Name

CYGPKG_HAL_NIOS2_NEEK_CYCLONE3_BOARD — eCos Platform HAL Support for the Nios II Embedded Evaluation Kit, Cyclone III Edition

Description

This package provides platform HAL support for the Altera Nios II Embedded Evaluation Kit, Cyclone III Edition, also known as the NEEK board. Since this platform is based around an FPGA it can run a variety of hardware designs, and each design needs its own h/w design HAL to define the details of the hardware configured into the FPGA. The platform HAL contains support for some of the off-chip peripherals on the board, for example the external flash memory and the I²C device used to hold the ethernet MAC address. It also contains some code and configuration options which are likely to be reusable across many h/w designs, to avoid duplicating code unnecessarily.

The h/w design determines which peripherals are available, and that in turn affects how eCos can be used. Hence details of setting up a NEEK board for eCos development can be found in the h/w design HAL documentation. In addition the Nios II architectural HAL documentation contains some generic setup instructions which will be applicable to most h/w designs.

Configuration Options

This 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 provided by this package is CYG_HAL_STARTUP. This can take either two or three values, depending on the h/w design:

ROM
This startup type should be used for code that should execute from the external flash. The executable will start running from the Nios II reset vector defined in the h/w design and will contain all the low-level initialization code needed to bring up the system. ROM startup can be used for production systems. It can also be used for building the RedBoot ROM monitor on h/w designs that support RedBoot, and the application can then be loaded into RAM and run from there.
RAMJTAG
This startup type will be used mainly for debugging via JTAG. The nios2-elf-gdb debugger will be used, directly or indirectly, to load the application into RAM and start it running.
RAM
This startup type is only available if the h/w design incorporates a uart. It assumes that a ROM-startup RedBoot has been programmed into flash. JTAG is not used for debugging, only for the initial installation. For debugging, nios2-elf-gdb connects to the RedBoot ROM monitor over serial or ethernet and can then be used to load the application into RAM and run it. For production systems a RedBoot boot script can be used to load the application from flash to RAM and start it running.

For ROM and RAMJTAG startup, if the h/w design incorporates a uart then by default that will be used for the diagnostics channel. This can be changed via the configuration option CYGIMP_HAL_NIOS2_DIAGNOSTICS_PORT. The alternative destination is discard which just discards all diagnostics output. For RAM startup the application will inherit its diagnostics channel from the RedBoot ROM monitor.

The remaining configuration options in this package are primarily for internal use within the configuration system.

External Flash

The NEEK board comes with a single Strata-compatible external flash chip. Assuming the h/w design incorporates support for this, the Strata V2 flash driver will automatically be loaded when creating a new eCos configuration. However the driver will be inactive by default. To activate the driver the generic flash support CYGPKG_IO_FLASH must be added to the configuration. The platform HAL will then instantiate a flash device object.

I2C Buses and Devices

The NEEK board comes with a number of I²C devices on two sets of GPIO lines. Given the right support in the h/w design the platform HAL will instantiate bit-banged I²C bus objects and define I²C device objects. The latter can then be manipulated using the generic eCos I²C API, for example cyg_i2c_tx, as defined by the package CYGPKG_IO_I2C.

If the h/w design HAL defines symbols HAL_NIOS2_AVALON_PIO_id_eeprom_dat_BASE and HAL_NIOS2_AVALON_PIO_id_eeprom_scl_BASE then the platform HAL will instantiate an I²C bus hal_neek_cyclone3_id_eeprom_bus and an I²C device hal_neek_cyclone3_24lc02b, corresponding to an EEPROM chip. This chip is factory-programmed with an ethernet MAC address in bytes 2-7. If the h/w design and the eCos configuration involve an ethernet device then the platform HAL will provide this MAC address to the ethernet driver. The other bytes in the EEPROM are not used by eCos so are available to application code.

If the h/w design HAL defines symbols HAL_NIOS2_AVALON_PIO_lcd_i2c_scl_BASE and HAL_NIOS2_AVALON_PIO_lcd_i2c_sdat_BASE then the platform HAL will instantiate an I²C bus hal_neek_cyclone3_lcd_i2c_bus and two I²C device objects hal_neek_cyclone3_wm8731 and hal_neek_cyclone3_adv7180.

LEDs

The NEEK board comes with four LEDs, although not all h/w designs will allow access to all four. If the h/w design incorporates a suitable GPIO port and the h/w design HAL defines the symbol HAL_NIOS2_AVALON_PIO_led_BASE then the platform HAL will provide two additional functions for manipulating the LEDs:

#include <cyg/hal/hal_io.h>
extern void hal_nios2_led_set(int which, int on);
extern void hal_nios2_led_set_all(int setting);

The first function can be used to switch a single LED on or off. The second can be used to change the setting of all four LEDs, using the bottom four bits of the setting argument.