doc/README.nios - u-boot - Git at Google


 			   U-Boot for Nios-32

 		    Last Update: February 1, 2004
 ====================================================================

 This file contains information regarding U-Boot and the Altera
 Nios CPU. For information regarding U-Boot and the Nios Development
 Kits see:

   * Cyclone Edition (DK-1C20), see doc/README.dk1c20
   * Stratix Edition (DK-1S10), see doc/README.dk1s10 (TODO)
   * Stratix Edition (DK-1S40), see doc/README.dk1s40 (TODO)
   * Stratix Edition (DK-20K200), see doc/README.dk20k200 (TODO)

 For informations regarding Nios Development Kit hardware overview
 and the NIOS CPU standard configuration of all known boards made by
 Altera see:

   * Development Kit (DK) hardware overview, see doc/README.nios_DK
   * NIOS CPU standard_32 at DK-1C20, see doc/README.dk1c20_std32
   * NIOS CPU standard_32 at DK-1S10, see doc/README.dk1s10_std32
   * NIOS CPU standard_32 at DK-1S40, see doc/README.dk1s40_std32
   * NIOS CPU standard_32 at DK-20K200, see doc/README.dk20k200_std32

 For those interested in contributing ... see HELP WANTED below.


 1. OVERVIEW
 ------------

 U-Boot has been successfully tested on the Nios Cyclone development
 board using both the 'safe' and 'standard 32' configurations with
 Nios CPU revision 3.1 (CPU_ID = 0x3018). U-Boot can be used with
 or without the GERMS monitor. The initial version of U-Boot for the
 Cyclone development kit is about 60 Kbyte and will fit in a single
 sector of on-board FLASH. Only the Nios 32-bit CPU is supported.

 1.1 GERMS Monitor
 ------------------
 If GERMS is just not enough, then U-Boot is a great antibiotic.
 You will be very pleased with its high degree of configurability
 and its rich feature set.

 A few of the most obvious limitations of GERMS are overcome by
 using U-Boot (See 'Brain Damage'). Most notably, you can use
 minicom or Hyperterminal (duh).

 1.2 Altera Source Code
 -----------------------
 The Nios port does NOT include ANY sources that Altera has the
 copyright. This was a conscious decision ... not an accident.
 The Altera license is not clear in terms of distributing Altera
 sources (when altera silicon is not involved). This isn't really
 a problem as little, if any, of the Altera source contains
 features that are not already available in U-Boot.

 1.3 Debugging via OCI
 ---------------------
 The Nios port supports debugging with gdb and/or nios-console
 via the JTAG port. Stubs for debugging with gdb via the serial
 port are not currently implemented.


 2. CONFIGURATION OPTIONS/SETTINGS
 ----------------------------------

 2.1 Nios-specific Options/Settings
 -----------------------------------
 All configuration options/settings that are specific to Nios begin
 with "CONFIG_NIOS_", "CONFIG_SYS_NIOS_", or "CONFIG_SYS_NIOS_CPU_".

 The configuration follows a two-stage process. In the first stage
 the NIOS CPU core will defined like defined in Alteras SOPC Builder.
 At this point we use the "CONFIG_SYS_NIOS_CPU_" defines exclusively. For
 more informations about all the definitions you have to setup see
 into current board configurations and doc/README.nios_CFG_NIOS_CPU.

 In second stage we bring the NIOS CPU configuration in relation to
 U-Boot configuration options/settings. The following is a list of
 currently defined Nios-specific options/parameters used inside of
 U-Boot. If any options are related to Standard-32 Nios SDK
 excalibur.h definitions, the related definition follows the
 description).

 CONFIG_NIOS -- defined for all Nios-32 boards.

 CONFIG_SYS_NIOS_CONSOLE -- the base address of the console UART or the JTAG
 	stdio port. To enable a console via JTAG, define
 	CONFIG_CONSOLE_JTAG and set CGF_NIOS_CONSOLE to the base address
 	of the JTAG stdio port (normally OCI base + 0x00fa). Then
 	run nios-console with the -w option.
 	(standard-32: nasys_uart_0 resp. na_uart1_base).

 CONFIG_SYS_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
 	parameter is set to '1'.

 CONFIG_SYS_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).

 CONFIG_SYS_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
 	MSTEP instruction (not yet implemented).

 CONFIG_SYS_NIOS_TMRBASE -- the base address of the timer used to support
 	xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
 	(standard-32: nasys_timer_1 resp. na_lo_priority_timer2_base).

 CONFIG_SYS_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
 	the timer. (standard-32: nasys_timer_1_irq resp.
 	na_low_priority_timer2_irq).

 CONFIG_SYS_NIOS_TMRMS -- the period of the timer in milliseconds.

 CONFIG_SYS_NIOS_TMRCNT -- the preloadable counter value for the timer if it has
 	no fixed period.

 CONFIG_SYS_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
 	(standard-32: na_asmi_base).

 CONFIG_SYS_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
 	(nasys_spi_0)

 CONFIG_SYS_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
 	This value can be 8 or 16 only! (PTF: databits)


 2.2 Differences in U-Boot Options/Settings
 -------------------------------------------
 Some 'standard' U-Boot options/settings are treated differently in
 the Nios port. These are described below.

 CONFIG_SYS_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
 	global data structure in the Nios memory space. More simply,
 	the address of global data.


 3. ASSEMBLY CODING
 -------------------

 In browsing the assembly source files, you may notice the absence
 of the 'magic macros' (e.g. MOVIA, MOVIP, ADDIP etc.). This is
 deliberate. The documentation for the magic macros is scant and
 it is hard to find ... it does not appear in the Nios programmer's
 manual, nor does it appear in the assembler manual. Regardless,
 the macros actually do very little to improve readability anyway.

 With this in mind, all assembler modules use only instructions that
 appear in the Nios programmer's manual OR are directly supported
 by the nios-elf toolchain. For example, the 'dec %rB' instruction
 is an alias for 'subi %rB,1' that is supported by the assembler
 but does not appear in the programmer's manual.


 4. BOOT PROCESS
 ---------------

 4.1 Boot process over GERMS
 ---------------------------
 When the NIOS CPU catch a reset signal it will begin to be running
 code from CONFIG_SYS_NIOS_CPU_RST_VECT. Normally at this place it will
 find the GERMS monitor. That's the case for the generic NIOS CPU
 configuration "standard_32". When the GERMS monitor starts running,
 it performs important system initializations and then looks for
 executable code in flash, using the following steps:

     1. Examining the two bytes at CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x04000C.
     2. Examining the button 0 on the PIO CONFIG_SYS_NIOS_CPU_BUTTON_PIO.
     3. If the button is not pressed and the two bytes contain 'N'
        and 'i', the monitor executes a CALL to location
        CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x040000.
     4. If the code is not executed in step 3 or the code returns,
        then prints an 8-digit version number to STDOUT and waits for
        user commands from STDIN.

 In normal case, for "standard_32", STDIN and STDOUT are the first
 serial port.

 4.2 Return to GERMS command line
 --------------------------------
 During the boot process, the GERMS monitor checks for the existence
 of application software in flash memory. If found, the processor
 immediately executes the code. To return program execution to the
 GERMS monitor (that is, avoid running code stored in flash memory):

     1. Hold down CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.
     2. Press then release the CPU reset button.
     3. Release CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.


 5. DEBUGGING WITH GDB
 ---------------------

 Debug sessions using gdb are currently supported only via JTAG. The
 stubs for debugging via a serial port are not implemented. To enable
 the gdb JTAG stubs, simply reference _brkpt_hw_int and _brkpt_sw_int
 at vector table offsets 3 and 4, respectively. For an example, see
 board/altera/dk1c20/vectors.S.

 5.1 Vector Table Initialization and ROM Stubs
 ---------------------------------------------
 If CONFIG_ROM_STUBS is defined, the debug breakpoint and single step
 entries in the vector table are restored to their initial values
 immediately _after_ initializing the vector table. Defining this macro
 is useful when ROM-based stubs are implemented.

 NOTE: The default GERMS monitor does NOT implement gdb stubs, nor does
 it initialize the vector table. Therefore, when debugging U-Boot, you
 should NOT set a software breakpoint prior to vector table initialization.

 5.2 Starting a Debug Session
 ----------------------------
 If you're not familiar with gdb, you follow these step-by-step instructions.
 These instructions are NOT the only way to start a debug session, but they
 cover most of the individual functions to get you started.

 	1.  Start the JTAG gdb server. Open a Nios shell window and start
 	the server. When the server is started you must provide the base
 	address of the OCI core. For example, when using the Cyclone
 	development kit (DK1C20):

 		$ nios-gdb-server --ocibase=0x00920800 --tcpport=2342

 	2.  Start gdb. Open a Nios shell window, change to the top-level
 	U-Boot directory and start gdb, specifying the u-boot elf file:

 		$ nios-elf-gdb u-boot

 	3.  Update target settings. From the file menu, select
 	"Target Settings ..." and select the following, then click 'Ok':

 		Target:	Remote/TCP
 		Port :	2342   (same as in step 1)
 		Display download dialog: checked
 		All other check boxes: unchecked

 	4.  Connect to the target. Select menu: 'Run->Connect to target'.
 	You should see a dialog box indicating the you successfully connected
 	to the target.

 	5.  Download U-Boot. Select menu: 'Run->Download'.

 	6.  Open a gdb console window and set the source directory paths.
 	Select menu: 'View->Console'. In the console window, enter the
 	following commands, then close the console window:

 		(gdb) directory common
 		(gdb) directory cpu/nios
 		(gdb) directory lib_nios
 		(gdb) directory board/altera/dk1c20

 	Note that the last command is for the DK1C20 board only. If you
 	are using another board, specify that board's directory.

 	7.  Open the file board.c (using the file menu in the lower
 	left hand corner). Scroll to the board_init() routine and set
 	a breakpoint.

 	8. Run U-Boot. Just click on the run icon, or select menu:
 	'Run->Run'. U-Boot should start running, then break at your
 	breakpoint.

 	9.  Have fun & start learning more about gdb.


 5.3 For advanced Users
 ----------------------
 A few notes for those more familiar with gdb.

 	-Serial port stubs are not implemented. Sorry, but it's just not
 	worth _my_ effort. The JTAG stubs work great and are ridiculously
 	simple to implement.

 	-If you need to debug the early startup code (prior to the vector
 	table initialization), use the nios-console debugger.

 	- Connect, download & run -- there are some problems here. Connect
 	download and run seperately to avoid trouble.

 6. BRAIN DAMAGE
 ----------------

 This section describes some of the unfortunate and avoidable aspects
 of working with the Nios CPU ... and some things you can do to
 reduce your pain.

 6.1 GERMS doesn't work with Hyperterminal
 ------------------------------------------
 GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
 (or minicom) -- geez. Regardless of you opion of Hyperterminal, this
 sad design decision is remedied by using U-Boot.

 6.2 cygwin Incompatibility
 ---------------------------
 The version of cygwin distributed with the nios GNUPro toolchain is
 out-of-date and incompatible with the latest cygwin distributions.
 In addition, many of the standard utilities are very dated as well.
 If you try to download and build the lastest version of grep for
 example, you'll quickly realize that a native gcc is not available
 (the next topic) which leads to U-Boot build problems (following
 topic).

 The solution ... well, you can wait for Altera ... or build as
 set of tools for linux.

 6.3 No native gcc
 ------------------
 I'm not sure how this one slipped through the cracks ... but it is
 a real pain. Basically, if you want to build anything for the native
 environment -- forget it! A native (cygwin) gcc is not distributed,
 and the old version of cygwin makes locating one challenging.

 The solution ... same as above. Just download the gcc source from
 Altera and build up a set of cross tools for your favorite linux
 distro. Anybody who wants to use an already precompiled NIOS cross
 toolchain can it found in the CDK4NIOS project hosted by Source
 Forge at http://cdk4nios.sourceforge.net.

 6.4 Can't build default U-Boot
 -------------------------------
 By default, when you build U-Boot you will be building some native
 tools along with the target elf, bin, and srec files. Without a
 native gcc, this (obviously) causes problems.

 For developers using the Altera cygwin tools you can remove the
 'tools' directory from SUBDIRS in the top-level Makefile. You will
 also have to edit common/Makefile:

 Replace:
 env_embedded.o: env_embedded.c ../tools/envcrc
 	$(CC) $(AFLAGS) -Wa,--no-warn \
 		-DENV_CRC=$(shell ../tools/envcrc) \
 		-c -o $@ env_embedded.c

 With:
 env_embedded.o: env_embedded.c
 	$(CC) $(AFLAGS) -Wa,--no-warn \
 		-DENV_CRC=0 \
 		-c -o $@ env_embedded.c

 BTW, thats a 'zero' ... not the letter 'O'. And not that the
 "../tools/envcrc" dependency is removed.


 7. HELP WANTED
 ---------------

 There are plenty of areas where help is needed. Here's are some ideas
 for those interested in contributing:

 -CompactFlash. Port & test CF/FAT.

 -Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
  command.

 -Add boot support for ucLinux (niosnommu).

 -Implement (don't copy Altera code) the __mulxx routines using the
  MSTEP and MUL instructions (e.g. CONFIG_SYS_NIOS_MULT_HW and CONFIG_SYS_NIOS_MULT_MSTEP).


 Regards,

 --Scott
 <smcnutt@psyent.com>

 --Stephan
 <linz@li-pro.net>

	U-Boot for Nios-32

	Last Update: February 1, 2004
	====================================================================

	This file contains information regarding U-Boot and the Altera
	Nios CPU. For information regarding U-Boot and the Nios Development
	Kits see:

	* Cyclone Edition (DK-1C20), see doc/README.dk1c20
	* Stratix Edition (DK-1S10), see doc/README.dk1s10 (TODO)
	* Stratix Edition (DK-1S40), see doc/README.dk1s40 (TODO)
	* Stratix Edition (DK-20K200), see doc/README.dk20k200 (TODO)

	For informations regarding Nios Development Kit hardware overview
	and the NIOS CPU standard configuration of all known boards made by
	Altera see:

	* Development Kit (DK) hardware overview, see doc/README.nios_DK
	* NIOS CPU standard_32 at DK-1C20, see doc/README.dk1c20_std32
	* NIOS CPU standard_32 at DK-1S10, see doc/README.dk1s10_std32
	* NIOS CPU standard_32 at DK-1S40, see doc/README.dk1s40_std32
	* NIOS CPU standard_32 at DK-20K200, see doc/README.dk20k200_std32

	For those interested in contributing ... see HELP WANTED below.


	1. OVERVIEW
	------------

	U-Boot has been successfully tested on the Nios Cyclone development
	board using both the 'safe' and 'standard 32' configurations with
	Nios CPU revision 3.1 (CPU_ID = 0x3018). U-Boot can be used with
	or without the GERMS monitor. The initial version of U-Boot for the
	Cyclone development kit is about 60 Kbyte and will fit in a single
	sector of on-board FLASH. Only the Nios 32-bit CPU is supported.

	1.1 GERMS Monitor
	------------------
	If GERMS is just not enough, then U-Boot is a great antibiotic.
	You will be very pleased with its high degree of configurability
	and its rich feature set.

	A few of the most obvious limitations of GERMS are overcome by
	using U-Boot (See 'Brain Damage'). Most notably, you can use
	minicom or Hyperterminal (duh).

	1.2 Altera Source Code
	-----------------------
	The Nios port does NOT include ANY sources that Altera has the
	copyright. This was a conscious decision ... not an accident.
	The Altera license is not clear in terms of distributing Altera
	sources (when altera silicon is not involved). This isn't really
	a problem as little, if any, of the Altera source contains
	features that are not already available in U-Boot.

	1.3 Debugging via OCI
	---------------------
	The Nios port supports debugging with gdb and/or nios-console
	via the JTAG port. Stubs for debugging with gdb via the serial
	port are not currently implemented.


	2. CONFIGURATION OPTIONS/SETTINGS
	----------------------------------

	2.1 Nios-specific Options/Settings
	-----------------------------------
	All configuration options/settings that are specific to Nios begin
	with "CONFIG_NIOS_", "CONFIG_SYS_NIOS_", or "CONFIG_SYS_NIOS_CPU_".

	The configuration follows a two-stage process. In the first stage
	the NIOS CPU core will defined like defined in Alteras SOPC Builder.
	At this point we use the "CONFIG_SYS_NIOS_CPU_" defines exclusively. For
	more informations about all the definitions you have to setup see
	into current board configurations and doc/README.nios_CFG_NIOS_CPU.

	In second stage we bring the NIOS CPU configuration in relation to
	U-Boot configuration options/settings. The following is a list of
	currently defined Nios-specific options/parameters used inside of
	U-Boot. If any options are related to Standard-32 Nios SDK
	excalibur.h definitions, the related definition follows the
	description).

	CONFIG_NIOS -- defined for all Nios-32 boards.

	CONFIG_SYS_NIOS_CONSOLE -- the base address of the console UART or the JTAG
	stdio port. To enable a console via JTAG, define
	CONFIG_CONSOLE_JTAG and set CGF_NIOS_CONSOLE to the base address
	of the JTAG stdio port (normally OCI base + 0x00fa). Then
	run nios-console with the -w option.
	(standard-32: nasys_uart_0 resp. na_uart1_base).

	CONFIG_SYS_NIOS_FIXEDBAUD -- defined if the console UART PTF fixed_baud
	parameter is set to '1'.

	CONFIG_SYS_NIOS_MULT_HW -- use full hardware multiply (not yet implemented).

	CONFIG_SYS_NIOS_MULT_MSTEP -- use hardware assisted multiply using the
	MSTEP instruction (not yet implemented).

	CONFIG_SYS_NIOS_TMRBASE -- the base address of the timer used to support
	xxx_timer routines (e.g. set_timer(), get_timer(), etc.).
	(standard-32: nasys_timer_1 resp. na_lo_priority_timer2_base).

	CONFIG_SYS_NIOS_TMRIRQ -- the interrupt request (vector number) assigned to
	the timer. (standard-32: nasys_timer_1_irq resp.
	na_low_priority_timer2_irq).

	CONFIG_SYS_NIOS_TMRMS -- the period of the timer in milliseconds.

	CONFIG_SYS_NIOS_TMRCNT -- the preloadable counter value for the timer if it has
	no fixed period.

	CONFIG_SYS_NIOS_ASMIBASE -- the base address of the ASMI peripheral.
	(standard-32: na_asmi_base).

	CONFIG_SYS_NIOS_SPIBASE -- the base address of the SPI master (!) peripheral.
	(nasys_spi_0)

	CONFIG_SYS_NIOS_SPIBITS -- the amount of configured SPI data bits in PTF.
	This value can be 8 or 16 only! (PTF: databits)


	2.2 Differences in U-Boot Options/Settings
	-------------------------------------------
	Some 'standard' U-Boot options/settings are treated differently in
	the Nios port. These are described below.

	CONFIG_SYS_GBL_DATA_OFFSET -- in the Nios port, this is the offset of the
	global data structure in the Nios memory space. More simply,
	the address of global data.


	3. ASSEMBLY CODING
	-------------------

	In browsing the assembly source files, you may notice the absence
	of the 'magic macros' (e.g. MOVIA, MOVIP, ADDIP etc.). This is
	deliberate. The documentation for the magic macros is scant and
	it is hard to find ... it does not appear in the Nios programmer's
	manual, nor does it appear in the assembler manual. Regardless,
	the macros actually do very little to improve readability anyway.

	With this in mind, all assembler modules use only instructions that
	appear in the Nios programmer's manual OR are directly supported
	by the nios-elf toolchain. For example, the 'dec %rB' instruction
	is an alias for 'subi %rB,1' that is supported by the assembler
	but does not appear in the programmer's manual.


	4. BOOT PROCESS
	---------------

	4.1 Boot process over GERMS
	---------------------------
	When the NIOS CPU catch a reset signal it will begin to be running
	code from CONFIG_SYS_NIOS_CPU_RST_VECT. Normally at this place it will
	find the GERMS monitor. That's the case for the generic NIOS CPU
	configuration "standard_32". When the GERMS monitor starts running,
	it performs important system initializations and then looks for
	executable code in flash, using the following steps:

	1. Examining the two bytes at CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x04000C.
	2. Examining the button 0 on the PIO CONFIG_SYS_NIOS_CPU_BUTTON_PIO.
	3. If the button is not pressed and the two bytes contain 'N'
	and 'i', the monitor executes a CALL to location
	CONFIG_SYS_NIOS_CPU_FLASH_BASE + 0x040000.
	4. If the code is not executed in step 3 or the code returns,
	then prints an 8-digit version number to STDOUT and waits for
	user commands from STDIN.

	In normal case, for "standard_32", STDIN and STDOUT are the first
	serial port.

	4.2 Return to GERMS command line
	--------------------------------
	During the boot process, the GERMS monitor checks for the existence
	of application software in flash memory. If found, the processor
	immediately executes the code. To return program execution to the
	GERMS monitor (that is, avoid running code stored in flash memory):

	1. Hold down CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.
	2. Press then release the CPU reset button.
	3. Release CONFIG_SYS_NIOS_CPU_BUTTON_PIO, button number 0.


	5. DEBUGGING WITH GDB
	---------------------

	Debug sessions using gdb are currently supported only via JTAG. The
	stubs for debugging via a serial port are not implemented. To enable
	the gdb JTAG stubs, simply reference _brkpt_hw_int and _brkpt_sw_int
	at vector table offsets 3 and 4, respectively. For an example, see
	board/altera/dk1c20/vectors.S.

	5.1 Vector Table Initialization and ROM Stubs
	---------------------------------------------
	If CONFIG_ROM_STUBS is defined, the debug breakpoint and single step
	entries in the vector table are restored to their initial values
	immediately _after_ initializing the vector table. Defining this macro
	is useful when ROM-based stubs are implemented.

	NOTE: The default GERMS monitor does NOT implement gdb stubs, nor does
	it initialize the vector table. Therefore, when debugging U-Boot, you
	should NOT set a software breakpoint prior to vector table initialization.

	5.2 Starting a Debug Session
	----------------------------
	If you're not familiar with gdb, you follow these step-by-step instructions.
	These instructions are NOT the only way to start a debug session, but they
	cover most of the individual functions to get you started.

	1. Start the JTAG gdb server. Open a Nios shell window and start
	the server. When the server is started you must provide the base
	address of the OCI core. For example, when using the Cyclone
	development kit (DK1C20):

	$ nios-gdb-server --ocibase=0x00920800 --tcpport=2342

	2. Start gdb. Open a Nios shell window, change to the top-level
	U-Boot directory and start gdb, specifying the u-boot elf file:

	$ nios-elf-gdb u-boot

	3. Update target settings. From the file menu, select
	"Target Settings ..." and select the following, then click 'Ok':

	Target: Remote/TCP
	Port : 2342 (same as in step 1)
	Display download dialog: checked
	All other check boxes: unchecked

	4. Connect to the target. Select menu: 'Run->Connect to target'.
	You should see a dialog box indicating the you successfully connected
	to the target.

	5. Download U-Boot. Select menu: 'Run->Download'.

	6. Open a gdb console window and set the source directory paths.
	Select menu: 'View->Console'. In the console window, enter the
	following commands, then close the console window:

	(gdb) directory common
	(gdb) directory cpu/nios
	(gdb) directory lib_nios
	(gdb) directory board/altera/dk1c20

	Note that the last command is for the DK1C20 board only. If you
	are using another board, specify that board's directory.

	7. Open the file board.c (using the file menu in the lower
	left hand corner). Scroll to the board_init() routine and set
	a breakpoint.

	8. Run U-Boot. Just click on the run icon, or select menu:
	'Run->Run'. U-Boot should start running, then break at your
	breakpoint.

	9. Have fun & start learning more about gdb.


	5.3 For advanced Users
	----------------------
	A few notes for those more familiar with gdb.

	-Serial port stubs are not implemented. Sorry, but it's just not
	worth _my_ effort. The JTAG stubs work great and are ridiculously
	simple to implement.

	-If you need to debug the early startup code (prior to the vector
	table initialization), use the nios-console debugger.

	- Connect, download & run -- there are some problems here. Connect
	download and run seperately to avoid trouble.

	6. BRAIN DAMAGE
	----------------

	This section describes some of the unfortunate and avoidable aspects
	of working with the Nios CPU ... and some things you can do to
	reduce your pain.

	6.1 GERMS doesn't work with Hyperterminal
	------------------------------------------
	GERMS doesn't do CR/LF mapping that is compatible with Hyperterminal
	(or minicom) -- geez. Regardless of you opion of Hyperterminal, this
	sad design decision is remedied by using U-Boot.

	6.2 cygwin Incompatibility
	---------------------------
	The version of cygwin distributed with the nios GNUPro toolchain is
	out-of-date and incompatible with the latest cygwin distributions.
	In addition, many of the standard utilities are very dated as well.
	If you try to download and build the lastest version of grep for
	example, you'll quickly realize that a native gcc is not available
	(the next topic) which leads to U-Boot build problems (following
	topic).

	The solution ... well, you can wait for Altera ... or build as
	set of tools for linux.

	6.3 No native gcc
	------------------
	I'm not sure how this one slipped through the cracks ... but it is
	a real pain. Basically, if you want to build anything for the native
	environment -- forget it! A native (cygwin) gcc is not distributed,
	and the old version of cygwin makes locating one challenging.

	The solution ... same as above. Just download the gcc source from
	Altera and build up a set of cross tools for your favorite linux
	distro. Anybody who wants to use an already precompiled NIOS cross
	toolchain can it found in the CDK4NIOS project hosted by Source
	Forge at http://cdk4nios.sourceforge.net.

	6.4 Can't build default U-Boot
	-------------------------------
	By default, when you build U-Boot you will be building some native
	tools along with the target elf, bin, and srec files. Without a
	native gcc, this (obviously) causes problems.

	For developers using the Altera cygwin tools you can remove the
	'tools' directory from SUBDIRS in the top-level Makefile. You will
	also have to edit common/Makefile:

	Replace:
	env_embedded.o: env_embedded.c ../tools/envcrc
	$(CC) $(AFLAGS) -Wa,--no-warn \
	-DENV_CRC=$(shell ../tools/envcrc) \
	-c -o $@ env_embedded.c

	With:
	env_embedded.o: env_embedded.c
	$(CC) $(AFLAGS) -Wa,--no-warn \
	-DENV_CRC=0 \
	-c -o $@ env_embedded.c

	BTW, thats a 'zero' ... not the letter 'O'. And not that the
	"../tools/envcrc" dependency is removed.


	7. HELP WANTED
	---------------

	There are plenty of areas where help is needed. Here's are some ideas
	for those interested in contributing:

	-CompactFlash. Port & test CF/FAT.

	-Bedbug. Develop bedbug for Nios ... or at least provide a disassemble
	command.

	-Add boot support for ucLinux (niosnommu).

	-Implement (don't copy Altera code) the __mulxx routines using the
	MSTEP and MUL instructions (e.g. CONFIG_SYS_NIOS_MULT_HW and CONFIG_SYS_NIOS_MULT_MSTEP).


	Regards,

	--Scott
	<smcnutt@psyent.com>

	--Stephan
	<linz@li-pro.net>