Optional and Required GPIO Callback Functions
A general-purpose I/O (GPIO) controller driver calls the GPIO_CLX_RegisterClient method to register as a client of the GPIO framework extension (GpioClx). During this call, the driver passes a registration packet to GpioClx that specifies a list of event callback functions that are implemented by the driver. GpioClx calls these callback functions to configure the GPIO controller hardware, perform I/O operations, and manage interrupts. GpioClx requires a GPIO controller driver to implement certain callback functions, but support for other callback functions is optional.
The registration packet is a GPIO_CLIENT_REGISTRATION_PACKET structure. If the GPIO controller driver implements a particular callback function, it writes the function pointer to that callback function into the corresponding member of this structure. Or, to indicate that a particular callback function is not supported, the driver writes NULL to the corresponding member.
The following callback functions must be included in the registration packet:
CLIENT_PrepareController CLIENT_QueryControllerBasicInformation CLIENT_StartController CLIENT_StopController CLIENT_ReleaseController If any callback function in the preceding list is missing (that is, if the corresponding function pointer in the registration packet is NULL), the GPIO_CLX_RegisterClient method fails.
A GPIO controller driver is not required to support reading from or writing to GPIO I/O pins, which are pins that are configured as data inputs or data outputs. (A GPIO controller with no I/O pins could still relay interrupt requests from peripheral devices.) However, if the registration packet includes either of the following I/O-related callback functions, the packet must include both of the following callback functions:
CLIENT_ConnectIoPins CLIENT_DisconnectIoPins In addition, if the registration packet includes the two callback functions in the preceding list, the driver must additionally support reading from GPIO I/O pins, writing to GPIO I/O pins, or both. Specifically, the registration packet must include at least one callback function in the following list:
CLIENT_ReadGpioPins or CLIENT_ReadGpioPinsUsingMask CLIENT_WriteGpioPins or CLIENT_WriteGpioPinsUsingMask A driver that supports reads must implement one of the two CLIENT_ReadGpioPinsXxx callback functions in the preceding list. A driver that supports writes must implement one of the two CLIENT_WriteGpioPinsXxx callback functions in the preceding list.
A driver that implements CLIENT_ReadGpioPinsUsingMask, CLIENT_WriteGpioPinsUsingMask, or both, must set the FormatIoRequestsAsMasks flag bit in the device information that is supplied by the CLIENT_QueryControllerBasicInformation callback function. A driver that implements CLIENT_ReadGpioPins, CLIENT_WriteGpioPins, or both, must not set this flag bit. For more information, see the description of the Flags member in CLIENT_CONTROLLER_BASIC_INFORMATION.
A GPIO controller driver is not required to support GPIO interrupts. However, if the registration packet includes any of the following interrupt-related callback functions, the packet must include all of the following callback functions:
CLIENT_EnableInterrupt CLIENT_DisableInterrupt CLIENT_MaskInterrupts CLIENT_QueryActiveInterrupts CLIENT_UnmaskInterrupt A driver that supports the masking of interrupts must implement the CLIENT_MaskInterrupts callback function. A driver that supports the querying of active interrupts must implement the CLIENT_QueryActiveInterrupts callback function.
The CLIENT_ClearActiveInterrupts callback function is a special case. If the GPIO controller hardware automatically clears active interrupts when they are read, the CLIENT_ClearActiveInterrupts function is not needed and the corresponding function pointer in the registration packet should be set to NULL. However, if active interrupts are not automatically cleared when they are read, and if the interrupt-related callback functions in the preceding list are supplied in the registration packet, the CLIENT_ClearActiveInterrupts function must be included in the packet. To indicate that the hardware automatically clears the active interrupts when they are read, the driver sets the ActiveInterruptsAutoClearOnRead flag bit in the device information that is supplied by the CLIENT_QueryControllerBasicInformation callback function. For more information, see the description of the Flags member in CLIENT_CONTROLLER_BASIC_INFORMATION.
If the GPIO controller driver supports GPIO interrupts, the registration packet can, as an option, include the following callback function:
CLIENT_QueryEnabledInterrupts GpioClx supports the CLIENT_QueryEnabledInterrupts function starting with Windows 8.1.
A driver that supports component-level power management must implement both of the following callback functions:
CLIENT_RestoreBankHardwareContext CLIENT_SaveBankHardwareContext To indicate that the hardware supports component-level power management, the driver sets the BankIdlePowerMgmtSupported flag bit in the device information that is supplied by the CLIENT_QueryControllerBasicInformation callback function. For more information, see the description of the Flags member in CLIENT_CONTROLLER_BASIC_INFORMATION.
The CLIENT_PreProcessControllerInterrupt, CLIENT_ReconfigureInterrupt, and CLIENT_ControllerSpecificFunction callback functions are optional and are supported by GpioClx to address hardware-specific issues in some GPIO controller implementations. Only GPIO controller drivers with special requirements implement these functions.