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