GPIO_CLX_ProcessAddDevicePreDeviceCreate function (gpioclx.h)

Article
10/21/2021

The GPIO_CLX_ProcessAddDevicePreDeviceCreate method loads initialization information into two structures that are passed as input parameters to the WdfDeviceCreate method.

Syntax

NTSTATUS GPIO_CLX_ProcessAddDevicePreDeviceCreate(
  [in]      WDFDRIVER              Driver,
  [in, out] PWDFDEVICE_INIT        DeviceInit,
  [out]     PWDF_OBJECT_ATTRIBUTES FdoAttributes
);

Parameters

[in] Driver

A WDFDRIVER handle to the framework driver object for the GPIO controller driver.

[in, out] DeviceInit

A pointer to a framework-allocated WDFDEVICE_INIT structure. This method loads initialization information into this structure. On return, this structure is ready to be used as an input parameter to the WdfDeviceCreate method.

[out] FdoAttributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure. This method loads initialization information into this structure. On return, this structure is ready to be used as an input parameter to the WdfDeviceCreate method.

Return value

GPIO_CLX_ProcessAddDevicePreDeviceCreate returns STATUS_SUCCESS if the call is successful. Possible return values include the following error codes.

Return code	Description
STATUS_INVALID_PARAMETER	The caller is not a registered client of GpioClx.
STATUS_INSUFFICIENT_RESOURCES	Out of memory.

Remarks

Your GPIO controller driver must call this method in its EvtDriverDeviceAdd callback function, before the call to the WdfDeviceCreate method that creates the device object (FDO) that represents the GPIO controller. Otherwise, the GPIO framework extension (GpioClx) cannot handle I/O requests or process interrupts for the new framework device object.

Examples

The following code example shows the EvtDriverDeviceAdd callback function in the GPIO controller driver for an "XYZ" GPIO controller device.

NTSTATUS
  XyzEvtDriverDeviceAdd(
    _In_ WDFDRIVER Driver,
    _Inout_ PWDFDEVICE_INIT DeviceInit
    )
{
    WDFDEVICE Device;
    WDF_OBJECT_ATTRIBUTES FdoAttributes;
    NTSTATUS Status;

    Status = GPIO_CLX_ProcessAddDevicePreDeviceCreate(Driver,
                                                      DeviceInit,
                                                      &FdoAttributes);
    if (!NT_SUCCESS(Status)) {
        goto ExitDeviceAdd;
    }

    //
    // Call the framework to create the device and attach it to the lower stack.
    //

    Status = WdfDeviceCreate(&DeviceInit, &FdoAttributes, &Device);
    if (!NT_SUCCESS(Status)) {
        goto ExitDeviceAdd;
    }

    Status = GPIO_CLX_ProcessAddDevicePostDeviceCreate(Driver, Device);
    if (!NT_SUCCESS(Status)) {
        goto ExitDeviceAdd;
    }

ExitDeviceAdd:
    return Status;
}

In the preceding code example, the WdfDeviceCreate call creates the framework device object that represents the GPIO controller device. The two input parameters for this call point to WDFDEVICE_INIT and WDF_OBJECT_ATTRIBUTES structures. These structures are modified by the GPIO_CLX_ProcessAddDevicePreDeviceCreate call, which precedes the WdfDeviceCreate call. The output parameter, Device, from the WdfDeviceCreate call is an input parameter to the GPIO_CLX_ProcessAddDevicePostDeviceCreate call, which follows the WdfDeviceCreate call.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Universal
Header	gpioclx.h
Library	Msgpioclxstub.lib
IRQL	PASSIVE_LEVEL