Name

CYGPKG_HAL_NIOS2_DEVKIT — eCos Platform HAL Support for the Stratix II/2s60-RoHS and Cyclone II/2c35 Boards

Description

The package CYGPKG_HAL_NIOS2_DEVKIT provides platform HAL support for the Altera Stratix II/2s60-RoHS and Cyclone II/2c35 development boards, and may also be usable with various other boards depending on compatibility. It is always used in conjunction with the Nios II architectural HAL CYGPKG_HAL_NIOS2 and with a hardware design HAL which provides details of the design that is programmed into the FPGA.

The main characteristics of both boards are as follows:

  1. An FPGA which gets loaded on power up with a hardware design. The eCos Nios II HALs assume that this hardware design consists of a Nios II processor plus various peripherals. Different FPGAs are used on the different boards.
  2. A 16MB AMD flash device or compatible. This is a 16-bit device but is attached to the FPGA via an 8-bit data bus. Part of the flash memory is used to hold the current hardware design and a factory default design. On the Stratix II board these reside at offsets 0x00800000 and 0x00C00000 respectively. On the Cyclone II board the offsets are 0x00C00000 and 0x00E00000. In a typical eCos setup this flash will also hold a RedBoot image and an area for RedBoot's fconfig and fis persistent data. It may also hold one or more application images which RedBoot can load into RAM, and any other persistent data that the application needs.
  3. Reset circuitry which on power up loads the hardware design from the flash device into the FPGA. This happens before any code starts running so eCos does not interact with this circuitry in any way.
  4. 32MB of SDRAM. In a typical setup the first 64K of this is reserved for RedBoot data and for special bits of code and data such as the Nios II exception vector, while the remainder holds the application code and data.
  5. 2MB of SRAM. Typically eCos does not use any of this so all of it is available to the application, and there is linker script support for placing code and data there. Note that if the hardware design places the exception vector in SRAM then eCos will use a small amount of memory at the start of SRAM. Hardware designs can also include on-chip RAM or IRAM which applications can use in much the same way as SRAM.
  6. A transceiver for a single uart. This is normally used by eCos as the diagnostics and debug channel so all hardware designs should include a uart connected to the transceiver.
  7. A jtag connector, providing an alternative debug mechanism to RedBoot's gdb stubs. The jtag connector can also be used for programming the flash, for example when installing a new hardware design.
  8. A lan91c111 ethernet chip. This can be used by one of the eCos TCP/IP stacks and for network debugging. Alternatively network connectivity can be provided by an ethernet device incorporated into the hardware design.
  9. A row of LEDs and a dual seven-segment display.
  10. Various other devices such as switches which are not directly supported by eCos, and which instead are left available for application use. The Stratix II and Cyclone II boards also come with expansion connectors so that additional hardware can be connected.

Installation

Generic instructions for setting up a board for use with eCos are provided by the Nios II architectural HAL documentation. The Stratix II and Cyclone II boards have no special requirements so the generic instructions should be followed. The address map depends on the hardware design so the documentation for the hardware design HAL should be consulted for details.

Configuration Options

The devkit platform HAL package should be loaded automatically when eCos is configured for appropriate target hardware. It should never be necessary to load this package explicitly. Unloading the package should only happen as a side effect of switching target hardware.

The main configuration option in this package is CYG_HAL_STARTUP. This can take the following values:

ROM
This startup type should be used for code that should execute from flash. The executable will start executing from the Nios II reset vector and will contain all the low-level initialization code needed to bring up the system. Typically this startup type is only used for the RedBoot ROM monitor. On the Stratix II and Cyclone II boards the flash is accessed via an 8-bit data bus so executing code from flash will be slow, even with an instruction cache. Instead application code will normally execute in RAM. It will either be loaded during a gdb debug session, or it can be loaded from flash and started automatically by RedBoot using the load and go commands.
RAM
This startup type should be used for applications that should execute from RAM, either via a gdb debug session interacting with RedBoot's gdb stubs or loaded from flash by RedBoot. eCos will assume that certain services such as diagnostics channel support will be provided by RedBoot and can be accessed via the virtual vector mechanism.
RAMJTAG

This startup type is also for applications that should execute from RAM. However it is assumed that the application is not running on top of RedBoot and cannot access any services via the virtual vector mechanisms. Instead the HAL diagnostics channel will be implemented by direct access to the uart, and functionality like RedBoot's fconfig settings will not be available at all. This startup type is used primarily when debugging an application via jtag instead of via RedBoot's gdb stubs.

Builds of RedBoot are a special case. For a RAM-resident version of RedBoot there is no difference between the RAM and RAMJTAG startup types.

If the hardware design includes support for the lan91c111 ethernet chip and if the eCos configuration involves ethernet networking then there are two options related to the lan91c111 device. CYGDAT_HAL_NIOS2_DEVKIT_ETH_LAN91C111_NAME specifies the name of the ethernet device, defaulting to “eth0”. There should be no need to change this unless the hardware design includes other ethernet devices and their drivers use the same name for the device instances. CYGDAT_HAL_NIOS2_DEVKIT_ETH_LAN91C111_MAC specifies the fallback ethernet station address or MAC address. The Stratix II and Cyclone II boards do not have a serial eeprom or similar hardware to provide a unique MAC address, so instead this address has to be provided by software. Usually it will be held in flash as a RedBoot fconfig persistent variable. However if the fconfig entries have not been initialized, or if they are not accessible because the application is being debugged over jtag and uses the RAMJTAG startup type, then the lan91c111 ethernet device will instead use the fallback MAC address specified by this configuration option. No two boards on the same network should ever use the same MAC address so great care must be taken when debugging multiple boards over jtag using the same eCos configuration.

The devkit platform HAL contains a number of other configuration options but these are mainly for internal use by other packages and it should not normally be necessary to edit their values manually.

The HAL Port

The devkit platform HAL does not change the Nios II architectural HAL's implementation of the eCos HAL specification. It does provide the platform-specific linker script support. This takes into account the supported startup types, the locations of the Nios II reset and exception vectors, and the presence of SRAM and any on-chip IRAM.

eCos itself does not use any of the SRAM or the IRAM, except as necessary for exception processing. Instead these memories are available for use by the application. Any code that should end up running from SRAM should be placed in a .sram_text section. Similarly initialized data should be placed in .sram_data, and uninitialized data should go in .sram_bss. All uninitialized data will be zeroed by the eCos startup code. The equivalent sections for on-chip IRAM are .iram_text, .iram_data and .iram_bss. The platform HAL comes with a testcase tests/memories.c which also serves as an example of how to use this functionality.

Other Functionality

If the hardware design includes GPIO units for the row of LEDs and for the dual seven-segment display then the platform HAL provides a number of utility functions for manipulating these.

#include <cyg/hal/hal_io.h>

externC void    hal_nios2_led_set(int /* which */, int /* on */);
externC void    hal_nios2_led_set_all(int /* settings */);
externC void    hal_nios2_set_7seg(int /* left */, int /* right */);

There is a testcase tests/lights.c which also serves as an example of how to use functions.

At the end of its initialization sequence RedBoot will switch all the LEDs off, thus setting them to a known state, and it will set the seven-segment display to rb, acting as a visual hint to the user that initialization is complete.

Reusing the Devkit Platform HAL

The devkit platform HAL is intended for use with the Stratix II/2s60_RoHS and Cyclone II/2c35 boards. However it should be usable as is with various other boards, or need only minor changes. The important points to note are as follows:

  1. The devkit platform HAL assumes that there is an AMD-compatible flash device on the board, and that it is a 16-bit device attached to the FPGA via an 8-bit bus. The exact flash device and its size do not matter since a run-time CFI query is performed to determine the actual characteristics of the flash device. However if the flash device is not AMD-compatible, not a 16-bit device, or not attached via an 8-bit bus, then the file src/devkit_flash.c will have to be changed. With default configuration settings it is also assumed that the Nios II reset vector is at the start of the flash, that the first 128K of flash are available for RedBoot code, and that the last 64K of flash can be used for RedBoot's fis and fconfig persistent data.
  2. The linker script assumes that there is a bank of SDRAM and that this will be used as the main location for application code and data. The size of the SDRAM is obtained from the hardware design HAL. Typically the first 64K is reserved for RedBoot's data area and for special bits of code such as the Nios II exception vector.
  3. The SRAM and on-chip IRAM are optional. The devkit platform HAL checks whether or not the hardware design HAL provides base address and size definitions for these.
  4. Usually at least one uart is essential to provide the diagnostics and debug channel.
  5. The lan91c111 ethernet chip is optional. The devkit platform HAL will only instantiate the ethernet device if the hardware design HAL specifies that this chip is present.
  6. Similarly the row of LEDs and the dual seven-segment display are optional and support for these is only provided if the hardware design includes GPIO units labelled “led” and “seven_seg”