5.1.1 Every DriverEntry Routine’s Responsibilites

Every DriverEntry routine is run in the context of a system thread at IRQL PASSIVE_LEVEL.

In general, a DriverEntry routine is responsible for exporting the driver’s other entry points, for initializing the NT objects the driver uses, and for setting up any other system resources that the driver uses. For more information about NT objects, see Chapter 3.

A DriverEntry routine can use the Windows NT® registry to get some of the information it needs to initialize the driver or its device(s). The DriverEntry routine must set information in the registry for other NT drivers and/or protected subsystems to use. For more information about using the registry, see Chapter 16.

    In particular, every DriverEntry routine must do the following:

Return from DriverEntry

As shown by its declaration, a DriverEntry routine returns an NTSTATUS-type value. The DriverEntry routine should postpone any call to IoRegisterDriverReinitialization until just before it returns STATUS_SUCCESS. It must not make this call unless it will return STATUS_SUCCESS.

If a DriverEntry routine returns something other than STATUS_SUCCESS to indicate that it can successfully process I/O requests for at least one named device object that it created, that driver does not remain loaded.

A DriverEntry routine that will fail initialization must free any NT objects, system resources, and registry resources it has already set up before it returns control. It should reset the driver’s Dispatch entry points in the driver object for IRP_MJ_FLUSH_BUFFERS and/or IRP_MJ_SHUTDOWN to NULL if the driver supports these requests. If it already called IoRegisterShutdownNotification, the DriverEntry routine must call IoUnregisterShutdownNotification before it fails initialization.

If a driver will fail initialization, the DriverEntry routine also should log an error or have IoReportResourceUsage log a hardware resource conflict error on a device driver’s behalf before DriverEntry returns control. For more information about logging I/O and resource-conflict errors, see Chapter 16.