/*++ Copyright (c) 1998-1999 Microsoft Corporation Module Name: rm.h Abstract: "Resource Manager" structures and APIs Author: Revision History: Who When What -------- -------- ---- josephj 11-10-98 created --*/ //================================================================================= // O S - S P E C I F I C T Y P E S //================================================================================= #define RM_OS_LOCK NDIS_SPIN_LOCK #define OS_WORK_ITEM NDIS_WORK_ITEM #define OS_TIMER NDIS_TIMER #define RM_STATUS NDIS_STATUS #define RM_OS_FILL_MEMORY(_dest, _len, _fill) NdisFillMemory(_dest, _len, _fill) #define RM_OS_ZERO_MEMORY(_dest, _len) NdisZeroMemory(_dest, _len) #define RM_OS_GET_CURRENT_THREAD_HANDLE() NULL // If set, the object tree is explicitly maintained. // #define RM_TRACK_OBJECT_TREE 1 //================================================================================= // F O R W A R D R E F E R E N C E S //================================================================================= typedef struct _RM_STACK_RECORD RM_STACK_RECORD, *PRM_STACK_RECORD; typedef struct _RM_OBJECT_HEADER RM_OBJECT_HEADER, *PRM_OBJECT_HEADER; typedef struct _RM_TASK RM_TASK, *PRM_TASK; typedef struct _RM_RESOURCE_TABLE_ENTRY RM_RESOURCE_TABLE_ENTRY, *PRM_RESOURCE_TABLE_ENTRY; //================================================================================= // T Y P E D E F S //================================================================================= // // RM_DBG_LOCK_INFO Keeps debugging information specific to an instance of a RM_LOCK. // typedef struct _RM_DBG_LOCK_INFO { // // If nonzero, LocID is a magic number which uniquely identifies the source // location where the lock was aquired. // ULONG uLocID; // // pSR points to the stack record of the currently owning thread, if there // is one. If a function F expects an object pObj to be locked on entry, // it can ASSERT(pObj->pLock->pDbgInfo->pSR == pSR); // struct _RM_STACK_RECORD *pSR; } RM_DBG_LOCK_INFO, *PRM_DBG_LOCK_INFO; // // RM_LOCK keeps information about a lock. // typedef struct _RM_LOCK { // // Native, os-provided lock structure. // RM_OS_LOCK OsLock; // // Level of this lock. Multiple locks can only be acquired in increasing order // of this value. // ULONG Level; // // Pointer to debugging info for this lock. Could be NULL. // PRM_DBG_LOCK_INFO pDbgInfo; #if RM_EXTRA_CHECKING RM_DBG_LOCK_INFO DbgInfo; #endif // RM_EXTRA_CHECKING } RM_LOCK, *PRM_LOCK; typedef ULONG (*PFNLOCKVERIFIER) ( PRM_LOCK pLock, BOOLEAN fLock, PVOID pContext, PRM_STACK_RECORD pSR ); // RM_LOCKING_INFO keeps information about a particular lock being held. // In non-checking mode, this is just the pointer to the lock. // In checking mode, this additionally contains information that can be used // to verify that the entity being protected by the lock is not changed when // the lock is not being held. // typedef struct { PRM_LOCK pLock; #if RM_EXTRA_CHECKING PFNLOCKVERIFIER pfnVerifier; PVOID pVerifierContext; #endif // RM_EXTRA_CHECKING } RM_LOCKING_INFO, PRM_LOCKING_INFO; // // RM_STACK_RECORD keeps information relevant to the current call tree. // typedef struct _RM_STACK_RECORD { // // LockInfo contains information about currently-held locks. // struct { // // Level of the currently held lock. Locks must be claimed in // order of increasing Level values. The lowest level value is 1. Level // 0 indicates no locks held. // UINT CurrentLevel; // // Pointer to the first location to store a pointers to a locks. // PRM_LOCKING_INFO *pFirst; // // Pointer to the next free location to store a pointer to a lock // that has been claimed in this call tree. // PRM_LOCKING_INFO *pNextFree; // // Pointer to the last valid location to store a lock pointer. // PRM_LOCKING_INFO *pLast; } LockInfo; // // Count of tmp refs taken with this stack record. // ULONG TmpRefs; #if DBG // // DbgInfo contains diagnostic information relevant to this call tree. // struct { // // Verbosity level // ULONG Level; // // Points to the os-provided thread handle of the current thread. // if there is one. // PVOID pvThread; } DbgInfo; #endif // DBG } RM_STACK_RECORD, *PRM_STACK_RECORD; #if DBG #define RM_INIT_DBG_STACK_RECORD(_sr, _dbglevel) \ _sr.DbgInfo.Level = _dbglevel; \ _sr.DbgInfo.pvThread = RM_OS_GET_CURRENT_THREAD_HANDLE(); #else #define RM_INIT_DBG_STACK_RECORD(_sr, _dbglevel) #endif // // RM_DECLARE_STACK_RECORD_EX is a macro to reserve some stack space for // a stack record. // #define RM_DECLARE_STACK_RECORD_EX(_sr, _max_locks, _dbglevel) \ RM_LOCKING_INFO rm_lock_array[_max_locks]; \ RM_STACK_RECORD _sr; \ RM_OS_ZERO_MEMORY(rm_lock_array, sizeof(rm_lock_array)); \ _sr.TmpRefs = 0; \ _sr.LockInfo.CurrentLevel = 0; \ _sr.LockInfo.pFirst = rm_lock_array; \ _sr.LockInfo.pNextFree = rm_lock_array; \ _sr.LockInfo.pLast = rm_lock_array+(_max_locks)-1; \ RM_INIT_DBG_STACK_RECORD(_sr, _dbglevel); // // RM_DECLARE_STACK_RECORD is a macro to reserve default stack space for // a stack record. // #define RM_DECLARE_STACK_RECORD(_sr) \ RM_DECLARE_STACK_RECORD_EX(_sr, 4, 0) // // Generic memory allocator prototype // typedef PVOID (*PFN_RM_MEMORY_ALLOCATOR)( PVOID pAllocationContext, UINT Size // in bytes ); // // Generic memory deallocator prototype // typedef PVOID (*PFN_RM_MEMORY_DEALLOCATOR)( PVOID pMem, PVOID pAllocationContext ); // RM_HASH_LINK is the field in the structures being hashed that is // used to link all items in the same bucket. It also contains the // "HashKey", which is a potentially-nonunique UINT-sized hash of the // real key. // typedef struct _RM_HASH_LINK { struct _RM_HASH_LINK *pNext; UINT uHash; } RM_HASH_LINK, *PRM_HASH_LINK; // // Hash table comparison function. // typedef BOOLEAN (*PFN_RM_COMPARISON_FUNCTION)( PVOID pKey, PRM_HASH_LINK pItem ); // // Hash computation function. // typedef ULONG (*PFN_RM_HASH_FUNCTION)( PVOID pKey ); // // RM_HASH_INFO specifies customizing information about a hash table. // typedef struct { // Allocator used to allocate the hash table if it needs to grow. // PFN_RM_MEMORY_ALLOCATOR pfnTableAllocator; // Free function for the above allocator. PFN_RM_MEMORY_DEALLOCATOR pfnTableDeallocator; // Comparison function for strict equality. // PFN_RM_COMPARISON_FUNCTION pfnCompare; // Function to generate a ULONG-sized hash. // PFN_RM_HASH_FUNCTION pfnHash; #if OBSOLETE // Offset in sizeof(UINT) to location of the place to keep // the next pointer for the bucket list. // UINT OffsetNext; // Offset in sizeof(UINT) to location of UINT-sized Temp ref // UINT OffsetTmpRef; // Offset in sizeof(UINT) to location of UINT-sized Tot ref // UINT OffsetTotRef; // Offset in sizeof(UINT) to location of ULONG-sized hash key. // UINT OffsetHashKey; #endif // OBSOLETE } RM_HASH_INFO, *PRM_HASH_INFO; #define RM_MIN_HASH_TABLE_SIZE 4 // // RM_HASH_TABLE is a hash table. // typedef struct { // Number of items currently in hash table. // UINT NumItems; // Stats is a 32-bit quantity keeps a running total of number of accesses // (add+search+remove) in the HIWORD and the total number of list nodes // traversed in the LOWORD. This field gets updated even on searches, but // it is not protected by the hash table lock -- instead it is // updated using an interlocked operation. This allows us to use // a read lock for searches while still updating this statistic value. // The Stats field is re-scaled when the counts get too high, to avoid // overflow and also to favor more recent stats in preference to older // stats. // // NumItems, Stats and TableLength are used to decide whether to // dynamically resize the hash table. // ULONG Stats; // Length of hash table in units of PVOID // ULONG TableLength; // Pointer to TableLength-sized array of PVOIDs -- this is the actual hash table // PRM_HASH_LINK *pTable; // The hash table // PRM_HASH_LINK InitialTable[RM_MIN_HASH_TABLE_SIZE]; // Static information about this hash table. // PRM_HASH_INFO pHashInfo; // Passed into the allocate/deallocate functions. // PVOID pAllocationContext; } RM_HASH_TABLE, *PRM_HASH_TABLE; // Returns approximate value of (num-nodes-traversed)/(num-accesses) // #define RM_HASH_TABLE_TRAVERSE_RATIO(_pHash_Table) \ (((_pHash_Table)->Stats & 0xffff) / (1+((_pHash_Table)->Stats >> 16))) // // NOTE: the "1+" above is simply to guard against devide-by-zero. // // RM_OBJECT_DIAGNOSTIC_INFO keeps diagnostic info specific to an instance of // an object. // // This structure is for private use of the RM APIs. // The only field of general interest is PrevState. // typedef struct { // Back pointer to owning object. // RM_OBJECT_HEADER *pOwningObject; // Each time the object-specific State field is updated, it's previous // value is saved here. // ULONG PrevState; // Used for correctly updating PrevState. // ULONG TmpState; // Diagnostic-related state. // ULONG DiagState; #define fRM_PRIVATE_DISABLE_LOCK_CHECKING (0x1<<0) // This is an object-specific checksum that is computed and // saved just before the object is unlocked. It is checked // just after the object is locked. // ULONG Checksum; // Native OS lock to be *only* to serialize access to the information // in this structure. // RM_OS_LOCK OsLock; // Keeps an associative list of all entities which have been registered // (using RmDbgAddAssociation) with this object. Ths includes objects which // have been linked to this object using the RmLinkObjects call, as well // as childen and parents of this object. // RM_HASH_TABLE AssociationTable; // Following is set to TRUE IFF there was an allocation failure when trying to // add an association. If there'e been an allocation failure, we don't complain // (i.e. ASSERT) if an attempt is made to remove an assertion that doesn't // exist. In this way we gracefully deal with allocation failures of the // association table entries. // INT AssociationTableAllocationFailure; // The per-object list of log entries. // This is serialized by the global rm lock, not the local rm-private lock! // LIST_ENTRY listObjectLog; // Count of entries in this object's log. // This is serialized by the global rm lock, not the local rm-private lock! // UINT NumObjectLogEntries; #if TODO // We haven't implemented the following yet... // Future: // RM_STATE_HISTORY -- generalization of PrevState. #endif // TODO } RM_OBJECT_DIAGNOSTIC_INFO, *PRM_OBJECT_DIAGNOSTIC_INFO; typedef PRM_OBJECT_HEADER (*PFN_CREATE_OBJECT)( PRM_OBJECT_HEADER pParentObject, PVOID pCreateParams, PRM_STACK_RECORD psr ); typedef VOID (*PFN_DELETE_OBJECT)(PRM_OBJECT_HEADER, PRM_STACK_RECORD psr); // // RM_STATIC_OBJECT_INFO keeps information that is common to all instances of // a particular type of object. // typedef struct { ULONG TypeUID; ULONG TypeFlags; char* szTypeName; UINT Timeout; // // Various Handlers // PFN_CREATE_OBJECT pfnCreate; PFN_DELETE_OBJECT pfnDelete; PFNLOCKVERIFIER pfnLockVerifier; // // Resource Information // UINT NumResourceTableEntries; struct _RM_RESOURCE_TABLE_ENTRY * pResourceTable; // // Hash-table info, if this object is part of a group. // PRM_HASH_INFO pHashInfo; } RM_STATIC_OBJECT_INFO, *PRM_STATIC_OBJECT_INFO; // // RM_OBJECT_HEADER is the common header for all objects. // typedef struct _RM_OBJECT_HEADER { // // Object-type-specific signature. // ULONG Sig; // // Description of this object (could be the same as pStaticInfo->szTypeName, // but may be something more specific). // Used only for debugging purposes. // TODO: consider moving this into the pDiagInfo struct. For now, leave it // here because it's useful when debugging. // const char *szDescription; // // Object-specific state. // ULONG State; ULONG RmState; // One or more RMOBJSTATE_* or RMTSKSTATE_* flags below... // // RM state flags.... // // Object allocation state... // #define RMOBJSTATE_ALLOCMASK 0x00f #define RMOBJSTATE_ALLOCATED 0x001 #define RMOBJSTATE_DEALLOCATED 0x000 // Task state ... // #define RMTSKSTATE_MASK 0x0f0 #define RMTSKSTATE_IDLE 0x000 #define RMTSKSTATE_STARTING 0x010 #define RMTSKSTATE_ACTIVE 0x020 #define RMTSKSTATE_PENDING 0x030 #define RMTSKSTATE_ENDING 0x040 // Task delay state // #define RMTSKDELSTATE_MASK 0x100 #define RMTSKDELSTATE_DELAYED 0x100 // Task abort state // #define RMTSKABORTSTATE_MASK 0x200 #define RMTSKABORTSTATE_ABORT_DELAY 0x200 // // Bitmap identifying resources used by this object. // ULONG ResourceMap; // Total reference count. // // ULONG TotRefs; // // Pointer to a RM_LOCK object used to serialize access to this object. // PRM_LOCK pLock; // // Pointer to information common to all instances of this object type. // PRM_STATIC_OBJECT_INFO pStaticInfo; // // Points to diagnostic information about this object. Could be NULL. // PRM_OBJECT_DIAGNOSTIC_INFO pDiagInfo; // // Points to the parent object. // struct _RM_OBJECT_HEADER *pParentObject; // // Points to the root (ancestor of all object) -- could be the same // as pParentObject; // struct _RM_OBJECT_HEADER *pRootObject; // // This is a private lock used exclusively by the RM apis. It is // never left unlocked by the RM apis. // TODO: maybe make this a native-os lock. // RM_LOCK RmPrivateLock; // Used to create groups of objects. // TODO: make this a private field, present only if the object is // meant to be in a group. // RM_HASH_LINK HashLink; #if RM_TRACK_OBJECT_TREE LIST_ENTRY listChildren; // Protected by this object's RmPrivateLock. LIST_ENTRY linkSiblings; // Protected by parent object's RmPrivateLock. #endif // RM_TRACK_OBJECT_TREE } RM_OBJECT_HEADER, *PRM_OBJECT_HEADER; // // Diagnostic resource tracking. // typedef struct { ULONG_PTR Instance; ULONG TypeUID; PRM_OBJECT_HEADER pParentObject; ULONG CallersUID; ULONG CallersSrUID; } RM_DBG_RESOURCE_ENTRY; typedef enum { RM_RESOURCE_OP_LOAD, RM_RESOURCE_OP_UNLOAD } RM_RESOURCE_OPERATION; typedef RM_STATUS (*PFN_RM_RESOURCE_HANDLER)( PRM_OBJECT_HEADER pObj, RM_RESOURCE_OPERATION Op, PVOID pvUserParams, PRM_STACK_RECORD psr ); typedef struct _RM_RESOURCE_TABLE_ENTRY { UINT ID; PFN_RM_RESOURCE_HANDLER pfnHandler; } RM_RESOURCE_TABLE_ENTRY, *PRM_RESOURCE_TABLE_ENTRY; typedef struct { UINT u; } RM_OBJECT_INDEX, *PRM_OBJECT_INDEX; typedef struct { PRM_OBJECT_HEADER pOwningObject; const char * szDescription; PRM_STATIC_OBJECT_INFO pStaticInfo; RM_HASH_TABLE HashTable; // Private lock used ONLY by group access functions. // RM_OS_LOCK OsLock; // When non-NULL, points to the task responsible for unloading all objects // in this group. // PRM_TASK pUnloadTask; BOOLEAN fEnabled; } RM_GROUP, *PRM_GROUP; typedef enum { RM_TASKOP_START, RM_TASKOP_PENDCOMPLETE, RM_TASKOP_END, RM_TASKOP_PRIVATE, RM_TASKOP_ABORT, RM_TASKOP_TIMEOUT } RM_TASK_OPERATION; typedef RM_STATUS (*PFN_RM_TASK_HANDLER)( IN struct _RM_TASK * pTask, IN RM_TASK_OPERATION Op, IN UINT_PTR UserParam, IN PRM_STACK_RECORD pSR ); // // For START and PENDCOMPLETE, a return value other than PENDING causes // the task to end. Of course, it is illegal to return non-pending when // the task is in a pending state. // // Task allocator prototype // typedef RM_STATUS (*PFN_RM_TASK_ALLOCATOR)( IN PRM_OBJECT_HEADER pParentObject, IN PFN_RM_TASK_HANDLER pfnHandler, IN UINT Timeout, IN const char * szDescription, OUT PRM_TASK *ppTask, IN PRM_STACK_RECORD pSR ); typedef struct _RM_TASK { RM_OBJECT_HEADER Hdr; PFN_RM_TASK_HANDLER pfnHandler; LIST_ENTRY linkFellowPendingTasks; LIST_ENTRY listTasksPendingOnMe; struct _RM_TASK * pTaskIAmPendingOn; // In the case that we need to asynchronously notify the completion of a // pending operation, we can save the completion param here. // UINT_PTR AsyncCompletionParam; UINT SuspendContext; } RM_TASK, *PRM_TASK; typedef VOID (_cdecl *PFN_DBG_DUMP_LOG_ENTRY) ( char *szFormatString, UINT_PTR Param1, UINT_PTR Param2, UINT_PTR Param3, UINT_PTR Param4 ); #if RM_EXTRA_CHECKING // (For debugging only) // Keeps track of a single association (See RmDbgAddAssociation) // This is a PRIVATE data structure, and is only here because // the kd extension refers to it. // typedef struct { ULONG LocID; ULONG_PTR Entity1; ULONG_PTR Entity2; ULONG AssociationID; const char * szFormatString; RM_HASH_LINK HashLink; } RM_PRIVATE_DBG_ASSOCIATION; // (For debugging only) // Keeps track of a single per-object log entry. // This is a PRIVATE data structure, and is only here because // the kd extension refers to it. // typedef struct { // Link to other entries for this object // LIST_ENTRY linkObjectLog; // Link to other entries in the global list. // LIST_ENTRY linkGlobalLog; // Object this entry belongs to // PRM_OBJECT_HEADER pObject; // Function to be used for dumping the log. // PFN_DBG_DUMP_LOG_ENTRY pfnDumpEntry; // Prefix string to be dumped *before* the log display. // This was added so we could log associations properly, otherwise it's // extra baggage. Can be null. // char *szPrefix; // Format string for log display -- 1st arg to pfnDumpEntry // char *szFormatString; // Remaining args to pfnDumpEntry; // // UINT_PTR Param1; UINT_PTR Param2; UINT_PTR Param3; UINT_PTR Param4; // If non-NULL, piece of memory to be freed when the log entry is freed. // TODO: See notes.txt entry "03/07/1999 ... Registering root objects with RM" // on how we will find the deallocator function. For now we simply // use NdisFreeMemory. // PVOID pvBuf; } RM_DBG_LOG_ENTRY; #endif RM_EXTRA_CHECKING //================================================================================= // U T I L I T Y M A C R O S //================================================================================= #define RM_PARENT_OBJECT(_pObj) \ ((_pObj)->Hdr.pParentObject) #define RM_PEND_CODE(_pTask) \ ((_pTask)->SuspendContext) #define RM_ASSERT_SAME_LOCK_AS_PARENT(_pObj) \ ASSERTEX( \ ((_pObj)->Hdr.pLock == (_pObj)->Hdr.pParentObject->pLock), \ (_pObj)) #define RM_SET_STATE(_pObj, _Mask, _Val) \ (((_pObj)->Hdr.State) = (((_pObj)->Hdr.State) & ~(_Mask)) | (_Val)) #define RM_CHECK_STATE(_pObj, _Mask, _Val) \ ((((_pObj)->Hdr.State) & (_Mask)) == (_Val)) #define RM_GET_STATE(_pObj, _Mask) \ (((_pObj)->Hdr.State) & (_Mask)) // Asserts that the object is in the "zombie" state, i.e., it // lives on just because of references. // WARNING: It is upto the caller to synchronize access to this -- for example // if they're going to do thing's like if (!RM_IS_ZOMBIE(pObj)) {do-stuff}, they // had better make sure that only one of them goes on to "does-stuff". // #define RM_IS_ZOMBIE(_pobj) \ (((_pobj)->Hdr.RmState&RMOBJSTATE_ALLOCMASK)==RMOBJSTATE_DEALLOCATED) // Asserts that no locks are held. // #define RM_ASSERT_NOLOCKS(_psr) \ ASSERTEX((_psr)->LockInfo.CurrentLevel == 0, (_psr)) // Assert that no locks or tmprefs are held. // #define RM_ASSERT_CLEAR(_psr) \ ASSERTEX(((_psr)->LockInfo.CurrentLevel==0) && (_psr)->TmpRefs==0, (_psr)) #if RM_EXTRA_CHECKING // // TODO: rename the following to something better... // #define RM_DBG_ASSERT_LOCKED0(_pLk, _pSR) \ ASSERTEX((_pLk)->DbgInfo.pSR == (_pSR), (_pHdr)) // TODO -- replace calls to this by calls to RM_ASSERT_OBJLOCKED #define RM_DBG_ASSERT_LOCKED(_pHdr, _pSR) \ ASSERTEX((_pHdr)->pLock->DbgInfo.pSR == (_pSR), (_pHdr)) #define RM_ASSERT_OBJLOCKED(_pHdr, _pSR) \ ASSERTEX((_pHdr)->pLock->DbgInfo.pSR == (_pSR), (_pHdr)) // Note that we can't assume DbgInfo.pSR is NULL below (it could be locked // by some other thread), but we CAN assert that DbgInfo.pSR is not equal to the // current pSR! // #define RM_ASSERT_OBJUNLOCKED(_pHdr, _pSR) \ ASSERTEX((_pHdr)->pLock->DbgInfo.pSR != (_pSR), (_pHdr)) #else // !RM_EXTRA_CHECKING #define RM_DBG_ASSERT_LOCKED0(_pLk, _pSR) (0) #define RM_DBG_ASSERT_LOCKED(_pHdr, _pSR) (0) #define RM_ASSERT_OBJLOCKED(_pHdr, _pSR) (0) #define RM_ASSERT_OBJUNLOCKED(_pHdr, _pSR) (0) #endif // !RM_EXTRA_CHECKING #define RM_NUM_ITEMS_IN_GROUP(_pGroup) \ ((_pGroup)->HashTable.NumItems) //================================================================================= // F U N C T I O N P R O T O T Y P E S //================================================================================= VOID RmInitializeRm(VOID); VOID RmDeinitializeRm(VOID); VOID RmInitializeHeader( IN PRM_OBJECT_HEADER pParentObject, IN PRM_OBJECT_HEADER pObject, IN UINT Sig, IN PRM_LOCK pLock, IN PRM_STATIC_OBJECT_INFO pStaticInfo, IN const char * szDescription, IN PRM_STACK_RECORD pSR ); // // Object allocation and deallocation APIs // VOID RmDeallocateObject( IN PRM_OBJECT_HEADER pObject, IN PRM_STACK_RECORD pSR ); // // locking // VOID RmInitializeLock( IN PRM_LOCK pLock, IN UINT Level ); VOID RmDoWriteLock( PRM_LOCK pLock, PRM_STACK_RECORD pSR ); #if TODO VOID RmDoReadLock( IN PRM_OBJECT_HEADER pObj, IN PRM_STACK_RECORD pSR ); #else //!TODO #define RmDoReadLock RmDoWriteLock #endif //!TODO VOID RmDoUnlock( PRM_LOCK pLock, PRM_STACK_RECORD pSR ); #if TODO VOID RmReadLockObject( IN PRM_OBJECT_HEADER pObj, #if RM_EXTRA_CHECKING UINT uLocID, #endif //RM_EXTRA_CHECKING IN PRM_STACK_RECORD pSR ); #else //!TODO #define RmReadLockObject RmWriteLockObject #endif //!TODO VOID RmWriteLockObject( IN PRM_OBJECT_HEADER pObj, #if RM_EXTRA_CHECKING UINT uLocID, #endif //RM_EXTRA_CHECKING IN PRM_STACK_RECORD pSR ); VOID RmUnlockObject( IN PRM_OBJECT_HEADER pObj, IN PRM_STACK_RECORD pSR ); VOID RmUnlockAll( IN PRM_STACK_RECORD pSR ); VOID RmDbgChangeLockScope( IN PRM_OBJECT_HEADER pPreviouslyLockedObject, IN PRM_OBJECT_HEADER pObject, IN ULONG LocID, IN PRM_STACK_RECORD ); // // reference counting // VOID RmLinkObjects( IN PRM_OBJECT_HEADER pObj1, IN PRM_OBJECT_HEADER pObj2, IN PRM_STACK_RECORD pSr ); VOID RmUnlinkObjects( IN PRM_OBJECT_HEADER pObj1, IN PRM_OBJECT_HEADER pObj2, IN PRM_STACK_RECORD pSr ); VOID RmLinkObjectsEx( IN PRM_OBJECT_HEADER pObj1, IN PRM_OBJECT_HEADER pObj2, IN ULONG LocID, IN ULONG AssocID, IN const char * szAssociationFormat, IN ULONG InvAssocID, IN const char * szInvAssociationFormat, IN PRM_STACK_RECORD pSR ); VOID RmUnlinkObjectsEx( IN PRM_OBJECT_HEADER pObj1, IN PRM_OBJECT_HEADER pObj2, IN ULONG LocID, IN ULONG AssocID, IN ULONG InvAssocID, IN PRM_STACK_RECORD pSR ); VOID RmLinkToExternalEx( IN PRM_OBJECT_HEADER pObj, IN ULONG LocID, IN UINT_PTR ExternalEntity, IN ULONG AssocID, IN const char * szAssociationFormat, IN PRM_STACK_RECORD pSR ); VOID RmUnlinkFromExternalEx( IN PRM_OBJECT_HEADER pObj, IN ULONG LocID, IN UINT_PTR ExternalEntity, IN ULONG AssocID, IN PRM_STACK_RECORD pSR ); VOID RmLinkToExternalFast( // TODO make inline IN PRM_OBJECT_HEADER pObj ); VOID RmUnlinkFromExternalFast( // TODO make inline IN PRM_OBJECT_HEADER pObj ); VOID RmTmpReferenceObject( IN PRM_OBJECT_HEADER pObj, IN PRM_STACK_RECORD pSR ); VOID RmTmpDereferenceObject( IN PRM_OBJECT_HEADER pObj, IN PRM_STACK_RECORD pSR ); // // Generic resource management // RM_STATUS RmLoadGenericResource( IN PRM_OBJECT_HEADER pObj, IN UINT GenericResourceID, IN PRM_STACK_RECORD pSR ); VOID RmUnloadGenericResource( IN PRM_OBJECT_HEADER pObj, IN UINT GenericResourceID, IN PRM_STACK_RECORD pSR ); VOID RmUnloadAllGenericResources( IN PRM_OBJECT_HEADER pObj, IN PRM_STACK_RECORD pSR ); // // Diagnostic per-object tracking of arbitrary "associations" // // // NOTE: AssociationID must not have the high-bit set. Associations with the // high bit set are reserved for internal use of the Rm API implementation. // VOID RmDbgAddAssociation( IN ULONG LocID, IN PRM_OBJECT_HEADER pObject, IN ULONG_PTR Instance1, IN ULONG_PTR Instance2, IN ULONG AssociationID, IN const char * szFormatString, OPTIONAL IN PRM_STACK_RECORD pSR ); VOID RmDbgDeleteAssociation( IN ULONG LocID, IN PRM_OBJECT_HEADER pObject, IN ULONG_PTR Entity1, IN ULONG_PTR Entity2, IN ULONG AssociationID, IN PRM_STACK_RECORD pSR ); VOID RmDbgPrintAssociations( IN PRM_OBJECT_HEADER pObject, IN PRM_STACK_RECORD pSR ); // // Diagnostic per-object logging. // VOID RmDbgLogToObject( IN PRM_OBJECT_HEADER pObject, IN char * szPrefix, OPTIONAL IN char * szFormatString, IN UINT_PTR Param1, IN UINT_PTR Param2, IN UINT_PTR Param3, IN UINT_PTR Param4, IN PFN_DBG_DUMP_LOG_ENTRY pfnDumpEntry, OPTIONAL IN PVOID pvBuf OPTIONAL ); VOID RmDbgPrintObjectLog( IN PRM_OBJECT_HEADER pObject ); VOID RmDbgPrintGlobalLog(VOID); // // Groups of Objects // VOID RmInitializeGroup( IN PRM_OBJECT_HEADER pOwningObject, IN PRM_STATIC_OBJECT_INFO pStaticInfo, IN PRM_GROUP pGroup, IN const char* szDescription, IN PRM_STACK_RECORD pSR ); VOID RmDeinitializeGroup( IN PRM_GROUP pGroup, IN PRM_STACK_RECORD pSR ); RM_STATUS RmLookupObjectInGroup( IN PRM_GROUP pGroup, IN ULONG Flags, // Lookup flags defined below IN PVOID pvKey, IN PVOID pvCreateParams, OUT PRM_OBJECT_HEADER * ppObject, OUT INT * pfCreated, IN PRM_STACK_RECORD pSR ); // // Lookup flags // #define RM_CREATE 0x1 #define RM_NEW (0x1<<1) #define RM_LOCKED (0x1<<2) #define RM_CREATE_AND_LOCK_OBJECT_IN_GROUP(_pGrp, _pKey, _pParams, _ppHdr, _fC,_psr)\ RmLookupObjectInGroup( \ (_pGrp), \ RM_CREATE|RM_NEW|RM_LOCKED, \ (_pKey), \ (_pParams), \ (_ppHdr), \ (_fC), \ (_psr) \ ); // RM_STATUS // RM_LOOKUP_AND_LOCK_OBJECT_IN_GROUP( // PRM_GROUP _pGrp, // PVOID _pKey, // PRM_OBJECT_HEADER * _ppHdr, // PRM_STACK_RECORD _psr // ) // Lookup (don't create) and lock an object in the specified group. // #define RM_LOOKUP_AND_LOCK_OBJECT_IN_GROUP(_pGrp, _pKey, _ppHdr, _psr) \ RmLookupObjectInGroup( \ (_pGrp), \ RM_LOCKED, \ (_pKey), \ NULL, \ (_ppHdr), \ NULL, \ (_psr) \ ); RM_STATUS RmGetNextObjectInGroup( IN PRM_GROUP pGroup, IN PRM_OBJECT_HEADER pCurrentObject, OPTIONAL OUT PRM_OBJECT_HEADER * ppNextObject, IN PRM_STACK_RECORD pSR ); VOID RmFreeObjectInGroup( IN PRM_GROUP pGroup, IN PRM_OBJECT_HEADER pObject, IN struct _RM_TASK *pTask, OPTIONAL IN PRM_STACK_RECORD pSR ); VOID RmFreeAllObjectsInGroup( IN PRM_GROUP pGroup, IN struct _RM_TASK *pTask, OPTIONAL IN PRM_STACK_RECORD pSR ); VOID RmUnloadAllObjectsInGroup( IN PRM_GROUP pGroup, PFN_RM_TASK_ALLOCATOR pfnUnloadTaskAllocator, PFN_RM_TASK_HANDLER pfnUnloadTaskHandler, PVOID pvUserParam, IN struct _RM_TASK *pTask, OPTIONAL IN UINT uTaskPendCode, OPTIONAL IN PRM_STACK_RECORD pSR ); VOID RmEnableGroup( IN PRM_GROUP pGroup, IN PRM_STACK_RECORD pSR ); // Enumeration function prototype. This function is passed into // RmEnumerateObjectsInGroup and gets called for each object in the group // until the function returns FALSE. // typedef INT (*PFN_RM_GROUP_ENUMERATOR) ( PRM_OBJECT_HEADER pHdr, PVOID pvContext, PRM_STACK_RECORD pSR ); VOID RmEnumerateObjectsInGroup( PRM_GROUP pGroup, PFN_RM_GROUP_ENUMERATOR pfnFunction, PVOID pvContext, INT fStrong, PRM_STACK_RECORD pSR ); VOID RmWeakEnumerateObjectsInGroup( PRM_GROUP pGroup, PFN_RM_GROUP_ENUMERATOR pfnFunction, PVOID pvContext, PRM_STACK_RECORD pSR ); // // Task APIs // VOID RmInitializeTask( IN PRM_TASK pTask, IN PRM_OBJECT_HEADER pParentObject, IN PFN_RM_TASK_HANDLER pfnHandler, IN PRM_STATIC_OBJECT_INFO pStaticInfo, OPTIONAL IN const char * szDescription, OPTIONAL IN UINT Timeout, IN PRM_STACK_RECORD pSR ); RM_STATUS RmStartTask( IN PRM_TASK pTask, IN UINT_PTR UserParam, IN PRM_STACK_RECORD pSR ); VOID RmAbortTask( IN PRM_TASK pTask, IN PRM_STACK_RECORD pSR ); VOID RmDbgDumpTask( IN PRM_TASK pTask, IN PRM_STACK_RECORD pSR ); RM_STATUS RmSuspendTask( IN PRM_TASK pTask, IN UINT SuspendContext, IN PRM_STACK_RECORD pSR ); VOID RmUnsuspendTask( IN PRM_TASK pTask, IN PRM_STACK_RECORD pSR ); VOID RmResumeTask( IN PRM_TASK pTask, IN UINT_PTR SuspendCompletionParam, IN PRM_STACK_RECORD pSR ); VOID RmResumeTaskAsync( IN PRM_TASK pTask, IN UINT_PTR SuspendCompletionParam, IN OS_WORK_ITEM * pOsWorkItem, IN PRM_STACK_RECORD pSR ); VOID RmResumeTaskDelayed( IN PRM_TASK pTask, IN UINT_PTR SuspendCompletionParam, IN ULONG MsDelay, IN OS_TIMER * pOsTimerObject, IN PRM_STACK_RECORD pSR ); VOID RmResumeDelayedTaskNow( IN PRM_TASK pTask, IN OS_TIMER * pOsTimer, OUT PUINT pTaskResumed, IN PRM_STACK_RECORD pSR ); RM_STATUS RmPendTaskOnOtherTask( IN PRM_TASK pTask, IN UINT SuspendContext, IN PRM_TASK pOtherTask, IN PRM_STACK_RECORD pSR ); // See 03/26/1999 notes.txt entry "Some proposed ..." // RM_STATUS RmPendOnOtherTaskV2( IN PRM_TASK pTask, IN UINT SuspendContext, IN PRM_TASK pOtherTask, IN PRM_STACK_RECORD pSR ); VOID RmCancelPendOnOtherTask( IN PRM_TASK pTask, IN PRM_TASK pOtherTask, IN UINT_PTR UserParam, IN PRM_STACK_RECORD pSR ); // // Timer management // VOID RmResetAgeingTimer( IN PRM_OBJECT_HEADER pObj, IN UINT Timeout, IN PRM_STACK_RECORD pSR ); // // Hash table manipulation. // VOID RmInitializeHashTable( PRM_HASH_INFO pHashInfo, PVOID pAllocationContext, PRM_HASH_TABLE pHashTable ); VOID RmDeinitializeHashTable( PRM_HASH_TABLE pHashTable ); BOOLEAN RmLookupHashTable( PRM_HASH_TABLE pHashTable, PRM_HASH_LINK ** pppLink, PVOID pvRealKey ); BOOLEAN RmNextHashTableItem( PRM_HASH_TABLE pHashTable, PRM_HASH_LINK pCurrentLink, // OPTIONAL PRM_HASH_LINK * ppNextLink ); VOID RmAddHashItem( PRM_HASH_TABLE pHashTable, PRM_HASH_LINK * ppLink, PRM_HASH_LINK pLink, PVOID pvKey ); VOID RmRemoveHashItem( PRM_HASH_TABLE pHashTable, PRM_HASH_LINK pLinkToRemove ); typedef VOID (*PFN_ENUM_HASH_TABLE) ( PRM_HASH_LINK pLink, PVOID pvContext, PRM_STACK_RECORD pSR ); VOID RmEnumHashTable( PRM_HASH_TABLE pHashTable, PFN_ENUM_HASH_TABLE pfnEnumerator, PVOID pvContext, PRM_STACK_RECORD pSR ); #if OBSOLETE // // Indexes of objects. // RM_STATUS RmAllocateObjectIndex( IN PRM_OBJECT_HEADER pParentObject, // OBSOLETE IN PRM_OBJECT_ALLOCATOR pObjectAllocator, IN PRM_STATIC_OBJECT_INFO pStaticInfo, IN PULONG Flags, OUT PRM_OBJECT_INDEX * ppObjectIndex, IN PRM_STACK_RECORD pSR ); VOID RmFreeObjectIndex( IN PRM_OBJECT_INDEX pObjectIndex, IN PRM_STACK_RECORD pSR ); RM_STATUS RmLookupObjectInIndex( IN PRM_OBJECT_INDEX pObjectIndex, IN PULONG Flags, // create, remove, lock IN PVOID pvKey, OUT PRM_OBJECT_HEADER * ppObject, IN PRM_STACK_RECORD pSR ); RM_STATUS RmRemoveObjectFromIndex( IN PRM_OBJECT_INDEX pObjectIndex, IN PRM_OBJECT_HEADER pObject, IN PRM_STACK_RECORD pSR ); typedef RM_STATUS (*PFN_RM_OBJECT_INDEX_ENUMERATOR)( IN PRM_OBJECT_HEADER pObject, IN PVOID pvContext, IN PRM_STACK_RECORD pSR ); RmEnumerateObjectsInIndex( IN PRM_OBJECT_INDEX pObjectIndex, IN PFN_RM_OBJECT_INDEX_ENUMERATOR pfnEnumerator, IN PRM_STACK_RECORD pSR ); #endif // OBSOLETE