Name

CYGPKG_HAL_NIOS2_NEEK_CYCLONE3_APPSELECTOR — eCos Support for the Appselector Hardware Design on a Nios II Embedded Evaluation Kit, Cyclone III Edition

Description

This package provides the hardware design HAL for the version 8.0 appselector hardware design running on a Nios II Embedded Evaluation Kit, Cyclone III edition, also known as the NEEK board. This is the hardware design programmed into boards as shipped from the factory, and in the examples/application_selector and factory_recovery directories of the software supplied with the board.

[Note]Note

There are a number of different and incompatible versions of the appselector hardware design. This package supports only the 8.0 version, a copy of which is supplied with eCosPro releases. If your NEEK board runs a different version of the hardware design then it will be necessary to update the board before eCos can be used. Instructions on how to do this are given below.

The hardware design includes the following functionality:

CPU
A Nios II/s processor running at 60MHz. This has 4K of instruction cache and 2K of data cache. It has level 1 jtag support only with no hardware breakpoints. The reset vector is at address 0x04100000 in external flash and the exception vector is at address 0x05000020 in external SRAM.
SDRAM
32MB of external SDRAM at 0x00000000. If RedBoot is used then the bottom 64K will be reserved for RedBoot. The remainder is used as the default location for application data, and for application code for RAM and RAMJTAG startups.
SRAM
1MB of external SRAM at 0x05000000. Some of this will be used for exception and interrupt handling. The remainder is available for use by the application. Code and data can be placed here by putting it into .sram_text, .sram_data and .sram_bss sections. The platform HAL package CYGPKG_HAL_NIOS2_NEEK_CYCLONE3_BOARD contains a memories.c testcase which can be used as an example.
IRAM
4K of on-chip RAM at 0x08000000. This can be used only for holding data, not code. Some of this is used for holding DMA descriptors for the triple-speed ethernet device. The remainder is available for use by application data, by putting it into .iram_data and .iram_bss sections. The platform HAL package CYGPKG_HAL_NIOS2_NEEK_CYCLONE3_BOARD contains a memories.c testcase which can be used as an example.
Flash
16MB of external Strata flash at 0x04000000 attached via an 16-bit data bus. This is supported via the V2 Strata flash driver CYGPKG_DEVS_FLASH_STRATA_V2. The driver will be inactive unless the generic flash support package CYGPKG_IO_FLASH has been added to the configuration. The first megabyte of the flash is reserved for holding the hardware design. Locations 0x04100000 onwards are used to hold the code for ROM startup applications, or to hold RedBoot if that is used. RedBoot's FIS and fconfig data are held at the end of the flash. The remainder is available for use by the application.
system clock
An Avalon timer labelled sys_clk used to implement the main eCos system clock. By default the system clock will operate at 100Hz, but this can be changed by editing the configuration option CYGNUM_HAL_RTC_PERIOD.
uart
An Avalon uart connected to the external transceiver on the board. This is hardwired at 115200 baud, 8 bits, no parity, 1 stop bit, and no RTS/CTS support. Usually this uart will be used by eCos and/or RedBoot for the HAL diagnostics and debug channel, so it will not be available to the application. If the uart is not used in this way then it can be accessed by the application code via the serial device driver CYGPKG_DEVS_SERIAL_NIOS2_AVALON_UART. The configuration will also need to include the generic serial support package CYGPKG_IO_SERIAL, and the option CYGPKG_IO_SERIAL_DEVICES will need to be enabled.
tse
A triple-speed ethernet device, and associated DMA engines. In eCos configurations which involve networking this device will be supported via the ethernet driver package CYGPKG_DEVS_ETH_NIOS2_TSE. The ethernet's MAC address is held in an external EEPROM attached to a bit-banged I²C bus.
I2C
The NEEK board has two I²C buses, implemented by bit-banging GPIO ports: hal_neek_cyclone3_id_eeprom_bus and hal_neek_cyclone3_lcd_i2c_bus. There are I²C device instances for the devices attached to these buses: hal_neek_cyclone3_24lc02b for the EEPROM, hal_neek_cyclone3_adv7180 for the video decoder and hal_neek_cyclone3_wm8731 for the sound chip. The generic I²C package CYGPKG_IO_I2C provides an API for manipulating such devices. Bytes 2 to 7 of the EEPROM are used to hold the ethernet MAC address so should not be changed by application code. If any of the bus or device instances are not used directly or indirectly then they will be removed by link-time garbage collection.
sysid
A system id register. This is used by RedBoot to check that the current hardware design matches the RedBoot build.
Other
A number of other hardware units including a jtag uart, an SPI bus, and a framebuffer device driving an LCD panel. These are not currently used by eCos so can be accessed directly by application code.

Setting up a Board

The eCos port targets a VHDL hardware design named appselector. This hardware design is provided by Altera, and new NEEK boards usually come with this h/w design preprogrammed into the external flash. However, there are several different and incompatible versions of this design. The eCos port specifically targets the 8.0 version. If your board comes with a different version of the h/w design or if a different h/w design has been programmed into flash then it will first be necessary to program the right design into flash. The required image file restore_cycloneIII_3c25.flash can be found in the nios2/ subdirectory of the installation. The sources for this h/w design are also included with the release.

The most convenient way to install a h/w design is to use Altera's flash programming tools, provided with Quartus and the Nios II Embedded Development Suite (nios2eds). The NEEK board has a built-in jtag interface accessible via a USB port, which can be used for this purpose.

The Quartus tools can be downloaded from Altera. Version 13.1 is the last version released that supports the Cyclone III FPGA that the Neek board is based upon. The free “web” version can be downloaded from http://dl.altera.com/13.1/?edition=web and the subscription version from http://dl.altera.com/13.1/?edition=subscription. Version 13.1, unlike some earlier versions, incorporates the EDS tools within the Quartus download.

Assuming that the Altera software as been correctly installed and that a USB cable has been connected between the host PC and the NEEK board, the following commands will install Altera's appselector application and support data, as well as the hardware design. On a Windows PC these commands need to be issued within the Altera EDS Nios command shell, not the Windows or eCos command shells.

$ cd <ecosproinstalldir>/ecos-<version>/nios2
$ nios2-flash-programmer --base=0x04000000 --go restore_cycloneIII_3c25.flash

If application development will use just the jtag interface then the board can now be used to run eCos applications configured for RAMJTAG startup. This involves running the Nios II gdb server supplied by Altera:

$ nios2-gdb-server --tcpport 9000 --tcppersist

eCos applications and tests configured for RAMJTAG startup can now be downloaded and executed via nios2-elf-gdb at another command line prompt. For example:

nios2-elf-gdb <executable-file>
(gdb) target remote localhost:9000
(gdb) set $ienable=0
(gdb) load
(gdb) continue

When using jtag, by default diagnostic output will be directed to the serial port and may be viewed using a terminal emulator configured for 115200/8N1 with no handshaking.

If instead application development will happen via RedBoot then the next step is to install a RedBoot image, replacing the appselector application. Note you must power cycle the board between the above step and this one. Start by connecting a serial cable between the host PC and the NEEK board, and start up a terminal emulator running at 115200/8N1 with no handshaking. Next use Altera's EDS command shell to issue the following commands to program the RedBoot image into flash via jtag:

$ cd <ecosproinstalldir>/ecos-<version>/loaders/nios2_neek_cyclone3_appselector
$ bin2flash --location=0x00100000 \
          --input=redboot_ROM.bin \
          --output=redboot.flash
$ nios2-flash-programmer --base=0x04000000 \
                       --sidp=0x08002f40 \
                       --id=1727563914 \
                       --no-keep-nearby \
                       --go \
                       redboot.flash

The --sidp and --id arguments are used to check that the board is running the correct h/w design. The --go argument causes the board to restart, so RedBoot should now be running and should have output its banner and a prompt. The terminal emulator can now be used to execute the following commands at the RedBoot prompt to initialise the Flash contents:

RedBoot> fis init
RedBoot> fconfig -i

eCos applications and tests configured for RAM startup can now be downloaded and executed via nios2-elf-gdb. For example, to run the prebuilt eCos test over serial, first exit the terminal emulator so that nios2-elf-gdb can access the serial port, and then use the following commands:

nios2-elf-gdb <path>/thread_gdb
(gdb) set remotebaud 115200
(gdb) target remote /dev/ttyS0
(gdb) load
(gdb) continue

RedBoot binaries are provided under the 'loaders' directory in the release. They may be rebuilt by making RAM and ROM startup RedBoot images in the documented manner, each in a separate working directory. For RAM startup:

$ ecosconfig new nios2_neek_cyclone3_appselector redboot
$ ecosconfig import <path>/redboot_RAM.ecm
$ ecosconfig check
$ ecosconfig tree
$ make

The .ecm import file can be found in the misc subdirectory of this package. Similarly for ROM startup:

$ ecosconfig new nios2_neek_cyclone3_appselector redboot
$ ecosconfig import <path>/redboot_ROM.ecm
$ ecosconfig check
$ ecosconfig tree
$ make

Configuration Options

This hardware design HAL package will be loaded automatically when creating an eCos configuration for the nios2_neek_cyclone3_appselector target, together with the Nios II architectural HAL CYGPKG_HAL_NIOS2 and the platform HAL CYGPKG_HAL_NIOS2_NEEK_CYCLONE3_BOARD. It should never be necessary to load this package explicitly. Unloading the package should only happen as a side effect of switching target hardware.

Selecting the nios2_neek_cyclone3_appselector target will also load a flash driver, a serial driver, an ethernet driver, and I²C support. The flash driver will be inactive unless the configuration also includes the generic flash support package CYGPKG_IO_FLASH. The serial driver will be inactive unless the configuration includes the generic serial support package CYGPKG_IO_SERIAL and the option CYGPKG_IO_SERIAL_DEVICES is enabled. The ethernet driver will be active only in eCos configurations which involve networking. The I²C package is always active, but any functionality that is not used directly or indirectly will be removed via link-time garbage collection.

The port to the appselector h/w design supports three startup types:

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 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 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, by default the uart 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 configuration option CYGNUM_HAL_RTC_PERIOD can be used to change the system clock frequency. The default value gives a 100Hz clock.