16.6.2 Filling in an Error Log Packet
The error log packet is defined as follows:
typedef struct _IO_ERROR_LOG_PACKET {
UCHAR MajorFunctionCode;
UCHAR RetryCount;
USHORT DumpDataSize;
USHORT NumberOfStrings;
USHORT StringOffset;
USHORT EventCategory;
NTSTATUS ErrorCode;
ULONG UniqueErrorValue;
NTSTATUS FinalStatus;
ULONG SequenceNumber;
ULONG IoControlCode;
LARGE_INTEGER DeviceOffset;
ULONG DumpData[1];
} IO_ERROR_LOG_PACKET, *PIO_ERROR_LOG_PACKET;
The driver should fill in an error log packet with the following data:
MajorFunctionCode
Indicates the IRP_MJ_XXX from the driver’s I/O stack location in the current IRP.
RetryCount
Indicates how many times the driver has retried the operation and encountered this error.
RetryCount is a zero-based value. That is, the driver should set it to zero when an error is first encountered for the current IRP.
DumpDataSize
Indicates the size in bytes required for any DumpData the driver will set in the packet.
The specified value should be an integral multiple of sizeof(ULONG).
NumberOfStrings
Indicates how many insertion strings the driver will supply with this packet. NT drivers set this value to zero for errors that need no insertion strings.
The NT error-logging thread can use these driver-supplied, zero-terminated Unicode strings to fill in messages written into the Win32 event log, where it can be examined using the Win32 event viewer. The I/O Manager assumes that the initial insertion string, if any, is either the name of the driver or of the device on which the error occurred.
Insertion strings provided by a driver should be language independent. Drivers that log errors and use insertion strings should use strings read from the registry or use names which are language independent or are the same in any language, for example, file names.
In most cases, NT device and intermediate drivers can simply log I/O errors without having to supply insertion strings for a higher-level event-logging component and/or without having to set up a driver-specific event-logging component. Of the system-supplied NT drivers, only network device drivers currently supply insertion strings in error log packets.
StringOffset
Indicates the offset, immediately following the DumpData, at which any driver-supplied insertion string data begins.
If a driver supplies this data, each string must be a zero-terminated Unicode string.
EventCategory
For drivers that install themselves in the registry as event-logging components, this is a driver-defined value that was specified in the driver’s message file for categories.
Most NT device and intermediate drivers set this value to zero. For more information about setting up an event-logging component, see Section 16.8.4.
ErrorCode
Indicates the type of error.
This is a system-defined or driver-defined constant, as described in Section 16.6.5.
UniqueErrorValue
Indicates where the error was detected in the driver.
FinalStatus
Indicates the value set in the I/O status block of the IRP when it was completed or the STATUS_XXX returned by a support routine the driver called.
SequenceNumber
Indicates a driver-assigned sequence number for the current IRP, which should be constant for the life of a given request.
IoControlCode
Indicates the I/O control code from the driver’s I/O stack location in the current IRP if the MajorFunctionCode is IRP_MJ_DEVICE_CONTROL or IRP_MJ_INTERNAL_DEVICE_CONTROL. Otherwise, this value should be zero.
For more information about I/O control codes and device I/O control requests, see the Kernel-Mode Driver Reference.
DeviceOffset
Indicates the offset into the device where the error occurred.
DumpData
Can be used to store driver-specific data, such as register values or whatever else the driver writer decides would be useful for identifying the cause of the error.
Any driver-supplied insertion strings must be supplied immediately following the dump data, starting at StringOffset.