DOC: IoInitializeIrp Function Documentation Is Incorrect

• Microsoft Win32 Device Driver Kit (DDK) for Windows NT, versions 3.1, 3.5, 3.51, 4.0
  on the following platforms: Alpha, x86

SUMMARY

The following statement in the comments section of the IoInitializeIrp function reference documentation is incorrect:

If a driver calls IoAllocateIrp, it also must call IoInitializeIrp with
the same StackSize value and the pointer returned by IoAllocateIrp.

MORE INFORMATION

On the contrary, a driver should never call IoInitializeIrp on an IRP allocated with IoAllocateIrp. Since the IRP is completely initialized by IoAllocateIrp, there is no need to call this function.

IoAllocateIrp tries to allocate storage for an IRP first from a look-aside list, and, if that fails, from NonPagedPool. If both these attempts fail and if the caller's previous mode is kernel-mode, it allocates storage from NonPagedPoolMustSucceed. It keeps track of this memory pool information in Irp->AllocationFlags field so that the system can return memory to the appropriate pool during IoFreeIrp call.

Since the IoInitializeIrp function zeros the entire IRP before initializing it, it results in the loss of this important allocation information set in Irp->AllocationFlags by IoAllocateIrp. This could lead to memory corruption and subsequent system crash if the system returns memory to an inappropriate pool when the IRP is freed.

You should use this function to initialize an IRP only if you allocate storage for the IRP with ExAllocatePool function from NonPagedPool.

Keywords          : kbdocerr kbDDK kbDecAlpha kbIFS kbKMode kbNTOS400 kbx86 
Version           : 
Platform          : 
Issue type        : 

Last Reviewed: March 6, 1999