blob: 671e7277fa93cfc015ff0bb9de62ed5be980d260 [file] [log] [blame]
wdenk4a551702003-10-08 23:26:14 +00001
2 U-Boot for Nios-32
3
wdenkec4c5442004-02-09 23:12:24 +00004 Last Update: February 1, 2004
wdenk4a551702003-10-08 23:26:14 +00005====================================================================
6
7This file contains information regarding U-Boot and the Altera
8Nios CPU. For information regarding U-Boot and the Nios Development
wdenkc935d3b2004-01-03 19:43:48 +00009Kits see:
10
11 * Cyclone Edition (DK-1C20), see doc/README.dk1c20
12 * Stratix Edition (DK-1S10), see doc/README.dk1s10 (TODO)
13 * Stratix Edition (DK-1S40), see doc/README.dk1s40 (TODO)
14 * Stratix Edition (DK-20K200), see doc/README.dk20k200 (TODO)
15
16For informations regarding Nios Development Kit hardware overview
17and the NIOS CPU standard configuration of all known boards made by
18Altera see:
19
20 * Development Kit (DK) hardware overview, see doc/README.nios_DK
21 * NIOS CPU standard_32 at DK-1C20, see doc/README.dk1c20_std32
22 * NIOS CPU standard_32 at DK-1S10, see doc/README.dk1s10_std32
23 * NIOS CPU standard_32 at DK-1S40, see doc/README.dk1s40_std32
24 * NIOS CPU standard_32 at DK-20K200, see doc/README.dk20k200_std32
wdenk4a551702003-10-08 23:26:14 +000025
26For those interested in contributing ... see HELP WANTED below.
27
28
291. OVERVIEW
30------------
31
32U-Boot has been successfully tested on the Nios Cyclone development
33board using both the 'safe' and 'standard 32' configurations with
wdenk180d3f72004-01-04 16:28:35 +000034Nios CPU revision 3.1 (CPU_ID = 0x3018). U-Boot can be used with
wdenk4a551702003-10-08 23:26:14 +000035or without the GERMS monitor. The initial version of U-Boot for the
36Cyclone development kit is about 60 Kbyte and will fit in a single
37sector of on-board FLASH. Only the Nios 32-bit CPU is supported.
38
391.1 GERMS Monitor
40------------------
41If GERMS is just not enough, then U-Boot is a great antibiotic.
42You will be very pleased with its high degree of configurability
43and its rich feature set.
44
45A few of the most obvious limitations of GERMS are overcome by
46using U-Boot (See 'Brain Damage'). Most notably, you can use
47minicom or Hyperterminal (duh).
48
491.2 Altera Source Code
50-----------------------
51The Nios port does NOT include ANY sources that Altera has the
52copyright. This was a conscious decision ... not an accident.
53The Altera license is not clear in terms of distributing Altera
54sources (when altera silicon is not involved). This isn't really
55a problem as little, if any, of the Altera source contains
56features that are not already available in U-Boot.
57
wdenke4cc71a2004-05-19 21:33:14 +0000581.3 Debugging via OCI
59---------------------
60The Nios port supports debugging with gdb and/or nios-console
61via the JTAG port. Stubs for debugging with gdb via the serial
62port are not currently implemented.
63
wdenk4a551702003-10-08 23:26:14 +000064
wdenk4a551702003-10-08 23:26:14 +0000652. CONFIGURATION OPTIONS/SETTINGS
66----------------------------------
67
682.1 Nios-specific Options/Settings
69-----------------------------------
70All configuration options/settings that are specific to Nios begin
wdenkc935d3b2004-01-03 19:43:48 +000071with "CONFIG_NIOS_", "CFG_NIOS_", or "CFG_NIOS_CPU_".
wdenk4a551702003-10-08 23:26:14 +000072
wdenkc935d3b2004-01-03 19:43:48 +000073The configuration follows a two-stage process. In the first stage
74the NIOS CPU core will defined like defined in Alteras SOPC Builder.
75At this point we use the "CFG_NIOS_CPU_" defines exclusively. For
76more informations about all the definitions you have to setup see
77into current board configurations and doc/README.nios_CFG_NIOS_CPU.
78
79In second stage we bring the NIOS CPU configuration in relation to
80U-Boot configuration options/settings. The following is a list of
81currently defined Nios-specific options/parameters used inside of
82U-Boot. If any options are related to Standard-32 Nios SDK
83excalibur.h definitions, the related definition follows the
84description).
wdenk4a551702003-10-08 23:26:14 +000085
86CONFIG_NIOS -- defined for all Nios-32 boards.
87
wdenke4cc71a2004-05-19 21:33:14 +000088CFG_NIOS_CONSOLE -- the base address of the console UART or the JTAG
89 stdio port. To enable a console via JTAG, define
90 CONFIG_CONSOLE_JTAG and set CGF_NIOS_CONSOLE to the base address
91 of the JTAG stdio port (normally OCI base + 0x00fa). Then
92 run nios-console with the -w option.
wdenkc935d3b2004-01-03 19:43:48 +000093 (standard-32: nasys_uart_0 resp. na_uart1_base).
wdenk4a551702003-10-08 23:26:14 +000094
95CFG_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
96 parameter is set to '1'.
97
98CFG_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
99
100CFG_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
101 MSTEP instruction (not yet implemented).
102
103CFG_NIOS_TMRBASE -- the base address of the timer used to support
104 xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
wdenkc935d3b2004-01-03 19:43:48 +0000105 (standard-32: nasys_timer_1 resp. na_lo_priority_timer2_base).
wdenk4a551702003-10-08 23:26:14 +0000106
107CFG_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
wdenkc935d3b2004-01-03 19:43:48 +0000108 the timer. (standard-32: nasys_timer_1_irq resp.
109 na_low_priority_timer2_irq).
wdenk4a551702003-10-08 23:26:14 +0000110
111CFG_NIOS_TMRMS -- the period of the timer in milliseconds.
112
wdenk63e73c92004-02-23 22:22:28 +0000113CFG_NIOS_TMRCNT -- the preloadable counter value for the timer if it has
114 no fixed period.
115
wdenk180d3f72004-01-04 16:28:35 +0000116CFG_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
117 (standard-32: na_asmi_base).
118
wdenkec4c5442004-02-09 23:12:24 +0000119CFG_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
120 (nasys_spi_0)
121
122CFG_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
123 This value can be 8 or 16 only! (PTF: databits)
124
125
wdenk4a551702003-10-08 23:26:14 +00001262.2 Differences in U-Boot Options/Settings
127-------------------------------------------
128Some 'standard' U-Boot options/settings are treated differently in
129the Nios port. These are described below.
130
131CFG_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
132 global data structure in the Nios memory space. More simply,
133 the address of global data.
134
135
1363. ASSEMBLY CODING
137-------------------
138
139In browsing the assembly source files, you may notice the absence
140of the 'magic macros' (e.g. MOVIA, MOVIP, ADDIP etc.). This is
141deliberate. The documentation for the magic macros is scant and
142it is hard to find ... it does not appear in the Nios programmer's
143manual, nor does it appear in the assembler manual. Regardless,
144the macros actually do very little to improve readability anyway.
145
146With this in mind, all assembler modules use only instructions that
147appear in the Nios programmer's manual OR are directly supported
148by the nios-elf toolchain. For example, the 'dec %rB' instruction
149is an alias for 'subi %rB,1' that is supported by the assembler
150but does not appear in the programmer's manual.
151
152
wdenkc935d3b2004-01-03 19:43:48 +00001534. BOOT PROCESS
154---------------
155
1564.1 Boot process over GERMS
157---------------------------
158When the NIOS CPU catch a reset signal it will begin to be running
159code from CFG_NIOS_CPU_RST_VECT. Normally at this place it will
160find the GERMS monitor. That's the case for the generic NIOS CPU
161configuration "standard_32". When the GERMS monitor starts running,
162it performs important system initializations and then looks for
163executable code in flash, using the following steps:
164
165 1. Examining the two bytes at CFG_NIOS_CPU_FLASH_BASE + 0x04000C.
166 2. Examining the button 0 on the PIO CFG_NIOS_CPU_BUTTON_PIO.
167 3. If the button is not pressed and the two bytes contain 'N'
168 and 'i', the monitor executes a CALL to location
169 CFG_NIOS_CPU_FLASH_BASE + 0x040000.
170 4. If the code is not executed in step 3 or the code returns,
171 then prints an 8-digit version number to STDOUT and waits for
172 user commands from STDIN.
173
174In normal case, for "standard_32", STDIN and STDOUT are the first
175serial port.
176
1774.2 Return to GERMS command line
178--------------------------------
179During the boot process, the GERMS monitor checks for the existence
180of application software in flash memory. If found, the processor
181immediately executes the code. To return program execution to the
182GERMS monitor (that is, avoid running code stored in flash memory):
183
184 1. Hold down CFG_NIOS_CPU_BUTTON_PIO, button number 0.
185 2. Press then release the CPU reset button.
186 3. Release CFG_NIOS_CPU_BUTTON_PIO, button number 0.
187
188
wdenke4cc71a2004-05-19 21:33:14 +00001895. DEBUGGING WITH GDB
190---------------------
191
192Debug sessions using gdb are currently supported only via JTAG. The
193stubs for debugging via a serial port are not implemented. To enable
194the gdb JTAG stubs, simply reference _brkpt_hw_int and _brkpt_sw_int
195at vector table offsets 3 and 4, respectively. For an example, see
196board/altera/dk1c20/vectors.S.
197
1985.1 Vector Table Initialization and ROM Stubs
199---------------------------------------------
200If CONFIG_ROM_STUBS is defined, the debug breakpoint and single step
201entries in the vector table are restored to their initial values
202immediately _after_ initializing the vector table. Defining this macro
203is useful when ROM-based stubs are implemented.
204
205NOTE: The default GERMS monitor does NOT implement gdb stubs, nor does
206it initialize the vector table. Therefore, when debugging U-Boot, you
207should NOT set a software breakpoint prior to vector table initialization.
208
2095.2 Starting a Debug Session
210----------------------------
211If you're not familiar with gdb, you follow these step-by-step instructions.
212These instructions are NOT the only way to start a debug session, but they
213cover most of the individual functions to get you started.
214
215 1. Start the JTAG gdb server. Open a Nios shell window and start
216 the server. When the server is started you must provide the base
217 address of the OCI core. For example, when using the Cyclone
218 development kit (DK1C20):
219
220 $ nios-gdb-server --ocibase=0x00920800 --tcpport=2342
221
222 2. Start gdb. Open a Nios shell window, change to the top-level
223 U-Boot directory and start gdb, specifying the u-boot elf file:
224
225 $ nios-elf-gdb u-boot
226
227 3. Update target settings. From the file menu, select
228 "Target Settings ..." and select the following, then click 'Ok':
229
230 Target: Remote/TCP
231 Port : 2342 (same as in step 1)
232 Display download dialog: checked
233 All other check boxes: unchecked
234
235 4. Connect to the target. Select menu: 'Run->Connect to target'.
236 You should see a dialog box indicating the you successfully connected
237 to the target.
238
239 5. Download U-Boot. Select menu: 'Run->Download'.
240
241 6. Open a gdb console window and set the source directory paths.
242 Select menu: 'View->Console'. In the console window, enter the
243 following commands, then close the console window:
244
245 (gdb) directory common
246 (gdb) directory cpu/nios
247 (gdb) directory lib_nios
248 (gdb) directory board/altera/dk1c20
249
250 Note that the last command is for the DK1C20 board only. If you
251 are using another board, specify that board's directory.
252
253 7. Open the file board.c (using the file menu in the lower
254 left hand corner). Scroll to the board_init() routine and set
255 a breakpoint.
256
257 8. Run U-Boot. Just click on the run icon, or select menu:
258 'Run->Run'. U-Boot should start running, then break at your
259 breakpoint.
260
261 9. Have fun & start learning more about gdb.
262
263
2645.3 For advanced Users
265----------------------
266A few notes for those more familiar with gdb.
267
268 -Serial port stubs are not implemented. Sorry, but it's just not
269 worth _my_ effort. The JTAG stubs work great and are ridiculously
270 simple to implement.
271
272 -If you need to debug the early startup code (prior to the vector
273 table initialization), use the nios-console debugger.
274
275 - Connect, download & run -- there are some problems here. Connect
276 download and run seperately to avoid trouble.
277
2786. BRAIN DAMAGE
wdenk4a551702003-10-08 23:26:14 +0000279----------------
280
281This section describes some of the unfortunate and avoidable aspects
282of working with the Nios CPU ... and some things you can do to
283reduce your pain.
284
wdenke4cc71a2004-05-19 21:33:14 +00002856.1 GERMS doesn't work with Hyperterminal
wdenk4a551702003-10-08 23:26:14 +0000286------------------------------------------
287GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
288(or minicom) -- geez. Regardless of you opion of Hyperterminal, this
289sad design decision is remedied by using U-Boot.
290
wdenke4cc71a2004-05-19 21:33:14 +00002916.2 cygwin Incompatibility
wdenk4a551702003-10-08 23:26:14 +0000292---------------------------
293The version of cygwin distributed with the nios GNUPro toolchain is
294out-of-date and incompatible with the latest cygwin distributions.
295In addition, many of the standard utilities are very dated as well.
296If you try to download and build the lastest version of grep for
297example, you'll quickly realize that a native gcc is not available
298(the next topic) which leads to U-Boot build problems (following
299topic).
300
301The solution ... well, you can wait for Altera ... or build as
302set of tools for linux.
303
wdenke4cc71a2004-05-19 21:33:14 +00003046.3 No native gcc
wdenk4a551702003-10-08 23:26:14 +0000305------------------
306I'm not sure how this one slipped through the cracks ... but it is
307a real pain. Basically, if you want to build anything for the native
308environment -- forget it! A native (cygwin) gcc is not distributed,
309and the old version of cygwin makes locating one challenging.
310
311The solution ... same as above. Just download the gcc source from
312Altera and build up a set of cross tools for your favorite linux
wdenkc935d3b2004-01-03 19:43:48 +0000313distro. Anybody who wants to use an already precompiled NIOS cross
314toolchain can it found in the CDK4NIOS project hosted by Source
315Forge at http://cdk4nios.sourceforge.net.
wdenk4a551702003-10-08 23:26:14 +0000316
wdenke4cc71a2004-05-19 21:33:14 +00003176.4 Can't build default U-Boot
wdenk4a551702003-10-08 23:26:14 +0000318-------------------------------
319By default, when you build U-Boot you will be building some native
320tools along with the target elf, bin, and srec files. Without a
321native gcc, this (obviously) causes problems.
322
323For developers using the Altera cygwin tools you can remove the
324'tools' directory from SUBDIRS in the top-level Makefile. You will
325also have to edit common/Makefile:
326
327Replace:
328environment.o: environment.c ../tools/envcrc
329 $(CC) $(AFLAGS) -Wa,--no-warn \
330 -DENV_CRC=$(shell ../tools/envcrc) \
331 -c -o $@ environment.c
332
333With:
wdenke4cc71a2004-05-19 21:33:14 +0000334environment.o: environment.c
wdenk4a551702003-10-08 23:26:14 +0000335 $(CC) $(AFLAGS) -Wa,--no-warn \
336 -DENV_CRC=0 \
337 -c -o $@ environment.c
338
wdenke4cc71a2004-05-19 21:33:14 +0000339BTW, thats a 'zero' ... not the letter 'O'. And not that the
340"../tools/envcrc" dependency is removed.
wdenk4a551702003-10-08 23:26:14 +0000341
342
wdenke4cc71a2004-05-19 21:33:14 +00003437. HELP WANTED
wdenk4a551702003-10-08 23:26:14 +0000344---------------
345
346There are plenty of areas where help is needed. Here's are some ideas
347for those interested in contributing:
348
wdenk4a551702003-10-08 23:26:14 +0000349-CompactFlash. Port & test CF/FAT.
350
wdenk4a551702003-10-08 23:26:14 +0000351-Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
352 command.
353
354-Add boot support for ucLinux (niosnommu).
355
356-Implement (don't copy Altera code) the __mulxx routines using the
357 MSTEP and MUL instructions (e.g. CFG_NIOS_MULT_HW and CFG_NIOS_MULT_MSTEP).
358
359
wdenk4a551702003-10-08 23:26:14 +0000360Regards,
361
362--Scott
363<smcnutt@psyent.com>
wdenkc935d3b2004-01-03 19:43:48 +0000364
365--Stephan
366<linz@li-pro.net>