The Atmel SAMA5D3 parts include 128K of on-chip SRAM for general application use. Other SRAM memory exists as part of specific on-chip I/O controllers and may be available for general purpose use if the corresponding I/O is not being used (e.g. NFC SRAM), though eCos by default does not provide explicit support for such use.
The SAMA5D3 parts also provide I/O controllers which allow access to various external memory types, which eCos may use where supported by the relevant platform HAL. Application execution is normally based on such external memory due to the limited size of the on-chip SRAM available.
The SAMA5D3 HAL provides interrupt support via the on-chip Advanced Interrupt Controller.
Interrupt controller definitions
The file <cyg/hal/sama5d3_ints.h> (located at hal/arm/cortexa/sama5d3/var/VERSION/include/sama5d3_ints.h in the eCos source repository) contains interrupt vector number definitions for use with the eCos kernel and driver interrupt APIs.
It should be noted that further decoding is performed on the multiplexed system CYGNUM_HAL_INTERRUPT_SYS interrupt to identify the cause more specifically. Note that as a result, placing an interrupt handler on the CYGNUM_HAL_INTERRUPT_SYS interrupt will not work as expected. Conversely, masking a decoded derivative of the CYGNUM_HAL_INTERRUPT_SYS interrupt will not work as this would mask other CYGNUM_HAL_INTERRUPT_SYS interrupts, but masking the CYGNUM_HAL_INTERRUPT_SYS interrupt itself will work. On the other hand, unmasking a decoded CYGNUM_HAL_INTERRUPT_SYS interrupt will unmask the CYGNUM_HAL_INTERRUPT_SYS interrupt as a whole, thus unmasking interrupts for the other units on this shared interrupt.
If the CDL option CYGHWR_HAL_ARM_CORTEXA_SAMA5D3_PIO_DEMUX is configured then the variant HAL also provides support for de-multiplexing PIO interrupt sources, allowing the standard eCos interrupt system to be used to control the use of individual PIO pin interrupt handlers. This support avoids the need for the developer to manually handle multiple active interrupt PIO pins on a single controller vector ISR function, and as such the feature is normally recommended. However for very small memory footprint systems the RAM overhead of maintaining a significantly increased set of ISR descriptor vectors may be deemed inappropriate, and so the developer is free to disable the extension and manually support the base per-controller CYGNUM_HAL_INTERRUPT_PIO# shared interrupt source as required for their PIO interrupt requirements.
Note: If the variant demultiplexing support is disabled then certain standard drivers may have restricted functionality on specific platforms if they depend on using the per-pin interrupt support for certain features.
The list of interrupt vectors may be augmented on a per-platform basis. Consult the platform HAL documentation for your platform for whether this is the case.
Interrupt controller Functions
The source file src/sama5d3_misc.c within this package
provides most of the support functions to manipulate the interrupt controller.
hal_IRQ_handler queries the IRQ status register
to determine the interrupt cause. Functions
hal_interrupt_unmask enable or disable interrupts
within the interrupt controller.
Interrupts are configured in the
function, where the
arguments are interpreted as follows:
To fit into the eCos interrupt model, interrupts essentially must be
acknowledged immediately once
explicitly acknowledges the PIO controller interrupt sources.
hal_interrupt_set_level is used to
set the priority level of the supplied interrupt within the
Advanced Interrupt Controller.
Note that in all the above, it is not recommended to call the
described functions directly. Instead either the HAL macros
HAL_INTERRUPT_MASK et al) or preferably the
kernel or driver APIs should be used to control interrupts.
Using the Advanced Interrupt Controller for VSRs
The SAMA5D3 HAL has been designed to exploit benefits of the on-chip Advanced Interrupt Controller (AIC) on the SAMA5D3. Support has been included for exploiting its ability to provide hardware vectoring for VSR interrupt handlers.
The interrupt decoding path has been optimised by allowing the AIC to be interrogated for the interrupt handler VSR to use. These vectored interrupts are by default still configured to point to the default ARM architecture HAL IRQ and FIQ VSRs. However applications may set their own VSRs to override this default behaviour to allow optimised interrupt handling.
The VSR vector numbers to use when overriding are also defined in the <cyg/hal/sama5d3_ints.h> header. Consult the kernel and generic HAL documentation for more information on VSRs and how to set them.
Interrupt handling withing standalone applications
For non-eCos standalone applications running under RedBoot, it is possible
to install an interrupt handler into the interrupt vector table manually.
Memory mappings are platform-dependent and so the platform documentation
should be consulted, but in general the address of the interrupt table
can be determined by analyzing RedBoot's symbol table, and searching
for the address of the symbol name
Table slots correspond to the interrupt numbers as detailed
inserted in this table should be pointers to a C/C++ function with the
extern unsigned int isr( unsigned int vector, unsigned int data );
vectorargument will also be the interrupt vector number. The
dataargument is extracted from a corresponding table named
hal_interrupt_datawhich immediately follows the interrupt vector table. It is still the responsibility of the application to enable and configure the interrupt source appropriately if needed.
Periodic Interval Timer
The eCos kernel system clock is implemented using the
Periodic Interval Timer (PIT) controller. By default,
the system clock interrupts once every 10ms, corresponding to a 100Hz
clock. This can be changed by the configuration
CYGNUM_HAL_RTC_DENOMINATOR which corresponds
to the clock frequency. Other clock-related settings are recalculated
automatically if the denominator is changed. If the desired frequency
cannot be expressed accurately solely with changes
CYGNUM_HAL_RTC_DENOMINATOR, then the
also be adjusted, and again clock-related settings will automatically
The PIT is also used to implement the HAL microsecond delay function,
HAL_DELAY_US. This is used by some device
drivers, and in non-kernel configurations such as with RedBoot where
this timer is needed for loading program images via X/Y-modem
protocols and debugging via TCP/IP. Standalone applications which
require RedBoot services, such as debugging, should avoid use of this
The variant HAL provides support for packaging the configuration of a GPIO line into a single 32-bit descriptor that can then be used with macros to configure the pin and set and read its value. Details are supplied later.
eCos includes RTC (known in eCos as a wallclock) device drivers for
the on-chip RTC in the SAMA5D3 family. This support is located in the
(“AT91 wallclock driver”). Normally this package
is included automatically by the relevant platform HAL.
The SAMA5D3 HAL contains support for gprof-based
profiling using a sampling timer. The default timer used is channel 0
of Timer 0 (CYGHWR_HAL_SAMA5D3_TC0). This timer is
only enabled when the gprof profiling package
CYGPKG_PROFILE_GPROF) is included and enabled in
the eCos configuration, otherwise it remains available for application
Not all SAMA5D3 variants have multiple timer blocks. For example, when targetting the SAMA5D31 variant, only TC0 is available and so profiling support may not be possible if the application requires the use of that timer block.
The SAMA5D3 variant HAL supports basic polled HAL diagnostic I/O over
any of the on-chip serial devices. There is also a fully
interrupt-driven serial device driver suitable for eCos applications
for all on-chip serial devices. The serial driver consists of an eCos
CYGPKG_IO_SERIAL_ARM_AT91 which provides
all support for the SAMA5D3 on-chip serial devices. Using the HAL
diagnostic I/O support, any of these devices can be used by the ROM
monitor or RedBoot for communication with GDB. If a device 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. An alternative serial port should be used instead.
The HAL defines CDL interfaces for each of the available UARTs, CYGINT_HAL_ARM_CORTEXA_SAMA5D3_DBGU. CYGINT_HAL_ARM_CORTEXA_SAMA5D3_USART0 to CYGINT_HAL_ARM_CORTEXA_SAMA5D3_USART3, and (if available for the target CPU) CYGINT_HAL_ARM_CORTEXA_SAMA5D3_UART0 and CYGINT_HAL_ARM_CORTEXA_SAMA5D3_UART1. The platform HAL CDL should contain an implements directive for each such UART that is available for use on the board. This will enable use of the UART for diagnostic use.
The SAMA5D3 UARTs provide TX and RX data lines plus hardware flow control using RTS/CTS for those UARTs that have them available and connected.
The platform HAL provides definitions to allow access to devices on
the SPI buses. The HAL provides information to the general AT91 SPI
CYGPKG_DEVS_SPI_ARM_AT91) which in turn
provides the underlying implementation for the SPI API layer in
CYGPKG_IO_SPI package. All these packages are
automatically loaded when configuring for the board.
The SAMA5D3 variant implements the SPI buses as configured for the platform:
The platform specific HAL may implement specific SPI device instances as relevant for the underlying hardware. e.g. SPI Dataflash devices.
Two-Wire Interface (TWI)
CYGPKG_DEVS_I2C_ATMEL_TWI package implements a
Two-Wire Interface (TWI) driver for the TWI controllers present on the
SAMA5D3 family of devices. This type of bus is also known
as I²C®. The generic API
for this driver may be found within
CYGPKG_IO_I2C package, along with the API
hardware package is normally included by default when configuring a
SAMA5D3 platfornm, and so does not need to be manually added to a
Support for TWI functionality is controlled within the SAMA5D3 variant
HAL via the
component. The component controls, via sub-options, whether TWI driver
support is enabled for the different on-chip TWI buses available.
For each individual bus that is available the driver package itself
option to configure the TWI bus clock speed,
where x is replaced by the relevant bus
The driver package implements the necessary I²C bus instances as appropriate:
The platform HAL provides definitions to the general USB controller
CYGPKG_DEVS_USB_AT91) which in turn
provides the underlying implementation for the USB API layer
The driver layer supports both OHCI host functionality via
CYGPKG_DEVS_USB_OHCI package, allowing
peripheral devices to be attached to an eCos “host”, and
for device functionality via
CYGPKG_DEVS_USB_PCD_UDPHS package, where the
eCos application implements the peripheral device support for
attaching to an external host.
All the necessary hardware packages are automatically loaded when
configuring for the board. However, the
CYGPKG_IO_USB package needs to be
included and configured when USB functionality is required.
CYGPKG_DEVS_USB_OHCI package implements the
generic parts of the OHCI (host controller) support, and in
conjunction with the platform specific driver and
CYGPKG_IO_USB package allows eCos to act as a
“host” for attached USB devices.
The eCos USB host stack includes a number of class drivers and the ability for users to write additional ones using the eCos USB host API. See the USB chapter for further details, including a complete listing of supported classes.
CYGPKG_DEVS_USB_PCD_UDPHS package implements
the generic parts of the Atmel UDPHS (USB High Speed Device Port)
peripheral controller support, and in conjunction with
CYGPKG_IO_USB package provides support for
implementing USB device/peripheral class drivers.
The USB chapter provides target mode stack details including a list of supported device/peripheral class drivers and information related to adding new class drivers.
Depending on how an eCos SAMA5D3 application is started will influence the CPU and peripheral clock frequencies used for application execution. For ROM startup, or SRAM when started by the on-chip RomBOOT, the eCos configuration supplied CYGHWR_HAL_ARM_CORTEXA_SAMA5D3_CLOCK_PLL_DIVA and CYGHWR_HAL_ARM_CORTEXA_SAMA5D3_CLOCK_PLL_MULA options, in conjunction with the platform supplied CYGHWR_HAL_ARM_CORTEXA_SAMA5D3_OSC_MAIN value, will be used to set the CPU and I/O clock frequencies. For the ROMRAM and RAM startup types the clock frequenies in effect when the application is loaded (either via another application, debug monitor of hardware debugger) are used. As such, the SAMA5D3 variant HAL provides access to variables that hold the currently configured clock frequencies:
cyg_uint32 hal_sama5d3_slck; // SLCK cyg_uint32 hal_sama5d3_mainck; // MAINCK cyg_uint32 hal_sama5d3_pllack; // PLLA frequency cyg_uint32 hal_sama5d3_upllck; // UPLL frequency cyg_uint32 hal_sama5d3_pclk; // Processor clock cyg_uint32 hal_sama5d3_mclk; // Main peripheral clock
It is not expected that applications will need to interpret or use the values, but the HAL makes use of the values to ensure valid clock configurations are used.