CLIENT_CreateIoContext function
[This documentation is preliminary and is subject to change.]
OBSOLETE! The CLIENT_CreateIoContext event callback function creates an I/O context for a set of general-purpose I/O (GPIO) pins in the specified bank that are configured as data inputs or outputs.
Note This callback function is obsolete and is not used by the current version of the GPIO framework extension (GpioClx).
Syntax
GPIO_CLIENT_CREATE_IO_CONTEXT CLIENT_CreateIoContext;
NTSTATUS CLIENT_CreateIoContext(
_In_ PVOID Context,
_In_ BANK_ID BankId,
_In_ PPIN_NUMBER PinNumberTable,
_In_ ULONG PinCount,
_In_ ULONG ConnectMode,
_Out_ PVOID *ClientIoContext
)
{ ... }
Parameters
Context [in]
A pointer to the GPIO controller driver's device context.BankId [in]
A bank of GPIO pins. If M is the number of banks in the GPIO controller, BankId is an integer in the range 0 to M–1. The GPIO framework extension previously obtained the number of banks in the controller from the CLIENT_QueryControllerInformation event callback function. For more information, see Remarks in CLIENT_CONTROLLER_INFORMATION.PinNumberTable [in]
A pointer to an array of bank-relative PIN_NUMBER values. Each array element specifies the number of a GPIO pin that is associated with this I/O context. If N is the number of GPIO pins in this bank, the pins are numbered 0 to N–1. The number of elements in this array is specified by the PinCount parameter.PinCount [in]
The number of elements in the PinNumberTable array.ConnectMode [in]
Whether the GPIO pins that are associated with this I/O context are configured as inputs or as outputs. The value of this parameter is either GPIO_CONNECT_MODE_INPUT or GPIO_CONNECT_MODE_OUTPUT. For more information, see GPIO_CONNECT_MODE_XXX.ClientIoContext [out]
A pointer to a PVOID variable into which this function writes the address of the newly created I/O context. If the GPIO controller driver does not require an I/O context for the GPIO pins in the PinNumberTable array, the function writes NULL to this variable.
Return value
The CLIENT_CreateIoContext function returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error code.
Remarks
This callback function is implemented by the GPIO controller driver. The GPIO framework extension (GpioClx) calls this function.
As an option, a GPIO controller driver can allocate an I/O context to contain configuration and state information about a set of GPIO pins that are configured as data inputs or outputs. All of the pins in this set belong to the specified bank. A driver that does not use I/O contexts does not need to implement a CLIENT_CreateIoContext callback function. For more information, see Optional and Required GPIO Callback Functions.
When the driver for a peripheral device opens an I/O connection to a set of GPIO pins, GpioClx calls the CLIENT_CreateIoContext function to create an I/O context for the pins in the connection. When the connection is closed, GpioClx calls the CLIENT_DeleteIoContext callback function to delete the I/O context.
If peripheral device drivers open several I/O connections, the GPIO controller driver can allocate a separate I/O context for each connection.
GpioCls passes an I/O context pointer as an input parameter to the following event callback functions:
To register your driver's CLIENT_CreateIoContext callback function, call the GPIO_CLX_RegisterClient method. This method accepts, as an input parameter, a pointer to a GPIO_CLIENT_REGISTRATION_PACKET structure that contains a CLIENT_CreateIoContext function pointer.
Examples
The function type for this callback is declared in Gpioclx.h, as follows.
typedef NTSTATUS
GPIO_CLIENT_STOP_CONTROLLER(
_In_ PVOID Context,
_In_ PPIN_NUMBER PinNumberTable,
_In_ ULONG PinCount,
_In_ ULONG ConnectMode,
_Out_ PVOID *ClientIoContext
);
To define a CLIENT_CreateIoContext callback function that is named MyEvtGpioCreateIoContext, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as follows.
GPIO_CLIENT_STOP_CONTROLLER MyEvtGpioCreateIoContext;
Then, implement your callback function as follows.
NTSTATUS
MyEvtGpioCreateIoContext(
_In_ PVOID Context,
_In_ PPIN_NUMBER PinNumberTable,
_In_ ULONG PinCount,
_In_ ULONG ConnectMode,
_Out_ PVOID *ClientIoContext
)
{ ... }
For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for WDM Drivers.
Requirements
Version |
Available starting with Windows Developer Preview. |
Header |
Gpioclx.h |
IRQL |
Called at PASSIVE_LEVEL. |
See also
GPIO_CLIENT_REGISTRATION_PACKET
Build date: 9/7/2011