CeLogImportTable_V5 (Compact 2013)

Article
08/12/2016

3/28/2014

Windows Embedded Compact supports a CeLogImportTable_V5 structure for use with IOCTL_CELOG_IMPORT. For more information, see IOCTL_CELOG_IMPORT.

This structure and the previous CeLogImportTable structure, version 4, differ in that the function pointers are now strongly typed, and the table includes six new function pointers. To use this structure, event tracking libraries must also set the dwVersion member to 5 before calling IOCTL_CELOG_IMPORT.

Event tracking libraries built with older structures will continue to work on newer versions of the operating system, but new event tracking libraries should use CeLogImportTable_V5.

This structure is used in conjunction with IOCTL_CELOG_IMPORT, which is the I/O control used by the CeLog DLL to request information about the kernel.

Because an event tracking library loads into the kernel, the kernel often calls CeLogData from within parts of the kernel where it is not safe to make system calls. These restrictions mean that it is not safe to interact with the kernel debugger to perform activities such as setting a breakpoint, or stepping through the code in the debugger.

In addition, it is not safe to call the functions in this structure that are logged during restricted parts of the kernel. Failing to follow these restrictions might cause an unrecoverable system crash.

Syntax

typedef struct {
    DWORD    dwVersion;
    PFN_CeLogImport_CreateEventW              pCreateEventW;
    PFN_CeLogImport_EventModify               pEventModify;
    PFN_CeLogImport_CreateFileMappingW        pCreateFileMappingW;
    PFN_CeLogImport_MapViewOfFile             pMapViewOfFile;
    PFN_CeLogImport_UnmapViewOfFile           pUnmapViewOfFile;
    PFN_CeLogImport_CloseHandle               pCloseHandle;
    PFN_CeLogImport_LockPages                 pLockPages;
    PFN_CeLogImport_UnlockPages               pUnlockPages;
    PFN_CeLogImport_VirtualAlloc              pVirtualAlloc;
    PFN_CeLogImport_VirtualFree               pVirtualFree;
    PFN_CeLogImport_MapPtrToProcess           pMapPtrToProcess;
    PFN_CeLogImport_QueryPerformanceCounter   pQueryPerformanceCounter;
    PFN_CeLogImport_QueryPerformanceFrequency pQueryPerformanceFrequency;
    PFN_CeLogImport_NKDbgPrintfW              pNKDbgPrintfW;
    PFN_CeLogImport_CeLogReSync               pCeLogReSync;
    PFN_CeLogImport_GetLastError              pGetLastError;
    PFN_CeLogImport_SetLastError              pSetLastError;
    PFN_CeLogImport_GetThreadCallStack        pGetThreadCallStack;
    PFN_CeLogImport_InSysCall                 pInSysCall;
    DWORD*   pdwCeLogTLBMiss;
    DWORD    dwCeLogLargeBuf;
    DWORD    dwCeLogSmallBuf;
    DWORD    dwDefaultThreadQuantum;
    DWORD    dwNumberOfCPUs;
    PFN_CeLogImport_RegQueryValueExW          pRegQueryValueExW;
    PFN_CeLogImport_CeLogData                 pCeLogData;
    PFN_CeLogImport_AcquireCeLogSpinLock      pAcquireCeLogSpinLock;
    PFN_CeLogImport_ReleaseCeLogSpinLock      pReleaseCeLogSpinLock;
    PFN_CeLogImport_GetCurrentCPU             pGetCurrentCPU;
    PFN_CeLogImport_VirtualAllocCopyInKernel  pVirtualAllocCopyInKernel;
    PFN_CeLogImport_QueryPerformanceCounterEx pQueryPerformanceCounterEx; // QPC with interrupt flag
} CeLogImportTable_V5;

Members

Parameter	Description
dwVersion	Specifies the version of this structure. Must be set to 5.
pCreateEventW	Pointer to the DLL version of the CreateEvent function.
pEventModify	Pointer to the DLL version of EventModify. EventModify is used to implement the SetEvent, the ResetEvent, and the PulseEvent functions. The equivalent calls for these are: `SetEvent(h)->pEventModify(h, EVENT_SET)` `ResetEvent(h)->pEventModify(h, EVENT_RESET)` `PulseEvent(h)->pEventModify(h, EVENT_PULSE)` The pEventModify function that you pass as part of this function does nothing if you call it during a KCall. A CeLog DLL can test whether it is in a KCall by using the pInSysCall function that is part of this structure, too.
pCreateFileMapping	Pointer to the DLL version of the CreateFileMapping function.
pMapViewOfFile	Pointer to the DLL version of the MapViewOfFile function. This pointer will be NULL if the kernel does not include support for memory-mapped files.
pUnmapViewOfFile	Pointer to the DLL version of the UnmapViewOfFile function.
pCloseHandle	Pointer to the DLL version of the CloseHandle function.
pLockPages	Pointer to the DLL version of the LockPages function.
pUnlockPagew	Pointer to the DLL version of the UnlockPages function.
pVirtualAlloc	Pointer to the DLL version of the VirtualAlloc function.
pVirtualFree	Pointer to the DLL version of the VirtualFree function.
pMapPtrToProcess	NULL.
pQueryPerformanceCounter	Obsolete. This may not work on SMP; instead, use pQueryPerformanceCounterEx. Pointer to the DLL version of the QueryPerformanceCounter function. The caller must not own the CeLog spinlock while calling this function because that can cause deadlocks on an SMP machine.
pQueryPerformanceFrequency	Pointer to the DLL version of the QueryPerformanceFrequency function.
pNKDbgPrintfW	Pointer to the DLL version of the NKDbgPrintfW function.
pCeLogReSync	Pointer to the DLL's version of CeLogReSync.
pGetLastError	Pointer to the DLL's version of GetLastError.
pSetLastError	Pointer to the DLL's version of SetLastError.
pGetThreadCallStack	Pointer to the DLL's version of GetThreadCallStack.
pInSysCall	Pointer to the DLL version of the InSysCall wrapper function. For information about important restrictions for this function, see the Remarks section.
pdwCeLogTLBMiss	Pointer to the translation look-aside buffer (TLB) miss count. The kernel software TLB miss handler maintains this pointer.
dwCeLogLargeBuf	OEM-changeable large buffer size.
dwCeLogSmallBuf	Deprecated. The value is always 0.
dwDefaultThreadQuantum	Specifies the scheduler's default thread quantum.
dwNumberOfCPUs	Specifies the number of CPUs on the target device.
pRegQueryValueExW	Pointer to the kernel entry point to the NKRegQueryValueExW function.
pCeLogData	Pointer to the kernel entry point to the CeLogData function.
pAcquireCeLogSpinLock	Acquires the CeLog spinlock.
pReleaseCeLogSpinLock	Releases the CeLog spinlock.
pGetCurrentCPU	Gets the processor ID. The caller must own the CeLog spinlock.
pVirtualAllocCopyInKernel	The VirtualAllocCopyEx function with the src and dest parameters set to kernel.
pQueryPerformanceCounterEx	A different version of pQueryPerformanceCounter, one with an interrupt flag. The caller must not own the CeLog spinlock while calling this function because that can cause deadlocks on an SMP machine.

Remarks

The pCeLogData member is a pointer to the CeLogData. Logging libraries can call this function to recursively log data to all CeLog logging libraries.

The pAcquireCeLogSpinLock and the pReleaseCeLogSpinLock members can be used to acquire a spinlock for synchronization inside the CeLogData logging method.

The pGetCurrentCPU member returns the current processor, and can only be called while holding the CeLog spinlock.

The pVirtualAllocCopyInKernel member is a pointer to a version of the VirtualAllocCopyEx function that expects that the source and destination process are the kernel. Event tracking libraries can use this function to allocate uncached copies of virtual addresses.

The pQueryPerformanceCounter and the pQueryPerformanceCounterEx members fail if called while holding any spinlocks, including the CeLogData spinlock.

It is recommended that you use pQueryPerformanceCounterEx, instead of pQueryPerformanceCounter, because on SMP machines, the latter function always fails to return the performance counter. These functions are the same, except in one respect. You must pass an additional flag to pQueryPerformanceCounterEx indicating whether you are calling it during an interrupt. Pass TRUE to pQueryPerformanceCounterEx if you call it during an interrupt; otherwise, pass FALSE. Also, on SMP machines, passing FALSE during an interrupt might cause the system to stop responding.

The pEventModify member fails if it is not currently safe to set the event.

Function Pointer Types

typedef HANDLE (*PFN_CeLogImport_CreateEventW) (LPSECURITY_ATTRIBUTES lpsa, BOOL bManualReset,BOOL bInitialState, LPCWSTR lpName);

typedef BOOL (*PFN_CeLogImport_EventModify) (HANDLE hEvent, DWORD func);

typedef HANDLE (*PFN_CeLogImport_CreateFileMappingW) (HANDLE hFile, LPSECURITY_ATTRIBUTES lpsa, DWORD flProtect, DWORD dwMaxSizeHigh, DWORD dwMaxSizeLow, LPCWSTR lpName);

typedef LPVOID (*PFN_CeLogImport_MapViewOfFile) (HANDLE hMap, DWORD fdwAccess, DWORD dwOffsetHigh, DWORD dwOffsetLow, DWORD cbMap);

typedef BOOL (*PFN_CeLogImport_UnmapViewOfFile) (LPCVOID lpvAddr);

typedef BOOL (*PFN_CeLogImport_CloseHandle) (HANDLE hObject);

typedef BOOL (*PFN_CeLogImport_LockPages) (LPVOID lpvAddress, DWORD cbSize, PDWORD pPFNs, int fOptions);

typedef BOOL (*PFN_CeLogImport_UnlockPages) (LPVOID lpvAddress, DWORD cbSize);

typedef LPVOID (*PFN_CeLogImport_VirtualAlloc) (LPVOID lpAddress, DWORD dwSize, DWORD flAllocationType, DWORD flProtect);

typedef BOOL (*PFN_CeLogImport_VirtualFree) (LPVOID lpAddress, DWORD dwSize, DWORD dwFreeType);

typedef LPVOID (*PFN_CeLogImport_MapPtrToProcess) (LPVOID lpv, HANDLE hProc);

typedef BOOL (*PFN_CeLogImport_QueryPerformanceCounter) (LARGE_INTEGER *lpPerformanceCount);

typedef BOOL (*PFN_CeLogImport_QueryPerformanceFrequency) (LARGE_INTEGER *lpFrequency);

typedef void (*PFN_CeLogImport_NKDbgPrintfW) (LPCWSTR lpszFmt, ...);

typedef BOOL (*PFN_CeLogImport_CeLogReSync) ();

typedef DWORD (*PFN_CeLogImport_GetLastError) ();

typedef VOID (*PFN_CeLogImport_SetLastError) (DWORD dwError);

typedef ULONG (*PFN_CeLogImport_GetThreadCallStack) (HANDLE hThrd, ULONG dwMaxFrames, LPVOID lpFrames, DWORD dwFlags, DWORD dwSkip);

typedef BOOL (*PFN_CeLogImport_InSysCall) ();

typedef LONG (*PFN_CeLogImport_RegQueryValueExW) (HKEY, LPCWSTR, LPDWORD, LPDWORD, LPBYTE, LPDWORD);

typedef void (*PFN_CeLogImport_CeLogData) (BOOL, DWORD, PVOID, DWORD, DWORD, DWORD, DWORD, BOOL);

typedef void (*PFN_CeLogImport_AcquireCeLogSpinLock) (void);

typedef void (*PFN_CeLogImport_ReleaseCeLogSpinLock) (void);

typedef DWORD (*PFN_CeLogImport_GetCurrentCPU) (void);

typedef LPVOID (*PFN_CeLogImport_VirtualAllocCopyInKernel) (LPVOID pAddr, DWORD cbSize, DWORD dwProtect);

typedef BOOL (*PFN_CeLogImport_QueryPerformanceCounterEx) (LARGE_INTEGER *lpPerformanceCount, BOOL fDuringInterrupt);

CeLogImportTable_V5 (Compact 2013)

Syntax

Members

Remarks

Function Pointer Types

See Also

Reference

Other Resources

Additional resources