The HAL Port
Prev Chapter 283. Atmel SAMA5D3x-CM (CPU Module) Platform HAL Next

Name

HAL Port — Implementation Details

Overview

The SAMA5D3x-CM daughterboard platform HAL package is loaded automatically when eCos is configured for a suitable target, e.g. atsama5d31_ek. It should never be necessary to load this package explicitly. Unloading the package should only happen as a side effect of switching target hardware.

Startup

In the release view of the world (depending on the state of the BMS signal) the SAMA5D3x-CM daughterboard either boots into the BootUp “application loader” from a suitable on-chip RomBOOT supported memory, or alternatively from the EBI-CS0 parallel NOR flash based ROM startup type application.

When using the second-stage BootUp loader the main (ROMRAM startup type) application is then loaded from the configured non-volatile storage (e.g. parallel NOR flash) 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/sama5d3x_mb_misc.c.

Memory Map

The SAMA5D3X_CM 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 512MiB 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.
NOR FLASH
This is located at address 0x10000000 of the memory space and MAY be mapped to 0x00000000 at reset if the SAMA5D3 is so configured. This region is 16MiB in size. ROM applications are by default configured to run from this memory. When RedBoot is being used then this memory is managed by RedBoot's FIS system, otherwise it is the applications responsibility to manage the NOR flash space.
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/sama5d3x_cm_io.h> defines the following convenience function to allow the LEDs to be controlled: 

extern void hal_sama5d3x_cm_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.

[Note]Note

The blue LED on GPIO line PE25 is also used as the 1-wire bus, so accesses to 1-wire devices will cause that LED to flicker.

SPI Dataflash

The variant HAL SPI support provides the necessary underlying SPI bus definition. The CM platform layer defines the spi_dataflash_dev0 device instance describing the SPI Dataflash hardware.

The SPI Dataflash media can only be accessed with the Flash API using the flash device m25pxx_flash_device. For the purposes of this API a placeholder address range has been allocated as if the Flash is present at this address. The base of this address range is 0xE0000000. This reserved range is not real memory and any attempt to access it directly by the processor other than via the Flash API will result in a memory address exception.

A test application at25df321 is provided within the tests subdirectory of the CYGPKG_HAL_ARM_CORTEXA_SAMA5D3X_CM package. This test communicates with the SPI Dataflash on the CM to perform read and write operations using the flash API.

Ethernet Driver

Depending on the processor specific SAMA5D3x-CM module used, either or both EMAC and GMAC Ethernet devices are available to use. The CYGPKG_DEVS_ETH_ARM_AT91 package supports both of these devices. This driver is not active until the generic Ethernet support package, CYGPKG_IO_ETH_DRIVERS, is included in the configuration.

Both the standard (BSD and lwIP compatible) and direct (lwIP only) device drivers are supported. The standard driver is enabled by default; the direct driver can be enabled by setting CYGOPT_IO_ETH_DRIVERS_LWIP_DRIVER_DIRECT option. At the time of writing, the direct driver only supports the EMAC (ETH1), and not the GMAC (ETH0).

RedBoot Installation

[Note]Note

Unless you explicitly need network based debugging, or are interested in other aspects of the RedBoot functionality, it is generally the case that development and debugging using a direct hardware JTAG/SWD approach is generally superior and obviates the need to install RedBoot on the target.

RedBoot, by default, is configured to use the EBI_CS0 NOR flash as storage for its FIS and config information, regardless of whether it is executing from RAM or in place as a ROM application.

Building RedBoot

RedBoot will normally be a ROMRAM startup, since it will be loaded via the second-level bootloader, or loaded directly using a hardware JTAG debugger, into the DDR2-SDRAM memory for execution.

[Note]Note

Pre-built RedBoot binary images are supplied with the eCos release in the loaders sub-directory.

The following example illustrates the command-line steps needed to configure and build a ROMRAM RedBoot: 

$ mkdir redboot_ROMRAM
$ cd redboot_ROMRAM
$ ecosconfig new atsama5d31_ek redboot
$ ecosconfig import $ECOS_REPOSITORY/packages/hal/arm/cortexa/sama5d3/sama5d3x_mb/current/misc/redboot_ROMRAM.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make

However, if required, a ROM based RedBoot can be executed directly from the EBI_CS0 NOR flash when JP9 on the SAMA5D3x-MB motherboard is closed. 

$ mkdir redboot_ROM
$ cd redboot_ROM
$ ecosconfig new atsama5d31_ek redboot
[ … ecosconfig output elided … ]
$ ecosconfig import $ECOS_REPOSITORY/packages/hal/arm/cortexa/sama5d3/sama5d3x_mb/current/misc/redboot_ROM.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make

The RedBoot Location section of the generic SAMA5D3 variant documentation provides a graphical representation of both these ROMRAM and ROM models.

Programming RedBoot

Some hardware debuggers will allow direct programming of the EBI_CS0 NOR flash, but for those that do not provide such support a JTAG loaded ROMRAM executable can be used to load and write the ROM image to its NOR flash destination. For example, if the ROMRAM RedBoot as built above is loaded using a hardware debugger and executed, then the following shows that RAM based RedBoot being used to load a 0x16020 byte long redboot.bin image from a TFTP server and written to the RedBoot FIS section in the NOR. 

RedBoot> load -r -h 192.168.7.39 -b 0x30000000 redboot.bin
Using default protocol (TFTP)
Raw file loaded 0x30000000-0x30016020, assumed entry at 0x30000000
RedBoot> fis unlock RedBoot
... Unlocking from 0x10000000-0x100fffff: ........
RedBoot> fis write -f 0x10000000 -b 0x30000000 -l 0x16020
* CAUTION * about to program FLASH
            at 0x10000000..0x1001ffff from 0x30000000 - continue (y/n)? y
... Erase from 0x10000000-0x1001ffff: .
... Program from 0x30000000-0x30020000 to 0x10000000: .
RedBoot> mcmp -s 0x30000000 -d 0x10000000 -l 0x16020

With the binary image written to the start of the NOR flash, and the motherboard BMS signal suitably configured, then after a power-on reset the board will boot using the ROM RedBoot application. Such a RedBoot world allows for GDB debugging of RAM startup applications loaded via the J8 USART1 serial connection, the 10/100 (EMAC) Ethernet connection, or the 10/10/1000 (GMAC) Ethernet connection. Selection of which Ethernet interface to use is set with the RedBoot fconfig command and its Default network device: entry. Entering at91_eth0 selects the Gigabit Ethernet (J17/GETH) interface, whereas at91_eth1 selects the 10/100 Ethernet (J24/ETH1) interface.

This method of using a RAM based RedBoot, and loading a binary into RAM (or SRAM) before writing to the NOR flash, can be used for any ROM application that needs to be executed from startup with a BMS closed configured platform. Alternatively, Atmel provides tools to work in conjunction with the on-chip SAM-BA monitor that can also be used to program the various CPU Module memories.

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 ROMRAM startup, where both code and data are using the external DDR2-SDRAM.

Example 283.1. sama5d3x_cm Real-time characterization

              Startup, main thrd : stack used   444 size  1792
              Startup :  Interrupt stack used  4096 size  4096
              Startup : Idlethread stack used    88 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.80 microseconds (23 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.67    1.09    2.67    0.31   53%  28% Create thread
     0.17    0.12    0.85    0.07   65%  65% Yield thread [all suspended]
     0.20    0.12    1.33    0.10   85%  59% Suspend [suspended] thread
     0.16    0.12    0.61    0.06   71%  71% Resume thread
     0.26    0.12    0.97    0.05   82%   9% Set priority
     0.01    0.00    0.24    0.02   92%  92% Get priority
     0.62    0.48    3.88    0.15   92%  84% Kill [suspended] thread
     0.17    0.12    0.85    0.07   65%  65% Yield [no other] thread
     0.31    0.24    1.09    0.08   90%  64% Resume [suspended low prio] thread
     0.15    0.12    0.36    0.04   78%  78% Resume [runnable low prio] thread
     0.25    0.12    1.09    0.03   85%   9% Suspend [runnable] thread
     0.18    0.12    1.09    0.07   98%  65% Yield [only low prio] thread
     0.16    0.12    0.61    0.05   78%  78% Suspend [runnable->not runnable]
     0.55    0.48    1.94    0.09   89%  73% Kill [runnable] thread
     0.48    0.36    2.30    0.08   59%  31% Destroy [dead] thread
     0.90    0.73    1.94    0.09   84%   7% Destroy [runnable] thread
     1.30    1.09    3.03    0.19   51%  62% Resume [high priority] thread
     0.42    0.36    1.21    0.06   61%  61% Thread switch

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

     0.08    0.00    0.73    0.09   87%  59% Init mutex
     0.22    0.12    1.21    0.09   46%  46% Lock [unlocked] mutex
     0.27    0.12    1.94    0.14   50%  90% Unlock [locked] mutex
     0.20    0.12    1.09    0.10   90%  62% Trylock [unlocked] mutex
     0.16    0.12    0.61    0.06   78%  78% Trylock [locked] mutex
     0.03    0.00    0.48    0.05   84%  84% Destroy mutex
     1.23    1.21    1.82    0.04   96%  96% Unlock/Lock mutex

     0.19    0.00    0.85    0.09   87%   6% Create mbox
     0.01    0.00    0.36    0.02   96%  96% Peek [empty] mbox
     0.30    0.24    1.45    0.11   90%  90% Put [first] mbox
     0.00    0.00    0.00    0.00  100% 100% Peek [1 msg] mbox
     0.28    0.24    0.61    0.06   81%  81% Put [second] mbox
     0.00    0.00    0.12    0.01   96%  96% Peek [2 msgs] mbox
     0.25    0.12    1.33    0.07   78%  18% Get [first] mbox
     0.25    0.12    0.73    0.04   81%  12% Get [second] mbox
     0.28    0.12    1.09    0.09   78%  12% Tryput [first] mbox
     0.21    0.12    0.61    0.07   59%  37% Peek item [non-empty] mbox
     0.23    0.12    1.09    0.07   62%  34% Tryget [non-empty] mbox
     0.20    0.12    0.48    0.07   46%  46% Peek item [empty] mbox
     0.19    0.12    0.61    0.07   96%  50% Tryget [empty] mbox
     0.02    0.00    0.12    0.03   87%  87% Waiting to get mbox
     0.01    0.00    0.12    0.01   93%  93% Waiting to put mbox
     0.05    0.00    0.48    0.07   68%  68% Delete mbox
     0.89    0.73    1.94    0.09   90%   6% Put/Get mbox

     0.03    0.00    0.24    0.05   75%  75% Init semaphore
     0.15    0.12    0.48    0.05   81%  81% Post [0] semaphore
     0.19    0.12    0.36    0.06   50%  46% Wait [1] semaphore
     0.15    0.12    0.61    0.05   90%  90% Trywait [0] semaphore
     0.13    0.12    0.24    0.01   93%  93% Trywait [1] semaphore
     0.03    0.00    0.36    0.05   81%  81% Peek semaphore
     0.01    0.00    0.36    0.02   96%  96% Destroy semaphore
     0.81    0.73    1.94    0.10   93%  62% Post/Wait semaphore

     0.15    0.00    0.61    0.11   62%  28% Create counter
     0.05    0.00    0.36    0.07   68%  68% Get counter value
     0.01    0.00    0.12    0.01   93%  93% Set counter value
     0.20    0.12    0.48    0.06   56%  40% Tick counter
     0.02    0.00    0.24    0.03   87%  87% Delete counter

     0.02    0.00    0.36    0.03   90%  90% Init flag
     0.17    0.12    0.97    0.08   96%  75% Destroy flag
     0.14    0.12    0.73    0.04   93%  93% Mask bits in flag
     0.20    0.12    1.09    0.09   93%  62% Set bits in flag [no waiters]
     0.32    0.24    2.06    0.13   93%  93% Wait for flag [AND]
     0.30    0.24    1.21    0.09   96%  75% Wait for flag [OR]
     0.26    0.12    1.09    0.06   81%  12% Wait for flag [AND/CLR]
     0.25    0.12    0.97    0.04   84%  12% Wait for flag [OR/CLR]
     0.00    0.00    0.12    0.01   96%  96% Peek on flag

     0.20    0.00    0.85    0.11   78%   6% Create alarm
     0.26    0.12    1.09    0.06   78%  12% Initialize alarm
     0.14    0.12    0.36    0.03   90%  90% Disable alarm
     0.27    0.12    1.21    0.07   84%   6% Enable alarm
     0.16    0.12    0.36    0.05   71%  71% Delete alarm
     0.24    0.12    0.61    0.03   81%  12% Tick counter [1 alarm]
     1.00    0.97    1.21    0.04   81%  81% Tick counter [many alarms]
     0.37    0.24    1.09    0.04   84%  12% Tick & fire counter [1 alarm]
     5.82    5.70    6.55    0.05   75%  18% Tick & fire counters [>1 together]
     1.17    1.09    1.82    0.09   93%  56% Tick & fire counters [>1 separately]
     2.26    2.18    4.73    0.08   49%  49% Alarm latency [0 threads]
     2.57    2.30    4.24    0.11   67%  10% Alarm latency [2 threads]
     3.08    2.67    4.12    0.21   65%  20% Alarm latency [many threads]
     2.98    2.91    4.97    0.08   97%  60% Alarm -> thread resume latency

     1.07    0.97    2.91    0.00            Clock/interrupt latency

     0.67    0.48    1.70    0.00            Clock DSR latency

      239     172     272                    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   232 size  1280

 Timing complete - 29820 ms total

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

Prev Up Next
SAMA5D3x-CM Platform HAL Home Chapter 284. Atmel SAMA5D3 Xplained Platform HAL