path: root/sim/ppc/README.psim

			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 either be run stand alone (psim or run) or
used as part of GDB.


KNOWN FEATURES


SMP: A Symetric Multi-Processor configuration is suported.  This
includes modeling of the PowerPC load word and reserve instructions
(if intending to use this feature you are well advised to read the the
source code for the reservation instructions so that you are aware of
any potential limitations in the model).  The number of processors is
selected during startup.

DUAL-ENDIAN: Both little and big endian models are suported.  The
execution of instruction sequences that switch between the two modes,
however, is not.  The endianess is selected during startup.

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.  The environment is selected
during startup.  The OEA model is still under development.

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).  The device tree used to create
the hardware model is created during startup.  This device tree is
still under development.

VEA SYSTEM CALLS: In user mode, basic system calls (read, write, open,
close ...) are emulated.  Under NetBSD (simply because that is what my
machine at home runs) the list is more extensive.

PEDANTIC VEA MEMORY MODEL: 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.

PROFILING: The simulation is able to count the number and type of
instructions issued and the number of loads and stores.  This feature
is still under development.

PERFORMANCE: In its default configuration PSIM is constructed 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

	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.


In the directory ftp.ci.com.au:pub/clayton you will also notice files
named psim-NNNNNN.tar.gz.  Those, more recent snapshots, may or may
not work with gdb.


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 news group.  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.

Flush instruction cache instructions do nothing.  Perhaphs they should
(if there is an instruction cache) flush it.

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

OpenBoot and PR*P interfaces missing.  Open boot could be implemented
by putting special instructions at the address of the OpenBoot
callback functions.  Those instructions could than emulate OpenBoot
behavour.

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


----------------------------------------------------------------


Random notes on performance:


$ cd test
time ../psim count `expr 10000000 / 2`
time ../psim volatile-count `expr 10000000 / 7`

Where 2 and 7 are the number of instructions in the main loop.


	611/729 - baseline

Tests:

	CFLAGS= -c -O2 -m486 -fomit-frame-pointer

	o	different first/second level table/switch combinations

		0 - use a table
		1 - use a simple switch
		2 - use an expanded switch

i486DX4/100 - AMD

	1/108/140 - switch=0/0/0,expand=2,inline=2,nia=1,cache=1
	1/114/140 - switch=0/0/0,expand=2,inline=2,nia=1,cache=1
	1/137/149 - switch=0/0,expand=2,inline=1,nia=1,cache=1
	1/144/155 - switch=2/1,expand=2,inline=1,nia=1,cache=1
	1/153/159 - switch=2/1,expand=0,inline=1,nia=1,cache=1
	1/185/189 - switch=0/0,expand=0,inline=1,nia=1

i486DX2/66

	1/572/695 - switch=1/1,expand=0,inline=0
	1/579/729 - switch=0/0,expand=0,inline=0
	1/570/682 - switch=2/2,expand=0,inline=0
	1/431/492 - switch=0/0,expand=0,inline=1,nia=0
	1/271/292 - switch=2/1,expand=0,inline=1,nia=0
	1/270/316 - switch=2/2,expand=0,inline=1,nia=0
	1/271/281 - switch=1/1,expand=0,inline=1,nia=1
	1/267/274 - switch=2/1,expand=0,inline=1,nia=1