U-Boot for Nios-32
- Last Update: November 30, 2003
+ Last Update: February 1, 2004
====================================================================
This file contains information regarding U-Boot and the Altera
U-Boot has been successfully tested on the Nios Cyclone development
board using both the 'safe' and 'standard 32' configurations with
-Nios CPU revision 3.08 (CPU_ID = 0x3008). U-Boot can be used with
+Nios CPU revision 3.1 (CPU_ID = 0x3018). U-Boot can be used with
or without the GERMS monitor. The initial version of U-Boot for the
Cyclone development kit is about 60 Kbyte and will fit in a single
sector of on-board FLASH. Only the Nios 32-bit CPU is supported.
a problem as little, if any, of the Altera source contains
features that are not already available in U-Boot.
-The Nios port also does not use the long-winded peripheral
-structure definitions from the Nios SDK.
+1.3 Debugging via OCI
+---------------------
+The Nios port supports debugging with gdb and/or nios-console
+via the JTAG port. Stubs for debugging with gdb via the serial
+port are not currently implemented.
2. CONFIGURATION OPTIONS/SETTINGS
2.1 Nios-specific Options/Settings
-----------------------------------
All configuration options/settings that are specific to Nios begin
-with "CONFIG_NIOS_", "CFG_NIOS_", or "CFG_NIOS_CPU_".
+with "CONFIG_NIOS_", "CONFIG_SYS_NIOS_", or "CONFIG_SYS_NIOS_CPU_".
The configuration follows a two-stage process. In the first stage
the NIOS CPU core will defined like defined in Alteras SOPC Builder.
-At this point we use the "CFG_NIOS_CPU_" defines exclusively. For
+At this point we use the "CONFIG_SYS_NIOS_CPU_" defines exclusively. For
more informations about all the definitions you have to setup see
into current board configurations and doc/README.nios_CFG_NIOS_CPU.
CONFIG_NIOS -- defined for all Nios-32 boards.
-CFG_NIOS_CONSOLE -- the base address of the console UART.
+CONFIG_SYS_NIOS_CONSOLE -- the base address of the console UART or the JTAG
+ stdio port. To enable a console via JTAG, define
+ CONFIG_CONSOLE_JTAG and set CGF_NIOS_CONSOLE to the base address
+ of the JTAG stdio port (normally OCI base + 0x00fa). Then
+ run nios-console with the -w option.
(standard-32: nasys_uart_0 resp. na_uart1_base).
-CFG_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
+CONFIG_SYS_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
parameter is set to '1'.
-CFG_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
+CONFIG_SYS_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
-CFG_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
+CONFIG_SYS_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
MSTEP instruction (not yet implemented).
-CFG_NIOS_TMRBASE -- the base address of the timer used to support
+CONFIG_SYS_NIOS_TMRBASE -- the base address of the timer used to support
xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
(standard-32: nasys_timer_1 resp. na_lo_priority_timer2_base).
-CFG_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
+CONFIG_SYS_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
the timer. (standard-32: nasys_timer_1_irq resp.
na_low_priority_timer2_irq).
-CFG_NIOS_TMRMS -- the period of the timer in milliseconds.
+CONFIG_SYS_NIOS_TMRMS -- the period of the timer in milliseconds.
+
+CONFIG_SYS_NIOS_TMRCNT -- the preloadable counter value for the timer if it has
+ no fixed period.
+
+CONFIG_SYS_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
+ (standard-32: na_asmi_base).
+
+CONFIG_SYS_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
+ (nasys_spi_0)
+
+CONFIG_SYS_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
+ This value can be 8 or 16 only! (PTF: databits)
+
2.2 Differences in U-Boot Options/Settings
-------------------------------------------
Some 'standard' U-Boot options/settings are treated differently in
the Nios port. These are described below.
-CFG_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
+CONFIG_SYS_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
global data structure in the Nios memory space. More simply,
the address of global data.
4.1 Boot process over GERMS
---------------------------
When the NIOS CPU catch a reset signal it will begin to be running
-code from CFG_NIOS_CPU_RST_VECT. Normally at this place it will
+code from CONFIG_SYS_NIOS_CPU_RST_VECT. Normally at this place it will
find the GERMS monitor. That's the case for the generic NIOS CPU
configuration "standard_32". When the GERMS monitor starts running,
it performs important system initializations and then looks for
executable code in flash, using the following steps:
- 1. Examining the two bytes at CFG_NIOS_CPU_FLASH_BASE + 0x04000C.
- 2. Examining the button 0 on the PIO CFG_NIOS_CPU_BUTTON_PIO.
+ 1. Examining the two bytes at CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x04000C.
+ 2. Examining the button 0 on the PIO CONFIG_SYS_NIOS_CPU_BUTTON_PIO.
3. If the button is not pressed and the two bytes contain 'N'
and 'i', the monitor executes a CALL to location
- CFG_NIOS_CPU_FLASH_BASE + 0x040000.
+ CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x040000.
4. If the code is not executed in step 3 or the code returns,
then prints an 8-digit version number to STDOUT and waits for
user commands from STDIN.
immediately executes the code. To return program execution to the
GERMS monitor (that is, avoid running code stored in flash memory):
- 1. Hold down CFG_NIOS_CPU_BUTTON_PIO, button number 0.
+ 1. Hold down CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.
2. Press then release the CPU reset button.
- 3. Release CFG_NIOS_CPU_BUTTON_PIO, button number 0.
+ 3. Release CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.
+
+
+5. DEBUGGING WITH GDB
+---------------------
+
+Debug sessions using gdb are currently supported only via JTAG. The
+stubs for debugging via a serial port are not implemented. To enable
+the gdb JTAG stubs, simply reference _brkpt_hw_int and _brkpt_sw_int
+at vector table offsets 3 and 4, respectively. For an example, see
+board/altera/dk1c20/vectors.S.
+
+5.1 Vector Table Initialization and ROM Stubs
+---------------------------------------------
+If CONFIG_ROM_STUBS is defined, the debug breakpoint and single step
+entries in the vector table are restored to their initial values
+immediately _after_ initializing the vector table. Defining this macro
+is useful when ROM-based stubs are implemented.
+
+NOTE: The default GERMS monitor does NOT implement gdb stubs, nor does
+it initialize the vector table. Therefore, when debugging U-Boot, you
+should NOT set a software breakpoint prior to vector table initialization.
+
+5.2 Starting a Debug Session
+----------------------------
+If you're not familiar with gdb, you follow these step-by-step instructions.
+These instructions are NOT the only way to start a debug session, but they
+cover most of the individual functions to get you started.
+
+ 1. Start the JTAG gdb server. Open a Nios shell window and start
+ the server. When the server is started you must provide the base
+ address of the OCI core. For example, when using the Cyclone
+ development kit (DK1C20):
+
+ $ nios-gdb-server --ocibase=0x00920800 --tcpport=2342
+
+ 2. Start gdb. Open a Nios shell window, change to the top-level
+ U-Boot directory and start gdb, specifying the u-boot elf file:
+
+ $ nios-elf-gdb u-boot
+ 3. Update target settings. From the file menu, select
+ "Target Settings ..." and select the following, then click 'Ok':
-5. BRAIN DAMAGE
+ Target: Remote/TCP
+ Port : 2342 (same as in step 1)
+ Display download dialog: checked
+ All other check boxes: unchecked
+
+ 4. Connect to the target. Select menu: 'Run->Connect to target'.
+ You should see a dialog box indicating the you successfully connected
+ to the target.
+
+ 5. Download U-Boot. Select menu: 'Run->Download'.
+
+ 6. Open a gdb console window and set the source directory paths.
+ Select menu: 'View->Console'. In the console window, enter the
+ following commands, then close the console window:
+
+ (gdb) directory common
+ (gdb) directory cpu/nios
+ (gdb) directory lib_nios
+ (gdb) directory board/altera/dk1c20
+
+ Note that the last command is for the DK1C20 board only. If you
+ are using another board, specify that board's directory.
+
+ 7. Open the file board.c (using the file menu in the lower
+ left hand corner). Scroll to the board_init() routine and set
+ a breakpoint.
+
+ 8. Run U-Boot. Just click on the run icon, or select menu:
+ 'Run->Run'. U-Boot should start running, then break at your
+ breakpoint.
+
+ 9. Have fun & start learning more about gdb.
+
+
+5.3 For advanced Users
+----------------------
+A few notes for those more familiar with gdb.
+
+ -Serial port stubs are not implemented. Sorry, but it's just not
+ worth _my_ effort. The JTAG stubs work great and are ridiculously
+ simple to implement.
+
+ -If you need to debug the early startup code (prior to the vector
+ table initialization), use the nios-console debugger.
+
+ - Connect, download & run -- there are some problems here. Connect
+ download and run seperately to avoid trouble.
+
+6. BRAIN DAMAGE
----------------
This section describes some of the unfortunate and avoidable aspects
of working with the Nios CPU ... and some things you can do to
reduce your pain.
-5.1 GERMS doesn't work with Hyperterminal
+6.1 GERMS doesn't work with Hyperterminal
------------------------------------------
GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
(or minicom) -- geez. Regardless of you opion of Hyperterminal, this
sad design decision is remedied by using U-Boot.
-5.2 cygwin Incompatibility
+6.2 cygwin Incompatibility
---------------------------
The version of cygwin distributed with the nios GNUPro toolchain is
out-of-date and incompatible with the latest cygwin distributions.
The solution ... well, you can wait for Altera ... or build as
set of tools for linux.
-5.3 No native gcc
+6.3 No native gcc
------------------
I'm not sure how this one slipped through the cracks ... but it is
a real pain. Basically, if you want to build anything for the native
toolchain can it found in the CDK4NIOS project hosted by Source
Forge at http://cdk4nios.sourceforge.net.
-5.4 Can't build default U-Boot
+6.4 Can't build default U-Boot
-------------------------------
By default, when you build U-Boot you will be building some native
tools along with the target elf, bin, and srec files. Without a
also have to edit common/Makefile:
Replace:
-environment.o: environment.c ../tools/envcrc
+env_embedded.o: env_embedded.c ../tools/envcrc
$(CC) $(AFLAGS) -Wa,--no-warn \
-DENV_CRC=$(shell ../tools/envcrc) \
- -c -o $@ environment.c
+ -c -o $@ env_embedded.c
With:
-environment.o: environment.c ../tools/envcrc
+env_embedded.o: env_embedded.c
$(CC) $(AFLAGS) -Wa,--no-warn \
-DENV_CRC=0 \
- -c -o $@ environment.c
+ -c -o $@ env_embedded.c
-BTW, thats a 'zero' ... not the letter 'O'.
+BTW, thats a 'zero' ... not the letter 'O'. And not that the
+"../tools/envcrc" dependency is removed.
-6. HELP WANTED
+7. HELP WANTED
---------------
There are plenty of areas where help is needed. Here's are some ideas
-CompactFlash. Port & test CF/FAT.
--ASMI support. Use ASMI for environment, etc.
-
-Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
command.
-Add boot support for ucLinux (niosnommu).
-Implement (don't copy Altera code) the __mulxx routines using the
- MSTEP and MUL instructions (e.g. CFG_NIOS_MULT_HW and CFG_NIOS_MULT_MSTEP).
+ MSTEP and MUL instructions (e.g. CONFIG_SYS_NIOS_MULT_HW and CONFIG_SYS_NIOS_MULT_MSTEP).
Regards,