2 PSIM - model the PowerPC environment
4 Copyright (C) 1994-1996, Andrew Cagney <cagney@highland.com.au>.
6 ----------------------------------------------------------------------
11 This file describes how to build the program PSIM
13 o Walk through a basic build
15 o Discussion of PSIM's components and
16 how they relate to the build process
18 o Detailed description of each of PSIM's
19 compile time configuration options
22 ----------------------------------------------------------------------
27 PSIM 1.0.2 is included in GDB-4.16. To build PSIM you will need the
30 gdb-4.16.tar.gz Available from your favorite GNU
33 gcc GCC version two includes suport
34 for long long (64bit integer)
35 arrithemetic which PSIM uses. Hence
36 it is recommended that you build PSIM
44 $ gunzip < gdb-4.16.tar.gz | tar xf -
49 First consult the gdb documentation
56 then something like (I assume SH):
58 $ CC=gcc ./configure \
59 --enable-sim-powerpc \
60 --target=powerpc-unknown-eabi \
61 --prefix=/applications/psim
64 4. Build (again specifying GCC)
68 alternatively, if you are short on disk space or only
69 want to build the simulator:
71 $ ( cd libiberty && make CC=gcc )
72 $ ( cd bfd && make CC=gcc )
73 $ ( cd sim/ppc && make CC=gcc )
82 $ cp gdb/gdb ~/bin/powerpc-unknown-eabisim-gdb
83 $ cp sim/ppc/run ~/bin/powerpc-unknown-eabisim-run
86 ----------------------------------------------------------------------
92 A PSIM is an ongoing development. Occasional snapshots which both contain new
93 features and fix old bugs are made available. See the ftp directory:
95 ftp://ftp.ci.com.au/pub/psim/beta
96 or ftp://cambridge.cygnus.com/pub/psim/beta
98 for the latest version. To build/install one of these snapshots, you
99 replace the sim/ppc found in the gdb archive with with one from the
100 snapshot. Then just re-configure and rebuild/install.
109 1. Remove the old psim directory
111 $ mv sim/ppc sim/old.ppc
114 2. Unpack the new one
116 $ gunzip < ../psim-NNNNNN.tar.gz | tar tf -
117 $ gunzip < ../psim-NNNNNN.tar.gz | tar tf -
120 3. Reconfigure/rebuild (as seen above):
122 $ CC=gcc ./configure \
123 --enable-sim-powerpc \
124 --target=powerpc-unknown-eabi \
125 --prefix=/applications/psim
129 ----------------------------------------------------------------------
134 From time to time, problems involving the integration of PSIM into gdb
135 are found. While eventually each of these problems is resolved there
136 can be periouds during which a local hack may be needed.
138 At the time of writing the following were outstanding:
142 ftp://ftp.ci.com.au/pub/psim/gdb-4.15+attach.diff.gz
143 or ftp://cambridge.cygnus.com/pub/psim/gdb-4.15+attach.diff.gz
145 PSIM, unlike the other simulators found in GDB, is able to load
146 the description of a target machine (including the initial
147 state of all processor registers) from a file.
149 Unfortunatly GDB does not yet have a standard command that
150 facilitates the use of this feature. Until such a command is
151 added, the patch (hack?) gdb-4.15+attach.diff.gz can be used to
152 extend GDB's attach command so that it can be used to initialize
153 the simulators configuration from a file.
157 ----------------------------------------------------------------------
165 ftp://ftp.ci.com.au/pub/psim/RUN
166 or ftp://cambridge.cygnus.com/pub/psim/RUN
169 ----------------------------------------------------------------------
172 COMPILE TIME CONFIGURATION OPTIONS:
175 PSIM's compile time configuration is controlled by autoconf. PSIM's
176 configure script recognises options of the form:
178 --enable-sim-<option>[=<val>]
180 And can be specified on the configure command line (at the top level
181 of the gdb directory tree) vis:
184 $ CC=gcc ./configure \
185 --target=powerpc-unknown-eabisim \
186 --prefix=/applications/psim \
190 For a brief list of PSIM's configuration options, configure --help
196 Each PSIM specific option is discussed in detail below.
200 --enable-sim-cflags=<opts>
203 Specify additional C compiler flags that are to be used when compiling
206 PSIM places heavy demands on both the host machine and its C compiler. So that
207 the builder has better control over the compiler the above option can be used
208 to pass additional options to the compiler while PSIM is being built.
210 Ex: No debug information
212 PSIM can be built with everything inline. Unfortunately, because of
213 all the debugging information generated the C compiler can grow very
214 very large as a result. For GCC, the debug information can be
215 restricted with the `-g0' option. To specify that this option should
216 be include in the CFLAGS when compiling the psim source code use:
218 --enable-sim-cflags=-g0
220 Ex: Additional optimization flags
222 A significant gain in performance can be achieved by tuning the
223 optimization flags passed to the C compiler. For instance on an x86
226 --enable-sim-cflags='-g0 -O2 -fno-strength-reduce -f...'
230 --enable-sim-warnings=<flags>
233 Turn on additional GCC specific checks.
235 Some hosts (NetBSD, Linux, Solaris-2.5) have complete header files
236 that include correct prototypes for all library functions. On such
237 hosts, PSIM can be built with many more than the standard C checks
238 enabled. The option --enable-sim-warnings controls this.
242 With just --enable-sim-warnings, the following -W options are enabled:
243 -Werror -Wall -Wpointer-arith -Wmissing-prototypes.
247 --enable-sim-opcode=which
250 Specify the file containing the rules for generating the instruction
251 decode and execute functions from the file ppc-instructions.
253 The form of the instruction decode and execute functions is controlled
254 by an opcode table. It specifies: the combination of switch
255 statements and jump tables to use when decoding an instruction and how
256 much of each instruction should be decoded before calling the
257 instruction execute function.
259 PSIM includes a number of opcode tables:
262 Generates a small compact two level switch statement
263 that will compile quickly and run reasonably fast.
265 This may be useful on a small machine.
268 (the default) A fairly aggressive instruction decode
269 table that includes the breaking out of a number
270 of special instruction cases (eg RA==0 vs RA!=0).
273 Identical to complex except a switch statement
274 is used. Ideal for when the icache is being
278 In addition to the instruction decodes performed
279 by psim-opcode-complex, this also full decodes mtspr,
280 mfspr, and branch instructions. The table generated
281 is very large and, as a consequence, only performs
282 well on machines with large caches.
286 Generate test (but workable) tables. These exercise
287 PSIM's ability to generate instruction decode functions
288 that are a combination of jump-tables and switch statements.
290 The program igen generates the instruction tables from the opcode
291 table and the ppc-instruction table.
298 Enable/disable the use of a switch statement when looking up the
299 attributes of a SPR register.
301 The PowerPC architecture defines a number of Special Purpose Registers
302 (SPR's). Associated with each of these registers are a number of
303 attributes (such as validity or size) which the instructions
304 mtspr/mfspr query as part of their execution.
306 For PSIM, this information is kept in a table (ppc-spr-table). The
307 program dgen converts this table into lookup routines (contained in
308 the generated files spreg.h spreg.c) that can be used to query an
309 SPR's attributes. Those lookup routines are either implemented as
310 a table or alternatively as a number of switch statements:
312 spr_table spr_info[] = { .... };
313 int spr_length(sprs spr) { return spr_info[spr].length; }
317 int spr_length(sprs spr) { switch (spr) { case ..: return ..; } }
319 In general the first implementation (a table) is the most efficient.
320 It may, however, prove that when performing an aggressive optimization
321 where both the SPR is known and the above function is being inlined
322 (with the consequence that GCC can eliminate the switch statement)
323 that the second choice is improves performance.
325 In practice, only a marginal (if any benefit) has ever been seen.
329 --enable-sim-duplicate
332 Create a duplicate copy of each instruction function hardwiring
333 instruction fields that would have otherwise have been variable.
335 As discussed above, igen outputs a C function generated from the file
336 ppc-instructions (using the opcode rules) for each of the
337 instructions. Thus multiple entries in the instruction decode tables
338 may be pointing back at the same function. Enabling duplicate, will
339 result in psim creating a duplicate of the instruction's function for
340 each different entry in the instruction decode tables.
342 For instance, given the branch instruction:
344 0.19,6.BO,11.BI,16./,21.528,31.LK
346 if (LK) LR = (spreg)IEA(CIA + 4);
349 igen as part of its instruction lookup table may have generated two
350 different entries - one for LK=0 and one for LK=1. With duplicate
351 enabled, igen outputs (almost) duplicate copies of branch function,
352 one with LK hardwired to 0 and one with LK hardwired to 1.
354 By doing this the compiler is provided with additional information that
355 will allow it possibly eliminate dead code. (such as the assignment
360 Because this feature is such a big win, --enable-sim-duplicate is
361 turned on by default.
365 Only rarely (eg on a very small host) would this feature need to be
366 disabled (using: --disable-sim-duplicate).
370 --enable-sim-filter=rule
373 Include/exclude PowerPC instructions that are specific to a particular
376 Some of the PowerPC instructions included in the file ppc-instructions
377 are limited to certain specific PPC implementations. For instance,
380 0.58,6.RT,11.RA,16.DS,30.2:DS:64::Load Word Algebraic
382 Is only valid for the 64bit architecture. The enable-sim-filter flag
383 is passed to igen so that it can `filter out' any invalid
384 instructions. The filter rule has the form:
390 --enable-sim-filter='-f 64'
392 (the default) would filter out all 64bit instructions.
394 Ex: Remove floating point instructions
396 A given 32bit PowerPC implementation may not include floating point
397 hardware. Consequently there is little point in including floating
398 point instructions in the instruction table. The option:
400 --enable-sim-filter='-f 64 -f f'
402 will eliminate all floating point instructions from the instruction
407 --enable-sim-icache=size
410 Set the size of the cache used to hold decoded instructions.
412 Psim executes instructions in two separate steps:
414 o instruction fetch/decode
416 o instruction execution
418 For a given instruction, the first stage need only be executed once
419 (the first time the instruction is encountered) while the second stage
420 must be executed every time the program `executes' that instruction.
422 Exploiting this, PSIM can maintain a cache of decoded instructions.
423 It will then use the decoded instruction from the cache in preference
424 to fetching/decoding the real instruction from memory.
428 Because this feature is normally such a big win, it is enabled by
429 default (with the cache size set to 1024 entries).
431 The 1024 entries equals 4096 bytes (or one page) of instructions.
432 Larger caches can be used but with caution - PSIM does not check for
433 address aliasing within its instruction cache.
435 Ex: disable the cache
437 There may be cases (for instance where the cache has a low hit rate)
438 where the psim performs better with no instruction cache. For such
439 situations, the cache can be disabled vis: --disable-sim-icache.
443 --enable-sim-inline[=module]
446 Specify the inlining of one or more modules.
448 Many architectures (in particular the x86) suffer from a large
449 function call overhead. By eliminating function calls (through
450 inlining of functions) a large performance gain can be achieved.
452 In PSIM, modules are inlined in one of two possible ways. Some
453 modules (such as the byte swapping code) can be inlined into any
454 module that calls them. Other modules, due to complex
455 interdependencies, are only inlined as a group when compiling the
456 external interface module psim.c.
460 By default the modules endian (handle be/le), bits (manipulate
461 bit-fields within words), cpu (the processor object) and events
462 (timers) are inlined in any module that calls them. This gives a
463 reasonable performance gain with little additional compilation
466 Ex: recommended --enable-sim-inline
468 Assuming you machine is reasonably well configured, this option is
469 highly recommended. On the x86 several orders of magnitude
470 improvement in performance is possible.
474 The file std-config.h contains a detailed description of how the
475 inlining works. Individual modules can be inlined by specifying them.
476 For if you have a very large cache the model module could be inlined
479 --enable-sim-inline=MODEL
483 --enable-sim-endian=endian
486 Specify the byte order of the target.
488 By default, PSIM is able to execute both big and little endian
489 executables. As a consequence, every byte swap routine includes a
490 test to see if the byte swap is really needed. By specifying the byte
491 order of the target (and the host below) the need for this test can be
494 Clearly setting the byte order of the target is only useful when known
499 --enable-sim-hostendain=end
502 As above but for the host.
504 Normally this option should not be needed. configure (autoconf) should
505 determine the byte order of the host automatically. However if for
506 some reason there is a problem, this option can be used to override
514 Set the maximum number of processors that PSIM can model.
516 Psim can model (with small limitation discussed else where) a
517 multi-processor PowerPC environment. While the overhead of
518 co-ordinating the execution of a number of processors is relatively
519 small it is still significant when compared to handling only one
522 This option only sets the maximum number of processors that can be
523 simulated. The number active during a given simulation run us
524 determined at run time.
528 By default 5 processors are configured but only one is enabled.
529 Additional processors can be enabled with the runtime option:
531 -o '/openprom/options/smp 5'
535 Unless you intend studying multi-processor systems there is little reason for
536 having PSIM configured with SMP support. Specifying:
539 or --enable-sim-smp=0
541 will eliminate any SMP such as:
543 for (cpu = 0; cpu < nr_cpus; cpu++)
548 --enable-sim-xor-endian=n
551 Set the byte-size of the bus involved in the PowerPC's xor endian byte
554 The PowerPC's implementation of BE/LE mode is different to what a
555 programmer may first expect. The details of this implementation are
556 discussed at length in PowerPC documentation.
560 By default this is configured with a value of 8 (the bus size of most
565 Unless you are expecting to test/debug PowerPC be/le switching code
566 this option is of little use and should be disabled:
568 --disable-sim-xor-endian
572 --enable-sim-bitsize=n
575 Specify the bit size (32/64) of the PowerPC to be modelled.
577 Note: By default 32 is specified. The implementation of the 64bit
578 architecture is still under development.
581 --enable-sim-hostbitsize=32|64
583 As above but for the host.
585 NOTE: Psim has yet to be built on a 64bit host.
592 Hardwire the PowerPC environment being modelled (user, virtual or
595 The PowerPC architecture defines three different levels of compliance to its
596 architectural specification. These environments are discussed in detail in
597 PowerPC publications.
599 user - normal user programs
600 virtual - an extension of the user environment (includes timers)
601 operating - kernel code
605 By default all three environments are supported.
609 If you only intend running psim with user (or operating) code then
610 PSIM should be configured accordingly. For user code, it eliminates:
611 support for timers and events and redundant VM calls.
615 --enable-sim-timebase
618 Enable/disable the time base register.
620 The PowerPC architecture (virtual environment) includes a time base
621 register. Maintaining that register incurs an overhead in
622 performance that can be eliminated by eliminating time-base register
627 Normally this option is not used. Instead --enable-sim-env (above) us
628 used to disable/enable features such as the timebase register.
632 --enable-sim-alignment=align
635 Control the PowerPC's memory access alignment restrictions.
637 The PowerPC in LE mode only allows memory transfers of a correctly
638 aligned size/address. The above option controls how misaligned
639 accesses are handled.
641 strict All accesses must be correctly aligned
643 nonstrict Unaligned access allowed (the are split
644 into a number of aligned accesses).
648 Unless otherwise specified PSIM will auto configure a BE program to
649 allow miss-aligned accesses while a LE program will not.
653 The recently announced 604e processor allows miss-aligned accesses in both
654 BE and LE modes. If modeling the 604e then you should specify:
656 --enable-sim-alignment=nonstrict
663 Include code to trace PSIM's internal progress (also controlled by the
666 Checking to see if a trace message should be output slows down a
667 simulation. Disabling this option (--disable-sim-trace) eliminates
668 completely that code.
675 Include the code that checks the correctness of parts of PSIM.
677 Eliminating such code (--disable-sim-assert) eliminates internal
678 consistency tests and their overhead.
682 --enable-sim-reserved-bits
685 Include code to check that the reserved fields of the instruction are
688 The PowerPC architecture defines certain fields of some instructions
689 as reserved (`/'). By default, for each instruction, PSIM will check
690 the reserved fields causing an invalid instruction exception if a
691 field is invalid. Disabling this option eliminates this test. This
692 is at the slight risk of PSIM treating an invalid instruction as
700 Include support for hardware floating point.
704 --enable-sim-monitor=mon
707 Include support for basic instruction counting.
709 If you are not interested in the performance of either you program or
710 the simulator then you can disable this option.
714 --enable-sim-model=which
716 Hardwire the processor that will be used as a reference when modeling
721 --enable-sim-default-model=which
724 Specify the processor of choice for the execution unit model.
728 --enable-sim-model-issue
731 Include support for the modeling of processor execution units.
733 ----------------------------------------------------------------------
735 TYPICAL CONFIGURATION OPTIONS:
742 o ramp up the compiler options (some
743 of the below are P5 specific).
745 o disable anything not used
748 --prefix=/applications/psim \
749 --target=powerpc-unknown-eabi \
750 --enable-sim-powerpc \
751 --enable-sim-warnings \
752 --enable-sim-inline \
754 --enable-sim-duplicate \
755 --enable-sim-endian=big \
756 --disable-sim-xor-endian \
757 --enable-sim-env=user \
758 --disable-sim-reserved-bits \
759 --disable-sim-assert \
760 --disable-sim-trace \
761 --enable-sim-cflags='-g0,-O2,-fno-strength-reduce,-fomit-frame-pointer'
766 The key configuration changes are:
768 o turn off the instruction cache. The overhead
769 of flushing and reloading it is greater than
772 o use a switch statement (ppc-opcode-flat) for
773 the instruction decode and then (-O3) fully
774 inline all functions.
776 o --enable-sim-warnings is not present. GCC (2.7.2)
777 gets confused by the instruction decode table
778 generated by igen (contains a perfect switch)
779 and, as a consequence, generates a bogus warning.
782 --prefix=/applications/psim \
783 --target=powerpc-unknown-eabi \
784 --enable-sim-powerpc \
785 --enable-sim-inline \
787 --enable-sim-duplicate \
788 --enable-sim-endian=big \
789 --disable-sim-xor-endian \
790 --enable-sim-env=operating \
791 --disable-sim-reserved-bits \
792 --disable-sim-assert \
793 --disable-sim-trace \
794 --enable-sim-opcode=ppc-opcode-flat \
795 --disable-sim-icache \
796 --enable-sim-cflags='-g0,-O3,-fno-strength-reduce,-fomit-frame-pointer'