Subversion Repositories scarts

                PSIM - model the PowerPC environment

    Copyright (C) 1994-1996, Andrew Cagney .

    ----------------------------------------------------------------------

                        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-[=]

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=

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=

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 

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'