To be specific, this includes:

• Definitions valid for this architecture and board
  Every board has its own way of initialising (eg; powering up and configuring DRAM or remapping ROM from boot location to normal location). Actual ARM code to do this must be provided.
• Layout and location of data within memory
  Primarily, you must specify the location of the HAL zero page and subsequently locations of various things within that zero page. Also, processor stacks and MMU page table locations and of course code to determine size and location of DRAM is required.

Of course, given that boards will have wildly differing capabilities and configurations, the content provided by the board definition modules will also wildly vary. This chapter documents the absolute minimum required of a board definition module.

On ARM board definitions, one needs to write a BoardDefinesH.s which is a header file included by the Core/ARM files. You also must write a BoardDefines.h file which mirrors the content of BoardDefinesH.s for C code. You will also need to write modules to drive board-specific things like timers or LEDs - these may be in ARM assembler or C, whichever you choose.

The best way of porting to a new board is to take an existing board definition file and alter it. You will find it extensively documented internally to aid quick porting.

On tiny systems with 4Kb of DRAM or more, one must integrate the zero page, static data and User32 program stack into the same 4Kb. To do thus, decrease and shuffle around the generous sizes given to the processor supervisor stacks. Set the ARM linker to place the data within the zero page and make space in the zero page for it to fit (don't forget zero-initialised data). And then change the values for bottom and top of memory returned by BOARD_SETUPMEMORYSYSTEM to the start and end of the zero page. You can determine the size of static C data by subtracting the values of the linker symbols Image$$RW$$Base from Image$$ZI$$Limit (use the ARM debugger to determine these through its list low level symbols operation)

You may specify zero for the number of handlers, but then it is your responsibility to install a handler for that exception. Furthermore, you must ensure that exception is not triggered prior to your installing a handler for it.

You must also specify the sizes of the stacks for each of the ARM processor supervisor modes (IRQ32, FIQ32, Abort32, Undef32 and SVC32):

Furthermore, you must specify the layout of the HAL zero page. The HAL zero page is used as storage by many HAL modules - it is some form of alterable memory available to the HAL from start-up. Most embedded systems will have at least 1k of storage space immediately available to the processor from startup without the need of any setup code - this is ideal for storing the HAL zero page (even if only temporarily). The layout and contents of the zero page is definable by you, and hence may occupy as much or as little space as you desire:

Some of these may change according to debug or standalone builds. If a standalone build is being made, STANDALONE is defined. If the ARM debuggers Angel or Demon are being used to debug a debug build, then ANGEL or DEMON is defined respectively. Use conditional compilation to change memory layouts according build type.

Finally, you must map out where all the possible UART driver context blocks will live within zero page (if at all) which is of course defined by BOARD_HALZP_UARTSPACE above. Typically, these will follow the format:

AT91AUARTID           EQU 2
AT91AUARTADDR         EQU 0xFFFD0000
HALZP_AT91AUARTSPACE  EQU (AT91AUARTID * HALUARTBLK_SIZEOF)

This is the definition of a serial UART called AT91A. The ID is the index of the number of structures into the zero page UART space - so, for example, the first UART context would be 0, the next 1, the next 2 etc. You see how this works as HALZP_AT91AUARTSPACE is set to the ID multiplied by the size of the UART context structure, HALUARTBLK_SIZEOF. To maintain good form, the UART hardware address is also specified here (as AT91UARTADDR) to aid ease of changing the hardware in the future - however, your UART may not need this.

On ARM's with an MMU and 16k of space to store L1 page tables, this is easy. However, for smaller embedded implementations there simply isn't enough space so a hardware solution is provided which allows a write to a register to remap ROM and replace it with RAM.

The ARM's three stage pipeline is used to offset the program counter by the required amount in the instruction just postceding the write to the hardware register. Hence on exit from this macro the program counter may be many megabytes from where it was.

The exact nature of the code required to perform this remap is outside the scope of this manual. However, NedHAL does not require RAM to exist at 0x00000000 and hence for an initial port you may not need to place any code in this macro.

Note also that this macro's contents are not used in debug builds of NedHAL

When this macro exits, DRAM should be fully accessible. NedHAL subsequent to this sets up the User32 stack at the end of DRAM and copies static C and assembler data into the start of DRAM (on STANDALONE builds only - debug builds vary)

Note also that this macro's contents are not used in debug builds of NedHAL

The location of the zero page is left entirely up to you. See the Miscellaneous section above for tips concerning location, size and layout of the HAL zero page.

The value returned by this macro may vary according to debug or standalone builds.

• Determining the memory configuration of the board (eg; size of memory, whether it is contiguous or not)
• Building ARM MMU page tables to remap physical memory into a more desirable form (STANDALONE builds only)
• Enabling ARM MMU, write-buffering, caching and other performance features
• Setting locations of the base and top of DRAM

The ARM control modules ARMCore, ARMCache and ARMMMU have API's to help you in writing this macro. To write the base and top of DRAM, write members HALZP_DRAMBASE and HALZP_DRAMTOP within the HAL zero page with suitable addresses.

Failing to disable the unknown interrupt may cause the interrupt exception handler code to be reentered immediately on exit from the handler, thus locking up the machine.

Typical things to do here are to initialise board modules eg; propriatery timer driver modules. One might also set up debug output through the DebugIO module to use propriatery serial UART driver modules.