doc/README.nios

   1
   2                            U-Boot for Nios-32
   3
   4                     Last Update: October 4, 2003
   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 Kit, Cyclone Edition (DK-1C20), see doc/README.dk1c20.
  10
  11 For those interested in contributing ... see HELP WANTED below.
  12
  13
  14 1. OVERVIEW
  15 ------------
  16
  17 U-Boot has been successfully tested on the Nios Cyclone development
  18 board using both the 'safe' and 'standard 32' configurations with
  19 Nios CPU revision 3.08 (CPU_ID = 0x3008). U-Boot can be used with
  20 or without the GERMS monitor. The initial version of U-Boot for the
  21 Cyclone development kit is about 60 Kbyte and will fit in a single
  22 sector of on-board FLASH. Only the Nios 32-bit CPU is supported.
  23
  24 1.1 GERMS Monitor
  25 ------------------
  26 If GERMS is just not enough, then U-Boot is a great antibiotic.
  27 You will be very pleased with its high degree of configurability
  28 and its rich feature set.
  29
  30 A few of the most obvious limitations of GERMS are overcome by
  31 using U-Boot (See 'Brain Damage'). Most notably, you can use
  32 minicom or Hyperterminal (duh).
  33
  34 1.2 Altera Source Code
  35 -----------------------
  36 The Nios port does NOT include ANY sources that Altera has the
  37 copyright. This was a conscious decision ... not an accident.
  38 The Altera license is not clear in terms of distributing Altera
  39 sources (when altera silicon is not involved). This isn't really
  40 a problem as little, if any, of the Altera source contains
  41 features that are not already available in U-Boot.
  42
  43 The Nios port also does not use the long-winded peripheral
  44 structure definitions from the Nios SDK.
  45
  46
  47
  48 2. CONFIGURATION OPTIONS/SETTINGS
  49 ----------------------------------
  50
  51 2.1 Nios-specific Options/Settings
  52 -----------------------------------
  53 All configuration options/settings that are specific to Nios begin
  54 with "CONFIG_NIOS_" or "CFG_NIOS_". The following is a list of
  55 currently defined Nios-specific options/parameters. If any options
  56 are related to Standard-32 Nios SDK excalibur.h definitions, the
  57 related definition follows the description).
  58
  59
  60 CONFIG_NIOS -- defined for all Nios-32 boards.
  61
  62 CFG_NIOS_CONSOLE -- the base address of the console UART.
  63         (standard-32: na_uart1_base).
  64
  65 CFG_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
  66         parameter is set to '1'.
  67
  68 CFG_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
  69
  70 CFG_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
  71         MSTEP instruction (not yet implemented).
  72
  73 CFG_NIOS_TMRBASE -- the base address of the timer used to support
  74         xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
  75         (standard-32: na_lo_priority_timer2_base).
  76
  77 CFG_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
  78         the timer. (standard-32: na_low_priority_timer2_irq).
  79
  80 CFG_NIOS_TMRMS -- the period of the timer in milliseconds.
  81
  82 2.2 Differences in U-Boot Options/Settings
  83 -------------------------------------------
  84 Some 'standard' U-Boot options/settings are treated differently in
  85 the Nios port. These are described below.
  86
  87 CFG_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
  88         global data structure in the Nios memory space. More simply,
  89         the address of global data.
  90
  91
  92 3. ASSEMBLY CODING
  93 -------------------
  94
  95 In browsing the assembly source files, you may notice the absence
  96 of the 'magic macros' (e.g. MOVIA, MOVIP, ADDIP etc.). This is
  97 deliberate. The documentation for the magic macros is scant and
  98 it is hard to find ... it does not appear in the Nios programmer's
  99 manual, nor does it appear in the assembler manual. Regardless,
 100 the macros actually do very little to improve readability anyway.
 101
 102 With this in mind, all assembler modules use only instructions that
 103 appear in the Nios programmer's manual OR are directly supported
 104 by the nios-elf toolchain. For example, the 'dec %rB' instruction
 105 is an alias for 'subi %rB,1' that is supported by the assembler
 106 but does not appear in the programmer's manual.
 107
 108
 109 4. BRAIN DAMAGE
 110 ----------------
 111
 112 This section describes some of the unfortunate and avoidable aspects
 113 of working with the Nios CPU ... and some things you can do to
 114 reduce your pain.
 115
 116 4.1 GERMS doesn't work with Hyperterminal
 117 ------------------------------------------
 118 GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
 119 (or minicom) -- geez. Regardless of you opion of Hyperterminal, this
 120 sad design decision is remedied by using U-Boot.
 121
 122 4.2 cygwin Incompatibility
 123 ---------------------------
 124 The version of cygwin distributed with the nios GNUPro toolchain is
 125 out-of-date and incompatible with the latest cygwin distributions.
 126 In addition, many of the standard utilities are very dated as well.
 127 If you try to download and build the lastest version of grep for
 128 example, you'll quickly realize that a native gcc is not available
 129 (the next topic) which leads to U-Boot build problems (following
 130 topic).
 131
 132 The solution ... well, you can wait for Altera ... or build as
 133 set of tools for linux.
 134
 135 4.3 No native gcc
 136 ------------------
 137 I'm not sure how this one slipped through the cracks ... but it is
 138 a real pain. Basically, if you want to build anything for the native
 139 environment -- forget it! A native (cygwin) gcc is not distributed,
 140 and the old version of cygwin makes locating one challenging.
 141
 142 The solution ... same as above. Just download the gcc source from
 143 Altera and build up a set of cross tools for your favorite linux
 144 distro.
 145
 146 4.4 Can't build default U-Boot
 147 -------------------------------
 148 By default, when you build U-Boot you will be building some native
 149 tools along with the target elf, bin, and srec files. Without a
 150 native gcc, this (obviously) causes problems.
 151
 152 For developers using the Altera cygwin tools you can remove the
 153 'tools' directory from SUBDIRS in the top-level Makefile. You will
 154 also have to edit common/Makefile:
 155
 156 Replace:
 157 environment.o: environment.c ../tools/envcrc
 158         $(CC) $(AFLAGS) -Wa,--no-warn \
 159                 -DENV_CRC=$(shell ../tools/envcrc) \
 160                 -c -o $@ environment.c
 161
 162 With:
 163 environment.o: environment.c ../tools/envcrc
 164         $(CC) $(AFLAGS) -Wa,--no-warn \
 165                 -DENV_CRC=0 \
 166                 -c -o $@ environment.c
 167
 168 BTW, thats a 'zero' ... not the letter 'O'.
 169
 170
 171 5. HELP WANTED
 172 ---------------
 173
 174 There are plenty of areas where help is needed. Here's are some ideas
 175 for those interested in contributing:
 176
 177 -SMC 91C111 support. E.g. add in tftpboot, etc.
 178
 179 -CompactFlash. Port & test CF/FAT.
 180
 181 -ASMI support. Use ASMI for environment, etc.
 182
 183 -Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
 184  command.
 185
 186 -Add boot support for ucLinux (niosnommu).
 187
 188 -Implement (don't copy Altera code) the __mulxx routines using the
 189  MSTEP and MUL instructions (e.g. CFG_NIOS_MULT_HW and CFG_NIOS_MULT_MSTEP).
 190
 191
 192
 193 Regards,
 194
 195 --Scott
 196 <smcnutt@psyent.com>