#include <fxchildlist.hpp>

Inheritance diagram for FxDeviceDescriptionEntry:

Collaboration diagram for FxDeviceDescriptionEntry:

[legend]

Public Member Functions
	FxDeviceDescriptionEntry (__inout FxChildList *DeviceList, __in ULONG AddressDescriptionSize, __in ULONG IdentificationDescriptionSize)

	~FxDeviceDescriptionEntry ()

_Must_inspect_result_ PVOID	operator new (__in size_t AllocatorBlock, __in PFX_DRIVER_GLOBALS DriverGlobals, __in size_t TotalDescriptionSize)

FxChildList *	GetParentList (VOID)

PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER	GetId (VOID)

BOOLEAN	IsDeviceReportedMissing (VOID)

BOOLEAN	IsDeviceRemoved (VOID)

VOID	ProcessDeviceRemoved (VOID)

VOID	DeviceSurpriseRemoved (VOID)

_Must_inspect_result_ FxDeviceDescriptionEntry *	Clone (__inout PLIST_ENTRY FreeListHead)

BOOLEAN	MatchStateToFlags (__in ULONG Flags)

Public Member Functions inherited from FxStump
PVOID	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)

PVOID	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in POOL_TYPE PoolType)

VOID	operator delete (__in PVOID pointer)

PVOID	operator new[] (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)

VOID	operator delete[] (__in PVOID pointer)

Protected Member Functions
BOOLEAN __inline	IsPresent (VOID)

Protected Member Functions inherited from FxStump
	FxStump (VOID)

Static Protected Member Functions
static FxDeviceDescriptionEntry *	_FromDescriptionLink (__in PLIST_ENTRY Link)

static FxDeviceDescriptionEntry *	_FromModificationLink (__in PLIST_ENTRY Link)

Friends
class	FxDevice

class	FxChildList

Detailed Description

Definition at line 666 of file fxchildlist.hpp.

Constructor & Destructor Documentation

◆ FxDeviceDescriptionEntry()

FxDeviceDescriptionEntry::FxDeviceDescriptionEntry	(	__inout FxChildList *	DeviceList,
		__in ULONG	AddressDescriptionSize,
		__in ULONG	IdentificationDescriptionSize
	)

Definition at line 31 of file fxchildlist.cpp.

{
    m_IdentificationDescription =
        (PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER) WDF_PTR_ADD_OFFSET(
        this, WDF_ALIGN_SIZE_UP(sizeof(*this), sizeof(PVOID)));
 
    m_IdentificationDescription->IdentificationDescriptionSize =
        AddressDescriptionSize;
 
    if (IdentificationDescriptionSize > 0) {
        m_AddressDescription =
            (PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER) WDF_PTR_ADD_OFFSET(
                m_IdentificationDescription,
                WDF_ALIGN_SIZE_UP(AddressDescriptionSize, sizeof(PVOID)));
 
        m_AddressDescription->AddressDescriptionSize =
            IdentificationDescriptionSize;
    }
 
    InitializeListHead(&m_DescriptionLink);
    InitializeListHead(&m_ModificationLink);
 
    m_ModificationState = ModificationInsert;
 
    m_DeviceList = DeviceList;
 
    m_FoundInLastScan = FALSE;
    m_ProcessingSurpriseRemove = FALSE;
    m_PendingDeleteOnScanEnd = FALSE;
 
    //
    // The parent DO can go away while the child still exists (stuck in a
    // suprise remove state w/an open handle).  As such, when the parent is
    // destroyed, it will release its reference on the FxChildList.  Each
    // description will have its own reference to the list to keep the list
    // alive as long as the child DO exists.
    //
    m_DeviceList->ADDREF(this);
}

◆ ~FxDeviceDescriptionEntry()

FxDeviceDescriptionEntry::~FxDeviceDescriptionEntry ( )

Definition at line 75 of file fxchildlist.cpp.

{
    m_DeviceList->RELEASE(this);
}

Member Function Documentation

◆ _FromDescriptionLink()

static FxDeviceDescriptionEntry * FxDeviceDescriptionEntry::_FromDescriptionLink ( __in PLIST_ENTRY Link )

inlinestaticprotected

Definition at line 770 of file fxchildlist.hpp.

    {
        return CONTAINING_RECORD(Link,
                                 FxDeviceDescriptionEntry,
                                 m_DescriptionLink);
    }

Referenced by FxChildList::BeginScan(), FxChildList::DrainFreeListHead(), FxChildList::EndScan(), FxChildList::GetNextDevice(), FxChildList::GetNextStaticDevice(), FxChildList::IndicateWakeStatus(), FxChildList::InvokeReportedMissingCallback(), FxChildList::NotifyDeviceRemove(), FxChildList::NotifyDeviceSurpriseRemove(), FxChildList::PostParentToD0(), FxChildList::ProcessBusRelations(), FxChildList::SearchBackwardsForMatchingDescriptionLocked(), FxChildList::UpdateAllAsPresent(), and FxChildList::UpdateDeviceAsMissing().

◆ _FromModificationLink()

static FxDeviceDescriptionEntry * FxDeviceDescriptionEntry::_FromModificationLink ( __in PLIST_ENTRY Link )

inlinestaticprotected

Definition at line 781 of file fxchildlist.hpp.

    {
        return CONTAINING_RECORD(Link,
                                 FxDeviceDescriptionEntry,
                                 m_ModificationLink);
    }

Referenced by FxChildList::BeginScan(), FxChildList::EndScan(), FxChildList::GetNextDevice(), FxChildList::GetNextStaticDevice(), FxChildList::NotifyDeviceSurpriseRemove(), FxChildList::ProcessModificationsLocked(), FxChildList::SearchBackwardsForMatchingModificationLocked(), FxChildList::UpdateAllAsPresent(), and FxChildList::UpdateDeviceAsMissing().

◆ Clone()

_Must_inspect_result_ FxDeviceDescriptionEntry * FxDeviceDescriptionEntry::Clone ( __inout PLIST_ENTRY FreeListHead )

Definition at line 259 of file fxchildlist.cpp.

{
    FxDeviceDescriptionEntry* pNewEntry;
    NTSTATUS status;
 
    pNewEntry = new(m_DeviceList->GetDriverGlobals(),
                    m_DeviceList->m_TotalDescriptionSize)
        FxDeviceDescriptionEntry(m_DeviceList,
                                 m_DeviceList->m_IdentificationDescriptionSize,
                                 m_DeviceList->m_AddressDescriptionSize);
 
    if (pNewEntry == NULL) {
        return NULL;
    }
 
    status = m_DeviceList->DuplicateId(pNewEntry->m_IdentificationDescription,
                                       m_IdentificationDescription);
 
    if (NT_SUCCESS(status) && m_DeviceList->HasAddressDescriptions()) {
        status = m_DeviceList->DuplicateAddress(pNewEntry->m_AddressDescription,
                                                m_AddressDescription);
    }
 
    if (NT_SUCCESS(status)) {
        pNewEntry->m_FoundInLastScan = TRUE;
    }
    else {
        //
        // Free it later
        //
        InsertTailList(FreeListHead, &pNewEntry->m_DescriptionLink);
        pNewEntry = NULL;
    }
 
    return pNewEntry;
}

◆ DeviceSurpriseRemoved()

VOID FxDeviceDescriptionEntry::DeviceSurpriseRemoved ( VOID )

Definition at line 102 of file fxchildlist.cpp.

{
    KIRQL irql;
 
    KeAcquireSpinLock(&m_DeviceList->m_ListLock, &irql);
    m_ProcessingSurpriseRemove = TRUE;
    KeReleaseSpinLock(&m_DeviceList->m_ListLock, irql);
}

Referenced by FxPkgPdo::_PnpSurpriseRemoval(), and FxPkgPdo::PnpEventSurpriseRemovePendingOverload().

◆ GetId()

PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FxDeviceDescriptionEntry::GetId ( VOID )

inline

Definition at line 697 of file fxchildlist.hpp.

    {
        return m_IdentificationDescription;
    }

Referenced by FxPkgPdo::PnpEventEjectHardwareOverload().

◆ GetParentList()

FxChildList * FxDeviceDescriptionEntry::GetParentList ( VOID )

inline

Definition at line 688 of file fxchildlist.hpp.

    {
        return m_DeviceList;
    }

Referenced by FxPkgPdo::AskParentToRemoveAndReenumerate(), FxPkgPdo::Initialize(), IsDeviceRemoved(), FxPkgPdo::PnpEventEjectHardwareOverload(), and ProcessDeviceRemoved().

◆ IsDeviceRemoved()

BOOLEAN FxDeviceDescriptionEntry::IsDeviceRemoved ( VOID )

Definition at line 148 of file fxchildlist.cpp.

{
    KIRQL irql;
    BOOLEAN removed;
    FxChildList* pList;
 
    pList = GetParentList();
    removed = FALSE;
    FxVerifierCheckIrqlLevel(m_DeviceList->GetDriverGlobals(), PASSIVE_LEVEL);
 
    KeAcquireSpinLock(&m_DeviceList->m_ListLock, &irql);
 
    m_ProcessingSurpriseRemove = FALSE;
 
    if (m_DescriptionState == DescriptionReportedMissing) {
        //
        // We should delete this entry as it was reported missing.
        //
        ASSERT(m_ModificationState == ModificationUnspecified);
 
        m_DescriptionState = DescriptionUnspecified;
 
        //
        // Remove from the current list if no scan going on.
        // Note that the description entry can't be removed from list if scan
        // count is > 0 because it might be part of an iterator that driver is
        // still using to iterate thru the child list.
        //
        if (pList->GetScanCount() == 0) {
            //
            // Remove from the current list
            //
            RemoveEntryList(&m_DescriptionLink);
            InitializeListHead(&m_DescriptionLink);
        }
        else {
            //
            // The entry will be removed and deleted when scan count goes to
            // zero by the scanning thread, so make sure pdo deosn't reference
            // the entry any more.
            //
            m_PendingDeleteOnScanEnd = TRUE;
            if (m_Pdo != NULL) {
                m_Pdo->GetPdoPkg()->m_Description = NULL;
            }
        }
 
        removed = TRUE;
 
        //
        // No need to add a reference to m_DeviceList becuase as we hold a
        // reference to it already.  This reference is bound by the lifetime
        // of this object, so we can always safely touch m_DeviceList even if
        // the FDO is gone before the child is removed.
        //
    }
 
    KeReleaseSpinLock(&m_DeviceList->m_ListLock, irql);
 
    return removed;
}

Referenced by FxPkgPdo::PnpEventCheckForDevicePresenceOverload().

◆ IsDeviceReportedMissing()

BOOLEAN FxDeviceDescriptionEntry::IsDeviceReportedMissing ( VOID )

Definition at line 114 of file fxchildlist.cpp.

{
    KIRQL irql;
    BOOLEAN result;
 
    KeAcquireSpinLock(&m_DeviceList->m_ListLock, &irql);
    if (m_DescriptionState == DescriptionReportedMissing) {
        result = TRUE;
    }
    else {
        result = FALSE;
    }
    KeReleaseSpinLock(&m_DeviceList->m_ListLock, irql);
 
    return result;
}

Referenced by FxPkgPdo::DeleteSymbolicLinkOverload().

◆ IsPresent()

BOOLEAN __inline FxDeviceDescriptionEntry::IsPresent ( VOID )

inlineprotected

Definition at line 755 of file fxchildlist.hpp.

    {
        if (m_DescriptionState == DescriptionPresentNeedsInstantiation ||
            m_DescriptionState == DescriptionInstantiatedHasObject) {
            return TRUE;
        }
        else {
            return FALSE;
        }
    }

◆ MatchStateToFlags()

BOOLEAN FxDeviceDescriptionEntry::MatchStateToFlags ( __in ULONG Flags )

inline

Definition at line 731 of file fxchildlist.hpp.

    {
        if (((Flags & WdfRetrievePresentChildren) &&
                        m_DescriptionState == DescriptionInstantiatedHasObject)
            ||
            ((Flags & WdfRetrieveMissingChildren) &&
                       (m_DescriptionState == DescriptionReportedMissing ||
                        m_DescriptionState == DescriptionNotPresent))
            ||
            ((Flags & WdfRetrievePendingChildren) &&
                    m_DescriptionState == DescriptionPresentNeedsInstantiation)
            ) {
 
            return TRUE;
        }
 
        return FALSE;
    }

◆ operator new()

_Must_inspect_result_ PVOID FxDeviceDescriptionEntry::operator new	(	__in size_t	AllocatorBlock,
		__in PFX_DRIVER_GLOBALS	DriverGlobals,
		__in size_t	TotalDescriptionSize
	)

Definition at line 82 of file fxchildlist.cpp.

{
    PVOID p;
 
    UNREFERENCED_PARAMETER(AllocatorBlock);
 
    p = FxPoolAllocate(FxDriverGlobals, NonPagedPool, TotalDescriptionSize);
 
    if (p != NULL) {
        RtlZeroMemory(p, TotalDescriptionSize);
    }
 
    return p;
}

◆ ProcessDeviceRemoved()

VOID FxDeviceDescriptionEntry::ProcessDeviceRemoved ( VOID )

Definition at line 213 of file fxchildlist.cpp.

{
    LIST_ENTRY freeHead;
    KIRQL irql;
    FxChildList* pList;
 
    FxVerifierCheckIrqlLevel(m_DeviceList->GetDriverGlobals(), PASSIVE_LEVEL);
 
    pList = GetParentList();
    InitializeListHead(&freeHead);
    KeAcquireSpinLock(&m_DeviceList->m_ListLock, &irql);
 
    //
    // Remove from the current list. In some cases the entry may not be in any
    // list in which case RemoveEntryList() will be a noop.
    // Note that the description entry can't be removed from list if scan count
    // is > 0 because it might be part of an iterator that driver is still using
    // to iterate thru the child list.
    //
    if (pList->GetScanCount() == 0 || IsListEmpty(&m_DescriptionLink)) {
        RemoveEntryList(&m_DescriptionLink);
 
        //
        // Instead of reimplementing a single description cleanup, just use the
        // version which cleans up a list.
        //
        InsertTailList(&freeHead, &m_DescriptionLink);
    }
    else {
        //
        // The entry will be removed when scan count goes to zero.
        //
        ASSERT(m_ModificationState == ModificationUnspecified &&
                m_DescriptionState == DescriptionUnspecified);
        m_PendingDeleteOnScanEnd = TRUE;
    }
 
    KeReleaseSpinLock(&m_DeviceList->m_ListLock, irql);
 
    m_DeviceList->DrainFreeListHead(&freeHead);
}

Referenced by FxPkgPdo::PnpEventPdoRemovedOverload().

Friends And Related Function Documentation

◆ FxChildList

friend class FxChildList

friend

Definition at line 668 of file fxchildlist.hpp.

◆ FxDevice

friend class FxDevice

friend

Definition at line 667 of file fxchildlist.hpp.

Member Data Documentation

◆ m_AddressDescription

PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER FxDeviceDescriptionEntry::m_AddressDescription

protected

Definition at line 797 of file fxchildlist.hpp.

Referenced by Clone(), FxChildList::CloneEntryLocked(), and FxDeviceDescriptionEntry().

◆ m_DescriptionLink

LIST_ENTRY FxDeviceDescriptionEntry::m_DescriptionLink

protected

Definition at line 791 of file fxchildlist.hpp.

Referenced by _FromDescriptionLink(), Clone(), FxChildList::CloneEntryLocked(), FxDeviceDescriptionEntry(), IsDeviceRemoved(), and ProcessDeviceRemoved().

◆ m_DescriptionState

FxChildListDescriptionState FxDeviceDescriptionEntry::m_DescriptionState

protected

Definition at line 793 of file fxchildlist.hpp.

Referenced by FxChildList::CloneEntryLocked(), IsDeviceRemoved(), IsDeviceReportedMissing(), IsPresent(), MatchStateToFlags(), and ProcessDeviceRemoved().

◆ m_DeviceList

FxChildList* FxDeviceDescriptionEntry::m_DeviceList

protected

Definition at line 805 of file fxchildlist.hpp.

Referenced by Clone(), DeviceSurpriseRemoved(), FxDeviceDescriptionEntry(), GetParentList(), IsDeviceRemoved(), IsDeviceReportedMissing(), ProcessDeviceRemoved(), and ~FxDeviceDescriptionEntry().

◆ m_FoundInLastScan

BOOLEAN FxDeviceDescriptionEntry::m_FoundInLastScan

protected

Definition at line 807 of file fxchildlist.hpp.

Referenced by Clone(), and FxDeviceDescriptionEntry().

◆ m_IdentificationDescription

PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FxDeviceDescriptionEntry::m_IdentificationDescription

protected

Definition at line 795 of file fxchildlist.hpp.

Referenced by Clone(), FxDeviceDescriptionEntry(), and GetId().

◆ m_ModificationLink

LIST_ENTRY FxDeviceDescriptionEntry::m_ModificationLink

protected

Definition at line 799 of file fxchildlist.hpp.

Referenced by _FromModificationLink(), and FxDeviceDescriptionEntry().

◆ m_ModificationState

FxChildListModificationState FxDeviceDescriptionEntry::m_ModificationState

protected

Definition at line 801 of file fxchildlist.hpp.

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

◆ m_Pdo

CfxDevice* FxDeviceDescriptionEntry::m_Pdo

protected

Definition at line 803 of file fxchildlist.hpp.

Referenced by IsDeviceRemoved().

◆ m_PendingDeleteOnScanEnd

BOOLEAN FxDeviceDescriptionEntry::m_PendingDeleteOnScanEnd

protected

Definition at line 811 of file fxchildlist.hpp.

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

◆ m_ProcessingSurpriseRemove

BOOLEAN FxDeviceDescriptionEntry::m_ProcessingSurpriseRemove

protected

Definition at line 809 of file fxchildlist.hpp.

Referenced by DeviceSurpriseRemoved(), FxDeviceDescriptionEntry(), and IsDeviceRemoved().

◆ m_ReportedMissingCallbackState

FxChildListReportedMissingCallbackState FxDeviceDescriptionEntry::m_ReportedMissingCallbackState

protected

Definition at line 813 of file fxchildlist.hpp.

The documentation for this struct was generated from the following files:

sdk/lib/drivers/wdf/shared/inc/private/common/fxchildlist.hpp
sdk/lib/drivers/wdf/kmdf/src/core/fxchildlist.cpp
sdk/lib/drivers/wdf/shared/irphandlers/pnp/um/fxchildlistum.cpp

Protected Attributes
LIST_ENTRY	m_DescriptionLink

FxChildListDescriptionState	m_DescriptionState

PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER	m_IdentificationDescription

PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER	m_AddressDescription

LIST_ENTRY	m_ModificationLink

FxChildListModificationState	m_ModificationState

CfxDevice *	m_Pdo

FxChildList *	m_DeviceList

BOOLEAN	m_FoundInLastScan

BOOLEAN	m_ProcessingSurpriseRemove

BOOLEAN	m_PendingDeleteOnScanEnd

FxChildListReportedMissingCallbackState	m_ReportedMissingCallbackState

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ FxDeviceDescriptionEntry()

◆ ~FxDeviceDescriptionEntry()

Member Function Documentation

◆ _FromDescriptionLink()

◆ _FromModificationLink()

◆ Clone()

◆ DeviceSurpriseRemoved()

◆ GetId()

◆ GetParentList()

◆ IsDeviceRemoved()

◆ IsDeviceReportedMissing()

◆ IsPresent()

◆ MatchStateToFlags()

◆ operator new()

◆ ProcessDeviceRemoved()

Friends And Related Function Documentation

◆ FxChildList

◆ FxDevice

Member Data Documentation

◆ m_AddressDescription

◆ m_DescriptionLink

◆ m_DescriptionState

◆ m_DeviceList

◆ m_FoundInLastScan

◆ m_IdentificationDescription

◆ m_ModificationLink

◆ m_ModificationState

◆ m_Pdo

◆ m_PendingDeleteOnScanEnd

◆ m_ProcessingSurpriseRemove

◆ m_ReportedMissingCallbackState