     [file version.texi not included]
     [file config.texi not included]

This file documents the OpenRISC Architectural Simulator, OR1KSIM.

Copyright © 2008 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''.

Scope of this Document
**********************

This document is the user guide for OR1KSIM, the OpenRISC 1000 Architectural Simulator.

Installation
************

Installation follows standard GNU protocols.

Preparation
===========

Unpack the software and create a separate directory in which to build it:

     tar jxf or1ksim-VERSION.tar.bz2
     mkdir builddir_or1ksim
     cd builddir_or1ksim

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-VERSION/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. See 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.

          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.

          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.

Building and Installing
=======================

The tool is then built with:

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

     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

Usage
*****

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

--enable-profile
     Enable instruction profiling.

--enable-mprofile
     Enable memory profiling.

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.

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.

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.

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

 -- 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 interrupt on interrupt line I.

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

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.

Configuration File Format
=========================

The configuration file is a plain text file.

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

Configuration File Syntax
-------------------------

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

     section SECTION_NAME

       <contents>...

     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 (see Interactive Command Line).

     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.

Simulator Configuration
=======================

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
     0 means no debug messages. 1-9 means produce debug messages. The 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.

          Setting this parameter seriously degrades performance.

          If this execution flow tracking is enabled, then dependstats must be enabled in the CPU configuration section (see 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.

          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.

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

Verification API (VAPI) Configuration
-------------------------------------

The Verification API (VAPI) provides a TCP/IP interface to allow components of the simulation to be controlled externally. See 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.

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

          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.

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 described here for the record.

CUC configuration is described in section cuc. This section may appear at most once. The following parameters may be specified.

memory_order = none|weak|strong|exact
     This parameter specifies the memory ordering required:

     memory_order=none
          Different memory ordering, even if there are dependencies. Bursts can be made, width can change.

          Different memory ordering, even if there are dependencies. If dependencies cannot occur, then bursts can be made, width can change.

          Same memory ordering. Bursts can be made, width can change.

          Exactly the same memory ordering and widths.

     The default value is memory_order=exact. Invalid memory orderings are ignored with a warning.

calling_convention = 0|1
     If 1 (true), programs follow OpenRISC calling conventions. If 0 (the default), they may use other convenitions.

enable_bursts = 0 | 1
     If 1 (true), bursts are detected. If 0 (the default), bursts are not detected.

no_multicycle = 0 | 1
     If 1 (true), no multicycle logic paths will be generated. If 0 (the default), multicycle logic paths will be generated.

timings_file = "FILENAME"
     FILENAME specifies a file containing timing information. The default value is "virtex.tim". For backwards compatibility, the alternative name timings_fn is supported for this parameter, but deprecated.

Configuring the OpenRISC Architectural Components
=================================================

CPU Configuration
-----------------

CPU configuration is described in section cpu. This section should appear only once. At present Or1ksim does not model multi-CPU systems. The following parameters may be specified.

ver = VALUE

cfg = VALUE

rev = VALUE
     The values are used to form the corresponding fields in the VR Special Purpose Register (SPR 0). Default values 0. A warning is given and the value truncated if it is too large (8 bits for ver and cfg, 6 bits for rev).

upr = VALUE
     Used as the value of the Unit Present Register (UPR) Special Purpose Register (SPR 1) to VALUE. Default value is 0x0000075f, i.e.

       * UPR present (0x00000001)

       * Data cache present (0x00000002)

       * Instruction cache present (0x00000004)

       * Data MMY present (0x00000008)

       * Instruction MMU present (0x00000010)

       * Debug unit present (0x00000040)

       * Power management unit present (0x00000100)

       * Programmable interrupt controller present (0x00000200)

       * Tick timer present (0x00000400)

     However, with the exection of the UPR present (0x00000001) and tick timer present, the various fields will be modified with the values specified in their corresponding configuration sections.

cfgr = VALUE
     Sets the CPU configuration register (Special Purpose Register 2) to VALUE. Default value is 0x00000020, i.e. support for the ORBIS32 instruction set. Attempts to set any other value are accepted, but issue a warning that there is no support for the instruction set.

sr = VALUE
     Sets the supervision register Special Purpose Register (SPR 0x11) to VALUE. Default value is 0x00008001, i.e. start in supervision mode (0x00000001) and set the ``Fixed One'' bit (0x00008000).

superscalar = 0|1
     If 1, the processor operates in superscalar mode. Default value is 0.

     In the current simulator, the only functional effect of superscalar mode is to affect the calculation of the number of cycles taken to execute an instruction.

          The code for this does not appear to be complete or well tested, so users are advised not to use this option.

hazards = 0|1
     If 1, data hazards are tracked in a superscalar CPU. Default value is 0.

     In the current simulator, the only functional effect is to cause logging of hazard waiting information if the CPU is superscalar. However nowhere in the simulator is this data actually computed, so the net result is probably to have no effect.

     if harzards are tracked, current hazards can be displayed using the simulator's r command.

          The code for this does not appear to be complete or well tested, so users are advised not to use this option.

dependstats = 0|1
     If 1, inter-instruction dependencies are calculated. Default value 0.

     If these values are calculated, the depencies can be displayed using the simulator's stat command.

          This field must be enabled, if execution execution flow tracking (field history) has been requested in the simulator configuration section (see Simulator Behavior).

sbuf_len = VALUE
     The length of the store buffer is set to VALUE, which must be no greater than 256. Larger values will be truncated to 256 with a warning. Negative values will be treated as 0 with a warning. Use 0 to disable the store buffer.

     When the store buffer is active, stores are accumulated and committed when I/O is idle.

Memory Configuration
--------------------

Memory configuration is described in section memory. This section may appear multiple times, specifying multiple blocks of memory. The following parameters may be specified.

type=random|pattern|unknown|zero
     Specifies the values to which memory should be initialized. The default value is unknown.

     random
          Set the memory values to be a random value. A seed for the random generator may be set using the random_seed field in this section (see below), thus ensuring the same ``random'' values are used each time.

     pattern
          Set the memory values to be a pattern value, which is set using the pattern field in this section (see below).

     unknown
          The memory values are not initialized (i.e. left ``unknown''). This option will yield faster initialization of the simulator.

     zero
          Set the memory values to be 0. This is the equivalent of type=pattern and a pattern value of 0, and implemented as such.

               As a consequence, if the pattern field is subsequently specified in this section, the value in that field will be used instead of zero to initialize the memory.

random_seed = VALUE
     Set the seed for the random number generator to VALUE. This only has any effect for memory type random.

     The default value is -1, which means the seed will be set from a call to the time function, thus ensuring different random values are used on each run. The simulator prints out the seed used in this case, allowing repeat runs to regenerate the same random values used in any particular run.

pattern = VALUE
     Set the pattern to be used when initializing memory to VALUE. The default value is 0. This only has any effect for memory type pattern. The least significant 8 bits of this value is used to initialize each byte. More than 8 bits can be specified, but will ignored with a warning.

          The default value, is equivalent to setting the memory type to be zero. If that is what is intended, then using type=zero explicitly is better than using type=pattern and not specifying a value for pattern.

baseaddr = VALUE
     Set the base address of the memory to VALUE. It should be aligned to a multiple of the memory size rounded up to the nearest 2^n. The default value is 0.

size = VALUE
     Set the size of the memory block to be VALUE bytes. This should be a multiple of 4 (i.e. word aligned). The default value is 1024.

          When allocating memory, the simulator will allocate the nearest 2^n bytes greater than or equal to VALUE, and will not notice memory misses in any part of the memory between VALUE and the amount allocated.

          As a consequence users are strongly recommended to specify memory sizes that are an exact power of 2. If some other amount of memory is required, it should be specified as separate, contiguous blocks, each of which is a power of 2 in size.

name = "TEXT"
     Name the block. Typically these describe the type of memory being modeled (thus "SRAM" or "Flash". The default is "anonymous memory block".

          It is not clear that this information is currently ever used in normal operation of the simulator. Even the info command of the simulator ignores it.

ce = VALUE
     Set the chip enable index of the memory instance. Each memory instance should have a unique chip enable index, which should be greater than or equal to zero. This is used by the memory controller when identifying different memory instances.

     The default value is -1 (invalid).

mc = VALUE
     Specifies the memory controller this memory is connected to. It should correspond to the index field specified in a section mc for a memory controller (see Memory Controller Configuration).

     Default value is 0, which is also the default value of a memory controller index field. This is suitable therefore for designs with just one memory controller.

delayr = VALUE
     The number of cycles required for a read access. Set to -1 if the memory does not support reading. Default value 1. The simulator will add this number of cycles to the total instruction cycle count when reading from main memory.

delayw = VALUE
     The number of cycles required for a write access. Set to -1 if the memory does not support writing. Default value 1. The simulator will add this number of cycles to the total instruction cycle count when writing to main memory.

log = "FILE"
     If specified, file names a file for all memory accesses to be logged. If not specified, the default value, NULL is used, meaning that the memory is not logged.

Memory Management Configuration
-------------------------------

Memory Management Unit (MMU) configuration is described in section dmmu (for the data MMU) and section immu (for the instruction MMU). Each section should appear at most once. The following parameters may be specified.

enabled = 0|1
     If 1 (true), the data or instruction (as appropriate) MMU is enabled. If 0 (the default), it is disabled.

nsets = VALUE
     Sets the number of data or instruction (as appropriate) TLB sets to VALUE, which must be a power of two, not exceeding 128. Values which do not fit these criteria are ignored with a warning. The default value is 1.

nways = VALUE
     Sets the number of data or instruction (as appropriate) TLB ways to VALUE. The value must be in the range 1 to 4. Values outside this range are ignored with a warning. The default value is 1.

pagesize = VALUE
     The data or instruction (as appropriate) MMU page size is set to VALUE, which must be a power of 2. Values which are not a power of 2 are ignored with a warning. The default is 8192 (0x2000).

entrysize = VALUE
     The data or instruction (as appropriate) MMU entry size is set to VALUE, which must be a power of 2. Values which are not a power of 2 are ignored with a warning. The default value is 1.

          OR1KSIM does not appear to use the entrysize parameter in its simulation of the MMUs. Thus setting this value does not seem to matter.

ustates = VALUE
     The number of instruction usage states for the data or instruction (as appropriate) MMU is set to VALUE, which must be 2, 3 or 4. Values outside this range are ignored with a warning. The default value is 2.

          OR1KSIM does not appear to use the ustates parameter in its simulation of the MMUs. Thus setting this value does not seem to matter.

hitdelay = VALUE
     Set the number of cycles a data or instruction (as appropriate) MMU hit costs. Default value 1.

missdelay = VALUE
     Set the number of cycles a data or instruction (as appropriate) MMU miss costs. Default value 1.

Cache Configuration
-------------------

Cache configuration is described in section dc (for the data cache) and seciton ic (for the instruction cache). Each section should appear at most once. The following parameters may be specified.

enabled = 0|1
     If 1 (true), the data or instruction (as appropriate) cache is enabled. If 0 (the default), it is disabled.

nsets = VALUE
     Sets the number of data or instruction (as appropriate) cache sets to VALUE, which must be a power of two, not exceeding MAX_DC_SETS (for the data cache) or MAX_IC_SETS (for the instruction cache). At the time of writing, these constants are both defined in the code to be 1024). The default value is 1.

nways = VALUE
     Sets the number of data or instruction (as appropriate) cache ways to VALUE, which must be a power of two, not exceeding MAX_DC_WAYS (for the data cache) or MAX_IC_WAYS (for the instruction cache). At the time of writing, these constants are both defined in the code to be 32). The default value is 1.

blocksize = VALUE
     The data or instruction (as appropriate) cache block size is set to VALUE bytes, which must be either 16 or 32. The default is 16.

ustates = VALUE
     The number of instruction usage states for the data or instruction (as appropriate) cache is set to VALUE, which must be 2, 3 or 4. The default value is 2.

hitdelay = VALUE
     Instruction cache only. Set the number of cycles an instruction cache hit costs. Default value 1.

missdelay = VALUE
     Instruction cache only. Set the number of cycles an instruction cache miss costs. Default value 1.

load_hitdelay = VALUE
     Data cache only. Set the number of cycles a data load cache hit costs. Default value 2.

load_missdelay = VALUE
     Data cache only. Set the number of cycles a data load cache miss costs. Default value 2.

store_hitdelay = VALUE
     Data cache only. Set the number of cycles a data store cache hit costs. Default value 0.

store_missdelay = VALUE
     Data cache only. Set the number of cycles a data store cache miss costs. Default value 0.

Interrupt Configuration
-----------------------

Programmable Interrupt Controller (PIC) configuration is described in section pic. This section may appear at most once---OR1KSIM has no mechanism for handling multiple interrupt controllers. The following parameters may be specified.

enabled = 0|1
     If 1 (true), the programmable interrupt controller is enabled. If 0 (the default), it is disabled.

edge_trigger = 0|1
     If 1 (true, the default), the programmable interrupt controller is edge triggered. If 0 (false), it is level triggered.

Power Management Configuration
------------------------------

Power management implementation is incomplete. At present the effect (which only happens when the power management unit is enabled) of setting the different bits in the power management Special Purpose Register (PMR, SPR 0x4000) is

SDF (bit mask 0x0000000f)
     No effect - these bits are ignored

DME (bit mask 0x00000010)
SME (bit mask 0x00000020)
     Both these bits cause the processor to stop executing instructions. However all other functions (debug interaction, CLI, VAPI etc) carry on as normal.

DCGE (bit mask 0x00000004)
     No effect - this bit is ignored

SUME (bit mask 0x00000008)
     Enabling this bit causes a message to be printed, advising that the processor is suspending and the simulator exits.

On reset all bits are cleared.

Power management configuration is described in section pm. This section may appear at most once. The following parameter may be specified.

enabled = 0|1
     If 1 (true), power management is enabled. If 0 (the default), it is disabled.

Branch Prediction Configuration
-------------------------------

From examining the code base, it seems the branch prediction function is not fully implemented. At present the functionality seems restricted to collection of statistics.

Branch prediction configuration is described in section bpb. This section may appear at most once. The following parameters may be specified.

enabled = 0|1
     If 1 (true), branch prediction is enabled. If 0 (the default), it is disabled.

btic = 0|1
     If 1 (true), the branch target instruction cache model is enabled. If 0 (the default), it is disabled.

sbp_bf_fwd = 0|1
     If 1 (true), use forward prediction for the l.bf instruction. If 0 (the default), do not use forward prediction for this instruction.

sbp_bnf_fwd = 0|1
     If 1 (true), use forward prediction for the l.bnf instruction. If 0 (the default), do not use forward prediction for this instruction.

hitdelay = VALUE
     Set the number of cycles a branch prediction hit costs. Default value 0.

missdelay = VALUE
     Set the number of cycles a branch prediction miss costs. Default value 0.

Debug Interface Configuration
-----------------------------

The debug unit and debug interface configuration is described in section debug. This section may appear at most once. The following parameters may be specified.

enabled = 0|1
     If 1 (true), the debug unit is enabled. If 0 (the default), it is disabled.

          This enables the functionality of the debug unit (its registers etc) within the mode. It does not provide any external interface to the debug unit. For that, see gdb_enabled and rsp_enabled below.

rsp_enabled = 0|1
     If 1 (true), the GDB Remote Serial Protocol server is started, provding an interface to an external GNU debugger, using the port specified in the rsp_port field (see below), or the or1ksim-rsp TCP/IP service. If 0 (the default), the server is not started, and no external interface is provided.

     For more detailed information on the interface to the GNU Debugger see Embecosm Application Note 2, Howto: Porting the GNU Debugger Practical Experience with the OpenRISC 1000 Architecture, by Jeremy Bennett, published by Embecosm Limited (www.embecosm.com).

          rsp_enabled may not be enabled with gdb_enabled (see below). If both are enabled, a warning is issued and only the Remote Serial Protocol interface is enabled.

rsp_port = VALUE
     VALUE specifies the port to be used for the GDB Remote Serial Protocol interface to the GNU Debugger (GDB). Default value 51000. If the value 0 is specified, OR1KSIM will instead look for a TCP/IP service named or1ksim-rsp.

          There is no registered port for OR1KSIM Remote Serial Protocol service or1ksim-rsp. Good practice suggests users should adopt port values in the Dynamic or Private port range, i.e. 49152-65535.

gdb_enabled = 0|1
     If 1 (true), the OpenRISC Remote JTAG protocol server is started, provding an interface to an external GNU debugger, using the port specified in the server_port field (see below), or the or1ksim TCP/IP service. If 0 (the default), the server is not started, and no external interface is provided.

     For more detailed information on the interface to the GNU Debugger see Embecosm Application Note 2, Howto: Porting the GNU Debugger Practical Experience with the OpenRISC 1000 Architecture, by Jeremy Bennett, published by Embecosm Limited (www.embecosm.com).

          The OpenRISC Remote JTAG protocol is unique to OpenRISC, and remains only for backward compatibility. New users should adopt the standard GDB Remote Serial Protocol interface (see rsp_enabled above) providing access to a wider range of GDB functionality.

          gdb_enabled may not be enabled with rsp_enabled. If both are enabled, a warning is issued and only the Remote Serial Protocol interface is enabled.

server_port = VALUE
     VALUE specifies the port to be used for the OpenRISC Rmote JTAG protocol interface to the GNU Debugger (GDB). Default value 51000. If the value 0 is specified, OR1KSIM will instead look for a TCP/IP service named or1ksim.

          There is no registered port for OR1KSIM Remote JTAG Interface or service or1ksim. Good practice suggests users should adopt port values in the Dynamic or Private port range, i.e. 49152-65535.

vapi_id = VALUE
     VALUE specifies the value of the Verification API (VAPI) base address to be used with the debug unit. See Verification API, for more details.

     If this is specified and VALUE is non-zero, all OpenRISC Remote JTAG protocol transactions will be logged to the VAPI log file, if enabled. This is the only functionality associated with VAPI for the debug unit. No VAPI commands are sent, nor requests handled.

Configuring Memory Mapped Peripherals
=====================================

All peripheral components are optional. If they are specified, then (unlike other components) by default they are enabled.

Memory Controller Configuration
-------------------------------

The memory controller used in OR1KSIM is the component implemented at OpenCores, and found in the top level CVS directory, mem_ctrl. It is described in the document Memory Controller IP Core by Rudolf Usselmann, which can be found in the doc subdirectory. It is a memory mapped component, which resides on the main OpenRISC Wishbone data bus.

The memory controller configuration is described in section mc. This section may appear multiple times, specifying multiple memory controllers. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this memory controller is enabled. If 0, it is disabled.

          The memory controller can effectively also be disabled by setting an appropriate power on control register value (see below). However this should only be used if it is desired to specifically model this behavior of the memory controller, not as a way of disabling the memory controller in general.

baseaddr = VALUE
     Set the base address of the memory controller's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The memory controller has a 7 bit address bus, with a total of 19 32-bit registers, at addresses 0x00 through 0x4c (address 0x0c and addresses 0x50 through 0x7c are not used).

poc = VALUE
     Specifies the value of the power on control register, The least signficant two bits specify the bus width (use 0 for an 8-bit bus, 1 for a 16-bit bus and 2 for a 32-bit bus) and the next two bits the type of memory connected (use 0 for a disabled interface, 1 for SSRAM, 2 for asyncrhonous devices and 3 for synchronous devices).

     If other bits are specified, they are ignored with a warning.

          The default value, 0, corresponds to a disabled 8-bit bus, and is likely not the most suitable value

index = VALUE
     Specify the index of this memory controller amongst all the memory controllers. This value should be unique for each memory controller, and is used to associate specific memories with the controller, through the mc field in the section memory configuration (see Memory Configuration).

     The default value, 0, is suitable when there is only one memory controller.

UART Configuration
------------------

The UART implemented in OR1KSIM follows the specification of the National Semiconductor 16450 and 16550 parts. It is a memory mapped component, which resides on the main OpenRISC Wishbone data bus.

The component provides a number of interfaces to emulate the behavior of an external terminal connected to the UART.

UART configuration is described in section uart. This section may appear multiple times, specifying multiple UARTs. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this UART is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the UART's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The UART has a 3 bit address bus, with a total of 8 8-bit registers, at addresses 0x0 through 0x7.

channel = "TYPE:ARGS"
     Specify the channel representing the terminal connected to the UART Rx & Tx pins.

     channel="file:rxfile,txfile"
          Read input characters from the file rxfile and write output characters to the file txfile (which will be created if required).

     channel="xterm:ARGS"
          Create an xterm on startup, write UART Tx traffic to the xterm and take Rx traffic from the keyboard when the xterm window is selected. Additional arguments to the xterm command (for example specifying window size may be specified in ARGS, or this may be left blank.

     channel="tcp:VALUE"
          Open the TCP/IP port specified by VALUE and read and write UART traffic from and to it.

          Typically a telnet session is connected to the other end of this port.

               There is no registered port for OR1KSIM telnet UART connection. Priviledged access is required to read traffic on the registered ``well-known'' telnet port (23). Instead users should use port values in the Dynamic or Private port range, i.e. 49152-65535.

     channel="fd:rxfd,txfd"
          Read and write characters from and to the existing open numerical file descriptors, file rxfd and txfd.

     channel="tty:device=/dev/ttyS0,baud=9600"
          Read and write characters from and to a physical serial port. The precise device (shown here as /dev/ttyS0) may vary from machine to machine.

     The default value for this field is "xterm:".

irq = VALUE
     Use VALUE as the IRQ number of this UART. Default value 0.

16550 = 0|1
     If 1 (true), the UART has the functionality of a 16550. If 0 (the default), it has the functionality of a 16450. The principal difference is that the 16550 can buffer multiple characters.

jitter = VALUE
     Set the jitter, modeled as a time to block, to VALUE milliseconds. Set to -1 to disable jitter modeling. Default value 0.

          This functionality has yet to be implemented, so this parameter has no effect.

vapi_id = VALUE
     VALUE specifies the value of the Verification API (VAPI) base address to be used with the UART. See Verification API, for more details, which details the use of the VAPI with the UART.

DMA Configuration
-----------------

The DMA controller used in OR1KSIM is the component implemented at OpenCores, and found in the top level CVS directory, wb_dma. It is described in the document Wishbone DMA/Bridge IP Core by Rudolf Usselmann, which can be found in the doc subdirectory. It is a memory mapped component, which resides on the main OpenRISC Wishbone data bus. The present implementation is incomplete, intended only to support the Ethernet interface (see Ethernet Configuration), although the Ethernet interface is not yet completed.

DMA configuration is described in section dma. This section may appear multiple times, specifying multiple DMA controllers. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this DMA controller is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the DMA's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The DMA controller has a 10 bit address bus, with a total of 253 32-bit registers. The first 5 registers at addresses 0x000 through 0x010 control the overall behavior of the DMA controller. There are then 31 blocks of 8 registers, controlling each of the 31 DMA channels available. Addresses 0x014 through 0x01c are not used.

irq = VALUE
     Use VALUE as the IRQ number of this DMA controller. Default value 0.

vapi_id = VALUE
     VALUE specifies the value of the Verification API (VAPI) base address to be used with the DMA controller. See Verification API, for more details, which details the use of the VAPI with the DMA controller.

Ethernet Configuration
----------------------

The Ethernet MAC used in OR1KSIM is the component implemented at OpenCores, and found in the top level CVS directory, ethernet. It also forms part of the OpenRISC SoC, ORPSoC. It is described in the document Ethernet IP Core Specification by Igor Mohor, which can be found in the doc subdirectory. It is a memory mapped component, which resides on the main OpenRISC Wishbone data bus.

Ethernet configuration is described in section ethernet. This section may appear multiple times, specifying multiple Ethernet interfaces. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this Ethernet MAC is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the MAC's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The Ethernet MAC has a 7-bit address bus, with a total of 21 32-bit registers. Addresses 0x54 through 0x7c are not used.

          The Ethernet specification describes a Tx control register, TXCTRL, at address 0x50. However this register is not implemented in the OR1KSIM model.

dma = VALUE
     VALUE specifies the DMA controller with which this Ethernet is associated. The default value is 0.

          Support for external DMA is not provided in the current implementation, and this value is ignored. In any case there is no equivalent field to which this can be matched in the current DMA component implementation (see DMA Configuration).

irq = VALUE
     Use VALUE as the IRQ number of this Ethernet MAC. Default value 0.

rtx_type = 0|1
     If 1 (true) use a socket interface to the Ethernet (see parameter sockif below). If 0 (the default), use a file interface, reading and writing from and to the files specified in the rxfile and txfile parameters (see below).

          By default the socket interface is not provided in OR1KSIM. If it is required, this must be requested when configuring, by use of the --enable-ethphy option to configure.

               configure --target=or32-uclinux --enable-ethphy ...

rx_channel = RXVALUE
tx_channel = TXVALUE
     RXVALUE specifies the DMA channel to use for receive and TXVALUE the DMA channel to use for transmit. Both default to 0.

          As noted above, support for external DMA is not provided in the current implementation, and so these values are ignored.

rxfile = "RXFILE"
txfile = "TXFILE"
     When rtx_type is 0 (see above), RXFILE specifies the file to use as input and TXFILE specifies the fie to use as output.

     The file contains a sequence of packets. Each packet consists of a packet length (32 bits), followed by that many bytes of data. Once the input file is empty, the Ethernet MAC behaves as though there were no data on the Ethernet. The default values of these parameters are "eth_rx" and "eth_tx" respectively.

     The input file must exist and be readable. The output file must be writable and will be created if necessary. If either of these conditions is not met, a warning will be given.

sockif = "SERVICE"
     When rtx_type is 1 (see above), SERVICE specifies the service to use for communication. This may be TCP/IP or UDP/IP. The default value of this parameter is "or1ksim_eth".

vapi_id = VALUE
     VALUE specifies the value of the Verification API (VAPI) base address to be used with the Ethernet PHY. See Verification API, for more details, which details the use of the VAPI with the DMA controller.

GPIO Configuration
------------------

The GPIO used in OR1KSIM is the component implemented at OpenCores, and found in the top level CVS directory, gpio. It is described in the document GPIO IP Core Specification by Damjan Lampret and Goran Djakovic, which can be found in the doc subdirectory. It is a memory mapped component, which resides on the main OpenRISC Wishbone data bus.

GPIO configuration is described in section gpio. This section may appear multiple times, specifying multiple GPIO devices. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this GPIO is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the GPIO's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The GPIO has a 6 bit address bus, with a total of 10 32-bit registers, although the number of bits that are actively used varies. Addresses 0x28 through 0x3c are not used.

irq = VALUE
     Use VALUE as the IRQ number of this GPIO. Default value 0.

vapi_id = VALUE
     VALUE specifies the value of the Verification API (VAPI) base address to be used with the GPIO. See Verification API, for more details, which details the use of the VAPI with the GPIO controller. For backwards compatibility, the alternative name base_vapi_id is supported for this parameter, but deprecated.

Display Interface Configuration
-------------------------------

OR1KSIM models a VGA interface to an external monitor.  The VGA controller used in OR1KSIM is the component implemented at OpenCores, and found in the top level CVS directory, vga_lcd, with no support for the optional hardware cursors. It is described in the document VGA/LCD Core v2.0 Specifications by Richard Herveille, which can be found in the doc subdirectory. It is a memory mapped component, which resides on the main OpenRISC Wishbone data bus.

The current implementation provides only functionality to dump the screen to a file at intervals.

VGA controller configuration is described in section vga. This section may appear multiple times, specifying multiple VGA controllers. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this VGA is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the VGA controller's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The VGA controller has a 12-bit address bus, with 7 32-bit registers, at addresses 0x000 through 0x018, and two color lookup tables at addresses 0x800 through 0xfff. The hardware cursor registers are not implemented, so addresses 0x01c through 0x7fc are not used.

irq = VALUE
     Use VALUE as the IRQ number of this VGA controller. Default value 0.

refresh_rate = VALUE
     VALUE specifies number of cycles between screen dumps. Default value is derived from the simulation clock cycle time (see Simulator Behavior), to correspond to dumping 50 times per simulated second.

txfile = "FILE"
     FILE specifies the base of the filename for screen dumps. Successive screen dumps will be in BMP format, in files with the name FILENNNN.bmp, where NNNN is a sequential count of the screen dumps starting at zero. The default value is "vga_out". For backwards compatibility, the alternative name filename is supported for this parameter, but deprecated.

Frame Buffer Configuration
--------------------------

     The frame buffer is only partially implemented. Its configuration fields are described here, but the component should not be used at this time. Like the VGA controller, it is designed to make screen dumps to file.

Frame buffer configuration is described in section fb. This section may appear multiple times, specifying multiple frame buffers. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this frame buffer is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the frame buffer's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The frame buffer has an 121-bit address bus, with 4 32-bit registers, at addresses 0x000 through 0x00c, and a PAL lookup table at addresses 0x400 through 0x4ff. Addresses 0x010 through 0x3fc and addresses 0x500 through 0x7ff are not used.

refresh_rate = VALUE
     VALUE specifies number of cycles between screen dumps. Default value is derived from the simulation clock cycle time (see Simulator Behavior), to correspond to dumping 50 times per simulated second.

txfile = "FILE"
     FILE specifies the base of the filename for screen dumps. Successive screen dumps will be in BMP format, in files with the name FILENNNN.bmp, where NNNN is a sequential count of the screen dumps starting at zero. The default value is "fb_out". For backwards compatibility, the alternative name filename is supported for this parameter, but deprecated.

Keyboard Configuration (PS2)
----------------------------

The PS2 interface provided by OR1KSIM is not documented. It may be based on the PS2 project at OpenCores, and found in the top level CVS directory, ps2. However this project lacks any documentation beyond its project webpage. Since most PS2 interfaces follow the Intel i8042 standard, this is presumably what is expected with this device.

The implementation only provides for keyboard support, which is modelled as a file of keystrokes. There is no mouse support.

     A standard i8042 device has two registers at addresses 0x60 (command) and 0x64 (status). Inspection of the code, suggests that the OR1KSIM component places these registers at addresses 0x00 and 0x04.

     The port of Linux for the OpenRISC 1000, which runs on OR1KSIM implements the i8042 device driver, anticipating these registers reside at their conventional address. It seems unlikel that this code will work.

     This component should be used with caution.

Keyboard configuration is described in section kbd. This section may appear multiple times, specifying multiple keyboard interfaces. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this keyboard is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the keyboard's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The keyboard PS/2 interface has an 3-bit address bus, with 2 8-bit registers, at addresses 0x000 and 0x004.

          As noted above, a standard Intel 8042 interface would expect to find these registers at locations 0x60 and 0x64, thus requiring at least a 7-bit bus.

irq = VALUE
     Use VALUE as the IRQ number of this Keyboard interface. Default value 0.

rxfile = "FILE"
     file specifies a file containing raw key stroke data, which models the input from a physical keyboard. The default value is "kbd_in".

Disc Interface Configuration
----------------------------

The ATA/ATAPI disc controller used in OR1KSIM is the OCIDEC (OpenCores IDE Controller) component implemented at OpenCores, and found in the top level CVS directory, ata. It is described in the document ATA/ATAPI-5 Core Specification by Richard Herveille, which can be found in the doc subdirectory. It is a memory mapped component, which resides on the main OpenRISC Wishbone data bus.

ATA/ATAPI configuration is described in section ata. This section may appear multiple times, specifying multiple disc controllers. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this ATA/ATAPI interface is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the ATA/ATAPI interface's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The ATA/ATAPI PS/2 interface has an 5-bit address bus, with 8 32-bit registers. Depending on the version of the OCIDEC ATA/ATAPI interface selected (see dev_id below), not all registers will be available.

irq = VALUE
     Use VALUE as the IRQ number of this ATA/ATAPI interface. Default value 0.

dev_id = 1|2|3
     This parameter specifies which version of the OCIDEC ATA/ATAPI interface to model. The default value is 1.

     Version 1 supports only the CTRL, STAT and PCTR registers. Versions 2 & 3 add the FCTR registers, Version 3 adds the DTR registers and the RXD/TXD registers.

rev = VALUE
     Set the VALUE as the revision of the OCIDEC ATA/ATAPI interface. The default value is 1. The default value is 0. Its value should be in the range 0-15. Larger values are truncated with a warning. This only affects the reset value of the STAT register, where it forms bits 24-27.

pio_mode0_t1 = VALUE
pio_mode0_t2 = VALUE
pio_mode0_t4 = VALUE
pio_mode0_teoc = VALUE
     These parameters specify the timings for use with Programmed Input/Output (PIO) transfers. They are specified as the number of clock cycles - 2, rounded up to the next highest integer, or zero if that would be negative. The values should not exceed 255. If they do, they will be ignored with a warning.

     See the ATA/ATAPI-5 specification for explanations of each of these timing parameters. The default values are:

          pio_mode0_t1   =  6
          pio_mode0_t2   = 28
          pio_mode0_t4   =  2
          pio_mode0_teoc = 23

dma_mode0_tm = VALUE
dma_mode0_td = VALUE
dma_mode0_teoc = VALUE
     These parameters specify the timings for use with DMA transfers. They are specified as the number of clock cycles - 2, rounded up to the next highest integer, or zero if that would be negative. The values should not exceed 255. If they do, they will be ignored with a warning.

     See the ATA/ATAPI-5 specification for explanations of each of these timing parameters. The default values are:

          dma_mode0_tm   =  4
          dma_mode0_td   = 21
          dma_mode0_teoc = 21

ATA/ATAPI Device Configuration
..............................

Within the section ata, each device is specified separately. The device subsection is introduced by

     device VALUE

VALUE is the device number, which should be 0 or 1. The subsection ends with enddevice. Note that if the same device number is specified more than once, the previous values will be overwritten. Within the device subsection, the following parameters may appear:

type = VALUE
     VALUEspecifies the type of device: 0 (the default) for ``not connected'', 1 for hard disk simulated in a file and 2 for local system hard disk.

file = "FILENAME"
     filename specifies the file to be used for a simulated ATA device if the file type (see type above) is 1. Default value "ata-FileN", where N is the device number.

size = VALUE
     VALUE specifies the size of a simulated ATA device if the file type (see type above) is 1. The default value is zero.

packet = 0|1
     If 1 (true), implement the PACKET command feature set. If 0 (the default), do not implement the PACKET command feature set.

firmware = "STR"
     Firmware to report in response to the ``Identify Device'' command. Default "02207031".

heads = VALUE
     Number of heads in the device. Default 7, use -1 to disable all heads.

sectors = VALUE
     Number of sectors per track in the device. Default 32.

mwdma = 0|1|2|-1
     Highest multi-word DMA mode supported. Default 2, use -1 to disable.

pio = 0|1|2|3|4
     Highest PIO mode supported. Default 4.

Generic Peripheral Configuration
--------------------------------

When used as a library (see Simulator Library), OR1KSIM makes provision for any additional peripheral to be implemented externally. Any read or write access to this peripheral's memory map generates upcalls to an external handler. This interface can support either C or C++, and was particularly designed to facilitate support for OSCI SystemC (see http://www.systemc.org).

Generic peripheral configuration is described in section generic. This section may appear multiple times, specifying multiple external peripherals. The following parameters may be specified.

enabled = 0|1
     If 1 (true, the default), this ATA/ATAPI interface is enabled. If 0, it is disabled.

baseaddr = VALUE
     Set the base address of the generic peripheral's memory mapped registers to VALUE. The default is 0, which is probably not a sensible value.

     The size of the memory mapped register space is controlled by the size paramter, described below.

size = VALUE
     Set the size of the generic peripheral's memory mapped register space to VALUE bytes. Any read or write accesses to addresses with offsets of 0 to VALUE-1 bytes from the base address specified in parameter baseaddr (see above) will be directed to the external interface.

     VALUE will be rounded up the nearest power of 2. It's default value is zero. If VALUE is not an exact power of two, accesses to address offsets of VALUE or above up to the next power of 2 will generate a warning, and have no effect (reads will return zero).

name = "STR"
     This gives the peripheral the name "STR". This is used to identify the peripheral in error messages and warnings, and when reporting its status. The default value is "anonymous external peripheral".

byte_enabled = 0|1
hw_enabled = 0|1
word_enabled = 0|1
     If 1 (true, the default), these parameters respectively enable the device for byte wide, half-word wide and word wide accesses. If 0, accesses of that width will fail.

Interactive Command Line
************************

If started with the -f flag, or if interrupted with ctrl-C, OR1KSIM provides the user with an interactive command line. The commands available, which may not be abbreviated, are:

q
     Exit the simulator

r
     Display all the General Purpose Registers (GPRs). Also shows the just executed and next to be executed instructions symbolically and the state of the flag in the Supervision Register.

t
     Execute the next instruction and then display register/instruction information as with the r command (see above).

run NUM [ hush ]
     Execute NUM instructions. The register/instruction information is displayed after each instruction, as with the r command (see above) unless hush is specified.

pr REG VALUE
     Patch register REG with VALUE.

dm FROMADDR [ TOADDR ]
     Display memory bytes between FROMADDR and TOADDR. If TOADDR is not given, 64 bytes are displayed, starting at FROMADDR.

          The output from this command is broken (a bug). OR1KSIM attempts to print out 16 bytes per row. However, instead of printing out the address at the start of each row, it prints the address (of the first of the 16 bytes) before each byte.

de FROMADDR [ TOADDR ]
     Disassemble code between FROMADDR and TOADDR. If TOADDR is not given, 16 instructions are disassembled.

     The disassembly is entirely numerical, and gives no symbolic information.

pm ADDR VALUE
     Patch the 4 bytes in memory starting at ADDR with the 32-bit VALUE.

pc VALUE
     Patch the program counter with VALUE.

cm FROMADDR TOADDR SIZE
     Copy SIZE bytes in memory from FROMADDR to TOADDR.

break ADDR
     Toggle the breakpoint set at ADDR.

breaks
     List all set breakpoints

reset
     Reset the simulator. Includes modeling a reset of the processor, so execution will restart from the reset vector location, 0x100.

hist
     If saving the execution history has been configured (see Simulator Behavior), display the execution history.

stall
     Stall the processor, so that control is passed to the debug unit. When stalled, the processor can execute no instructions. This command is useful when debugging the JTAG interface, used by debuggers such as GDB.

unstall
     Unstall the processor, so that normal execution can continue. This command is useful when debugging the JTAG interface, used by debuggers such as GDB.

stats CATEGORY | clear
     Print the statistics for the given CATEGORY, if available, or clear if clear is specified. The categories are:

     1
          Miscellaneous statistics: branch predictions (if branch predictions are enabled), branch target cache model (if enabled), cache (if enbaled), MMU (if enabled) and number of addtional load & store cycles.

          See Configuring the OpenRisc Achitectural Components, for details of how to enable these various features.

     2
          Instruction usage statistics. Requires hazard analysis to be enabled (see CPU Configuration).

     3
          Instruction dependency statistics. Requires hazard analysis to be enabled (see CPU Configuration).

     4
          Functional unit dependency statistics. Requires hazard analysis to be enabled (see CPU Configuration).

     5
          Raw register usage over time. Requires hazard analysis to be enabled (see CPU Configuration).

     6
          Store buffer statistics. Requires the store buffer to be enabled (see CPU Configuration).

info
     Display detailed information about the simulator configuration. This is quite a lengthy about, because all MMU TLB information is displayed.

dv FROMADDR [ TOADDR ] [ MODULE ]
     Dump the area of memory between FROMADDR and TOADDR as Verilog code for a synchronous, 23-bit wide SRAM module, named MODULE. If TOADDR is not specified, then 64 bytes are dumped (as 16 32-bit words). If MODULE is not specified, or1k_mem is used.

     To save to a file, use the redirection function (described after this table, below).

dh FROMADDR [ TOADDR ]
     Dump the area of memory between FROMADDR and TOADDR as 32-bit hex numbers (no 0x, or 32'h prefix). If TOADDR is not specified, then 64 bytes are dumped (as 16 32-bit words).

     To save to a file, use the redirection function (described after this table, below).

setdbch
     Toggle debug channels on/off. See Standalone Simulator, for a description of specifying debug channels on the command line.

set SECTION PARAM = VALUE
     Set the configuration parameter PARA in section SECTION to VALUE. See Configuration, for details of configuration parameters and their settings.

debug
     Toggle the simulator debug mode. See Debug Interface Configuration, for information on this parameter.

          This is effectively enabling or disabling the debug unit. It does not effect the remote GDB debug interface. However using the remote debug interface while the debug unit is disabled will lead to undefined behavior and likely crash OR1KSIM

cuc
     Enter the the Custom Unit Compiler command prompt (see CUC Configuration).

          The CUC must be properly configured, for this to succeed. In particular a timing file must be available and readable. Otherwise OR1KSIM will crash.

help
     Print out brief information about each command available.

mprofile [-vh] [-m M] [-g N] [-f FILE] FROM TO
     Run the memory profiling utility. This follows the same usage as the standalone command (see Memory Profiling Utility).

profile [-vhcq] [-g FILE]
     Run the instruction profiling utility. This follows the same usage as the standalone command (see Profiling Utility).

For all commands, it is possible to redirect the output to a file, by using the redirection operator, >.

     COMMAND > FILENAME

This is particularly useful for commands dumping a large amount of output, such as dv.

     Unfortunately there is a serious bug with the redirection operator. It does not return output to standard output after the command completes. Until this bug is fixed, file redirection should not be used.

Verification API (VAPI)
***********************

The Verification API (VAPI) provides a TCP/IP interface to allow components of the simulation to be controlled externally. The interface is polled for new requests on each simulated clock cycle. Components within the simulator may send responses to such requests.

The inteface is an asynchronous duplex protocol. On the request side it provides for simple commands, known as VAPI IDs (a 32 bit integer), with a single piece of data (also a 32 bit integer). On the send side, it provides for sending a single VAPI ID and data. However there is no explicit command-response structure. Some components just accept requests (e.g. to set values), some just generate sends (to report values), and some do both.

Each component has a base ID (32 bit) and its commands will start from that base ID. This provides a simple partitioning of the command space amongst components. Request commands will be directed to the component with the closest base ID lower than the VAPI ID of the command.

Thus if there are two components with base IDs of 0x200 and 0x300, and a request with VAPI ID of 0x203 is received, it will be directed to the first component as its command #3.

The results of VAPI interactions are logged (by default in vapi.log unless an alternative is specified in section vapi).

Currently the following components support VAPI:

Debug Unit
     Although the Debug Unit can specify a base VAPI ID, it is not used to send commands or receive requests.

     Instead, if the base VAPI ID is set, all remote JTAG protocol exchanges are logged in the VAPI log file.

UART
     If a base VAPI ID is specified, the UART sends details of any chars or break characters sent, with dteails of the line control register etc encoded in the data packet sent.

     This supports a single VAPI command request, but encodes a sub-command in the top 8 bits of the associated data.

     0x00
          This stuffs the least significant 8 bits of the data into the serial register of the UART and the next 8 bits into the line control register, effectively providing control of the next character to be sent or received.

     0x01
          The divisor latch bytes are set from the least significant 16 bits of the data.

     0x02
          The line control register is set from bits 15-8 of the data.

     0x03
          The UART skew is set from the least significant 16 bits of the data

     0x04
          If the 16th most significant bit of the data is 1, start sending breaks, otherwise stop sending breaks. The breaks are sent or cleared after the number of UART clock divider ticks specified by the data (immediately if the data is zero).

DMA
     Although the DMA unit supports a base VAPI ID in its configuration (section dma), no VAPI data is sent, nor VAPI requests currently implemented.

Ethernet
     The following requests are handled by the Ethernet. Specified symbolically, these are the increments from the base VAPI ID of the Ethernet. At present no implementation is provided behind these VAPI requests.

     ETH_VAPI_DATA (0)

     ETH_VAPI_CTRL (0)

GPIO
     If a base VAPI ID is specified, the GPIO sends out on its base VAPI ID (symbolically, GPIO_VAPI_DATA (0) offset from the base VAPI ID) any changes in outputs.

     The following requests are handled by the GPIO. Specified symbolically, these are the increments from the VAPI base ID of the GPIO.

     GPIO_VAPI_DATA (0)
          Set the next input to the commands data field

     GPIO_VAPI_AUX (1)
          Set the GPIO auxiliary inputs to the data field

     GPIO_VAPI_CLOCK (2)
          Add an external GPIO clock trigger of period specified in the data field.

     GPIO_VAPI_RGPIO_OE (3)
          Set the GPIO output enable to the data field

     GPIO_VAPI_RGPIO_INTE (4)
          Set the next interrupt to the data field

     GPIO_VAPI_RGPIO_PTRIG (5)
          Set the next trigger to the data field

     GPIO_VAPI_RGPIO_AUX (6)
          Set the next auxiliary input to the data field

     GPIO_VAPI_RGPIO_CTRL (7)
          Set th next control input to the data field

A Guide to OR1KSIM Internals
****************************

These are notes to help those wanting to extend OR1KSIM. This section assumes the use of a tag file, so file locations of entities' definitions are not in general provided. For more on tags, see the Linux manual page for etags. A tag file can be created with:

     make tags

Coding Conventions for OR1KSIM
==============================

This chapter provides some guidelines for coding, to facilitate extensions to OR1KSIM

GNU Coding Standard
     Code should follow the GNU coding standard for C (http://www.gnu.org/prep/standards/. If in doubt, put your code through the indent program.

#include headers
     All C source code files should include config.h before any other file.

     This should be followed by inclusion of any system headers (but see the comments about portability and port.h below) and then by any OR1KSIM package headers.

     If port.h is required, it should be the first package header to be included after the system headers.

     All C source code and header files should directly include any system or package header they depend on, i.e. not rely on any other header having already included it. The two exceptions are

      1. All header files may assume that config.h has already been included.

      2. System headers which impose portability problems should be included by using the package header port.h, rather than the system headers themselves. This is the case for code requiring

            * strndup (from string.h)

            * Integer types (intN_t, uintN_t) (from inttypes.h).

            * isblank (from ctype.h)

#include files once only
     All include files should be protected by #ifndef to ensure their definitions are only included once. For instance a header file X-Y.H should surround its contents with:

          #ifndef X_Y__H
          #define X_Y__H

          <body of the include file>

          #endif  /* X_Y__H */

Avoid typedef
     The GNU coding style for C does not have a clear way to distinguish between user type name and user variables. For this reason typedef should be avoided except for the most ubiquitous user defined types. This makes the code much easier to read.

     There are some typedef declarations in the argtable2 library and the ELF and COFF headers, because this code is taken from other places.

     Within OR1KSIM legacy uses of typedef have largely been purged, except in the Custom Unit Compiler (see Custom Unit Compiler (CUC) Configuration).

     The remaining uses of typedef occur in two places:

       * port/port.h defines types to replace those in header files that are not available (character functions, string duplication, integer types).

          cpu/or1k/arch.h defines types for the key OR1KSIM entities: addresses (oraddr_t), unsigned register values (uorreg_t) and signed register (orreg_t) values.

     Where new types are defined, they should appear in one of these two files as appropriate. OR1KSIM specific types appearing in arch.h should always have the suffix _h.

Don't begin names with underscore
     Names beginning with _ are intended to be part of the C infrastructure. They should not be used in the simulator code.

Keep Non-global top level entities static
     All top level entities (functions, variables), which are not explicitly part of a global interface should be declared static. This ensures that unwanted connections are not inadvertently built across the program.

Use of inline
     Code should not be declared inline. Modern compilers can work out for themselves what is best in this respect.

Initialization
     All data structures should be explicitly initialized. In particular code should not rely on static data structures being initialized to zero.

     The rationale is that in future static data structures may become dynamic. This has been a particular source of bugs in OR1KSIM historically.

     A specific case is with new peripherals, which should always include a start function to pre-initialize all configuration parameters to sensible defaults

Configuration Validation
     All configuration values should be validated, preferably when encountered, if not when the section is closed, or otherwise at run time when the parameter is first used.

Global Data Structures
======================

config
     The global variable config of type struct config holds the configuration data for some of the OR1KSIM components which are always present. At present the components are:

       * The simulator defined in section sim (see Simulator Configuration).

       * The Verification API (VAPI) defined  in section vapi (see Verification API (VAPI) Configuration).

       * The Custom Unit Compiler (CUC), defined in section cuc (see Custom Unit Compiler (CUC) Configuration).

       * The CPU, defined in section cpu (see CPU Configuration).

       * The data cache (but not the instruction cache), defined in section dc (see Cache Configuration).

       * The power management unit, defined in section pm (see Power Management Configuration).

       * The programmable interrupt controller, defined in section pic (see Interrupt Configuration).

       * Branch prediciton, defined in section bpb (see Branch Prediction Configuration).

       * The debug unit, defined in section debug (see Debug Interface Configuration).

     This struct is made of a collection of structs, one for each component. For example the simulator configuration is held in config.sim.

config
     This is a linked list of data structures holding configuration data for all sections which are not held in the main config data structure. In general these are components (such as peripherals and memory) which may occur multiple times. However it also handles some architectural components which may occur only once, such as the memory management units, the instruction cache, the interrupt controller and branch prediction.

runtime
     The global variable runtime of type struct runtime holds all the runtime information about the simulation. To access this variable, sim-config.h must be included.

     This struct is itself made of 3 other structs, cpu (for CPU run time state), vapi (for Verification API state) and cuc (for Custom Unit Compiler state).

Concepts
========

Output Redirection
     The current output stream is held in runtime.cpu.fout. Output should be explicitly written to this stream, or may use the PRINTF macro, which will write its arguments to this output stream.

Reset Hooks
     Any peripheral may register a routine to be called when the the processor is reset by calling reg_sim_reset, providing a function and pointer to a data structure as arguments. On reset that function will be called with the data stucture pointer as argument.

Internal Debugging
==================

The function debug is like printf, but with an extra first argument, which is the debug level. If the debug level specified in the simulator configuration (see Simulator Behavior) is greater than or equal to this value, the remaining arguments are printed to the current output stream (see Output Redirection).

GNU Free Documentation License
******************************

     [file fdl-1.2.texi not included]