INFO: Meanings of Address Fields in an IRP Structure

• Microsoft Win32 Device Development Kit (DDK) for the 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

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.

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