INFO: Meanings of Address Fields in an IRP Structure

ID: Q115758

The information in this article applies to:

Microsoft Win32 Device Driver Kit (DDK) for Windows NT, versions 3.1, 3.5, 3.51

SUMMARY

An input/output (I/O) method tells the I/O manager how to process a user buffer before the buffer is passed on to the driver. This article explains how different I/O methods affect the various fields in the IRP structure and what those fields mean when a driver receives an IRP. For an overview of I/O methods, see the "Windows NT DDK Kernel-mode Driver Design Guide," section 3.2.4

MORE INFORMATION

Available I/O Methods and How a Driver Selects Them

A driver can use one of the three different I/O methods: "buffered," "direct," or "neither." After you use a kernel-mode driver to create a device object, you can specify in the Flags field of the device object which I/O method you want it to use. One of the two values, DO_BUFFERED_IO or DO_DIRECT_IO, can be OR'ed into the flag field. Or you can choose not to specify either method in the flag field. In this case, we will say the driver has chosen the "neither" method. The method selected in the Flags field affects I/O read or write requests dispatched to this device object through the driver's Read or Write dispatch routines.

However, device I/O control (IOCTL) requests are not affected by the method selected in the Flags field for the device object. The I/O method for an IOCTL request is determined by the method code in the IOCTL code. The method code contains the two least significant bits in the control code. An IOCTL code is defined using the CTL_CODE macro. One of the following pre- defined values can be used for the method code:

METHOD_BUFFERED

METHOD_IN_DIRECT

METHOD_OUT_DIRECT

METHOD_NEITHER

If a driver must support an public IOCTL defined by Windows NT, the driver must observe the method code defined in that IOCTL code. For information regarding defining a private IOCTL code using the CTL_CODE macro, see??

How the I/O Methods Affect Various Buffer Pointers in an IRP

According to the I/O method selected, the I/O manager sets various fields in an IRP differently. The fields affected are MdlAddress, AsssociatedIrp.SystemBuffer (or SystemBuffer) and UserBuffer. In the following discussion, if a field is not mentioned, it means the I/O manager does not use it and it will be set to NULL.

The "Buffered" Method
NOTE: In the following discussion, "input" means data from the user-mode application program to the driver and "output" means the data from the driver to the application.

For a read request, the I/O manager allocates a system buffer with the size equal to that of the user-mode buffer. The SystemBuffer field in the IRP contains the system address. The UserBuffer field contains the original user buffer address. When the request is completed, the I/O manager copies the data that the driver has provided from the system buffer to the user buffer. For a write request, a system buffer is allocated and SystemBuffer is set to the address. The user buffer's content is copied to the system buffer. But UserBuffer is not set. For an IOCTL request, a system buffer is allocated that is big enough to contain either the input or the output buffer and SystemBuffer is set to the allocated buffer's address. Data from the input buffer is copied into the system buffer. The UserBuffer field is set to the user-mode output buffer address. A kernel-mode driver should use the system buffer only and should not touch the address stored in UserBuffer.

In the case of IOCTL, the driver should get input from the system buffer and write output to the system buffer. The I/O system copies the output data from the system buffer to the user buffer when the request is completed.
The "Direct" Method
For both read and write requests, the user-mode buffer is locked and a memory descriptor list (MDL) is built. The MDL address is stored in the MdlAddress field of the IRP. Neither SystemBuffer nor UserBuffer has any meaning.

For IOCTL requests, in both METHOD_IN_DIRECT and METHOD_OUT_DIRECT, if there is an input buffer, a system buffer is allocated (again, SystemBuffer has the address) and the input data is copied into it. If there is an output buffer, it is locked down, an MDL is built, and MdlAddress is set. The UserBuffer field has no meaning.
The "Neither" Method
For read and write requests, the UserBuffer field is set to point the original user buffer. Nothing else is done. SystemAddress and MdlAddress have no meaning. For IOCTL requests, the I/O manager sets UserBuffer to the original user output buffer, and in addition, it sets Parameters.DeviceIoControl.Type3InputBuffer in the current I/O stack location to the user-input buffer. With this I/O method, it is up to the driver to decide what to do with the buffer(s), either allocating a system buffer or building an MDL.

As a general rule, a driver should not use the UserBuffer field as an address to access user data, even when the user buffer is locked down. This is because the calling user's address space may not be visible in the system when the driver is called. (An exception to this rule is that a highest-level driver may need to use UserBuffer to copy data before it passes the IRP down to lower-layered drivers. For more information, see the Windows NT DDK Kernel-mode Driver Design Guide.) With the "direct" method or with the "neither" method, after a MDL is built, a driver may use the function MmGetSystemAddressForMdl to get a valid system address to access the user buffer.

Keywords :
Version : WINNT: 3.1,3.5,3.51;
Platform : winnt
Issue type : kbinfo