fxdevicefdoapi.cpp

Go to the documentation of this file.

/*++

Copyright (c) Microsoft Corporation

Module Name:

    FxDeviceFdoApi.cpp

Abstract:

    This module exposes the "C" interface to the FxDevice object.

Author:



Environment:

    Kernel mode only

Revision History:

--*/

#include "fxcorepch.hpp"

extern "C" {
// #include "FxDeviceFdoApi.tmh"
}

//
// Extern "C" the rest of the  file
//
extern "C" {

_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
NTSTATUS
STDCALL
WDFEXPORT(WdfFdoAddStaticChild)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Fdo,
    __in
    WDFDEVICE Child
    )
/*++

Routine Description:
    Adds a statically enumerated child to the static device list.

Arguments:
    Fdo - the parent of the child

    Child - the child to add

Return Value:
    NTSTATUS

  --*/

{
    FxStaticChildDescription description;
    FxDevice* pFdo;
    FxDevice* pPdo;
    FxPkgFdo* pPkgFdo;
    NTSTATUS status;

    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         Fdo,
                         FX_TYPE_DEVICE,
                         (PVOID*)&pFdo);

    //
    // Verify type
    //
    if (pFdo->IsLegacy() || pFdo->IsFdo() == FALSE) {
        status = STATUS_INVALID_PARAMETER;

        DoTraceLevelMessage(
            pFdo->GetDriverGlobals(), TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "WDFDEVICE 0x%p is either legacy or is not a Fdo, %!STATUS!",
            Fdo, status);

        return status;
    }

    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         Child,
                         FX_TYPE_DEVICE,
                         (PVOID*)&pPdo);

    if (pPdo->IsLegacy() || pPdo->IsPdo() == FALSE) {
        status = STATUS_INVALID_PARAMETER;

        DoTraceLevelMessage(
            pFdo->GetDriverGlobals(), TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "WDFDEVICE Child 0x%p is either legacy or is not a PDO, %!STATUS!",
            Child, status);

        return status;
    }

    pPkgFdo = pFdo->GetFdoPkg();

    //
    // Try to add the device to the list.  We use the FxDevice* of the PDO as the
    // unique ID in the list.
    //
    description.Header.IdentificationDescriptionSize = sizeof(description);
    description.Pdo = pPdo;

    status = pPkgFdo->m_StaticDeviceList->Add(&description.Header, NULL, NULL);

    if (NT_SUCCESS(status)) {
        pFdo->SetDeviceTelemetryInfoFlags(DeviceInfoHasStaticChildren);
    }

    return status;
}

__drv_maxIRQL(DISPATCH_LEVEL)
VOID
STDCALL
WDFEXPORT(WdfFdoLockStaticChildListForIteration)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Fdo
    )
/*++

Routine Description:
    Locks the static child list for iteration.  Any adds or removes that occur
    while the list is locked are pended until it is unlocked.  Locking can
    be nested.  When the unlock count is zero, the changes are evaluated.

Arguments:
    Fdo - the parent who owns the list of static children

Return Value:
    None

  --*/

{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    WDF_CHILD_LIST_ITERATOR iterator;
    FxDevice* pDevice;
    FxPkgFdo* pPkgFdo;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Fdo,
                                   FX_TYPE_DEVICE,
                                   (PVOID*)&pDevice,
                                   &pFxDriverGlobals);

    //
    // Verify type
    //
    if (pDevice->IsLegacy() || (pDevice->IsFdo() == FALSE)) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "Invalid WDFDEVICE %p is not an FDO", Fdo);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        return;
    }

    pPkgFdo = pDevice->GetFdoPkg();

    //
    // Create a fake iterator to begin iteration.  We will not need it in the
    // retrieve next static child call.
    //
    WDF_CHILD_LIST_ITERATOR_INIT(&iterator, WdfRetrieveAllChildren);

    pPkgFdo->m_StaticDeviceList->BeginIteration(&iterator);
}

_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
WDFDEVICE
STDCALL
WDFEXPORT(WdfFdoRetrieveNextStaticChild)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Fdo,
    __in
    WDFDEVICE PreviousChild,
    __in
    ULONG Flags
    )
/*++

Routine Description:
    Returns the next static child in the list based on the PreviousChild and
    Flags values.

Arguments:
    Fdo - the parent which owns the static child list

    PreviousChild - The child returned on the last call to this DDI.  If NULL,
        returns the first static child specified by the Flags criteria

    Flags - combination of values from WDF_RETRIEVE_CHILD_FLAGS.
        WdfRetrievePresentChildren - reports children who have been reported as
                                     present to pnp
        WdfRetrieveMissingChildren = reports children who have been reported as
                                     missing to pnp
        WdfRetrievePendingChildren = reports children who have been added to the
                                     list, but not yet reported to pnp

Return Value:
    next WDFDEVICE handle representing a static child or NULL

  --*/
{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxDevice* pDevice;
    FxPkgFdo* pPkgFdo;
    WDFDEVICE next;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Fdo,
                                   FX_TYPE_DEVICE,
                                   (PVOID*)&pDevice,
                                   &pFxDriverGlobals);

    //
    // validate Flags
    //
    if (Flags == 0 || (Flags & ~WdfRetrieveAllChildren) != 0) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "Invalid Flags 0x%x", Flags);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        return NULL;
    }

    //
    // Verify type
    //
    if (pDevice->IsLegacy() || (pDevice->IsFdo() == FALSE)) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "WDFDEVICE %p is not an FDO", Fdo);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        return NULL;
    }

    pPkgFdo = pDevice->GetFdoPkg();

    next = pPkgFdo->m_StaticDeviceList->GetNextStaticDevice(PreviousChild, Flags);

    return next;
}

__drv_maxIRQL(DISPATCH_LEVEL)
VOID
STDCALL
WDFEXPORT(WdfFdoUnlockStaticChildListFromIteration)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Fdo
    )
/*++

Routine Description:
    Unlocks the static child list from iteration.  Upon the last unlock, any
    pended modifications to the list will be applied.

Arguments:
    Fdo - the parent who owns the static child list

Return Value:
    None

  --*/
{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    WDF_CHILD_LIST_ITERATOR iterator;
    FxDevice* pDevice;
    FxPkgFdo* pPkgFdo;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Fdo,
                                   FX_TYPE_DEVICE,
                                   (PVOID*)&pDevice,
                                   &pFxDriverGlobals);

    //
    // Verify type
    //
    if (pDevice->IsLegacy() || (pDevice->IsFdo() == FALSE)) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "WDFDEVICE %p is not an FDO", Fdo);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        return;
    }

    //
    // Local iterator used to end iteration.  WdfRetrieveAllChildren is an
    // arbitrary value.
    //
    WDF_CHILD_LIST_ITERATOR_INIT(&iterator, WdfRetrieveAllChildren);

    pPkgFdo = pDevice->GetFdoPkg();
    pPkgFdo->m_StaticDeviceList->EndIteration(&iterator);
}

_Must_inspect_result_
__drv_maxIRQL(PASSIVE_LEVEL)
NTSTATUS
STDCALL
WDFEXPORT(WdfFdoQueryForInterface)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Fdo,
    __in
    LPCGUID InterfaceType,
    __out
    PINTERFACE Interface,
    __in
    USHORT Size,
    __in
    USHORT Version,
    __in_opt
    PVOID InterfaceSpecificData
    )
/*++

Routine Description:
    Sends a query interface pnp request to the top of the stack (which means that
    the request will travel through this device before going down the stack).

Arguments:
    Fdo - the device stack which is being queried

    InterfaceType - interface type specifier

    Interface - Interface block which will be filled in by the component which
                responds to the query interface

    Size - size in bytes of Interfce

    Version - version of InterfaceType being requested

    InterfaceSpecificData - Additional data associated with Interface

Return Value:
    NTSTATUS

  --*/
{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxDeviceBase* pDeviceBase;
    FxDevice* pDevice;
    FxQueryInterfaceParams params = { (PVOID*) &pDevice, FX_TYPE_DEVICE, 0 };
    NTSTATUS status;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Fdo,
                                   FX_TYPE_DEVICE_BASE,
                                   (PVOID*)&pDeviceBase,
                                   &pFxDriverGlobals);

    pDevice = NULL;

    FxPointerNotNull(pFxDriverGlobals, InterfaceType);
    FxPointerNotNull(pFxDriverGlobals, Interface);

    status = FxVerifierCheckIrqlLevel(pFxDriverGlobals, PASSIVE_LEVEL);
    if (!NT_SUCCESS(status)) {
        return status;
    }

    //
    // See if we have a full fledged WDFDEVICE or a miniport WDFDEVICE
    //
    if (NT_SUCCESS(pDeviceBase->QueryInterface(&params))) {
        //
        // Verify type
        //
        if (pDevice->IsLegacy() || (pDevice->IsFdo() == FALSE)) {
            status = STATUS_INVALID_PARAMETER;

            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                "WDFDEVICE 0x%p Device is either legacy or is not a Fdo %!STATUS!",
                Fdo, status);

            return status;
        }
    }
    else {
        //
        // miniport WDFDEVICE, nothing to check
        //
        DO_NOTHING();
    }

    return pDeviceBase->QueryForInterface(
        InterfaceType, Interface, Size, Version, InterfaceSpecificData);
}

__drv_maxIRQL(DISPATCH_LEVEL)
WDFCHILDLIST
STDCALL
WDFEXPORT(WdfFdoGetDefaultChildList)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Fdo
    )
/*++

Routine Description:
    Returns the default dynamic child list associated with the FDO.   For a
    valid handle to be returned, the driver must have configured the default
    list in its device init phase.

Arguments:
    Fdo - the FDO being asked to return the handle

Return Value:
    a valid handle value or NULL

  --*/
{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxDevice* pDevice;
    FxPkgFdo* pPkgFdo;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Fdo,
                                   FX_TYPE_DEVICE,
                                   (PVOID*)&pDevice,
                                   &pFxDriverGlobals);

    //
    // Verify type
    //
    if (pDevice->IsLegacy() || (pDevice->IsFdo() == FALSE)) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "WDFDEVICE %p is not an FDO", Fdo);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        return NULL;
    }

    pPkgFdo = pDevice->GetFdoPkg();

    if (pPkgFdo->m_DefaultDeviceList != NULL) {
        return (WDFCHILDLIST) pPkgFdo->m_DefaultDeviceList->GetObjectHandle();
    }
    else {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "Default child list for FDO %p not configured, call "
            "WdfFdoInitSetDefaultChildListConfig to do so", Fdo);
        return NULL;
    }
}

} // extern "C"