Comtrol eCos - Manual (Page 343)

Chapter 11. Porting Guide
1. Make a new directory for the new architecture under the hal directory in the source repository. Make an arch
directory under this and populate this with the standard set of package directories.
2. Copy the CDL file from an example HAL changing its name to match the new HAL. Edit the file, changing
option names as appropriate. Delete any options that are specific to the original HAL, and and any new options
that are necessary for the new architecture. This is likely to be a continuing process during the development of
the HAL. See
the Section called CDL Requirements for more details.
3. Copy the hal_arch.h file from an example HAL. Within this file you need to change or define the following:
• Define the HAL_SavedRegisters structure. This may need to reflect the save order of any group register
save/restore instructions, the interrupt and exception save and restore formats, and the procedure calling
conventions. It may also need to cater for optional FPUs and other functional units. It can be quite difficult
to develop a layout that copes with all requirements.
• Define the bit manipulation routines, HAL_LSBIT_INDEX() and HAL_MSBIT_INDEX() . If the architecture
contains instructions to perform these, or related, operations, then these should be defined as inline assem-
bler fragments. Otherwise make them calls to functions.
• Define HAL_THREAD_INIT_CONTEXT() . This initializes a restorable CPU context onto a stack pointer so
that a later call to HAL_THREAD_LOAD_CONTEXT() or HAL_THREAD_SWITCH_CONTEXT() will execute it
correctly. This macro needs to take account of the same optional features of the architecture as the definition
of HAL_SavedRegisters.
• Define HAL_THREAD_LOAD_CONTEXT() and HAL_THREAD_SWITCH_CONTEXT() . These should just be calls
to functions in context.S .
• Define HAL_REORDER_BARRIER() . This prevents code being moved by the compiler and is necessary in
some order-sensitive code. This macro is actually defined identically in all architecture, so it can just be
copied.
• Define breakpoint support. The macro HAL_BREAKPOINT(label) needs to be an inline assembly frag-
ment that invokes a breakpoint. The breakpoint instruction should be labeled with the label argument.
HAL_BREAKINST and HAL_BREAKINST_SIZE define the breakpoint instruction for debugging purposes.
• Define GDB support. GDB views the registers of the target as a linear array, with each register having a
well defined offset. This array may differ from the ordering defined in HAL_SavedRegisters. The macros
HAL_GET_GDB_REGISTERS() and HAL_SET_GDB_REGISTERS() translate between the GDB array and the
HAL_SavedRegisters structure. The HAL_THREAD_GET_SAVED_REGISTERS() translates a stack pointer
saved by the context switch macros into a pointer to a HAL_SavedRegisters structure. Usually this is a
one-to-one translation, but this macro allows it to differ if necessary.
• Define long jump support. The type hal_jmp_buf and the functions hal_setjmp() and hal_longjmp()
provide the underlying implementation of the C library setjmp() and longjmp() .
• Define idle thread action. Generally the macro HAL_IDLE_THREAD_ACTION() is defined to call a function
in hal_misc.c .
• Define stack sizes. The macros CYGNUM_HAL_STACK_SIZE_MINIMUM and
CYGNUM_HAL_STACK_SIZE_TYPICAL should be defined to the minimum size for any thread stack and a
reasonable default for most threads respectively. It is usually best to construct these out of component sizes
for the CPU save state and procedure call stack usage. These definitions should not use anything other than
numerical values since they can be used from assembly code in some HALs.
• Define memory access macros. These macros provide translation between cached and uncached and physical
memory spaces. They usually consist of masking out bits of the supplied address and ORing in alternative
239