Subversion Repositories openrisc

This is ../../doc/or1ksim.info, produced by makeinfo version 4.13 from

../../doc/or1ksim.texi.

INFO-DIR-SECTION Embedded development

START-INFO-DIR-ENTRY

* Or1ksim: (or32-uclinux-or1ksim).      The OpenRISC 1000 Architectural

                                        Simulator

END-INFO-DIR-ENTRY

This file documents the OpenRISC Architectural Simulator, Or1ksim.

Copyright (C) 2008, 2009 Embecosm Limited.

     Permission is granted to copy, distribute and/or modify this

     document under the terms of the GNU Free Documentation License,

     Version 1.2 or any later version published by the Free Software

     Foundation; with no Invariant Sections, with no Front-Cover Texts,

     and with no Back-Cover Texts.  A copy of the license is included

     in the section entitled "GNU Free Documentation License".

File: or1ksim.info,  Node: Top,  Next: Installation,  Up: (dir)

Scope of this Document

**********************

This document is the user guide for Or1ksim, the OpenRISC 1000

Architectural Simulator.

* Menu:

* Installation::

* Usage::

* Configuration::

* Interactive Command Line::

* Verification API::

* Code Internals::

* GNU Free Documentation License::  The license for this documentation

* Index::

File: or1ksim.info,  Node: Installation,  Next: Usage,  Prev: Top,  Up: Top

1 Installation

**************

Installation follows standard GNU protocols.

* Menu:

* Preparation::

* Configuring the Build::

* Build and Install::

* Known Issues::

File: or1ksim.info,  Node: Preparation,  Next: Configuring the Build,  Up: Installation

1.1 Preparation

===============

Unpack the software and create a _separate_ directory in which to build

it:

     tar jxf or1ksim-0.3.1-2010-04-21.tar.bz2

     mkdir builddir_or1ksim

     cd builddir_or1ksim

File: or1ksim.info,  Node: Configuring the Build,  Next: Build and Install,  Prev: Preparation,  Up: Installation

1.2 Configuring the Build

=========================

Configure the software using the `configure' script in the main

directory.

The most significant argument is `--target', which should specify the

OpenRISC 1000 32-bit architecture.  If this argument is omitted, it will

default to OpenRISC 1000 32-bit with a warning

     ../or1ksim-0.3.1-2010-04-21/configure --target=or32-uclinux ...

There are several other options available, many of which are standard

to GNU `configure' scripts.  Use `configure --help' to see all the

options.  The most useful is `--prefix' to specify a directory for

installation of the tools.

A number of Or1ksim features in the simulator do require enabling at

configuration.  These include

`--enable-profiling'

`--disable-profiling'

     If enabled, Or1ksim is compiled for profiling with `gprof'.  This

     is disabled by default.  Only really of value for developers of

     Or1ksim.

`--enable-execution=simple'

`--enable-execution=complex'

`--enable-execution=dynamic'

     Or1ksim has developed to improve functionality and performance.

     This feature allows three versions of Or1ksim to be built

    `--enable-execution=simple'

          Build the original simple interpreting simulator

    `--enable-execution=complex'

          Build a more complex interpreting simulator.  Experiments

          suggest this is 50% faster than the simple simulator.  This

          is the default.

    `--enable-execution=dynamic'

          Build a dynamically compiling simulator.  This is the way

          many modern ISS are built.  This represents a work in

          progress.  Currently Or1ksim will compile, but segfaults if

          configured with this option.

     The default is `--enable-execution=complex'.

`--enable-ethphy'

`--disable-ethphy'

     If enabled, this option allows the Ethernet to be simulated by

     connecting via a socket (the alternative reads and writes, from

     and to files).  This must then be configured using the relevant

     fields in the `ethernet' section of the configuration file.  *Note

     Ethernet Configuration: Ethernet Configuration.

     The default is for this to be disabled.

`--enable-range-stats'

`--disable-range-stats'

     If enabled, this option allows statistics to be collected to

     analyse register access over time.  The default is for this to be

     disabled.

`--enable-ov-flag'

`--disable-ov-flag'

     If enabled, this option causes instructions to set the overflow

     flag.  The instructions affected by this are `l.add', `l.addc',

     `l.addi', `l.and', `l.andi', `l.div', `l.divu', `l.mul', `l.muli',

     `l.or', `l.ori', `l.sll', `l.slli', `l.srl', `l.srli', `l.sra',

     `l.srai', `l.sub', `l.xor' and `l.xori'.

     The default is for this to be disabled.

          Caution: This appears a very dangerous option, to the extent

          of arguably being a bug.  Whether or not flags are set is

          part of the OpenRISC 1000 architectural specification.

          Within the above list, the arithmetic instructions (`l.add',

          `l.addc', `l.addi', `l.div', `l.divu', `l.mul', `l.muli' and

          `l.sub'), together with `l.addic' which is missed out, set

          the overflow flag.  All the others (`l.and', `l.andi',

          `l.or', `l.ori', `l.sll', `l.slli', `l.srl', `l.srli',

          `l.sra', `l.srai', `l.xor' and `l.xori') do not.

          Thus it is impossible to get correct behavior whichever way

          this option is set.

`--enable-arith-flag'

`--disable-arith-flag'

     If enabled, this option causes instructions to set the flag (`F'

     bit) in the supervision register.  The instructions affected by

     this are `l.add', `l.addc', `l.addi', `l.and' and `l.andi'.

     The default is for this to be disabled.

          Caution: As with `--enable-ov-flag', this appears another

          very dangerous option, to the extent of arguably being a bug.

          It also appears to be only partially implemented--why only

          the instructions early in the alphabet?

          Whether or not flags are set is part of the OpenRISC 1000

          architectural specification.  The only flags which should set

          this are the "set flag" instructions: `l.sfeq', `l.sfeqi',

          `l.sfges', `l.sfgesi', `l.sfgeu', `l.sfgeui', `l.sfgts',

          `l.sfgtsi', `l.sfgtu', `l.sfgtui', `l.sfles', `l.sflesi',

          `l.sfleu', `l.sfleui', `l.sflts', `l.sfltsi', `l.sfltu',

          `l.sfltui', `l.sfne' and `l.sfnei'.

          The flags are correctly set (irrespective of

          `--enable-arith_flag').

          Correct behavior is thus achieved if this flag is not set.

          `--enable-arith-flag' should never be used.

`--enable-debug'

`--disable-debug'

     This is a feature of the Argtable2 package used to process

     arguments.  If enabled, some debugging features are turned on in

     Argtable2.  It is provided for completeness, but there is no

     reason why this feature should ever be needed by any Or1ksim user.

`--enable-all-tests'

`--disable-all-tests'

     Some of the tests (at the time of writing just one) will not

     compile without error.  If enabled with this flag, all test

     programs will be compiled with `make check'.

     This flag is intended for those working on the test package, who

     wish to get the missing test(s) working.

File: or1ksim.info,  Node: Build and Install,  Next: Known Issues,  Prev: Configuring the Build,  Up: Installation

1.3 Building and Installing

===========================

Build the tool with:

     make all

If you have the OpenRISC tool chain and DejaGNU installed, you can

verify the tool as follows (otherwise omit this step):

     make check

Install the tool with:

     make install

This will install the three variations of the Or1ksim tool,

`or32-uclinux-sim', `or32-uclinux-psim' and `or32-uclinux-mpsim', the

Or1ksim library, `libsim', the header file, `or1ksim.h' and this

documentation in `info' format.

     Note: Testing Or1ksim with `make check' is not yet supported.

The documentation may be created and installed in alternative formats

(PDF, Postscript, DVI, HTML) with for example:

     make pdf

     make install-pdf

File: or1ksim.info,  Node: Known Issues,  Prev: Build and Install,  Up: Installation

1.4 Known Problems and Issues

=============================

The following problems and issues are known about with Or1ksim

0.3.1-2010-04-21.  The OpenRISC tracker may be used to see the current

state of these issues and to raise new problems and feature requests.

It may be found at

`http://www.opencores.org/ptracker.cgi/view/or1k/398'.

   * The Supervision Register Little Endian Enable (LEE) bit is

     ignored.  Or1ksim can be built for either little endian or big

     endian use, but that behavior cannot be changed dynamically.

   * The NPC is a read/write register, but after being written it

     clears the pipeline.  This means that if the processor is stalled,

     the value should subsequently read back as 0, until the processor

     is unstalled and able to refill its pipeline.  By default Or1ksim

     always reports back the value of NPC, even when it has been

     written while stalled.

     There is now an option, `--strict-npc', which will enforce this

     behavior.  At some stage in the future it will become the default

     behavior, but for now it is an option, since its use will break

     GDB.

   * The memory components are given names in the configuration file.

     However there is currently no way for Or1ksim to report that name

     back to the user (for example to identify which memory block

     corresponds to a particular access).

   * Or1ksim allows the processor to be stalled (from the command

     line), even if there is no debugger present.  This seems to be a

     meaningless operation.

   * Or1ksim is not reentrant, so a program cannot instantiate multiple

     instances using the library.  This is clearly a problem when

     considering multi-core applications.  However it stems from the

     original design, and can only be fixed by a complete rewrite.  The

     entire source code uses static global constants liberally!

   * There is no support for floating point instructions currently in

     Or1ksim.  However this is a work in progress and should be

     available in the future.

File: or1ksim.info,  Node: Usage,  Next: Configuration,  Prev: Installation,  Up: Top

2 Usage

*******

* Menu:

* Standalone Simulator::

* Profiling Utility::

* Memory Profiling Utility::

* Simulator Library::

File: or1ksim.info,  Node: Standalone Simulator,  Next: Profiling Utility,  Up: Usage

2.1 Standalone Simulator

========================

The general form the standalone command is:

     or32-uclinux-sim [-vhi] [-f FILE] [--nosrv] [--srv=[N]] [-d STR]

                      [--enable-profile] [--enable-mprofile] [FILE]

Many of the options have both a short and a long form.  For example

`-h' or `--help'.

`-v'

`--version'

     Print out the version and copyright notice for Or1ksim and exit.

`-h'

`--help'

     Print out help about the command line options and what they mean.

`-f FILE'

`--file FILE'

     Read configuration commands from the specified file, looking first

     in the current directory, and otherwise in the `$HOME/.or1k'

     directory.  If this argument is not specified, the file `sim.cfg'

     in those two locations is used.  Failure to find the file is a

     fatal error.  *Note Configuration: Configuration, for detailed

     information on configuring Or1ksim.

`--nosrv'

     Do not start up the debug server.  This overrides any setting

     specified in the configuration file.  This option may not be

     specified with `--srv'.  If it is, a rude message is printed and

     the `--nosrv' option is ignored.

`--srv'

`--srv=N'

     Start up the debug server.  If the parameter, N, is specified, use

     that as the TCP/IP port for the server, otherwise a random value

     from the private port range (41920-65535) will be used.  This

     option may not be specified with `--nosrv'.  If it is, a rude

     message is printed and the `--nosrv' option is ignored.

`-d=CONFIG_STRING'

`--debug-config=CONFIG_STRING'

     Enable selected debug messages in Or1ksim.  This parameter is for

     use by developers only, and is not covered further here.  See the

     source code for more details.

`-i'

`--interactive'

     After starting, drop into the Or1ksim interactive command shell.

`--strict-npc'

     In real hardware, setting the next program counter (NPC, SPR 16),

     flushes the processor pipeline.  The consequence of this is that

     until the pipeline refills, reading the NPC will return zero.

     This is typically the case when debugging, since the processor is

     stalled.

     Historically, Or1ksim has always returned the value of the NPC,

     irrespective of when it is changed.  If the `--strict-npc' option

     is used, then Or1ksim will mirror real hardware more accurately.

     If the NPC is changed while the processor is stalled, subsequent

     reads of its value will return 0 until the processor is unstalled.

     This is not currently the default behavior, since tools such as

     GDB have been implemented assuming the historic Or1ksim behavior.

     However at some time in the future it will become the default.

`--enable-profile'

     Enable instruction profiling.

`--enable-mprofile'

     Enable memory profiling.

File: or1ksim.info,  Node: Profiling Utility,  Next: Memory Profiling Utility,  Prev: Standalone Simulator,  Up: Usage

2.2 Profiling Utility

=====================

This utility analyses instruction profile data generated by Or1ksim.

It may be invoked as a standalone command, or from the Or1ksim CLI.

The general form the standalone command is:

     or32-uclinux-profile [-vhcq] [-g=FILE]

Many of the options have both a short and a long form.  For example

`-h' or `--help'.

`-v'

`--version'

     Print out the version and copyright notice for the Or1ksim

     profiling utility and exit.

`-h'

`--help'

     Print out help about the command line options and what they mean.

`-c'

`--cumulative'

     Show cumulative sum of cycles in functions

`-q'

`--quiet'

     Suppress messages

`-g=FILE'

`--generate=FILE'

     The data file to analyse.  If omitted, the default file,

     `sim.profile' is used.

File: or1ksim.info,  Node: Memory Profiling Utility,  Next: Simulator Library,  Prev: Profiling Utility,  Up: Usage

2.3 Memory Profiling Utility

============================

This utility analyses memory profile data generated by Or1ksim.  It may

be invoked as a standalone command, or from the Or1ksim CLI.  The

general form the standalone command is:

     or32-uclinux-mprofile  [-vh] [-m=M] [-g=N] [-f=FILE] FROM TO

Many of the options have both a short and a long form.  For example

`-h' or `--help'.

`-v'

`--version'

     Print out the version and copyright notice for the Or1ksim memory

     profiling utility and exit.

`-h'

`--help'

     Print out help about the command line options and what they mean.

`-m=M'

`--mode=M'

     Specify the mode out output.  Permitted options are

    `detailed'

    `d'

          Detailed output.  This is the default if no mode is specified.

    `pretty'

    `p'

          Pretty printed output.

    `access'

    `a'

          Memory accesses only.

    `width'

    `w'

          Access width only.

`-g=N'

`--group=N'

     Group 2^n bits of successive addresses together.

`-f=FILE'

`--filename=FILE'

     The data file to analyse.  If not specified, the default,

     `sim.profile' is used.

`FROM'

`TO'

     FROM and TO are respectively the start and end address of the

     region of memory to be analysed.

File: or1ksim.info,  Node: Simulator Library,  Prev: Memory Profiling Utility,  Up: Usage

2.4 Simulator Library

=====================

Or1ksim may be used as a static of dynamic library, `libsim.a' or

`libsim.so'.  When compiling with the static library, the flag, `-lsim'

should be added to the link command.

The header file `or1ksim.h' contains appropriate declarations of the

functions exported by the Or1ksim library.  These are:

 -- `or1ksim.h': int or1ksim_init (const char *CONFIG_FILE, const char

          *IMAGE_FILE, void *CLASS_PTR, unsigned long int (*UPR)(void

          *CLASS_PTR, unsigned long int ADDR, unsigned long int MASK),

          void (*UPW)(void *CLASS_PTR, unsigned long int ADDR, unsigned

          long int MASK, unsigned long int WDATA))

     The initialization function is supplied with the name of a

     configuration file, CONFIG_FILE, an executable image, IMAGE_FILE,

     a pointer to the calling class, CLASS_PTR (since the library may

     be used from C++) and two up-call functions, one for reads, UPR,

     and one for writes, UPW.

     *Note Configuration: Configuration, for detailed information on

     configuring Or1ksim and the format of the configuration file.

     UPW is called for any write to an address external to the model

     (determined by a `generic' section in the configuration file).

     UPR is called for any reads to an external address.  The CLASS_PTR

     is passed back with these upcalls, allowing the function to

     associate the call with the class which originally initialized the

     library.

     MASK indicates which bytes in the word are to be written or read.

     Bytes to be read/written should have 0xff set in MASK.  Otherwise

     the byte should be zero.

     ADDR, MASK, WDATA and the result from UPR all use host-endianess,

     _not_ model-endianess.  The internal Or1ksim routines manage all

     the conversion.

 -- `or1ksim.h': int or1ksim_run (double DURATION)

     Run the simulator for the simulated duration specified (in

     seconds).

 -- `or1ksim.h': void or1ksim_reset_duration (double DURATION)

     Change the duration of a run specified in an earlier call to

     `or1ksim_run'.  Typically this is called from an upcall, which

     realizes it needs to change the duration of the run specified in

     the call to `or1ksim_run' that has been interrupted by the upcall.

     The time specified is the amount of time that the run must continue

     for (i.e the duration from _now_, not the duration from the

     original call to `or1ksim_run').

 -- `or1ksim.h': void or1ksim_set_time_point ()

     Set a timing point.  For use with `or1ksim_get_time_period'.

 -- `or1ksim.h': double or1ksim_get_time_period ()

     Return the simulated time (in seconds) that has elapsed since the

     last call to `or1ksim_set_time_point'.

 -- `or1ksim.h': int or1ksim_is_le ()

     Return 1 (logical true) if the Or1ksim simulation is

     little-endian, 0 otherwise.

 -- `or1ksim.h': unsigned long int or1ksim_clock_rate ()

     Return the Or1ksim clock rate (in Hz).  This is the value

     specified in the configuration file.

 -- `or1ksim.h': void or1ksim_interrupt (int I)

     Generate an edge-triggered interrupt on interrupt line I.  The

     interrupt is then immediately cleared automatically.  A warning

     will be generated and the interrupt request ignored if level

     sensitive interrupts have been configured with the programmable

     interrupt controller (*note Interrupt Configuration: Interrupt

     Configuration.).

 -- `or1ksim.h': void or1ksim_interrupt_set (int I)

     Assert a level-triggered interrupt on interrupt line I.  The

     interrupt must be cleared separately by an explicit call to

     `or1ksim_interrupt_clear'.  A warning will be generated, and the

     interrupt request ignored if edge sensitive interrupts have been

     configured with the programmable interrupt controller (*note

     Interrupt Configuration: Interrupt Configuration.).

 -- `or1ksim.h': void or1ksim_interrupt_clear (int I)

     Clear a level-triggered interrupt on interrupt line I, which was

     previously asserted by a call to `or1ksim_interrupt_set'.  A

     warning will be generated, and the interrupt request ignored if

     edge sensitive interrupts have been configured with the

     programmable interrupt controller (*note Interrupt Configuration:

     Interrupt Configuration.).

The libraries will be installed in the `lib' sub-directory of the main

installation directory (as specified with the `--prefix' option to the

`configure' script).

For example if the main installation directory is `/opt/or1ksim', the

library will be found in the `/opt/or1ksim/lib' directory.  It is

available as both a static library (`libsim.a') and a shared object

(`libsim.so').

To link against the library add the `-lsim' flag when linking and do

one of the following:

   * Add the library directory to the `LD_LIBRARY_PATH' environment

     variable during execution.  For example:

          export LD_LIBRARY_PATH=/opt/or1ksim/lib:$LD_LIBRARY_PATH

   * Add the library directory to the `LD_RUN_PATH' environment

     variable during linking.  For example:

          export LD_RUN_PATH=/opt/or1ksim/lib:$LD_RUN_PATH

   * Use the linker `--rpath' option and specify the library directory

     when linking your program.  For example

          gcc ...  -Wl,--rpath -Wl,/opt/or1ksim/lib ...

   * Add the library directory to `/etc/ld.so.conf'

File: or1ksim.info,  Node: Configuration,  Next: Interactive Command Line,  Prev: Usage,  Up: Top

3 Configuration

***************

Or1ksim is configured through a configuration file.  This is specified

through the `-f' parameter to the Or1ksim command, or passed as a

string when initializing the Or1ksim library.  If no file is specified,

the default `sim.cfg' is used.  The file is looked for first in the

current directory, then in the `$HOME/.or1k' directory of the user.

* Menu:

* Configuration File Format::

* Simulator Configuration::

* Core OpenRISC Configuration::

* Peripheral Configuration::

File: or1ksim.info,  Node: Configuration File Format,  Next: Simulator Configuration,  Up: Configuration

3.1 Configuration File Format

=============================

The configuration file is a plain text file.

* Menu:

* Configuration File Preprocessing::

* Configuration File Syntax::

File: or1ksim.info,  Node: Configuration File Preprocessing,  Next: Configuration File Syntax,  Up: Configuration File Format

3.1.1 Configuration File Preprocessing

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

The configuration file may include C style comments (i.e.  delimited by

`/*' and `*/').

Configure files may be included, using

     include FILENAME_TO_INCLUDE

File: or1ksim.info,  Node: Configuration File Syntax,  Prev: Configuration File Preprocessing,  Up: Configuration File Format

3.1.2 Configuration File Syntax

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

The configuration file is divided into a series of sections, with the

general form:

     section SECTION_NAME

       ...

     end

Sections may also have sub-sections within them (currently only the

ATA/ATAPI disc interface uses this).

Within a section, or sub-section are a series of parameter assignments,

one per line, withe the general form

       PARAMETER = VALUE

Depending on the parameter, the value may be a named value (an

enumeration), an integer (specified in any format acceptable in C) or a

string in doubple quotes.  For flag parameters, the value 1 is used to

mean "true" or "on" and the value "0" to mean "false" or "off".  An

example from a memory section shows each of these

     section memory

       type    = random

       pattern = 0x00

       name    = "FLASH"

       ...

     end

Many parameters are optional and take reasonable default values if not

specified.  However there are some parameters (for example the `ce'

parameter in `section memory') _must_ be specified.

Subsections are introduced by a keyword, with a parameter value (no `='

sign), and end with the same keyword prefixed by `end'.  Thus the

ATA/ATAPI inteface (`section ata') has a `device' subsection, thus:

     section ata

       ...

       device 0

         type    = 1

         file = "FILENAME"

         ...

       enddevice

       ...

     end

Some sections (for example `section sim') should appear only once.

Others (for example `section memory' may appear multiple times.

Sections may be omitted, _unless they contain parameters which are

non-optional_.  If the section describes a part of the simulator which

is optional (for example whether it has a UART), then that

functionality will not be provided.  If the section describes a part of

the simulator which is not optional (for example the CPU), then all the

parameters of that section will take their default values.

All optional parts of the functionality are always described by

sections including a `enabled' parameter, which can be set to 0 to

ensure that functionality is explicitly omitted.

Even if a section is disabled, all its parameters will be read and

stored.  This is helpful if the section is subsequently enabled from

the Or1ksim command line (*note Interactive Command Line: Interactive

Command Line.).

     Tip: It generally clearer to have sections describing _all_

     components, with omitted functionality explicitly indicated by

     setting the `enabled' parameter to 0

The following sections describe the various configuration sections and

the parameters which may be set in each.

File: or1ksim.info,  Node: Simulator Configuration,  Next: Core OpenRISC Configuration,  Prev: Configuration File Format,  Up: Configuration

3.2 Simulator Configuration

===========================

* Menu:

* Simulator Behavior::

* Verification API Configuration::

* CUC Configuration::

File: or1ksim.info,  Node: Simulator Behavior,  Next: Verification API Configuration,  Up: Simulator Configuration

3.2.1 Simulator Behavior

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

Simulator behavior is described in `section sim'.  This section should

appear only once.  The following parameters may be specified.

`verbose = 0|1'

     If 1 (true), print extra messages.  Default 0.

`debug = 0-9'

     higher the value the greater the number of messages.  Default 0.

     Negative values will be treated as 0 (with a warning).  Values

     that are too large will be treated as 9 (with a warning).

`profile = 0|1'

     If 1 (true) generate a profiling file using the file specified in

     the `prof_file' parameter or otherwise `sim.profile'.  Default 0.

`prof_file = ``FILENAME'''

     Specifies the file to be used with the `profile' parameter.

     Default `sim.profile'.  For backwards compatibility, the

     alternative name `prof_fn' is supported for this parameter, but

     deprecated.

`mprofile = 0|1'

     If 1 (true) generate a memory profiling file using the file

     specified in the `mprof_file' parameter or otherwise

     `sim.mprofile'.  Default 0.

`mprof_fn = ``FILENAME'''

     Specifies the file to be used with the `mprofile' parameter.

     Default `sim.mprofile'.  For backwards compatibility, the

     alternative name `mprof_fn' is supported for this parameter, but

     deprecated.

`history = 0|1'

     If 1 (true) track execution flow.  Default 0.

          Note: Setting this parameter seriously degrades performance.

          Note: If this execution flow tracking is enabled, then

          `dependstats' must be enabled in the CPU configuration

          section (*note CPU Configuration: CPU Configuration.).

`exe_log = 0|1'

     If 1 (true), generate an execution log.  Log is written to the

     file specified in parameter `exe_log_file'.  Default 0.

          Note: Setting this parameter seriously degrades performance.

`exe_log_type = default|hardware|simple|software'

     Type of execution log to produce.

    `default'

          Produce default output for the execution log.  In the current

          implementation this is the equivalent of `hardware'.

    `hardware'

          After each instruction execution, log the number of

          instructions executed so far, the next instruction to execute

          (in hex), the general purpose registers (GPRs), status

          register, exception program counter, exception, effective

          address register and exception status register.

    `simple'

          After each instruction execution, log the number of

          instructions executed so far and the next instruction to

          execute, symbolically disassembled.

    `software'

          After each instruction execution, log the number of

          instructions executed so far and the next instruction to

          execute, symbolically disassembled.  Also show the value of

          each operand to the instruction.

     Default value `hardware'.  Any unrecognized keyword (case

     insensitive) will be treated as the default with a warning.

          Note: Execution logs can be _very_ big.

`exe_log_start = VALUE'

     Address of the first instruction to start logging.  Default 0.

`exe_log_end = VALUE'

     Address of the last instruction to log.  Default no limit (i.e

     once started logging will continue until the simulator exits).

`exe_log_marker = VALUE'

     Specifies the number of instructions between printing horizontal

     markers.  Default is to produce no markers.

`exe_log_file = FILENAME'

     Filename for the execution log filename if `exe_log' is enabled.

     Default `executed.log'.  For backwards compatibility, the

     alternative name `exe_log_fn' is supported for this parameter, but

     deprecated.

`clkcycle = VALUE[ps|ns|us|ms]'

     Specify the time taken by one clock cycle.  If no units are

     specified, `ps' is assumed.  Default 4000ps (250MHz).

File: or1ksim.info,  Node: Verification API Configuration,  Next: CUC Configuration,  Prev: Simulator Behavior,  Up: Simulator Configuration

3.2.2 Verification API (VAPI) Configuration

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

The Verification API (VAPI) provides a TCP/IP interface to allow

components of the simulation to be controlled externally.  *Note

Verification API: Verification API, for more details.

Verification API configuration is described in `section vapi'.  This

section may appear at most once.  The following parameters may be

specified.

`enabled = 0|1'

     If 1 (true), verification API is enabled and its server started.

     If 0 (the default), it is disabled.

`server_port = VALUE'

     When VAPI is enabled, communication will be via TCP/IP on the port

     specified by VALUE.  The value must lie in the range 1 to 65535.

     The default value is 50000.

          Tip: There is no registered port for Or1ksim VAPI.  Good

          practice suggests users should adopt port values in the

          "Dynamic" or "Private" port range, i.e.  49152-65535.

`log_enabled = 0|1'

     If 1 (true), all VAPI requests and sent commands will be logged.

     If 0 (the default), logging is diabled.  Logs are written to the

     file specified by the `vapi_log_file' field (see below).

          Caution: This can generate a substantial amount of file I/O

          and seriously degrade simulator performance.

`hide_device_id = 0|1'

     If 1 (true) don't log the device ID.  If 0 (the default), log the

     device ID.  This feature (when set to 1) is provided for backwards

     compatibility with an old version of VAPI.

`vapi_log_file = "FILENAME"'

     Use `filename' as the file for logged data is logging is enabled

     (see `log_enabled' above).  The default is `"vapi.log"'.  For

     backwards compatibility, the alternative name `vapi_log_fn' is

     supported for this parameter, but deprecated.

File: or1ksim.info,  Node: CUC Configuration,  Prev: Verification API Configuration,  Up: Simulator Configuration

3.2.3 Custom Unit Compiler (CUC) Configuration

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

The Custom Unit Compiler (CUC) was a project by Marko Mlinar to generate

Verilog from ANSI C functions.  The project seems to not have progressed

beyond the initial prototype phase.  The configuration parameters are