Name

HAL Port — Implementation Details

Overview

This documentation explains how the eCos HAL specification has been mapped onto the SAMA5D3-XPLD board hardware, and should be read in conjunction with that specification. The SAMA5D3-XPLD platform HAL package complements the ARM architectural HAL and the SAMA5D3 variant HAL. It provides functionality which is specific to the target board.

Startup

In the release view of the world the SAMA5D3 Xplained board boots into the BootUp “application loader” from a suitable on-chip RomBOOT supported memory.

When using the second-stage BootUp loader the main (ROMRAM startup type) application is then loaded from the configured non-volatile storage (e.g. NAND, SD card) into the DDR2-SDRAM for execution.

The CPU variant bootstrap overview should be read in conjunction with this documentation.

Following a hard or soft reset the HAL will initialize or reinitialize many of the on-chip peripherals. There is an exception for RAM startup applications which depend on a ROM monitor for certain services, and so will not attempt to re-initialize the underlying peripheral.

For ROM, ROMRAM and SRAM startups the HAL will perform additional initialization, programming the various internal registers including the PLL, peripheral clocks and GPIO pins as required. The details of the early platform hardware startup may be found in the plf_hardware_init() function within the source file src/sama5d3xpld_misc.c.

Memory Map

The SAMA5D3 Xplained HAL package provides the memory layout information needed to generate the linker script. The key memory locations are as follows:

External RAM
This is located at address 0x20000000 of the memory space, and is 256MiB long. For ROM, ROMRAM and SRAM applications the initial 32KiB is set aside, primarily for the first level MMU table and (depending on the startup type) the eCos VSR table. The rest of the RAM is then available for application use. For RAM startup applications the first 1MiB of RAM is reserved for the “debug” monitor (e.g. RedBoot), and the top CYGNUM_HAL_COMMON_INTERRUPTS_STACK_SIZE bytes are reserved for the interrupt stack. The remainder is then available for the RAM application.
Internal RAM
This is located at address 0x00300000 of the memory space, and is 128KiB in size.
On-chip Peripherals
The I/O is primarily accessible from location 0xF0000000 upwards, though some I/O is mapped into the initial 10MiB of the address space. Descriptions of the contents can be found in the Atmel SAMA5D3 Series Datasheet.

Linker Scripts

The platform linker script defines the following symbol:

hal_mmu_page_directory_base
This symbol defines where the initialization code will place the level-1 table when initialising the MMU.

Diagnostic LEDs

Two LEDs are fitted onto the CPU Module for diagnostic purposes, one red and one blue.

The platform HAL header file at <cyg/hal/plf_io.h> defines the following convenience function to allow the LEDs to be controlled:

extern void hal_sama5d3xpld_led(cyg_uint32 bitmask);

The low-order 2-bits of the argument bitmask correspond to each of the 2 LEDs. The red LED is logically mapped to bit 0, with the blue LED mapped to bit 1.

Real-time characterization

The tm_basic kernel test gives statistics gathered about the real-time characterization and performance of the kernel. The sample output is shown here for information. The test was built for RAM startup, where both code and data are using the external DDR2-SDRAM.

Example 280.1. sama5d3xpld Real-time characterization

             Startup, main thrd : stack used   388 size  1792
             Startup :  Interrupt stack used  4096 size  4096
             Startup : Idlethread stack used    96 size  1280

eCos Kernel Timings
Notes: all times are in microseconds (.000001) unless otherwise stated

Reading the hardware clock takes 1 'ticks' overhead
... this value will be factored out of all other measurements
Clock interrupt took    2.97 microseconds (24 raw clock ticks)

Testing parameters:
   Clock samples:            32
   Threads:                  64
   Thread switches:         128
   Mutexes:                  32
   Mailboxes:                32
   Semaphores:               32
   Scheduler operations:    128
   Counters:                 32
   Flags:                    32
   Alarms:                   32
   Stack Size:             1088


                                 Confidence
     Ave     Min     Max     Var  Ave  Min  Function
  ======  ======  ======  ====== ========== ========
    1.60    1.09    5.09    0.29   65%  34% Create thread
    0.18    0.12    1.21    0.08   96%  65% Yield thread [all suspended]
    0.21    0.12    1.21    0.09   87%  53% Suspend [suspended] thread
    0.17    0.12    1.33    0.08   95%  75% Resume thread
    0.27    0.12    2.30    0.08   84%  10% Set priority
    0.02    0.00    0.48    0.04   87%  87% Get priority
    0.64    0.48    5.33    0.19   93%  82% Kill [suspended] thread
    0.18    0.12    1.09    0.07   98%  65% Yield [no other] thread
    0.36    0.24    1.82    0.09   48%  39% Resume [suspended low prio] thread
    0.17    0.12    1.33    0.07   96%  75% Resume [runnable low prio] thread
    0.25    0.12    1.82    0.06   75%  18% Suspend [runnable] thread
    0.18    0.12    1.09    0.08   96%  65% Yield [only low prio] thread
    0.15    0.12    0.97    0.05   82%  82% Suspend [runnable->not runnable]
    0.58    0.48    4.36    0.14   93%  93% Kill [runnable] thread
    0.56    0.48    3.15    0.11   95%  78% Destroy [dead] thread
    0.96    0.85    5.21    0.17   93%  89% Destroy [runnable] thread
    1.51    1.09    6.18    0.26   68%  48% Resume [high priority] thread
    0.40    0.36    1.21    0.05   74%  74% Thread switch

    0.02    0.00    0.24    0.03   87%  87% Scheduler lock
    0.11    0.00    0.24    0.01   92%   6% Scheduler unlock [0 threads]
    0.12    0.00    0.36    0.01   92%   6% Scheduler unlock [1 suspended]
    0.12    0.00    0.24    0.02   89%   7% Scheduler unlock [many suspended]
    0.12    0.00    0.36    0.01   92%   5% Scheduler unlock [many low prio]

    0.07    0.00    0.73    0.08   96%  59% Init mutex
    0.24    0.12    1.82    0.11   46%  46% Lock [unlocked] mutex
    0.27    0.12    2.06    0.14   56%  90% Unlock [locked] mutex
    0.22    0.12    1.21    0.12   90%  90% Trylock [unlocked] mutex
    0.19    0.12    1.45    0.11   90%  78% Trylock [locked] mutex
    0.03    0.00    0.24    0.04   81%  81% Destroy mutex
    1.25    1.09    2.79    0.10   90%   6% Unlock/Lock mutex

    0.19    0.00    1.09    0.11   78%  12% Create mbox
    0.03    0.00    0.73    0.05   90%  90% Peek [empty] mbox
    0.33    0.24    1.82    0.14   87%  87% Put [first] mbox
    0.02    0.00    0.61    0.04   96%  96% Peek [1 msg] mbox
    0.31    0.24    1.70    0.12   93%  93% Put [second] mbox
    0.02    0.00    0.48    0.03   96%  96% Peek [2 msgs] mbox
    0.29    0.12    1.82    0.12   81%  12% Get [first] mbox
    0.28    0.12    1.58    0.10   84%  12% Get [second] mbox
    0.28    0.12    1.33    0.10   81%  12% Tryput [first] mbox
    0.22    0.12    0.97    0.09   43%  43% Peek item [non-empty] mbox
    0.25    0.12    1.45    0.09   59%  31% Tryget [non-empty] mbox
    0.22    0.12    1.21    0.09   50%  46% Peek item [empty] mbox
    0.21    0.12    1.21    0.09   96%  50% Tryget [empty] mbox
    0.02    0.00    0.36    0.04   90%  90% Waiting to get mbox
    0.02    0.00    0.48    0.04   90%  90% Waiting to put mbox
    0.09    0.00    1.58    0.12   93%  68% Delete mbox
    0.95    0.73    3.15    0.17   90%  78% Put/Get mbox

    0.05    0.00    0.85    0.08   93%  84% Init semaphore
    0.17    0.12    1.09    0.09   93%  81% Post [0] semaphore
    0.23    0.12    1.21    0.10   46%  43% Wait [1] semaphore
    0.16    0.12    0.97    0.06   90%  90% Trywait [0] semaphore
    0.14    0.12    0.48    0.03   93%  93% Trywait [1] semaphore
    0.05    0.00    0.61    0.07   75%  75% Peek semaphore
    0.03    0.00    0.73    0.05   90%  90% Destroy semaphore
    0.87    0.73    2.55    0.11   68%  28% Post/Wait semaphore

    0.14    0.00    0.97    0.08   65%  18% Create counter
    0.04    0.00    0.48    0.06   75%  75% Get counter value
    0.02    0.00    0.24    0.03   90%  90% Set counter value
    0.22    0.12    0.73    0.07   56%  37% Tick counter
    0.03    0.00    0.73    0.06   87%  87% Delete counter

    0.03    0.00    0.61    0.06   84%  84% Init flag
    0.19    0.12    1.45    0.10   96%  78% Destroy flag
    0.15    0.12    0.73    0.05   87%  87% Mask bits in flag
    0.19    0.12    0.97    0.09   93%  62% Set bits in flag [no waiters]
    0.28    0.12    2.18    0.12   75%  93% Wait for flag [AND]
    0.30    0.24    1.70    0.10   96%  84% Wait for flag [OR]
    0.29    0.24    1.70    0.09   96%  96% Wait for flag [AND/CLR]
    0.28    0.12    1.94    0.10   84%  12% Wait for flag [OR/CLR]
    0.00    0.00    0.12    0.01   96%  96% Peek on flag

    0.17    0.00    1.21    0.12   75%  18% Create alarm
    0.31    0.12    2.42    0.15   84%  81% Initialize alarm
    0.16    0.12    0.97    0.06   90%  90% Disable alarm
    0.31    0.12    2.55    0.14   93%  93% Enable alarm
    0.19    0.12    1.09    0.09   93%  71% Delete alarm
    0.24    0.12    0.61    0.03   84%  12% Tick counter [1 alarm]
    1.02    0.97    1.70    0.07   81%  81% Tick counter [many alarms]
    0.40    0.24    1.70    0.09   90%   6% Tick & fire counter [1 alarm]
    5.85    5.70    7.15    0.09   78%  15% Tick & fire counters [>1 together]
    1.19    1.09    2.55    0.12   93%  56% Tick & fire counters [>1 separately]
    2.31    2.30    3.64    0.02   99%  99% Alarm latency [0 threads]
    2.54    2.30    3.27    0.12   50%  18% Alarm latency [2 threads]
    2.82    2.55    3.88    0.16   70%  35% Alarm latency [many threads]
    3.07    3.03    7.39    0.07   97%  97% Alarm -> thread resume latency

    1.02    0.97    2.18    0.00            Clock/interrupt latency

    0.68    0.48    1.45    0.00            Clock DSR latency

     221     136     264                    Worker thread stack used (stack size 1088)
            All done, main thrd : stack used   988 size  1792
            All done :  Interrupt stack used   156 size  4096
            All done : Idlethread stack used   240 size  1280

Timing complete - 29800 ms total

PASS:<Basic timing OK>
EXIT:<done>

Data integrity on the on-board NAND

The HAL port only provides ECC protection for the main area of the on-board MT29F2G08 NAND array. (This is achieved using the SAMA5D3 CPU's internal PMECC unit.)

Applications using the NAND library to store data in the spare area of the array should consider whether they ought to employ ECC or comparable protection for the data stored there. The recommended correction capacity for this part is 4 bits per quarter-page; refer to the MT29F2G08 datasheet for full details.

[Caution]Caution

The consequences of insufficient ECC protection are difficult to predict but are likely to include data corruption, undetected by the driver, at a higher rate than expected.