Update to rev 1.0 from andrew

1 files changed, 888 insertions, 0 deletions

diff --git a/sim/ppc/RUN b/sim/ppc/RUN
new file mode 100644
index 0000000..eaf4918
--- /dev/null
+++ b/sim/ppc/RUN
@@ -0,0 +1,888 @@
+
+		PSIM - model the PowerPC environment
+
+    Copyright (C) 1994-1996, Andrew Cagney <cagney@highland.com.au>.
+
+    ----------------------------------------------------------------------
+
+			Running PSIM
+
+	This file describes how to run the program PSIM.
+
+	o	Walk through a number of examples from the
+		pre-built tar archive psim-test.
+
+	o	Looks at the device tree used by PSIM.
+
+	o	Notes on building a programmer environment to
+		use with PSIM (BSD/UEA and BUG/OEA)
+
+
+    ----------------------------------------------------------------------
+
+
+RUNNING PSIM:
+
+
+The compressed tar archive psim-test available from:
+
+	ftp://ftp.ci.com.au/pub/psim/psim-test-1.0.tar.gz
+or	ftp://cambridge.cygnus.com/pub/psim/psim-test-1.0.tar.gz
+
+contains a number of pre-built programs for running under PSIM.  Each
+pre-built binary is built both big and little endian.  The suffixes
+.be/.le (executables) .bo/.lo (object files) and .ba/.la (libraries)
+are used.
+
+
+To run one of these programs, use:
+
+	powerpc-unknown-eabi-run <image>
+
+vis
+
+	powerpc-unknown-eabi-run psim-test/uea/envp
+
+(The program envp prints out your shells environment - very useful
+:-).  More generally psim is run as (this is part of the output from
+the -h option):
+
+        psim [ <psim-option> ... ] <image> [ <image-arg> ... ]
+
+Where
+
+        <image>       Name of the PowerPC program to run.
+                      This can either be a PowerPC binary or
+                      a text file containing a device tree
+                      specification.
+                      PSIM will attempt to determine from the
+                      specified <image> the intended emulation
+                      environment.
+                      If PSIM gets it wrong, the emulation
+                      environment can be specified using the
+                      `-e' option (described below).
+
+        <image-arg>   Argument to be passed to <image>
+                      These arguments will be passed to
+                      <image> (as standard C argv, argc)
+                      when <image> is started.
+
+        <psim-option> See below
+
+The following are valid <psim-option>s:
+
+        -m <model>    Specify the processor to model (604)
+                      Selects the processor to use when
+                      modeling execution units.  Includes:
+                      604, 603 and 603e
+
+        -e <os-emul>  specify an OS or platform to model
+                      Can be any of the following:
+                      bug - OEA + MOTO BUG ROM calls
+                      netbsd - UEA + NetBSD system calls
+                      chirp - OEA + a few OpenBoot calls
+
+        -i            Print instruction counting statistics
+
+        -I            Print execution unit statistics
+
+        -r <size>     Set RAM size in bytes (OEA environments)
+
+        -t [!]<trace> Enable (disable) <trace> option
+
+        -o <spec>     add device <spec> to the device tree
+
+        -h -? -H      give more detailed usage
+
+
+The `-H' option gives a long usage output.  This includes a complete
+list of all the pre-configured devices.
+
+
+    ----------------------------------------------------------------------
+
+
+RUNNING GDB:
+
+
+If you built PSIM with gdb then the following is a quick start
+tutorial.
+
+At present GDB, if configured big-endian (say) unlike PSIM, does not
+support the debugging of little endian binaries.  If you find that
+your program won't run at all, make certain that GDB and your
+program's endianness match.
+
+
+The most important thing is that before you can run the simulator you
+must enable it.  For the simulator, gdb is started like any program:
+
+	$ powerpc-unknown-eabi-gdb psim-test/uea/envp.be
+
+Next the simulator is enabled.  The command `target sim' accepts the
+same options as can be specified on the PSIM command line.
+
+	(gdb) target sim
+
+To trace the communication between psim and gdb specify `target sim -t
+gdb'.  Once enabled, the binary needs to be loaded, any breakpoints of
+interest set, and the program run:
+
+	(gdb) load
+	(gdb) break main
+	(gdb) run
+	.
+	.
+	.
+
+In addition, if you are wanting to run a program described by a device
+tree you can `attach' to the simulation using (I assume that you have
+applied the attach patch):
+
+	$ cd psim-test/tree
+	$ powerpc-unknown-eabi-gdb
+	(gdb) target sim
+	(gdb) attach device-tree
+	(gdb) run
+
+Here GDB takes the programs initial state from the attached
+device-tree instead of forcing initialisation.
+
+
+    ----------------------------------------------------------------------
+
+
+PROFILING:
+
+
+PSIM includes a number of performance monitoring (profiling)
+facilities:
+
+	o	instruction frequency counting
+
+	o	execution unit modeling (records
+		effective usage of units).
+
+	o	instruction cache performance
+
+As discussed in the file INSTALL, each can be configured to individual
+requirements.
+
+
+	-i	Enable instruction counting.
+
+		The frequency of all instructions is tabulated.  In
+		addition (f configured) the hit/miss rate of the
+		instruction cache is output.
+
+
+	-I	Enable execution unit analysis.
+
+		In addition to counting basic instructions also model
+		the performance of the processors execution units
+
+
+	-m <processor>
+
+		Select the processor to be modelled.
+
+		For execution unit analysis specify the processor that
+		is to be analysed.  By default the 604 is modelled
+		however, support for other processors such as the
+		603 and 603e is included.
+
+The output from a performance run (on a P90) for the program
+psim-test/profile/bench is below.  In this run psim was fairly
+agressively configured (see the file INSTALL for compile time
+configuration).
+
+	CPU #1 executed     41,994 AND instructions.
+	CPU #1 executed    519,785 AND Immediate instructions.
+	CPU #1 executed    680,058 Add instructions.
+	CPU #1 executed     41,994 Add Extended instructions.
+	CPU #1 executed    921,916 Add Immediate instructions.
+	CPU #1 executed    221,199 Add Immediate Carrying instructions.
+	CPU #1 executed    943,823 Add Immediate Shifted instructions.
+	CPU #1 executed    471,909 Add to Zero Extended instructions.
+	CPU #1 executed    571,915 Branch instructions.
+	CPU #1 executed  1,992,403 Branch Conditional instructions.
+	CPU #1 executed    571,910 Branch Conditional to Link Register instructions.
+	CPU #1 executed    320,431 Compare instructions.
+	CPU #1 executed    471,911 Compare Immediate instructions.
+	CPU #1 executed    145,867 Compare Logical instructions.
+	CPU #1 executed    442,414 Compare Logical Immediate instructions.
+	CPU #1 executed          1 Condition Register XOR instruction.
+	CPU #1 executed    103,873 Divide Word instructions.
+	CPU #1 executed    104,275 Divide Word Unsigned instructions.
+	CPU #1 executed    132,510 Extend Sign Byte instructions.
+	CPU #1 executed    178,895 Extend Sign Half Word instructions.
+	CPU #1 executed    871,920 Load Word and Zero instructions.
+	CPU #1 executed     41,994 Move From Condition Register instructions.
+	CPU #1 executed    100,005 Move from Special Purpose Register instructions.
+	CPU #1 executed    100,002 Move to Special Purpose Register instructions.
+	CPU #1 executed    804,619 Multiply Low Word instructions.
+	CPU #1 executed    421,201 OR instructions.
+	CPU #1 executed    471,910 OR Immediate instructions.
+	CPU #1 executed  1,292,020 Rotate Left Word Immediate then AND with Mask instructions.
+	CPU #1 executed    663,613 Shift Left Word instructions.
+	CPU #1 executed  1,151,564 Shift Right Algebraic Word Immediate instructions.
+	CPU #1 executed    871,922 Store Word instructions.
+	CPU #1 executed    100,004 Store Word with Update instructions.
+	CPU #1 executed    887,804 Subtract From instructions.
+	CPU #1 executed     83,988 Subtract From Immediate Carrying instructions.
+	CPU #1 executed          1 System Call instruction.
+	CPU #1 executed    207,746 XOR instructions.
+	
+	CPU #1 executed 23,740,856 cycles.
+	CPU #1 executed 10,242,780 stalls waiting for data.
+	CPU #1 executed          1 stall waiting for a function unit.
+	CPU #1 executed          1 stall waiting for serialization.
+	CPU #1 executed  1,757,900 times a write-back slot was unavailable.
+	CPU #1 executed  1,088,135 branches.
+	CPU #1 executed  2,048,093 conditional branches fell through.
+	CPU #1 executed  1,088,135 successful branch predictions.
+	CPU #1 executed    904,268 unsuccessful branch predictions.
+	CPU #1 executed    742,557 branch if the condition is FALSE conditional branches.
+	CPU #1 executed  1,249,846 branch if the condition is TRUE conditional branches.
+	CPU #1 executed    571,910 branch always conditional branches.
+	CPU #1 executed  9,493,653 1st single cycle integer functional unit instructions.
+	CPU #1 executed  1,220,900 2nd single cycle integer functional unit instructions.
+	CPU #1 executed  1,254,768 multiple cycle integer functional unit instructions.
+	CPU #1 executed  1,843,846 load/store functional unit instructions.
+	CPU #1 executed  3,136,229 branch functional unit instructions.
+	CPU #1 executed 16,949,396 instructions that were accounted for in timing info.
+	CPU #1 executed    871,920 data reads.
+	CPU #1 executed    971,926 data writes.
+	CPU #1 executed        221 icache misses.
+	CPU #1 executed 16,949,396 instructions in total.
+	
+	Simulator speed was 250,731 instructions/second
+
+
+    ----------------------------------------------------------------------
+
+
+PSIM CONFIGURATION - THE DEVICE TREE
+
+
+Internally PSIM's configuration is controlled by a tree data
+structure.  This structure, created at run-time, intentionally
+resembles the device tree used by OpenBoot firmware to describe a
+machines hardware configuration.
+
+PSIM can either create its device tree using a builtin emulation or
+from one read in from a file.
+
+During startup, the device tree is created using the following steps:
+
+	o	Initial empty tree is created
+
+	o	Any tree entry options specified on the
+		command line are merged in (the -o <entry>
+		option is used).
+
+		It should be pointed out that most of the
+		command line options (eg -r, -e, -m, -t
+		are all just short hand for corresponding
+		-o options).
+
+	o	If the specified program is a device tree spec, that
+		is loaded.
+
+		If the specified program is a text file it is assumed
+		that that file contains a further specification of the
+		simulators device tree.  That tree is loaded and
+		merged with the current tree options.
+
+	o	The selected emulation fills out any remaining details.
+
+		By this stage the emulation environment that the program
+		needs will either be specified in the device tree
+		(through the -e option) or determined from the
+		characteristics of the binary.
+
+		The selected emulation will then fill out any missing
+		nodes in the device tree.
+
+Most importantly earlier additions to the tree are not overridden by
+later additions.  Thus, command line options override information
+found in the program file and both override any emulation entries.
+
+The following is a summary of the most useful runtime configuration
+options:
+
+	-e <os-emul>
+	-o '/openprom/options/os-emul <os-emul>'
+
+		Run program using the <emulation> run-time
+		environment.
+
+	-r <ram-size>
+	-o '/openprom/options/oea-memory-size <ram-size>'
+
+		Set the size of the first bank of memory
+		(RAM from address 0 up).
+
+	-t print-device-tree
+	-o '/openprom/trace/print-device-tree 1'
+
+	-t dump-device-tree
+	-o '/openprom/trace/dump-device-tree 1'
+
+		Print out the device tree once it has been fully
+		populated. For dump-device-tree, exit simulator after
+		dumping the tree.
+
+		PSIM is able to reload the dumped device tree.
+
+		The format of the dumped tree is under development.
+
+	-o '/openprom/options/smp <N>'
+
+		Enable <N> processors for the simulation run.
+		See the directory psim-test/oea for an example.
+
+	-o '/openprom/options/alignment <N>'
+
+		Where <N> is 1 - nonstrict or 2 - strict.
+		Specify if the missaligned access are allowed
+		(non-strict) or result in an alignment exception
+		(strict).
+
+Devices (if included in the file device_table.c) can also be specified
+in a similar way.  For instance, to add a second serial port, a
+command like:
+
+	-o '/iobus@0x400000/console@0x000010'
+
+would create a `console' device at offset 0x10 within the `iobus' at
+memory address 0x400000.
+
+For more detailed information on device specifiers see the notes on
+the function dump_device_tree in the file device.c (found in the
+source code).
+
+
+    ----------------------------------------------------------------------
+
+
+BUILDING A BUG/OEA DEVELOPMENT ENVIRONMENT
+
+
+Background:
+
+
+Included in many PowerPC systems is Motorola's BUG monitor.  This
+monitor includes, for client programs, a set of services that allow
+that program to interact with hardware devices such as the console using
+a simple system call interface.
+
+PSIM is able to emulate a number of the services (including the
+console IO calls).  If additional services are needed they can easily
+be added.
+
+Cygnus support's newlib library includes includes an interface to the
+MOTO BUG services.  The notes below discuss how I both built and run
+programs compiled using this library on PSIM.
+
+The only confusing part about building a development environment based
+around newlib/binutils/gcc is a chicken/egg problem with include
+files:
+		
+	For GCC to build, a fairly complete set of include
+	files must be installed but newlib won't install its
+	include files until it has been built with gcc ...
+
+I get around this by installing the problematic include files by hand.
+
+
+Preparation:
+
+
+The following files are needed:
+
+From your favorite FTP site, the sources to gas/ld and gcc - mine
+happens to be archie.au :
+
+	ftp://archie.au/gnu/binutils-2.6.tar.gz
+	ftp://archie.au/gnu/gcc-2.6.2.tar.gz
+
+From ftp://ftp.cygnus.com/pub/newlib the source code to a library:
+
+	ftp://ftp.cygnus.com/pub/newlib/newlib-1.7.0.tar.gz
+
+From ftp://ftp.ci.com.au/pub/psim some minor patches and updates to
+the above library:
+
+	ftp://ftp.ci.com.au/pub/psim/newlib-1.7.0+float+ppc-asm.tar.gz
+	ftp://ftp.ci.com.au/pub/psim/newlib-1.7.0+ppc-fix.diff.gz
+	ftp://ftp.ci.com.au/pub/psim/binutils-2.6+note.diff.gz
+
+In addition you'll need to decide where you will be installing the
+development environment.  You will notice that in the below I install
+things well away /usr/local instead installing everything under its
+own directory in /applications.
+
+
+Method:
+
+
+These notes are based on an installation performed on a Sun-OS-4/SPARC
+host.  For other hosts and other configurations, the below should be
+considered as a guideline only.
+
+
+ 	o	Sanity check
+
+		$ cd .../scratch	# your scratch directory
+		$ ls -1
+		binutils-2.6.tar.gz
+		binutils-2.6+note.diff.gz
+		gcc-2.7.2,tar.gz
+		newlib-1.7.0+float+ppc-asm.tar.gz
+		newlib-1.7.0+ppc-fix.diff.gz
+		newlib-1.7.0.tar.gz
+
+
+	o	Unpack/build/install binutils
+
+		This is done first so that there is a gas/ld ready
+		for the building of GCC and NEWLIB.
+
+		$ cd .../scratch
+		$ gunzip < binutils-2.6.tar.gz | tar xf -
+		$ cd binutils-2.6
+
+		Optionally apply the note patch
+
+		$ gunzip ../binutils-2.6+note.diff.gz | patch
+
+		Then continue with the build
+
+		$ ./configure --target=powerpc-unknown-eabi \
+                              --prefix=/applications/psim
+		$ make
+		$ make install
+		$ cd ..
+		$ rm -rf binutils-2.6
+
+		This also creates much of the installation directory
+		tree.
+
+
+	o	Unpack newlib, install the include files so that they
+		are ready for GCC's build.
+
+		$ cd .../scratch
+		$ gunzip < newlib-1.7.0.tar.gz | tar xf -
+
+		New lib-1.7.0 had a few minor bugs (fixed in current):
+		the header files float.h and ppc-asm.h were missing;
+		the configure and Makefile's for the rs6000 (ppc) directory
+		contained typos:
+
+		$ cd .../scratch
+		$ cd newlib-1.7.0
+		$ gunzip < ../newlib-1.7.0+float+ppc-asm.tar.gz | tar xvf -
+		$ gunzip < ../newlib-1.7.0+ppc-fix.diff.gz | patch -p1
+		
+		Finally copy the include files to where GCC will see them:
+
+		$ cd .../scratch
+		$ cd newlib-1.7.0/newlib/libc
+		$ tar cf - include | \
+                   ( cd /applications/psim/powerpc-unknown-eabi && tar xf - )
+
+
+	o	Unpack/build gcc
+
+		$ cd .../scratch
+		$ gunzip < gcc-2.7.2,tar.gz | tar xf -
+		$ cd gcc-2.7.2
+		$ ./configure --target=powerpc-unknown-eabi \
+                              --prefix=/applications/psim
+		$ make
+		$ make install
+		$ cd ..
+		$ rm -rf gcc-2.7.2
+
+		Gcc likes to install its own dummy version of float that
+		just returns an error.
+
+		$ more /applications/psim/lib/gcc-lib/powerpc-unknown-eabi/2.7.2/include/float.h
+		$ rm /applications/psim/lib/gcc-lib/powerpc-unknown-eabi/2.7.2/include/float.h
+
+
+	o	Finish building/installing newlib
+
+		$ cd .../scratch
+		$ cd newlib-1.7.0
+		$ ./configure --target=powerpc-unknown-eabi \
+                              --prefix=/applications/psim
+
+		Your path will need to include the recently installed
+		gas/gcc when building.  Either add it to your path or
+		use:
+
+		$ PATH=/applications/psim/bin:$PATH make
+		$ PATH=/applications/psim/bin:$PATH make install
+
+
+	o	Finally, test out the build
+
+		$ cat hello.c
+		main()
+		{
+		  printf("hello world\n");
+		}
+
+		The binary is linked with an entry point less than 0x100000
+		(1mb) so that psim will recognize the binary as needing
+		the BUG/OEA instead of the BSD/UEA runtime environment.
+
+		$ powerpc-unknown-eabi-gcc -v -o hello \
+                    -Wl,-Ttext,0x4000,-Tdata,0x10000 \
+                    /applications/psim/powerpc-unknown-eabi/lib/mvme-crt0.o \
+                    hello.c \
+                    -lc -lmvme
+		$ powerpc-unknown-eabi-objdump -h hello
+		$ powerpc-unknown-eabi-run hello
+
+		It is also possible to force psim to use a specific
+		run-time environment using the -e option vis:
+
+		$ powerpc-unknown-eabi-run -e bug hello
+
+
+
+
+    ----------------------------------------------------------------------
+
+
+BUILDING A BSD/UEA DEVELOPMENT ENVIRONMENT
+
+
+Background:
+
+
+For a UEA to be useful it needs a supporting run-time environment.
+PSIM implements a runtime environment based on the NetBSD system call
+interface.
+
+More than any thing, this user level emulation was the first
+implemented because I happened to have the NetBSD source code lying
+lying around.
+
+
+Preparation:
+
+
+This requires the NetBSD-1.1 source tree online.  It can either be
+obtained vi ftp:
+
+	try http://www.netbsd.org  or  ftp://ftp.netbsd.org
+
+Alternatively obtain one of the NetBSD cdrom's.  Patches to this source
+tree that fill out much of the PowerPC code are available in:
+
+	ftp://ftp.ci.com.au/pub/clayton
+
+Fetch everything in that directory - diffs, tar archives and scripts.
+In addition a patch to binutils is in:
+
+	ftp://ftp.ci.com.au/pub/psim/binutils-2.6+note.diff.gz
+
+Finally you'll require a compiler and assembler/linker:
+
+	gcc-2.7.2.tar.gz
+	binutils-2.6.tar.gz
+
+
+
+
+Method:
+
+
+These notes are based on an installation performed on a Solaris2/x86
+host.  For other hosts and other configurations, the below should be
+considered as a guideline only.
+
+
+	o	Sanity check
+
+		I assume that you have already obtained the NetBSD-1.1 source
+		code and unpacked it into the directory bsd-src.  While the
+		full NetBSD source tree may not be needed, things are easier
+		if it is all online.
+
+		$ cd .../scratch
+		$ ls -1
+		binutils-2.6.tar.gz
+		binutils-2.6.tar.gz
+		clayton-include-960203.diff.gz
+		clayton-lib-960203.diff.gz
+		clayton-lib-960203.tar.gz
+		clayton-sys-960203.diff.gz
+		clayton-sys-960203.tar.gz
+		clayton-utils-960203.tar.gz
+		clayton.chown.sh
+		clayton.install.sh
+		clayton.lorder.sh
+		clayton.make.sh
+		clayton.usr.bin.make.diff
+		gcc-2.7.2.tar.gz
+		gcc-2.7.2+sys-types.diff.gz
+
+
+	o	Unpack the bsd source code (if you haven't already)
+
+		$ cd .../scratch
+		$ mkdir bsd-src
+		$ cd bsd-src
+		$ for d in /cdrom/bsdisc_12_95_disc2/NetBSD-1.1/source/*11
+                  do
+                    echo $d
+                    cat $d/*.?? | gunzip | tar xf -
+                  done
+
+		Flatten the directory structure a little.
+
+		$ mv usr/src/* .
+		$ rmdir usr/src usr
+		$ cd ..
+
+
+	o	Unpack/build/install binutils
+
+		$ cd .../scratch
+		$ gunzip < binutils-2.6.tar.gz | tar xf -
+		$ cd binutils-2.6
+
+		Optionally apply the note patch
+
+		$ gunzip ../binutils-2.6+note.diff.gz | patch
+
+		Then continue with the build
+
+		$ ./configure --target=powerpc-unknown-eabi \
+                              --prefix=/applications/psim
+		$ make
+		$ make install
+		$ cd ..
+		$ rm -rf binutils-2.6
+
+		This has the intended side effect of partially populating
+		the psim directory tree which makes follow on steps easier.
+
+
+	o	Fill out the install directory with a few additions (if
+		install -d works, this can be simplified).
+
+		$ mkdir \
+                    /applications/psim/bsd-root \
+                    /applications/psim/bsd-root/usr \
+                    /applications/psim/bsd-root/usr/share \
+                    /applications/psim/bsd-root/usr/share/doc \
+                    /applications/psim/bsd-root/usr/share/doc/psd \
+                    /applications/psim/bsd-root/usr/share/doc/psd/19.curses \
+                    /applications/psim/bsd-root/usr/include \
+                    /applications/psim/bsd-root/usr/lib \
+
+
+	o	Make the bsd and gnu include directories point to the same
+		location.
+
+		GCC expects include files to be in one location while the
+		bsd install expects them in a second.  The link is in
+		the direction below because bsd's install also insists on
+		a directory (not a link) for its install destination.
+
+		$ ln -s ../bsd-root/usr/include \
+                    /applications/psim/powerpc-unknown-eabi/include
+
+
+
+	o	Build/install Berkeley make
+
+		In building Berkeley make from the NetBSD-1.1 source tree
+		a number of problems may be encountered.
+
+		These problems have been fixed in NetBSD-current (after
+		4/2/96 (ie start Feb)) you should probably obtain that
+		version of make.  Alternatively, you can try following the
+		notes below that got make working on a Solaris-2.5/x86
+		host.
+
+		$ cd .../scratch
+		$ cd bsd-src/usr.bin/make
+		$ pwd
+		.../scratch/bsd-src/usr.bin/make
+
+		Copy/stub some additional include files that your host may not
+		have.
+
+		$ cp ../../include/ranlib.h ranlib.h
+		$ mkdir sys
+		$ cp ../../sys/sys/cdefs.h sys/cdefs.h
+		$ mkdir machine
+		$ touch machine/cdefs.h
+
+		Edit/fix some of the BSDisms. The patch file indicated
+		contains fixes I found when compiling on my host, your
+		host will probably differ.
+
+		$ gunzip < ../../../clayton.usr.bin.make.diff.gz | patch
+
+		Build it with some extra flags (again your flags will differ):
+
+		$ make -f Makefile.boot CC='gcc -g -DPOSIX'
+
+		With bmake built, install it into the target specific bin
+		directory:
+
+		$ cp bmake /applications/psim/powerpc-unknown-eabi/bin/make
+		$ cd ../../.. 
+
+
+	o	Patch/install Berkeley make's include (mk) files.
+
+		$ cd .../share
+		$ cd bsd-src/share
+		$ tar cf - mk | ( cd /applications/psim/bsd-root/usr/share \
+                     && tar xf - )
+		$ cd ../..
+
+
+	o	Set up a number of wrapper scripts for bmake so that it works.
+
+		In addition to needing BSD make the build process assumes
+		a number of BSD specific commands.  To get around this
+		several wrapper scripts are available.
+
+		powerpc-unknown-eabi-make (clayton.make)
+
+			Front end to Berkeley make setting it up for a
+			cross compilation
+
+			/applications/psim/bin/powerpc-unknown-eabi-make
+
+		chown (clayton.chown)
+
+			Wrapper that does not do any thing.
+			Avoids the need to be root when installing.
+
+			/applications/psim/powerpc-unknown-eabi/bin
+
+		install (clayton.install)
+
+			Wrapper to strip away a number of bsd specific install
+			arguments.
+
+			/applications/psim/powerpc-unknown-eabi/bin/install
+
+		lorder (clayton.lorder)
+
+			Tweaked lorder script that will use nm etc from
+			binutils.
+
+			/applications/psim/powerpc-unknown-eabi/bin/lorder
+
+
+	o	Apply the remaining patches for the BSD source tree
+
+		$ cd .../scratch
+		$ cd bsd-src
+		
+		Diffs are applied using something like:
+
+		$ gunzip < ../clayton-include-960203.diff.gz | more
+		...
+
+		The patch to sys/dev/pci/ncr.c.rej might fail.
+
+		The tar archives have a different problem, you need
+		to remove the `src' prefix.  I used
+
+		$ ln -s . src
+		$ gunzip < ../clayton-lib-960203.tar.gz | tar xtf -
+		...
+
+		So that src/xxx unpacked into ./xxx
+
+
+		$ cd ..
+
+
+
+	o	Install the include files
+
+		$ cd .../scratch
+		$ cd bsd-src/include
+		$ powerpc-unknown-eabi-make install
+		$ cd ../..
+		
+
+	o	Install a few other include files.
+
+		As with building libnew, the bsd build process has
+		several include file problems.
+
+		$ cd .../scratch
+		$ cd bsd-src
+		$ cp gnu/lib/libg++/g++-include/values.h \
+                    /applications/psim/powerpc-unknown-eabi/include
+		$ cp lib/libcurses/curses.h \
+                    /applications/psim/powerpc-unknown-eabi/include
+		
+		$ cd ..
+
+
+
+	o	Build/install gcc
+
+		$ cd .../scratch
+		$ gunzip < gcc-2.7.2,tar.gz | tar xf -
+		$ cd gcc-2.7.2
+
+		GCC and BSD (for PowerPC) have a conflicting type
+		declaration.  The patch below gets around this
+		problem:
+
+		$ gunzip < ../gcc-2.7.2+sys-types.diff.gz | patch
+
+		Other than that, assuming the include files installed
+		okay, the rest should be fine ....
+
+		$ ./configure --target=powerpc-unknown-eabi \
+                              --prefix=/applications/psim
+		$ make CC=gcc
+		$ make CC=gcc install
+		$ cd ..
+		$ rm -rf gcc-2.7.2
+
+
+	o	Build/install the Berkeley library:
+
+		$ cd .../scratch
+		$ cd bsd-src/lib
+		$ powerpc-unknown-eabi-make
+		$ powerpc-unknown-eabi-make install
+		$ cd ../..
+
+		If you encounter problems try the following: an include
+		file not yet installed; a directory not yet created;
+		running the hosts version of a program instead of a
+		bsd version.
+
+	o	Build/run a simple BSD program
+
+		$ cd .../scratch
+		$ cd bsd-src/usr.bin/printenv
+		$ powerpc-unknown-eabi-make
+		$ powerpc-unknown-eabi-run printenv
+		.
+		.
+		.
+
+
+    ----------------------------------------------------------------------