Go to the first, previous, next, last section; table of contents; home; full screen; PSIM.

Configuration Options

FIXME - Something here introducing the options including how to specify them.

--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).
default
Unless otherwise specified PSIM will auto configure a BE program to allow miss-aligned accesses while a LE program will not.
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-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-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-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.

Default
By default, when compiling with GCC-2 on an i486/P5/P6 the bswap instruction is used.

--enable-sim-cflags=<opts>

Specify additional C compiler flags that are to be used when compiling the simulator directory (sim/ppc).

PSIM places heavy demands on both the host machine and its C compiler. So that the builder has better control over the compilation process the above can be used to specify additional compilation options that will be used when compiling the simulation directory.

Limit debugging 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
Specify 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'

--enable-sim-config=<file>

Override default config file.

--enable-sim-default-model=which

Specify the processor of choice for the execution unit model.

--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).

Default
Because this feature is such a big win, --enable-sim-duplicate is turned on by default.
A small machine
Only rarely (eg on a very small host) would this feature need to be disabled (using: --disable-sim-duplicate).

--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-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
default
By default all three environments are supported.
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-filter=rule

Include 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 determine which of the optional instructions should be included in the simulator:

The filter rule has the form: 

        <class> { , <class> }

for instance: 

	--enable-sim-filter=32,f,o'

which is the default will include:

But would exclude any instruction such as Load Word Algebraic that is limited to 64 bit PowerPC implementations.

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-float

Include support for hardware floating point.

--enable-sim-hardware=<list>

Specify the devices that are to be included in the simulator.

--enable-sim-hostbitsize=32|64

As above but for the host.

Psim has not been built on a 64bit host.

--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-icache=icache-options

Configure the instruction cache that is used to store decoded fields from instructions.

PSIM executes instructions in two separate steps:

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.

Valid icache options include: SIZE - an integer specifying the number of direct mapped entries to use in the icache; define - use #define's to refer to members of an icache entry; semantic - in addition to decoding an instruction, the icache should include each instructions semantic code.

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.
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.

The 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.
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.
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-jump

Experemental.

Instead of creating several functions each containing a single part of the simulator instead create a single monolythic function that contains everything. Control is transfered using goto's and GCC's indirect jump instead of function calls.

--enable-sim-line-nr

Include line references in the generated files so that when debugging the orignal source code instead of the generated code is displayed.

--enable-sim-model=which

Hardwire the processor that will be used as a reference when modeling execution units.

--enable-sim-model-issue

Include support for the modeling of processor execution units.

--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-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:

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.
complex
This is 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).
flat
Identical to complex except a switch statement instead of a table is used. Ideal for when the icache is being disabled.
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.
test-1
@xitem 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.
goto
Experimental. Generate a single function that uses goto's instead of call/return when transfering control between code emulating specific instructions.

The program igen generates the instruction tables from the opcode table and the ppc-instruction table.

Igen is described separatly.

--enable-sim-packages=<list>

Specify the packages that are to be included with the simulator.

--enable-sim-warnings=<flags>

Pass parameters in registers instead of on the stack - x86/GCC specific.

--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-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.

Default
By default 5 processors are configured but only one is enabled. Additional processors can be enabled with the runtime option: 
	-n 5
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-stdcall=<type>

Use an alternative function call/return mechanism - x86/GCC specific.

--enable-sim-warnings=<flags>

Specify whether to use stdio for console input/output.

--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' and `spreg.c') that can be used to query an SPR's attributes. Those lookup routines are either implemented as a table or as a number of switch statements: 

	spr_table spr_info[] = { .... };
	int spr_length(sprs spr) { return spr_info[spr].length; }

or 

	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-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.

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-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-warnings=<flags>

Enable additional GCC specific compiler warnings.

Many hosts (ex NetBSD, Linux, Solaris) are shipped with 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.

Default warnings
With just --enable-sim-warnings, the following -W options are enabled:

--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.

This option is independant of --enable-sim-endian.

Default
By default this is configured with a value of 8 (the bus size of most 60x processors).
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
Go to the first, previous, next, last section; table of contents; home; full screen.