OEMGLOBAL (Compact 2013)

  • Article

10/16/2014

This structure defines all the functions that the OAL must implement for BSP migration and all the variables that it needs to define.

Syntax

typedef struct _OEMGLOBAL {
        DWORD dwVersion;
        PFN_InitDebugSerial pfnInitDebugSerial;
        PFN_InitPlatform pfnInitPlatform;
        PFN_WriteDebugByte pfnWriteDebugByte;
        PFN_WriteDebugString pfnWriteDebugString;
        PFN_ReadDebugByte pfnReadDebugByte;
        PFN_WriteDebugLED pfnWriteDebugLED;
        PFN_CacheRangeFlush pfnCacheRangeFlush;
        PFN_InitClock pfnInitClock;
        PFN_GetRealTime pfnGetRealTime;
        PFN_SetRealTime pfnSetRealTime;
        FPN_SetAlarmTime pfnSetAlarmTime;
        PFN_QueryPerfCounter pfnQueryPerfCounter;
        PFN_QueryPerfFreq pfnQueryPerfFreq;
        PFN_GetTickCount pfnGetTickCount;
        PFN_Idle pfnIdle;
        PFN_NotifyThreadExit pfnNotifyThreadExit;
        PFN_NotifyReschedule pfnNotifyReschedule;
        PFN_NotifyIntrOccurs pfnNotifyIntrOccurs;
        PFN_UpdateReschedTime pfnUpdateReschedTime;
        DWORD dwDefaultThreadQuantum;
        PFN_PowerOff pfnPowerOff;
        PFN_GetOEMRamTable pfnGetOEMRamTable;
        PFN_GetExtensionDRAM pfnGetExtensionDRAM;
        PFN_EnumExtensionDRAM pfnEnumExtensionDRAM;
        PFN_CalcFSPages pfnCalcFSPages;
        DWORD dwMainMemoryEndAddress;
        PFN_InterruptEnable pfnInterruptEnable;
        PFN_InterruptDisable pfnInterruptDisable;
        PFN_InterruptDone pfnInterruptDone;
        PFN_InterruptMask pfnInterruptMask;
        PFN_InitCoProcRegs pfnInitCoProcRegs;
        PFN_SaveCoProcRegs pfnSaveCoProcRegs;
        PFN_RestoreCoProcRegs pfnRestoreCoProcRegs;
        DWORD cbCoProcRegSize;
        DWORD fSaveCoProcReg;
        PFN_ReadRegistry pfnReadRegistry;
        PFN_WriteRegistry pfnWriteRegistry;
        PFN_RefreshWatchDog pfnRefreshWatchDog;
        DWORD dwWatchDogPeriod;
        DWORD dwWatchDogThreadPriority;
        PFN_ProfileTimerEnable pfnProfileTimerEnable;
        PFN_ProfileTimerDisable pfnProfileTimerDisable;
        DWORD cbErrReportSize;
        PFN_Ioctl pfnOEMIoctl;
        PFN_KDIoctl pfnKDIoctl;
        PFN_IsRom pfnIsRom;
        PFN_MapW32Priority pfnMapW32Priority;
        PFN_SetMemoryAttributes pfnSetMemoryAttributes;
        PFN_IsProcessorFeaturePresent pfnIsProcessorFeaturePresent;
        PFN_HaltSystem pfnHaltSystem;
        PFN_NotifyForceCleanBoot pfnNotifyForceCleanBoot;
        PROMChain_t pROMChain;
        LPVOID pKitlInfo;
        PFNVOID pfnKITLGlobalInit;
        DBGPARAM *pdpCurSettings;
        DWORD_PTR* p__security_cookie;
        DWORD_PTR* p__security_cookie_complement;
        DWORD dwAlarmResolution;
        DWORD dwYearsRTCRollover;
        DWORD dwPlatformFlags;
        struct _NKPagePoolParameters* pPagePoolParam;
        DWORD cpPageOutLow;
        DWORD cpPageOutHigh;
        PCSnapshotSupport pSnapshotSupport;
        DWORD _reserved_[12];
#if defined (x86)
        DWORD _reserved_plat_[16];
#elif defined (ARM)
        DWORD _reserved_plat_[14];
        PFN_PTEUpdateBarrier pfnPTEUpdateBarrier;
        PFN_VFPCoprocControl pfnVFPCoprocControl;
#elif defined (MIPS)
        DWORD _reserved_plat_[16];
#elif defined (SHx)
        DWORD _reserved_plat_[16];
#endif
        BOOL fMPEnable;
        PFN_MpStartAllCPUs pfnStartAllCpus;
        PFN_MpPerCPUInit pfnMpPerCPUInit;
        PFN_MpCpuPowerFunc pfnMpCpuPowerFunc;
        PFN_IpiHandler pfnIpiHandler;
        PFN_SendIPI pfnSendIpi;
        PFN_OEMIdleEx pfnIdleEx;
        PFN_InitInterlockedFunc pfnInitInterlockedFunc;
#if defined (x86)
        PFN_NMIHandler pfnNMIHandler;
        PFN_InterruptHandler pfnInterruptHandler;
        PFNVOID pfnFIQHandler;
        DWORD dwARM1stLvlBits;
        DWORD dwARMCacheMode;
        DWORD f_V6_VIVT_ICache;
        PFN_SaveRestoreVFPCtrlRegs pfnSaveVFPCtrlRegs;
        PFN_SaveRestoreVFPCtrlRegs pfnRestoreVFPCtrlRegs;
        PFN_HandleVFPException pfnHandleVFPExcp;
        PFN_IsVFPFeaturePresent pfnIsVFPFeaturePresent;
        DWORD dwPageTableCacheBits;
        DWORD dwTTBRCacheBits;
#elif defined (MIPS)
        DWORD dwCoProcBits;
        DWORD dwOEMTLBLastIdx;
        DWORD dwArchFlagOverride;
        const BYTE *pIntrPrio;
        const BYTE *pIntrMask;
#elif defined (SHx)
        PFN_NMIHandler pfnNMIHandler;
        DWORD dwSHxIntEventCodeLength
#else
#pragma error("No CPU Defined")
#endif
} OEMGLOBAL, *POEMGLOBAL;

Members

  • dwVersion
    Windows Embedded Compact version.
  • pfnInitPlatform
    Pointer to the function OEMInit.
  • pfnWriteDebugLED
    Pointer to an optional function, OEMWriteDebugLED, that outputs a byte to the target device's specified LED port. If the function is implemented, this member must be initialized.
  • pfnInitClock
    Pointer to the optional OEMInitClock function. If the function is implemented, this member must be initialized.
  • pfnQueryPerfCounter
    Pointer to an optional function, OEMQueryPerformanceCounter, which retrieves the current value of the high-resolution performance counter. If the function is implemented, this member must be initialized.
  • pfnQueryPerfFreq
    Pointer to an optional function, OEMQueryPerformanceFrequency, which retrieves the frequency of the high-resolution performance counter. If the function is implemented, this member must be initialized.
  • pfnIdle
    Pointer to the function OEMIdle.
  • pfnNotifyThreadExit
    Pointer to the optional OEMNotifyThreadExit function, which is called when a thread exits. If the function is implemented, this member must be initialized.
  • pfnNotifyReschedule
    Pointer to the optional OEMNotifyReschedule function, which is called when a new thread is ready to run. If the function is implemented, this member must be initialized.
  • pfnNotifyIntrOccurs
    Pointer to the optional OEMNotifyIntrOccurs function, which is called when an interrupt occurs. If this function is implemented, it must be initialized.
  • pfnUpdateReschedTime
    Pointer to the optional OEMUpdateReschedTime function. If the function is implemented, this member must be initialized.
  • dwDefaultThreadQuantum
    The DefaultThreadQuantum variable. By default, this member is set to DEFAULT_THREAD_QUANTUM.
  • pfnEnumExtensionDRAM
    Pointer to the optional OEMEnumExtensionDRAM function, which returns information about extension DRAM on the device. If the function is implemented, this member must be initialized.
  • pfnCalcFSPages
    Pointer to an optional function that calculates how much memory should be allocated to the object store. By default, points to FakeCalcPage; you can implement OEMCalcFSPages.
  • dwMainMemoryEndAddress
    The dwMainMemoryEndAddress variable, which specifies the next available address following the first available contiguous block of memory. This is an optional variable that is set to 0 by default.
  • pfnInitCoProcRegs
    Pointer to the optional OEMInitCoProcRegs function, which is called by the kernel when a thread is created to initialize the debug registers. If the function is implemented, this member must be initialized.
  • pfnSaveCoProcRegs
    Pointer to the optional OEMSaveCoProcRegs function, which is called by the kernel to save the platform-specific debug registers when a thread switch occurs. If the function is implemented, this member must be initialized.
  • pfnRestoreCoProcRegs
    Pointer to the optional OEMRestoreCoProcRegs function, which is called by the kernel to restore the platform-specific debug registers when a thread switch occurs. If the function is implemented, this member must be initialized.
  • cbCoProcRegSize
    The cbCoProcRegSize variable, which specifies the size of the memory allocation, in bytes, needed for the OEM to save or restore coprocessor registers. This variable is only used if the particular platform or CPU has coprocessor registers that must be saved or restored during context switches.
  • fSaveCoProcReg
    The fSaveCoProcReg variable, which specifies the flag to tell the kernel when the save/restore of coprocessor registers is performed. This variable is set to False by default.
  • pfnReadRegistry
    Pointer to the optional OEMReadRegistry function that reads a registry file into RAM from persistent storage. If the function is implemented, this member must be initialized.
  • pfnWriteRegistry
    Pointer to the optional OEMWriteRegistry function, which is called by the operating system to transfer registry data to persistent storage. If the function is implemented, this member must be initialized.
  • pfnRefreshWatchDog
    Pointer to the optional OEMRefreshWatchDog function, which is called by the kernel to refresh the hardware watchdog. If the function is implemented, this member must be initialized.
  • dwWatchDogPeriod
    The dwWatchDogPeriod variable, which specifies the watchdog period, in milliseconds, where the hardware watchdog must be refreshed before system reset. The default value, 0, indicates that the watchdog timer does not exist.
  • dwWatchDogThreadPriority
    The dwWatchDogThreadPriority variable, which specifies the kernel watchdog thread. By default, this member is set to DEFAULT_WATCHDOG_PRIORITY.
  • pfnProfileTimerEnable
    Pointer to the optional OEMProfileTimerEnable function, which enables an interrupt for the profiler timer. If the function is implemented, this member must be initialized.
  • pfnProfileTimerDisable
    Pointer to the optional OEMProfileTimerDisable function, which clears and disables the interrupt for a profiler timer. If this function is implemented, it must be initialized.
  • cbErrReportSize
    Specifies the amount of memory for the Windows Embedded Compact Error Reporting dump area. By default, this member is set to 0. cbErrReportSize was previously named cbNKDrWatsonSize.
  • pfnKDIoctl
    Pointer to the optional OEMKDIoctl function, which supports requests from the kernel debugger. If this function is implemented, it must be initialized.
  • pfnIsRom
    Pointer to the optional OEMIsRom function, which determines whether a given address range falls within a valid range of ROM addresses. If the function is implemented, this member must be initialized.
  • pfnMapW32Priority
    Pointer to the optional OEMMapW32Priority function, which by default is not implemented. If the function is implemented, this member must be initialized.
  • pfnSetMemoryAttributes
    Pointer to an optional function, OEMSetMemoryAttributes, that supports changes to memory attributes. If this function is implemented, it must be initialized.
  • pfnIsProcessorFeaturePresent
    Pointer to the optional OEMIsProcessorFeaturePresent function that retrieves information about the supported features in your system. If the function is implemented, this member must be initialized.
  • pfnHaltSystem
    Pointer to the optional OEMHaltSystem function that is called when the kernel is about to halt the system. If the function is implemented, this member must be initialized.
  • pfnNotifyForceCleanBoot
    Pointer to the optional OEMNotifyForceCleanBoot function that the kernel calls when the file system is identified as corrupted. It is called before the kernel forces a clean system boot.
  • pROMChain
    Pointer to an optional structure that defines an XIP region. If this structure is implemented, it must be initialized.
  • pKitlInfo
    Pointer to an optional structure that is used to pass platform-specific information from the OAL to the KITL. If this structure is implemented, it must be initialized.
  • pfnKITLGlobalInit
    Specifies the KITL entry point. By default, this is set to KitlDllMain.
  • p__security_cookie
    Pointer to the security cookie for the compiler's /GS build flag.
  • p__security_cookie_complement
    Pointer to the security cookie complement for the compiler's /GS build flag.
  • dwAlarmResolution
    The dwAlarmResolution variable, which specifies the alarm resolution in milliseconds.
  • dwYearsRTCRollover
    The dwYearsRTCRollover variable, which specifies the number of years for real-time clock (RTC) rollover.
  • dwPlatformFlags
    The dwPlatformFlags variable, which contains platform-specific flags.
  • pPagePoolParam
    Pointer to a NKPagePoolParameters structure that stores information about the parameters of the loader page pool and the file page pool.
  • cpPageOutLow
    Optional. Threshold below which page out is started. This member is set in the OEMInitGlobals function to the value of the PageOutLow variable.
  • cpPageOutHigh
    Optional. Threshold above which page out is stopped. This member is set in the OEMInitGlobals function to the value of the PageOutHigh variable.
  • pSnapshotSupport
    Optional. Const pointer to a SnapshotSupport structure that stores OEM-defined callback functions that support snapshot boot. The OEM must provide the address of the SnapshotSupport structure in this member.
  • _reserved_
    Reserved for future use.
  • _reserved_plat_[]
    Reserved for future use.
  • pfnPTEUpdateBarrier
    Pointer to an optional function of the type PFN_PTEUpdateBarrier for updating the barrier to page table entries. Certain ARM CPU designs may need to be notified of page table modifications.
  • pfnVFPCoprocControl
    Pointer to the optional OEMVFPCoProcControl function that sends a command to the Vector Floating Point (VFP) hardware, such as changing the power state of the coprocessor. This function is used on ARM processors that support VFP.
  • fMPEnable
    The fMpEnable variable, which specifies whether multiprocessor support is enabled.
  • pfnStartAllCpus
    Pointer to the OEMMpStartAllCpus function, which is required for multiprocessor support. It runs on the master CPU and starts all non-master CPUs.
  • pfnMpPerCPUInit
    Pointer to the OEMMpPerCPUInit function, which is required for multiprocessor support. It is the first function the kernel calls on each subordinate CPU and it returns the CPU ID.
  • pfnMpCpuPowerFunc
    Pointer to the OEMMpCpuPowerFunc function, which is optional for multiprocessor support. It is called by the kernel to change the power state of a specific CPU.
  • pfnIpiHandler
    Pointer to the OEMIpiHandler function, which is optional for multiprocessor support. It handles platform-specific interprocessor interrupts.
  • pfnSendIpi
    Pointer to the OEMSendIpi function, which is optional for multiprocessor support. It sends interprocessor interrupts.
  • pfnIdleEx
    Pointer to the OEMIdleEx function that places the CPUs in the idle state when there are no threads ready to run. It is required for multiprocessor support if there is more than one CPU to handle per CPUIdle.
  • pfnInitInterlockedFunc
    Pointer to the OEMInitInterlockedFunctions function, which is required for multiprocessor support. It initializes the interlocked function table for the OAL. A default implementation is provided by NKStub.lib for each CPU.
  • pfnNMIHandler
    Pointer to the function OEMNMIHandler. This function is used on x86 processors.
  • pfnInterruptHandler
    Pointer to the function OEMInterruptHandler. This function is used on ARM processors.
  • dwARM1stLvlBits
    The dwARM1stLvlBits variable, which specifies the extra bits to be set in the 1st level page table. This variable is applies only to ARM processors.
  • dwARMCacheMode
    The dwARMCacheMode variable, which specifies C and B bits to build the page tables. dwARMCacheMode is set to 0 by default. This variable applies only to ARM processors.
  • f_V6_VIVT_ICache
    (Deprecated) The f_V6_VIVT_ICache variable, which indicates that the instruction cache is virtually indexed and virtually tagged, by using address space identifiers (ASIDs). This variable applies only to ARMv6 processors.
  • pfnSaveVFPCtrlRegs
    Pointer to the optional OEMSaveVFPCtrlRegs function that is called when the kernel needs to save the state of the extra FPU registers for the current thread. If the function is implemented, this member must be initialized. This function is used on ARM processors if the CPU supports VFP.
  • pfnRestoreVFPCtrlRegs
    Pointer to the optional OEMRestoreVFPCtrlRegs function that is called to restore the state of the extra implementation-defined VFP registers for the current thread. If the function is implemented, this member must be initialized. This function is used on ARM processors if the CPU supports VFP.
  • pfnHandleVFPExcp
    Pointer to the optional OEMHandleVFPException function. This function is called to handle a floating point exception reported by VFP hardware. If the function is implemented, this member must be initialized. This function is used on ARM processors if the CPU supports VFP.
  • pfnIsVFPFeaturePresent
    Pointer to the optional OEMIsVFPFeaturePresent function, which queries the OAL for information about VFP hardware. This function is used on ARM processors that support VFP.
  • dwPageTableCacheBits;
    The dwPageTableCacheBits variable, which specifies cache bits for accessing the inner or outer page table.
  • dwTTBRCacheBits
    The dwTTBRCacheBits variable, which specifies cache bits for page tables in the Translation Table Base Register (TTBR), if the page tables can be cached.
  • dwCoProcBits
    Not supported.
  • dwOEMTLBLastIdx
    Not supported.
  • dwArchFlagOverride
    Not supported.
  • pIntrPrio
    Not supported.
  • pIntrMask
    Not supported.
  • pfnNMIHandler
    Pointer to the function OEMNMIHandler. This function is not supported in Windows Embedded Compact 2013 because SHx processors are not supported.
  • dwSHxIntEventCodeLength
    Specifies interrupt event code length for SHx processors. By default, this is set to SH4_INTEVT_LENGTH. This variable is not supported in Windows Embedded Compact 2013 because SHx processors are not supported.

Remarks

The OEMGLOBAL structure is defined in Public\Common\Oak\Inc\Oemglobal.h.

The initial values for the structure are defined in Oemglobal.c, which is built into OEMMain.lib and OEMMain_StaticKITL.lib. The OAL should link to OEMMain.lib when the KITL is built as a DLL, or to OEMMain_StaticKITL.lib if the KITL is linked into Oalkitl.exe. The two libraries are identical except for differences in the initialization of pfnKITLGlobalInit.

The mandatory functions in OEMGLOBAL are initialized. As a result, when the OAL links with OEMMain.lib or OEMMain_StaticKITL.lib, the OAL must provide the implementation.

On a symmetric multiprocessing system, interrupts remain enabled so IPIs can occur while in a debug break state. In this state, the timer interrupt continues to tick and increment CurMSec. To freeze the system tick during the debug break state, you should implement pfnKdEnableTime in g_pOemGlobal.

Requirements

Header

oemglobal.h

Library

OEMMain.lib or OEMMain_StaticKITL.lib

See Also

Reference

BSP Data Structures
IOCTL_HAL_GET_POOL_PARAMETERS