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-elf-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-2011-01-05.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-2011-01-05/configure --target=or32-elf ...

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.

For testing (using `make check'), the `--target' parameter may be
specified, to allow the target tool chain to be selected.  If not
specified, it will default to `or32-elf', which is the same prefix used
with the standard OpenRISC toolchain installation script.

A number of Or1ksim specific 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-unsigned-xori'
`--disable-unsigned-xori'
     Historically, `l.xori', has sign extended its operand.  This is
     inconsistent with the other logical opcodes (`l.andi', `l.ori'),
     but in the absence of `l.not', it allows a register to be inverted
     in a single instruction using:

          `l.xori  rD,rA,-1'

     This flag causes Or1ksim to treat the immediate operand as
     unsigned (i.e to zero-extend rather than sign-extend).

     The default is to sign-extend, so that existing code will continue
     to work.

          Caution: The GNU compiler tool chain makes heavy use of this
          instruction.  Using unsigned behavior will require the
          compiler to be modified accordingly.

          This option is provided for experimentation.  A future
          version of OpenRISC may adopt this more consistent behavior
          and also provide a `l.not' opcode.

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


A number of configuration flags have been removed since version 0.3.0,
because they led to invalid behavior of Or1ksim.  Those removed are:

`--enable-arith-flag'
`--disable-arith-flag'
     If enabled, this option caused certain instructions to set the flag
     (`F' bit) in the supervision register if the result were zero.
     The instructions affected by this were `l.add', `l.addc',
     `l.addi', `l.and' and `l.andi'.

     If set, this caused incorrect behavior.  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'.

`--enable-ov-flag'
`--disable-ov-flag'
     This flag caused certain instructions to set the overflow flag.
     If not, those instructions would not set the overflow flat.  The
     instructions affected by this were `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'.

     This guaranteed incorrect behavior.  The OpenRISC 1000 architecture
     specification defines which flags are set by which instructions.

     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.



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-elf-sim', `or32-elf-psim' and `or32-elf-mpsim', the Or1ksim
library, `libsim', the header file, `or1ksim.h' and this documentation
in `info' format.

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

Full details of outstanding issues may be found in the `NEWS' file in
the main directory of the distribution.  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 bugtracker.

The following issues are long standing and unlikely to be fixed in
Or1ksim in the near future.

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

   * 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!



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

2 Usage
*******

* Menu:

* Standalone Simulator::
* Profiling Utility::
* Memory Profiling Utility::
* Trace Generation::
* Simulator Library::
* Ethernet TUN/TAP Interface::
* l.nop Support::


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

2.1 Standalone Simulator
========================

The general form the standalone command is:

     or32-elf-sim [-vhiqVt] [-f FILE] [--nosrv] [--srv=[N]]
                      [-m <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.

`-i'
`--interactive'
     After starting, drop into the Or1ksim interactive command shell.

`-q'
`--quiet'
     Do not generate any information messages, only error messages.

`-V'
`--verbose'
     Generate extra output messages (equivalent of specifying the
     "verbose" option in the simulator configuration section (see *note
     Simulator Behavior: Simulator Behavior.).

`-t'
`--trace'
     Dump instruction just executed and any register/memory location
     chaged after each instruction (one line per instruction).

`--trace-physical'
`--trace-virtual'
     When tracing instructions, show the physical address
     (`--trace-physical') and/or the virtual address
     (`--trace-virtual') of the instruction being executed.  Both flags
     may be specified, in which case both physical and virtual
     addresses are shown, physical first.

          Note: Either or both flags may be specified without
          `--trace', to indicate how addresses should be shown if
          subsequently enabled by a `SIGUSER1' signal or `l.nop 8'
          opcode (*note Trace Generation: Trace Generation.).

`-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 "Remote Serial Protocol" 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 "Remote Serial Protocol" debug server.  This
     overrides any setting specified in the configuration file.  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.

`-m SIZE'
`--memory=SIZE'
     Configure a memory block of SIZE bytes, starting at address zero.
     The size may be followed by `k', `K', `m', `M', `g', `G', to
     indicate kilobytes (2^10 bytes), megabytes (2^20 bytes) and
     gigabytes (2^30 bytes).

     This is mainly intended for use when Or1ksim is used without a
     configuration file, to allow just the processor and memory to be
     set up.  This is the equivalent of specifying a configuration
     memory section with `baseaddr = 0' and `size = SIZE' and all other
     parameters taking their default value.

     If a configuration file is also used, it should be sure not to
     specify an overlapping memory block.

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

`--report-memory-errors'
     By default all exceptions are now handled silently.  If this
     option is specified, bus exceptions will be reported with a
     message to standard error indicating the address at which the
     exception occurred.

     This was the default behaviour up to Or1ksim 0.4.0.  This flag is
     provided for those who wish to keep that behavior.

`--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-elf-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: Trace Generation,  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-elf-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: Trace Generation,  Next: Simulator Library,  Prev: Memory Profiling Utility,  Up: Usage

2.4 Trace Generation
====================

An execution trace can be generated at run time with options passed by
the command line, or via the operating system's signal passing
mechanism, or by `l.nop' opcodes in an application program.

The following flag can be used to create an execution dump.

`-t'
`--trace'
     Dump instruction just executed and any register/memory location
     changed after each instruction (one line per instruction).  Each
     line starts with either "S" or "U" to indicate whether the
     processor was in supervisor or user mode _when the instruction
     completed_.  It is worth bearing in mind that tracing happens at
     completion of instruction execution and shows the state at that
     time.

Passing a signal `SIGUSR1' while the simulator is running toggles trace
generation. This can be done with the following command, assuming
Or1ksim's executable name is `or32-elf-sim':

     pkill -SIGUSR1 or32-elf-sim

This is useful in the case where trace output is desired after a
significant amount of simulation time, where it would be inconvenient to
generate trace up to that point.

If the `pkill' utility is not available, the `kill' utility can be used
if Or1ksim's process number is known. Use the following to determine
the process ID of the `or32-elf-sim' and then send the `SIGUSR1'
command to toggle execution trace generation:

     ps a | grep or32-elf-sim
     kill -SIGUSR1 _process-number_

Tracing can also be enabled and disabled from within a target program
using the `l.nop 8' and `l.nop 9' opcodes to enable and disable tracing
respectively.

By default tracing will show the virtual address of each instruction
traced.  This may be controlled by two options, `--trace-physical' to
show the physical address and/or `--trace-virtual' to show the virtual
address. If neither is specified, the virtual address is shown.

     Note: Either or both flags may be specified without `--trace', to
     indicate how addresses should be shown if subsequently enabled by a
     `SIGUSER1' signal or `l.nop 8' opcode.


File: or1ksim.info,  Node: Simulator Library,  Next: Ethernet TUN/TAP Interface,  Prev: Trace Generation,  Up: Usage

2.5 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 (int ARGC, char *ARGV, void
          *CLASS_PTR, int (*UPR)(void *CLASS_PTR, unsigned long int
          ADDR, unsigned char MASK[], unsigned char RDATA[], int
          DATA_LEN), int (*UPW)(void *CLASS_PTR, unsigned long int
          ADDR, unsigned char MASK[], unsigned char WDATA[], int
          DATA_LEN))
     The initialization function is supplied with a vector of arguments,
     which are interpreted as arguments to the standalone version (see
     *note Standalone Simulator: Standalone Simulator.), 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.

     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.  Both UPW and UPR should return zero on success and
     non-zero otherwise.  At the present time the meaning of non-zero
     values is not defined but this may change in the future.

     MASK indicates which bytes in the data are to be written or read.
     Bytes to be read/written should have 0xff set in MASK.  Otherwise
     the byte should be zero.  The adddress, ADDR, is the _full_
     address, since the upcall function must handle all generic
     devices, using the full address for decoding.

     Endianness is not a concern, since Or1ksim is transferring byte
     vectors, not multi-byte values.

     The result indicates whether the initialization was successful.
     The integer values are available as an `enum or1ksim', with
     possible values `OR1KSIM_RC_OK' and `OR1KSIM_RC_BADINIT'.

          Caution: This is a change from versions 0.3.0 and 0.4.0.  It
          further simplifies the interface, and makes Or1ksim more
          consistent with payload representation in SystemC TLM 2.0.

          Note: The current implementation of Or1ksim always transfers
          single words (4 bytes), using masks if smaller values are
          required.  In this it mimcs the behavior of the WishBone bus.


 -- `or1ksim.h': int or1ksim_run (double DURATION)
     Run the simulator for the simulated duration specified (in
     seconds).  A duration of -1 indicates `run forever'

     The result indicates how the run terminated.  The integer values
     are available as an `enum or1ksim', with possible values
     `OR1KSIM_RC_OK' (ran for the full duration), `OR1KSIM_RC_BRKPT'
     (terminated early due to hitting a breakpoint) and
     `OR1KSIM_RC_HALTED' (terminated early due to hitting `l.nop 1').


 -- `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 must be cleared separately by clearing the corresponding
     bit in the PICSR SPR.  Until the interrupt is cleared, any further
     interrupts on the same line will be ignored with a warning.  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'.  Until the interrupt is cleared, any
     further setting of interrupts on the same line will be ignored
     with a warning.  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.).


 -- `or1ksim.h': double or1ksim_jtag_reset ()
     Drive a reset sequence through the JTAG interface.  Return the
     (model) time taken for this action.  Remember that the JTAG has
     its own clock, which can be an order of magnitude slower than the
     main clock, so even a reset (5 JTAG cycles) could take 50
     processor clock cycles to complete.


 -- `or1ksim.h': double or1ksim_jtag_shift_ir (unsigned char *JREG, int
          NUM_BITS)
     Shift the supplied register through the JTAG instruction register.
     Return the (model) time taken for this action.  The register is
     supplied as a byte vector, with the least significant bits in the
     least significant byte.  If the total number of bits is not an
     exact number of bytes, then the odd bits are found in the least
     significant end of the highest numbered byte.

     For example a 12-bit register would have bits 0-7 in byte 0 and
     bits 11-8 in the least significant 4 bits of byte 1.


 -- `or1ksim.h': double or1ksim_jtag_shift_dr (unsigned char *JREG, int
          NUM_BITS)
     Shift the supplied register through the JTAG data register.
     Return the (model) time taken for this action.  The register is
     supplied as a byte vector, with the least significant bits in the
     least significant byte.  If the total number of bits is not an
     exact number of bytes, then the odd bits are found in the least
     significant end of the highest numbered byte.

     For example a 12-bit register would have bits 0-7 in byte 0 and
     bits 11-8 in the least significant 4 bits of byte 1.


 -- `or1ksim.h': int or1ksim_read_mem (unsigned long int ADDR, unsigned
          char *BUF, int LEN)
     Read LEN bytes from ADDR, placing the result in BUF.  Return LEN
     on success and 0 on failure.

          Note: This function was added in Or1ksim 0.5.0.


 -- `or1ksim.h': int or1ksim_write_mem (unsigned long int ADDR, const
          unsigned char *BUF, int LEN)
     Write LEN bytes to ADDR, taking the data from BUF.  Return LEN on
     success and 0 on failure.

          Note: This function was added in Or1ksim 0.5.0.


 -- `or1ksim.h': int or1ksim_read_spr (int SPRNUM, unsigned long int
          *SPRVAL_PTR)
     Read the SPR specified by SPRNUM, placing the result in
     SPRVAL_PTR.  Return non-zero on success and 0 on failure.

          Note: This function was added in Or1ksim 0.5.0.


 -- `or1ksim.h': int or1ksim_write_spr (int SPRNUM, unsigned long int
          SPRVA)
     Write SPRVAL to the SPR specified by SPRNUM.  Return non-zero on
     success and 0 on failure.

          Note: This function was added in Or1ksim 0.5.0.


 -- `or1ksim.h': int or1ksim_read_reg (int REGNUM, unsigned long int
          *REGVAL_PTR)
     Read the general purpose register specified by REGNUM, placing the
     result in REGVAL_PTR.  Return non-zero on success and 0 on failure.

          Note: This function was added in Or1ksim 0.5.0.


 -- `or1ksim.h': int or1ksim_write_reg (int REGNUM, unsigned long int
          REGVA)
     Write REGVAL to the general purpose register specified by REGNUM.
     Return non-zero on success and 0 on failure.

          Note: This function was added in Or1ksim 0.5.0.


 -- `or1ksim.h': void or1ksim_set_stall_state (int STATE)
     Set the processor's state according to STATE (1 = stalled, 0 = not
     stalled).

          Note: This function was added in Or1ksim 0.5.0.


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: Ethernet TUN/TAP Interface,  Next: l.nop Support,  Prev: Simulator Library,  Up: Usage

2.6 Ethernet TUN/TAP Interface
==============================

When an Ethernet peripheral is configured (*note Ethernet
Configuration: Ethernet Configuration.), one option is to tunnel
traffic through a TUN/TAP interface.  The low level TAP interface is
used to tunnel raw Ethernet datagrams.

The TAP interface can then be connected to a physical Ethernet through a
bridge, allowing the Or1ksim model to connect to a physical network.
This is particularly when Or1ksim is running the OpenRISC Linux kernel
image.

This section explains how to set up a bridge for use by Or1ksim. It does
require superuser access to the host machine (or at least the relevant
network capabilities). A system administrator can modify these
guidelines so they are executed on reboot if appropriate.

* Menu:

* Setting Up a Persistent TAP device::
* Establishing a Bridge::
* Opening the Firewall::
* Disabling Ethernet Filtering::
* Networking from OpenRISC Linux and BusyBox::
* Tearing Down a Bridge::


File: or1ksim.info,  Node: Setting Up a Persistent TAP device,  Next: Establishing a Bridge,  Up: Ethernet TUN/TAP Interface

2.6.1 Setting Up a Persistent TAP device
----------------------------------------

TUN/TAP devices can be created dynamically, but this requires superuser
privileges (or at least `CAP_NET_ADMIN' capability).  The solution is
to create a persistent TAP device.  This can be done using either
`openvpn' or `tunctl'.  In either case the package must be installed on
the host system.  Using `openvpn', the following would set up a TAP
interface for a specified user and group.

     openvpn --mktun --dev tap_n_ --user _username_ --group _groupname_


File: or1ksim.info,  Node: Establishing a Bridge,  Next: Opening the Firewall,  Prev: Setting Up a Persistent TAP device,  Up: Ethernet TUN/TAP Interface

2.6.2 Establishing a Bridge
---------------------------

A bridge is a "virtual" local area network interfaces, subsuming two or
more existing network interfaces.  In this case we will bridge the
physical Ethernet interface of the host with the TAP interface that
will be used by Or1ksim.

The Ethernet and TAP must lose their own individual IP addresses (by
setting them to 0.0.0.0) and are replaced by the IP address of the
bridge interface. To do this we use the `bridge-utils' package, which
must be installed on the host system. These commands are require
superuser privileges or `CAP_NET_ADMIN' capability. To create a new
interface `br_n_' the following commands are appropriate.

     brctl addbr br_n_
     brctl addif br_n_ eth_x_
     brctl addif br_n_ tap_y_

     ifconfig eth_x_ 0.0.0.0 promisc up
     ifconfig tap_y_ 0.0.0.0 promisc up

     dhclient br_n_

The last command instructs the bridge to obtain its IP address, netmask,
broadcast address, gateway and nameserver information using DHCP.  In a
network without DHCP it should be replaced by `ifconfig' to set a
static IP address, netmask and broadcast address.

     Note: This will leave a spare dhclient process running in the
     background, which should be killed for tidiness. There is a
     technique to avoid this using `omshell', but that is beyond the
     scope of this guide.

     Note: It is not clear to the author why the existing interfaces
     need to be brought up in promiscuous mode, but it seems to cure
     various problems.


File: or1ksim.info,  Node: Opening the Firewall,  Next: Disabling Ethernet Filtering,  Prev: Establishing a Bridge,  Up: Ethernet TUN/TAP Interface

2.6.3 Opening the Firewall
--------------------------

Firewall rules should be added to ensure traffic flows freely through
the TAP and bridge interfaces. As superuser the following commands are
appropriate.

     iptables -A INPUT -i tap_y_ -j ACCEPT
     iptables -A INPUT -i br_n_ -j ACCEPT
     iptables -A FORWARD -i br_n_ -j ACCEPT


File: or1ksim.info,  Node: Disabling Ethernet Filtering,  Next: Networking from OpenRISC Linux and BusyBox,  Prev: Opening the Firewall,  Up: Ethernet TUN/TAP Interface

2.6.4 Disabling Ethernet Filtering
----------------------------------

Some systems may have ethernet filtering enabled (`ebtables',
`bridge-nf', `arptables') which will stop traffic flowing through the
bridge.

The easiest way to disable this is by writing zero to all `bridge-nf-*'
entries in `/proc/sys/net/bridge'. As superuser the following commands
will achieve this.

     cd /proc/sys/net/bridge
     for f in bridge-nf-*; do echo 0 > $f; done


File: or1ksim.info,  Node: Networking from OpenRISC Linux and BusyBox,  Next: Tearing Down a Bridge,  Prev: Disabling Ethernet Filtering,  Up: Ethernet TUN/TAP Interface

2.6.5 Networking from OpenRISC Linux and BusyBox
------------------------------------------------

The main use of this style of Ethernet interface to Or1ksim is when
running the OpenRISC Linux kernel with BusyBox. The following commands
in the BusyBox console window will configure the Ethernet interface
(assumed to be `eth0') and bring it up with a DHCP assigned address.

     ifconfig eth0
     ifup eth0

At this stage interface to IP addresses will work correctly.

For DNS to work the BusyBox system needs to know where to find a
nameserver.  Under BusyBox, `udhcp' does not configure
`/etc/resolv.conf' automatically.

The solution is to duplicate the nameserver entry from the
`/etc/resolv.conf' file of the host on the BusyBox system. A typical
file might be as follows:

     `nameserver 192.168.0.1'

It is convenient to make this permanent within the Linux initramfs. Add
the file as `arch/openrisc/support/initramfs/etc/resolv.conf' within
the Linux source tree and rebuild `vmlinux'. It will then be present
automatically.

One of the most useful functions that is possible is to mount the host
file system through NFS. For example, from the BusyBox console:

     mount -t nfs -o nolock 192.168.0.60:/home /mnt

Another useful technique is to telnet into the BusyBox system from the
host. This is particularly valuable when a console process locks up,
since the `xterm' console will not recognize ctrl-C. Instead the rogue
process can be killed from a telnet connection.


File: or1ksim.info,  Node: Tearing Down a Bridge,  Prev: Networking from OpenRISC Linux and BusyBox,  Up: Ethernet TUN/TAP Interface

2.6.6 Tearing Down a Bridge
---------------------------

There is little reason why a bridge should ever need to be torn down,
but if desired, the following commands will achieve the effect.

     ifconfig br_n_ down
     brctl delbr br_n_

     dhclient eth_x_

As before this will leave a spare `dhclient' process in the background
which should be killed.

If desired the TAP interface can be deleted using

     openvpn --rmtun -dev tap_y_

     Caution: The TAP interface should not be in use when running this
     command. For example any OpenRISC Linux/BusyBox sessions should be
     closed first.


File: or1ksim.info,  Node: l.nop Support,  Prev: Ethernet TUN/TAP Interface,  Up: Usage

2.7 l.nop Opcode Support
========================

The OpenRISC `l.nop' opcode can take a parameter.  This has no effect
on the semantics of the opcode, but can be used to trigger side effect
behavior in a simulator.  Within Or1ksim, the following parameters are
supported.

`l.nop 0'
     The equivalent to `l.nop' with no parameter. Has no side effects.

`l.nop 1'
     Execution of Or1ksim is terminated. This is used to implement the
     library `exit' functions.

`l.nop 2'
     Report the value in `r3' on the console as a 32-bit hex value.

`l.nop 3'
     In earlier versions of Or1ksim this treated `r3' as a pointer to a
     `printf' style format string, and regsiters `r4' through `r8' as
     parameters for that format string.

     This opcode is no longer supported, and has no effect if used.

`l.nop 4'
     The value in `r3' is printed to standard output as an ASCII
     character.  All library output routines are implemented using this
     opcode.

`l.nop 5'
     The statistics counters are reset.

`l.nop 6'
     The number of clock ticks since start of execution (a 64-bit
     value) is returned in `r11' (low 32 bits) and `r12' (high 32 bits).

`l.nop 7'
     The number of picoseconds per clock cycle is returned in `r11'.
     This is used with `l.nop 6' to implement timing functions.

`l.nop 8'
     Instruction tracing is turned on.

`l.nop 9'
     Instruction tracing is turned off.



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/.or1ksim' 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.  A reference example,
`sim.cfg', is included in the top level directory of the distribution.

* 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 `*/').


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

       <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 (*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'
     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.  Default `sim.profile'.

`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_file = ``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.  Default `sim.mprofile'.

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

`exe_bin_insn_log = 0|1'
     Enable logging of executed instructions to a file in binary format.
     This is helpful for off-line dynamic execution analysis.

          Note: Execution logs can be _very_ big.  For example, while
          booting the Linux kernel, version 2.6.34, a log file 1.2GB in
          size was generated.

`exe_bin_insn_log_file = FILENAME'
     Filename for the binary execution log filename if
     `exe_bin_insn_log' is enabled.  Default `exe-insn.bin'.

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

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

    `memory_order=strong'
          Same memory ordering.  Bursts can be made, width can change.

    `memory_order=exact'
          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.



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

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

* Menu:

* CPU Configuration::
* Memory Configuration::
* Memory Management Configuration::
* Cache Configuration::
* Interrupt Configuration::
* Power Management Configuration::
* Branch Prediction Configuration::
* Debug Interface Configuration::


File: or1ksim.info,  Node: CPU Configuration,  Next: Memory Configuration,  Up: Core OpenRISC Configuration

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

          Note: This is particularly useful when an image is held in
          Flash at high memory (0xf0000000).  The EPH  bit can be set,
          so that interrupt vectors are basedf at 0xf0000000, rather
          than 0x0.

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

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

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

          Note: This field must be enabled, if execution execution flow
          tracking (field `history') has been requested in the simulator
          configuration section (*note Simulator Behavior: 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.

`hardfloat = 0|1'
     If 1, hardfloat instructions are enabled.  Default value 0.



File: or1ksim.info,  Node: Memory Configuration,  Next: Memory Management Configuration,  Prev: CPU Configuration,  Up: Core OpenRISC Configuration

3.3.2 Memory Configuration
--------------------------

Memory configuration is described in `section memory'.  This section
may appear multiple times, specifying multiple blocks of memory.

     Caution: The user may choose whether or not to enable a memory
     controller.  If a memory controller is enabled, then appropriate
     initalization code must be provided.  The section describing
     memory controller configuration describes the steps necessary for
     using smaller or larger memory sections (*note Memory Controller
     Configuration: Memory Controller Configuration.).

     The "uClibc" startup code initalizes a memory controller, assumed
     to be mapped at 0x93000000.  If a memory controller is _not_
     enabled, then the standard C library code will generate memory
     access errors.  The solution is to declare an additional writable
     memory block, mimicing the memory controller's register bank as
     follows.

          section memory
            pattern = 0x00
            type = unknown
            name = "MC shadow"
            baseaddr = 0x93000000
            size     = 0x00000080
            delayr = 2
            delayw = 4
          end


The following parameters may be specified.

`type=random|pattern|unknown|zero|exitnops'
     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.  This is the default.

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

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

    `exitnops'
          Set the memory values to be an instruction used to signal end
          of simulation. This is useful for causing immediate end of
          simulation when PC corruption occurs.


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

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

          Note: 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"'.

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

     There is no requirement to set `ce' if a memory controller is not
     enabled.  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 (*note Memory Controller Configuration:
     Memory Controller Configuration.).

     There is no requirement to set `mc' if a memory controller is not
     enabled.  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.



File: or1ksim.info,  Node: Memory Management Configuration,  Next: Cache Configuration,  Prev: Memory Configuration,  Up: Core OpenRISC Configuration

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

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

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



File: or1ksim.info,  Node: Cache Configuration,  Next: Interrupt Configuration,  Prev: Memory Management Configuration,  Up: Core OpenRISC Configuration

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



File: or1ksim.info,  Node: Interrupt Configuration,  Next: Power Management Configuration,  Prev: Cache Configuration,  Up: Core OpenRISC Configuration

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

     The library interface (*note Simulator Library: Simulator Library.)
     provides different functions for setting the different types of
     interrupt, and a function to clear level sensitive interrupts. Edge
     sensitive interrupts must be cleared by clearing the corresponding
     bit in the PICSR SPR.

     Internal functions to set and clear interrupts are also provided
     for peripherals implemented within Or1ksim. *Note Interrupts
     Internal: Interrupts Internal for more details.

`use_nmi = 0|1'
     If 1 (true, the default), interrupt lines 0 and 1 are
     non-maskable. In other words the least significant 2 bits of the
     PICMR SPR are hard-wired to 1.  If 0 (false), all interrupt lines
     are treated as equivalent.

          Note: These are not non-maskable in the true sense that they
          will pre-empt other interrupts.  Rather they can never be
          masked out using the PICMR register. It is up the interrupt
          exception handler to give these interrupt lines priority, and
          indeed to decide on the priority order in general.



File: or1ksim.info,  Node: Power Management Configuration,  Next: Branch Prediction Configuration,  Prev: Interrupt Configuration,  Up: Core OpenRISC Configuration

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



File: or1ksim.info,  Node: Branch Prediction Configuration,  Next: Debug Interface Configuration,  Prev: Power Management Configuration,  Up: Core OpenRISC Configuration

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



File: or1ksim.info,  Node: Debug Interface Configuration,  Prev: Branch Prediction Configuration,  Up: Core OpenRISC Configuration

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

          Note: 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
          `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_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'.

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

`vapi_id = VALUE'
     VALUE specifies the value of the Verification API (VAPI) base
     address to be used with the debug unit.  *Note Verification API:
     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.



File: or1ksim.info,  Node: Peripheral Configuration,  Prev: Core OpenRISC Configuration,  Up: Configuration

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

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

* Menu:

* Memory Controller Configuration::
* UART Configuration::
* DMA Configuration::
* Ethernet Configuration::
* GPIO Configuration::
* Display Interface Configuration::
* Frame Buffer Configuration::
* Keyboard Configuration::
* Disc Interface Configuration::
* Generic Peripheral Configuration::


File: or1ksim.info,  Node: Memory Controller Configuration,  Next: UART Configuration,  Up: Peripheral Configuration

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

The memory controller used in Or1ksim is the component implemented at
OpenCores, and found in the top level SVN 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.

     Warning: There are known to be problems with the current memory
     controller, which currently is not included in the regression test
     suite. Users are advised not to use the memory controller in the
     current release.

     Caution: There is no initialization code in the standard "newlib"
     library.

     The standard "uClibc" library assumes a memory controller mapped
     at 0x93000000 and will initialize the memory controller to expect
     64MB memory blocks, and any memory declarations _must_ reflect
     this.

     If smaller memory blocks are declared with a memory controller,
     then sufficient memory will not be allocated by Or1ksim, but out of
     range memory accesses will not be trapped.  For example declaring a
     memory section from 0-4MB with a memory controller enabled would
     mean that accesses between 4MB and 64MB would be permitted, but
     having no allocated memory would likely cause a segmentation fault.

     If the user is determined to use smaller memories with the memory
     controller, then custom initialization code must be provided, to
     ensure the memory controller traps out-of-memory accesses.

The following parameters may be specified.

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

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

          Caution: 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 (*note Memory Configuration: Memory Configuration.).

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



File: or1ksim.info,  Node: UART Configuration,  Next: DMA Configuration,  Prev: Memory Controller Configuration,  Up: Peripheral Configuration

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

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

          Note: 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.  *Note Verification API:
     Verification API, for more details, which details the use of the
     VAPI with the UART.



File: or1ksim.info,  Node: DMA Configuration,  Next: Ethernet Configuration,  Prev: UART Configuration,  Up: Peripheral Configuration

3.4.3 DMA Configuration
-----------------------

The DMA controller used in Or1ksim is the component implemented at
OpenCores, and found in the top level SVN 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 (*note 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.  *Note Verification
     API: Verification API, for more details, which details the use of
     the VAPI with the DMA controller.



File: or1ksim.info,  Node: Ethernet Configuration,  Next: GPIO Configuration,  Prev: DMA Configuration,  Up: Peripheral Configuration

3.4.4 Ethernet Configuration
----------------------------

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

The Ethernet MAC used in Or1ksim corresponds to the Verilog
implementation in project "ethmac". It's source code can be found in
the top level SVN directory, `ethmac'.  It also forms part of the
OpenRISC reference 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.

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

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

          Note: 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 (*note DMA
          Configuration: DMA Configuration.).

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

`rtx_type = "file"|"tap"'
     Specifies whether to use a TUN/TAP interface or file interface
     (the default) to model the external connection of the Ethernet.

     If a TUN/TAP interface is requested, Ethernet packets will be sent
     and received through the pesistent TAP interface specified in
     parameter `tap_dev' (see below).

     More details on configuring the TUN/TAP interface are given in the
     Usage section (*note Ethernet TUN/TAP Interface: Ethernet TUN/TAP
     Interface.).

     If a file interface (the default), is requested, the Ethernet will
     be modelled by reading and writing from and to the files specified
     in the `rxfile' and `txfile' parameters (see below).

          Caution: If a file interface is specified, Or1ksim will
          terminate once the receive file specified by `rxfile' is
          exhausted.

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

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

          Caution: Or1ksim will terminate once the RXFILE is exhausted.

`tap_dev = "TAP"'
     When `rtx_type' is `"tap"' (see above), TAP_DEV specifies the TAP
     device to use for communication.  This should be a persistent TAP
     device configured for the system (*note Ethernet TUN/TAP
     Interface: Ethernet TUN/TAP Interface.)

`phy_addr = VALUE'
     VALUE specifies the address for emulated ethernet PHY (default 0).
     If there are multiple Ethernet peripherals, they should each have a
     different PHY value.

`dummy_crc = 0|1'
     If 1 (true, the default), the length of the data transferred to
     the core will be increased by 4 bytes, as though the CRC were
     included.

          Note: This is for historical consistency with the OpenRISC
          Ethernet hardware MAC, which passes on the CRC in the data
          packet. This is unusual behavior for a MAC, but the OpenRISC
          Linux device drivers have been written to expect it.

`phy_addr = VALUE'
     VALUE specifies the address for emulated ethernet PHY (default 0).
     If there are multiple Ethernet peripherals, they should each have a
     different PHY value.

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



File: or1ksim.info,  Node: GPIO Configuration,  Next: Display Interface Configuration,  Prev: Ethernet Configuration,  Up: Peripheral Configuration

3.4.5 GPIO Configuration
------------------------

The GPIO used in Or1ksim is the component implemented at OpenCores, and
found in the top level SVN 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.  *Note Verification API:
     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.



File: or1ksim.info,  Node: Display Interface Configuration,  Next: Frame Buffer Con