doc/README.nios

   1
   2                            U-Boot for Nios-32
   3
   4                     Last Update: February 1, 2004
   5 ====================================================================
   6
   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:
  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
  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:
  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
  25
  26 For those interested in contributing ... see HELP WANTED below.
  27
  28
  29 1. OVERVIEW
  30 ------------
  31
  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.
  38
  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.
  44
  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).
  48
  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.
  57
  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.
  63
  64
  65 2. CONFIGURATION OPTIONS/SETTINGS
  66 ----------------------------------
  67
  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_".
  72
  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.
  78
  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).
  85
  86 CONFIG_NIOS -- defined for all Nios-32 boards.
  87
  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).
  94
  95 CFG_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
  96         parameter is set to '1'.
  97
  98 CFG_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
  99
 100 CFG_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
 101         MSTEP instruction (not yet implemented).
 102
 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).
 106
 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).
 110
 111 CFG_NIOS_TMRMS -- the period of the timer in milliseconds.
 112
 113 CFG_NIOS_TMRCNT -- the preloadable counter value for the timer if it has
 114         no fixed period.
 115
 116 CFG_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
 117         (standard-32: na_asmi_base).
 118
 119 CFG_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
 120         (nasys_spi_0)
 121
 122 CFG_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
 123         This value can be 8 or 16 only! (PTF: databits)
 124
 125
 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.
 130
 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.
 134
 135
 136 3. ASSEMBLY CODING
 137 -------------------
 138
 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.
 145
 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.
 151
 152
 153 4. BOOT PROCESS
 154 ---------------
 155
 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:
 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
 174 In normal case, for "standard_32", STDIN and STDOUT are the first
 175 serial port.
 176
 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):
 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
 189 5. DEBUGGING WITH GDB
 190 ---------------------
 191
 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.
 197
 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.
 204
 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.
 208
 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.
 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
 264 5.3 For advanced Users
 265 ----------------------
 266 A 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
 278 6. BRAIN DAMAGE
 279 ----------------
 280
 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.
 284
 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.
 290
 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).
 300
 301 The solution ... well, you can wait for Altera ... or build as
 302 set of tools for linux.
 303
 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.
 310
 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.
 316
 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.
 322
 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:
 326
 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
 332
 333 With:
 334 environment.o: environment.c
 335         $(CC) $(AFLAGS) -Wa,--no-warn \
 336                 -DENV_CRC=0 \
 337                 -c -o $@ environment.c
 338
 339 BTW, thats a 'zero' ... not the letter 'O'. And not that the
 340 "../tools/envcrc" dependency is removed.
 341
 342
 343 7. HELP WANTED
 344 ---------------
 345
 346 There are plenty of areas where help is needed. Here's are some ideas
 347 for those interested in contributing:
 348
 349 -CompactFlash. Port & test CF/FAT.
 350
 351 -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
 360 Regards,
 361
 362 --Scott
 363 <smcnutt@psyent.com>
 364
 365 --Stephan
 366 <linz@li-pro.net>