FxChildList Class Reference

#include <fxchildlist.hpp>

Inheritance diagram for FxChildList:

Collaboration diagram for FxChildList:

Public Member Functions
WDFCHILDLIST	GetHandle (VOID)
MxEvent *	GetScanEvent (VOID)
WDFDEVICE	GetDevice (VOID)
CfxDevice *	GetDeviceFromId (__inout PWDF_CHILD_RETRIEVE_INFO Info)
_Must_inspect_result_ NTSTATUS	GetAddressDescription (__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription, __out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription)
VOID	GetAddressDescriptionFromEntry (__in FxDeviceDescriptionEntry *Entry, __out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription)
VOID	BeginScan (__out_opt PULONG ScanTag=NULL)
VOID	EndScan (__inout_opt PULONG ScanTag=NULL)
VOID	CancelScan (__in BOOLEAN EndTheScan, __inout_opt PULONG ScanTag)
VOID	BeginIteration (__inout PWDF_CHILD_LIST_ITERATOR Iterator)
VOID	EndIteration (__inout PWDF_CHILD_LIST_ITERATOR Iterator)
VOID	InitIterator (__inout PWDF_CHILD_LIST_ITERATOR Iterator)
_Must_inspect_result_ NTSTATUS	GetNextDevice (__out WDFDEVICE *Device, __inout PWDF_CHILD_LIST_ITERATOR Iterator, __inout_opt PWDF_CHILD_RETRIEVE_INFO Info)
WDFDEVICE	GetNextStaticDevice (__in WDFDEVICE PreviousDevice, __in ULONG Flags)
BOOLEAN	IsScanCancelled (__in PULONG ScanTag)
_Must_inspect_result_ NTSTATUS	UpdateAsMissing (__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Description)
_Must_inspect_result_ NTSTATUS	UpdateDeviceAsMissing (__in CfxDevice *Device)
VOID	ReenumerateEntry (__inout FxDeviceDescriptionEntry *Entry)
VOID	UpdateAllAsPresent (__in_opt PULONG ScanTag=NULL)
_Must_inspect_result_ NTSTATUS	Add (__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription, __in_opt PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription, __in_opt PULONG ScanTag=NULL)
VOID	UpdateAddressDescriptionFromEntry (__inout FxDeviceDescriptionEntry *Entry, __in PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription)
BOOLEAN	HasAddressDescriptions (VOID)
ULONG	GetAddressDescriptionSize (VOID)
ULONG	GetIdentificationDescriptionSize (VOID)
VOID	CopyId (__out PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Dest, __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Source)
_Must_inspect_result_ NTSTATUS	ProcessBusRelations (__inout PDEVICE_RELATIONS *DeviceRelations)
VOID	InvokeReportedMissingCallback (VOID)
VOID	PostParentToD0 (VOID)
VOID	IndicateWakeStatus (__in NTSTATUS WakeWakeStatus)
VOID	ScanForChildren (VOID)
VOID	NotifyDeviceSurpriseRemove (VOID)
VOID	NotifyDeviceRemove (__inout PLONG ChildCount)
BOOLEAN	IsStaticList (VOID)
ULONG	GetScanCount (VOID)
Public Member Functions inherited from FxNonPagedObject
	FxNonPagedObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)
	FxNonPagedObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObjectType ObjectType)
virtual	~FxNonPagedObject (VOID)
	_Acquires_lock_ (this->m_NPLock.m_Lock) __drv_maxIRQL(DISPATCH_LEVEL) __drv_setsIRQL(DISPATCH_LEVEL) VOID Lock(__out __drv_deref(__drv_savesIRQL) PKIRQL PreviousIrql)
	_Releases_lock_ (this->m_NPLock.m_Lock) __drv_requiresIRQL(DISPATCH_LEVEL) __inline VOID Unlock(__in __drv_restoresIRQL KIRQL PreviousIrql)
	_Acquires_lock_ (this->m_NPLock.m_Lock) __drv_requiresIRQL(DISPATCH_LEVEL) VOID LockAtDispatch(VOID)
	_Requires_lock_held_ (this->m_NPLock.m_Lock) _Releases_lock_(this -> m_NPLock.m_Lock) __drv_requiresIRQL(DISPATCH_LEVEL) __inline VOID UnlockFromDispatch(VOID)
Public Member Functions inherited from FxObject
PVOID	GetCOMWrapper ()
void	SetCOMWrapper (__drv_aliasesMem PVOID Wrapper)
	FxObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)
virtual	~FxObject (VOID)
PVOID __inline	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObjectType Type)
PVOID __inline	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in_opt PWDF_OBJECT_ATTRIBUTES Attributes, __in USHORT ExtraSize=0)
VOID	operator delete (__in PVOID Memory)
VOID	SetNoContextHeader (VOID)
PVOID __inline	GetObjectHandle (VOID)
__inline FxContextHeader *	GetContextHeader (VOID)
__inline PFX_DRIVER_GLOBALS	GetDriverGlobals (VOID)
WDFTYPE	GetType (VOID)
USHORT	GetObjectSize (VOID)
LONG	GetRefCnt (VOID)
FxTagTracker *	GetTagTracker (VOID)
CfxDevice *	GetDevice (VOID)
CfxDeviceBase *	GetDeviceBase (VOID)
VOID	SetDeviceBase (__in CfxDeviceBase *DeviceBase)
__inline VOID	CallCleanup (VOID)
ULONG __inline	AddRef (__in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual ULONG	Release (__in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual ULONG	AddRefOverride (__in WDFOBJECT_OFFSET Offset, __in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual ULONG	ReleaseOverride (__in WDFOBJECT_OFFSET Offset, __in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual _Must_inspect_result_ NTSTATUS	QueryInterface (__in FxQueryInterfaceParams *Params)
VOID	MarkTraceState (VOID)
BOOLEAN __inline	IsTraceState (VOID)
VOID __inline	TraceDroppedEvent (__in FxObjectDroppedEvent Event)
VOID	MarkPassiveDispose (__in FxObjectLockState State=ObjectLock)
VOID	MarkPassiveCallbacks (__in FxObjectLockState State=ObjectLock)
VOID	MarkForceDisposeThread (__in FxObjectLockState State=ObjectLock)
BOOLEAN	IsPassiveCallbacks (__in BOOLEAN AcquireLock=TRUE)
BOOLEAN	IsPassiveDispose (__in BOOLEAN AcquireLock=TRUE)
BOOLEAN	IsForceDisposeThread (__in BOOLEAN AcquireLock=TRUE)
VOID	MarkCommitted (VOID)
BOOLEAN	IsCommitted (VOID)
VOID	MarkDisposeOverride (__in FxObjectLockState State=ObjectLock)
VOID	MarkNoDeleteDDI (__in FxObjectLockState State=ObjectLock)
BOOLEAN	IsNoDeleteDDI (VOID)
_Must_inspect_result_ NTSTATUS	Commit (__in_opt PWDF_OBJECT_ATTRIBUTES Attributes, __out_opt WDFOBJECT *ObjectHandle, __in_opt FxObject *Parent=NULL, __in BOOLEAN AssignDriverAsDefaultParent=TRUE)
VOID	DeleteFromFailedCreate (VOID)
VOID	ClearEvtCallbacks (VOID)
BOOLEAN	EarlyDispose (VOID)
virtual VOID	DeleteObject (VOID)
_Must_inspect_result_ NTSTATUS	AssignParentObject (__in FxObject *ParentObject)
_Must_inspect_result_ NTSTATUS	AddContext (__in FxContextHeader *Header, __in PVOID *Context, __in PWDF_OBJECT_ATTRIBUTES Attributes)
_Must_inspect_result_ NTSTATUS	RemoveParentAssignment (VOID)
_Must_inspect_result_ FxObject *	GetParentObjectReferenced (__in PVOID Tag)
BOOLEAN	IsDisposed (VOID)

Static Public Member Functions
static _Must_inspect_result_ NTSTATUS	_CreateAndInit (__out FxChildList **ChildList, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_OBJECT_ATTRIBUTES ListAttributes, __in size_t TotalDescriptionSize, __in CfxDevice *Device, __in PWDF_CHILD_LIST_CONFIG ListConfig, __in BOOLEAN Static=FALSE)
static _Must_inspect_result_ NTSTATUS	_ValidateConfig (__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_CHILD_LIST_CONFIG Config, __in size_t *TotalDescriptionSize)
static _Must_inspect_result_ NTSTATUS	_ComputeTotalDescriptionSize (__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_CHILD_LIST_CONFIG Config, __in size_t *TotalDescriptionSize)
static size_t	_ComputeRelationsSize (__in ULONG Count)
static FxChildList *	_FromEntry (__in FxTransactionedEntry *Entry)
Static Public Member Functions inherited from FxObject
static FxObject *	_FromDisposeEntry (__in PSINGLE_LIST_ENTRY Entry)
static FxObject *	_GetObjectFromHandle (__in WDFOBJECT Handle, __inout PWDFOBJECT_OFFSET ObjectOffset)
static PVOID __inline	_ToHandle (__in FxObject *Object)
static VOID __inline	_ReferenceActual (__in WDFOBJECT Object, __in_opt PVOID Tag, __in LONG Line, __in PSTR File)
static VOID __inline	_DereferenceActual (__in WDFOBJECT Object, __in_opt PVOID Tag, __in LONG Line, __in PSTR File)
static PVOID	_GetDebugBase (__in FxObject *Object)
static PFX_POOL_HEADER	_CleanupPointer (__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObject *Object)
static _Must_inspect_result_ NTSTATUS	_GetEffectiveLock (__in FxObject *Object, __in_opt IFxHasCallbacks *Callbacks, __in BOOLEAN AutomaticLocking, __in BOOLEAN PassiveCallbacks, __out FxCallbackLock **CallbackLock, __out_opt FxObject **CallbackLockObject)
static _Must_inspect_result_ NTSTATUS	_ObjectQuery (_In_ FxObject *Object, _In_ CONST GUID *Guid, _In_ ULONG QueryBufferLength, _Out_writes_bytes_(QueryBufferLength) PVOID QueryBuffer)

Public Attributes
FxTransactionedEntry	m_TransactionLink

Protected Member Functions
	FxChildList (__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in size_t TotalDescriptionSize, __in CfxDevice *Device, __in BOOLEAN Static)
virtual BOOLEAN	Dispose (VOID)
VOID	Initialize (__in PWDF_CHILD_LIST_CONFIG Config)
BOOLEAN	ReenumerateEntryLocked (__inout FxDeviceDescriptionEntry *Entry, __in BOOLEAN FromQDR)
BOOLEAN	CloneEntryLocked (__inout PLIST_ENTRY FreeListHead, __inout FxDeviceDescriptionEntry *Entry, __in BOOLEAN FromQDR)
VOID	ProcessModificationsLocked (__inout PLIST_ENTRY FreeListHead)
VOID	MarkDescriptionNotPresentWorker (__inout FxDeviceDescriptionEntry *DescriptionEntry, __in BOOLEAN ModificationCanBeQueued)
VOID	MarkModificationNotPresentWorker (__inout PLIST_ENTRY FreeListHead, __inout FxDeviceDescriptionEntry *ModificationEntry)
VOID	DrainFreeListHead (__inout PLIST_ENTRY FreeListHead)
FxDeviceDescriptionEntry *	SearchBackwardsForMatchingModificationLocked (__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Id)
FxDeviceDescriptionEntry *	SearchBackwardsForMatchingDescriptionLocked (__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Id)
_Must_inspect_result_ NTSTATUS	VerifyDescriptionEntry (__in PLIST_ENTRY Entry)
_Must_inspect_result_ NTSTATUS	VerifyModificationEntry (__in PLIST_ENTRY Entry)
BOOLEAN	CreateDevice (__inout FxDeviceDescriptionEntry *Entry, __inout PBOOLEAN InvalidateRelations)
_Must_inspect_result_ NTSTATUS	DuplicateId (__out PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Dest, __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Source)
BOOLEAN	CompareId (__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Lhs, __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Rhs)
_Must_inspect_result_ NTSTATUS	DuplicateAddress (__out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER Dest, __in PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER Source)
VOID	CopyAddress (__out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER Dest, __in_opt PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER Source)
VOID	CleanupDescriptions (__in_opt PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdDescription, __in_opt PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddrDescription)
Protected Member Functions inherited from FxObject
	FxObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObjectType ObjectType)
FxObjectDebugExtension *	GetDebugExtension (VOID)
BOOLEAN	IsDebug (VOID)
VOID	AllocateTagTracker (__in WDFTYPE Type)
virtual VOID	SelfDestruct (VOID)
PVOID __inline	GetObjectHandleUnchecked (VOID)
VOID __inline	DestroyChildren (VOID)
VOID	DeleteEarlyDisposedObject (VOID)

Protected Attributes
size_t	m_TotalDescriptionSize
ULONG	m_IdentificationDescriptionSize
ULONG	m_AddressDescriptionSize
FxChildListCreateDeviceCallback	m_EvtCreateDevice
FxChildListScanForChildrenCallback	m_EvtScanForChildren
PFN_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY	m_EvtIdentificationDescriptionCopy
PFN_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE	m_EvtIdentificationDescriptionDuplicate
PFN_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_CLEANUP	m_EvtIdentificationDescriptionCleanup
PFN_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE	m_EvtIdentificationDescriptionCompare
PFN_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY	m_EvtAddressDescriptionCopy
PFN_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE	m_EvtAddressDescriptionDuplicate
PFN_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_CLEANUP	m_EvtAddressDescriptionCleanup
PFN_WDF_CHILD_LIST_DEVICE_REENUMERATED	m_EvtChildListDeviceReenumerated
KSPIN_LOCK	m_ListLock
LIST_ENTRY	m_DescriptionListHead
LIST_ENTRY	m_ModificationListHead
FxChildListState	m_State
BOOLEAN	m_InvalidationNeeded
BOOLEAN	m_StaticList
BOOLEAN	m_IsAdded
UCHAR	m_EnumRetries
PULONG	m_ScanTag
ULONG	m_ScanCount
MxEvent	m_ScanEvent
Protected Attributes inherited from FxObject
union {
CfxDeviceBase *   m_DeviceBase
CfxDevice *   m_Device
};

Friends
struct	FxDeviceDescriptionEntry

Additional Inherited Members
Static Protected Member Functions inherited from FxObject
static PVOID	_GetBase (__in FxObject *Object)

Detailed Description

Definition at line 102 of file fxchildlist.hpp.

Constructor & Destructor Documentation

FxChildList()

FxChildList::FxChildList ( __in PFX_DRIVER_GLOBALS  FxDriverGlobals, __in size_t  TotalDescriptionSize, __in CfxDevice *  Device, __in BOOLEAN  Static  )

protected

Definition at line 298 of file fxchildlist.cpp.

      :
    FxNonPagedObject(FX_TYPE_CHILD_LIST,sizeof(FxChildList), FxDriverGlobals),
    m_TotalDescriptionSize(TotalDescriptionSize),
    m_EvtCreateDevice(FxDriverGlobals),
    m_EvtScanForChildren(FxDriverGlobals)
{
    //
    // Transaction link into list of FxChildList pointers maintained by
    // FxDevice's pnp package.
    //
    m_TransactionLink.SetTransactionedObject(this);

    m_Device = Device;

    m_IdentificationDescriptionSize = 0;
    m_AddressDescriptionSize = 0;

    m_EvtIdentificationDescriptionDuplicate = NULL;
    m_EvtIdentificationDescriptionCopy = NULL;
    m_EvtIdentificationDescriptionCleanup = NULL;
    m_EvtIdentificationDescriptionCompare = NULL;

    m_EvtAddressDescriptionDuplicate = NULL;
    m_EvtAddressDescriptionCopy = NULL;
    m_EvtAddressDescriptionCleanup = NULL;

    KeInitializeSpinLock(&m_ListLock);
    InitializeListHead(&m_DescriptionListHead);
    InitializeListHead(&m_ModificationListHead);

    m_State = ListUnlocked;

    m_InvalidationNeeded = FALSE;
    m_StaticList = Static;
    m_IsAdded = FALSE;

    m_EnumRetries = 0;

    m_ScanTag = NULL;
    m_ScanCount = 0;

    //
    // We want all waiters on the event to be satisfied, not just the first one
    //
    m_ScanEvent.Initialize(NotificationEvent, TRUE);

    MarkDisposeOverride(ObjectDoNotLock);
}

Referenced by _CreateAndInit().

Member Function Documentation

_ComputeRelationsSize()

static size_t FxChildList::_ComputeRelationsSize ( __in ULONG  Count )

inlinestatic

Definition at line 361 of file fxchildlist.hpp.

    {
        if (Count == 0) {
            return sizeof(((PDEVICE_RELATIONS) NULL)->Count);
        }
        else {
            return sizeof(DEVICE_RELATIONS) + (Count-1)*sizeof(PDEVICE_OBJECT);
        }
    }

Referenced by FxPkgPnp::HandleQueryDeviceRelations(), and ProcessBusRelations().

_ComputeTotalDescriptionSize()

_Must_inspect_result_ NTSTATUS FxChildList::_ComputeTotalDescriptionSize ( __in PFX_DRIVER_GLOBALS  FxDriverGlobals, __in PWDF_CHILD_LIST_CONFIG  Config, __in size_t *  TotalDescriptionSize  )

static

Definition at line 3194 of file fxchildlist.cpp.

{
    size_t addressAligned, idAligned;
    NTSTATUS status;

    *TotalDescriptionSize = 0;

    //
    // FxDeviceDescriptionEntry::operator new() will allocate a block of memory
    // that is
    // size =
    //  WDF_ALIGN_SIZE_UP(sizeof(FxDeviceDescriptionEntry), sizeof(PVOID)) +
    //  WDF_ALIGN_SIZE_UP(AddressDescriptionSize, sizeof(PVOID)) +
    //  WDF_ALIGN_SIZE_UP(IdentificationDescriptionSize, sizeof(PVOID));
    //
    // Validate the size now beforehand, not every we allocate
    //
    //
    // Test for overflow
    //
    idAligned = WDF_ALIGN_SIZE_UP(Config->IdentificationDescriptionSize,
                                  sizeof(PVOID));
    if (idAligned < Config->IdentificationDescriptionSize) {
        status = STATUS_INVALID_PARAMETER;
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                            "Config->IdentificationDescriptionSize %d too large"
                            "%!STATUS!", Config->IdentificationDescriptionSize,
                            status);
        return status;
    }

    addressAligned = WDF_ALIGN_SIZE_UP(Config->AddressDescriptionSize,
                                       sizeof(PVOID));
    if (addressAligned < Config->AddressDescriptionSize) {
        status = STATUS_INVALID_PARAMETER;
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                        "Config->AddressDescriptionSize %d too large, %!STATUS!",
                        Config->AddressDescriptionSize, status);
        return status;
    }

    status = RtlSizeTAdd(
        WDF_ALIGN_SIZE_UP(sizeof(FxDeviceDescriptionEntry), sizeof(PVOID)),
        idAligned,
        TotalDescriptionSize
        );
    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(
            FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
            "Could not add ID description size to block size, %!STATUS!",
            status);
        return status;
    }

    status = RtlSizeTAdd(*TotalDescriptionSize,
                         addressAligned,
                         TotalDescriptionSize);
    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(
            FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
            "Could not add address description size to block size, %!STATUS!",
            status);
        return status;
    }

    return STATUS_SUCCESS;
}

Referenced by _ValidateConfig(), FxPkgFdo::CreateDefaultDeviceList(), and FxPkgFdo::Initialize().

_CreateAndInit()

_Must_inspect_result_ NTSTATUS FxChildList::_CreateAndInit ( __out FxChildList **  ChildList, __in PFX_DRIVER_GLOBALS  FxDriverGlobals, __in PWDF_OBJECT_ATTRIBUTES  ListAttributes, __in size_t  TotalDescriptionSize, __in CfxDevice *  Device, __in PWDF_CHILD_LIST_CONFIG  ListConfig, __in BOOLEAN  Static = FALSE  )

static

Definition at line 367 of file fxchildlist.cpp.

{
    NTSTATUS ntStatus;
    FxChildList *childList = NULL;

    //
    // Initialize
    //
    *ChildList = NULL;

    //
    // Allocate a new child list object
    //
    childList = new(FxDriverGlobals, ListAttributes)
        FxChildList(FxDriverGlobals, TotalDescriptionSize, Device, Static);
    if (childList == NULL) {
        ntStatus = STATUS_INSUFFICIENT_RESOURCES;
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                            "No memory for WDFCHILDLIST handle, %!STATUS!",
                            ntStatus);
        goto exit;
    }

    //
    // Initialize the child list object
    //
    childList->Initialize(ListConfig);

    *ChildList = childList;
    ntStatus = STATUS_SUCCESS;

exit:
    if (!NT_SUCCESS(ntStatus)) {
        if (NULL != childList) {
            childList->DeleteFromFailedCreate();
        }
    }
    return ntStatus;
}

Referenced by FxPkgFdo::CreateDefaultDeviceList(), and FxPkgFdo::Initialize().

_FromEntry()

static FxChildList* FxChildList::_FromEntry ( __in FxTransactionedEntry *  Entry )

inlinestatic

Definition at line 375 of file fxchildlist.hpp.

    {
        return CONTAINING_RECORD(Entry, FxChildList, m_TransactionLink);
    }

Referenced by FxPkgPnp::ChildListNotifyRemove(), FxPkgPnp::HandleQueryBusRelations(), and FxPkgPnp::PnpEventSurpriseRemovePendingOverload().

_ValidateConfig()

_Must_inspect_result_ NTSTATUS FxChildList::_ValidateConfig ( __in PFX_DRIVER_GLOBALS  FxDriverGlobals, __in PWDF_CHILD_LIST_CONFIG  Config, __in size_t *  TotalDescriptionSize  )

static

Definition at line 3150 of file fxchildlist.cpp.

{
    NTSTATUS status;

    if (Config == NULL) {
        status = STATUS_INVALID_PARAMETER;
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                    "Invalid Config, NULL is not allowed, %!STATUS!", status);
        return status;
    }

    if (Config->Size != sizeof(WDF_CHILD_LIST_CONFIG)) {
        status = STATUS_INFO_LENGTH_MISMATCH;
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                    "Config->Size incorrect, expected %d, got %d, %!STATUS!",
                        sizeof(WDF_CHILD_LIST_CONFIG), Config->Size, status);
        return status;
    }
    if (Config->IdentificationDescriptionSize == 0) {
        status = STATUS_INVALID_PARAMETER;
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                    "Config->IdentificationDescriptionSize must be non zero, "
                    "%!STATUS!", status);
        return status;
    }
    if (Config->EvtChildListCreateDevice == NULL) {
        status = STATUS_INVALID_PARAMETER;
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                    "Config->EvtChildListCreateDevice, NULL is not allowed, "
                    "%!STATUS!", status);
        return status;
    }

    return _ComputeTotalDescriptionSize(FxDriverGlobals,
                                        Config,
                                        TotalDescriptionSize);
}

Add()

_Must_inspect_result_ NTSTATUS FxChildList::Add	(	__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER	IdentificationDescription,
		__in_opt PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER	AddressDescription,
		__in_opt PULONG	ScanTag = NULL
	)

Definition at line 1488 of file fxchildlist.cpp.

{
    LIST_ENTRY freeHead;
    KIRQL irql;
    NTSTATUS status;
    FxDeviceDescriptionEntry* pEntry;
    BOOLEAN allocNewEntry;

    if (ScanTag != NULL) {
        if (*ScanTag != ScanTagActive) {
            ASSERT(*ScanTag == ScanTagCancelled);

            //
            // The descriptions are duplicated if needed, so no need to clean
            // them up
            //
            // CleanupDescriptions(IdentificationDescription,
            //                     AddressDescription);

            return STATUS_CANCELLED;
        }
    }

    status = STATUS_UNSUCCESSFUL;
    allocNewEntry = FALSE;
    InitializeListHead(&freeHead);

    KeAcquireSpinLock(&m_ListLock, &irql);

    pEntry = SearchBackwardsForMatchingModificationLocked(
        IdentificationDescription
        );

    if (pEntry != NULL) {
        switch (pEntry->m_ModificationState) {
        case ModificationInsert:
            if (HasAddressDescriptions()) {
                CopyAddress(pEntry->m_AddressDescription,
                            AddressDescription);
            }

            //
            // There is already a pending insert operation. All we need do is
            // update the stored description.
            //
            pEntry->m_FoundInLastScan = TRUE;

            status = STATUS_OBJECT_NAME_EXISTS;
            break;

        case ModificationRemove:
        case ModificationRemoveNotify:
            //
            // We found a pending remove. Therefore we need to add an insert
            // operation to the end of the mod list.
            //
            allocNewEntry = TRUE;
            break;

        default:
            ASSERTMSG("Invalid description modification state\n", FALSE);
            break;
        }
    }
    else {
        //
        // There are no matching modifications queued in the list. Go examine
        // the main list. We can't modify any of the child links right now
        // because the list might be locked down, but it is scannable!
        //
        pEntry = SearchBackwardsForMatchingDescriptionLocked(
            IdentificationDescription
            );

        if (pEntry != NULL && pEntry->IsPresent()) {
            //
            // This is an update. Enqueue it through this node.
            //
            ASSERT(pEntry->m_ModificationState == ModificationUnspecified);

            if (HasAddressDescriptions()) {
                CopyAddress(pEntry->m_AddressDescription,
                            AddressDescription);
            }

            pEntry->m_FoundInLastScan = TRUE;
            status = STATUS_OBJECT_NAME_EXISTS;
        }
        else {
            //
            // Either no entry was found, or a "missing" entry was identified
            // instead. In both cases we need to add an insert operation to the
            // end of the modification list.
            //
            allocNewEntry = TRUE;
        }
    }

    if (allocNewEntry) {

        pEntry =
            new(GetDriverGlobals(), m_TotalDescriptionSize)
                FxDeviceDescriptionEntry(this,
                                         m_IdentificationDescriptionSize,
                                         m_AddressDescriptionSize);

        if (pEntry != NULL) {
            status = DuplicateId(pEntry->m_IdentificationDescription,
                   IdentificationDescription);

            if (NT_SUCCESS(status) && HasAddressDescriptions()) {
                status = DuplicateAddress(pEntry->m_AddressDescription,
                                          AddressDescription);
            }

            if (NT_SUCCESS(status)) {
                pEntry->m_FoundInLastScan = TRUE;
                InsertTailList(&m_ModificationListHead,
                               &pEntry->m_ModificationLink);

                if (m_StaticList) {
                    FxDevice* pPdo;

                    pPdo = CONTAINING_RECORD(pEntry->m_IdentificationDescription,
                                             FxStaticChildDescription,
                                             Header)->Pdo;

                    //
                    // The device is no longer deletable by the driver writer
                    //
                    pPdo->MarkNoDeleteDDI();

                    //
                    // Plug in the description like we do for dynamic PDOs in
                    // FxPkgPdo::Initialize.
                    //
                    pPdo->GetPdoPkg()->m_Description = pEntry;

                    //
                    // Let the device know it was inserted into the list.  This
                    // used to know in pPdo::DeleteObject how to proceed.
                    //
                    pPdo->GetPdoPkg()->m_AddedToStaticList = TRUE;
                }
            }
            else {
                InsertTailList(&freeHead, &pEntry->m_DescriptionLink);
            }
        }
        else {
            status = STATUS_INSUFFICIENT_RESOURCES;
        }
    }

    ProcessModificationsLocked(&freeHead);

    KeReleaseSpinLock(&m_ListLock, irql);

    DrainFreeListHead(&freeHead);

    return status;
}

BeginIteration()

VOID FxChildList::BeginIteration

(

__inout PWDF_CHILD_LIST_ITERATOR

Iterator

)

Definition at line 820 of file fxchildlist.cpp.

{
    KIRQL irql;

    //
    // Almost the same semantic as BeginScan except we don't mark all of the
    // children as missing when we start.
    //
    KeAcquireSpinLock(&m_ListLock, &irql);

    InitIterator(Iterator);
    //
    // Set the scanevent to non-signaled state. Some code paths such as
    // PDO eject will wait for the completion of child list iteration or scan
    // so that a QDR that follows eject is guaranteed to pick up the change in
    // PDO state that the code path made. Note that scan and iteration can be
    // nested and in that case this event will be clear each time but it will be
    // set (signalled) only after all the iteration and scan opeartions have
    // completed.
    //
    m_ScanEvent.Clear();
    m_ScanCount++;

    DoTraceLevelMessage(GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                        "Begin iteration on WDFCHILDLIST %p, scan count %d",
                        GetHandle(), m_ScanCount);

    KeReleaseSpinLock(&m_ListLock, irql);
}

BeginScan()

VOID FxChildList::BeginScan

(

__out_opt PULONG

ScanTag = NULL

)

Definition at line 555 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pEntry;
    PLIST_ENTRY ple;
    KIRQL irql;

    KeAcquireSpinLock(&m_ListLock, &irql);

    // KeClearEvent is faster than KeResetEvent for putting event to not-signaled state
    m_ScanEvent.Clear();
    m_ScanCount++;

    DoTraceLevelMessage(
        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
        "Begin scan on WDFCHILDLIST %p, scan count %d",
        GetHandle(), m_ScanCount);

    if (ScanTag != NULL) {
        if (m_ScanTag != NULL) {
            *m_ScanTag = ScanTagCancelled;
        }

        *ScanTag = ScanTagActive;
        m_ScanTag = ScanTag;
    }

    //
    // Start by walking over all entries and setting their FoundInLastScan
    // fields to FALSE. We need to set both present items in the Desc list
    // and inserts in the Mod list. It's actually easier just to walk over
    // everything.
    //
    for (ple = m_DescriptionListHead.Flink;
         ple != &m_DescriptionListHead;
         ple = ple->Flink) {
        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);
        pEntry->m_FoundInLastScan = FALSE;
    }

    for (ple = m_ModificationListHead.Flink;
         ple != &m_ModificationListHead;
         ple = ple->Flink) {
        pEntry = FxDeviceDescriptionEntry::_FromModificationLink(ple);
        pEntry->m_FoundInLastScan = FALSE;
    }

    KeReleaseSpinLock(&m_ListLock, irql);
}

CancelScan()

VOID FxChildList::CancelScan	(	__in BOOLEAN	EndTheScan,
		__inout_opt PULONG	ScanTag
	)

Definition at line 795 of file fxchildlist.cpp.

{
    *ScanTag = ScanTagCancelled;

    if (EndTheScan) {
        EndScan(ScanTag);
    }
}

CleanupDescriptions()

VOID FxChildList::CleanupDescriptions ( __in_opt PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  IdDescription, __in_opt PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  AddrDescription  )

inlineprotected

Definition at line 544 of file fxchildlist.hpp.

    {
        if (m_EvtAddressDescriptionCleanup != NULL && AddrDescription != NULL) {
            m_EvtAddressDescriptionCleanup(GetHandle(), AddrDescription);
        }

        if (m_EvtIdentificationDescriptionCleanup != NULL && IdDescription != NULL) {
            m_EvtIdentificationDescriptionCleanup(GetHandle(), IdDescription);
        }
    }

Referenced by DrainFreeListHead().

CloneEntryLocked()

BOOLEAN FxChildList::CloneEntryLocked ( __inout PLIST_ENTRY  FreeListHead, __inout FxDeviceDescriptionEntry *  Entry, __in BOOLEAN  FromQDR  )

protected

Definition at line 1675 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pClone;
    BOOLEAN invalidateRelations;

    DoTraceLevelMessage(
        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
        "attempting to clone PDO WDFDEVICE %p, !devobj %p, From QDR %d",
        Entry->m_Pdo->GetHandle(), Entry->m_Pdo->GetDeviceObject(), FromQDR);

    invalidateRelations = FALSE;

    pClone = Entry->Clone(FreeListHead);

    if (pClone != NULL) {
        //
        // Check to see if the driver writer OKs the cloning, aka
        // reenumeration.
        //
        if (m_EvtChildListDeviceReenumerated != NULL &&
            m_EvtChildListDeviceReenumerated(
                GetHandle(),
                Entry->m_Pdo->GetHandle(),
                Entry->m_AddressDescription,
                pClone->m_AddressDescription) == FALSE){
            //
            // The clone will be freed later by the caller by placing
            // it on the free list.
            //
            InsertTailList(FreeListHead, &pClone->m_DescriptionLink);
        }
        else {
            DoTraceLevelMessage(
                GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                "clone successful (new entry is %p), marking PDO "
                "WDFDEVICE %p, !devobj %p as missing", pClone,
                Entry->m_Pdo->GetHandle(), Entry->m_Pdo->GetDeviceObject());

            //
            // Setup the state of the clone
            //
            pClone->m_DescriptionState = DescriptionPresentNeedsInstantiation;
            pClone->m_ModificationState = ModificationUnspecified;

            //
            // This is important that this is last.  If a subsequent
            // modification arrives for this device, we want to find the
            // clone before the old device.  Since all changes search the
            // list backwards, inserting at the tail accomplishes this.
            //
            InsertTailList(&m_DescriptionListHead,
                           &pClone->m_DescriptionLink);

            if (FromQDR == FALSE) {
                Entry->m_DescriptionState = DescriptionNotPresent;
                invalidateRelations = TRUE;
            }
        }
    }
    else {
        //
        // Could not allocate a clone, do not anything.
        //
        DO_NOTHING();
    }

    //
    // Convert the original device's modification state back to a
    // unspecified in all cases.
    //
    Entry->m_ModificationState = ModificationUnspecified;

    return invalidateRelations;
}

Referenced by ProcessBusRelations(), and ProcessModificationsLocked().

CompareId()

BOOLEAN FxChildList::CompareId ( __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  Lhs, __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  Rhs  )

inlineprotected

Definition at line 492 of file fxchildlist.hpp.

    {
        if (m_EvtIdentificationDescriptionCompare != NULL) {
            return m_EvtIdentificationDescriptionCompare(GetHandle(),
                                                         Lhs,
                                                         Rhs);
        }
        else {
            return (m_IdentificationDescriptionSize ==
                    RtlCompareMemory(Lhs,
                                     Rhs,
                                     m_IdentificationDescriptionSize)) ? TRUE
                                                                       : FALSE;
        }
    }

Referenced by SearchBackwardsForMatchingDescriptionLocked(), and SearchBackwardsForMatchingModificationLocked().

CopyAddress()

VOID FxChildList::CopyAddress ( __out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  Dest, __in_opt PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  Source  )

inlineprotected

Definition at line 528 of file fxchildlist.hpp.

    {
        if (Source != NULL) {
            if (m_EvtAddressDescriptionCopy != NULL) {
                m_EvtAddressDescriptionCopy(GetHandle(), Source, Dest);
            }
            else {
                RtlCopyMemory(Dest, Source, m_AddressDescriptionSize);
            }
        }
    }

Referenced by Add(), GetAddressDescription(), GetAddressDescriptionFromEntry(), GetDeviceFromId(), GetNextDevice(), and UpdateAddressDescriptionFromEntry().

CopyId()

VOID FxChildList::CopyId ( __out PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  Dest, __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  Source  )

inline

Definition at line 273 of file fxchildlist.hpp.

    {
        if (m_EvtIdentificationDescriptionCopy != NULL) {
            m_EvtIdentificationDescriptionCopy(GetHandle(), Source, Dest);
        }
        else {
            RtlCopyMemory(Dest, Source, m_IdentificationDescriptionSize);
        }
    }

Referenced by GetNextDevice().

CreateDevice()

BOOLEAN FxChildList::CreateDevice ( __inout FxDeviceDescriptionEntry *  Entry, __inout PBOOLEAN  InvalidateRelations  )

protected

Definition at line 2251 of file fxchildlist.cpp.

{
    WDFDEVICE_INIT init(m_Device->GetDriver());
    NTSTATUS status;
    KIRQL irql;

    init.CreatedOnStack = TRUE;
    init.SetPdo(m_Device);
    init.Pdo.DescriptionEntry = Entry;

    if (m_StaticList) {
        init.CreatedDevice =
            CONTAINING_RECORD(Entry->m_IdentificationDescription,
                              FxStaticChildDescription,
                              Header)->Pdo;
    }
    else {
        //
        // This description needs a device, create it now.
        //
        status = m_EvtCreateDevice.Invoke(
            GetHandle(), Entry->m_IdentificationDescription, &init);

        if (status == STATUS_RETRY) {
            if (init.CreatedDevice != NULL) {
                //
                // Destroy any allocations assocated with the device.
                //
                init.CreatedDevice->Destroy();
            }

            *InvalidateRelations = TRUE;

            return FALSE;
        }

        if (NT_SUCCESS(status)) {
            //
            // Make sure that a framework device was actually created
            //
            if (init.CreatedDevice == NULL) {
                //
                // Driver didn't actually create the device, even though its
                // EvtChildListCreateDevice returned a successful return code.
                // Change the status to indicate an error, so that we enter the
                // error handling code below.
                //
                DoTraceLevelMessage(
                    GetDriverGlobals(), TRACE_LEVEL_ERROR, TRACINGPNP,
                    "EvtChildListCreateDevice returned a successful status "
                    "%!STATUS! but did not create a device object", status);

                FxVerifierDbgBreakPoint(GetDriverGlobals());

                status = STATUS_INVALID_DEVICE_OBJECT_PARAMETER;
            }
        }

        if (!NT_SUCCESS(status)) {
            if (init.CreatedDevice != NULL) {
                KeAcquireSpinLock(&m_ListLock, &irql);
                //
                // Set to missing so that when the pnp machine evaluates whether the
                // PDO has been reported missing or not, it chooses missing and
                // deletes the PDO immediately.
                //
                Entry->m_DescriptionState = DescriptionReportedMissing;

                if (Entry->m_ModificationState != ModificationUnspecified) {
                    //
                    // Cannot be ModificationInsert since this device ID is already
                    // in the list.
                    //
                    // Cannot be ModificationClone since the FDO for this device
                    // is the only one who can ask for that and since PDO creation
                    // failed, there is no FDO.
                    //
                    // Cannot be ModificationRemove because the list is locked
                    // against changes and ModificationRemoveNotify becomes
                    // ModificationRemove only after the list has been unlocked.
                    //
                    ASSERT(Entry->m_ModificationState == ModificationRemoveNotify);

                    //
                    // Remove the modification from the list.  The call to
                    // DeleteDeviceFromFailedCreate below will destroy this
                    // Entry due to the pnp state machine deleting the PDO.
                    //
                    RemoveEntryList(&Entry->m_ModificationLink);
                }
                KeReleaseSpinLock(&m_ListLock, irql);

                ASSERT(init.CreatedDevice->IsPnp());
                ASSERT(init.CreatedDevice->GetDevicePnpState() == WdfDevStatePnpInit);
                ASSERT(init.CreatedDevice->GetPdoPkg()->m_Description != NULL);

                ASSERT(Entry->m_Pdo == NULL);

                DoTraceLevelMessage(
                    GetDriverGlobals(), TRACE_LEVEL_ERROR, TRACINGPNP,
                    "WDFDEVICE %p !devobj %p created, but EvtChildListCreateDevice "
                    "returned status %!STATUS!", init.CreatedDevice->GetHandle(),
                    init.CreatedDevice->GetDeviceObject(), status);

                //
                // Simulate a remove event coming to the device.  After this call
                // returns, init.CreatedDevice is no longer a valid pointer!
                //
                // Please note that DeleteDeviceFromFailedCreate just returns
                // the passed status back unless device is a filter, in which
                // case it changes it to success.
                //
                // It is not really the status of DeleteDeviceFromFailedCreate
                // operation, which is why we don't check it.
                //
                (void) init.CreatedDevice->DeleteDeviceFromFailedCreate(
                                                                status,
                                                                TRUE);

                init.CreatedDevice = NULL;
            }
            else {
                LIST_ENTRY freeHead;

                InitializeListHead(&freeHead);

                //
                // Add a modification that this entry is now gone.  If there is
                // an active scan and it has added this device, there would
                // be no entry in the modification case list because the add
                // would have updated the description entry.
                //
                KeAcquireSpinLock(&m_ListLock, &irql);
                MarkDescriptionNotPresentWorker(Entry, TRUE);
                ProcessModificationsLocked(&freeHead);
                KeReleaseSpinLock(&m_ListLock, irql);

                //
                // Free structures outside of any internal WDF lock
                //
                DrainFreeListHead(&freeHead);
            }

            return FALSE;
        }
    }

    //
    // Assign m_Pdo here once we have a fully baked and created device.  We only
    // assign m_Pdo after we have completely initalized device because we check
    // for m_Pdo in PostParentToD0.
    //
    Entry->m_Pdo = init.CreatedDevice;
    Entry->m_DescriptionState = DescriptionInstantiatedHasObject;

    return TRUE;
}

Referenced by ProcessBusRelations().

Dispose()

BOOLEAN FxChildList::Dispose ( VOID  )

protectedvirtual

Reimplemented from FxObject.

Definition at line 353 of file fxchildlist.cpp.

{
    if (m_IsAdded) {
        ASSERT(m_Device != NULL);
        m_Device->RemoveChildList(this);
    }

    return TRUE;
}

DrainFreeListHead()

VOID FxChildList::DrainFreeListHead ( __inout PLIST_ENTRY  FreeListHead )

protected

Definition at line 2075 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry *pEntry;
    FxDevice* pPdo;
    PLIST_ENTRY pCur;

    while (!IsListEmpty(FreeListHead)) {
        pCur = RemoveHeadList(FreeListHead);
        InitializeListHead(pCur);

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(pCur);

        //
        // If this is a static list and the entry has not yet been instantiated,
        // tell PnP to remove the device.
        //
        // There is a corner case of a static PDO being added and
        // immediately marked as missing before it has a chance to move to
        // description list. This case is handled here by checking the
        // modification state of ModificationNeedsPnpRemoval. Fx cannot just
        // delete the description because there is a driver-created PDO
        // associated with the description and it needs to be cleaned up.
        //
        if (m_StaticList &&
            (pEntry->m_DescriptionState == DescriptionPresentNeedsInstantiation ||
             pEntry->m_ModificationState == ModificationNeedsPnpRemoval )) {

            pPdo = CONTAINING_RECORD(pEntry->m_IdentificationDescription,
                                     FxStaticChildDescription,
                                     Header)->Pdo;

            //
            // The pnp removal path expects that there is no modifcation pending
            // when removing the description.
            //
            if (pEntry->m_ModificationState == ModificationNeedsPnpRemoval) {
                ASSERT(pEntry->m_DescriptionState == DescriptionUnspecified);
                ASSERT(IsListEmpty(&pEntry->m_ModificationLink));

                pEntry->m_ModificationState = ModificationUnspecified;
            }

            //
            // Change the state to reported missing (which is what we are basically
            // simulating here anyways) so that when we process the entry again
            // when the PDO really goes away we cleanup the entry.
            //
            // Also, when posting PnpEventRemove to the child, child will
            // call FxDeviceDescriptionEntry::IsDeviceRemoved which checks for
            // reported missing before reporting if the device has been removed
            // (and we want the device to be reported as removed).
            //
            pEntry->m_DescriptionState = DescriptionReportedMissing;

            //
            // Not yet reported to PnP,  so it should be in the initial state
            //
            ASSERT(pPdo->GetDevicePnpState() == WdfDevStatePnpInit);

            //
            // m_Description should be set when the FxPkgPdo was created
            //
            ASSERT(pPdo->GetPdoPkg()->m_Description != NULL);

            //
            // Since the pPdo->m_PkgPnp->m_DeviceRemoveProcessed == NULL, the
            // pnp state machine will delete the PDO.  We are simulating the same
            // situation where an FDO is in the remove path and is telling each
            // of its removed PDOs to delete themselves.
            //
            pPdo->m_PkgPnp->PnpProcessEvent(PnpEventRemove);
        }
        else {
            CleanupDescriptions(pEntry->m_IdentificationDescription,
                               pEntry->m_AddressDescription);

            delete pEntry;
        }
    }
}

Referenced by Add(), CreateDevice(), EndScan(), InvokeReportedMissingCallback(), NotifyDeviceRemove(), NotifyDeviceSurpriseRemove(), ProcessBusRelations(), FxDeviceDescriptionEntry::ProcessDeviceRemoved(), ReenumerateEntry(), UpdateAllAsPresent(), UpdateAsMissing(), and UpdateDeviceAsMissing().

DuplicateAddress()

_Must_inspect_result_ NTSTATUS FxChildList::DuplicateAddress ( __out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  Dest, __in PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  Source  )

inlineprotected

Definition at line 513 of file fxchildlist.hpp.

    {
        if (m_EvtAddressDescriptionDuplicate != NULL) {
            return m_EvtAddressDescriptionDuplicate(GetHandle(), Source, Dest);
        }
        else {
            RtlCopyMemory(Dest, Source, m_AddressDescriptionSize);
            return STATUS_SUCCESS;
        }
    }

Referenced by Add(), and FxDeviceDescriptionEntry::Clone().

DuplicateId()

_Must_inspect_result_ NTSTATUS FxChildList::DuplicateId ( __out PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  Dest, __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  Source  )

inlineprotected

Definition at line 475 of file fxchildlist.hpp.

    {
        if (m_EvtIdentificationDescriptionDuplicate != NULL) {
            return m_EvtIdentificationDescriptionDuplicate(GetHandle(),
                                                           Source,
                                                           Dest);
        }
        else {
            RtlCopyMemory(Dest, Source, m_IdentificationDescriptionSize);
            return STATUS_SUCCESS;
        }
    }

Referenced by Add(), and FxDeviceDescriptionEntry::Clone().

EndIteration()

VOID FxChildList::EndIteration

(

__inout PWDF_CHILD_LIST_ITERATOR

Iterator

)

Definition at line 853 of file fxchildlist.cpp.

{
    DoTraceLevelMessage(GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                        "end iteration on WDFCHILDLIST");

    //
    // Semantic is exactly the same as EndScan.  Basically, all changes are
    // delayed until there are no more active scans, so the end of an interation
    // is the same as the end of a scan.
    //
    EndScan();

    RtlZeroMemory(&Iterator->Reserved[0], sizeof(Iterator->Reserved));
}

EndScan()

VOID FxChildList::EndScan

(

__inout_opt PULONG

ScanTag = NULL

)

Definition at line 607 of file fxchildlist.cpp.

{
    PLIST_ENTRY pCur, pNext;
    LIST_ENTRY freeHead;
    FxDeviceDescriptionEntry* pEntry;
    KIRQL irql;

    InitializeListHead(&freeHead);

    KeAcquireSpinLock(&m_ListLock, &irql);

    if (ScanTag != NULL) {
        if (*ScanTag != ScanTagActive) {
            ASSERT(*ScanTag == ScanTagCancelled);
            KeReleaseSpinLock(&m_ListLock, irql);
            return;
        }

        *ScanTag = ScanTagFinished;
        m_ScanTag = NULL;
    }

    m_ScanCount--;

    DoTraceLevelMessage(
        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
        "End scan on WDFCHILDLIST %p, scan count %d",
        GetHandle(), m_ScanCount);

    if (m_ScanCount == 0) {
        //
        // Walk over all modification entries and remove any pending insert that
        // wasn't seen in the scan. Note that MarkDescriptionNotPresentWorker will
        // enqueue the entry to be freed later.
        //
        // Also, convert any clones of devices not reported as present to
        // removal modifications so that the original is still reported missing.
        //
        for (pCur = m_ModificationListHead.Flink;
             pCur != &m_ModificationListHead;
             pCur = pNext) {

            pNext = pCur->Flink;

            pEntry = FxDeviceDescriptionEntry::_FromModificationLink(pCur);

            DoTraceLevelMessage(
                GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                "entry %p modified in last scan, "
                "mod state  %!FxChildListModificationState!,"
                "desc state %!FxChildListDescriptionState!",
                pEntry, pEntry->m_ModificationState,
                pEntry->m_DescriptionState);

            if (pEntry->m_FoundInLastScan == FALSE) {
                switch (pEntry->m_ModificationState) {
                case ModificationInsert:
                    //
                    // Insertion that never made through to the end of a scan.
                    //
                    MarkModificationNotPresentWorker(&freeHead, pEntry);
                    break;

                case ModificationClone:
                    DoTraceLevelMessage(
                        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                        "clone of PDO WDFDEVICE %p, !devobj %p dropped because "
                        "it is missing", pEntry->m_Pdo->GetHandle(),
                        pEntry->m_Pdo->GetDeviceObject());

                    //
                    // We were asked for a clone in the middle of a scan and the
                    // device was not reported, so it is now missing.  Convert
                    // the clone modification to a remove modification.
                    //
                    pEntry->m_ModificationState = ModificationRemoveNotify;

                    //
                    // Remove the modification from the current mod list.  It
                    // will be re-added below when we iterate over the
                    // descriptions list.
                    //
                    RemoveEntryList(&pEntry->m_ModificationLink);
                    InitializeListHead(&pEntry->m_ModificationLink);

                    //
                    // We can only have been cloning a device which is present
                    // and not yet reported missing to the OS.
                    //
                    ASSERT(pEntry->m_DescriptionState ==
                              DescriptionInstantiatedHasObject);
                    break;
                }
            }
        }

        //
        // Walk over all desc entries and remove anything that wasn't found in the
        // scan. Since MarkDescriptionNotPresentWorker doesn't drain the
        // modifications, we don't have to worry about any entries disappearing.
        //
        for (pCur = m_DescriptionListHead.Flink;
             pCur != &m_DescriptionListHead;
             pCur = pCur->Flink) {

            pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(pCur);

            if (pEntry->m_PendingDeleteOnScanEnd) {
                //
                // The entry was pnp removed but was not removed from list
                // because scan count was > 0. It is safe to remove and delete
                // it now.

                // Update the current pointer before the entry is removed.
                pCur = pCur->Blink;

                RemoveEntryList(&pEntry->m_DescriptionLink);
                InsertTailList(&freeHead, &pEntry->m_DescriptionLink);
                pEntry = NULL;
                continue;
            }
            else if (pEntry->IsPresent() && pEntry->m_FoundInLastScan == FALSE) {
                if (pEntry->m_Pdo != NULL) {
                    DoTraceLevelMessage(
                        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                        "marking PDO WDFDEVICE %p, !devobj %p as not present",
                        pEntry->m_Pdo->GetHandle(),
                        pEntry->m_Pdo->GetDeviceObject());

                }
                else {
                    DoTraceLevelMessage(
                        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                        "marking PDO (entry %p) which needs instantiation as "
                        "not present", pEntry);
                }

                MarkDescriptionNotPresentWorker(pEntry, TRUE);
            }
        }

        //
        // Attempt to drain any mods we made.
        //
        ProcessModificationsLocked(&freeHead);

        //
        // We need to check m_KnownPdo here because if this
        // object is attached to a PDO, the PDO's devobj could be in a state where
        // PnP does not know it is a PDO yet.  m_KnownPdo
        // is set when the PDO receives a start device and by the time start
        // device arrives, we definitely know the PDO is known the PnP.
        //
        // No need to hold a lock while checking m_KnownPdo
        // because if miss the transition from FALSE to TRUE, relations will
        // automaticaly be invalidated by the cause of that transition (start
        // device arrival).  PnP automatically sends a QDR after a successful
        // start.
        //

        if (m_InvalidationNeeded) {
            PDEVICE_OBJECT pdo;

            //
            // This does the m_KnownPdo check.
            //
            pdo = m_Device->GetSafePhysicalDevice();

            if (pdo != NULL) {
                m_InvalidationNeeded = FALSE;
                IoInvalidateDeviceRelations(pdo, BusRelations);
            }
        }

        m_ScanEvent.Set();
    }

    KeReleaseSpinLock(&m_ListLock, irql);

    //
    // Free structures outside of any internal WDF lock
    //
    DrainFreeListHead(&freeHead);
}

Referenced by CancelScan(), and EndIteration().

GetAddressDescription()

_Must_inspect_result_ NTSTATUS FxChildList::GetAddressDescription	(	__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER	IdentificationDescription,
		__out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER	AddressDescription
	)

Definition at line 509 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pEntry;
    NTSTATUS status;
    KIRQL irql;

    KeAcquireSpinLock(&m_ListLock, &irql);

    pEntry = SearchBackwardsForMatchingModificationLocked(
        IdentificationDescription);

    if (pEntry == NULL) {
        pEntry = SearchBackwardsForMatchingDescriptionLocked(
            IdentificationDescription);
    }

    if (pEntry != NULL) {
        CopyAddress(AddressDescription, pEntry->m_AddressDescription);
        status = STATUS_SUCCESS;
    }
    else {
        status = STATUS_NO_SUCH_DEVICE;
    }

    KeReleaseSpinLock(&m_ListLock, irql);

    return status;
}

GetAddressDescriptionFromEntry()

VOID FxChildList::GetAddressDescriptionFromEntry	(	__in FxDeviceDescriptionEntry *	Entry,
		__out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER	AddressDescription
	)

Definition at line 542 of file fxchildlist.cpp.

{
    KIRQL irql;

    KeAcquireSpinLock(&m_ListLock, &irql);
    CopyAddress(AddressDescription, Entry->m_AddressDescription);
    KeReleaseSpinLock(&m_ListLock, irql);
}

GetAddressDescriptionSize()

ULONG FxChildList::GetAddressDescriptionSize ( VOID  )

inline

Definition at line 257 of file fxchildlist.hpp.

    {
        return m_AddressDescriptionSize;
    }

Referenced by if().

GetDevice()

WDFDEVICE FxChildList::GetDevice

(

VOID

)

Definition at line 450 of file fxchildlist.cpp.

{
    return m_Device->GetHandle();
}

GetDeviceFromId()

CfxDevice * FxChildList::GetDeviceFromId

(

__inout PWDF_CHILD_RETRIEVE_INFO

Info

)

Definition at line 458 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pEntry;
    FxDevice* device;
    WDF_CHILD_LIST_RETRIEVE_DEVICE_STATUS status;
    KIRQL irql;

    device = NULL;

    KeAcquireSpinLock(&m_ListLock, &irql);

    pEntry = SearchBackwardsForMatchingModificationLocked(
        Info->IdentificationDescription);

    if (pEntry != NULL && pEntry->m_ModificationState == ModificationInsert) {
        status = WdfChildListRetrieveDeviceNotYetCreated;
    }
    else {
        pEntry = SearchBackwardsForMatchingDescriptionLocked(
            Info->IdentificationDescription);

        if (pEntry != NULL) {
            if (pEntry->m_DescriptionState == DescriptionPresentNeedsInstantiation) {
                status = WdfChildListRetrieveDeviceNotYetCreated;
            }
            else {
                status = WdfChildListRetrieveDeviceSuccess;
                device = pEntry->m_Pdo;
            }
        }
        else {
            status = WdfChildListRetrieveDeviceNoSuchDevice;
        }
    }

    if (pEntry != NULL && Info->AddressDescription != NULL) {
        CopyAddress(Info->AddressDescription,
                    pEntry->m_AddressDescription);
    }

    KeReleaseSpinLock(&m_ListLock, irql);

    Info->Status = status;

    return device;
}

GetHandle()

WDFCHILDLIST FxChildList::GetHandle ( VOID  )

inline

Definition at line 121 of file fxchildlist.hpp.

    {
        return (WDFCHILDLIST) GetObjectHandle();
    }

Referenced by BeginIteration(), BeginScan(), CleanupDescriptions(), CloneEntryLocked(), CompareId(), CopyAddress(), CopyId(), CreateDevice(), DuplicateAddress(), DuplicateId(), EndScan(), GetNextDevice(), FxPkgPnp::HandleQueryBusRelations(), NotifyDeviceRemove(), ProcessBusRelations(), and ScanForChildren().

GetIdentificationDescriptionSize()

ULONG FxChildList::GetIdentificationDescriptionSize ( VOID  )

inline

Definition at line 265 of file fxchildlist.hpp.

    {
        return m_IdentificationDescriptionSize;
    }

Referenced by if().

GetNextDevice()

_Must_inspect_result_ NTSTATUS FxChildList::GetNextDevice	(	__out WDFDEVICE *	Device,
		__inout PWDF_CHILD_LIST_ITERATOR	Iterator,
		__inout_opt PWDF_CHILD_RETRIEVE_INFO	Info
	)

Definition at line 872 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pEntry;
    PLIST_ENTRY ple;
    NTSTATUS status;
    WDF_CHILD_LIST_RETRIEVE_DEVICE_STATUS dstatus = WdfChildListRetrieveDeviceNoSuchDevice;
    ULONG cur, i;
    KIRQL irql;
    BOOLEAN found;

    pEntry = NULL;
    status = STATUS_NO_MORE_ENTRIES;

    KeAcquireSpinLock(&m_ListLock, &irql);

    ASSERT(m_ScanCount > 0);
    if (m_ScanCount == 0) {
        status = STATUS_INVALID_DEVICE_STATE;

        DoTraceLevelMessage(
            GetDriverGlobals(), TRACE_LEVEL_ERROR, TRACINGPNP,
            "WDFCHILDLIST %p cannot retrieve next device if the list is not "
            "locked for iteration, %!STATUS!", GetHandle(), status);

        goto Done;
    }

    ple = (PLIST_ENTRY) Iterator->Reserved[DescriptionIndex];

    if (ple != NULL) {
        if (GetDriverGlobals()->FxVerifierOn) {
            status = VerifyDescriptionEntry(ple);
            if (!NT_SUCCESS(status)) {
                goto Done;
            }
        }

        found = FALSE;

        //
        // Try to find the next entry
        //
        for (ple = ple->Flink; ple != &m_DescriptionListHead; ple = ple->Flink) {
            pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

            if (pEntry->MatchStateToFlags(Iterator->Flags)) {
                //
                // An item was found
                //
                found = TRUE;

                //
                // Call the caller's compare function to further refine the match
                // if necessary.
                //
                if (Info != NULL &&
                    Info->EvtChildListIdentificationDescriptionCompare != NULL) {

                    found = Info->EvtChildListIdentificationDescriptionCompare(
                        GetHandle(),
                        Info->IdentificationDescription,
                        pEntry->m_IdentificationDescription);
                }

                if (found) {
                    break;
                }
            }
        }

        if (found) {
            //
            // We can safely store the description entry because we are
            // guaranteed it will stay in the description list until m_ScanCount
            // reaches zero.  In that case, the caller would need to call
            // EndIteration
            //
            Iterator->Reserved[DescriptionIndex] = ple;

            if (pEntry->m_Pdo != NULL) {
                *Device = pEntry->m_Pdo->GetHandle();
                dstatus = WdfChildListRetrieveDeviceSuccess;
            }
            else {
                dstatus = WdfChildListRetrieveDeviceNotYetCreated;
            }

            if (Info != NULL) {
                if (Info->IdentificationDescription != NULL) {
                    CopyId(Info->IdentificationDescription,
                           pEntry->m_IdentificationDescription);
                }
                if (Info->AddressDescription != NULL) {
                    CopyAddress(Info->AddressDescription,
                                pEntry->m_AddressDescription);
                }

                Info->Status = dstatus;
            }

            status = STATUS_SUCCESS;
        }
        else {
            Iterator->Reserved[DescriptionIndex] = NULL;
            ple = NULL;
            status = STATUS_NO_MORE_ENTRIES;
        }
    }

    cur = PtrToUlong(Iterator->Reserved[ModificationIndex]);

    if ((Iterator->Flags & WdfRetrievePendingChildren) == 0 ||
        cur == 0) {
        goto Done;
    }


    //
    // Walk the modification list.  Since this list can change from call to call
    // to GetNextDevice we can't rely on the previous entry still being present
    // so we must use an index into the list.  This is not guaranteed to
    // enumerate all pending additions, but it should be good enough.
    //
    found = FALSE;

    for (i = 1, ple = m_ModificationListHead.Flink;
         ple != &m_ModificationListHead;
         ple = ple->Flink) {

        pEntry = FxDeviceDescriptionEntry::_FromModificationLink(ple);

        if (pEntry->m_ModificationState == ModificationInsert) {
            i++;

            if (i > cur) {
                found = TRUE;

                if (Info != NULL &&
                    Info->EvtChildListIdentificationDescriptionCompare != NULL) {

                    found = Info->EvtChildListIdentificationDescriptionCompare(
                        GetHandle(),
                        Info->IdentificationDescription,
                        pEntry->m_IdentificationDescription);
                }

                if (found) {
                    //
                    // Store the next item number
                    //
                    Iterator->Reserved[ModificationIndex] = ULongToPtr(i);

                    if (Info != NULL) {
                        if (Info->IdentificationDescription != NULL) {
                            CopyId(Info->IdentificationDescription,
                                   pEntry->m_IdentificationDescription);
                        }
                        if (Info->AddressDescription != NULL) {
                            CopyAddress(Info->AddressDescription,
                                        pEntry->m_AddressDescription);
                        }

                        Info->Status = WdfChildListRetrieveDeviceNotYetCreated;
                    }

                    status = STATUS_SUCCESS;
                    break;
                }
            }
        }
    }

    if (found == FALSE) {
        Iterator->Reserved[ModificationIndex] = ULongToPtr(0);
    }

Done:
    KeReleaseSpinLock(&m_ListLock, irql);

    return status;
}

GetNextStaticDevice()

WDFDEVICE FxChildList::GetNextStaticDevice	(	__in WDFDEVICE	PreviousDevice,
		__in ULONG	Flags
	)

Definition at line 1059 of file fxchildlist.cpp.

{
    FxStaticChildDescription *pStatic;
    FxDeviceDescriptionEntry* pEntry;
    WDFDEVICE result;
    PLIST_ENTRY ple;
    KIRQL irql;
    BOOLEAN isNext;

    ASSERT(m_StaticList);

    result = NULL;

    if (PreviousDevice == NULL) {
        //
        // No previous handle, we want the first device we find
        //
        isNext = TRUE;
    }
    else {
        //
        // We have a previuos handle, find it in the list first before setting
        // isNext.
        //
        isNext = FALSE;
    }

    KeAcquireSpinLock(&m_ListLock, &irql);

    ASSERT(m_ScanCount > 0);
    if (m_ScanCount == 0) {
        goto Done;
    }

    //
    // Try to find the next entry
    //
    if (Flags & WdfRetrievePresentChildren) {
        for (ple = m_DescriptionListHead.Flink;
             ple != &m_DescriptionListHead;
             ple = ple->Flink) {
            pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

            //
            // If the entry is marked pending delete, skip it, because the
            // relationship between entry and its PDO has been removed and PDO
            // may have actually been deleted by this time. The only reason
            // this entry is here is because there is still a scan going on
            // and the entry can't be removed in the midst of a scan.
            //
            if (pEntry->m_PendingDeleteOnScanEnd) {
                continue;
            }

            pStatic = CONTAINING_RECORD(pEntry->m_IdentificationDescription,
                                        FxStaticChildDescription,
                                        Header);

            //
            // Only return a handle if it is in a state in which the caller is
            // interested in hearing about.
            //
            if (isNext && pEntry->MatchStateToFlags(Flags)) {
                result = pStatic->Pdo->GetHandle();
                break;
            }
            else if (pStatic->Pdo->GetHandle() == PreviousDevice) {
                isNext = TRUE;
            }
        }
    }

    //
    // We have taken care of all the other states (reported, pending removal,
    //  removed) in the previuos loop.
    //
    if (result == NULL && (Flags & WdfRetrievePendingChildren)) {
        //
        // Walk the modification list.  Since this list can change from call to
        // call, there is no way to definitively give the driver a snapshot of
        // this list of modifications.
        //
        for (ple = m_ModificationListHead.Flink;
             ple != &m_ModificationListHead;
             ple = ple->Flink) {

            pEntry = FxDeviceDescriptionEntry::_FromModificationLink(ple);

            if (pEntry->m_PendingDeleteOnScanEnd) {
                continue;
            }

            pStatic = CONTAINING_RECORD(pEntry->m_IdentificationDescription,
                                        FxStaticChildDescription,
                                        Header);

            //
            // Only return a handle if it is in a state in which the caller is
            // interested in hearing about.
            //
            if (isNext && pEntry->m_ModificationState == ModificationInsert) {
                result = pStatic->Pdo->GetHandle();
                break;
            }
            else if (pStatic->Pdo->GetHandle() == PreviousDevice) {
                isNext = TRUE;
            }
        }
    }

Done:
    KeReleaseSpinLock(&m_ListLock, irql);

    return result;
}

GetScanCount()

ULONG FxChildList::GetScanCount ( VOID  )

inline

Definition at line 383 of file fxchildlist.hpp.

    {
        return m_ScanCount;
    }

Referenced by FxDeviceDescriptionEntry::IsDeviceRemoved(), and FxDeviceDescriptionEntry::ProcessDeviceRemoved().

GetScanEvent()

MxEvent* FxChildList::GetScanEvent ( VOID  )

inline

Definition at line 129 of file fxchildlist.hpp.

    {
        return m_ScanEvent.GetSelfPointer();
    }

Referenced by FxPkgPdo::PnpEventEjectHardwareOverload().

HasAddressDescriptions()

BOOLEAN FxChildList::HasAddressDescriptions ( VOID  )

inline

Definition at line 249 of file fxchildlist.hpp.

    {
        return m_AddressDescriptionSize > 0 ? TRUE : FALSE;
    }

Referenced by Add(), FxDeviceDescriptionEntry::Clone(), and if().

IndicateWakeStatus()

VOID FxChildList::IndicateWakeStatus

(

__in NTSTATUS

WakeWakeStatus

)

Definition at line 2911 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pEntry;
    PLIST_ENTRY ple;
    KIRQL irql;

    KeAcquireSpinLock(&m_ListLock, &irql);
    for (ple = m_DescriptionListHead.Flink;
         ple != &m_DescriptionListHead;
         ple = ple->Flink) {

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

        if (pEntry->m_PendingDeleteOnScanEnd) {
            COVERAGE_TRAP();
            continue;
        }

        if (pEntry->m_Pdo != NULL) {
            ASSERT(pEntry->m_Pdo->m_PkgPnp->m_SharedPower.m_WaitWakeOwner == TRUE);
            pEntry->m_Pdo->m_PkgPnp->PowerIndicateWaitWakeStatus(WaitWakeStatus);
        }
    }
    KeReleaseSpinLock(&m_ListLock, irql);
}

Initialize()

VOID FxChildList::Initialize ( __in PWDF_CHILD_LIST_CONFIG  Config )

protected

Definition at line 416 of file fxchildlist.cpp.

{
    //
    // Driver cannot call WdfObjectDelete on this handle
    //
    MarkNoDeleteDDI();

    m_IdentificationDescriptionSize = Config->IdentificationDescriptionSize;
    m_AddressDescriptionSize = Config->AddressDescriptionSize;

    m_EvtCreateDevice.m_Method = Config->EvtChildListCreateDevice;
    m_EvtScanForChildren.m_Method = Config->EvtChildListScanForChildren;

    m_EvtIdentificationDescriptionDuplicate = Config->EvtChildListIdentificationDescriptionDuplicate;
    m_EvtIdentificationDescriptionCopy = Config->EvtChildListIdentificationDescriptionCopy;
    m_EvtIdentificationDescriptionCleanup = Config->EvtChildListIdentificationDescriptionCleanup;
    m_EvtIdentificationDescriptionCompare = Config->EvtChildListIdentificationDescriptionCompare;

    m_EvtAddressDescriptionDuplicate = Config->EvtChildListAddressDescriptionDuplicate;
    m_EvtAddressDescriptionCopy = Config->EvtChildListAddressDescriptionCopy;
    m_EvtAddressDescriptionCleanup = Config->EvtChildListAddressDescriptionCleanup;

    m_EvtChildListDeviceReenumerated = Config->EvtChildListDeviceReenumerated;

    //
    // Add this ChildList to the parent device's list of children lists.
    //
    m_Device->AddChildList(this);
    m_IsAdded = TRUE;
}

Referenced by _CreateAndInit().

InitIterator()

VOID FxChildList::InitIterator

(

__inout PWDF_CHILD_LIST_ITERATOR

Iterator

)

Definition at line 808 of file fxchildlist.cpp.

{
    Iterator->Reserved[DescriptionIndex] = &m_DescriptionListHead;

    if (Iterator->Flags & WdfRetrievePendingChildren) {
        Iterator->Reserved[ModificationIndex] = ULongToPtr(1);
    }
}

Referenced by BeginIteration().

InvokeReportedMissingCallback()

VOID FxChildList::InvokeReportedMissingCallback

(

VOID

)

Definition at line 2836 of file fxchildlist.cpp.

{
    PLIST_ENTRY ple, pNext;
    KIRQL irql;
    FxDeviceDescriptionEntry* pEntry;
    LIST_ENTRY freeHead;

    InitializeListHead(&freeHead);

    //
    // Prevent modification list processing so that we can walk the
    // description list safely.
    //
    KeAcquireSpinLock(&m_ListLock, &irql);
    m_State = ListLockedForEnum;
    KeReleaseSpinLock(&m_ListLock, irql);

    //
    // Invoke the ReportedMissing callback if present for children reported
    // missing.
    //
    for (ple = m_DescriptionListHead.Flink;
         ple != &m_DescriptionListHead;
         ple = pNext) {
        pNext = ple->Flink;

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

        if (pEntry->m_ReportedMissingCallbackState == CallbackNeedsToBeInvoked) {
            (pEntry->m_Pdo->GetPdoPkg())->m_DeviceReportedMissing.Invoke(
                    pEntry->m_Pdo->GetHandle());

            pEntry->m_ReportedMissingCallbackState = CallbackInvoked;
        }
    }

    KeAcquireSpinLock(&m_ListLock, &irql);
    m_State = ListUnlocked;
    ProcessModificationsLocked(&freeHead);
    KeReleaseSpinLock(&m_ListLock, irql);

    DrainFreeListHead(&freeHead);
}

Referenced by FxPkgPnp::HandleQueryBusRelations().

IsScanCancelled()

BOOLEAN FxChildList::IsScanCancelled ( __in PULONG  ScanTag )

inline

Definition at line 205 of file fxchildlist.hpp.

    {
        return *ScanTag == ScanTagCancelled ? TRUE : FALSE;
    }

IsStaticList()

BOOLEAN FxChildList::IsStaticList ( VOID  )

inline

Definition at line 334 of file fxchildlist.hpp.

    {
        return m_StaticList;
    }

Referenced by MarkModificationNotPresentWorker().

MarkDescriptionNotPresentWorker()

VOID FxChildList::MarkDescriptionNotPresentWorker ( __inout FxDeviceDescriptionEntry *  DescriptionEntry, __in BOOLEAN  ModificationCanBeQueued  )

protected

Definition at line 1935 of file fxchildlist.cpp.

{
    BOOLEAN queueMod;

    ASSERT(DescriptionEntry->IsPresent());

    queueMod = FALSE;

    if (ModificationCanBeQueued) {
        if (IsListEmpty(&DescriptionEntry->m_ModificationLink)) {
            queueMod = TRUE;
        }
        else {
            //
            // If the modification is queued, it must be removal
            //
            ASSERT(DescriptionEntry->m_ModificationState ==
                                                      ModificationRemoveNotify);
            ASSERT(DescriptionEntry->m_FoundInLastScan == FALSE);
        }
    }
    else {
        queueMod = TRUE;
    }

    if (queueMod) {
        ASSERT(IsListEmpty(&DescriptionEntry->m_ModificationLink));
        ASSERT(DescriptionEntry->m_ModificationState == ModificationUnspecified);

        //
        // Add a removal modification entry into the modification list.
        // The ModificationRemoveNotify state will be converted into
        // ModificationRemove later while the list lock is still being held.
        //
        DescriptionEntry->m_ModificationState = ModificationRemoveNotify;
        DescriptionEntry->m_FoundInLastScan = FALSE;

        InsertTailList(&m_ModificationListHead,
                        &DescriptionEntry->m_ModificationLink);
    }
}

Referenced by CreateDevice(), EndScan(), MarkModificationNotPresentWorker(), NotifyDeviceSurpriseRemove(), UpdateAsMissing(), and UpdateDeviceAsMissing().

MarkModificationNotPresentWorker()

VOID FxChildList::MarkModificationNotPresentWorker ( __inout PLIST_ENTRY  FreeListHead, __inout FxDeviceDescriptionEntry *  ModificationEntry  )

protected

Definition at line 2003 of file fxchildlist.cpp.

{
    switch (ModificationEntry->m_ModificationState) {
    case ModificationInsert:
        //
        // This one was never reported to the OS. Remove it now.
        //
        RemoveEntryList(&ModificationEntry->m_ModificationLink);
        InitializeListHead(&ModificationEntry->m_ModificationLink);

        if (IsStaticList()) {
            //
            // There is a corner case of a static PDO being added and
            // immediately marked as missing before it has a chance to move to
            // description list. This case is handled here by marking the
            // modification state to ModificationNeedsPnpRemoval. Fx cannot just
            // delete the description because there is a driver-created PDO
            // associated with the description and it needs to be cleaned up.
            //
            ModificationEntry->m_ModificationState = ModificationNeedsPnpRemoval;
            ASSERT(ModificationEntry->m_DescriptionState == DescriptionUnspecified);
        }

        ASSERT(IsListEmpty(&ModificationEntry->m_DescriptionLink));
        InsertTailList(FreeListHead, &ModificationEntry->m_DescriptionLink);
        break;

    case ModificationClone:
        //
        // In between the PDOs stack asking for a reenumeration and applying
        // this change, the bus driver has reported the child as missing.
        // Convert the clone modification to a removal modification.
        //

        //
        // MarkDescriptionNotPresentWorker expects that m_ModificationEntry is
        // not in any list and points to itself.
        //
        RemoveEntryList(&ModificationEntry->m_ModificationLink);
        InitializeListHead(&ModificationEntry->m_ModificationLink);

        MarkDescriptionNotPresentWorker(ModificationEntry, FALSE);
        break;

    default:
        DO_NOTHING();
        break;
    }
}

Referenced by EndScan(), NotifyDeviceSurpriseRemove(), UpdateAsMissing(), and UpdateDeviceAsMissing().

NotifyDeviceRemove()

VOID FxChildList::NotifyDeviceRemove

(

__inout PLONG

ChildCount

)

Definition at line 3041 of file fxchildlist.cpp.

{
    PLIST_ENTRY pCur;
    LIST_ENTRY freeHead;
    FxDeviceDescriptionEntry* pEntry;
    KIRQL irql;

    DoTraceLevelMessage(GetDriverGlobals(), TRACE_LEVEL_INFORMATION, TRACINGPNP,
                        "WDFCHILDLIST %p:  removing children", GetHandle());

    InitializeListHead(&freeHead);
    pEntry = NULL;

    FxVerifierCheckIrqlLevel(GetDriverGlobals(), PASSIVE_LEVEL);

    //
    // Surprise remove handling covers the first stage of processing.  This will
    // process the modification list, esp the insert modifications which will
    // be cleaned up.
    //
    NotifyDeviceSurpriseRemove();

    KeAcquireSpinLock(&m_ListLock, &irql);

    ProcessModificationsLocked(&freeHead);

    m_State = ListLockedForParentRemove;

    for ( ; ; ) {

        //
        // Find the first child which was not surprise removed.  If surprise
        // removed and not yet removed, then there is an outstanding handle
        // which has not yet been closed.
        //
        for (pCur = m_DescriptionListHead.Flink;
             pCur != &m_DescriptionListHead;
             pCur = pCur->Flink) {

            pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(pCur);

            ASSERT(pEntry->m_DescriptionState == DescriptionReportedMissing);

            if (pEntry->m_ProcessingSurpriseRemove == FALSE) {
                break;
            }
        }

        //
        // If we are at the end of the list, we are done
        //
        if (pCur == &m_DescriptionListHead) {
            break;
        }

        DoTraceLevelMessage(GetDriverGlobals(), TRACE_LEVEL_INFORMATION, TRACINGPNP,
                            "Removing entry %p, WDFDEVICE %p, PDO %p",
                            pEntry, pEntry->m_Pdo->GetHandle(),
                            pEntry->m_Pdo->GetPhysicalDevice());

        ASSERT(pEntry->m_ModificationState == ModificationUnspecified);
        RemoveEntryList(&pEntry->m_DescriptionLink);
        InitializeListHead(&pEntry->m_DescriptionLink);

        KeReleaseSpinLock(&m_ListLock, irql);

        //
        // Go through FxPkgPdo to handle cleanup.  CleanupOrphanedDevice will
        // free this entry.
        //
        ASSERT(pEntry->m_Pdo != NULL);
        ASSERT(pEntry->m_PendingDeleteOnScanEnd == FALSE);

        pEntry->m_Pdo->SetParentWaitingOnRemoval();
        InterlockedIncrement(ChildCount);

        //
        // Start the child going away
        //
        pEntry->m_Pdo->m_PkgPnp->PnpProcessEvent(PnpEventParentRemoved);

        KeAcquireSpinLock(&m_ListLock, &irql);
    }

    m_State = ListUnlocked;
    ProcessModificationsLocked(&freeHead);

    KeReleaseSpinLock(&m_ListLock, irql);

    DrainFreeListHead(&freeHead);
}

Referenced by FxPkgPnp::ChildListNotifyRemove().

NotifyDeviceSurpriseRemove()

VOID FxChildList::NotifyDeviceSurpriseRemove

(

VOID

)

Definition at line 2954 of file fxchildlist.cpp.

{
    PLIST_ENTRY pCur, pNext;
    LIST_ENTRY freeHead;
    FxDeviceDescriptionEntry* pEntry;
    KIRQL irql;

    InitializeListHead(&freeHead);

    FxVerifierCheckIrqlLevel(GetDriverGlobals(), PASSIVE_LEVEL);

    KeAcquireSpinLock(&m_ListLock, &irql);

    //
    // Walk over all mod entries and remove any pending inserts. Note that
    // MarkModificationNotPresentWorker will add any such INSERTs found in the
    // mod list to the free list.
    //
    for (pCur = m_ModificationListHead.Flink;
         pCur != &m_ModificationListHead;
         pCur = pNext) {

        pNext = pCur->Flink;

        pEntry = FxDeviceDescriptionEntry::_FromModificationLink(pCur);

        if (pEntry->m_ModificationState == ModificationInsert) {
            MarkModificationNotPresentWorker(&freeHead, pEntry);
        }
    }

    //
    // Walk over all desc entries and remove them. Since
    // MarkDescriptionNotPresentWorker doesn't drain the mods,
    // we don't have to worry about any entries disappearing.
    //
    for (pCur = m_DescriptionListHead.Flink;
         pCur != &m_DescriptionListHead;
         pCur = pCur->Flink) {

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(pCur);

        if (pEntry->IsPresent()) {
            MarkDescriptionNotPresentWorker(pEntry, TRUE);
        }
    }

    //
    // Attempt to drain any mods we made.
    //
    ProcessModificationsLocked(&freeHead);

    //
    // Walk over all desc entries and advance them to missing.
    //
    for (pCur = m_DescriptionListHead.Flink;
         pCur != &m_DescriptionListHead;
         pCur = pCur->Flink) {

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(pCur);

        if (pEntry->m_DescriptionState == DescriptionNotPresent) {
            pEntry->m_DescriptionState = DescriptionReportedMissing;
        }
    }

    KeReleaseSpinLock(&m_ListLock, irql);

    DrainFreeListHead(&freeHead);
}

Referenced by NotifyDeviceRemove(), and FxPkgPnp::PnpEventSurpriseRemovePendingOverload().

PostParentToD0()

VOID FxChildList::PostParentToD0

(

VOID

)

Definition at line 2883 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pEntry;
    PLIST_ENTRY ple;
    KIRQL irql;

    KeAcquireSpinLock(&m_ListLock, &irql);
    for (ple = m_DescriptionListHead.Flink;
         ple != &m_DescriptionListHead;
         ple = ple->Flink) {

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

        if (pEntry->m_PendingDeleteOnScanEnd) {
            COVERAGE_TRAP();
            continue;
        }

        if (pEntry->m_Pdo != NULL) {
            pEntry->m_Pdo->m_PkgPnp->PowerProcessEvent(PowerParentToD0);
        }
    }
    KeReleaseSpinLock(&m_ListLock, irql);
}

ProcessBusRelations()

_Must_inspect_result_ NTSTATUS FxChildList::ProcessBusRelations

(

__inout PDEVICE_RELATIONS *

DeviceRelations

)

Definition at line 2414 of file fxchildlist.cpp.

{
    LIST_ENTRY freeHead;
    PLIST_ENTRY ple, pNext;
    FxDeviceDescriptionEntry* pEntry;
    PDEVICE_RELATIONS pPriorRelations, pNewRelations;
    PDEVICE_OBJECT pDevice;
    BOOLEAN needToReportMissingChildren, invalidateRelations, cleanupRelations;
    ULONG additionalCount, totalCount, i;
    size_t size;
    NTSTATUS status;
    KIRQL irql;
    PFX_DRIVER_GLOBALS pFxDriverGlobals;

    FxVerifierCheckIrqlLevel(GetDriverGlobals(), PASSIVE_LEVEL);

    pNewRelations = NULL;
    invalidateRelations = FALSE;
    cleanupRelations = TRUE;
    InitializeListHead(&freeHead);
    pFxDriverGlobals = GetDriverGlobals();

    //
    // Get the count of DO's we will need to add. While we're at it, free any
    // extensions that never got a chance for a DO, and note extensions that
    // will need to wait for a remove IRP.
    //
    KeAcquireSpinLock(&m_ListLock, &irql);

    m_State = ListLockedForEnum;

    additionalCount = 0;
    needToReportMissingChildren = FALSE;

    for (ple = m_DescriptionListHead.Flink;
         ple != &m_DescriptionListHead;
         ple = ple->Flink) {

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

        switch (pEntry->m_DescriptionState) {

        case DescriptionPresentNeedsInstantiation:
        case DescriptionInstantiatedHasObject:
            //
            // We'll be needing a DO here.
            //
            additionalCount++;
            break;

        case DescriptionNotPresent:
            //
            // We will now report the description as missing
            //
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP,
                "PDO WDFDEVICE %p !devobj %p in a not present state, need to "
                "report as missing",
                pEntry->m_Pdo->GetHandle(), pEntry->m_Pdo->GetDeviceObject());

            needToReportMissingChildren = TRUE;
            break;

        case DescriptionReportedMissing:
            //
            // Already reported missing in a previous handling of QDR
            //
            break;

        default:
            ASSERTMSG("Invalid description state\n", FALSE);
            break;
        }
    }

    KeReleaseSpinLock(&m_ListLock, irql);

    pPriorRelations = *DeviceRelations;

    //
    // If we have
    // 1)  no devices in the list AND
    //   a) we have nothing to report OR
    //   b) we have something to report and there are previous relations (which
    //      if left unchanged will be used to report our missing devices)
    //
    // THEN nothing else to do except marking the NotPresent children as
    // missing, unlock the list and return the special return
    // code STATUS_NOT_SUPPORTED indicating this condition.
    //
    if (additionalCount == 0 &&
        (needToReportMissingChildren == FALSE || pPriorRelations != NULL)) {
        //
        // We have nothing to add, nor subtract from prior allocations. Note
        // the careful logic with counting missing children - the OS does not
        // treat no list and an empty list identically. As such we must be
        // sure to return some kind of list in the case where we reported
        // something previously.
        //
        // Mark the NotPresent children as Missing
        // We can walk the ChildList without holding the spinlock because we set
        // m_State to ListLockedForEnum.
        //
        if (needToReportMissingChildren) {
            for (ple = m_DescriptionListHead.Flink;
                 ple != &m_DescriptionListHead;
                 ple = pNext) {
                pNext = ple->Flink;

                pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

                if (pEntry->m_DescriptionState == DescriptionNotPresent) {
                    //
                    // We will now report the description as missing
                    //
                    DoTraceLevelMessage(
                        pFxDriverGlobals, TRACE_LEVEL_INFORMATION, TRACINGPNP,
                        "PDO WDFDEVICE %p !devobj %p reported as missing to pnp",
                        pEntry->m_Pdo->GetHandle(), pEntry->m_Pdo->GetDeviceObject());

                    pEntry->m_DescriptionState = DescriptionReportedMissing;
                    pEntry->m_ReportedMissingCallbackState = CallbackNeedsToBeInvoked;
                }
            }
        }
        else {
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP,
                "Nothing to report on WDFCHILDLIST %p, returning early", GetHandle());
        }

        cleanupRelations = FALSE;
        status = STATUS_NOT_SUPPORTED;
        goto Done;
    }

    //
    // Adjust the count for any existing relations.
    //
    totalCount = additionalCount;
    if (pPriorRelations != NULL) {
        totalCount += pPriorRelations->Count;
    }

    size = _ComputeRelationsSize(totalCount);

    pNewRelations = (PDEVICE_RELATIONS)
        ExAllocatePoolWithTag(PagedPool, size, pFxDriverGlobals->Tag);

    if (pNewRelations == NULL) {
        //
        // We can't add our information.
        //
        DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                            "Could not allocate relations for %d devices",
                            totalCount);

        //
        // Just like above, STATUS_NOT_SUPPORTED is a special value indicating
        // to the caller that the QDR has not been handled and that the caller
        // should not change the status or the existing relations in the irp.
        //
        cleanupRelations = FALSE;
        status = STATUS_NOT_SUPPORTED;

        m_EnumRetries++;
        if (m_EnumRetries <= FX_CHILD_LIST_MAX_RETRIES) {
            invalidateRelations = TRUE;
        }
        else {
            if (needToReportMissingChildren) {
                DoTraceLevelMessage(
                    pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                    "WDFCHILDLIST %p could not allocate relations required for "
                    "reporting children as missing after max retries",
                    GetHandle());
            }

            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                "WDFCHILDLIST %p retried %d times to report relations, but "
                "failed each time", GetHandle(), FX_CHILD_LIST_MAX_RETRIES);
        }

        if (pPriorRelations == NULL) {
            //
            // If the prior relations are NULL we can just return failure and
            // not affect anyone else's state that had previous thought they
            // committed a relations structure back to pnp (which we tried to
            // update but could not b/c of no memory).
            //
            // By returning failure that is != STATUS_NOT_SUPPORTED, the pnp
            // manager will not process a change in the relations.
            //
            status = STATUS_INSUFFICIENT_RESOURCES;
        }
        else {
            //
            // Do *not* throw away the old list and return error because that
            // will put the driver which created the existing relations into an
            // inconsistent state with respect to the pnp manager state if we
            // fail it here and the pnp manager never seeds the changes.
            //
            // Instead, we must process the failure locally and mark each object
            // which is already reported as present as missing.
            //
            for (ple = m_DescriptionListHead.Flink;
                 ple != &m_DescriptionListHead;
                 ple = pNext) {

                pNext = ple->Flink;
                pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

                switch (pEntry->m_DescriptionState) {
                case DescriptionPresentNeedsInstantiation:
                    //
                    // This description can stay in this state b/c we will just
                    // ask for another QDR.
                    //
                    break;

                case DescriptionInstantiatedHasObject:
                    DoTraceLevelMessage(
                        pFxDriverGlobals, TRACE_LEVEL_INFORMATION, TRACINGPNP,
                        "PDO WDFDEVICE %p !devobj %p being marked as missing "
                        "because of failure to allocate device relations and "
                        "an already existing relations %p",
                        pEntry->m_Pdo->GetHandle(),
                        pEntry->m_Pdo->GetDeviceObject(), pPriorRelations);

                    KeAcquireSpinLock(&m_ListLock, &irql);
                    if (m_StaticList == FALSE) {
                        if (ReenumerateEntryLocked(pEntry, TRUE)) {
                            DoTraceLevelMessage(
                                pFxDriverGlobals,
                                TRACE_LEVEL_INFORMATION, TRACINGPNP,
                                "PDO WDFDEVICE %p !devobj %p being cloned "
                                "because of the failure to allocate device "
                                "relations",
                                pEntry->m_Pdo->GetHandle(),
                                pEntry->m_Pdo->GetDeviceObject());

                            (void) CloneEntryLocked(&freeHead, pEntry, TRUE);
                        }
                    }
                    else {
                        DoTraceLevelMessage(
                            pFxDriverGlobals,
                            TRACE_LEVEL_WARNING, TRACINGPNP,
                            "PDO WDFDEVICE %p !devobj %p is a statically "
                            "enumerated PDO therefore can not be cloned and is "
                            "being marked missing because of failure to "
                            "allocate device relations. It will be surprise "
                            "removed by pnp manager. Bus driver may continue "
                            "to function normally but will lose this child PDO",
                            pEntry->m_Pdo->GetHandle(),
                            pEntry->m_Pdo->GetDeviceObject());
                    }
                    pEntry->m_DescriptionState = DescriptionReportedMissing;
                    pEntry->m_ReportedMissingCallbackState = CallbackNeedsToBeInvoked;
                    KeReleaseSpinLock(&m_ListLock, irql);
                    break;

                case DescriptionNotPresent:
                    //
                    // We will now report the description as missing
                    //
                    DoTraceLevelMessage(
                        pFxDriverGlobals, TRACE_LEVEL_INFORMATION, TRACINGPNP,
                        "PDO WDFDEVICE %p !devobj %p reported as missing to pnp "
                        "(by using existing relations)",
                        pEntry->m_Pdo->GetHandle(),
                        pEntry->m_Pdo->GetDeviceObject());

                    pEntry->m_DescriptionState = DescriptionReportedMissing;
                    pEntry->m_ReportedMissingCallbackState = CallbackNeedsToBeInvoked;
                    break;
                }
            }
        }

        goto Done;
    }

    RtlZeroMemory(pNewRelations, size);

    if (pPriorRelations != NULL && pPriorRelations->Count > 0) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP,
            "WDFCHILDLIST %p prior relations %p contained %d objects",
            GetHandle(), pPriorRelations, pPriorRelations->Count
            );

        RtlCopyMemory(pNewRelations,
                      pPriorRelations,
                      _ComputeRelationsSize(pPriorRelations->Count));
    }

    //
    // We can walk the ChildList without holding the spinlock because we set
    // m_State to ListLockedForEnum.
    //
    status = STATUS_SUCCESS;

    for (ple = m_DescriptionListHead.Flink;
         ple != &m_DescriptionListHead;
         ple = pNext) {
        pNext = ple->Flink;

        pEntry = FxDeviceDescriptionEntry::_FromDescriptionLink(ple);

        switch (pEntry->m_DescriptionState) {
        case DescriptionPresentNeedsInstantiation:
            //
            // This extension needs a device handle. Create one now.
            //
            DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP,
                                "Creating PDO device object from reported device");
            if (CreateDevice(pEntry, &invalidateRelations) == FALSE) {
                break;
            }

            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_INFORMATION, TRACINGPNP,
                "PDO created successfully, WDFDEVICE %p !devobj %p",
                pEntry->m_Pdo->GetHandle(), pEntry->m_Pdo->GetDeviceObject());

            // || || Fall through || ||
            // \/ \/              \/ \/
        case DescriptionInstantiatedHasObject:

            DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP,
                                "Reporting PDO WDFDEVICE %p !devobj %p",
                                pEntry->m_Pdo->GetHandle(),
                                pEntry->m_Pdo->GetDeviceObject());

            pDevice = pEntry->m_Pdo->GetDeviceObject();
            ObReferenceObject(pDevice);
            pNewRelations->Objects[pNewRelations->Count] = pDevice;
            pNewRelations->Count++;
            break;

        case DescriptionNotPresent:
            //
            // We will now report the description as missing
            //
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_INFORMATION, TRACINGPNP,
                "PDO WDFDEVICE %p !devobj %p reported as missing to pnp",
                pEntry->m_Pdo->GetHandle(), pEntry->m_Pdo->GetDeviceObject());

            pEntry->m_DescriptionState = DescriptionReportedMissing;
            pEntry->m_ReportedMissingCallbackState = CallbackNeedsToBeInvoked;

            break;

        case DescriptionReportedMissing:
            break;

        default:
            ASSERTMSG("Invalid description state\n", FALSE);
            break;
        }
    }

Done:
    KeAcquireSpinLock(&m_ListLock, &irql);

    //
    // Make sure that the description we just dequeued is not on the modification
    // list.
    //
    m_State = ListUnlocked;
    ProcessModificationsLocked(&freeHead);

    if (NT_SUCCESS(status)) {
        m_EnumRetries = 0;
    }

    KeReleaseSpinLock(&m_ListLock, irql);

    if (invalidateRelations) {
        //
        // We failed for some reason or other. Queue up a new attempt.
        //
        // NOTE:  no need to check m_Device->m_KnownPdo here
        //        because we are in the middle of a QDR for m_Device which means
        //        that it, or its stack, is already known to PnP.
        //
        IoInvalidateDeviceRelations(m_Device->GetPhysicalDevice(), BusRelations);
    }

    DrainFreeListHead(&freeHead);

    if (cleanupRelations) {
        if (pPriorRelations != NULL) {
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP,
                "Freeing prior relations %p", pPriorRelations);

            ExFreePool(pPriorRelations);
            pPriorRelations = NULL;
        }

        if (!NT_SUCCESS(status) && pNewRelations != NULL) {
            for(i = 0; i < pNewRelations->Count; i++) {
                ObDereferenceObject(pNewRelations->Objects[i]);
            }

            ExFreePool(pNewRelations);
            pNewRelations = NULL;
        }

        *DeviceRelations = pNewRelations;
    }

    return status;
}

Referenced by FxPkgPnp::HandleQueryBusRelations().

ProcessModificationsLocked()

VOID FxChildList::ProcessModificationsLocked ( __inout PLIST_ENTRY  FreeListHead )

protected

Definition at line 1755 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry *pEntry;
    PLIST_ENTRY pCur, pNext;
    BOOLEAN invalidateRelations;

    //
    // If the list is locked or there are still active scans, we must not process
    // any modifications.
    //
    if (m_State != ListUnlocked || m_ScanCount > 0) {
        DoTraceLevelMessage(
            GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
            "Not processing modifications on WDFCHILDLIST %p (list state %d, "
            "scan count %d)", GetObjectHandle(), m_State, m_ScanCount);
        return;
    }

    DoTraceLevelMessage(
        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
        "Begin processing modifications on WDFCHILDLIST %p", GetObjectHandle());

    //
    // First do the mod updates. As quick as possible. Note that we need to
    // update
    //
    for (pCur = m_ModificationListHead.Flink;
         pCur != &m_ModificationListHead;
         pCur = pNext) {

        pNext = pCur->Flink;

        pEntry = FxDeviceDescriptionEntry::_FromModificationLink(pCur);

        switch (pEntry->m_ModificationState) {
        case ModificationRemoveNotify:















            pEntry->m_ModificationState = ModificationRemove;
            break;

        default:
            break;
        }
    }

    invalidateRelations = FALSE;
    while(!IsListEmpty(&m_ModificationListHead)) {
        pCur = RemoveHeadList(&m_ModificationListHead);

        InitializeListHead(pCur);
        pEntry = FxDeviceDescriptionEntry::_FromModificationLink(pCur);

        ASSERT(pEntry->m_ModificationState == ModificationInsert ||
                  pEntry->m_ModificationState == ModificationClone ||
                  pEntry->m_ModificationState == ModificationRemove);

        DoTraceLevelMessage(
            GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
            "entry %p, mod state is %!FxChildListModificationState!",
            pEntry, pEntry->m_ModificationState);

        switch (pEntry->m_ModificationState) {
        case ModificationRemove:
            //
            // Remove's are stacked on top of the entry they need to take out.
            //
            ASSERT(pEntry->IsPresent());

            pEntry->m_ModificationState = ModificationUnspecified;

            DoTraceLevelMessage(
                GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                "processing remove on entry %p, description state is "
                "%!FxChildListDescriptionState!",
                pEntry, pEntry->m_DescriptionState);

            switch (pEntry->m_DescriptionState) {
            case DescriptionPresentNeedsInstantiation:
                //
                // We got to the entry before a DO could be created for it or
                // an instantiation failed.  If deleeted before creation, the
                // list entry points to itself.  If the instantiation failed,
                // the list entry is in the description list and must be
                // removed from it.
                //
                // Mark it for deletion now (outside of the lock being held).
                //
                DoTraceLevelMessage(
                    GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                    "entry %p never reported to pnp, mark for deletion", pEntry);

                RemoveEntryList(&pEntry->m_DescriptionLink);
                InsertTailList(FreeListHead, &pEntry->m_DescriptionLink);
                break;

            case DescriptionInstantiatedHasObject:
                DoTraceLevelMessage(
                    GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                    "committing PDO WDFDEVICE %p, !devobj %p as not present",
                    pEntry->m_Pdo->GetHandle(), pEntry->m_Pdo->GetDeviceObject());

                pEntry->m_DescriptionState = DescriptionNotPresent;
                invalidateRelations = TRUE;
                break;

            default:
                ASSERTMSG("Invalid description state\n", FALSE);
                break;
            }

            break;

        case ModificationInsert:
            //
            // CurEntry is our entry to insert into the list. We simply "move"
            // the mod entries to desc entries.
            //
            ASSERT(pEntry->m_DescriptionState == DescriptionUnspecified);
            pEntry->m_DescriptionState = DescriptionPresentNeedsInstantiation;

            DoTraceLevelMessage(
                GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
                "marking entry %p as needing instantiation", pEntry);

            InsertTailList(&m_DescriptionListHead, &pEntry->m_DescriptionLink);
            pEntry->m_ModificationState = ModificationUnspecified;
            invalidateRelations = TRUE;
            break;

        case ModificationClone:
            invalidateRelations = CloneEntryLocked(FreeListHead, pEntry, FALSE);
            break;

        default:
            ASSERTMSG("Invalid description modification state\n", FALSE);
            break;
        }
    }

    if (invalidateRelations) {
        PDEVICE_OBJECT pdo;

        if (m_ScanCount) {
            m_InvalidationNeeded = TRUE;
        }
        else if ((pdo = m_Device->GetSafePhysicalDevice()) != NULL) {
            //
            // See previous usage of m_Device->m_KnownPdo for
            // comments on why a lock is not necessary when reading its value.
            //
            m_InvalidationNeeded = FALSE;
            IoInvalidateDeviceRelations(pdo, BusRelations);
        }
        else {
            m_InvalidationNeeded = TRUE;
        }
    }

    DoTraceLevelMessage(
        GetDriverGlobals(), TRACE_LEVEL_VERBOSE, TRACINGPNP,
       "end processing modifications on WDFCHILDLIST %p", GetObjectHandle());
}