windows-nt-4.0/private/ntos/ndis/madge/driver/drv_err.c

/****************************************************************************
*
* DRV_ERR.C : Part of the FASTMAC TOOL-KIT (FTK)
*
* THE ERROR EXPLANATION MODULE
*
* Copyright (c) Madge Networks Ltd. 1991-1993
*
* COMPANY CONFIDENTIAL
*
*****************************************************************************
*
* The driver module provides a  simple  interface  to  allow  the  use  of
* Fastmac  in as general a setting as possible. It handles the downloading
* of the Fastmac code and the initialization  of  the  adapter  card.   It
* provides  simple  transmit  and  receive  routines.   It  is desgined to
* quickly allow the implementation of  Fastmac  applications.  It  is  not
* designed as the fastest or most memory efficient solution.
*
* The DRV_ERR.C module contains the routine to explain the cause of errors
* when other driver routines fail.
* 
****************************************************************************/

/*---------------------------------------------------------------------------
|
| DEFINITIONS
|
---------------------------------------------------------------------------*/

#include "ftk_defs.h"

/*---------------------------------------------------------------------------
|
| MODULE ENTRY POINTS
|
---------------------------------------------------------------------------*/

#include "ftk_intr.h"   /* routines internal to FTK */
#include "ftk_extr.h"   /* routines provided or used by external FTK user */

/*---------------------------------------------------------------------------
|
| LOCAL VARIABLES
|
---------------------------------------------------------------------------*/

#include "ftk_tab.h"

/****************************************************************************
*                                                                          
*                      driver_explain_error                                
*                      ====================                                
*                                                                          
* PARAMETERS :                                                             
* ============                                                             
*                                                                          
* ADAPTER_HANDLE  adapter_handle                                            
*                                                                          
* This handle identifies the adapter for which the error has occured.      
*                                                                          
* BYTE            * returned_error_type                                               
*                                                                          
* The byte pointed to is filled in with a value representing the  type  of 
* error that has occured. If no error has actually occured it is filled in 
* woth the value zero (0).                                                 
*                                                                          
* BYTE            * returned_error_value                                              
*                                                                          
* The  byte  pointed  to  is  filled  in  with  a  value  representing the 
* particular error of a given type that  has  occured.  If  no  error  has 
* actually occured it is filled in with the value zero (0).                
*                                                                          
* char          * * returned_error_message                                          
*                                                                          
* This  pointer,  on  exit,  points  to  a  string  containing  a  message 
* describing the error that has occured. If no error has actually  occured 
* then  it  points  to a null message.                                     
*                                                                          
* BODY :                                                                   
* ======                                                                   
*                                                                          
* The  driver_explain_error  routine  returns  details  of the most recent 
* error to occur using a given adapter.                                    
*                                                                          
* RETURNS :                                                                
* =========                                                                
*                                                                          
* The  routine  returns  a  boolean  value indicating whether the error is 
* fatal or not. If the error is fatal (returns FALSE) then the adapter can 
* not be used subsequently except via  a  call  to  driver_remove_adapter. 
* However,  the  adapter  can,  after  a call to driver_remove_adapter, be 
* initialized again etc.                                                   
*                                                                          
****************************************************************************/

#ifdef FTK_RES_FUNCTION
#pragma FTK_RES_FUNCTION(driver_explain_error)
#endif

export WBOOLEAN  
driver_explain_error(
    ADAPTER_HANDLE adapter_handle,
    BYTE *         returned_error_type,
    BYTE *         returned_error_value,
    char * *       returned_error_message
    )
{

    ERROR_MESSAGE_RECORD * err_msg_record;
    char                 * err_msg_header;
    ADAPTER              * adapter;
    ERROR_RECORD         * adapter_error_record;


    if (adapter_handle >= MAX_NUMBER_OF_ADAPTERS)
    {
        /*
         * Adapter handle is invalid if greater than max number of adapters.
         */

        *returned_error_type  = ERROR_TYPE_DRIVER;
        *returned_error_value = DRIVER_E_01_INVALID_HANDLE;

        /*
         * Set up returned error msg to point to special string.
         * No adapter structure so can not use error message adapter field.
         */

#ifdef FTK_NO_ERROR_MESSAGES
        *returned_error_message = "";
#else
        *returned_error_message = drv_err_msg_1;
#endif
        /*
         * This is a fatal error.
         */

        return FALSE;
    }

    if (adapter_record[adapter_handle] == NULL)
    {
        /*
         * Adapter handle is invalid when no adapter structure for handle.
         * Caused by either the adapter handle being invalid or
         * the call to sys_alloc_adapter_structure having failed.
         * Fill in returned error type and value.
         */

        *returned_error_type  = ERROR_TYPE_DRIVER;
        *returned_error_value = DRIVER_E_02_NO_ADAP_STRUCT;

        /*
         * Set up returned error msg to point to special string.
         * No adapter structure so can not use error message adapter field.
         */

#ifdef FTK_NO_ERROR_MESSAGES
        *returned_error_message = "";
#else
        *returned_error_message = drv_err_msg_2;
#endif
        /*
         * This is a fatal error.
         */

        return FALSE;
    }

    /*
     * Now know adapter handle is valid. Get pointer to adapter structure.
     */

    adapter = adapter_record[adapter_handle];

    /*
     * Get pointer to error record for adapter.
     */

    adapter_error_record = &adapter->error_record;

    /*
     * Check for special case when no error has actually occured.
     */

    if (adapter_error_record->type == ERROR_TYPE_NONE)
    {
        /*
         * Fill in returned error type and value as zero.
         */

        *returned_error_type  = 0;
        *returned_error_value = 0;

        /*
         * Set the returned error message string to be null.
         * If no error then adapter error message field must be null.
         */

#ifdef FTK_NO_ERROR_MESSAGES
        *returned_error_message = "";
#else
        *returned_error_message = adapter->error_message.string;
#endif

        /*
         * This is a non-fatal 'error'.
         */

        return TRUE;
    }

    /*
     * Now know have genuine error recorded by FTK. Fill in 
     * returned error type and value.
     */

    *returned_error_type  = adapter_error_record->type;
    *returned_error_value = adapter_error_record->value;

#ifdef FTK_NO_ERROR_MESSAGES
    *returned_error_message = "";
#else

    /*
     * All error messages are got from error message tables.
     * First get error message header. Note it is known that 
     * *returned_error_type is valid here.
     */

    err_msg_header = error_msg_headers_table[(*returned_error_type) - 1];

    /*
     * Copy error message header to error message in adapter structure.
     */

    util_string_copy(adapter->error_message.string, err_msg_header);

    /*
     * Get pointer to correct error message table for rest of message.
     */

    err_msg_record = list_of_error_msg_tables[(*returned_error_type) - 1];

    /*
     * Search for required error message within table. Table ends with 
     * special marked entry. So if error message not found will use 
     * "Unknown error" message.
     */

    while (err_msg_record->value != ERR_MSG_UNKNOWN_END_MARKER)
    {
        if (err_msg_record->value == *returned_error_value)
        {
            break;
        }
        err_msg_record++;
    }

    /*
     * Concatenate error message onto end of error header in
     * error message field of adapter structure.
     */

    util_string_concatenate(
        adapter->error_message.string,
        err_msg_record->err_msg_string
        );

    /*
     * Set up return pointer to error message.
     */

    *returned_error_message = adapter->error_message.string;

#endif 

    /*
     * Return FALSE for fatal errors.
     */

    if (macro_fatal_error(*returned_error_type))
    {
        return FALSE;
    }

    /*
     * Return TRUE for non-fatal errors.
     */

    return TRUE;
}


/****************************************************************************
*
*                      driver_check_version
*                      ====================
*
* PARAMETERS : 
* ============
* 
* UINT * returned_version_number
*
* The  returned  version  number is zero (0) if the version numbers of all
* the FTK modules do not match correctly.  If they do, then  the  returned
* version  number  is  the  real version number mutiplied by 100 (eg. 1.01
* becomes 101).
*
*
* BODY :
* ======
*
* The driver_check_version routine checks the version  number  consistency
* of  the  FTK  by  looking  at  all the different code modules and header
* files.
* 
* RETURNS :
* =========
*
* The  routine  returns  TRUE  if  the  version  numbers  are  consistent.
* Otherwise, it returns FALSE.
*
****************************************************************************/

/*
 * Marker at end of version number array.
 */

#define VERSION_NUMBERS_END_MARK        0xFFFF

/*
 * Version number array containing version numbers of ALL header files.
 */

local UINT version_number[] = 
{
    FTK_VERSION_NUMBER_FTK_ADAP_H,
    FTK_VERSION_NUMBER_FTK_AT_H,
    FTK_VERSION_NUMBER_FTK_CARD_H,
    FTK_VERSION_NUMBER_FTK_DOWN_H,
    FTK_VERSION_NUMBER_FTK_EISA_H,
    FTK_VERSION_NUMBER_FTK_PCI_H,
    FTK_VERSION_NUMBER_FTK_PCMC_H,
    FTK_VERSION_NUMBER_FTK_PNP_H,
    FTK_VERSION_NUMBER_FTK_ERR_H,
    FTK_VERSION_NUMBER_FTK_FM_H,
    FTK_VERSION_NUMBER_FTK_INIT_H,
    FTK_VERSION_NUMBER_FTK_MACR_H,
    FTK_VERSION_NUMBER_FTK_MC_H,
    FTK_VERSION_NUMBER_FTK_SRB_H,
    FTK_VERSION_NUMBER_FTK_TAB_H,
    FTK_VERSION_NUMBER_FTK_USER_H,
    FTK_VERSION_NUMBER_DRV_ERR_H,
    FTK_VERSION_NUMBER_DRV_INIT_H,
    FTK_VERSION_NUMBER_DRV_IRQ_H,
    FTK_VERSION_NUMBER_DRV_MISC_H,
    FTK_VERSION_NUMBER_DRV_SRB_H,
    FTK_VERSION_NUMBER_DRV_RXTX_H,
    FTK_VERSION_NUMBER_HWI_GEN_H,
    FTK_VERSION_NUMBER_HWI_AT_H,
    FTK_VERSION_NUMBER_HWI_EISA_H,
    FTK_VERSION_NUMBER_HWI_MC_H,
    FTK_VERSION_NUMBER_HWI_PCI_H,
    FTK_VERSION_NUMBER_HWI_PCMC_H,
    FTK_VERSION_NUMBER_HWI_PNP_H,
    FTK_VERSION_NUMBER_SYS_ALLO_H,
    FTK_VERSION_NUMBER_SYS_BUFF_H,
    FTK_VERSION_NUMBER_SYS_DMA_H,
    FTK_VERSION_NUMBER_SYS_IRQ_H,
    FTK_VERSION_NUMBER_SYS_MEM_H,
    FTK_VERSION_NUMBER_SYS_TIME_H,
    FTK_VERSION_NUMBER_SYS_PCI_H,
    FTK_VERSION_NUMBER_SYS_CS_H,
    FTK_VERSION_NUMBER_USER_H,
    FTK_VERSION_NUMBER_UTIL_H,
    VERSION_NUMBERS_END_MARK};


#ifdef FTK_RES_FUNCTION
#pragma FTK_RES_FUNCTION(driver_check_version)
#endif

export WBOOLEAN  
driver_check_version(
    UINT * returned_version_number
    )
{
    UINT i;

    /*
     * Check for consistent version number.
     */

    i = 0;

    while (version_number[i+1] != VERSION_NUMBERS_END_MARK)
    {
        if (version_number[i] != version_number[i + 1])
        {
            /*
             * Inconsistent version numbers so return failure.
             */

            *returned_version_number = 0;
            return FALSE;
            }

        i++;
    }

    /*
     * Version numbers are consistent so return version number and success.
     */

    *returned_version_number = version_number[0];

    return TRUE;
}


/****************************************************************************
*
*                      driver_check_adapter
*                      ====================
*
* The driver_check_adapter routine is called at  the  beginning  of  every
* driver routine, except driver_remove_adapter and driver_prepare_adapter,
* in  order  to  check  the validity of the adapter handle. It also checks
* that the adapter is in the correct operative state,  and  that  the  SRB
* associated  with  the adapter is in the correct state (if any particular
* state is required).
*  
****************************************************************************/

#ifdef FTK_RES_FUNCTION
#pragma FTK_RES_FUNCTION(driver_check_adapter)
#endif

export WBOOLEAN  
driver_check_adapter(
    ADAPTER_HANDLE adapter_handle,
    UINT           required_adapter_status,
    UINT           required_srb_status
    )
{
    ADAPTER * adapter;

    /*
     * Adapter handle is invalid if greater than max number of adapter.
     * Can not set up error record but see driver_explain_error.
     */

    if (adapter_handle >= MAX_NUMBER_OF_ADAPTERS)
    {
        return FALSE;
    }

    /*
     * Adapter handle is invalid when no adapter structure for handle.
     * Can not set up error record but see driver_explain_error.
     */

    if (adapter_record[adapter_handle] == NULL)
    {
        return FALSE;
    }

    /*
     * Get pointer to adapter structure.
     */

    adapter = adapter_record[adapter_handle];

    /*
     * If fatal error already exists for adapter then fail. Do not not 
     * change error code in this case. Fatal errors are - driver, hwi, 
     * init, bring-up, adapter, auto_open.
     */

    if (macro_fatal_error(adapter->error_record.type))
    {
        return FALSE;
    }

    /*
     * Check if status of adapter is that required.
     */

    if (adapter->adapter_status != required_adapter_status)
    {
        if (required_adapter_status == ADAPTER_PREPARED_FOR_START)
        {
            /*
             * Required adapter status is ADAPTER_PREPARED_FOR_START.
             * Fill in error record and fail.
             */

            adapter->error_record.type  = ERROR_TYPE_DRIVER;
            adapter->error_record.value = DRIVER_E_07_NOT_PREPARED;

            return FALSE;
        }
        else
        {
            /*
             * Required adapter status is ADAPTER_RUNNING.
             * Fill in error record and fail.
             */

            adapter->error_record.type  = ERROR_TYPE_DRIVER;
            adapter->error_record.value = DRIVER_E_08_NOT_RUNNING;

            return FALSE;
        }
    }

    /*
     * Check if status of SRB is that required. Only do if particular 
     * state is needed.
     */

    if ((required_srb_status != SRB_ANY_STATE) &&
        (adapter->srb_status != required_srb_status))
    {
        if (required_srb_status == SRB_FREE)
        {
            /*
             * Required srb status is SRB_FREE fill in error record 
             * and fail.
             */

            adapter->error_record.type  = ERROR_TYPE_DRIVER;
            adapter->error_record.value = DRIVER_E_09_SRB_NOT_FREE;

            return FALSE;
        }
        else
        {
            /*
             * Never require srb status to be SRB_NOT_FREE.
             */
        }
    }

    /*
     * Adapter handle and status are okay so complete successfully.
     */

    return TRUE;
}


/******** End of DRV_ERR.C *************************************************/