HAL Structure

In order to write an eCos HAL it's a good idea to have at least a passing understanding of how the HAL interacts with the rest of the system.

HAL Classes

The eCos HAL consists of four HAL sub-classes. This table gives a brief description of each class and partly reiterates the description in Chapter 2. The links refer to the on-line CVS tree (specifically to the sub-HALs used by the PowerPC MBX target).

HAL typeDescriptionFunctionality Overview
Common HAL (hal/common)Configuration options and functionality shared by all HALs.Generic debugging functionality, driver API, eCos/ROM monitor calling interface, and tests.
Architecture HAL (hal/<architecture>/arch)Functionality specific to the given architecture. Also default implementations of some functionality which can be overridden by variant or platform HALs.Architecture specific debugger functionality (handles single stepping, exception-to-signal conversion, etc.), exception/interrupt vector definitions and handlers, cache definition and control macros, context switching code, assembler functions for early system initialization, configuration options, and possibly tests.
Variant HAL (hal/<architecture>/<variant>)Some CPU architectures consist of a number variants, for example MIPS CPUs come in both 32 and 64 bit versions, and some variants have embedded features additional to the CPU core.Variant extensions to the architecture code (cache, exception/interrupt), configuration options, possibly drivers for variant on-core devices, and possibly tests.
Platform HAL (hal/<architecture>/<platform>)Contains functionality and configuration options specific to the platform.Early platform initialization code, platform memory layout specification, configuration options (processor speed, compiler options), diagnostic IO functions, debugger IO functions, platform specific extensions to architecture or variant code (off-core interrupt controller), and possibly tests.
Auxiliary HAL (hal/<architecture>/<module>)Some variants share common modules on the core. Motorola's PowerPC QUICC is an example of such a module.Module specific functionality (interrupt controller, simple device drivers), possibly tests.

File Descriptions

Listed below are the files found in various HALs, with a short description of what each file contains. When looking in existing HALs beware that they do not necessarily follow this naming scheme. If you are writing a new HAL, please try to follow it as closely as possible. Still, no two targets are the same, so sometimes it makes sense to use additional files.

Common HAL

FileDescription
include/dbg-thread-syscall.hDefines the thread debugging syscall function. This is used by the ROM monitor to access the thread debugging API in the RAM application. .
include/dbg-threads-api.hDefines the thread debugging API. .
include/drv_api.hDefines the driver API.
include/generic-stub.hDefines the generic stub features.
include/hal_if.hDefines the ROM/RAM calling interface API.
include/hal_misc.hDefines miscellaneous helper functions shared by all HALs.
include/hal_stub.hDefines eCos mappings of GDB stub features.
src/dbg-threads-syscall.cThread debugging implementation.
src/drv_api.cDriver API implementation. Depending on configuration this provides either wrappers for the kernel API, or a minimal implementation of these features. This allows drivers to be written relying only on HAL features.
src/dummy.cEmpty dummy file ensuring creation of libtarget.a.
src/generic-stub.cGeneric GDB stub implementation. This provides the communication protocol used to communicate with GDB over a serial device or via the network.
src/hal_if.cROM/RAM calling interface implementation. Provides wrappers from the calling interface API to the eCos features used for the implementation.
src/hal_misc.cVarious helper functions shared by all platforms and architectures.
src/hal_stub.cWrappers from eCos HAL features to the features required by the generic GDB stub.
src/stubrom/stubrom.cThe file used to build eCos GDB stub images. Basically a cyg_start function with a hard coded breakpoint.
src/thread-packets.cMore thread debugging related functions.
src/thread-pkts.hDefines more thread debugging related function.

Architecture HAL

Some architecture HALs may add extra files for architecture specific serial drivers, or for handling interrupts and exceptions if it makes sense.

Note that many of the definitions in these files are only conditionally defined - if the equivalent variant or platform headers provide the definitions, those override the generic architecture definitions.

FileDescription
include/arch.incVarious assembly macros used during system initialization.
include/basetype.hEndian, label, alignment, and type size definitions. These override common defaults in CYGPKG_INFRA.
include/hal_arch.hSaved register frame format, various thread, register and stack related macros.
include/hal_cache.hCache definitions and cache control macros.
include/hal_intr.hException and interrupt definitions. Macros for configuring and controlling interrupts. eCos real-time clock control macros.
include/hal_io.hMacros for accessing IO devices.
include/<arch>_regs.hArchitecture register definitions.
include/<arch>_stub.hArchitecture stub definitions. In particular the register frame layout used by GDB. This may differ from the one used by eCos.
include/<arch>.incArchitecture convenience assembly macros.
src/<arch>.ldLinker macros.
src/context.SFunctions handling context switching and setjmp/longjmp.
src/hal_misc.cException and interrupt handlers in C. Various other utility functions.
src/hal_mk_defs.cUsed to export definitions from C header files to assembler header files.
src/hal_intr.cAny necessary interrupt handling functions.
src/<arch>stub.cArchitecture stub code. Contains functions for translating eCos exceptions to UNIX signals and functions for single-stepping.
src/vectors.SException, interrupt and early initialization code.

Variant HAL

Some variant HALs may add extra files for variant specific serial drivers, or for handling interrupts/exceptions if it makes sense.

Note that these files may be mostly empty if the CPU variant can be controlled by the generic architecture macros. The definitions present are only conditionally defined - if the equivalent platform headers provide the definitions, those override the variant definitions.

FileDescription
include/var_arch.hSaved register frame format, various thread, register and stack related macros.
include/var_cache.hCache related macros.
include/var_intr.hInterrupt related macros.
include/var_regs.hExtra register definitions for the CPU variant.
include/variant.incVarious assembly macros used during system initialization.
src/var_intr.cInterrupt functions if necessary.
src/var_misc.chal_variant_init function and any necessary extra functions.
src/variant.SInterrupt handler table definition.
src/<arch>_<variant>.ldLinker macros.

Platform HAL

Extras files may be added for platform specific serial drivers. Extra files for handling interrupts and exceptions will be present if it makes sense.

FileDescription
include/hal_diag.hDefines functions used for HAL diagnostics output. This would normally be the ROM calling interface wrappers, but may also be the low-level IO functions themselves, saving a little overhead.
include/platform.incPlatform initialization code. This includes memory controller, vectors, and monitor initialization. Depending on the architecture, other things may need defining here as well: interrupt decoding, status register initialization value, etc.
include/plf_cache.hPlatform specific cache handling.
include/plf_intr.hPlatform specific interrupt handling.
include/plf_io.hPCI IO definitions and macros. May also be used to override generic HAL IO macros if the platform endianness differs from that of the CPU.
include/plf_stub.hDefines stub initializer and board reset details.
src/hal_diag.cMay contain the low-level device drivers. But these may also reside in plf_stub.c
src/platform.SMemory controller setup macro, and if necessary interrupt springboard code.
src/plf_misc.cPlatform initialization code.
src/plf_mk_defs.cUsed to export definitions from C header files to assembler header files.
src/plf_stub.cPlatform specific stub initialization and possibly the low-level device driver.

The platform HAL also contains files specifying the platform's memory layout. These files are located in include/pkgconf.

Auxiliary HAL

Auxiliary HALs contain whatever files are necessary to provide the required functionality. There are no predefined set of files required in an auxiliary HAL.

2017-02-09
Documentation license for this page: Open Publication License