IoAllocateErrorLogEntry

PVOID
    IoAllocateErrorLogEntry(
        IN PVOID  IoObject,
        IN UCHAR  EntrySize
        );

IoAllocateErrorLogEntry allocates an error log packet and returns a pointer to the packet so the caller can supply information about an I/O error.

Parameters

IoObject

Points to a device object representing the device on which an I/O error occurred, or to a driver object representing the driver that found an error.

EntrySize

Specifies the size in bytes of the packet to be allocated. This value cannot exceed ERROR_LOG_MAXIMUM_SIZE.

Return Value

IoAllocateErrorLogEntry returns a pointer to the allocated packet in which the driver sets up the error data, or NULL if a packet could not be allocated.

Comments

The driver must fill in the packet with information about the error and, then, call IoWriteErrorLogEntry to post the entry to the error log.

The value supplied for EntrySize depends on how much DumpData the driver includes in the error log packet, as well as any InsertionStrings it provides for the error. In general, the value of EntrySize is the following:

sizeof(IO_ERROR_LOG_PACKET) + (n * sizeof(ULONG))
        + sizeof(InsertionStrings)

Where n depends on how much DumpData the driver supplies with the error. If IoAllocateErrorLogPacket returns NULL, the driver should continue to run and assume that, if the same error occurs again, the driver can log the error at that point. The returned 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;

Caller-supplied data in the packet includes the following:

Member	Meaning
MajorFunctionCode	The IRP_MJ_XXX of the current IRP.
RetryCount	A count of how many times the caller has retried the operation and encountered the same error.
DumpDataSize	The number of bytes of caller-suplied DumpData, if any.
NumberOfStrings	The number of insertion strings supplied following the DumpData; the initial string, if any, is assumed to be the driver name or that of the target device object.
StringOffset	The offset, immediately following any DumpData, of the caller-supplied, zero-terminated Unicode insertion strings, if any.
EventCategory	A caller-determined value matching that in the caller’s message file for categories if the driver set itself up in the registry as an event-logging component; otherwise, zero.
ErrorCode	An IO_ERR_XXX value.
UniqueErrorValue	A driver-determined value that indicates where in the driver the error was encountered.
FinalStatus	The STATUS_XXX value to be set in the I/O status block of the IRP or a STATUS_XXX returned by a support routine.
SequenceNumber	A driver-assigned number for the current IRP, constant for the life of the request.
IoControlCode	An IOCTL_XXX if MajorFunctionCode is IRP_MJ_DEVICE_CONTROL, IRP_MJ_INTERNAL_DEVICE_CONTROL, or IRP_MJ_SCSI; otherwise, zero.
DeviceOffset	The offset on the device where the error occurred, or zero.
DumpData	Caller-supplied data, such as device register contents, if DumpDataSize is nonzero.

The I/O Manager uses the first insertion string for the device or driver name derived from the IoObject.

Callers of IoAllocateErrorLogEntry must be running at IRQL <= DISPATCH_LEVEL.

See Also

IoWriteErrorLogEntry