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:

CLIENT_ReadGpioPins

CLIENT_ReadGpioPinsUsingMask

CLIENT_WriteGpioPins

CLIENT_WriteGpioPinsUsingMask

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

CLIENT_DeleteIoContext

CLIENT_ReadGpioPins

CLIENT_ReadGpioPinsUsingMask

CLIENT_WriteGpioPins

CLIENT_WriteGpioPinsUsingMask

GPIO_CLX_RegisterClient

GPIO_CONNECT_MODE_XXX

GPIO_CLIENT_REGISTRATION_PACKET

 

 

Build date: 9/7/2011