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
  59 2. CONFIGURATION OPTIONS/SETTINGS
  60 ----------------------------------
  61
  62 2.1 Nios-specific Options/Settings
  63 -----------------------------------
  64 All configuration options/settings that are specific to Nios begin
  65 with "CONFIG_NIOS_", "CFG_NIOS_", or "CFG_NIOS_CPU_".
  66
  67 The configuration follows a two-stage process. In the first stage
  68 the NIOS CPU core will defined like defined in Alteras SOPC Builder.
  69 At this point we use the "CFG_NIOS_CPU_" defines exclusively. For
  70 more informations about all the definitions you have to setup see
  71 into current board configurations and doc/README.nios_CFG_NIOS_CPU.
  72
  73 In second stage we bring the NIOS CPU configuration in relation to
  74 U-Boot configuration options/settings. The following is a list of
  75 currently defined Nios-specific options/parameters used inside of
  76 U-Boot. If any options are related to Standard-32 Nios SDK
  77 excalibur.h definitions, the related definition follows the
  78 description).
  79
  80 CONFIG_NIOS -- defined for all Nios-32 boards.
  81
  82 CFG_NIOS_CONSOLE -- the base address of the console UART.
  83         (standard-32: nasys_uart_0 resp. na_uart1_base).
  84
  85 CFG_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
  86         parameter is set to '1'.
  87
  88 CFG_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
  89
  90 CFG_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
  91         MSTEP instruction (not yet implemented).
  92
  93 CFG_NIOS_TMRBASE -- the base address of the timer used to support
  94         xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
  95         (standard-32: nasys_timer_1 resp. na_lo_priority_timer2_base).
  96
  97 CFG_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
  98         the timer. (standard-32: nasys_timer_1_irq resp.
  99         na_low_priority_timer2_irq).
 100
 101 CFG_NIOS_TMRMS -- the period of the timer in milliseconds.
 102
 103 CFG_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
 104         (standard-32: na_asmi_base).
 105
 106 CFG_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
 107         (nasys_spi_0)
 108
 109 CFG_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
 110         This value can be 8 or 16 only! (PTF: databits)
 111
 112
 113 2.2 Differences in U-Boot Options/Settings
 114 -------------------------------------------
 115 Some 'standard' U-Boot options/settings are treated differently in
 116 the Nios port. These are described below.
 117
 118 CFG_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
 119         global data structure in the Nios memory space. More simply,
 120         the address of global data.
 121
 122
 123 3. ASSEMBLY CODING
 124 -------------------
 125
 126 In browsing the assembly source files, you may notice the absence
 127 of the 'magic macros' (e.g. MOVIA, MOVIP, ADDIP etc.). This is
 128 deliberate. The documentation for the magic macros is scant and
 129 it is hard to find ... it does not appear in the Nios programmer's
 130 manual, nor does it appear in the assembler manual. Regardless,
 131 the macros actually do very little to improve readability anyway.
 132
 133 With this in mind, all assembler modules use only instructions that
 134 appear in the Nios programmer's manual OR are directly supported
 135 by the nios-elf toolchain. For example, the 'dec %rB' instruction
 136 is an alias for 'subi %rB,1' that is supported by the assembler
 137 but does not appear in the programmer's manual.
 138
 139
 140 4. BOOT PROCESS
 141 ---------------
 142
 143 4.1 Boot process over GERMS
 144 ---------------------------
 145 When the NIOS CPU catch a reset signal it will begin to be running
 146 code from CFG_NIOS_CPU_RST_VECT. Normally at this place it will
 147 find the GERMS monitor. That's the case for the generic NIOS CPU
 148 configuration "standard_32". When the GERMS monitor starts running,
 149 it performs important system initializations and then looks for
 150 executable code in flash, using the following steps:
 151
 152     1. Examining the two bytes at CFG_NIOS_CPU_FLASH_BASE + 0x04000C.
 153     2. Examining the button 0 on the PIO CFG_NIOS_CPU_BUTTON_PIO.
 154     3. If the button is not pressed and the two bytes contain 'N'
 155        and 'i', the monitor executes a CALL to location
 156        CFG_NIOS_CPU_FLASH_BASE + 0x040000.
 157     4. If the code is not executed in step 3 or the code returns,
 158        then prints an 8-digit version number to STDOUT and waits for
 159        user commands from STDIN.
 160
 161 In normal case, for "standard_32", STDIN and STDOUT are the first
 162 serial port.
 163
 164 4.2 Return to GERMS command line
 165 --------------------------------
 166 During the boot process, the GERMS monitor checks for the existence
 167 of application software in flash memory. If found, the processor
 168 immediately executes the code. To return program execution to the
 169 GERMS monitor (that is, avoid running code stored in flash memory):
 170
 171     1. Hold down CFG_NIOS_CPU_BUTTON_PIO, button number 0.
 172     2. Press then release the CPU reset button.
 173     3. Release CFG_NIOS_CPU_BUTTON_PIO, button number 0.
 174
 175
 176 5. BRAIN DAMAGE
 177 ----------------
 178
 179 This section describes some of the unfortunate and avoidable aspects
 180 of working with the Nios CPU ... and some things you can do to
 181 reduce your pain.
 182
 183 5.1 GERMS doesn't work with Hyperterminal
 184 ------------------------------------------
 185 GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
 186 (or minicom) -- geez. Regardless of you opion of Hyperterminal, this
 187 sad design decision is remedied by using U-Boot.
 188
 189 5.2 cygwin Incompatibility
 190 ---------------------------
 191 The version of cygwin distributed with the nios GNUPro toolchain is
 192 out-of-date and incompatible with the latest cygwin distributions.
 193 In addition, many of the standard utilities are very dated as well.
 194 If you try to download and build the lastest version of grep for
 195 example, you'll quickly realize that a native gcc is not available
 196 (the next topic) which leads to U-Boot build problems (following
 197 topic).
 198
 199 The solution ... well, you can wait for Altera ... or build as
 200 set of tools for linux.
 201
 202 5.3 No native gcc
 203 ------------------
 204 I'm not sure how this one slipped through the cracks ... but it is
 205 a real pain. Basically, if you want to build anything for the native
 206 environment -- forget it! A native (cygwin) gcc is not distributed,
 207 and the old version of cygwin makes locating one challenging.
 208
 209 The solution ... same as above. Just download the gcc source from
 210 Altera and build up a set of cross tools for your favorite linux
 211 distro. Anybody who wants to use an already precompiled NIOS cross
 212 toolchain can it found in the CDK4NIOS project hosted by Source
 213 Forge at http://cdk4nios.sourceforge.net.
 214
 215 5.4 Can't build default U-Boot
 216 -------------------------------
 217 By default, when you build U-Boot you will be building some native
 218 tools along with the target elf, bin, and srec files. Without a
 219 native gcc, this (obviously) causes problems.
 220
 221 For developers using the Altera cygwin tools you can remove the
 222 'tools' directory from SUBDIRS in the top-level Makefile. You will
 223 also have to edit common/Makefile:
 224
 225 Replace:
 226 environment.o: environment.c ../tools/envcrc
 227         $(CC) $(AFLAGS) -Wa,--no-warn \
 228                 -DENV_CRC=$(shell ../tools/envcrc) \
 229                 -c -o $@ environment.c
 230
 231 With:
 232 environment.o: environment.c ../tools/envcrc
 233         $(CC) $(AFLAGS) -Wa,--no-warn \
 234                 -DENV_CRC=0 \
 235                 -c -o $@ environment.c
 236
 237 BTW, thats a 'zero' ... not the letter 'O'.
 238
 239
 240 6. HELP WANTED
 241 ---------------
 242
 243 There are plenty of areas where help is needed. Here's are some ideas
 244 for those interested in contributing:
 245
 246 -CompactFlash. Port & test CF/FAT.
 247
 248 -Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
 249  command.
 250
 251 -Add boot support for ucLinux (niosnommu).
 252
 253 -Implement (don't copy Altera code) the __mulxx routines using the
 254  MSTEP and MUL instructions (e.g. CFG_NIOS_MULT_HW and CFG_NIOS_MULT_MSTEP).
 255
 256
 257 Regards,
 258
 259 --Scott
 260 <smcnutt@psyent.com>
 261
 262 --Stephan
 263 <linz@li-pro.net>