Generic Installation Instructions

Overview

Typical Nios II hardware for use with eCos will include an FPGA to run the hardware design, a bank each of external parallel NOR flash and SDRAM, an rs232 transceiver plus a uart in the hardware design to act as the diagnostics and debug channel, support logic to initialize the hardware following power up, and any other peripherals appropriate to the application. The external flash is needed to hold the hardware design as well as code and persistent data, and external SDRAM is needed because a typical FPGA cannot provide enough RAM for the system's requirements. Relative to the FPGA and the SDRAM the external flash is usually somewhat slow.

In a self-contained production system both the hardware design and all code will reside in the flash, and the FPGA will start executing code from flash shortly after power up once the hardware design has been loaded. This code will be linked against a build of eCos configured to use a ROM startup. The code can be the actual application, which means that the entire application will execute in place from flash and all hardware resources are available to it. However because of flash speed issues the resulting performance may be poor. An alternative approach is to have a two-stage boot process: the code that runs from flash is the RedBoot ROM monitor, linked using a ROM startup; following system initialization RedBoot then loads the application from flash into RAM and starts it running; this load can be done using either the fis load and go commands in a boot script, or alternatives such as the Robust Boot Loader CYGPKG_RBL. The application is linked against a separate eCos build configured for RAM startup, and can access some facilities provided by RedBoot such as the fconfig persistent data database. However some flash and RAM needs to be reserved for RedBoot.

An alternative available on some platforms is a ROMRAM startup. Here the application starts up as per a ROM startup, but then copies itself into RAM and continues executing from there, avoiding the performance problems of executing from flash. There is no RedBoot in the system so no resources need be reserved for it, but on the other hand its facilities are not available.

Another alternative is to use an EPCS serial flash chip instead of or in addition to the parallel flash. The hardware design and the boot code both reside in the EPCS chip, and the FPGA will load the design on power up. The design automatically includes a very simple bootloader provided by Altera which runs, copies the main boot code from the EPCS chip to RAM, and then jumps to the entry point.

Obviously during software development it is undesirable to reprogram the parallel flash or the EPCS chip following every build. Instead the nios2-elf-gdb debugger will load the application into RAM and run it under debugger control, complete with facilities such as breakpoints and single stepping. The debugger can be run either directly from the command line or from inside an integrated development environment, depending on the user's preferences and the tools available.

nios2-elf-gdb can interact with the target in two ways. It can use dedicated debug hardware such as the jtag-based Altera USB Blaster. Alternatively it can communicate with the RedBoot ROM monitor over either an rs232 connection or an ethernet network. Both approaches have advantages and disadvantages. Debugging via jtag can be less intrusive on the application's behaviour, but some functionality such as RedBoot's fconfig data will not be available. If the hardware design incorporates hardware breakpoints then jtag also offers limited capabilities for debugging code that executes from flash. RedBoot has some knowledge of eCos internals so debugging via RedBoot also provides some advanced functionality such as thread-aware debugging. Applications that will be debugged via RedBoot should be linked against an eCos built configured for RAM startup. Note that this means that exactly same application image can later be programmed into flash in a production system. Applications that will be debugged via jtag should be linked against an eCos built configured for RAMJTAG startup.

Preparing a board for debugging via jtag simply involves setting up the hardware and software in accordance with the appropriate Altera documentation. Debugging via RedBoot is more complicated because it means installing RedBoot and initializing the fis and fconfig persistent data. This is covered in more detail below. Typically the RedBoot image resides in the first 128K of flash, the last 64K of flash is used for RedBoot's persistent data, and the first 64K of external SDRAM is reserved for use by RedBoot.

Embedded hardware varies widely and eCos is itself a highly configurable operation system, so many variations of the above setup are possible. Hence some platforms will have their own installation instructions and the platform HAL documentation should be consulted first before proceeding with the instructions below. In addition some of the information such as the location of RedBoot depend on the hardware design and possibly the platform HAL, so again the appropriate documentation should be consulted for details.

Installing RedBoot

Typically the hardware design, specifically the .sof file that is the final result of compilation, needs to be programmed into flash alongside RedBoot and everything else. This can be done either using the graphical tools provided with Quartus and the Altera IDE, or using command line tools like sof2flash and nios2-flash-programmer. These tools require a jtag connection to the target, and the Altera documentation should be consulted for further details. The location of the hardware design within the flash is determined by the board's reset logic so that information can be found in the hardware design and platform HAL documentation.

The next step is to program a ROM-startup build of RedBoot into flash at the reset location. Typically the external flash is placed at location 0x00000000 within the address map and execution will start from that address, but this may be changed within the hardware design. eCosPro releases for a supported target will come with prebuilts of RedBoot in a variety of file formats (usually the ELF executable, raw binary, and S-records). Alternatively RedBoot can be rebuilt for the target as per the standard RedBoot documentation. This may either generate the various file formats automatically or it may be necessary to use nios2-elf-objcopy to convert from the ELF executable to other formats.

There are two main ways of getting RedBoot into flash. The first is to use the Altera utilities, either the graphical ones or the command-line tools. For example nios2-flash-programmer can be used together with the S-record version of the RedBoot build. When the board is reset afterwards RedBoot will start running, sending output out of the board's first serial port and providing a prompt. Starting up a terminal emulator program on the host will allow the user to see this output and to invoke RedBoot commands. The rs232 parameters will depend on the hardware design, but typically RedBoot will communicate at 115200 baud, 8 bits, no parity, 1 stop bit. At this stage there will be a number of warnings from RedBoot about uninitialized fis and fconfig settings, which is to be expected since the relevant initialization commands have not been run yet. These commands are fis init and fconfig -i, and the RedBoot documentation should be consulted for further information.

If the hardware design image is held in flash then it is usually a good idea at this stage to create one or more fis entries, marking the relevant part of the flash as in use and preventing RedBoot from overwriting the image by accident. In theory this will also allow RedBoot commands to be used to update the hardware design image if needed, although the jtag flash utilities are generally more convenient for this. For example, on a Stratix II/2s60_RoHS board the current hardware design resides at offset 0x00800000 within the flash and for safety there is also a factory fallback design at 0x00C00000.

RedBoot> fis create -f 0x00800000 -l 0x00400000 -n hwdesign_user
RedBoot> fis create -f 0x00C00000 -l 0x003F0000 -n hwdesign_bak
    

Here the -f specifies the address, -l the length, and -n prevents RedBoot from initializing the relevant parts of flash and thus overwriting the hardware designs already programmed.

If the hardware design includes a system id register then during initialization RedBoot will check the current value of that register with the setting defined in the hardware design HAL. A mismatch indicates that the RedBoot build does not correspond to the hardware design being used, so RedBoot may not be fully functional and may even fail before getting as far as providing a prompt. Sometimes this warning is innocuous because, even though a custom hardware design is being used, it is fully compatible with the one RedBoot was built for (same memory map, same interrupt vector assignments, same settings for those peripherals used by RedBoot). If so the warning can either be ignored or RedBoot can be rebuilt with an updated system id value.

The alternative approach to installing RedBoot via the jtag flash programming utilities is to go via a RAM build of RedBoot. This has the advantage of supplying the user with more information as the installation process proceeds. For example if there is a problem with the way the hardware design attempts to access flash then a RAM build of RedBoot may still function to some extent but report errors whenever attempting to access the flash, whereas a ROM build of RedBoot trying to execute from that flash may fail silently.

The file that is needed is an RedBoot ELF executable for a RAM startup build (RedBoot is not a typical eCos application and for it there is no difference between the RAM and RAMJTAG startup types). Again eCosPro releases for a supported target will come with prebuilts, alternatively Redboot can be rebuilt in the usual way. The RedBoot build will be run via nios2-elf-gdb over jtag, so typically this will first involve starting up nios2-gdb-server:

$ nios2-gdb-server --tcpport 9000
    

And then at a separate shell prompt:

$ nios2-elf-gdb <path>/redboot.elf
(gdb) target remote localhost:9000
(gdb) set $status=0
(gdb) load
(gdb) continue
    

Setting $status to 0 has the effect of disabling interrupts, useful if the board was previously used to run an application and that run left interrupts enabled. If an interrupt is pending then as soon as the continue command is executed and RedBoot starts running, before it has a chance to run a single instruction let alone initialize the system appropriately for interrupt handling, an interrupt exception will occur. Disabling interrupts before the continue avoids any such problems.

Once the RAM RedBoot starts running it should send output out of the board's first serial port and provide a prompt, as before. If this does not happen it indicates a mismatch between the RedBoot build and the hardware design, for example the RedBoot build being used may be for a different target or the hardware design currently running on the board may not be the one that RedBoot was built for. If the discrepancy is minor then the RAM RedBoot may still provide some diagnostics indicating what is wrong, for example it may warn about a system id mismatch.

Once the RAM RedBoot is up and running the fis init and fconfig -i commands can be run as before, and fis entries for any hardware design(s) in reserved areas of flash can be created. Finally a ROM version of RedBoot can be uploaded:

RedBoot> load -r -m ymodem -b %{freememlo}
    

The raw binary version of the RedBoot build, typically redboot.rom.bin should now be uploaded via the host's terminal emulator program using a ymodem transfer. Once this has finished the ROM RedBoot can be installed into flash, and a reset command will restart the processor from the reset vector which should now be RedBoot code.

RedBoot> fis create RedBoot -b %{freememlo}
…
RedBoot> reset
    

Updating RedBoot

Sometimes it may be necessary or desirable to install a new version of RedBoot, either because the hardware design has changed or because of a software update. The new version can be installed using the above instructions, usually skipping the fis and fconfig initializations because there is no need to repeat these. Alternatively it is also possible to use an existing still-functional ROM RedBoot to run up a RAM RedBoot and then use the latter to install a new ROM RedBoot - obviously it is not possible for a ROM RedBoot to update itself because it would be overwriting its own code. This has the advantage of not requiring jtag unless something goes badly wrong and major recovery is needed, but it will take somewhat longer. At the ROM RedBoot prompt:

RedBoot> load -r -m ymodem -b <address>
RedBoot> go
    

Again this involves a ymodem transfer from the host to the target, this time using the raw binary file redboot.ram.bin. The address should be the execution address for RAM applications, typically 64K into external RAM but the details will depend on the hardware design and the platform. It is also possible to skip the -r option and the address and transfer an ELF executable, but this involves a larger transfer so will take more time. The go command transfers control to the RAM RedBoot, and the ROM RedBoot binary can then be uploaded and programmed into flash as before.