MINI2440: Temporary reset of base board init
[u-boot-openmoko/mini2440.git] / doc / README.nios
blob671e7277fa93cfc015ff0bb9de62ed5be980d260
2                            U-Boot for Nios-32
4                     Last Update: February 1, 2004
5 ====================================================================
7 This file contains information regarding U-Boot and the Altera
8 Nios CPU. For information regarding U-Boot and the Nios Development
9 Kits see:
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)
16 For informations regarding Nios Development Kit hardware overview
17 and the NIOS CPU standard configuration of all known boards made by
18 Altera see:
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
26 For those interested in contributing ... see HELP WANTED below.
29 1. OVERVIEW
30 ------------
32 U-Boot has been successfully tested on the Nios Cyclone development
33 board using both the 'safe' and 'standard 32' configurations with
34 Nios CPU revision 3.1 (CPU_ID = 0x3018). U-Boot can be used with
35 or without the GERMS monitor. The initial version of U-Boot for the
36 Cyclone development kit is about 60 Kbyte and will fit in a single
37 sector of on-board FLASH. Only the Nios 32-bit CPU is supported.
39 1.1 GERMS Monitor
40 ------------------
41 If GERMS is just not enough, then U-Boot is a great antibiotic.
42 You will be very pleased with its high degree of configurability
43 and its rich feature set.
45 A few of the most obvious limitations of GERMS are overcome by
46 using U-Boot (See 'Brain Damage'). Most notably, you can use
47 minicom or Hyperterminal (duh).
49 1.2 Altera Source Code
50 -----------------------
51 The Nios port does NOT include ANY sources that Altera has the
52 copyright. This was a conscious decision ... not an accident.
53 The Altera license is not clear in terms of distributing Altera
54 sources (when altera silicon is not involved). This isn't really
55 a problem as little, if any, of the Altera source contains
56 features that are not already available in U-Boot.
58 1.3 Debugging via OCI
59 ---------------------
60 The Nios port supports debugging with gdb and/or nios-console
61 via the JTAG port. Stubs for debugging with gdb via the serial
62 port are not currently implemented.
65 2. CONFIGURATION OPTIONS/SETTINGS
66 ----------------------------------
68 2.1 Nios-specific Options/Settings
69 -----------------------------------
70 All configuration options/settings that are specific to Nios begin
71 with "CONFIG_NIOS_", "CFG_NIOS_", or "CFG_NIOS_CPU_".
73 The configuration follows a two-stage process. In the first stage
74 the NIOS CPU core will defined like defined in Alteras SOPC Builder.
75 At this point we use the "CFG_NIOS_CPU_" defines exclusively. For
76 more informations about all the definitions you have to setup see
77 into current board configurations and doc/README.nios_CFG_NIOS_CPU.
79 In second stage we bring the NIOS CPU configuration in relation to
80 U-Boot configuration options/settings. The following is a list of
81 currently defined Nios-specific options/parameters used inside of
82 U-Boot. If any options are related to Standard-32 Nios SDK
83 excalibur.h definitions, the related definition follows the
84 description).
86 CONFIG_NIOS -- defined for all Nios-32 boards.
88 CFG_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.
93         (standard-32: nasys_uart_0 resp. na_uart1_base).
95 CFG_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
96         parameter is set to '1'.
98 CFG_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
100 CFG_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
101         MSTEP instruction (not yet implemented).
103 CFG_NIOS_TMRBASE -- the base address of the timer used to support
104         xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
105         (standard-32: nasys_timer_1 resp. na_lo_priority_timer2_base).
107 CFG_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
108         the timer. (standard-32: nasys_timer_1_irq resp.
109         na_low_priority_timer2_irq).
111 CFG_NIOS_TMRMS -- the period of the timer in milliseconds.
113 CFG_NIOS_TMRCNT -- the preloadable counter value for the timer if it has
114         no fixed period.
116 CFG_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
117         (standard-32: na_asmi_base).
119 CFG_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
120         (nasys_spi_0)
122 CFG_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
123         This value can be 8 or 16 only! (PTF: databits)
126 2.2 Differences in U-Boot Options/Settings
127 -------------------------------------------
128 Some 'standard' U-Boot options/settings are treated differently in
129 the Nios port. These are described below.
131 CFG_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.
136 3. ASSEMBLY CODING
137 -------------------
139 In browsing the assembly source files, you may notice the absence
140 of the 'magic macros' (e.g. MOVIA, MOVIP, ADDIP etc.). This is
141 deliberate. The documentation for the magic macros is scant and
142 it is hard to find ... it does not appear in the Nios programmer's
143 manual, nor does it appear in the assembler manual. Regardless,
144 the macros actually do very little to improve readability anyway.
146 With this in mind, all assembler modules use only instructions that
147 appear in the Nios programmer's manual OR are directly supported
148 by the nios-elf toolchain. For example, the 'dec %rB' instruction
149 is an alias for 'subi %rB,1' that is supported by the assembler
150 but does not appear in the programmer's manual.
153 4. BOOT PROCESS
154 ---------------
156 4.1 Boot process over GERMS
157 ---------------------------
158 When the NIOS CPU catch a reset signal it will begin to be running
159 code from CFG_NIOS_CPU_RST_VECT. Normally at this place it will
160 find the GERMS monitor. That's the case for the generic NIOS CPU
161 configuration "standard_32". When the GERMS monitor starts running,
162 it performs important system initializations and then looks for
163 executable code in flash, using the following steps:
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.
174 In normal case, for "standard_32", STDIN and STDOUT are the first
175 serial port.
177 4.2 Return to GERMS command line
178 --------------------------------
179 During the boot process, the GERMS monitor checks for the existence
180 of application software in flash memory. If found, the processor
181 immediately executes the code. To return program execution to the
182 GERMS monitor (that is, avoid running code stored in flash memory):
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.
189 5. DEBUGGING WITH GDB
190 ---------------------
192 Debug sessions using gdb are currently supported only via JTAG. The
193 stubs for debugging via a serial port are not implemented. To enable
194 the gdb JTAG stubs, simply reference _brkpt_hw_int and _brkpt_sw_int
195 at vector table offsets 3 and 4, respectively. For an example, see
196 board/altera/dk1c20/vectors.S.
198 5.1 Vector Table Initialization and ROM Stubs
199 ---------------------------------------------
200 If CONFIG_ROM_STUBS is defined, the debug breakpoint and single step
201 entries in the vector table are restored to their initial values
202 immediately _after_ initializing the vector table. Defining this macro
203 is useful when ROM-based stubs are implemented.
205 NOTE: The default GERMS monitor does NOT implement gdb stubs, nor does
206 it initialize the vector table. Therefore, when debugging U-Boot, you
207 should NOT set a software breakpoint prior to vector table initialization.
209 5.2 Starting a Debug Session
210 ----------------------------
211 If you're not familiar with gdb, you follow these step-by-step instructions.
212 These instructions are NOT the only way to start a debug session, but they
213 cover most of the individual functions to get you started.
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):
220                 $ nios-gdb-server --ocibase=0x00920800 --tcpport=2342
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:
225                 $ nios-elf-gdb u-boot
227         3.  Update target settings. From the file menu, select
228         "Target Settings ..." and select the following, then click 'Ok':
230                 Target: Remote/TCP
231                 Port :  2342   (same as in step 1)
232                 Display download dialog: checked
233                 All other check boxes: unchecked
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.
239         5.  Download U-Boot. Select menu: 'Run->Download'.
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:
245                 (gdb) directory common
246                 (gdb) directory cpu/nios
247                 (gdb) directory lib_nios
248                 (gdb) directory board/altera/dk1c20
250         Note that the last command is for the DK1C20 board only. If you
251         are using another board, specify that board's directory.
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.
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.
261         9.  Have fun & start learning more about gdb.
264 5.3 For advanced Users
265 ----------------------
266 A few notes for those more familiar with gdb.
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.
272         -If you need to debug the early startup code (prior to the vector
273         table initialization), use the nios-console debugger.
275         - Connect, download & run -- there are some problems here. Connect
276         download and run seperately to avoid trouble.
278 6. BRAIN DAMAGE
279 ----------------
281 This section describes some of the unfortunate and avoidable aspects
282 of working with the Nios CPU ... and some things you can do to
283 reduce your pain.
285 6.1 GERMS doesn't work with Hyperterminal
286 ------------------------------------------
287 GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
288 (or minicom) -- geez. Regardless of you opion of Hyperterminal, this
289 sad design decision is remedied by using U-Boot.
291 6.2 cygwin Incompatibility
292 ---------------------------
293 The version of cygwin distributed with the nios GNUPro toolchain is
294 out-of-date and incompatible with the latest cygwin distributions.
295 In addition, many of the standard utilities are very dated as well.
296 If you try to download and build the lastest version of grep for
297 example, you'll quickly realize that a native gcc is not available
298 (the next topic) which leads to U-Boot build problems (following
299 topic).
301 The solution ... well, you can wait for Altera ... or build as
302 set of tools for linux.
304 6.3 No native gcc
305 ------------------
306 I'm not sure how this one slipped through the cracks ... but it is
307 a real pain. Basically, if you want to build anything for the native
308 environment -- forget it! A native (cygwin) gcc is not distributed,
309 and the old version of cygwin makes locating one challenging.
311 The solution ... same as above. Just download the gcc source from
312 Altera and build up a set of cross tools for your favorite linux
313 distro. Anybody who wants to use an already precompiled NIOS cross
314 toolchain can it found in the CDK4NIOS project hosted by Source
315 Forge at http://cdk4nios.sourceforge.net.
317 6.4 Can't build default U-Boot
318 -------------------------------
319 By default, when you build U-Boot you will be building some native
320 tools along with the target elf, bin, and srec files. Without a
321 native gcc, this (obviously) causes problems.
323 For developers using the Altera cygwin tools you can remove the
324 'tools' directory from SUBDIRS in the top-level Makefile. You will
325 also have to edit common/Makefile:
327 Replace:
328 environment.o: environment.c ../tools/envcrc
329         $(CC) $(AFLAGS) -Wa,--no-warn \
330                 -DENV_CRC=$(shell ../tools/envcrc) \
331                 -c -o $@ environment.c
333 With:
334 environment.o: environment.c
335         $(CC) $(AFLAGS) -Wa,--no-warn \
336                 -DENV_CRC=0 \
337                 -c -o $@ environment.c
339 BTW, thats a 'zero' ... not the letter 'O'. And not that the
340 "../tools/envcrc" dependency is removed.
343 7. HELP WANTED
344 ---------------
346 There are plenty of areas where help is needed. Here's are some ideas
347 for those interested in contributing:
349 -CompactFlash. Port & test CF/FAT.
351 -Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
352  command.
354 -Add boot support for ucLinux (niosnommu).
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).
360 Regards,
362 --Scott
363 <smcnutt@psyent.com>
365 --Stephan
366 <linz@li-pro.net>