rename CFG_ macros to CONFIG_SYS

[people/ms/u-boot.git] / doc / README.adnpesc1

	      SSV ADNP/ESC1 Embedded Softcore Computing
		 Nios Softcore, Altera Cyclone FPGA

		    Last Update: February 27, 2004
====================================================================

This file contains information regarding U-Boot and the SSV Embedded
Nios Softcore Computing platform ADNP/ESC1. For general Nios
information see doc/README.nios.

Most stuff of this file was borrowed and based on README.dk1s10,
the Altera DK-1S10 related information file.

For those interested in contributing ... see HELP WANTED section
in doc/README.nios.

Contents:

	1. Files
	2. Memory Organization
	3. CPU Variations
	4. Examples
	5. Programming U-Boot into FLASH with GERMS
	6. Autoboot
	7. U-Boot environment convention and update philosophy

====================================================================

1. Files
=========
	board/ssv/adnpesc1/*
	include/configs/ADNPESC1.h
	include/configs/ADNPESC1_base_32.h


2. Memory Organization
=======================

For the most part, you can put things pretty much anywhere.
This is pretty flexible for Nios. So here we make some arbitrary
choices & assume that the monitor is placed at the end of a memory
resource. So you must make sure TEXT_BASE is chosen appropriately.
This is very important if you plan to move your memory to another
place as configured at this time!

	-The heap is placed below the monitor (U-Boot code).
	-Global data is placed below the heap.
	-The stack is placed below global data (&grows down).

(see doc/README.adnpesc1_base32 too)


3. CPU Variations
=================

There are more than one NIOS CPU variation for the ADNP/ESC1 possible.
U-Boot supports the following CPU configurations:

	- SSV Basis 32 (make ADNPESC1_base_32_config)
	- SSV Basis 32 at DNP evaluation base board 2
	  (make ADNPESC1_DNPEVA2_base_32_config)


4. Examples
============

The hello_world example works fine. To try out you have to change
the default load address from 0x0100_0000 to 0x0204_0000 in
examples/Makefile (the real SDRAM for default board configuration).


5. Programming U-Boot into FLASH with GERMS
============================================

The current version of the ADNP/ESC1 port with the default
configuration settings occupies about 97 KBytes of flash.
A minimal configuration occupies less than 70 KByte
(network, SPI, POST and board command support disabled). You
can save more memory by deactivating the Hu-Shell support and
long command help (CONFIG_SYS_HUSH_PARSER, CONFIG_SYS_LONGHELP).

To program U-Boot into the ADNP/ESC1 flash using GERMS do the
following:

1. Download U-Boot to its target run space in SDRAM:

   a. Close jumper RCM_EN# and push the reset button.

   b. From the command line, download U-Boot using the
      nios-run:

	$ nios-run -r u-boot.srec

      NOTE: In some cases this want fail. I don't know why,
	    but try again.

This takes about 1 minute (GERMS is not very speedy here).
After u-boot is downloaded it will be executed. You should
see the following:

    U-Boot 1.0.2 (Jan 30 2004 - 12:59:15)

    CPU: Nios-32 Rev. 3.3 (0x3038)
    Reg file size: 512 LO_LIMIT/HI_LIMIT: 1/30
    Board: SSV DilNetPC ADNP/ESC1
    Conf.: SSV Base 32 (nios_32)
    In:    serial
    Out:   serial
    Err:   serial
    ADNPESC1 >


2. Quit nios-run and start your terminal application (e.g. start
   Hyperterminal or minicom).

3. Download the u-boot code to RAM. When using Hyperterminal, do the
   following:

   a. From the u-boot command prompt start a binary download to SDRAM:

      at the SSV Basis 32 to SDRAM:

	==> loadb 2000100

   b. Download u-boot.bin using kermit.

4. From the U-Boot command prompt, erase flash:

   at the SSV Basis 32 from 0x1000000 to 0x103ffff:

	==> protect off 1:0-3
	==> erase 1:0-3

5. Copy the binary image from SDRAM to flash:

   at the SSV Basis 32 from SDRAM:

	==> cp.b 2000100 1000000 $filesize

U-Boot will now automatically start when the board is powered on or
reset using the SSV Basis 32 configuration without closed RCM jumper.
To start U-Boot with closed RCM Jumper, enter the following GERMS
command:

    + g 1000000


6. Autoboot
===========

U-Boot will try to boot a valid Nios application from Flash. For this
it will use the deposited Hu-Shell script in environment variable
'bootcmd' which is looking for a valid Nios application identifier
string in Flash and go on at even its entry address. For more
information see the next chapter.


7. U-Boot environment convention and update philosophy
======================================================

U-Boot for the SSV ADNP/ESC1 target knows about many environment
variables used to control the startup process, update process for
raw Nios applications, and optionally file system image updates.
In default configuration there are two Hu-Shell scripts to update
the Nios application and/or the file system image:

1. Update Nios application (ex. the uCLinux kernel):

	run 'appl_update'

2. Update optional file system image (ex. RomFS image used by uCLinux):

	run 'fs_update'

The Nios application can be any programm code generated in relation
to the Nios application identifier -- the string "Nios" at offset
address 0x0c. To use the scripts like described above in a secure way
you have to check-up the next environment variables:

1. update_allowed

	- Update switch -- must be set to '1' (one) to allow any update
	- default is '0' (zero)

	  NOTE:	You should avoid to save this variable with non zero
		value to Flash. Otherwise it would be allow any
		update process at any time!

2. appl_entry_addr

	- Nios application area start address (usually in Flash)
	- this is the startup address for autoboot
	- each Nios application code we want to update will be copied
	  to this address
	- default is CONFIG_SYS_ADNPESC1_NIOS_APPL_ENTRY

3. appl_end_addr

	- Nios application area end address (usually in Flash)
	- will be used to unprotect/erase the Flash area while updating
	- default is CONFIG_SYS_ADNPESC1_NIOS_APPL_END

4. appl_ident_addr

	- address of the Nios application identification string
	- this is the address checked-up by autoboot
	- default is CONFIG_SYS_ADNPESC1_NIOS_APPL_IDENT

5. appl_ident_str

	- the Nios application identification string itself
	- default is CONFIG_SYS_ADNPESC1_NIOS_IDENTIFIER

6. appl_name

	- name of file we have to download/update
	- default is ADNPESC1/base32/linux.bin

7. fs_base_addr

	- optionally file system area start address (usually in Flash)
	- each file system we want to update will be copied to this address
	- default is CONFIG_SYS_ADNPESC1_FILESYSTEM_BASE

8. fs_end_addr

	- optionally file system area end address (usually in Flash)
	- will be used to unprotect/erase the Flash area while updating
	- default is CONFIG_SYS_ADNPESC1_FILESYSTEM_END

9. fs_name

	- name of file we have to download/update
	- default is ADNPESC1/base32/romfs.img