NdisWriteErrorLogEntry

NdisWriteErrorLogEntry

VOID
NdisWriteErrorLogEntry(
IN NDIS_HANDLE NdisAdapterHandle,
IN NDIS_ERROR_CODE ErrorCode,
IN ULONG NumberOfErrorValues,
IN ULONG ...
);

NdisWriteErrorLogEntry writes an entry to the system I/O error log file.

Parameters

NdisAdapterHandle

Specifies the handle representing the NIC that is the cause of the I/O error to be logged. This handle is an input parameter to MiniportInitialize.

ErrorCode

Specifies the NDIS_STATUS_XXX code describing the I/O error.

NumberOfErrorValues

Specifies the number of ULONG values to follow this parameter.

...

Specifies a variable-sized array of ULONGs associated with the error to be logged.

Comments

NdisWriteErrorLogEntry allocates an I/O error log record, fills in the record with the supplied information about the error, and then writes the record to the I/O error log file.

The system places a limit on the potential size of an error log record. The Windows NT limit is defined as ERROR_LOG_MAXIMUM_SIZE. The NumberOfErrorValues passed to NdisWriteErrorLogEntry therefore has a system-enforced limit, which is considerably less than the maximum possible value for a ULONG.

In practice, few callers of NdisWriteErrorLogEntry even approach the limit for NumberOfErrorValues because supplying many additional NDIS_STATUS_XXX values is not particularly helpful to the user or system administrator who later reads the error log, using the Win32 event viewer. Logging an I/O error at every possible opportunity is not particularly helpful to users either, so a miniport should log only critical I/O errors that can help a user or system administrator to debug a network failure for which the NIC is responsible on a particular machine or a configuration resource conflict discovered during driver initialization.

In general, a NIC driver calls NdisWriteErrorLogEntry during initialization from its MiniportInitialize function if it cannot initialize a NIC that it controls or cannot allocate the hardware resources it needs to carry out I/O operations on its NIC. A NIC driver also can call NdisWriteErrorLogEntry when a device-reset operation fails due to unrecoverable hardware error(s). Logging these kinds of I/O errors helps users or system administrators to identify a badly configured NIC or a NIC with failing hardware components.

Callers of NdisWriteErrorLogEntry run at IRQL <= DISPATCH_LEVEL.