On-chip Subsystems and Peripherals
Prev Chapter 277. Atmel ATSAMA5D3 Variant HAL Next

Name

On-chip Subsystems and Peripherals — Hardware Support

Hardware support

On-chip Memory

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.

Interrupts

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]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. The hal_IRQ_handler queries the IRQ status register to determine the interrupt cause. Functions hal_interrupt_mask and hal_interrupt_unmask enable or disable interrupts within the interrupt controller.

Interrupts are configured in the hal_interrupt_configure function, where the level and up arguments are interpreted as follows:

levelupinterrupt on
00Falling Edge
01Rising Edge
10Low Level
11High Level

To fit into the eCos interrupt model, interrupts essentially must be acknowledged immediately once decoded. The hal_interrupt_acknowledge function explicitly acknowledges the PIO controller interrupt sources.

The 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 hal_interrupt_handlers. Table slots correspond to the interrupt numbers as detailed above. Pointers inserted in this table should be pointers to a C/C++ function with the following prototype: 

extern unsigned int isr( unsigned int vector, unsigned int data );

For non-eCos applications run from RedBoot, the return value can be ignored. The vector argument will also be the interrupt vector number. The data argument is extracted from a corresponding table named hal_interrupt_data which 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 option 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 to CYGNUM_HAL_RTC_DENOMINATOR, then the configuration option CYGNUM_HAL_RTC_NUMERATOR may also be adjusted, and again clock-related settings will automatically be recalculated.

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 timer.

GPIO

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.

RTC/Wallclock

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 package CYGPKG_DEVICES_WALLCLOCK_ARM_AT91 (“AT91 wallclock driver”). Normally this package is included automatically by the relevant platform HAL.

Profiling Support

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 use.

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.

Serial I/O

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 package: 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.

SPI

The platform HAL provides definitions to allow access to devices on the SPI buses. The HAL provides information to the general AT91 SPI driver (CYGPKG_DEVS_SPI_ARM_AT91) which in turn provides the underlying implementation for the SPI API layer in the 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:

  • cyg_spi_at91_bus0
  • cyg_spi_at91_bus1

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)

The 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 the CYGPKG_IO_I2C package, along with the API documentation. The CYGPKG_DEVS_I2C_ATMEL_TWI hardware package is normally included by default when configuring a SAMA5D3 platfornm, and so does not need to be manually added to a configuration.

Support for TWI functionality is controlled within the SAMA5D3 variant HAL via the CYGPKG_HAL_ARM_CORTEXA_SAMA5D3_I2C CDL 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 provides the CYGNUM_DEVS_I2C_ATMEL_TWIx_CLOCK option to configure the TWI bus clock speed, where x is replaced by the relevant bus number.

The driver package implements the necessary I²C bus instances as appropriate:

  • hal_atmel_i2c_bus0
  • hal_atmel_i2c_bus1
  • hal_atmel_i2c_bus2

The platform or application code can then register devices attached tospecific buses as needed.

MCI (MMC/SD card controller)

If a suitable socket or sockets exist, the platform HAL may provide definitions to allow use of MMC or SD cards accessed using the on-chip Multimedia Card Interface (MCI) peripheral block. The SAMA5D3 processor has support for up to three independent high speed MCI (HSMCI) controllers; although at present in eCos, only one may be configured for use, fixed at configuration time.

The device driver itself is found in the separate package CYGPKG_DEVS_MMCSD_ATMEL_SAM_MCI, which is loaded automatically when selecting any platform supporting it, and further documentation can be found in that package. Typically, disk support (CYGPKG_IO_DISK), generic filesystem support (CYGPKG_IO_FILEIO) and a filesystem such as FAT (CYGPKG_FS_FAT along with its prerequisite CYGPKG_LINUX_COMPAT) are then added to allow application use.

Features such as card insertion/removal detection, SDIO or write protection detection are hardware and platform specific, and platform documentation should be consulted for more information on those features.

USB

The platform HAL provides definitions to the general USB controller driver (CYGPKG_DEVS_USB_AT91) which in turn provides the underlying implementation for the USB API layer (CYGPKG_IO_USB).

The driver layer supports both OHCI host functionality via the CYGPKG_DEVS_USB_OHCI package, allowing peripheral devices to be attached to an eCos “host”, and for device functionality via the 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 top-level CYGPKG_IO_USB package needs to be included and configured when USB functionality is required.

OHCI

The CYGPKG_DEVS_USB_OHCI package implements the generic parts of the OHCI (host controller) support, and in conjunction with the platform specific driver and the 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.

Device

The 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 the 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.

Clock Control

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.

Prev Up Next
Bootstrap Home GPIO Support on SAMA5D3 processors