doc/README.nios

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