INFO: Meanings of Address Fields in an IRP Structure

Article translations Article translations
Article ID: 115758 - View products that this article applies to.
This article was previously published under Q115758
This article has been archived. It is offered "as is" and will no longer be updated.
Expand all | Collapse all

On This Page

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, refer to the DDK section 'Defining I/O Control Codes'.

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 inthe 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. Drivers, however, should not change the value of these fields.

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.

Properties

Article ID: 115758 - Last Review: February 28, 2014 - Revision: 3.2
APPLIES TO
  • Microsoft Windows NT 4.0 Driver Development Kit, when used with:
    • Microsoft Windows NT Advanced Server 3.1
    • Microsoft Windows NT 4.0
    • Microsoft Windows NT 3.51 Service Pack 5
    • Microsoft Windows NT 4.0
  • Microsoft Win32 Device Driver Kit for Windows 2000, when used with:
    • Microsoft Windows 2000 Standard Edition
  • Microsoft Windows XP Driver Development Kit
Keywords: 
kbnosurvey kbarchive kbinfo KB115758

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com