old-cross-binutils/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
architecture.  It can either be run stand alone (psim or run) or used
as part of GDB.


SOURCE:

	PSIM is now part of the Cygnus GDB source tree (hopefully it
	will in turn become part of the next FSF release of GDB).

	If you're looking for a more `cutting' edge version of this
	program then it can be found in:

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

	This contains a replacement for the directory sim/ppc.  As
	these releases prove stable they are merged back into the GDB
	source tree.

	If you find bugs or experience problems, please e-mail them to
	the alias:

		powerpc-psim@ci.com.au

	It's a majordomo mailing list.


BUILDING:

	o At present PSIM can only be built using the compiler GCC
	  (yes that is bug).  This is because, among other things the
	  code exploits GCC's suport of long ongs.

	o I also suggest that you install: flex, bision, gnu-make and
	  byacc.  Doing this just makes builds easier.

	o Configure almost as per normal, specifing the special target
	  eabisim vis:

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

	  by default (because of its dependency on GCC).

	o Build your entire gdb tree as per normal.  Something along the
	  lines of:

		$ cd gdb-4.15
		$ make CC=gcc
		.
		.
		.



	o Install it it all as per normal.  Something along the lines of:

		$ cd gdb-4.15
		$ make CC=gcc install


RUNNING:

	PSIM can either be run as a stand alone program or as part
	of gdb.  The psim-test archive (found in:

		ftp.ci.com.au:pub/clayton

	contains pre-compiled and linked programs that can be run on
	PSIM.  The notes below assume that you have unpacked that tar
	archive.

	To rebuild the archive you will need to obtain a working
	version of an ELF compiler/linker for the PowerPC.
	
	Example of running PSIM:

		Print out the users environment:

			$ sim/ppc/psim sim/ppc/test/envp

		Print out the arguments:

			$ sim/ppc/psim sim/ppc/test/argv a b c

		Check the OEA model:

			$ sim/ppc/psim sim/ppc/test/interrupt

		Check that sbrk works

			$ sim/ppc/psim sim/ppc/test/break

		Try for speed.  The program count contains a loop
		of two instructions which is looped <arg> times.
		See later for how to make PSIM run 10-100 times
		faster.

			$ time sim/ppc/sim sim/ppc/test/count 5000000
			$ expr 10 \* 1000 \* 1000 / <seconds>


	Example of running GDB:	

		The most important thing to be aware of is the fact
		that before the simulator is used, the user must attach
		to it (target sim) and than load the executable (load count).

			$ cd sim/ppc/test
			$ powerpc-unknown-eabi-gdb count
			(gdb) target sim
			(gdb) load count
			(gdb) break main
			(gdb) run
			.
			.
			.


CONFIGURATION:

	Making it go faster

	See the file sim/ppc/config.h (which is copied from
	sim/ppc/std-config.h) for further information.


KNOWN FEATURES

	SMP: A Symetric Multi-Processor configuration is suported.
	This includes a model of the PowerPC load word and reserve
	et.al. 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).

	DUAL-ENDIAN: Both little and big endian modes are suported.
	Switching between the two modes at run time, however, is not.

	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 of them.
	That is the User Instruction Set Architecture, the Virtual
	Environment Architecture and finally the Operating Environment
	Architecture.

	HARDWARE DEVICES: The OEA model includes facilities that allow
	a programmer to (I won't say easily) extend this simulator so
	that a program can interact with models of real devices.
	Illustrating this is the phony machine clayton that includes
	console, interrupt control unit and reset register devices.

	PEDANTIC VEA MEMORY MODEL: 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 bugs in
	peoples code so I've renamed it `a feature' :-)

	RUNTIME CONFIG OF HARDWARE: In addition to the three builtin
	models of hardware - VEA, OEA/Hardware and (the start of) OpenBoot,
	it is possible to load a file containing a specification of a
	custom device tree.


KNOWN PROBLEMS:

	FLOATING POINT: Need to add suport for non IEEE float
	machines.  Need to more fully handle exceptions (eg things
	like divide by zero).

	DEVICE TREE DOC: How to create and use the device tree is not
	documented at all.

	INITIALIZATION: When running from gdb, things are not
	re-initialzied very well e.g. registers are not rezeroed.

	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.

	Only basic (hackish) floating point implemented, I would not
	trust it and it is going to change.

	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.

	OPTIONS/FLAGS: Need a function that can parse command line
	options so that both psim and sim_{load,open,command} can all
	call it.  Options should be extended to allow the setting of
	things like floating point support.

THANKS:

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

		Allen Briggs, Bett Koch, David Edelsohn,
		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

----

CFLAGS = -g -Wall -Wno-unused -Wmissing-prototypes -Werror