diff options
Diffstat (limited to 'sim/ppc/INSTALL')
| -rw-r--r-- | sim/ppc/INSTALL | 812 |
1 files changed, 0 insertions, 812 deletions
diff --git a/sim/ppc/INSTALL b/sim/ppc/INSTALL deleted file mode 100644 index da288f1629d..00000000000 --- a/sim/ppc/INSTALL +++ /dev/null @@ -1,812 +0,0 @@ - - PSIM - model the PowerPC environment - - Copyright (C) 1994-1996, Andrew Cagney <cagney@highland.com.au>. - - ---------------------------------------------------------------------- - - - Building PSIM - - This file describes how to build the program PSIM - - o Walk through a basic build - - o Discussion of PSIM's components and - how they relate to the build process - - o Detailed description of each of PSIM's - compile time configuration options - - - ---------------------------------------------------------------------- - - -BUILDING PSIM: - -PSIM 1.0.2 is included in GDB-4.16. To build PSIM you will need the -following: - - gdb-4.16.tar.gz Available from your favorite GNU - ftp site - - gcc GCC version two includes suport - for long long (64bit integer) - arrithemetic which PSIM uses. Hence - it is recommended that you build PSIM - using GCC. - -Method: - - 1. Unpack gdb - - $ cd .../scratch - $ gunzip < gdb-4.16.tar.gz | tar xf - - - - 2. Configure gdb - - First consult the gdb documentation - - $ cd .../scratch - $ cd gdb-4.16 - $ more README - $ more gdb/README - - then something like (I assume SH): - - $ CC=gcc ./configure \ - --enable-sim-powerpc \ - --target=powerpc-unknown-eabi \ - --prefix=/applications/psim - - - 4. Build (again specifying GCC) - - $ make CC=gcc - - alternatively, if you are short on disk space or only - want to build the simulator: - - $ ( 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 - - - ---------------------------------------------------------------------- - - -UPDATING PSIM: - - -A PSIM is an ongoing development. Occasional snapshots which both contain new -features and fix old bugs are made available. See the ftp directory: - - ftp://ftp.ci.com.au/pub/psim/beta -or ftp://cambridge.cygnus.com/pub/psim/beta - -for the latest version. To build/install one of these snapshots, you -replace the sim/ppc found in the gdb archive with with one from the -snapshot. Then just re-configure and rebuild/install. - - Procedure: - - 0. A starting point - - $ cd gdb-4.16 - - - 1. Remove the old psim directory - - $ mv sim/ppc sim/old.ppc - - - 2. Unpack the new one - - $ gunzip < ../psim-NNNNNN.tar.gz | tar tf - - $ gunzip < ../psim-NNNNNN.tar.gz | tar tf - - - - 3. Reconfigure/rebuild (as seen above): - - $ CC=gcc ./configure \ - --enable-sim-powerpc \ - --target=powerpc-unknown-eabi \ - --prefix=/applications/psim - $ make CC=gcc - - - ---------------------------------------------------------------------- - - -UPDATES TO GDB: - -From time to time, problems involving the integration of PSIM into gdb -are found. While eventually each of these problems is resolved there -can be periouds during which a local hack may be needed. - -At the time of writing the following were outstanding: - - ATTACH command: - - ftp://ftp.ci.com.au/pub/psim/gdb-4.15+attach.diff.gz - or ftp://cambridge.cygnus.com/pub/psim/gdb-4.15+attach.diff.gz - - PSIM, unlike the other simulators found in GDB, is able to load - the description of a target machine (including the initial - state of all processor registers) from a file. - - Unfortunatly GDB does not yet have a standard command that - facilitates the use of this feature. Until such a command is - added, the patch (hack?) gdb-4.15+attach.diff.gz can be used to - extend GDB's attach command so that it can be used to initialize - the simulators configuration from a file. - - - - ---------------------------------------------------------------------- - - -RUNNING PROGRAMS: - - -See the file: - - ftp://ftp.ci.com.au/pub/psim/RUN -or ftp://cambridge.cygnus.com/pub/psim/RUN - - - ---------------------------------------------------------------------- - - -COMPILE TIME CONFIGURATION OPTIONS: - - -PSIM's compile time configuration is controlled by autoconf. PSIM's -configure script recognises options of the form: - - --enable-sim-<option>[=<val>] - -And can be specified on the configure command line (at the top level -of the gdb directory tree) vis: - - $ cd gdb-4.15 - $ CC=gcc ./configure \ - --target=powerpc-unknown-eabisim \ - --prefix=/applications/psim \ - --enable-sim-inline - $ make CC=gcc - -For a brief list of PSIM's configuration options, configure --help -will list them vis: - - $ cd sim/ppc - $ ./configure --help - -Each PSIM specific option is discussed in detail below. - - - ---enable-sim-cflags=<opts> - - -Specify additional C compiler flags that are to be used when compiling -just PSIM. - -PSIM places heavy demands on both the host machine and its C compiler. So that -the builder has better control over the compiler the above option can be used -to pass additional options to the compiler while PSIM is being built. - -Ex: No debug information - -PSIM can be built with everything inline. Unfortunately, because of -all the debugging information generated the C compiler can grow very -very large as a result. For GCC, the debug information can be -restricted with the `-g0' option. To specify that this option should -be include in the CFLAGS when compiling the psim source code use: - - --enable-sim-cflags=-g0 - -Ex: Additional optimization flags - -A significant gain in performance can be achieved by tuning the -optimization flags passed to the C compiler. For instance on an x86 -you may consider: - - --enable-sim-cflags='-g0 -O2 -fno-strength-reduce -f...' - - - ---enable-sim-warnings=<flags> - - -Turn on additional GCC specific checks. - -Some hosts (NetBSD, Linux, Solaris-2.5) have complete header files -that include correct prototypes for all library functions. On such -hosts, PSIM can be built with many more than the standard C checks -enabled. The option --enable-sim-warnings controls this. - -Ex: Default warnings - -With just --enable-sim-warnings, the following -W options are enabled: --Werror -Wall -Wpointer-arith -Wmissing-prototypes. - - - ---enable-sim-opcode=which - - -Specify the file containing the rules for generating the instruction -decode and execute functions from the file ppc-instructions. - -The form of the instruction decode and execute functions is controlled -by an opcode table. It specifies: the combination of switch -statements and jump tables to use when decoding an instruction and how -much of each instruction should be decoded before calling the -instruction execute function. - -PSIM includes a number of opcode tables: - - psim-opcode-simple - Generates a small compact two level switch statement - that will compile quickly and run reasonably fast. - - This may be useful on a small machine. - - psim-opcode-complex - (the default) A fairly aggressive instruction decode - table that includes the breaking out of a number - of special instruction cases (eg RA==0 vs RA!=0). - - psim-opcode-flat - Identical to complex except a switch statement - is used. Ideal for when the icache is being - disabled. - - psim-opcode-stupid - In addition to the instruction decodes performed - by psim-opcode-complex, this also full decodes mtspr, - mfspr, and branch instructions. The table generated - is very large and, as a consequence, only performs - well on machines with large caches. - - ppc-opcode-test-1 - ppc-opcode-test-2 - Generate test (but workable) tables. These exercise - PSIM's ability to generate instruction decode functions - that are a combination of jump-tables and switch statements. - -The program igen generates the instruction tables from the opcode -table and the ppc-instruction table. - - - ---enable-sim-switch - - -Enable/disable the use of a switch statement when looking up the -attributes of a SPR register. - -The PowerPC architecture defines a number of Special Purpose Registers -(SPR's). Associated with each of these registers are a number of -attributes (such as validity or size) which the instructions -mtspr/mfspr query as part of their execution. - -For PSIM, this information is kept in a table (ppc-spr-table). The -program dgen converts this table into lookup routines (contained in -the generated files spreg.h spreg.c) that can be used to query an -SPR's attributes. Those lookup routines are either implemented as -a table or alternatively as a number of switch statements: - - spr_table spr_info[] = { .... }; - int spr_length(sprs spr) { return spr_info[spr].length; } - -vs - - int spr_length(sprs spr) { switch (spr) { case ..: return ..; } } - -In general the first implementation (a table) is the most efficient. -It may, however, prove that when performing an aggressive optimization -where both the SPR is known and the above function is being inlined -(with the consequence that GCC can eliminate the switch statement) -that the second choice is improves performance. - -In practice, only a marginal (if any benefit) has ever been seen. - - - ---enable-sim-duplicate - - -Create a duplicate copy of each instruction function hardwiring -instruction fields that would have otherwise have been variable. - -As discussed above, igen outputs a C function generated from the file -ppc-instructions (using the opcode rules) for each of the -instructions. Thus multiple entries in the instruction decode tables -may be pointing back at the same function. Enabling duplicate, will -result in psim creating a duplicate of the instruction's function for -each different entry in the instruction decode tables. - -For instance, given the branch instruction: - - 0.19,6.BO,11.BI,16./,21.528,31.LK - ... - if (LK) LR = (spreg)IEA(CIA + 4); - ... - -igen as part of its instruction lookup table may have generated two -different entries - one for LK=0 and one for LK=1. With duplicate -enabled, igen outputs (almost) duplicate copies of branch function, -one with LK hardwired to 0 and one with LK hardwired to 1. - -By doing this the compiler is provided with additional information that -will allow it possibly eliminate dead code. (such as the assignment -to LK if LR==0). - -Ex: default - -Because this feature is such a big win, --enable-sim-duplicate is -turned on by default. - -Ex: A small machine - -Only rarely (eg on a very small host) would this feature need to be -disabled (using: --disable-sim-duplicate). - - - ---enable-sim-filter=rule - - -Include/exclude PowerPC instructions that are specific to a particular -implementation. - -Some of the PowerPC instructions included in the file ppc-instructions -are limited to certain specific PPC implementations. For instance, -the instruction: - - 0.58,6.RT,11.RA,16.DS,30.2:DS:64::Load Word Algebraic - -Is only valid for the 64bit architecture. The enable-sim-filter flag -is passed to igen so that it can `filter out' any invalid -instructions. The filter rule has the form: - - -f <name> - -thus: - - --enable-sim-filter='-f 64' - -(the default) would filter out all 64bit instructions. - -Ex: Remove floating point instructions - -A given 32bit PowerPC implementation may not include floating point -hardware. Consequently there is little point in including floating -point instructions in the instruction table. The option: - - --enable-sim-filter='-f 64 -f f' - -will eliminate all floating point instructions from the instruction -table. - - - ---enable-sim-icache=size - - -Set the size of the cache used to hold decoded instructions. - -Psim executes instructions in two separate steps: - - o instruction fetch/decode - - o instruction execution - -For a given instruction, the first stage need only be executed once -(the first time the instruction is encountered) while the second stage -must be executed every time the program `executes' that instruction. - -Exploiting this, PSIM can maintain a cache of decoded instructions. -It will then use the decoded instruction from the cache in preference -to fetching/decoding the real instruction from memory. - -Ex: default - -Because this feature is normally such a big win, it is enabled by -default (with the cache size set to 1024 entries). - -The 1024 entries equals 4096 bytes (or one page) of instructions. -Larger caches can be used but with caution - PSIM does not check for -address aliasing within its instruction cache. - -Ex: disable the cache - -There may be cases (for instance where the cache has a low hit rate) -where the psim performs better with no instruction cache. For such -situations, the cache can be disabled vis: --disable-sim-icache. - - - ---enable-sim-inline[=module] - - -Specify the inlining of one or more modules. - -Many architectures (in particular the x86) suffer from a large -function call overhead. By eliminating function calls (through -inlining of functions) a large performance gain can be achieved. - -In PSIM, modules are inlined in one of two possible ways. Some -modules (such as the byte swapping code) can be inlined into any -module that calls them. Other modules, due to complex -interdependencies, are only inlined as a group when compiling the -external interface module psim.c. - -Ex: default - -By default the modules endian (handle be/le), bits (manipulate -bit-fields within words), cpu (the processor object) and events -(timers) are inlined in any module that calls them. This gives a -reasonable performance gain with little additional compilation -overhead. - -Ex: recommended --enable-sim-inline - -Assuming you machine is reasonably well configured, this option is -highly recommended. On the x86 several orders of magnitude -improvement in performance is possible. - -Ex: fine tuning - -The file std-config.h contains a detailed description of how the -inlining works. Individual modules can be inlined by specifying them. -For if you have a very large cache the model module could be inlined -with: - - --enable-sim-inline=MODEL - - - ---enable-sim-bswap - - -(x86 specific) Use the i486/P5/P6 byte swap instruction. - -PSIM contains generic byte swapping code. For the x86 (P[4-6]) PSIM -can be built so that it uses the bswap instruction instead of relying -on the compiler to generate byte swap code. - -Ex: default - -By default, when compiling with GCC-2 on an i486/P5/P6 the bswap -instruction is used. - - - ---enable-sim-endian=endian - - -Specify the byte order of the target. - -By default, PSIM is able to execute both big and little endian -executables. As a consequence, every byte swap routine includes a -test to see if the byte swap is really needed. By specifying the byte -order of the target (and the host below) the need for this test can be -eliminated. - -Clearly setting the byte order of the target is only useful when known -before hand. - - - ---enable-sim-hostendain=end - - -As above but for the host. - -Normally this option should not be needed. configure (autoconf) should -determine the byte order of the host automatically. However if for -some reason there is a problem, this option can be used to override -autoconf. - - - ---enable-sim-smp=n - - -Set the maximum number of processors that PSIM can model. - -Psim can model (with small limitation discussed else where) a -multi-processor PowerPC environment. While the overhead of -co-ordinating the execution of a number of processors is relatively -small it is still significant when compared to handling only one -processor. - -This option only sets the maximum number of processors that can be -simulated. The number active during a given simulation run us -determined at run time. - -Ex: default - -By default 5 processors are configured but only one is enabled. -Additional processors can be enabled with the runtime option: - - -o '/openprom/options/smp 5' - -Ex: recommended - -Unless you intend studying multi-processor systems there is little reason for -having PSIM configured with SMP support. Specifying: - - --disable-sim-smp -or --enable-sim-smp=0 - -will eliminate any SMP such as: - - for (cpu = 0; cpu < nr_cpus; cpu++) - ... - - - ---enable-sim-xor-endian=n - - -Set the byte-size of the bus involved in the PowerPC's xor endian byte -swapping. - -The PowerPC's implementation of BE/LE mode is different to what a -programmer may first expect. The details of this implementation are -discussed at length in PowerPC documentation. - -Ex: default - -By default this is configured with a value of 8 (the bus size of most -60x processors). - -Ex: recommended - -Unless you are expecting to test/debug PowerPC be/le switching code -this option is of little use and should be disabled: - - --disable-sim-xor-endian - - - ---enable-sim-bitsize=n - - -Specify the bit size (32/64) of the PowerPC to be modelled. - -Note: By default 32 is specified. The implementation of the 64bit -architecture is still under development. - - ---enable-sim-hostbitsize=32|64 - -As above but for the host. - -NOTE: Psim has yet to be built on a 64bit host. - - - ---enable-sim-env=env - - -Hardwire the PowerPC environment being modelled (user, virtual or -operating). - -The PowerPC architecture defines three different levels of compliance to its -architectural specification. These environments are discussed in detail in -PowerPC publications. - - user - normal user programs - virtual - an extension of the user environment (includes timers) - operating - kernel code - -Ex: default - -By default all three environments are supported. - -Ex: recommended - -If you only intend running psim with user (or operating) code then -PSIM should be configured accordingly. For user code, it eliminates: -support for timers and events and redundant VM calls. - - - ---enable-sim-timebase - - -Enable/disable the time base register. - -The PowerPC architecture (virtual environment) includes a time base -register. Maintaining that register incurs an overhead in -performance that can be eliminated by eliminating time-base register -support. - -Ex: default - -Normally this option is not used. Instead --enable-sim-env (above) us -used to disable/enable features such as the timebase register. - - - ---enable-sim-alignment=align - - -Control the PowerPC's memory access alignment restrictions. - -The PowerPC in LE mode only allows memory transfers of a correctly -aligned size/address. The above option controls how misaligned -accesses are handled. - - strict All accesses must be correctly aligned - - nonstrict Unaligned access allowed (the are split - into a number of aligned accesses). - -Ex: default - -Unless otherwise specified PSIM will auto configure a BE program to -allow miss-aligned accesses while a LE program will not. - -Ex: 604e - -The recently announced 604e processor allows miss-aligned accesses in both -BE and LE modes. If modeling the 604e then you should specify: - - --enable-sim-alignment=nonstrict - - - ---enable-sim-trace - - -Include code to trace PSIM's internal progress (also controlled by the --t option). - -Checking to see if a trace message should be output slows down a -simulation. Disabling this option (--disable-sim-trace) eliminates -completely that code. - - - ---enable-sim-assert - - -Include the code that checks the correctness of parts of PSIM. - -Eliminating such code (--disable-sim-assert) eliminates internal -consistency tests and their overhead. - - - ---enable-sim-reserved-bits - - -Include code to check that the reserved fields of the instruction are -zero. - -The PowerPC architecture defines certain fields of some instructions -as reserved (`/'). By default, for each instruction, PSIM will check -the reserved fields causing an invalid instruction exception if a -field is invalid. Disabling this option eliminates this test. This -is at the slight risk of PSIM treating an invalid instruction as -valid. - - - ---enable-sim-float - - -Include support for hardware floating point. - - - ---enable-sim-monitor=mon - - -Include support for basic instruction counting. - -If you are not interested in the performance of either you program or -the simulator then you can disable this option. - - - ---enable-sim-model=which - -Hardwire the processor that will be used as a reference when modeling -execution units. - - - ---enable-sim-default-model=which - - -Specify the processor of choice for the execution unit model. - - - ---enable-sim-model-issue - - -Include support for the modeling of processor execution units. - - ---------------------------------------------------------------------- - -TYPICAL CONFIGURATION OPTIONS: - - - VEA CODE ONLY: - - Here of note are: - - o ramp up the compiler options (some - of the below are P5 specific). - - o disable anything not used - - CC=gcc ./configure \ - --prefix=/applications/psim \ - --target=powerpc-unknown-eabi \ - --enable-sim-powerpc \ - --enable-sim-warnings \ - --enable-sim-inline \ - --disable-sim-smp \ - --enable-sim-duplicate \ - --enable-sim-endian=big \ - --disable-sim-xor-endian \ - --enable-sim-env=user \ - --disable-sim-reserved-bits \ - --disable-sim-assert \ - --disable-sim-trace \ - --enable-sim-cflags='-g0,-O2,-fno-strength-reduce,-fomit-frame-pointer' - - - OEA CODE ONLY: - - The key configuration changes are: - - o turn off the instruction cache. The overhead - of flushing and reloading it is greater than - not having a cache. - - o use a switch statement (ppc-opcode-flat) for - the instruction decode and then (-O3) fully - inline all functions. - - o --enable-sim-warnings is not present. GCC (2.7.2) - gets confused by the instruction decode table - generated by igen (contains a perfect switch) - and, as a consequence, generates a bogus warning. - - CC=gcc ./configure \ - --prefix=/applications/psim \ - --target=powerpc-unknown-eabi \ - --enable-sim-powerpc \ - --enable-sim-inline \ - --disable-sim-smp \ - --enable-sim-duplicate \ - --enable-sim-endian=big \ - --disable-sim-xor-endian \ - --enable-sim-env=operating \ - --disable-sim-reserved-bits \ - --disable-sim-assert \ - --disable-sim-trace \ - --enable-sim-opcode=ppc-opcode-flat \ - --disable-sim-icache \ - --enable-sim-cflags='-g0,-O3,-fno-strength-reduce,-fomit-frame-pointer' |