eCos Product
eCos Net Distribution
RedBoot Product
RedBoot Net Distribution
Supported Hardware
Downloading and Installation
Documentation
FAQ
Keeping in Touch
Problems
Licensing
Anonymous CVS
Contributions and Third Party Projects
|
HAL Layout
The HAL Directory Layout
The eCos HAL consists of four sub-HAL classes. This table gives a
brief description of each class. The links refer to the on-line CVS
tree (specifically to the sub-HALs used by the PowerPC MBX target).
HAL type |
Description |
Functionality 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
Below is listed the files found in various HALs, with a short
description of what the file contains. When looking in existing HALs,
beware that they do not necessarily follow the below naming scheme -
but if you are writing a new HAL, please try to follow the below as
closely as possible. Still, no two targets are the same, so sometimes
it makes sense to use additional files.
Common HAL
File |
Description |
include/dbg-thread-syscall.h |
Defines the thread debugging syscall function. This is used by
the ROM monitor to access the thread debugging API in the RAM
application. [FIXME: link thread debug description]. |
include/dbg-threads-api.h |
Defines the thread debugging API. [FIXME: link thread
debug description]. |
include/drv_api.h |
Defines the driver API. |
include/generic-stub.h |
Defines the generic stub features. |
include/hal_if.h |
Defines the ROM/RAM calling interface API. |
include/hal_misc.h |
Defines miscellaneous helper functions shared by all HALs. |
include/hal_stub.h |
Defines eCos mappings of GDB stub features. |
src/dbg-threads-syscall.c |
Thread debugging implementation. |
src/drv_api.c |
Driver API implementation. Depending on configuration this
provides either wrappers for kernel features, or a minimal
implementation of these features. This allows drivers to be written
relying only on HAL features. |
src/dummy.c |
Empty dummy file ensuring creation of libtarget.a. |
src/generic-stub.c |
Generic GDB stub implementation. [this will likely be replaced
by the bsp stub in the future] |
src/hal_if.c |
ROM/RAM calling interface implementation. Provides wrappers from
the calling interface API to the eCos features used for the
implementation. |
src/hal_misc.c |
Various helper functions shared by all platforms and
architectures. |
src/hal_stub.c |
Wrappers from eCos HAL features to the features required by the
generic GDB stub. |
src/stubrom/stubrom.c |
The file used to build eCos GDB stub images. Basically a
cyg_start function with a hardcoded breakpoint. |
src/thread-packets.c |
More thread debugging related functions. |
src/thread-pkts.h |
Defines more thread debugging related function. |
Architecture HAL
Some architecture HALs may add extra files for architecture
specific serial drivers, or for handling interrupts/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.
File |
Description |
include/arch.inc |
Various assembly macros used during system initialization. |
include/basetype.h |
Endian, label, alignment, and type size definitions. These
override common defaults in CYGPKG_INFRA. |
include/hal_arch.h |
Saved register frame format, various thread, register and stack
related macros. |
include/hal_cache.h |
Cache definitions and cache control macros. |
include/hal_intr.h |
Exception and interrupt definitions. Macros for configuring and
controlling interrupts. eCos real-time clock control macros. |
include/hal_io.h |
Macros for accessing IO devices. |
include/<arch>_regs.h |
Architecture register definitions. |
include/<arch>_stub.h |
Architecture stub definitions. In particular the register frame
layout used by GDB. This may differ from the one used by eCos. |
include/<arch>.inc |
Architecture convenience assembly macros. |
src/<arch>.ld |
Linker macros. |
src/context.S |
Functions handling context switching and setjmp/longjmp. |
src/hal_misc.c |
Execption and interrupt handlers in C. Various other utility
functions. |
src/hal_mk_defs.c |
Used to export definitions from C header files to assembler
header files. |
src/hal_intr.c |
Any necessary interrupt handling functions. |
src/<arch>stub.c |
Architecture stub code. Contains functions for translating eCos
exceptions to UNIX signals and functions for single-stepping. |
src/vectors.S |
Exception, 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.
File |
Description |
include/var_arch.h |
Saved register frame format, various thread, register and stack
related macros. |
include/var_cache.h |
Cache related macros. |
include/var_intr.h |
Interrupt related macros. |
include/var_regs.h |
Extra register definitions for the CPU variant. |
include/variant.inc |
Various assembly macros used during system initialization. |
src/var_intr.c |
Interrupt functions if necessary. |
src/var_misc.c |
hal_variant_init function and any necessary extra functions. |
src/variant.S |
Interrupt handler table definition. |
src/<arch>_<variant>.ld |
Linker macros. |
Platform HAL
Extras files for platform specific serial drivers. Extra files
for handling interrupts/exceptions if it makes sense.
File |
Description |
include/hal_diag.h |
Defines 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.inc |
Platform 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.h |
Platform specific cache handling. |
include/plf_intr.h |
Platform specific interrupt handling. |
include/plf_io.h |
PCI IO definitions and macros. May also be used to override
generic HAL IO macros if the platform endianess differs from that of
the CPU. |
include/plf_stub.h |
Defines stub initializer and board reset details. |
src/hal_diag.c |
May contain the low-level device drivers. But these may also
reside in plf_stub.c |
src/platform.S |
Memory controller setup macro, and if necessary interrupt
springboard code. |
src/plf_misc.c |
Platfor initialization code. |
src/plf_mk_defs.c |
Used to export definitions from C header files to assembler
header files. |
src/plf_stub.c |
Platform 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.
|