binutils-gdb/sim/ppc

			PSIM

Copyright (C) 1994-1995, Andrew Cagney <cagney@highland.com.au>

This directory contains the program PSIM that models the PowerPC (tm -
IBM) architecture.  It can be run either standalone (psim or run) or
used as part of GDB.


KNOWN FEATURES:


SMP: It is possible to configure this simulator so that it implements
a restricted model of a Symetric Multi-Processor architecture.  It is
important to note that the SMP model has limitations.  In particular,
the PowerPC's load word and reserve (etc) instructions do not model
the behavour defined in the Architecture manual.  People intending to
use this feature should read the code implementing those instructions.

ENDIAN SUPORT: Pure big, pure little and PowerPC little endian (xor
endian) models are suported.

UIEA, VEA and OEA: The PowerPC architecture defines three levels of
the PowerPC architecture.  This simulator, to a reasonable degree, is
capable of modeling all three.  That is the User Instruction Set
Architecture, the Virtual Environment Architecture and finally the
Operating Environment Architecture.

HARDWARE DEVICE TREE: In the OEA, the model of the target machines
hardware is built from a tree of devices (bit like Open Boot).
Included in this is the ability to model bus hierachies and
runtime-configurable devices (eg PCI).

OS EMULATION: Suport for os/firmware emulations (system or rom-calls)
is included.  At present limited implemtations of two emulations are
included:NetBSD (UEA model) and OpenBoot (OEA model).

PEDANTIC VEA MEMORY MODEL: In VEA/UEA NetBSD simulations, this model
implements the break (brk, sbrk) system calls.  Further, the user
model has very strict memory access controls.  User programs can not
assume that they can stray off the end of valid memory areas.  This
model defines valid memory addresses in strict accordance to the
executable and does not page allign their values.  At first this was a
bug but since then has turned up several problems in user code so it
is now described as a feature.

PERFORMANCE MONITORING: This simulation is able to monitor things such
as cpu/io read/writes and register allocation.

PERFORMANCE: In its default configuration PSIM is configured so that
it will compile fast and run slow.  Through the enabling of more
agressive compile options (and the disabling of unwanted features) the
build can be changed to compile slow and run fast.

FLOATING POINT: Preliminary suport for floating point is included.
Real kernels don't need floating point.


BUILDING PSIM:

To build PSIM you will need the following:

	gdb-4.15.tar.gz		From your favorite GNU ftp site.
				I've also tested psim-951016 with
				gdb-4.15.1.


	ftp://ftp.ci.com.au/pub/clayton/README.pim

				This file.

	ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+psim-951016.diff.gz

				This contains a few minor patches to
				gdb-4.15 so that will include psim
				when it is built.

	ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+psim-951016.tar.gz

				This contains the psim files propper.

	ftp://ftp.ci.com.au/pub/clayton/psim-test-951016.tar.gz

				(Optional) A scattering of pre-compiled
				programs that run under the simulator.

	gcc			Again available from your favorite
				GNU ftp site.

	patch			Sun's patch behaves a little wierd
				and doesn't appear to like creating
				empty files.


Since PSIM is still being developed, from time to time, further psim
snap shots are occasionally made available.  These snapshots may or
may not work with GDB-4.15.  Several of the more significant snap
shots are:

	ftp://ftp.ci.com.au/pub/clayton/psim-951215.tar.gz

				A dangerous snap shot

				Hopefully merges in Michael stuff
				with mine,  adds multiple emulations
				(OpenBoot and NetBSD),  revamps
				inline stuff, rearanges devices so
				that phandls and ihandles can be
				implemented.

	ftp://ftp.ci.com.au/pub/clayton/psim-951203.tar.gz

				A good snapshot

				This includes extensions from Michael
				Meissner that add monitoring of the
				PowerPC's register and bus architectures.


Procedure:

0.	A starting point

		$ ls -1
		gdb-4.15+psim-951016.diff.gz
		gdb-4.15+psim-951016.tar.gz
		gdb-4.15.tar.gz
		psim-test-951016.tar.gz


1.	Unpack gdb

		$ gunzip < gdb-4.15.tar.gz | tar xf -


2.	Change to the gdb directory, apply the psim patches and unpack
	the psim files.

		$ cd gdb-4.15

		$ gunzip < ../gdb-4.15+psim-951016.diff.gz | more
		$ gunzip < ../gdb-4.15+psim-951016.diff.gz | patch -p1

		$ gunzip < ../gdb-4.15+psim-951016.tar.gz | tar tvf -
		$ gunzip < ../gdb-4.15+psim-951016.tar.gz | tar xvf -


3.	Configure gdb

		$ more gdb/README

	then something like (I assume SH):

		$ CC=gcc ./configure --target=powerpc-unknown-eabisim

	eabisim is needed as by default (because PSIM needs GCC) the
	simulator is not built.


4.	Build

		$ make CC=gcc

	alternativly, if you are short on disk space or just want the
	simulator built:

		$ ( cd libiberty && make CC=gcc )
		$ ( cd bfd && make CC=gcc )
		$ ( cd sim/ppc && make CC=gcc )


5.	Install

		$ make CC=gcc install

	or just

		$ cp gdb/gdb ~/bin/powerpc-unknown-eabisim-gdb
		$ cp sim/ppc/run ~/bin/powerpc-unknown-eabisim-run


USING THE SIMULATOR:

(I assume that you've unpacked the psim-test archive).

1.	As a standalone program

	Print out the users environment:

		$ powerpc-unknown-eabisim-run envp

	Print out the arguments:

		$ powerpc-unknown-eabisim-run argv a b c

	Check that sbrk works:

		$ powerpc-unknown-eabisim-run break


2.	Example of running GDB:	

	The main thing to note is that before you can run the simulator
	you must enable it.  The example below illustrates this:

		$ powerpc-unknown-eabisim-gdb envp
		(gdb) target sim
		(gdb) load
		(gdb) break main
		(gdb) run
		.
		.
		.


BUGS AND PROBLEMS:

There is a mailing list (subscribe through majordomo@ci.com.au) (that
is almost never used) at:

	powerpc-psim@ci.com.au

If I get the ftp archive updated I post a note to that mailing list.
In addition your welcome to send bugs or problems either to me or to
that e-mail list.


KNOWN PROBLEMS:

See the ChangeLog file looking for lines taged with the word FIXME.

COREFILE.C: The implementation of corefile.c (defined by corefile.h) isn't the
best.  It is intended to be functionaly correct rather than fast.

HTAB (page) code for OEA model untested.  Some of the vm code
instructions unimplemented.

Lacks PowerOpen (a.k.a. XCOFF a.k.a. AIX) and NT startups.  The
PowerOpen worked until I added the ELF one.

Missing VEA system calls.

Missing or commented out instructions.

64bit target untested.

64bit host broken.  For instance use of scanf "%x", &long long.

Event code for pending events from within signal handlers not
finished/tested.

Better and more devices.

PORTABILITY (Notes taken from Michael Meissner): Heavy use of the ##
operator - fix using the clasic X/**/Y hack; Use of the signed
keyword.  In particular, signed char has no analogue in classic C
(though most implementations of classic C use signed chars); Use of
long long which restricts the target compiler to be GCC.


THANKS:

Thanks go to the following who each helped in some way.

	Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam,
	Michael Meissner, Bob Mercier, Richard Perini,
	Richard Stallman, Mitchele Walker