handling IRPs 13: I/O Control Codes (IOCTLs)

I/O Control Codes (IOCTLs)

The I/O Manager sends an I/O control code (IOCTL) as part of the IRP for requests other than read or write requests. An IOCTL is a 32-bit control code that identifies an I/O or device operation. Requests that specify IOCTLs can have both input and output buffers.

The operating system supports two types of IOCTLs, which are sent in two different IRPs:

·         IRP_MJ_DEVICE_CONTROL requests can be sent from user mode or kernel mode. These requests are sometimes called public IOCTLs.

·         IRP_MJ_INTERNAL_DEVICE_CONTROL requests can be sent by kernel-mode components only. These requests are typically used for driver-to-driver communication and are sometimes called private IOCTLs.

 

For an IOCTL, the transfer mechanism is specified in theMethodfield of the control code. IOCTLs support the following transfer mechanisms:

·         METHOD_BUFFERED

·         METHOD_OUT_DIRECT

·         METHOD_IN_DIRECT

·         METHOD_NEITHER

 

METHOD_BUFFERED IOCTLs

In a METHOD_BUFFERED IOCTL, like a buffered read or write request, data transfer is performed through a copy of the user’s buffer passed in theIrp‑>AssociatedIrp.SystemBuffer field. The lengths of the input and output buffers are passed in the driver’s IO_STACK_LOCATION structure in theParameters.DeviceIoControl.InputBufferLength field and theParameters.DeviceIoControl.OutputBufferLength field. These values represent the maximum number of bytes the driver should read or write in response to the buffered IOCTL.

METHOD_BUFFERED IOCTLs are the most secure IOCTLs because the buffer pointer is guaranteed to be valid and aligned on a natural processor boundary, and the data in the buffer cannot change.

The I/O Manager does not zero-initialize the output buffer before issuing the request. The driver is responsible for writing either valid data or zeroes in the output buffer up to the return byte count it specifies in the Irp->IoStatus.Information field. Failing to write valid data or zeroes could result in returning private kernel data to the user-mode application. Because this data could belong to another user, this error is considered a breach of system security.

METHOD_OUT_DIRECT IOCTLs

An IOCTL that specifies METHOD_OUT_DIRECT or METHOD_DIRECT_FROM_HARDWARE represents a read operation from the hardware. METHOD_OUT_DIRECT and METHOD_DIRECT_FROM_HARDWARE can be used interchangeably.

In METHOD_OUT_DIRECT requests, theIrp‑>AssociatedIrp.SystemBuffer field contains a kernel-mode copy of the requestor’s input buffer. TheIrp‑>MdlAddress field contains an MDL that describes the requestor’s output buffer. The I/O Manager readies this buffer for the driver to write. As in read and write operations, the driver must call theMmGetSystemAddressForMdlSafe macro to get a kernel-mode pointer to the buffer described by the MDL.

The requestor’s input buffer typically contains a pointer to a command that the driver should interpret or send to the device. The requestor’s output buffer typically is the location to which the driver should transfer the result of the operation.

METHOD_IN_DIRECT IOCTLs

An IOCTL that specifies METHOD_IN_DIRECT or METHOD_DIRECT_TO_HARDWARE requests a write operation to the hardware. METHOD_DIRECT_TO_HARDWARE and METHOD_IN_DIRECT can be used interchangeably.

In METHOD_IN_DIRECT requests, theIrp->AssociatedIrp.SystemBuffer field contains a kernel-mode copy of the requestor’s input buffer. TheIrp->MdlAddress field contains an MDL that describes the requestor’s output buffer. The I/O Manager readies this buffer for the driver to read. As in read and write operations, the driver must call theMmGetSystemAddressForMdlSafe macro to get a kernel-mode pointer to the buffer described by the MDL.

The input and output buffers are typically used in similar ways for METHOD_OUT_DIRECT and METHOD_IN_DIRECT IOCTLs. The requestor’s input buffer contains a command for the driver or device. However, the requestor’s output buffer contains the data for the driver to transfer to the device. In effect, it is a second input buffer.

METHOD_NEITHER IOCTLs

A driver can define IOCTLs that use neither direct nor buffered I/O. METHOD_NEITHER IOCTLs have separate user-mode pointers for input and output buffers:

·         IrpSp->Parameters.DeviceIoControl.Type3InputBuffer points to the input buffer.

·         Irp->UserBuffer points to the output buffer.

 

The input and output buffer addresses are user-mode pointers. Therefore, drivers must validate these pointers before using them, by calling theProbeForRead andProbeForWrite routines within atry/except block. In addition, the driver must copy all parameters to kernel-mode memory (either in the pool or on the stack) before validating them.

Note: For detailed information on probing and on problems commonly seen in driver I/O paths, see the white paper “Common Driver Reliability Issues.”