PSIM - model a PowerPC platform Copyright (C) 1994-1995, Andrew Cagney . This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. This directory contains the source code to the program PSIM that implements a model of a PowerPC platform. PSIM can either be built standalone or as part of the debugger GDB. What is PSIM? PSIM is an ANSI C program that can be configured to model various PowerPC platforms. The platform that is modeled can vary from: o A user program environment (UEA) complete with emulated system calls to o A hardware platform with several processors interacting with each other and various modeled hardware devices. Is the source code available? Yes. The source code to PSIM is available under the terms of the GNU Public Licence. This allows you to distribute the source code for free but with certain conditions. What motivated PSIM? As an idea, psim was first discussed seriously during mid 1994. At that time its main objectives were: o good performance Many simulators loose out by only providing a binary interface to the internals. This inteface eventually becomming a bottle neck in the simulators performance. It was intended that PSIM would avoid this problem by giving the user access to the full source code. Further, by exploiting the power of modern compilers it was hoped that PSIM would achieve good performance with out having to compromize its internal design. o practical portability Rather than try to be portable to every C compiler on every platform, it was decided that PSIM would restrict its self to suporting ANSI compilers that included the extension of a long long type. GCC is one such compiler, consequenly PSIM should be portable to any machine running GCC. o flexability in its design PSIM should allow the user to select the features required and customize the build accordingly. By having the source code, the compler is able to eliminate any un used features of the simulator. After all, let the compiler do the work. o SMP A model that allowed the simulation of SMP platforms with out the large overhead often encountered with such models. PSIM achieves each of these objectives. Who would be interested in PSIM? o the curious Using psim, gdb, gcc and binutils the curious user can contruct an environment that allows them to play with PowerPC user programs with out the need for real hardware. o the analyst PSIM includes many (contributed) monitoring features which (unlike many other simulators) do not come with a great penalty in performance. Thus the performance analyst is able to use this simulator to model the inpact of changes to the system they are analysing. Be that system a compiler or real hardware platform. If PSIM doesn't monitor a components of interest, the source code is freely available, and hence there is no hinderance to changing things to meet a specific analysts needs. o the serious SW developer PSIM models all three levels of the PowerPC Architecture: UEA, VEA and OEA. Further, the internal design is such that PSIM can be extended to suport additional development requirements. Such requirements might include (for the UEA) a new Operating System emulation through to (for the OEA) a model of a different hardware platform. What features does PSIM have? Monitoring and modeling PSIM includes (thanks to Michael Meissner) a detailed model of the various PowerPC implementations schedulers. SMP The PowerPC ISA defines SMP synchronizing instructions this simulator models a limited subset of their behavor. Consequently, if you limit code to the use the modeled behavour, PSIM can be used to model SMP PowerPC platforms. People intending to use this system should study the code implementing the lwarx etc instructions. ENDIAN SUPORT PSIM implements the PowerPC's big and little (xor endian) modes and correctly simulates code that switches between these two modes. In addition, psim can model a true little-endian machine. ISA models (Instruction Set Architecture) PSIM includes a model of the UEA, VEA and OEA. This inclues the time base registers (VEA) and HTAB and BATS (OEA). In addition, a preliminary model of the 64 bit PowerPC architecture is implemented. Hardware PSIM's internals are based around the concept of a Device Tree. This tree intentionaly resembles that of the Device Tree found in OpenBoot firmware. PSIM is flexable enough to allow the user to fully configure the actual hardware model from a device tree specification that is read in from a file. A user can either run a program using one of PSIM's built in hardware models specify a custom hardware model that should be simulated. A user is also able to quickly add a model of new hardware devices so that they can be included in a custom hardware model. Emulation PSIM is able (UEA) to emulate UNIX calls based on NetBSD abi through to (preliminary) the ROM rom calls found in common firmware (OpenBoot and BUGAPI). Floating point Preliminary suport for floating point is included. Real kernels don't need floating point. Is PSIM CHRP Compliant? No. However, PSIM does include all the hooks that are needed to construct a model of a CHRP compliant platform. That is: o OpenBoot client software o OpenPIC interrupt controller o Hooks to implement a RTAS interface o the ability to add a model of each of the hardware devices required by a CHRP compliant desktop. How do I build PSIM? To build PSIM you will need the following files: gdb-4.15.tar.gz From your favorite GNU ftp site. I've also tested psim-951016 with gdb-4.15.1. If you would prefer a graphical development environment then PSIM can also be built with gdbtk. 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/psim-test-951016.tar.gz (Optional) A scattering of pre-compiled programs that run under the simulator. ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+psim-951016.tar.gz This contains the psim files proper. 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. You may want to consider installing gnu's patch. In addition, I'm slowly building up a set of useful patches to gdb-4.15 that are useful. You will want to also apply these patches: ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+attach.diff.gz Patch to gdb that allows the `attach' command to be used when connecting to a simulator. See that file for more information. ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+note.diff.gz Patch to gdb's bfd that adds basic support for a .note section. OpenBoot makes use of a .note section when loading a boot image. 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 - You may also want to consider applying the `attach' and `note' patches that are available vis: $ gunzip < ../gdb-4.15+attach.diff.gz | more $ gunzip < ../gdb-4.15+attach.diff.gz | patch -p $ gunzip < ../gdb-4.15+note.diff.gz | more $ gunzip < ../gdb-4.15+note.diff.gz | patch -p 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 Is there a more recent version of PSIM and if so, how would I build it? A PSIM is an ongoing development, occasional snapshots (that include new features) are made available. Several of the more recent snapshots are: ftp://ftp.ci.com.au/pub/clayton/psim-951219.tar.gz 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. To build/install one of these snapshots, you replace the current gdb/sim/ppc directory with the one in the update, re-configure and rebuild. Procedure: 0. A starting point $ cd gdb-4.15 1. Remove the old psim directory $ mv sim/ppc sim/old.ppc 2. Unpack the new one $ gunzip < ../psim-960105.tar.gz | tar tf - $ gunzip < ../psim-960105.tar.gz | tar tf - 3. Reconfig/rebuild (as seen above): $ CC=gcc ./configure --target=powerpc-unknown-eabisim $ make CC=gcc Are there any example programs that can be run on PSIM? Psim has a simple test suite that is used to ensure that fixes do not introduce new bugs. This test suite like psim is updated: ftp://ftp.ci.com.au/pub/clayton/psim-test-951218.tar.gz Prebuilt test programs for PSIM. Includes examples of UEA, VEA and OEA code. Requires gcc-2.7.2 and binutils-2.6 to rebuild. ftp://ftp.ci.com.au/pub/clayton/psim-test-951016.tar.gz (Optional) A scattering of pre-compiled programs that run under the simulator. How do I use the simulator? I assume that you've unpacked a psim-test archive. 1. As a standalone program Print out the users environment: $ powerpc-unknown-eabisim-run psim-test/uea/envp Print out the arguments: $ powerpc-unknown-eabisim-run psim-test/uea/argv a b c Check that sbrk works: $ powerpc-unknown-eabisim-run psim-test/uea/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 psim-test/uea/envp (gdb) target sim (gdb) load (gdb) break main (gdb) run . . . 3. Using a device tree as a description of a machine (I assume that you have applied the attach bug). $ cd psim-test/tree $ powerpc-unknown-eabisim-gdb (gdb) target sim (gdb) attach device-tree (gdb) run or $ cd psim-test/tree $ powerpc-unknown-eabisim-run device-tree Where do I send bugs or report 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. Does PSIM have any limitations or problems? See the file PROBLEMS (included in the distribution) for any outstanding issues. Who helped? 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