mirror of https://github.com/lianthony/NT4.0
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
555 lines
16 KiB
555 lines
16 KiB
/****************************************************************************
|
|
*
|
|
* 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 *************************************************/
|