16.6.5 Defining New IO_ERR_XXX

NT driver writers can create driver-specific private IO_ERR_XXX codes of type NTSTATUS within the driver's xxxlog.mc resource file.

The NTSTATUS Facility field, shown in Figure 16.5, for such an error must be set to FACILITY_IO_ERROR_CODE. The driver writer must supply a Sev value and a unique Code value for each new IO_ERR_XXX. Such a driver also must set the C bit in its new IO_ERR_XXX.

The Sev field shown in Figure 16.5 indicates the severity code, which must be one of the following system-defined values:

STATUS_SEVERITY_SUCCESS

Indicates STATUS_SUCCESS was set for FinalStatus, and a value such as IO_ERR_RETRY_SUCCEEDED for an ErrorCode value in error log packets.

While STATUS_PENDING also belongs to the STATUS_SEVERITY_SUCCESS category, NT drivers would not log an error on a pending IRP.

STATUS_SEVERITY_INFORMATIONAL

Indicates an informational NTSTATUS value, such as STATUS_SERIAL_MORE_WRITES.

STATUS_SEVERITY_WARNING

Indicates a warning NTSTATUS value, such as STATUS_DEVICE_PAPER_EMPTY.

STATUS_SEVERITY_ERROR

Indicates an error NTSTATUS value, such as STATUS_INSUFFICIENT_RESOURCES for a FinalStatus value or IO_ERR_CONFIGURATION_ERROR for an ErrorCode value in error log packets.

Most public IO_ERR_XXX constants belong to the STATUS_SEVERITY_ERROR category.

If the designer of an NT driver decides to make a set of driver-defined errors visible to system administrators or end users through the Win32 event viewer, such a driver must set itself up as an error-logging component in the registry, as described in Section 16.8.4.