Production-Quality OAL Components (Compact 2013)

  • Article

10/16/2014

The production-quality OEM adaptation layer (PQOAL) model divides the original monolithic OAL into a collection of modular libraries. Each library is a functional component within the OAL.

Although the library code's location depends on the scope of the hardware it supports, the code is grouped in the following categories:

  • Common
    Code that is not hardware-specific.
  • CPU family
    Code that is unique to the CPU family.
  • Chip-specific
    Code that is unique to a specific CPU or system-on-a-chip (SOC) model
  • Platform
    Code that is unique to a specific board implementation

Each library provides an external interface consisting of functions and global variables that communicate among the other modular libraries and the OAL and the kernel.

The collection of modular libraries that are available with the PQOAL model are described in the following sections.

Boot Arguments Library

The boot arguments library passes parameters from the boot loader to the kernel in a uniform way on devices that use a boot loader. It does not export any function or variable to the kernel. The boot arguments library uses encapsulated data types for each component that is being initialized. With this approach, you can maintain component separation and still add components in the future without affecting existing components. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_args.h.

The boot arguments library relies on image configuration parameters to locate the shared data area. If a component has specified a configuration data type, you include this data type in the OEM-defined BSP_ARGS type and then the boot loader configures it.

BSP_ARGS relies on a standard header, OAL_ARGS_HEADER, to validate the data. In OEMInit, the signature is validated. If the signature is invalid, the OAL might assume that the BSP_ARGS parameters are not initialized.

Cache Library

The cache library implements the cache and translation look-aside buffer (TLB) operations. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_cache.h.

The internal library exports only two functions: the OEMCacheRangeFlush function and the IOCTL call to the kernel. In the common library, OEMCacheRangeFlush decodes the dwFlags parameter and calls the appropriate internal functions.

Ethernet Drivers Library

The Ethernet drivers library implements Ethernet kernel independent transport layer (KITL) device drivers, which are implemented in the common library.

The %_WINCEROOT%\Platform\Common\Src\Inc\Oal_ethdrv.h file contains prototypes for the Ethernet KITL device drivers. For information about the function prototypes, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_kitl.h.

Flash Library

The flash library implements code for flash memory operations. The PQOAL implementation provides generic solutions for JEDEC-compliant flash memory.

Interrupt Library

The interrupt library implements interrupt processing. A combination of OAL common routines and processor-specific routines provide support for interrupts.

Depending on the CPU or SOC model, you can implement the interrupt library with hardware platform callbacks. This method is useful on hardware that uses an external secondary interrupt controller.

For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_intr.h.

Interrupt Latency Timing Library

The interrupt latency timing library implements the ILTiming functionality, which you typically use during the development process. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_ilt.h.

I/O Library

The I/O library implements I/O functions. It also contains functions that you use to map a bus address to a system address, read or write bus configuration space, and power off or power on the bus controller. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_io.h.

IOCTL Library

The IOCTL library provides common OAL implementations for IOCTL codes that are hardware platform-independent. It also provides a central method for configuring IOCTL processing, which removes a source of duplicated code across all hardware platforms and substantially reduces maintenance and test efforts. This also relieves OEMs from having to implement the common functionality.

By using the IOCTL library, OEMs can easily replace OAL functions with custom hardware platform functions through a function callout table that is defined in the configuration directory. A standard hardware platform file, Ioctl.c, includes this configuration table. The function callout table provides a single point of control for all IOCTL processing.

The IOCTL table contains the IOCTL code and a function pointer to handle the IOCTL. The function pointer might be a public OAL function or a hardware platform function. The OAL provides a placeholder function if the IOCTL is unsupported. The placeholder function generates an error message for unimplemented IOCTLs. The IOCTL code and an associated function pointer with the same argument prototype as OEMIoControl define the IOCTL handler.

There are OAL and hardware platform-specific data items relevant to IOCTL processing. The hardware platform code must be able to set OAL IOCTL variables. This is accomplished through global variables in the hardware platform file Ioctl.c. In the Ioctl.c file, the global variables are defined and initialized from configuration parameters defined in the configuration file Ioctl_cfg.h. This approach is necessary to maintain the separation between the OAL and hardware platform code.

The OAL IOCTL library implements the OEMIoControl function. The implementation searches the IOCTL table for the corresponding code that when found executes the function. Because the IOCTL table is a simple table lookup, IOCTL codes closer to the top of the table require less search time. For better performance, position IOCTL codes with a higher execution rate at the top of the table.

For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_ioctl.h.

KITL Library

The OAL KITL library provides a wrapper interface to KITL and the KITL parameters. KITL is not part of the OAL; it is an independent transport layer called by the OAL. For more information, see Kernel Independent Transport Layer.

Logging Library

The logging library provides a single function and zone definitions to trace OAL components in a consistent way. This library provides an interface for consistent tracing of OAL components. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_log.h.

You instrument all function entries and exits with the OAL_FUNC zone using the OALMSG macro, which calls down to the printing routines.

  • Function entry tracing:

    +FuncName( Arg1, Arg2, ... )

  • Function exit tracing:

    -FuncName(rc=x)

    In the function for exit tracing, rc indicates the return code, if present.

By turning on the OAL_FUNC zone trace mask, you can follow the OAL program flow. Use the following guidelines when tracking OAL components:

  • Instrument any error conditions with the OAL_ERROR zones.
    The error string must begin with "ERROR: ".
  • Instrument any warning conditions with the OAL_WARN zones.
    The warning string must begin with "WARNING:".
  • Instrument any informational tracing with the OAL_INFO zone.
    The informational string must begin with "INFO:".

The logging library relies on a global OAL trace mask and uses the underlying output methods provided by the kernel. Trace initially uses serial output, and then switches to KITL if it is enabled.

Memory Library

The memory library implements translation between the physical and virtual memory in the kernel space. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_memory.h.

For x86 and ARM hardware platforms, the implementation uses OEMAddressTable to implement OALVAtoPA and OALPAtoVA functions. Both routines traverse this table to perform the address conversion. The remaining functions are implemented as C/C++ macros.

PCI Library

The PCI library supports a simplified initialization of the PCI configuration space to provide support for the boot loader and OS startup. This library supports bus initialization to enable KITL initialization of a PCI resident network interface card (NIC). For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_pci.h.

OEMPCIBusConfigure accepts the valid PCI memory and I/O address ranges for the hardware platform. The information and associated bridge window registers are hardware platform-specific.

Power Management Library

The power management library implements system suspend-and-resume operations.

In most cases, power management is hardware-dependent. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_power.h.

Profiler Library

The profiler library implements the OAL functions required for kernel profiling. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_profiler.h.

Real-Time Clock Library

The real-time clock library implements functionality for the real-time clock (RTC) by defining the functions OALIoCtlHalInitRTC, OEMGetRealTime, OEMSetRealTime, and OEMSetAlarmTime.

For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_rtc.h and %_WINCEROOT%\Platform\Common\Src\Common\RTC\Timer\Rtc.c.

Timer Library

The timer library implements the system tick or clock. For more information, see %_WINCEROOT%\Platform\Common\Src\Inc\Oal_timer.h.

You can replace the PQOAL implementation, as long as your custom implementation exports the kernel and OAL interfaces. You can replace the timer related functions with the common implementation for the rest of the library.

The PQOAL code implementation assumes the timer has a granularity equal to or higher than 1 millisecond with the ability to reduce and extend the system tick. The code uses system tick manipulation in two situations. It is used in OEMIdle to extend the actual system tick beyond the normal system tick period, which is usually 1 millisecond, before it puts the CPU in idle with OAL. It is also used to return the system to the normal tick period when the system returns from idle. When you use kernel profiling, use the system tick manipulation in OEMProfileTimerEnable to reduce the system tick period. In this case, use the period that is shorter than 1 millisecond. To avoid collisions with possible timer manipulation in OEMIdle, set the maximum idle period to the normal system tick period.

The PQOAL implements a busy loop in the OALCPUIdle function. Use this implementation for development only. In the product you release to customers, use the OEMIdle stub, if your hardware does not support idle mode.

See Also

Reference

Production-Quality OAL Reference