README.nios 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366
  1. U-Boot for Nios-32
  2. Last Update: February 1, 2004
  3. ====================================================================
  4. This file contains information regarding U-Boot and the Altera
  5. Nios CPU. For information regarding U-Boot and the Nios Development
  6. Kits see:
  7. * Cyclone Edition (DK-1C20), see doc/README.dk1c20
  8. * Stratix Edition (DK-1S10), see doc/README.dk1s10 (TODO)
  9. * Stratix Edition (DK-1S40), see doc/README.dk1s40 (TODO)
  10. * Stratix Edition (DK-20K200), see doc/README.dk20k200 (TODO)
  11. For informations regarding Nios Development Kit hardware overview
  12. and the NIOS CPU standard configuration of all known boards made by
  13. Altera see:
  14. * Development Kit (DK) hardware overview, see doc/README.nios_DK
  15. * NIOS CPU standard_32 at DK-1C20, see doc/README.dk1c20_std32
  16. * NIOS CPU standard_32 at DK-1S10, see doc/README.dk1s10_std32
  17. * NIOS CPU standard_32 at DK-1S40, see doc/README.dk1s40_std32
  18. * NIOS CPU standard_32 at DK-20K200, see doc/README.dk20k200_std32
  19. For those interested in contributing ... see HELP WANTED below.
  20. 1. OVERVIEW
  21. ------------
  22. U-Boot has been successfully tested on the Nios Cyclone development
  23. board using both the 'safe' and 'standard 32' configurations with
  24. Nios CPU revision 3.1 (CPU_ID = 0x3018). U-Boot can be used with
  25. or without the GERMS monitor. The initial version of U-Boot for the
  26. Cyclone development kit is about 60 Kbyte and will fit in a single
  27. sector of on-board FLASH. Only the Nios 32-bit CPU is supported.
  28. 1.1 GERMS Monitor
  29. ------------------
  30. If GERMS is just not enough, then U-Boot is a great antibiotic.
  31. You will be very pleased with its high degree of configurability
  32. and its rich feature set.
  33. A few of the most obvious limitations of GERMS are overcome by
  34. using U-Boot (See 'Brain Damage'). Most notably, you can use
  35. minicom or Hyperterminal (duh).
  36. 1.2 Altera Source Code
  37. -----------------------
  38. The Nios port does NOT include ANY sources that Altera has the
  39. copyright. This was a conscious decision ... not an accident.
  40. The Altera license is not clear in terms of distributing Altera
  41. sources (when altera silicon is not involved). This isn't really
  42. a problem as little, if any, of the Altera source contains
  43. features that are not already available in U-Boot.
  44. 1.3 Debugging via OCI
  45. ---------------------
  46. The Nios port supports debugging with gdb and/or nios-console
  47. via the JTAG port. Stubs for debugging with gdb via the serial
  48. port are not currently implemented.
  49. 2. CONFIGURATION OPTIONS/SETTINGS
  50. ----------------------------------
  51. 2.1 Nios-specific Options/Settings
  52. -----------------------------------
  53. All configuration options/settings that are specific to Nios begin
  54. with "CONFIG_NIOS_", "CONFIG_SYS_NIOS_", or "CONFIG_SYS_NIOS_CPU_".
  55. The configuration follows a two-stage process. In the first stage
  56. the NIOS CPU core will defined like defined in Alteras SOPC Builder.
  57. At this point we use the "CONFIG_SYS_NIOS_CPU_" defines exclusively. For
  58. more informations about all the definitions you have to setup see
  59. into current board configurations and doc/README.nios_CFG_NIOS_CPU.
  60. In second stage we bring the NIOS CPU configuration in relation to
  61. U-Boot configuration options/settings. The following is a list of
  62. currently defined Nios-specific options/parameters used inside of
  63. U-Boot. If any options are related to Standard-32 Nios SDK
  64. excalibur.h definitions, the related definition follows the
  65. description).
  66. CONFIG_NIOS -- defined for all Nios-32 boards.
  67. CONFIG_SYS_NIOS_CONSOLE -- the base address of the console UART or the JTAG
  68. stdio port. To enable a console via JTAG, define
  69. CONFIG_CONSOLE_JTAG and set CGF_NIOS_CONSOLE to the base address
  70. of the JTAG stdio port (normally OCI base + 0x00fa). Then
  71. run nios-console with the -w option.
  72. (standard-32: nasys_uart_0 resp. na_uart1_base).
  73. CONFIG_SYS_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
  74. parameter is set to '1'.
  75. CONFIG_SYS_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).
  76. CONFIG_SYS_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
  77. MSTEP instruction (not yet implemented).
  78. CONFIG_SYS_NIOS_TMRBASE -- the base address of the timer used to support
  79. xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
  80. (standard-32: nasys_timer_1 resp. na_lo_priority_timer2_base).
  81. CONFIG_SYS_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
  82. the timer. (standard-32: nasys_timer_1_irq resp.
  83. na_low_priority_timer2_irq).
  84. CONFIG_SYS_NIOS_TMRMS -- the period of the timer in milliseconds.
  85. CONFIG_SYS_NIOS_TMRCNT -- the preloadable counter value for the timer if it has
  86. no fixed period.
  87. CONFIG_SYS_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
  88. (standard-32: na_asmi_base).
  89. CONFIG_SYS_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
  90. (nasys_spi_0)
  91. CONFIG_SYS_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
  92. This value can be 8 or 16 only! (PTF: databits)
  93. 2.2 Differences in U-Boot Options/Settings
  94. -------------------------------------------
  95. Some 'standard' U-Boot options/settings are treated differently in
  96. the Nios port. These are described below.
  97. CONFIG_SYS_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
  98. global data structure in the Nios memory space. More simply,
  99. the address of global data.
  100. 3. ASSEMBLY CODING
  101. -------------------
  102. In browsing the assembly source files, you may notice the absence
  103. of the 'magic macros' (e.g. MOVIA, MOVIP, ADDIP etc.). This is
  104. deliberate. The documentation for the magic macros is scant and
  105. it is hard to find ... it does not appear in the Nios programmer's
  106. manual, nor does it appear in the assembler manual. Regardless,
  107. the macros actually do very little to improve readability anyway.
  108. With this in mind, all assembler modules use only instructions that
  109. appear in the Nios programmer's manual OR are directly supported
  110. by the nios-elf toolchain. For example, the 'dec %rB' instruction
  111. is an alias for 'subi %rB,1' that is supported by the assembler
  112. but does not appear in the programmer's manual.
  113. 4. BOOT PROCESS
  114. ---------------
  115. 4.1 Boot process over GERMS
  116. ---------------------------
  117. When the NIOS CPU catch a reset signal it will begin to be running
  118. code from CONFIG_SYS_NIOS_CPU_RST_VECT. Normally at this place it will
  119. find the GERMS monitor. That's the case for the generic NIOS CPU
  120. configuration "standard_32". When the GERMS monitor starts running,
  121. it performs important system initializations and then looks for
  122. executable code in flash, using the following steps:
  123. 1. Examining the two bytes at CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x04000C.
  124. 2. Examining the button 0 on the PIO CONFIG_SYS_NIOS_CPU_BUTTON_PIO.
  125. 3. If the button is not pressed and the two bytes contain 'N'
  126. and 'i', the monitor executes a CALL to location
  127. CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x040000.
  128. 4. If the code is not executed in step 3 or the code returns,
  129. then prints an 8-digit version number to STDOUT and waits for
  130. user commands from STDIN.
  131. In normal case, for "standard_32", STDIN and STDOUT are the first
  132. serial port.
  133. 4.2 Return to GERMS command line
  134. --------------------------------
  135. During the boot process, the GERMS monitor checks for the existence
  136. of application software in flash memory. If found, the processor
  137. immediately executes the code. To return program execution to the
  138. GERMS monitor (that is, avoid running code stored in flash memory):
  139. 1. Hold down CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.
  140. 2. Press then release the CPU reset button.
  141. 3. Release CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.
  142. 5. DEBUGGING WITH GDB
  143. ---------------------
  144. Debug sessions using gdb are currently supported only via JTAG. The
  145. stubs for debugging via a serial port are not implemented. To enable
  146. the gdb JTAG stubs, simply reference _brkpt_hw_int and _brkpt_sw_int
  147. at vector table offsets 3 and 4, respectively. For an example, see
  148. board/altera/dk1c20/vectors.S.
  149. 5.1 Vector Table Initialization and ROM Stubs
  150. ---------------------------------------------
  151. If CONFIG_ROM_STUBS is defined, the debug breakpoint and single step
  152. entries in the vector table are restored to their initial values
  153. immediately _after_ initializing the vector table. Defining this macro
  154. is useful when ROM-based stubs are implemented.
  155. NOTE: The default GERMS monitor does NOT implement gdb stubs, nor does
  156. it initialize the vector table. Therefore, when debugging U-Boot, you
  157. should NOT set a software breakpoint prior to vector table initialization.
  158. 5.2 Starting a Debug Session
  159. ----------------------------
  160. If you're not familiar with gdb, you follow these step-by-step instructions.
  161. These instructions are NOT the only way to start a debug session, but they
  162. cover most of the individual functions to get you started.
  163. 1. Start the JTAG gdb server. Open a Nios shell window and start
  164. the server. When the server is started you must provide the base
  165. address of the OCI core. For example, when using the Cyclone
  166. development kit (DK1C20):
  167. $ nios-gdb-server --ocibase=0x00920800 --tcpport=2342
  168. 2. Start gdb. Open a Nios shell window, change to the top-level
  169. U-Boot directory and start gdb, specifying the u-boot elf file:
  170. $ nios-elf-gdb u-boot
  171. 3. Update target settings. From the file menu, select
  172. "Target Settings ..." and select the following, then click 'Ok':
  173. Target: Remote/TCP
  174. Port : 2342 (same as in step 1)
  175. Display download dialog: checked
  176. All other check boxes: unchecked
  177. 4. Connect to the target. Select menu: 'Run->Connect to target'.
  178. You should see a dialog box indicating the you successfully connected
  179. to the target.
  180. 5. Download U-Boot. Select menu: 'Run->Download'.
  181. 6. Open a gdb console window and set the source directory paths.
  182. Select menu: 'View->Console'. In the console window, enter the
  183. following commands, then close the console window:
  184. (gdb) directory common
  185. (gdb) directory cpu/nios
  186. (gdb) directory lib_nios
  187. (gdb) directory board/altera/dk1c20
  188. Note that the last command is for the DK1C20 board only. If you
  189. are using another board, specify that board's directory.
  190. 7. Open the file board.c (using the file menu in the lower
  191. left hand corner). Scroll to the board_init() routine and set
  192. a breakpoint.
  193. 8. Run U-Boot. Just click on the run icon, or select menu:
  194. 'Run->Run'. U-Boot should start running, then break at your
  195. breakpoint.
  196. 9. Have fun & start learning more about gdb.
  197. 5.3 For advanced Users
  198. ----------------------
  199. A few notes for those more familiar with gdb.
  200. -Serial port stubs are not implemented. Sorry, but it's just not
  201. worth _my_ effort. The JTAG stubs work great and are ridiculously
  202. simple to implement.
  203. -If you need to debug the early startup code (prior to the vector
  204. table initialization), use the nios-console debugger.
  205. - Connect, download & run -- there are some problems here. Connect
  206. download and run seperately to avoid trouble.
  207. 6. BRAIN DAMAGE
  208. ----------------
  209. This section describes some of the unfortunate and avoidable aspects
  210. of working with the Nios CPU ... and some things you can do to
  211. reduce your pain.
  212. 6.1 GERMS doesn't work with Hyperterminal
  213. ------------------------------------------
  214. GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
  215. (or minicom) -- geez. Regardless of you opion of Hyperterminal, this
  216. sad design decision is remedied by using U-Boot.
  217. 6.2 cygwin Incompatibility
  218. ---------------------------
  219. The version of cygwin distributed with the nios GNUPro toolchain is
  220. out-of-date and incompatible with the latest cygwin distributions.
  221. In addition, many of the standard utilities are very dated as well.
  222. If you try to download and build the lastest version of grep for
  223. example, you'll quickly realize that a native gcc is not available
  224. (the next topic) which leads to U-Boot build problems (following
  225. topic).
  226. The solution ... well, you can wait for Altera ... or build as
  227. set of tools for linux.
  228. 6.3 No native gcc
  229. ------------------
  230. I'm not sure how this one slipped through the cracks ... but it is
  231. a real pain. Basically, if you want to build anything for the native
  232. environment -- forget it! A native (cygwin) gcc is not distributed,
  233. and the old version of cygwin makes locating one challenging.
  234. The solution ... same as above. Just download the gcc source from
  235. Altera and build up a set of cross tools for your favorite linux
  236. distro. Anybody who wants to use an already precompiled NIOS cross
  237. toolchain can it found in the CDK4NIOS project hosted by Source
  238. Forge at http://cdk4nios.sourceforge.net.
  239. 6.4 Can't build default U-Boot
  240. -------------------------------
  241. By default, when you build U-Boot you will be building some native
  242. tools along with the target elf, bin, and srec files. Without a
  243. native gcc, this (obviously) causes problems.
  244. For developers using the Altera cygwin tools you can remove the
  245. 'tools' directory from SUBDIRS in the top-level Makefile. You will
  246. also have to edit common/Makefile:
  247. Replace:
  248. env_embedded.o: env_embedded.c ../tools/envcrc
  249. $(CC) $(AFLAGS) -Wa,--no-warn \
  250. -DENV_CRC=$(shell ../tools/envcrc) \
  251. -c -o $@ env_embedded.c
  252. With:
  253. env_embedded.o: env_embedded.c
  254. $(CC) $(AFLAGS) -Wa,--no-warn \
  255. -DENV_CRC=0 \
  256. -c -o $@ env_embedded.c
  257. BTW, thats a 'zero' ... not the letter 'O'. And not that the
  258. "../tools/envcrc" dependency is removed.
  259. 7. HELP WANTED
  260. ---------------
  261. There are plenty of areas where help is needed. Here's are some ideas
  262. for those interested in contributing:
  263. -CompactFlash. Port & test CF/FAT.
  264. -Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
  265. command.
  266. -Add boot support for ucLinux (niosnommu).
  267. -Implement (don't copy Altera code) the __mulxx routines using the
  268. MSTEP and MUL instructions (e.g. CONFIG_SYS_NIOS_MULT_HW and CONFIG_SYS_NIOS_MULT_MSTEP).
  269. Regards,
  270. --Scott
  271. <smcnutt@psyent.com>
  272. --Stephan
  273. <linz@li-pro.net>