/*++
Copyright (c) Microsoft Corporation
Module Name:
FxObject.hpp
Abstract:
This is the C++ header for the FxObject
Author:
Revision History:
Made mode agnostic
IMPORTANT: Common code must call Initialize method of
FxObject before using it
Cannot put CreateAndInitialize method on this class as it
cannot be instantiated
--*/
#ifndef _FXOBJECT_H_
#define _FXOBJECT_H_
extern "C" {
#if defined(EVENT_TRACING)
#include "FxObject.hpp.tmh"
#endif
}
//
// Macros to pass line and file information to AddRef and Release calls.
//
// NOTE: ADDREF and RELEASE can be used by any class derived from FxObject or
// IFxMemory while the OFFSET only works with an FxObject derivation
//
#define ADDREF(_tag) AddRef(_tag, __LINE__, __FILE__)
#define RELEASE(_tag) Release(_tag, __LINE__, __FILE__)
#define ADDREF_OFFSET(_tag, offset) AddRefOverride(offset, _tag, __LINE__, __FILE__)
#define RELEASE_OFFSET(_tag, offset) ReleaseOverride(offset, _tag, __LINE__, __FILE__)
//
// This assumes that the bottom 3 bits of an FxObject are clear, ie that the
// FxObject is 8 byte aligned. The conversion from and to a handle value
// will set / clear these bits as appropriate.
//
enum FxHandleFlags {
FxHandleFlagIsOffset = 0x1,
FxHandleFlagMask = 0x7, // bottom 3 bits are free
};
//
// We cannot define FxHandleValueMask as an enumerant in FxHandleFlags because
// an enum is limited to sizeof(ULONG), which doesn't work for us on a 64 bit OS
//
extern DECLSPEC_SELECTANY const ULONG_PTR FxHandleValueMask = (~((ULONG_PTR) FxHandleFlagMask));
//
// The type itself is aligned, but the pointer is not b/c those interested in the
// offset do not need it to be aligned.
//
// The offset is aligned on an 8 byte boundary so that we have the lower 3 bits
// of the low byte to use for a bit field
//
typedef DECLSPEC_ALIGN(8) USHORT WDFOBJECT_OFFSET_ALIGNED;
typedef USHORT WDFOBJECT_OFFSET, *PWDFOBJECT_OFFSET;
struct FxQueryInterfaceParams {
//
// We intentionally do not declare a constructor for this structure.
// Instead, code should use an inline initializer list. This reduces the
// number of cycles on hot paths by removing a funciton call.
//
// FxQueryInterfaceParams(
// PVOID* Object,
// WDFTYPE Type
// ) :
// Type(Type), Object(Object), Offset(0) {if (Object != NULL) *Object = NULL; }}
//
// Object to query for
//
PVOID* Object;
//
// Type for the object to query for
//
WDFTYPE Type;
//
// Offset of handle within its owning object. If zero, the Object was the
// handle. If not zero, ((PUCHAR) Object)-Offset will yield the owning
// Object.
//
WDFOBJECT_OFFSET Offset;
};
//
// type of object being allocated. An internal object does *NOT*
// 1) have its size rounded up to an alignment value
// 2) extra size and context header appended to the allocation
//
enum FxObjectType : UINT32 {
FxObjectTypeInvalid = 0,
FxObjectTypeInternal,
FxObjectTypeExternal,
FxObjectTypeEmbedded,
};
// Ensures that a BOOL type is generated from a flag mask
#define FLAG_TO_BOOL(_Flags, _FlagMask) (!!((_Flags) & (_FlagMask)))
enum FxObjectLockState {
ObjectDoNotLock = 0,
ObjectLock = 1
};
//
// Defines for FxObject::m_ObjectFlags
//
// NOTE: if you modify (add, remove, reassign a value) this enum in any way
// you must also change FxObject::m_ObjectFlagsByName.* to match your changes!!
//
enum FXOBJECT_FLAGS {
FXOBJECT_FLAGS_PASSIVE_CALLBACKS = 0x00000001, // Object must have all callbacks at passive level
// implies passive destroy
FXOBJECT_FLAGS_NODELETEDDI = 0x00000002, // The WdfObjectDelete DDI is invalid
FXOBJECT_FLAGS_DELETECALLED = 0x00000004, // DeleteObject method called
FXOBJECT_FLAGS_COMMITTED = 0x00000008, // Commit called
FXOBJECT_FLAGS_PASSIVE_DISPOSE = 0x00000010, // Object must be Dispose()'d at passive level
FXOBJECT_FLAGS_FORCE_DISPOSE_THREAD = 0x00000020, // Object is always disposed in the dispose thread
// UNUSED = 0x00000040,
FXOBJECT_FLAGS_HAS_DEBUG = 0x00000080, // has FxObjectDebugExtension before object pointer
FXOBJECT_FLAGS_EARLY_DISPOSED_EXT = 0x00000100, // Early disposed externally to the state machine
FXOBJECT_FLAGS_TRACE_STATE = 0x00000200, // log state changes to the IFR
FXOBJECT_FLAGS_HAS_CLEANUP = 0x00000400,
FXOBJECT_FLAGS_DISPOSE_OVERRIDE = 0x00000800,
};
//
// FxObject state represents whether an object is
// tearing down, and what phase its in.
//
enum FxObjectState {
FxObjectStateInvalid = 0,
FxObjectStateCreated,
FxObjectStateDisposed,
FxObjectStateDisposingEarly,
FxObjectStateDisposingDisposeChildren,
FxObjectStateDeferedDisposing,
FxObjectStateDeferedDeleting,
FxObjectStateWaitingForEarlyDispose,
FxObjectStateWaitingForParentDeleteAndDisposed,
FxObjectStateDeletedDisposing,
FxObjectStateDeletedAndDisposed,
FxObjectStateDeferedDestroy,
FxObjectStateDestroyed,
FxObjectStateMaximum,
};
enum FxObjectDroppedEvent {
FxObjectDroppedEventAssignParentObject = 0,
FxObjectDroppedEventAddChildObjectInternal,
FxObjectDroppedEventRemoveChildObjectInternal,
FxObjectDroppedEventDeleteObject,
FxObjectDroppedEventPerformEarlyDispose,
FxObjectDroppedEventRemoveParentAssignment,
FxObjectDroppedEventParentDeleteEvent,
};
// begin_wpp config
// CUSTOM_TYPE(FxObjectState, ItemEnum(FxObjectState));
// CUSTOM_TYPE(FxObjectDroppedEvent, ItemEnum(FxObjectDroppedEvent));
// end_wpp
#define DECLARE_INTERNAL_NEW_OPERATOR() \
PVOID \
__inline \
operator new( \
__in size_t Size, \
__in PFX_DRIVER_GLOBALS FxDriverGlobals \
) \
{ \
return FxObjectHandleAlloc(FxDriverGlobals, \
NonPagedPool, \
Size, \
0, \
WDF_NO_OBJECT_ATTRIBUTES,\
0, \
FxObjectTypeInternal); \
}
struct FxObjectDebugExtension {
FxTagTracker* TagTracker;
FxVerifierLock* VerifierLock;
BYTE StateHistory[8];
LONG StateHistoryIndex;
//
// Signature lives after all the fields to avoid byte padding if it is
// first on 64 bit systems.
//
ULONG Signature;
DECLSPEC_ALIGN(MEMORY_ALLOCATION_ALIGNMENT) ULONG AllocationStart[1];
};
enum FxObjectDebugExtensionValues {
FxObjectDebugExtensionSize = FIELD_OFFSET(FxObjectDebugExtension, AllocationStart),
FxObjectDebugExtensionSignature = 'DOxF',
};
class UfxObject;
class FxObject {
friend UfxObject; //UMDF object wrapper
friend FxDisposeList;
friend VOID GetTriageInfo(VOID);
private:
#if FX_CORE_MODE==FX_CORE_USER_MODE
#ifndef INLINE_WRAPPER_ALLOCATION
PVOID m_COMWrapper;
#endif
#endif
WDFTYPE m_Type;
//
// This is the already computed value of
// WDF_ALIGN_SIZE_UP(sizeof(derived object), MEMORY_ALLOCATION_ALIGNMENT) +
// WDF_ALIGN_SIZE_UP(extraContext, MEMORY_ALLOCATION_ALIGNMENT)
//
USHORT m_ObjectSize;
// Reference count is operated on with interlocked operations
LONG m_Refcnt;
PFX_DRIVER_GLOBALS m_Globals;
// Flags are protected by m_SpinLock, bits defined by the enum FXOBJECT_FLAGS
union {
USHORT m_ObjectFlags;
// Each field in this struct correspond to ascending enumerant values
// in FXOBJECT_FLAGS.
//
// NOTE: you should never touch these fields in any code, they are here
// strictly for use by the debugger extension so that it doesn't
// have to result FXOBJECT_FLAGS enumerant name strings into values.
//
struct {
USHORT PassiveCallbacks : 1;
USHORT NoDeleteDDI : 1;
USHORT DeleteCalled : 1;
USHORT Committed : 1;
USHORT PassiveDispose : 1;
USHORT ForceDisposeThread : 1;
USHORT Unused : 1;
USHORT HasDebug : 1;
USHORT EarlyDisposedExt : 1;
USHORT TraceState : 1;
} m_ObjectFlagsByName;
};
//
// m_ObjectState is protected by m_SpinLock. Contains values in the
// FxObjectState enum.
//
USHORT m_ObjectState;
// List of Child Objects
LIST_ENTRY m_ChildListHead;
// SpinLock protects m_ObjectState, m_ObjectFlags, m_ChildListHead, and m_ParentObject
MxLock m_SpinLock;
//
// Parent object when this object is a child.
//
// This is protected by the child objects m_SpinLock
//
FxObject* m_ParentObject;
//
// Link for when this object is a child
//
// This is accessed by the parent of this object, and
// protected by the parents spinlock.
//
LIST_ENTRY m_ChildEntry;
//
//
//
SINGLE_LIST_ENTRY m_DisposeSingleEntry;
protected:
union {
//
// This field is set when the object is being contructed or before
// Commit() and from then on is read only.
//
// FxDeviceBase* is used by the core object state machine. Derived
// objects might need the fuller FxDevice* (and they can safely get at
// it since they know they are a part of the derived FxDevice*).
//
CfxDeviceBase* m_DeviceBase;
CfxDevice* m_Device;
};
private:
FxObject(
VOID
)
{
// Always make the caller supply a type and size
}
// Do not specify argument names
FX_DECLARE_VF_FUNCTION_P1(
VOID,
VerifyConstruct,
_In_ BOOLEAN
);
VOID
__inline
Construct(
__in BOOLEAN Embedded
)
{
m_Refcnt = 1;
m_ObjectState = FxObjectStateCreated;
m_ObjectFlags = 0;
m_ParentObject = NULL;
InitializeListHead(&m_ChildListHead);
InitializeListHead(&m_ChildEntry);
m_DisposeSingleEntry.Next = NULL;
m_DeviceBase = NULL;
VerifyConstruct(m_Globals, Embedded);
}
VOID
__inline
SetObjectStateLocked(
__in FxObjectState NewState
)
{
if (m_ObjectFlags & FXOBJECT_FLAGS_TRACE_STATE) {
DoTraceLevelMessage(
m_Globals, TRACE_LEVEL_VERBOSE, TRACINGOBJECT,
"Object %p, WDFOBJECT %p transitioning from %!FxObjectState! to "
"%!FxObjectState!", this, GetObjectHandleUnchecked(),
m_ObjectState, NewState);
if (IsDebug()) {
FxObjectDebugExtension* pExtension;
pExtension = GetDebugExtension();
pExtension->StateHistory[
InterlockedIncrement(&pExtension->StateHistoryIndex)] =
(BYTE) NewState;
}
}
m_ObjectState = (USHORT) NewState;
}
protected:
FxObject(
__in WDFTYPE Type,
__in USHORT Size,
__in PFX_DRIVER_GLOBALS FxDriverGlobals,
__in FxObjectType ObjectType
);
FxObjectDebugExtension*
GetDebugExtension(
VOID
)
{
return CONTAINING_RECORD(this, FxObjectDebugExtension, AllocationStart);
}
BOOLEAN
IsDebug(
VOID
)
{
return FLAG_TO_BOOL(m_ObjectFlags, FXOBJECT_FLAGS_HAS_DEBUG);
}
static
PVOID
_GetBase(
__in FxObject* Object
)
{
if (Object->IsDebug()) {
return _GetDebugBase(Object);
}
else {
return (PVOID) Object;
}
}
VOID
AllocateTagTracker(
__in WDFTYPE Type
);
virtual
VOID
SelfDestruct(
VOID
)
{
delete this;
}
PVOID
__inline
GetObjectHandleUnchecked(
VOID
)
{
//
// We don't support offset handles in the base FxObject implementation.
// Offsets are specialized to internal objects of an FxObject
//
if (m_ObjectSize > 0) {
return _ToHandle(this);
}
else {
return NULL;
}
}
VOID
__inline
DestroyChildren(
VOID
)
{
PLIST_ENTRY ple;
FxObject *pChild;
while (!IsListEmpty(&m_ChildListHead)) {
ple = RemoveHeadList(&m_ChildListHead);
pChild = CONTAINING_RECORD(ple, FxObject, m_ChildEntry);
//
// Mark entry as unlinked
//
InitializeListHead(&pChild->m_ChildEntry);
//
// Inform child object of destruction. Object may be gone after return.
//
pChild->ParentDeleteEvent();
}
}
public:
#ifdef INLINE_WRAPPER_ALLOCATION
#if FX_CORE_MODE==FX_CORE_USER_MODE
static
USHORT
GetWrapperSize(
);
virtual
PVOID
GetCOMWrapper(
) = 0;
#else
static
USHORT
__inline
GetWrapperSize(
)
{
return 0;
}
#endif
#else
#if FX_CORE_MODE==FX_CORE_USER_MODE
PVOID GetCOMWrapper(){ return m_COMWrapper; }
void SetCOMWrapper(__drv_aliasesMem PVOID Wrapper){ m_COMWrapper = Wrapper; }
#endif
#endif
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
)
{
UNREFERENCED_PARAMETER(Type);
return FxObjectHandleAlloc(FxDriverGlobals,
NonPagedPool,
Size,
0,
WDF_NO_OBJECT_ATTRIBUTES,
0,
Type);
}
PVOID
__inline
operator new(
__in size_t Size,
__in PFX_DRIVER_GLOBALS FxDriverGlobals,
__in_opt PWDF_OBJECT_ATTRIBUTES Attributes,
__in USHORT ExtraSize = 0
)
{
return FxObjectHandleAlloc(FxDriverGlobals,
NonPagedPool,
Size,
0,
Attributes,
ExtraSize,
FxObjectTypeExternal);
}
VOID
operator delete(
__in PVOID Memory
);
static
FxObject*
_FromDisposeEntry(
__in PSINGLE_LIST_ENTRY Entry
)
{
return CONTAINING_RECORD(Entry, FxObject, m_DisposeSingleEntry);
}
//
// m_ObjectSize contains the size of the object + extra size. m_ObjectSize
// was already rounded up to the correct alignment when it was contructed.
//
#define GET_CONTEXT_HEADER() WDF_PTR_ADD_OFFSET_TYPE(this, m_ObjectSize, FxContextHeader*)
VOID
SetNoContextHeader(
VOID
)
{
m_ObjectSize = 0;
}
PVOID
__inline
GetObjectHandle(
VOID
)
{
ASSERT(GetRefCnt() > 0);
return GetObjectHandleUnchecked();
}
static
FxObject*
_GetObjectFromHandle(
__in WDFOBJECT Handle,
__inout PWDFOBJECT_OFFSET ObjectOffset
)
{
ULONG_PTR handle, flags;
handle = (ULONG_PTR) Handle;
//
// store the flags and then clear them off so we have a valid value
//
flags = FxHandleFlagMask & handle;
handle &= ~FxHandleFlagMask;
//
// It is assumed the caller has already set the offset to zero
//
// *ObjectOffset = 0;
//
// We always apply the mask
//
handle = handle ^ FxHandleValueMask;
if (flags & FxHandleFlagIsOffset) {
//
// The handle is a pointer to an offset value. Return the offset
// to the caller and then compute the object since the pointer
// to the offset is part of the object we are returning.
//
*ObjectOffset = *(PWDFOBJECT_OFFSET) handle;
return (FxObject*) (((PUCHAR) handle) - *ObjectOffset);
}
else {
//
// No offset, no verification. We pass the FxObject as the handle
//
return (FxObject*) handle;
}
}
static
PVOID
__inline
_ToHandle(
__in FxObject* Object
)
{
//
// Always XOR the constant. Faster than checking
// FxDriverGlobals->FxVerifierHandle.
//
return (PVOID) (((ULONG_PTR) Object) ^ FxHandleValueMask);
}
static
VOID
__inline
_ReferenceActual(
__in WDFOBJECT Object,
__in_opt PVOID Tag,
__in LONG Line,
__in PSTR File
)
{
FxObject* pObject;
WDFOBJECT_OFFSET offset;
offset = 0;
pObject = FxObject::_GetObjectFromHandle(Object, &offset);
if (offset == 0) {
pObject->AddRef(Tag, Line, File);
}
else {
pObject->AddRefOverride(offset, Tag, Line, File);
}
}
static
VOID
__inline
_DereferenceActual(
__in WDFOBJECT Object,
__in_opt PVOID Tag,
__in LONG Line,
__in PSTR File
)
{
FxObject* pObject;
WDFOBJECT_OFFSET offset;
offset = 0;
pObject = FxObject::_GetObjectFromHandle(Object, &offset);
if (offset == 0) {
pObject->Release(Tag, Line, File);
}
else {
pObject->ReleaseOverride(offset, Tag, Line, File);
}
}
__inline
FxContextHeader*
GetContextHeader(
VOID
)
{
if (m_ObjectSize == 0) {
return NULL;
}
else {
return GET_CONTEXT_HEADER();
}
}
__inline
PFX_DRIVER_GLOBALS
GetDriverGlobals(
VOID
)
{
return m_Globals;
}
WDFTYPE
GetType(
VOID
)
{
return m_Type;
}
USHORT
GetObjectSize(
VOID
)
{
return m_ObjectSize;
}
LONG
GetRefCnt(
VOID
)
{
return m_Refcnt;
}
FxTagTracker*
GetTagTracker(
VOID
)
{
if (IsDebug()) {
return CONTAINING_RECORD(this,
FxObjectDebugExtension,
AllocationStart)->TagTracker;
}
else {
return NULL;
}
}
CfxDevice*
GetDevice(
VOID
)
{
return m_Device;
}
CfxDeviceBase*
GetDeviceBase(
VOID
)
{
return m_DeviceBase;
}
VOID
SetDeviceBase(
__in CfxDeviceBase* DeviceBase
)
{
m_DeviceBase = DeviceBase;
}
static
PVOID
_GetDebugBase(
__in FxObject* Object
)
{
return CONTAINING_RECORD(Object, FxObjectDebugExtension, AllocationStart);
}
__inline
VOID
CallCleanup(
VOID
)
{
if (m_ObjectFlags & FXOBJECT_FLAGS_HAS_CLEANUP) {
CallCleanupCallbacks();
}
}
ULONG
__inline
AddRef(
__in_opt PVOID Tag = NULL,
__in LONG Line = 0,
__in_opt PSTR File = NULL
)
{
FxTagTracker* pTagTracker;
ULONG c;
c = InterlockedIncrement(&m_Refcnt);
//
// Catch the transition from 0 to 1. Since the REF_OBJ starts off at 1,
// we should never have to increment to get to this value.
//
ASSERT(c > 1);
pTagTracker = GetTagTracker();
if (pTagTracker != NULL) {
pTagTracker->UpdateTagHistory(Tag, Line, File, TagAddRef, c);
}
return c;
}
virtual
ULONG
Release(
__in_opt PVOID Tag = NULL,
__in LONG Line = 0,
__in_opt PSTR File = NULL
)
{
FxTagTracker* pTagTracker;
ULONG c;
pTagTracker = GetTagTracker();
if (pTagTracker != NULL) {
pTagTracker->UpdateTagHistory(Tag, Line, File, TagRelease, m_Refcnt - 1);
}
c = InterlockedDecrement(&m_Refcnt);
if (c == 0) {
FinalRelease();
}
return c;
}
virtual
ULONG
AddRefOverride(
__in WDFOBJECT_OFFSET Offset,
__in_opt PVOID Tag = NULL,
__in LONG Line = 0,
__in_opt PSTR File = NULL
)
{
UNREFERENCED_PARAMETER(Offset);
return AddRef(Tag, Line, File);
}
virtual
ULONG
ReleaseOverride(
__in WDFOBJECT_OFFSET Offset,
__in_opt PVOID Tag = NULL,
__in LONG Line = 0,
__in_opt PSTR File = NULL
)
{
UNREFERENCED_PARAMETER(Offset);
return Release(Tag, Line, File);
}
_Must_inspect_result_
virtual
NTSTATUS
QueryInterface(
__in FxQueryInterfaceParams* Params
);
VOID
MarkTraceState(
VOID
)
{
m_ObjectFlags |= FXOBJECT_FLAGS_TRACE_STATE;
}
BOOLEAN
__inline
IsTraceState(
VOID
)
{
return FLAG_TO_BOOL(m_ObjectFlags, FXOBJECT_FLAGS_TRACE_STATE);
}
VOID
__inline
TraceDroppedEvent(
__in FxObjectDroppedEvent Event
)
{
if (IsTraceState()) {
DoTraceLevelMessage(
m_Globals, TRACE_LEVEL_INFORMATION, TRACINGOBJECT,
"Object %p, WDFOBJECT %p, state %!FxObjectState! dropping event"
" %!FxObjectDroppedEvent!",
this, GetObjectHandleUnchecked(), m_ObjectState, Event);
}
}
VOID
MarkPassiveDispose(
__in FxObjectLockState State = ObjectLock
)
{
//
// Object which can have > passive level locks, but needs to be Dispose()'d
// at passive level. This means that the object's client cleanup
// routines will also be guaranteed to run at passive.
//
if (State == ObjectLock) {
KIRQL oldIrql;
m_SpinLock.Acquire(&oldIrql);
m_ObjectFlags |= FXOBJECT_FLAGS_PASSIVE_DISPOSE;
m_SpinLock.Release(oldIrql);
}
else {
m_ObjectFlags |= FXOBJECT_FLAGS_PASSIVE_DISPOSE;
}
}
//
// Sets that the object is a passive level only object who
// accesses page-able pool, routines, or has a driver
// specified passive constraint on callbacks such as
// Cleanup and Destroy.
//
VOID
MarkPassiveCallbacks(
__in FxObjectLockState State = ObjectLock
)
{
if (State == ObjectLock) {
KIRQL oldIrql;
m_SpinLock.Acquire(&oldIrql);
m_ObjectFlags |= FXOBJECT_FLAGS_PASSIVE_CALLBACKS | FXOBJECT_FLAGS_PASSIVE_DISPOSE;
m_SpinLock.Release(oldIrql);
}
else {
m_ObjectFlags |= FXOBJECT_FLAGS_PASSIVE_CALLBACKS | FXOBJECT_FLAGS_PASSIVE_DISPOSE;
}
}
VOID
MarkForceDisposeThread(
__in FxObjectLockState State = ObjectLock
)
{
//
// Object must always be disposed in a separate thread
// to allow waiting for some outstanding async
// operation to complete.
//
if (State == ObjectLock) {
KIRQL oldIrql;
m_SpinLock.Acquire(&oldIrql);
m_ObjectFlags |= FXOBJECT_FLAGS_FORCE_DISPOSE_THREAD;
m_SpinLock.Release(oldIrql);
}
else {
m_ObjectFlags |= FXOBJECT_FLAGS_FORCE_DISPOSE_THREAD;
}
}
BOOLEAN
IsPassiveCallbacks(
__in BOOLEAN AcquireLock = TRUE
)
{
BOOLEAN result;
KIRQL oldIrql = PASSIVE_LEVEL;
if (AcquireLock) {
m_SpinLock.Acquire(&oldIrql);
}
result = IsPassiveCallbacksLocked();
if (AcquireLock) {
m_SpinLock.Release(oldIrql);
}
return result;
}
BOOLEAN
IsPassiveDispose(
__in BOOLEAN AcquireLock = TRUE
)
{
BOOLEAN result;
KIRQL oldIrql = PASSIVE_LEVEL;
if (AcquireLock) {
m_SpinLock.Acquire(&oldIrql);
}
result = IsPassiveDisposeLocked();
if (AcquireLock) {
m_SpinLock.Release(oldIrql);
}
return result;
}
BOOLEAN
IsForceDisposeThread(
__in BOOLEAN AcquireLock = TRUE
)
{
BOOLEAN result;
KIRQL oldIrql = PASSIVE_LEVEL;
if (AcquireLock) {
m_SpinLock.Acquire(&oldIrql);
}
result = IsForceDisposeThreadLocked();
if (AcquireLock) {
m_SpinLock.Release(oldIrql);
}
return result;
}
VOID
MarkCommitted(
VOID
)
{
//
// Since no client code is accessing the handle yet, we don't need to
// acquire the object state lock to set the flag since this will be
// the only thread touching m_ObjectFlags.
//
m_ObjectFlags |= FXOBJECT_FLAGS_COMMITTED;
}
BOOLEAN
IsCommitted(
VOID
)
{
//
// No need to acquire the lock because it is assumed the caller is
// calling on an object whose ref count has gone to zero so there are
// no other callers to contend with who might set this flag or modify
// m_ObjectFlags.
//
return FLAG_TO_BOOL(m_ObjectFlags, FXOBJECT_FLAGS_COMMITTED);
}
VOID
MarkDisposeOverride(
__in FxObjectLockState State = ObjectLock
)
{
if (State == ObjectLock) {
KIRQL irql;
m_SpinLock.Acquire(&irql);
m_ObjectFlags |= FXOBJECT_FLAGS_DISPOSE_OVERRIDE;
m_SpinLock.Release(irql);
}
else {
m_ObjectFlags |= FXOBJECT_FLAGS_DISPOSE_OVERRIDE;
}
}
VOID
MarkNoDeleteDDI(
__in FxObjectLockState State = ObjectLock
)
{
if (State == ObjectLock) {
KIRQL irql;
m_SpinLock.Acquire(&irql);
m_ObjectFlags |= FXOBJECT_FLAGS_NODELETEDDI;
m_SpinLock.Release(irql);
}
else {
m_ObjectFlags |= FXOBJECT_FLAGS_NODELETEDDI;
}
}
BOOLEAN
IsNoDeleteDDI(
VOID
)
{
// No need for lock since its only set in constructor/init
return FLAG_TO_BOOL(m_ObjectFlags, FXOBJECT_FLAGS_NODELETEDDI);
}
//
// Commit the WDF object before returning handle to the caller.
//
_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
);
//
// Request that an object be deleted.
//
// This can be the result of a WDF API or a WDM event.
//
virtual
VOID
DeleteObject(
VOID
);
//
// Invoked by FxObject *once* when the object is either
// being deleted, or rundown due to its parent object
// being deleted.
//
// An object can override this to perform per object
// cleanup if required.
//
// TRUE means that the cleanup callbacks should be called when the function
// returns. FALSE indicates that the caller will take care of calling the
// cleanup callbacks on behalf of the state machine.
//
virtual
BOOLEAN
Dispose(
VOID
);
//
// Request to make ParentObject the parent for this object.
//
_Must_inspect_result_
NTSTATUS
AssignParentObject(
__in FxObject* ParentObject
);
_Must_inspect_result_
NTSTATUS
AddContext(
__in FxContextHeader *Header,
__in PVOID* Context,
__in PWDF_OBJECT_ATTRIBUTES Attributes
);
//
// Request that this Object be removed from the child association
// list for its parent
//
_Must_inspect_result_
NTSTATUS
RemoveParentAssignment(
VOID
);
//
// Adds a reference to the parent object pointer if != NULL
//
_Must_inspect_result_
FxObject*
GetParentObjectReferenced(
__in PVOID Tag
);
//
// This is public to allow debug code to assert that
// an object has been properly disposed either through
// calling DeleteObject, or being disposed by its parent.
//
BOOLEAN
IsDisposed(
VOID
)
{
KIRQL oldIrql;
BOOLEAN disposed;
if (m_Globals->FxVerifierOn &&
m_Globals->FxVerifierHandle) {
m_SpinLock.Acquire(&oldIrql);
if (m_ObjectState == FxObjectStateCreated) {
disposed = FALSE;
}
else {
//
// Parent is disposing us, or we are being disposed
//
disposed = TRUE;
}
m_SpinLock.Release(oldIrql);
return disposed;
}
else {
return TRUE;
}
}
static
PFX_POOL_HEADER
_CleanupPointer(
__in PFX_DRIVER_GLOBALS FxDriverGlobals,
__in FxObject* Object
)
{
PFX_POOL_HEADER pHeader;
PVOID pObjectBase;
pObjectBase = _GetBase(Object);
pHeader = CONTAINING_RECORD(pObjectBase, FX_POOL_HEADER, AllocationStart);
//
// If PoolTracker is on then do....
//
if (FxDriverGlobals->IsPoolTrackingOn()) {
//
// Decommission this NonPaged Allocation tracker
//
FxPoolRemoveNonPagedAllocateTracker((PFX_POOL_TRACKER) pHeader->Base);
}
return pHeader;
}
_Must_inspect_result_
static
NTSTATUS
_GetEffectiveLock(
__in FxObject* Object,
__in_opt IFxHasCallbacks* Callbacks,
__in BOOLEAN AutomaticLocking,
__in BOOLEAN PassiveCallbacks,
__out FxCallbackLock** CallbackLock,
__out_opt FxObject** CallbackLockObject
);
//
// Implementation for WdfObjectQuery
//
_Must_inspect_result_
static
NTSTATUS
_ObjectQuery(
_In_ FxObject* Object,
_In_ CONST GUID* Guid,
_In_ ULONG QueryBufferLength,
_Out_writes_bytes_(QueryBufferLength)
PVOID QueryBuffer
);
protected:
VOID
DeleteEarlyDisposedObject(
VOID
);
private:
VOID
FinalRelease(
VOID
);
//
// This is used by verifier to ensure that DeleteObject
// is only called once.
//
// It must be accessed under the m_SpinLock.
//
// It returns TRUE if this is the first call.
//
BOOLEAN
MarkDeleteCalledLocked(
VOID
)
{
BOOLEAN retval;
retval = !(m_ObjectFlags & FXOBJECT_FLAGS_DELETECALLED);
m_ObjectFlags |= FXOBJECT_FLAGS_DELETECALLED;
return retval;
}
BOOLEAN
IsPassiveCallbacksLocked(
VOID
)
{
return FLAG_TO_BOOL(m_ObjectFlags, FXOBJECT_FLAGS_PASSIVE_CALLBACKS);
}
BOOLEAN
IsPassiveDisposeLocked(
VOID
)
{
return FLAG_TO_BOOL(m_ObjectFlags, FXOBJECT_FLAGS_PASSIVE_DISPOSE);
}
BOOLEAN
IsForceDisposeThreadLocked(
VOID
)
{
return FLAG_TO_BOOL(m_ObjectFlags, FXOBJECT_FLAGS_FORCE_DISPOSE_THREAD);
}
BOOLEAN
ShouldDeferDisposeLocked(
__out_opt PKIRQL PreviousIrql = NULL
)
{
if (IsForceDisposeThreadLocked()) {
return TRUE;
}
else if (IsPassiveDisposeLocked()) {
//
// Only call KeGetCurrentIrql() if absolutely necessary. It is an
// expensive call and we want to minimize the cycles required when
// destroying an object that requires passive rundown
//
//
// Cases:
// 1) Caller does not know the current IRQL, so we must query for it
//
// 2) Caller knew prev IRQL, so we used the caller's value
//
if (PreviousIrql == NULL) { // case 1
if (Mx::MxGetCurrentIrql() != PASSIVE_LEVEL) {
return TRUE;
}
}
else if (*PreviousIrql != PASSIVE_LEVEL) { // case 2
return TRUE;
}
}
return FALSE;
}
VOID
ParentDeleteEvent(
VOID
);
BOOLEAN
PerformEarlyDispose(
VOID
);
_Releases_lock_(this->m_SpinLock.m_Lock)
__drv_requiresIRQL(DISPATCH_LEVEL)
BOOLEAN
PerformEarlyDisposeWorkerAndUnlock(
__in __drv_restoresIRQL KIRQL OldIrql,
__in BOOLEAN CanDefer
);
_Releases_lock_(this->m_SpinLock.m_Lock)
__drv_requiresIRQL(DISPATCH_LEVEL)
BOOLEAN
PerformDisposingDisposeChildrenLocked(
__in __drv_restoresIRQL KIRQL OldIrql,
__in BOOLEAN CanDefer
);
_Releases_lock_(this->m_SpinLock.m_Lock)
__drv_requiresIRQL(DISPATCH_LEVEL)
BOOLEAN
DeleteWorkerAndUnlock(
__in __drv_restoresIRQL KIRQL OldIrql,
__in BOOLEAN CanDefer
);
VOID
QueueDeferredDisposeLocked(
__in FxObjectState NewDeferedState
);
VOID
DeferredDisposeWorkItem(
VOID
);
_Releases_lock_(this->m_SpinLock.m_Lock)
__drv_requiresIRQL(DISPATCH_LEVEL)
BOOLEAN
DisposeChildrenWorker(
__in FxObjectState NewDeferedState,
__in __drv_restoresIRQL KIRQL OldIrql,
__in BOOLEAN CanDefer
);
_When_(Unlock, _Releases_lock_(this->m_SpinLock.m_Lock))
__drv_when(Unlock, __drv_requiresIRQL(DISPATCH_LEVEL))
VOID
DeletedAndDisposedWorkerLocked(
__in __drv_when(Unlock, __drv_restoresIRQL) KIRQL OldIrql,
__in BOOLEAN Unlock = TRUE
);
_Must_inspect_result_
NTSTATUS
RemoveParentAssociation(
VOID
);
_Must_inspect_result_
NTSTATUS
AddChildObjectInternal(
__in FxObject* ChildObject
);
_Must_inspect_result_
NTSTATUS
RemoveChildObjectInternal(
__in FxObject* ChildObject
);
VOID
ProcessDestroy(
VOID
);
VOID
CallCleanupCallbacks(
VOID
);
};
#endif // _FXOBJECT_H_