Updating the OAL

Article
06/30/2006

When migrating your board support package (BSP), the following changes must be made to the OEM adaptation layer (OAL).

To update the OAL for migration

Implement a variable system timer tick in the OAL.

A variable system timer tick allows for better power management on your BSP. See the sample BSPs for implementation examples. The variable system timer tick function is implemented in your OAL.

For more information, see System Timer.

Update IRQ-to-SYSINTR mappings.

The PCI bus driver requires the ability to obtain and manage the translations for SYSINTR and interrupt request (IRQ) values. The following table shows the functions to implement for the PCI bus driver to work. These functions are exposed through the HAL IOCTLs described in the step 3.

Function	Description
OEMTranslateIrq	Takes an IRQ value and returns a logical interrupt, or SYSINTR, value. If the IRQ maps to more than one SYSINTR, the first mapping is returned.
OEMTranslateSysIntr	Takes a SYSINTR value and returns the corresponding IRQ.
OEMRequestSysIntr	Requests a new logical interrupt, SYSINTR, value for the specified IRQ. This sets up a new mapping in the OAL.
OEMGetInterrupt	Requests an IRQ value for the device location specified.

Add the following HAL IOCTLs, which were added to Windows CE .NET:

Power Manager IOCTLs:
- IOCTL_HAL_DISABLE_WAKE
- IOCTL_HAL_ENABLE_WAKE
VMINI IOCTLs:
KITL IOCTLs:
- IOCTL_KITL_GET_INFO
CEDDK IOCTLs:
- IOCTL_HAL_TRANSLATE_IRQ
  
  Calls OEMTranslateIrq for x86-based OALs, or OEMRequestSysIntr for OALs not based on x86. This IOCTL is implemented for backwards compatibility only. It may be removed in future releases. IOCTL_HAL_REQUEST_SYSINTR should be used instead.
- IOCTL_HAL_REQUEST_IRQ
  
  Calls OEMGetInterrupt and returns an interrupt number for a device based on its bus location. Currently, only the PCI bus is supported.
- IOCTL_HAL_REQUEST_SYSINTR
  
  Calls OEMRequestSysIntr. Only bus drivers should use this IOCTL to request SYSINTRs for their client drivers. Built-in drivers should rely on the OAL to set up an initial IRQ-to-SYSINTR mapping. In all cases, drivers should read their SYSINTRs from the registry.
Filesys.exe IOCTLs:
- IOCTL_HAL_INITREGISTRY
  
  Called by the file system before the registry is generally available to enable the OAL to pre-populate the registry with information about such debugging devices as those used by Kernel Independent Transport Layer (KITL).
Processor IOCTLs:
- IOCTL_PROCESSOR_INFORMATION
  
  Provides such information on the processor as the core, name, vendor, and so on.
Other OAL IOCTLs:
- IOCTL_HAL_POSTINIT
  
  Called after OEMInit to provide a context to perform additional platform initialization.
Remove the following IOCTLs, which are not supported in Windows CE .NET:
- IOCTL_EDBG_REGISTER_CLIENT
- IOCTL_EDBG_DEREGISTER_CLIENT
- IOCTL_EDBG_REGISTER_DFLT_CLIENT
- IOCTL_EDBG_SEND
- IOCTL_EDBG_RECV
- IOCTL_EDBG_SET_DEBUG
- IOCTL_HAL_PROFILE
- IOCTL_COLLECTOR_REGISTER
- IOCTL_COLLECTOR_SEND
- IOCTL_COLLECTOR_UNREGISTER
Modify IOCTL_HAL_GET_DEVICE_INFO to implement a new system parameter, SPI_GETPLATFORMVERSION. This parameter is used in conjunction with SPI_GETPLATFORMTYPE to assign a version number to a platform. The version information is needed because CAB files can now specify that a platform only be installed on the target device if the following conditions are true:
- The platform name matches the one in the CAB file.
- The platform version number is in the range specified in the CAB file.
SPI_GETPLATFORMTYPE can now return an array of strings, and for each string there must be an equivalent platform version structure or the WCELOAD process fails. The platform version structure is defined as follows:
```
typedef struct tagPLATFORMVERSION {
    DWORD dwMajor;
    DWORD dwMinor;
} PLATFORMVERSION, *PPLATFORMVERSION;
```
For example, if you are installing a Windows CE 4.2-based platform that includes the standard SDK, SPI_GETPLATFORMTYPE must return the following platforms strings to WCELOAD:
```
const WCHAR HALPlatformStr[] = L"My OEM Platform\0SSDK\0";
const PLATFORMVERSION HALPlatformVer[TOTALPLATFORMS] = {{n, n}, {4, 2}};
```
The name of your platform is always first, followed by "SSDK" if you have installed the standard SDK as part of your platform.
(Optional) Remove CreateStaticMapping space.
Enable KITL in the BSP or to migrate from Ethernet debug (EDBG) to KITL, as follows:
1. Use the Halkitl.c file from a similar platform. Configure function callback pointers to use the EDBG driver for your platform.
2. In your OAL, only enumerate KITL devices and any special debug or other devices that need to be set up by the OAL. After enumerating these devices, use the PCIReg function call in conjunction with IOCTL_HAL_INITREGISTRY to populate the registry with information on the KITL and other debug devices.
3. Call KitlInit or InitDebugEther, which calls KitlInit. This depends on the Halkitl.c version used. For more information about InitDebugEther, see Active and Passive KITL.
When enabling KITL and your implementation does not work correctly even when all the necessary pieces of code are in place, check PLATFORM_STRING in your boot loader and OAL. The problem may be due to a mismatch in the name that is in your boot loader with the one in your OAL. Microsoft recommends that you define PLATFORM_STRING somewhere in your header file or in Halkitl.c.
Enable interrupt service routines (ISRs). Your ISRs should call NKCallIntChain on shared interrupts and interrupts that are supported on installable ISRs. For details, see Installable ISRs.
Set up and initialize built-in devices.

You should populate the registry with the correct I/O resources information for all the built-in and debug devices on the hardware platform. When the system boots, the Registry Enumerator enumerates the registry and loads all the built-in devices.

I/O resource information includes memory windows such as MemBase and MemLen, I/O windows such as IoBase and IoLen, the interrupt request number (IRQ), and the SYSINTR value that the ISR returns. The initial state of the I/O Resource Manager is set in the registry and should indicate that resources used by the built-in devices are already in use. The I/O Resource Manager tracks the current resources available in the system and then manages all further I/O resource requests and allocations by bus drivers.
(Optional) Add a hive-based registry.

If your hardware platform has persistent storage and it supports the suspend without memory refresh state, then you should use a hive-based registry. Replace the object store-based registry with the hive-based registry in your BSP, adjust the configuration registry keys in your Platform.reg file, and implement a registry flushing strategy.
Support KITL transport.

To support passive KITL, pass pCfgData->KitlTransport — obtained from the Platform Builder user selections in the boot loader — up to the OAL. Use it to decide on the argument to KitlInit. See %_WINCEROOT%\Platform\Cepc\Kernel\Hal\Halkitl.c for more information.

If your SDB has more than one Ethernet port, use one for product Ethernet and another one for debug Ethernet (EDBG).

If your SDB only has one Ethernet port, you can implement one of the following:
- A KITL-based debug Ethernet driver in your boot loader. Use the native Ethernet port for debug and download functionality, and then add virtual network miniport (VMINI) support above the debug Ethernet driver to implement Ethernet sharing. This allows both product and debug Ethernet on the same Ethernet connection. See %_WINCEROOT%\Public\Common\Oak\Drivers\EthDbg\VBridge\Readme.txt for more information.
- A debug Ethernet driver for downloading. Switch to serial debug from the IDE. This assumes that you have implemented the serial debug interface in your boot loader.

Share via

Updating the OAL

See Also

Additional resources