--- /dev/null
+
+ 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-bswap \
+ --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 -malign-loops=2 -malign-jumps=2 -malign-functions=2'
+
+
+ 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-bswap \
+ --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 -malign-loops=2 -malign-jumps=2 -malign-functions=2'
projects / external / binutils.git / commitdiff