CLIENT_QueryControllerInterruptBinding function
[This documentation is preliminary and is subject to change.]
OBSOLETE! The CLIENT_QueryControllerInterruptBinding event callback function retrieves the mapping of interrupt resources to banks.
Note This callback function is obsolete and is not used by the current version of the GPIO framework extension (GpioClx).
Syntax
GPIO_CLIENT_QUERY_CONTROLLER_INTERRUPT_BINDING CLIENT_QueryControllerInterruptBinding;
NTSTATUS CLIENT_QueryControllerInterruptBinding(
_In_ PVOID Context,
_In_ WDFCMRESLIST ResourcesTranslated,
_In_ WDFCMRESLIST ResourcesRaw,
_In_ USHORT TotalBanks,
_Out_ PULONG ResourceMapping
)
{ ... }
Parameters
Context [in]
A pointer to the GPIO controller driver's device context.ResourcesTranslated [in]
A WDFCMRESLIST handle to a collection of framework resource objects. This collection identifies the translated (system-physical) hardware resources that the Plug and Play (PnP) manager has allocated for use by the GPIO controller device.ResourcesRaw [in]
A WDFCMRESLIST handle to a collection of framework resource objects. This collection identifies the raw (bus-relative) hardware resources that the PnP manager has allocated for use by the GPIO controller device.TotalBanks [in]
The total number of banks in the GPIO controller device. This number additionally specifies the length of the ResourceMapping array. GpioClx 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.ResourceMapping [out]
A pointer to a ULONG array that specifies the assignment of interrupt resources to banks. The array contains one element per bank. For each element, the function writes the resource index of the interrupt resource that is assigned to the corresponding bank. The resource index is an index into the resource list (either the ResourcesTranslated list or the ResourcesRaw list). A resource index in the ResourceMapping array must identify a resource of type CmResourceTypeInterrupt. Two or more elements can be set to the same resource index if the corresponding banks share an interrupt resource. If the GPIO controller driver does not assign an interrupt resource to a particular bank, the function writes the value (ULONG)(–1) to the array element for this bank.
Return value
The CLIENT_QueryControllerInterruptBinding function returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error status code.
Remarks
Typically, this function calls a method such as WdfCmResourceListGetDescriptor to enumerate the resources in the ResourcesTranslated or ResourcesRaw list. When a resource of type CmResourceTypeInterrupt is enumerated, the function can assign this resource to a particular bank by writing the resource index to the ResourceMapping array element for this bank. If N is the value of TotalBanks, the banks are numbered 0 to N–1, and the bank number is used to index into the ResourceMapping array.
If no pins in the GPIO controller device are configured as interrupt inputs, the CLIENT_QueryControllerInterruptBinding function is optional. If the GPIO controller driver does not implement this function, GpioClx can determine independently that the controller is assigned no interrupt resources. If the driver does implement this function, the function should set all elements in the ResourceMapping array to the value (ULONG)(–1).
If all of the banks in the GPIO controller share a single interrupt resource (interrupt line, interrupt vector, or message interrupt), the CLIENT_QueryControllerInterruptBinding function is optional. If the GPIO controller driver does not implement this function, GpioClx can determine independently that the controller is assigned one interrupt resource. If the driver does implement this function, the function should set all elements in the ResourceMapping array to the same resource index.
If the number of allocated interrupt resources is greater than or equal to the number of banks, the CLIENT_QueryControllerInterruptBinding function is optional. If the GPIO controller driver does not implement this function, GpioClx assigns one interrupt resource to each bank, and leaves any remaining resources unassigned. In this case, the first interrupt resource in the list is assigned to the first bank, the second interrupt resource in the list is assigned to the second bank, and so on.
If the GPIO controller contains more than one bank and is assigned more than one interrupt resource, but the number of banks exceeds the number of interrupt resources, the GPIO controller driver must implement a CLIENT_QueryControllerInterruptBinding function to specify the mapping of interrupt resources to banks. Otherwise, a bug check occurs in debug builds of GpioClx.
Examples
The function type for this callback is declared in Gpioclx.h, as follows.
typedef NTSTATUS
GPIO_CLIENT_QUERY_CONTROLLER_INTERRUPT_BINDING(
_In_ PVOID Context,
_In_ WDFCMRESLIST ResourcesTranslated,
_In_ WDFCMRESLIST ResourcesRaw,
_In_ USHORT TotalBanks,
_Out_ PULONG ResourceMapping
);
To define a CLIENT_QueryControllerInterruptBinding callback function that is named MyEvtGpioQueryControllerInterruptBinding, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as follows.
GPIO_CLIENT_QUERY_CONTROLLER_INTERRUPT_BINDING MyEvtGpioQueryControllerInterruptBinding;
Then, implement your callback function as follows.
NTSTATUS
MyEvtGpioQueryControllerInterruptBinding(
_In_ PVOID Context,
_In_ WDFCMRESLIST ResourcesTranslated,
_In_ WDFCMRESLIST ResourcesRaw,
_In_ USHORT TotalBanks,
_Out_ PULONG ResourceMapping
)
{ ... }
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_QueryControllerInformation
WdfCmResourceListGetDescriptor
Build date: 9/7/2011