INFO: Meanings of Address Fields in an IRP Structure

This article was previously published under Q115758
This article has been archived. It is offered "as is" and will no longer be updated.
SUMMARY
An input/output (I/O) method tells the I/O manager how to process a userbuffer before the buffer is passed on to the driver. This article explainshow different I/O methods affect the various fields in the IRP structureand what those fields mean when a driver receives an IRP. For an overviewof 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 adevice object, you can specify in the Flags field of the device objectwhich I/O method you want it to use. One of the two values, DO_BUFFERED_IOor DO_DIRECT_IO, can be OR'ed into the flag field. Or you can choose notto specify either method in the flag field. In this case, we will say thedriver has chosen the "neither" method. The method selected in the Flagsfield affects I/O read or write requests dispatched to this device objectthrough the driver's Read or Write dispatch routines.

However, device I/O control (IOCTL) requests are not affected by the methodselected in the Flags field for the device object. The I/O method for anIOCTL request is determined by the method code in the IOCTL code. Themethod code contains the two least significant bits in the control code. AnIOCTL 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 drivermust 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 fieldsin an IRP differently. The fields affected are MdlAddress,AsssociatedIrp.SystemBuffer (or SystemBuffer) and UserBuffer. In thefollowing discussion, if a field is not mentioned, it means the I/O managerdoes 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: 02/28/2014 07:55:07 - Revision: 3.2

Microsoft Windows NT 4.0 Driver Development Kit, Microsoft Win32 Device Driver Kit for Windows 2000, Microsoft Windows XP Driver Development Kit

  • kbnosurvey kbarchive kbinfo KB115758
Feedback