2 PSIM - model the PowerPC environment
4 Copyright (C) 1994-1996, Andrew Cagney <cagney@highland.com.au>.
6 ----------------------------------------------------------------------
10 This file describes how to run the program PSIM.
12 o Walk through a number of examples from the
13 pre-built tar archive psim-test.
15 o Looks at the device tree used by PSIM.
17 o Notes on building a programmer environment to
18 use with PSIM (BSD/UEA and BUG/OEA)
21 ----------------------------------------------------------------------
27 The compressed tar archive psim-test available from:
29 ftp://ftp.ci.com.au/pub/psim/psim-test-1.0.tar.gz
30 or ftp://cambridge.cygnus.com/pub/psim/psim-test-1.0.tar.gz
32 contains a number of pre-built programs for running under PSIM. Each
33 pre-built binary is built both big and little endian. The suffixes
34 .be/.le (executables) .bo/.lo (object files) and .ba/.la (libraries)
38 To run one of these programs, use:
40 powerpc-unknown-eabi-run <image>
44 powerpc-unknown-eabi-run psim-test/uea/envp
46 (The program envp prints out your shells environment - very useful
47 :-). More generally psim is run as (this is part of the output from
50 psim [ <psim-option> ... ] <image> [ <image-arg> ... ]
54 <image> Name of the PowerPC program to run.
55 This can either be a PowerPC binary or
56 a text file containing a device tree
58 PSIM will attempt to determine from the
59 specified <image> the intended emulation
61 If PSIM gets it wrong, the emulation
62 environment can be specified using the
63 `-e' option (described below).
65 <image-arg> Argument to be passed to <image>
66 These arguments will be passed to
67 <image> (as standard C argv, argc)
68 when <image> is started.
70 <psim-option> See below
72 The following are valid <psim-option>s:
74 -m <model> Specify the processor to model (604)
75 Selects the processor to use when
76 modeling execution units. Includes:
79 -e <os-emul> specify an OS or platform to model
80 Can be any of the following:
81 bug - OEA + MOTO BUG ROM calls
82 netbsd - UEA + NetBSD system calls
83 chirp - OEA + a few OpenBoot calls
85 -i Print instruction counting statistics
87 -I Print execution unit statistics
89 -r <size> Set RAM size in bytes (OEA environments)
91 -t [!]<trace> Enable (disable) <trace> option
93 -o <spec> add device <spec> to the device tree
95 -h -? -H give more detailed usage
98 The `-H' option gives a long usage output. This includes a complete
99 list of all the pre-configured devices.
102 ----------------------------------------------------------------------
108 If you built PSIM with gdb then the following is a quick start
111 At present GDB, if configured big-endian (say) unlike PSIM, does not
112 support the debugging of little endian binaries. If you find that
113 your program won't run at all, make certain that GDB and your
114 program's endianness match.
117 The most important thing is that before you can run the simulator you
118 must enable it. For the simulator, gdb is started like any program:
120 $ powerpc-unknown-eabi-gdb psim-test/uea/envp.be
122 Next the simulator is enabled. The command `target sim' accepts the
123 same options as can be specified on the PSIM command line.
127 To trace the communication between psim and gdb specify `target sim -t
128 gdb'. Once enabled, the binary needs to be loaded, any breakpoints of
129 interest set, and the program run:
138 In addition, if you are wanting to run a program described by a device
139 tree you can `attach' to the simulation using (I assume that you have
140 applied the attach patch):
143 $ powerpc-unknown-eabi-gdb
145 (gdb) attach device-tree
148 Here GDB takes the programs initial state from the attached
149 device-tree instead of forcing initialisation.
152 ----------------------------------------------------------------------
158 PSIM includes a number of performance monitoring (profiling)
161 o instruction frequency counting
163 o execution unit modeling (records
164 effective usage of units).
166 o instruction cache performance
168 As discussed in the file INSTALL, each can be configured to individual
172 -i Enable instruction counting.
174 The frequency of all instructions is tabulated. In
175 addition (f configured) the hit/miss rate of the
176 instruction cache is output.
179 -I Enable execution unit analysis.
181 In addition to counting basic instructions also model
182 the performance of the processors execution units
187 Select the processor to be modelled.
189 For execution unit analysis specify the processor that
190 is to be analysed. By default the 604 is modelled
191 however, support for other processors such as the
192 603 and 603e is included.
194 The output from a performance run (on a P90) for the program
195 psim-test/profile/bench is below. In this run psim was fairly
196 agressively configured (see the file INSTALL for compile time
199 CPU #1 executed 41,994 AND instructions.
200 CPU #1 executed 519,785 AND Immediate instructions.
201 CPU #1 executed 680,058 Add instructions.
202 CPU #1 executed 41,994 Add Extended instructions.
203 CPU #1 executed 921,916 Add Immediate instructions.
204 CPU #1 executed 221,199 Add Immediate Carrying instructions.
205 CPU #1 executed 943,823 Add Immediate Shifted instructions.
206 CPU #1 executed 471,909 Add to Zero Extended instructions.
207 CPU #1 executed 571,915 Branch instructions.
208 CPU #1 executed 1,992,403 Branch Conditional instructions.
209 CPU #1 executed 571,910 Branch Conditional to Link Register instructions.
210 CPU #1 executed 320,431 Compare instructions.
211 CPU #1 executed 471,911 Compare Immediate instructions.
212 CPU #1 executed 145,867 Compare Logical instructions.
213 CPU #1 executed 442,414 Compare Logical Immediate instructions.
214 CPU #1 executed 1 Condition Register XOR instruction.
215 CPU #1 executed 103,873 Divide Word instructions.
216 CPU #1 executed 104,275 Divide Word Unsigned instructions.
217 CPU #1 executed 132,510 Extend Sign Byte instructions.
218 CPU #1 executed 178,895 Extend Sign Half Word instructions.
219 CPU #1 executed 871,920 Load Word and Zero instructions.
220 CPU #1 executed 41,994 Move From Condition Register instructions.
221 CPU #1 executed 100,005 Move from Special Purpose Register instructions.
222 CPU #1 executed 100,002 Move to Special Purpose Register instructions.
223 CPU #1 executed 804,619 Multiply Low Word instructions.
224 CPU #1 executed 421,201 OR instructions.
225 CPU #1 executed 471,910 OR Immediate instructions.
226 CPU #1 executed 1,292,020 Rotate Left Word Immediate then AND with Mask instructions.
227 CPU #1 executed 663,613 Shift Left Word instructions.
228 CPU #1 executed 1,151,564 Shift Right Algebraic Word Immediate instructions.
229 CPU #1 executed 871,922 Store Word instructions.
230 CPU #1 executed 100,004 Store Word with Update instructions.
231 CPU #1 executed 887,804 Subtract From instructions.
232 CPU #1 executed 83,988 Subtract From Immediate Carrying instructions.
233 CPU #1 executed 1 System Call instruction.
234 CPU #1 executed 207,746 XOR instructions.
236 CPU #1 executed 23,740,856 cycles.
237 CPU #1 executed 10,242,780 stalls waiting for data.
238 CPU #1 executed 1 stall waiting for a function unit.
239 CPU #1 executed 1 stall waiting for serialization.
240 CPU #1 executed 1,757,900 times a write-back slot was unavailable.
241 CPU #1 executed 1,088,135 branches.
242 CPU #1 executed 2,048,093 conditional branches fell through.
243 CPU #1 executed 1,088,135 successful branch predictions.
244 CPU #1 executed 904,268 unsuccessful branch predictions.
245 CPU #1 executed 742,557 branch if the condition is FALSE conditional branches.
246 CPU #1 executed 1,249,846 branch if the condition is TRUE conditional branches.
247 CPU #1 executed 571,910 branch always conditional branches.
248 CPU #1 executed 9,493,653 1st single cycle integer functional unit instructions.
249 CPU #1 executed 1,220,900 2nd single cycle integer functional unit instructions.
250 CPU #1 executed 1,254,768 multiple cycle integer functional unit instructions.
251 CPU #1 executed 1,843,846 load/store functional unit instructions.
252 CPU #1 executed 3,136,229 branch functional unit instructions.
253 CPU #1 executed 16,949,396 instructions that were accounted for in timing info.
254 CPU #1 executed 871,920 data reads.
255 CPU #1 executed 971,926 data writes.
256 CPU #1 executed 221 icache misses.
257 CPU #1 executed 16,949,396 instructions in total.
259 Simulator speed was 250,731 instructions/second
262 ----------------------------------------------------------------------
265 PSIM CONFIGURATION - THE DEVICE TREE
268 Internally PSIM's configuration is controlled by a tree data
269 structure. This structure, created at run-time, intentionally
270 resembles the device tree used by OpenBoot firmware to describe a
271 machines hardware configuration.
273 PSIM can either create its device tree using a builtin emulation or
274 from one read in from a file.
276 During startup, the device tree is created using the following steps:
278 o Initial empty tree is created
280 o Any tree entry options specified on the
281 command line are merged in (the -o <entry>
284 It should be pointed out that most of the
285 command line options (eg -r, -e, -m, -t
286 are all just short hand for corresponding
289 o If the specified program is a device tree spec, that
292 If the specified program is a text file it is assumed
293 that that file contains a further specification of the
294 simulators device tree. That tree is loaded and
295 merged with the current tree options.
297 o The selected emulation fills out any remaining details.
299 By this stage the emulation environment that the program
300 needs will either be specified in the device tree
301 (through the -e option) or determined from the
302 characteristics of the binary.
304 The selected emulation will then fill out any missing
305 nodes in the device tree.
307 Most importantly earlier additions to the tree are not overridden by
308 later additions. Thus, command line options override information
309 found in the program file and both override any emulation entries.
311 The following is a summary of the most useful runtime configuration
315 -o '/openprom/options/os-emul <os-emul>'
317 Run program using the <emulation> run-time
321 -o '/openprom/options/oea-memory-size <ram-size>'
323 Set the size of the first bank of memory
324 (RAM from address 0 up).
327 -o '/openprom/trace/print-device-tree 1'
330 -o '/openprom/trace/dump-device-tree 1'
332 Print out the device tree once it has been fully
333 populated. For dump-device-tree, exit simulator after
336 PSIM is able to reload the dumped device tree.
338 The format of the dumped tree is under development.
340 -o '/openprom/options/smp <N>'
342 Enable <N> processors for the simulation run.
343 See the directory psim-test/oea for an example.
345 -o '/openprom/options/alignment <N>'
347 Where <N> is 1 - nonstrict or 2 - strict.
348 Specify if the missaligned access are allowed
349 (non-strict) or result in an alignment exception
352 Devices (if included in the file device_table.c) can also be specified
353 in a similar way. For instance, to add a second serial port, a
356 -o '/iobus@0x400000/console@0x000010'
358 would create a `console' device at offset 0x10 within the `iobus' at
359 memory address 0x400000.
361 For more detailed information on device specifiers see the notes on
362 the function dump_device_tree in the file device.c (found in the
366 ----------------------------------------------------------------------
369 BUILDING A BUG/OEA DEVELOPMENT ENVIRONMENT
375 Included in many PowerPC systems is Motorola's BUG monitor. This
376 monitor includes, for client programs, a set of services that allow
377 that program to interact with hardware devices such as the console using
378 a simple system call interface.
380 PSIM is able to emulate a number of the services (including the
381 console IO calls). If additional services are needed they can easily
384 Cygnus support's newlib library includes includes an interface to the
385 MOTO BUG services. The notes below discuss how I both built and run
386 programs compiled using this library on PSIM.
388 The only confusing part about building a development environment based
389 around newlib/binutils/gcc is a chicken/egg problem with include
392 For GCC to build, a fairly complete set of include
393 files must be installed but newlib won't install its
394 include files until it has been built with gcc ...
396 I get around this by installing the problematic include files by hand.
402 The following files are needed:
404 From your favorite FTP site, the sources to gas/ld and gcc - mine
405 happens to be archie.au :
407 ftp://archie.au/gnu/binutils-2.6.tar.gz
408 ftp://archie.au/gnu/gcc-2.6.2.tar.gz
410 From ftp://ftp.cygnus.com/pub/newlib the source code to a library:
412 ftp://ftp.cygnus.com/pub/newlib/newlib-1.7.0.tar.gz
414 From ftp://ftp.ci.com.au/pub/psim some minor patches and updates to
417 ftp://ftp.ci.com.au/pub/psim/newlib-1.7.0+float+ppc-asm.tar.gz
418 ftp://ftp.ci.com.au/pub/psim/newlib-1.7.0+ppc-fix.diff.gz
419 ftp://ftp.ci.com.au/pub/psim/binutils-2.6+note.diff.gz
421 In addition you'll need to decide where you will be installing the
422 development environment. You will notice that in the below I install
423 things well away /usr/local instead installing everything under its
424 own directory in /applications.
430 These notes are based on an installation performed on a Sun-OS-4/SPARC
431 host. For other hosts and other configurations, the below should be
432 considered as a guideline only.
437 $ cd .../scratch # your scratch directory
440 binutils-2.6+note.diff.gz
442 newlib-1.7.0+float+ppc-asm.tar.gz
443 newlib-1.7.0+ppc-fix.diff.gz
447 o Unpack/build/install binutils
449 This is done first so that there is a gas/ld ready
450 for the building of GCC and NEWLIB.
453 $ gunzip < binutils-2.6.tar.gz | tar xf -
456 Optionally apply the note patch
458 $ gunzip ../binutils-2.6+note.diff.gz | patch
460 Then continue with the build
462 $ ./configure --target=powerpc-unknown-eabi \
463 --prefix=/applications/psim
467 $ rm -rf binutils-2.6
469 This also creates much of the installation directory
473 o Unpack newlib, install the include files so that they
474 are ready for GCC's build.
477 $ gunzip < newlib-1.7.0.tar.gz | tar xf -
479 New lib-1.7.0 had a few minor bugs (fixed in current):
480 the header files float.h and ppc-asm.h were missing;
481 the configure and Makefile's for the rs6000 (ppc) directory
486 $ gunzip < ../newlib-1.7.0+float+ppc-asm.tar.gz | tar xvf -
487 $ gunzip < ../newlib-1.7.0+ppc-fix.diff.gz | patch -p1
489 Finally copy the include files to where GCC will see them:
492 $ cd newlib-1.7.0/newlib/libc
493 $ tar cf - include | \
494 ( cd /applications/psim/powerpc-unknown-eabi && tar xf - )
500 $ gunzip < gcc-2.7.2,tar.gz | tar xf -
502 $ ./configure --target=powerpc-unknown-eabi \
503 --prefix=/applications/psim
509 Gcc likes to install its own dummy version of float that
510 just returns an error.
512 $ more /applications/psim/lib/gcc-lib/powerpc-unknown-eabi/2.7.2/include/float.h
513 $ rm /applications/psim/lib/gcc-lib/powerpc-unknown-eabi/2.7.2/include/float.h
516 o Finish building/installing newlib
520 $ ./configure --target=powerpc-unknown-eabi \
521 --prefix=/applications/psim
523 Your path will need to include the recently installed
524 gas/gcc when building. Either add it to your path or
527 $ PATH=/applications/psim/bin:$PATH make
528 $ PATH=/applications/psim/bin:$PATH make install
531 o Finally, test out the build
536 printf("hello world\n");
539 The binary is linked with an entry point less than 0x100000
540 (1mb) so that psim will recognize the binary as needing
541 the BUG/OEA instead of the BSD/UEA runtime environment.
543 $ powerpc-unknown-eabi-gcc -v -o hello \
544 -Wl,-Ttext,0x4000,-Tdata,0x10000 \
545 /applications/psim/powerpc-unknown-eabi/lib/mvme-crt0.o \
548 $ powerpc-unknown-eabi-objdump -h hello
549 $ powerpc-unknown-eabi-run hello
551 It is also possible to force psim to use a specific
552 run-time environment using the -e option vis:
554 $ powerpc-unknown-eabi-run -e bug hello
559 ----------------------------------------------------------------------
562 BUILDING A BSD/UEA DEVELOPMENT ENVIRONMENT
568 For a UEA to be useful it needs a supporting run-time environment.
569 PSIM implements a runtime environment based on the NetBSD system call
572 More than any thing, this user level emulation was the first
573 implemented because I happened to have the NetBSD source code lying
580 This requires the NetBSD-1.1 source tree online. It can either be
583 try http://www.netbsd.org or ftp://ftp.netbsd.org
585 Alternatively obtain one of the NetBSD cdrom's. Patches to this source
586 tree that fill out much of the PowerPC code are available in:
588 ftp://ftp.ci.com.au/pub/clayton
590 Fetch everything in that directory - diffs, tar archives and scripts.
591 In addition a patch to binutils is in:
593 ftp://ftp.ci.com.au/pub/psim/binutils-2.6+note.diff.gz
595 Finally you'll require a compiler and assembler/linker:
606 These notes are based on an installation performed on a Solaris2/x86
607 host. For other hosts and other configurations, the below should be
608 considered as a guideline only.
613 I assume that you have already obtained the NetBSD-1.1 source
614 code and unpacked it into the directory bsd-src. While the
615 full NetBSD source tree may not be needed, things are easier
622 clayton-include-960203.diff.gz
623 clayton-lib-960203.diff.gz
624 clayton-lib-960203.tar.gz
625 clayton-sys-960203.diff.gz
626 clayton-sys-960203.tar.gz
627 clayton-utils-960203.tar.gz
632 clayton.usr.bin.make.diff
634 gcc-2.7.2+sys-types.diff.gz
637 o Unpack the bsd source code (if you haven't already)
642 $ for d in /cdrom/bsdisc_12_95_disc2/NetBSD-1.1/source/*11
645 cat $d/*.?? | gunzip | tar xf -
648 Flatten the directory structure a little.
655 o Unpack/build/install binutils
658 $ gunzip < binutils-2.6.tar.gz | tar xf -
661 Optionally apply the note patch
663 $ gunzip ../binutils-2.6+note.diff.gz | patch
665 Then continue with the build
667 $ ./configure --target=powerpc-unknown-eabi \
668 --prefix=/applications/psim
672 $ rm -rf binutils-2.6
674 This has the intended side effect of partially populating
675 the psim directory tree which makes follow on steps easier.
678 o Fill out the install directory with a few additions (if
679 install -d works, this can be simplified).
682 /applications/psim/bsd-root \
683 /applications/psim/bsd-root/usr \
684 /applications/psim/bsd-root/usr/share \
685 /applications/psim/bsd-root/usr/share/doc \
686 /applications/psim/bsd-root/usr/share/doc/psd \
687 /applications/psim/bsd-root/usr/share/doc/psd/19.curses \
688 /applications/psim/bsd-root/usr/include \
689 /applications/psim/bsd-root/usr/lib \
692 o Make the bsd and gnu include directories point to the same
695 GCC expects include files to be in one location while the
696 bsd install expects them in a second. The link is in
697 the direction below because bsd's install also insists on
698 a directory (not a link) for its install destination.
700 $ ln -s ../bsd-root/usr/include \
701 /applications/psim/powerpc-unknown-eabi/include
705 o Build/install Berkeley make
707 In building Berkeley make from the NetBSD-1.1 source tree
708 a number of problems may be encountered.
710 These problems have been fixed in NetBSD-current (after
711 4/2/96 (ie start Feb)) you should probably obtain that
712 version of make. Alternatively, you can try following the
713 notes below that got make working on a Solaris-2.5/x86
717 $ cd bsd-src/usr.bin/make
719 .../scratch/bsd-src/usr.bin/make
721 Copy/stub some additional include files that your host may not
724 $ cp ../../include/ranlib.h ranlib.h
726 $ cp ../../sys/sys/cdefs.h sys/cdefs.h
728 $ touch machine/cdefs.h
730 Edit/fix some of the BSDisms. The patch file indicated
731 contains fixes I found when compiling on my host, your
732 host will probably differ.
734 $ gunzip < ../../../clayton.usr.bin.make.diff.gz | patch
736 Build it with some extra flags (again your flags will differ):
738 $ make -f Makefile.boot CC='gcc -g -DPOSIX'
740 With bmake built, install it into the target specific bin
743 $ cp bmake /applications/psim/powerpc-unknown-eabi/bin/make
747 o Patch/install Berkeley make's include (mk) files.
751 $ tar cf - mk | ( cd /applications/psim/bsd-root/usr/share \
756 o Set up a number of wrapper scripts for bmake so that it works.
758 In addition to needing BSD make the build process assumes
759 a number of BSD specific commands. To get around this
760 several wrapper scripts are available.
762 powerpc-unknown-eabi-make (clayton.make)
764 Front end to Berkeley make setting it up for a
767 /applications/psim/bin/powerpc-unknown-eabi-make
769 chown (clayton.chown)
771 Wrapper that does not do any thing.
772 Avoids the need to be root when installing.
774 /applications/psim/powerpc-unknown-eabi/bin
776 install (clayton.install)
778 Wrapper to strip away a number of bsd specific install
781 /applications/psim/powerpc-unknown-eabi/bin/install
783 lorder (clayton.lorder)
785 Tweaked lorder script that will use nm etc from
788 /applications/psim/powerpc-unknown-eabi/bin/lorder
791 o Apply the remaining patches for the BSD source tree
796 Diffs are applied using something like:
798 $ gunzip < ../clayton-include-960203.diff.gz | more
801 The patch to sys/dev/pci/ncr.c.rej might fail.
803 The tar archives have a different problem, you need
804 to remove the `src' prefix. I used
807 $ gunzip < ../clayton-lib-960203.tar.gz | tar xtf -
810 So that src/xxx unpacked into ./xxx
817 o Install the include files
821 $ powerpc-unknown-eabi-make install
825 o Install a few other include files.
827 As with building libnew, the bsd build process has
828 several include file problems.
832 $ cp gnu/lib/libg++/g++-include/values.h \
833 /applications/psim/powerpc-unknown-eabi/include
834 $ cp lib/libcurses/curses.h \
835 /applications/psim/powerpc-unknown-eabi/include
844 $ gunzip < gcc-2.7.2,tar.gz | tar xf -
847 GCC and BSD (for PowerPC) have a conflicting type
848 declaration. The patch below gets around this
851 $ gunzip < ../gcc-2.7.2+sys-types.diff.gz | patch
853 Other than that, assuming the include files installed
854 okay, the rest should be fine ....
856 $ ./configure --target=powerpc-unknown-eabi \
857 --prefix=/applications/psim
859 $ make CC=gcc install
864 o Build/install the Berkeley library:
868 $ powerpc-unknown-eabi-make
869 $ powerpc-unknown-eabi-make install
872 If you encounter problems try the following: an include
873 file not yet installed; a directory not yet created;
874 running the hosts version of a program instead of a
877 o Build/run a simple BSD program
880 $ cd bsd-src/usr.bin/printenv
881 $ powerpc-unknown-eabi-make
882 $ powerpc-unknown-eabi-run printenv
888 ----------------------------------------------------------------------