BRECIS uClinux Release 2.5 Beta Two -- 30 May 2003

------------------------------------------------------------------------------
ATTENTION: The location of the "compiler tools" have changed.
ATTENTION: The path must change if you use the tools without using the
ATTENTION: compilescript Makefile.
ATTENTION: 
ATTENTION: The PATH variable must still be explicitly set to compile
ATTENTION: pmon and bbload.  The path variable must be set to point to
ATTENTION: uClinux/brecis/tools/mipsisa32-brecis-uclinux/bin/
------------------------------------------------------------------------------


Introduction
============

This file contains instructions for building uClinux,
	loading uClinux (from ethernet and from flash),
	building and loading demo applications,
	information on pre-built accounts,
	notes on the built-in webserver,
	using kgdb,
	pointers to more information on Kernel Loadable Modules,
	pointers to more information on FreeSWAN,
	pointers to more information on Building Custom Kernels.
	pointers to more information on Security Device Driver.



This is the recommended order for creating and modifying the uClinux
kernel for the BRECIS MSP Processor Family.

This write-up assumes that: 
	the cd is mounted as /mnt/cdrom,
	the user is using the bash shell,
	the host developer tools have been installed,
	any example commands are being executed in the appropriate
		directory, 
	


uClinux Build Instructions
==========================

1)	Ensure that the directory /tftpboot/${USER}/ exists and is
	writeable by ${USER}

	NOTE: For the initial build, copy the /mnt/cdrom/uClinux
	directory to your hard disk. 
		  cp -a /mnt/cdrom/uClinux uClinux

2)	Do a "make LINUXALL" (or execute script LINUXALL) in the directory
	uClinux/brecis/compilescripts.
   
	NOTES: The output of a build has been captured for comparison
	in uClinux/brecis/compilescripts/xxx.out

		   This script will require the root password a number of
	times to execute commands for building the file system image
	for the EVM board.
	
		    make LINUXALL does a make clean followed by a build of the
	linux system as defined by the current defined configuration.
	The defined configuration can be changed (see the FAQ).  
	
	WARNING:  If the defined configuration is changed, then it is
	important that the linux system be built from scratch.  Use the
	command "make distclean".  This command removes ALL objects and
	other configuation information.
		    

3)	The output of a successful compile will be the files:
	 /tftpboot/${USER}/image.bin
	 /tftpboot/${USER}/image.flash

	image.bin is the uClinux kernel + file system.

	image.flash is a gunzip program + a gzip of image.bin produced above
	The gunzip program will extract the uClinux kernel + file system
	and will start the uClinux kernel executing when called.



Loading uClinux over Ethernet
=============================

0)	The script uClinux/documentation/pmon-script contains the setup
	parameters used to boot linux.  This script may be customized for
	your product.  Items that might be customized include ip-addresses,
	ip-net masks, ip-gateways, ethernet speed and duplex defaults, etc.

	NOTE:  	To use a ethernet switch you MUST configure the pmon-script.
		See the script for the more information.

1)	Ensure that the script, uClinux/documentation/pmon-script, has
	been written to the BRECIS MSP EVM board flash location, bfc70000

	 NOTE: See the file, pmon/README-FIRST, for instructions on
	 how to customize this script to the desired network
	 environment and for instructions on loading pmon scripts. 

2)  Modify the following script as needed (especially the BRECIS MSP
	EVM IP address) and then execute the modified script to load the 
	kernel in the BRECIS MSP EVM board:
	uClinux/documentation/uClinuxload 

	  NOTE: the address in the script, pmon-script, 80100000, is
	  dependent on the kernel_entry address for the uClinux kernel.

	  The IP address in the pmon-script for the ipaddr variable
	  must be the same as the IP address in the uClinuxload script
	  for the EVMIPADDR variable. 

          The uClinux kernel presently only uses some of the
	  environment variables from pmon.  The uClinux kernel ignores
	  the IP addresses set in pmon.  The uClinux kernel DOES use
	  the modetty0 variable set in pmon.

3)	The uClinux kernel should boot to a login prompt. See the Account
	information below for initial login information.

4)	Set up and test an alias for eth0 to add desired IP address to eth0
	using the following commands:
		/sbin/ifconfig eth0:0 <ip-address> netmask <netmask> 
		/sbin/ifconfig 
		/bin/ping -c 4 -n <ip-address-of-PC>




Loading uClinux from Built-in Flash
===================================

	One would use bbload, a bbload script, and the image.flash binary.

	If one has an EVM board with two flash chips,
	one flash chip running pmon, and one wants to
	place bbload + image.flash in the other flash
	chip, please do as follows under pmon:

1)	Use pmon to copy the bbload image to the "other" flash chip 
	whose address is 0xbe000000.  The bbload image is bbload/bbload.

2)	Use pmon to copy the bbload script to the "other" flash chip 
	whose address is 0xbe010000.
	An example bbload script is uClinux/documentation/bbload-script

3)	Optional: build a manufacturing record using the Unix program, manufinfo.  
	Please see the manufinfo directory on the CD.

	Use pmon to copy the manufinfo record produced
	by manufinfo to the FLASH_CONFIG_ADDRESS in the
	"other" flash chip which is 0xbe000020.

	NOTE:	when pmon writes flash, pmon will save and re-write any data 
		to flash that was not to be changed.  
		I.e., pmon will try to preserve those bytes within a flash
		sector that was not to be changed.  The manufacturing info 
		record is in the SAME flash sector as bbload.  

		If a different flash writing program is used,
		please be certain it also preserves bytes
		in a flash sector that are not to be changed
		or please merge the manufacturing info record
		into the bbload image before writing the bbload image.

4)	Use pmon to copy the uClinux binary, image.flash, 
	to the "other" flash chip whose address is 0xbe020000.  

5)	Switch the chip selects on the EVM board so the "other" flash chip 
	is now chip select 0.

6)	Power cycle or push the reboot button on the
	EVM board.  bbload should start executing.

	Please see pmon/README-FIRST for instructions
	for getting a binary into the EVM board and
	writing the binary to flash.

	Please see bbload/README for an explanation of commands in 
	bbload-script.

	Pleasse see manufinfo/README for an explanation of 
	the manufacturing info record.




Building and Loading the DEMO Applications
==========================================

There are two demo programs. A customized "Hello World" program, found
in uClinux/brecis/demo and a text adventure program, found in
uClinux/brecis/adventure. Both programs are built and loaded in much
the same way. The following instructions build the program "demo." To
build, load and run "adventure," substitute all references of the file
name "demo" to the file name "adventure."

1)	To build the customized "Hello World" application, go to the
	uClinux/brecis/demo directory and execute make:
	cd uClinux/brecis/demo
	make
2)	To load this demo application using ftp:

	a) Ensure the BRECIS MSP EVM board is running uClinux
	b) Ensure that the IP address has been properly set using the
	   commands: 
		/sbin/ifconfig
		/bin/ping -c 4 -n <ip-address-of-PC>
	c) Set up a directory on the BRECIS MSP EVM board where the demo
	   application will be placed:
		cd /var
		mkdir demo
		cd demo

	   NOTE: Directories and files can only be dynamically
	   created under the /var directory. The var directory is
	   a "ramdisk" Instructions on reconfiguring the size of
	   the ramdisk are provided in the FAQ document.

	d) Ensure that a ftp server is running on the build machine.
	e) Run the ftp client on the BRECIS MSP EVM board to get the demo
	   application:
		ftp <ip-address-of-PC>
		<login>
		ftp> cd <build-directory>/uClinux/brecis/demo
		ftp> get demo
		ftp> bye

	f) Review the file permissions and correct if needed:
		ls -l 
		chmod 755 demo
		ls -l

	g) Run the application
		./demo
			



Account and Password Information
================================

The uClinux BRECIS MSP EVM board has two ways of having passwords selected.
For small non-changing passwords for ftpd and login, enable the userland
configuration option CONFIG_USE_TEXT_PASSWORDS.  For a normal /etc/passwd
file, do not choose this option.

The password for the root account on the uClinux BRECIS MSP EVM board
is "brecis". The default shell for root is sh. The man page for this
version of sh can be found on: /mnt/cdrom/uClinux/uC-src/sh/sh.1

The name/password if you ftp into the uClinux BRECIS MSP EVM board is
"maintainer"/"blip" for CONFIG_USE_TEXT_PASSWORDS, or "maintain"/"blip"
if using the /etc/passwd file.  Can only have eight (8) characters in
a username in /etc/passwd.

If the /etc/passwd file is selected, there are two additional accounts.
"nobody" has an untypeable password, and "demo"/"demo".



KGDB Usage 
==========

The KGDB stub is built in the uClinux kernel by default. To use the
KGDB stub, execute the following commands:

	1) Change the pmon-script running in the BRECIS MSP EVM board to
	   start uClinux with the gdb stub by changing the "g ..." pmon
	   command to include the "kgdb=scc0" or "kgdb=console" string.

	   Please see uClinux/documentation/pmon-script
	   as an example.  

	   "kgdb=console" will cause kgdb to use the console UART.  
	   "kgdb=scc0" will cause kgdb to use scc0.

	   The line speed for both interfaces is 57600.

	   NOTE: The console interface is stable. However, the scc0 
	   interface has not been thoroughly tested.

	   The BRECIS MSP EVM board requires a standard Cisco-style
	   self-configuring cable to configure the SCC0 port as a
	   RS-232 port. The port has been tested when configured as
	   DTE. These cables are available from several vendors.  The
	   Cisco assembly number for a RS-232 DTE cable is
	   72-0793-01. The Cisco assembly number for a RS-232 DCE
	   cable is 72-0794.01. 

	2) The gdb program to use on the host computer is mips-gdb.
	   This program is built as part of the build of open-tools.
	   The binary is located in the /opt/BRECIS/msp/bin directory.

	   To run mips-gdb, execute the following command:
		  mips-gdb -b 57600

	   Before attempting to use mips-gdb, please insure the physical
	   serial line setup between the BRECIS MSP EVM board and the host
	   computer is working by doing the following:

	   a) Start a minicom session running on the serial port
	      that is to be used by mips-gdb.

	   NOTE: use a serial speed of 57600.

	   b) Start the BRECIS MSP EVM board, specifying the appropriate
		  "kgdb=xxx" string on the "g ..." pmon command.

	   c) A '+' should print on the minicom session.





Kernel Loadable Modules
=======================

Documentation for kernel loadable modules can be found in the
following file: /mnt/cdrom/uClinux/documentation/KernelModules

This file contains information on 
	 different methods of incorporating/compiling KLM's, 
	 an example (seckerntest), 
	 current limitations, and 
	 some information on tainting warnings.




Building Custome Kernels
========================

Documentation for building Custom kernels can be found in the following 
files:
/mnt/cdrom/uClinux/documentation/multiple_setups_and_kernel_images
/mnt/cdrom/uClinux/brecis/compilescripts/Makefile



FreeSWAN 
========

Documentation for FreeSWAN can be found in the following directory:
/mnt/cdrom/uClinux/documentation/FreeSWAN

This directory contains:
	Notes on the FreeSWAN implementation (and status),
	build instructions, and
	sample configuration files.




RIP, OSPF, and BGP
==================

RIP OSPF and BGP are from www.zebra.org.  The source code can be found
in the /mnt/cdrom/uClinux/uC-src/real/zebra-* directory.  Documentation
from www.zebra.org can be found in the 
/mnt/cdrom/uClinux/uC-src/real/zebra-*/doc directory.
Please see the FAQ file in this directory for any BRECIS specific items.




Webserver Notes
===============

A small webserver is enabled by default. It is enabled in
/etc/inetd.conf The document root is /htdocs.  This directory is in
the rom image, so changing pages involves re-making this image or
recompiling the code to point to the ramdisk. The source can be found
in /mnt/cdrom/uClinux/uC-src/httpd.




BRECIS Security Device Driver
=============================

Documentation for the included uClinux Security Device Driver User
level API can be found in the following files. 

/mnt/cdrom/uClinux/brecis/secutil/MSP_SEC_DEV_API_documentation.txt
/mnt/cdrom/uClinux/brecis/secutil/MSP_SEC_V2_API_documentation.txt

The second file describes the new API to be used on chips with the
newer security engine, such as MSP2100 and MSP2010.
