Overview

The SAMA5D3 Xplained platform HAL package is loaded automatically when eCos is configured for a suitable target, e.g. atsama5d3xpld. 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

The SAMA5D3-XPLD board platform HAL package supports three separate startup types, as documented in the variant Startup documentation. The ROM startup type is not supported on this platform since the BMS signal configuration does not allow for EBI_CS#0 memory-mapped execution support.

Note

Normally the board has BootUp or AT91Bootstrap programmed into internal NAND flash within the first two non-factory-bad blocks. When using RedBoot as the loaded application then a ROMRAM build of RedBoot is programmed into the next four non-factory-bad blocks. On boot, RedBoot is copied to location 0x20008000 in external RAM. arm-eabi-gdb is then used to load a RAM startup application into memory from 0x20100000 and debug it. For such RAM applications it is assumed that the hardware has already been initialized by RedBoot. By default the application will use the eCos virtual vectors mechanism to obtain services from RedBoot, including diagnostic output.

Virtual Vectors

If the application is intended to act as a ROM monitor, providing services for other applications, then the configuration option CYGSEM_HAL_ROM_MONITOR should be set. Typically this option is set only when building the GDB stub ROM (or RedBoot).

If the application is supposed to make use of services provided by a ROM monitor, via the eCos virtual vector mechanism, then the configuration option CYGSEM_HAL_USE_ROM_MONITOR should be set. By default this option is enabled when building for a RAM startup, disabled otherwise. It can be manually disabled for a RAM startup, making the application self-contained, as a testing step before switching to ROM startup.

If the application does not rely on a ROM monitor for diagnostic services then the serial port will be claimed for HAL diagnostic output.

UART Serial Driver

The SAMA5D3-XPLD board provides a two-pin UART within the on-chip debug unit. This UART is configured as virtual vector communications channel 0 and is typically claimed by RedBoot for use as a console and/or GDB communication.

If this UART is needed by the application, either directly or via the serial driver, then it cannot also be used for GDB communication using the HAL I/O support.

The UART manifests on the board as the TTL-level TXD and RXD pins on J23. Hardware flow control (RTS/CTS) is not supported.

SPI Driver

An SPI bus driver is available for the SAMA5D3 in the package "Atmel AT91 SPI device driver" (CYGPKG_DEVS_SPI_ARM_AT91).

There are no on-board SPI devices, so no SPI devices are instantiated by default.

Consult the generic SPI driver API documentation in the eCosPro Reference Manual for further details on SPI support in eCosPro, along with the configuration options in the AT91 SPI device driver.

I²C Driver

Support for SAM I²C (TWI) busses is provided by the "Atmel TWI (I2C) device driver" package (CYGPKG_DEVS_I2C_ATMEL_TWI). The SAM variant HAL causes the two buses to be instantiated. These have been tested using external I²C devices.

Onboard NAND

The HAL port includes a low-level driver to access the on-board Micron MT29F2G08 NAND flash memory chip. To enable the driver, add the CYGPKG_IO_NAND package to your eCos configuration.

If using the NAND library direct, see also the NAND port implementation details.

	Note
	The onboard NAND chip is usually the boot device on this board.

	Warning
	Before writing to the NAND device from an application, be sure you understand the partition scheme in use and how it relates to the system bootstrap code. Failure to do so risks overwriting the second stage boot loader and/or RedBoot, leaving your board unbootable until you reprogram it.

There are several ways to partition the NAND chip. The eCos configuration setting CYGSEM_HAL_SAMA5D3_NAND_PARTITION_SCHEME specifies which one to use. The default NAND configuration, which eCosCentric recommend for development, is "Config_store" which uses the eCos on-NAND partition table.

eCos on-NAND partition table

The eCos native partition scheme ("Config_store") for this board has the following contents:

• The first 6 non-factory-bad blocks (384k) are reserved for the system bootstrap, and normally contain AT91Bootstrap or BootUp, followed by RedBoot (or an application running in place of it). This number appears in the eCos configuration as CYGNUM_HAL_SAMA5D3_NAND_RESERVE_BLOCKS_FOR_SYSTEM.
• NAND partition 0 comprises the next 10 blocks. This is used for the NAND configuration store which records the geometry of the remaining NAND partitions and hosts the RedBoot flash config area. The size of the configuration store may be reconfigured as CYGNUM_HAL_SAMA5D3_NAND_PARTITION_CONFIG_STORE_SIZE.
• The remainder of the chip, and the remainder of the partition slots, are available for arbitrary partitioning and use by applications, with their geometry stored dynamically in the configuration store (see below). It is automatically set up as a single partition, numbered 1; up to three partitions are available in a default configuration, but moremay be provisioned if required by reconfiguring CYGNUM_NAND_MAX_PARTITIONS.

	Warning
	If you change CYGNUM_HAL_SAMA5D3_NAND_RESERVE_BLOCKS_FOR_SYSTEM or CYGNUM_HAL_SAMA5D3_NAND_PARTITION_CONFIG_STORE_SIZE, you must rebuild all images (including RedBoot) that use the changed value and reprogram them at the same time. You should consider erasing and reprogramming the entire NAND array in order to guard against configuration skew situations which are likely to cause data corruption.

The geometry of the remaining partitions is stored as integer entries in the config store, with config store keys named nand.partition1.base, nand.partition1.size, nand.partition2.base, nand.partition2.size and so on.

These may be changed from within RedBoot using the nconfig command. For example:

RedBoot> nand info
NAND device `onboard':
  2048 bytes/page, 64 pages/block, capacity 2048 blocks x 128 kB = 256 MB
  Partition Start Blocks
       0       6     10
       1      16   2036
RedBoot> nconfig put nand.partition1.size uint 200
Written OK
RedBoot> nconfig put nand.partition2.base uint 216
Written OK
RedBoot> nconfig put nand.partition2.size uint 1836
Written OK
RedBoot> reset
... Resetting. RomBOOT

. . . full boot-up messages omitted for brevity . . .

+NAND: onboard: 1 partition  configured
NAND: Read partition geometry from config store
NAND: onboard: 3 partitions configured

. . . full boot-up messages omitted for brevity . . .

NAND: onboard
RedBoot> nand info
NAND device `onboard':
  2048 bytes/page, 64 pages/block, capacity 2048 blocks x 128 kB = 256 MB
  Partition Start Blocks
       0       6     10
       1      16    200
       2     216   1836
RedBoot>

Applications may change these via the config store call cyg_configstore_write_int; refer to the configuration store documentation for details.

	Note
	After changing the partition geometry in the config store, it is necessary to reset the board for the changes to take effect - hence the reset command above.

	Caution
	When changing partition geometry, eCos makes no attempt to preserve any data on the affected partition(s); it is up to you to arrange this if it is important to you. If you do not need to keep the data, consider erasing the affected partition(s) before editing them. RedBoot provides a nand erase command for just this purpose.

Manual partitioning

A CDL script which allows the chip to be manually partitioned is provided (see CYGSEM_HAL_SAMA5D3_NAND_PARTITION_MANUAL); if you choose to use this, by setting CYGSEM_HAL_SAMA5D3_NAND_PARTITION_SCHEME to "Manual", the relevant data structures will automatically be set up for you when the device is initialised. By default, the manual config CDL script does not set up any partitions.

	Note
	The configuration store always uses partition 0 on this board. If you wish to use the configuration store (such as in RedBoot) you must leave a suitable space for it. Do not write any other data to partition 0; it is automatically managed by the config store and will likely be erased.

	Warning
	The manual partitioning scheme does NOT take account of the space required for system bootstrap. If you choose this option, be sure to allow sufficient space for these in your partition layout.

Ethernet Driver

The SAMA5D3-XPLD board uses the SAMA5D3's internal EMAC and GMAC Ethernet devices attached to external Micrel KSZ8081RNB and KSZ9031RN PHYs respectively. The CYGPKG_DEVS_ETH_ARM_AT91 package contains all the code necessary to support this device and the platform HAL package contains definitions that customize the driver to the board. This driver is not active until the generic Ethernet support package, CYGPKG_IO_ETH_DRIVERS, is included in the configuration.

Both the standard 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).