IOCTL_GPIO_WRITE_PINS IOCTL (gpio.h)

Article
05/18/2021

The IOCTL_GPIO_WRITE_PINS I/O control code enables a client of the general-purpose I/O (GPIO) controller to write to a set of GPIO pins that are configured as outputs. Typically, the clients of a GPIO controller are drivers for peripheral devices that connect to GPIO pins.

Major code

IRP_MJ_DEVICE_CONTROL

Input buffer

The input buffer.

Input buffer length

The input buffer should be large enough to contain data for all of the GPIO pins that are part of the target connection to which the client sends the request. For example, if the GPIO controller hardware implements 64 GPIO pins, and the client opens a connection to three of these GPIO pins, a one-byte buffer is sufficiently large to contain the three 1-bit values to write to the three pins in the connection.

Output buffer

The output buffer contains the same data as the input buffer (because the TransferType for this IOCTL is METHOD_BUFFERED).

Output buffer length

Same as the input buffer.

Status block

If the operation is successful, the controller driver sets the Status member to STATUS_SUCCESS, and sets the Information member to the total number of bytes transferred during the requested operation. If the operation transfers N bits, the number of bytes transferred is (N + 7) / 8. (That is, 7 is added to N to round up to the next byte boundary before the integer division by 8.)

If this request fails, the Status member is set to an error code and no data is read from the GPIO pins. The requested operation might fail for various reasons, which can include invalid client input, low resources, and device malfunction.

If the input buffer is not large enough to contain one bit of data for each GPIO pin in the target connection, the Status member is set to STATUS_BUFFER_TOO_SMALL. If the GPIO pins in the target connection are configured as inputs, the Status member is set to STATUS_GPIO_OPERATION_DENIED.

Remarks

This request writes to all of the GPIO pins that are part of the target connection to which the client sends the request. For example, if the connection has three pins, bits 0, 1, and 2 from the input buffer are written to these three pins. The three pins in this example connection might map to GPIO pins 7, 8, and 23 in the GPIO controller hardware. If so, bit 0 (the least significant bit) in the buffer is written to GPIO pin 7, bit 1 in the buffer is written to GPIO pin 8, and bit 2 in the buffer is written to GPIO pin 23.

When the client opens a connection to a target GPIO device, all of the GPIO pins in this connection are configured either as inputs or as outputs. An IOCTL_GPIO_WRITE_PINS request can succeed only if the target pins are outputs.

The client sends this I/O control request to the file object for the target device. The file object is a FILE_OBJECT structure that represents a logical connection to the target. Kernel-mode driver framework (KMDF) drivers call the WdfIoTargetCreate method to open this connection. User-mode driver framework (UMDF) drivers call the IWDFRemoteTarget::OpenFileByName method to open the connection.

For code examples that show how to use the IOCTL_GPIO_WRITE_PINS request to write to a set of GPIO I/O pins, see the following topics:

Connecting a KMDF Driver to GPIO I/O Pins

Requirements

Requirement	Value
Minimum supported client	Supported starting with Windows 8.
Header	gpio.h