Subversion Repositories openrisc

\input texinfo   @c -*- texinfo -*-

@setfilename or1ksim.info

@afourpaper

@include version.texi

@include config.texi

@dircategory Embedded development

@direntry

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

                                        Simulator

@end direntry

@copying

This file documents the OpenRISC Architectural Simulator, @value{OR1KSIM}.

Copyright @copyright{} 2008, 2009 Embecosm Limited.

@quotation

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

@end quotation

@end copying

@setchapternewpage on

@settitle @value{OR1KSIM} User Guide

@syncodeindex fn cp

@syncodeindex vr cp

@titlepage

@title @value{OR1KSIM} User Guide

@author Jeremy Bennett

@author Embecosm Limited

@author Issue 1 for @value{OR1KSIM} @value{VERSION}

@page

@vskip 0pt plus 1filll

@insertcopying

Published by Embecosm Limited

@end titlepage

@contents

@node Top

@c Perhaps this should be the title of the document (but only for info,

@c not for TeX).  Existing GNU manuals seem inconsistent on this point.

@top Scope of this Document

This document is the user guide for @value{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::

@end menu

@node Installation

@chapter Installation

@cindex installing @value{OR1KSIM}

Installation follows standard GNU protocols.

@menu

* Preparation::

* Configuring the Build::

* Build and Install::

* Known Issues::

@end menu

@node Preparation

@section Preparation

Unpack the software and create a @emph{separate} directory in which to

build it:

@example

@kbd{tar jxf or1ksim-@value{VERSION}.tar.bz2}

@kbd{mkdir builddir_or1ksim}

@kbd{cd builddir_or1ksim}

@end example

@node Configuring the Build

@section Configuring the Build

Configure the software using the @command{configure} script in the

main directory.

The most significant argument is @code{--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

@example

@kbd{../or1ksim-@value{VERSION}/configure --target=or32-uclinux ...}

@end example

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

to GNU @command{configure} scripts.  Use @kbd{configure --help} to see

all the options.  The most useful is @code{--prefix} to specify a

directory for installation of the tools.

A number of @value{OR1KSIM} features in the simulator do require enabling at

configuration.  These include

@table @code

@item --enable-profiling

@cindex @code{--enable-profiling}

@itemx --disable-profiling

@cindex @code{--disable-profiling}

If enabled, @value{OR1KSIM} is compiled for profiling with

@command{gprof}.  This is disabled by default.  Only really of value for

developers of @value{OR1KSIM}.

@item --enable-execution=simple

@itemx --enable-execution=complex

@itemx --enable-execution=dynamic

@cindex @code{--enable-execution}

@cindex simple model

@cindex complex model

@cindex dynamic model

@value{OR1KSIM} has developed to improve functionality and

performance.  This feature allows three versions of @value{OR1KSIM} to be built

@table @code

@item --enable-execution=simple

Build the original simple interpreting simulator

@item --enable-execution=complex

Build a more complex interpreting simulator.  Experiments suggest this

is 50% faster than the simple simulator.  This is the default.

@item --enable-execution=dynamic

Build a dynamically compiling simulator.  This is the way many modern ISS are

built.  This represents a work in progress.  Currently @value{OR1KSIM} will

compile, but segfaults if configured with this option.

@end table

The default is @code{--enable-execution=complex}.

@item --enable-ethphy

@cindex @code{--enable-ethphy}

@itemx --disable-ethphy

@cindex @code{--disable-ethphy}

@cindex Ethernet via socket, enabling

@cindex enabling Ethernet via socket

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

@code{ethernet} section of the configuration file.  @xref{Ethernet

Configuration, , Ethernet Configuration}.

The default is for this to be disabled.

@item --enable-range-stats

@cindex @code{--enable-range-stats}

@itemx --disable-range-stats

@cindex @code{--disable-range-stats}

@cindex statistics, register over time

@cindex register over time statistics

If enabled, this option allows statistics to be collected to analyse

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

@item --enable-ov-flag

@cindex @code{--enable-ov-flag}

@itemx --disable-ov-flag

@cindex @code{--disable-ov-flag}

@cindex overflow flag setting by instructions

If enabled, this option causes instructions to set the overflow

flag.  The instructions affected by this are @code{l.add},

@code{l.addc}, @code{l.addi}, @code{l.and}, @code{l.andi},

@code{l.div}, @code{l.divu}, @code{l.mul}, @code{l.muli}, @code{l.or},

@code{l.ori}, @code{l.sll}, @code{l.slli}, @code{l.srl},

@code{l.srli}, @code{l.sra}, @code{l.srai}, @code{l.sub}, @code{l.xor}

and @code{l.xori}.

The default is for this to be disabled.

@quotation Caution

This appears a very dangerous option, to the extent of arguably being

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

architectural specification.  Within the above list, the arithmetic

instructions (@code{l.add}, @code{l.addc}, @code{l.addi},

@code{l.div}, @code{l.divu}, @code{l.mul}, @code{l.muli} and

@code{l.sub}), together with @code{l.addic} which is missed out, set

the overflow flag.  All the others (@code{l.and}, @code{l.andi},

@code{l.or}, @code{l.ori}, @code{l.sll}, @code{l.slli}, @code{l.srl},

@code{l.srli}, @code{l.sra}, @code{l.srai}, @code{l.xor} and

@code{l.xori}) do not.

Thus it is impossible to get correct behavior whichever way this option is

set.

@end quotation

@item --enable-arith-flag

@cindex @code{--enable-arith-flag}

@itemx --disable-arith-flag

@cindex @code{--disable-arith-flag}

@cindex flag setting by instructions

If enabled, this option causes instructions to set the flag (@code{F} bit) in

the supervision register.  The instructions affected by this are @code{l.add},

@code{l.addc}, @code{l.addi}, @code{l.and} and @code{l.andi}.

The default is for this to be disabled.

@quotation Caution

As with @code{--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: @code{l.sfeq}, @code{l.sfeqi}, @code{l.sfges}, @code{l.sfgesi},

@code{l.sfgeu}, @code{l.sfgeui}, @code{l.sfgts}, @code{l.sfgtsi},

@code{l.sfgtu}, @code{l.sfgtui}, @code{l.sfles}, @code{l.sflesi},

@code{l.sfleu}, @code{l.sfleui}, @code{l.sflts}, @code{l.sfltsi},

@code{l.sfltu}, @code{l.sfltui}, @code{l.sfne} and @code{l.sfnei}.

The flags are correctly set (irrespective of @code{--enable-arith_flag}).

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

@code{--enable-arith-flag} should never be used.

@end quotation

@item --enable-debug

@cindex @code{--enable-debug}

@itemx --disable-debug

@cindex @code{--disable-debug}

@cindex debugging enabled (Argtable2)

@cindex Argtable2 debugging

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 @value{OR1KSIM} user.

@item --enable-all-tests

@cindex @code{--enable-all-tests}

@itemx --disable-all-tests

@cindex @code{--disable-all-tests}

@cindex all tests enabled

@cindex tests, all enabled.

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 @command{make check}.

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

get the missing test(s) working.

@end table

@node Build and Install

@section Building and Installing

Build the tool with:

@example

@kbd{make all}

@end example

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

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

@example

@kbd{make check}

@end example

Install the tool with:

@example

@kbd{make install}

@end example

This will install the three variations of the @value{OR1KSIM} tool,

@command{or32-uclinux-sim}, @command{or32-uclinux-psim} and

@command{or32-uclinux-mpsim}, the @value{OR1KSIM} library, @file{libsim}, the

header file, @file{or1ksim.h} and this documentation in @command{info} format.

@quotation Note

Testing @value{OR1KSIM} with @kbd{make check} is not yet supported.

@end quotation

The documentation may be created and installed in alternative formats (PDF,

Postscript, DVI, HTML) with for example:

@example

@kbd{make pdf}

@kbd{make install-pdf}

@end example

@node Known Issues

@section Known Problems and Issues

The following problems and issues are known about with @value{OR1KSIM}

@value{VERSION}.  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 @url{http://www.opencores.org/ptracker.cgi/view/or1k/398}.

@itemize @bullet

@item

The Supervision Register Little Endian Enable (LEE) bit is

ignored.  @value{OR1KSIM} can be built for either little endian or big endian

use, but that behavior cannot be changed dynamically.

@item

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

pipeline.  This means that if the processor is stalled, the value should

subsequently read back as 0, until the processor is unstalled and able

to refill its pipeline.  By default @value{OR1KSIM} always reports back the value

of NPC, even when it has been written while stalled.

There is now an option, @code{--strict-npc}, which will enforce this

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

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

@item

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

there is currently no way for @value{OR1KSIM} to report that name back to the

user (for example to identify which memory block corresponds to a

particular access).

@item

@value{OR1KSIM} allows the processor to be stalled (from the command

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

meaningless operation.

@item

@value{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!

@item

There is no support for floating point instructions currently in

@value{OR1KSIM}.  However this is a work in progress and should be available in

the future.

@end itemize

@node Usage

@chapter Usage

@cindex running @value{OR1KSIM}

@menu

* Standalone Simulator::

* Profiling Utility::

* Memory Profiling Utility::

* Simulator Library::

@end menu

@node Standalone Simulator

@section Standalone Simulator

@cindex command line for @value{OR1KSIM} standalone use

The general form the standalone command is:

@example

or32-uclinux-sim [-vhi] [-f @var{file}] [--nosrv] [--srv=[@var{n}]] [-d @var{str}]

                 [--enable-profile] [--enable-mprofile] [@var{file}]

@end example

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

@code{-h} or @code{--help}.

@table @code

@item -v

@itemx --version

@cindex @code{-v}

@cindex @code{--version}

Print out the version and copyright notice for @value{OR1KSIM} and

exit.

@item -h

@itemx --help

@cindex @code{-h}

@cindex @code{--help}

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

@item -f @var{file}

@itemx --file @var{file}

@cindex @code{-f}

@cindex @code{--file}

Read configuration commands from the specified file, looking first in

the current directory, and otherwise in the @file{$HOME/.or1k}

directory.  If this argument is not specified, the file @file{sim.cfg}

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

error.  @xref{Configuration, , Configuration}, for detailed information

on configuring @value{OR1KSIM}.

@item --nosrv

@cindex @code{--nosrv}

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

in the configuration file.  This option may not be specified with

@code{--srv}.  If it is, a rude message is printed and the

@code{--nosrv} option is ignored.

@item --srv

@item --srv=@var{n}

@cindex @code{--srv}

Start up the debug server.  If the parameter, @var{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 @code{--nosrv}.  If it is, a rude message is

printed and the @code{--nosrv} option is ignored.

@item -d=@var{config_string}

@itemx --debug-config=@var{config_string}

@cindex @code{-d}

@cindex @code{--debug-config}

Enable selected debug messages in @value{OR1KSIM}.  This parameter is

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

source code for more details.

@item -i

@itemx --interactive

@cindex @code{-i}

@cindex @code{--interactive}

After starting, drop into the @value{OR1KSIM} interactive command

shell.

@item --strict-npc

@cindex @code{--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, @value{OR1KSIM} has always returned the value of the NPC,

irrespective of when it is changed.  If the @code{--strict-npc} option is

used, then @value{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 @value{OR1KSIM} behavior.  However at some

time in the future it will become the default.

@item --enable-profile

@cindex @code{--enable-profile}

Enable instruction profiling.

@item --enable-mprofile

@cindex @code{--enable-mprofile}

Enable memory profiling.

@end table

@node Profiling Utility

@section Profiling Utility

@cindex profiling for @value{OR1KSIM}

@cindex instruction profiling for @value{OR1KSIM}

This utility analyses instruction profile data generated by

@value{OR1KSIM}.  It may be invoked as a standalone command, or from

the @value{OR1KSIM} CLI.  The general form the standalone command is:

@example

or32-uclinux-profile [-vhcq] [-g=@var{file}]

@end example

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

@code{-h} or @code{--help}.

@table @code

@item -v

@itemx --version

@cindex @code{-v} (profiling utility)

@cindex @code{--version} (profiling utility)

Print out the version and copyright notice for the @value{OR1KSIM}

profiling utility and exit.

@item -h

@itemx --help

@cindex @code{-h} (profiling utility)

@cindex @code{--help} (profiling utility)

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

@item -c

@itemx --cumulative

@cindex @code{-c}

@cindex @code{--cumulative}

Show cumulative sum of cycles in functions

@item -q

@itemx --quiet

@cindex @code{-q}

@cindex @code{--quiet}

Suppress messages

@item -g=@var{file}

@itemx --generate=@var{file}

@cindex @code{-g}

@cindex @code{--generate}

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

@file{sim.profile} is used.

@end table

@node Memory Profiling Utility

@section Memory Profiling Utility

@cindex memory profiling version of @value{OR1KSIM}

This utility analyses memory profile data generated by

@value{OR1KSIM}.  It may be invoked as a standalone command, or from

the @value{OR1KSIM} CLI.  The general form the standalone command is:

@example

or32-uclinux-mprofile  [-vh] [-m=@var{m}] [-g=@var{n}] [-f=@var{file}] @var{from} @var{to}

@end example

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

@code{-h} or @code{--help}.

@table @code

@item -v

@itemx --version

@cindex @code{-v} (memory profiling utility)

@cindex @code{--version} (memory profiling utility)

Print out the version and copyright notice for the @value{OR1KSIM}

memory profiling utility and exit.

@item -h

@itemx --help

@cindex @code{-h} (memory profiling utility)

@cindex @code{--help} (memory profiling utility)

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

@item -m=@var{m}

@itemx --mode=@var{m}

@cindex @code{-m}

@cindex @code{--mode}

Specify the mode out output.  Permitted options are

@table @code

@item detailed

@itemx d

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

@item pretty

@itemx p

Pretty printed output.

@item access

@itemx a

Memory accesses only.

@item width

@itemx w

Access width only.

@end table

@item -g=@var{n}

@itemx --group=@var{n}

@cindex @code{-g}

@cindex @code{--group}

Group @math{2^n} bits of successive addresses together.

@item -f=@var{file}

@itemx --filename=@var{file}

@cindex @code{-f}

@cindex @code{--filename}

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

@file{sim.profile} is used.

@item @var{from}

@itemx @var{to}

@cindex memory profiling start address

@cindex memory profiling end address

@var{from} and @var{to} are respectively the start and end address of

the region of memory to be analysed.

@end table

@node Simulator Library

@section Simulator Library

@cindex library version of @value{OR1KSIM}

@value{OR1KSIM} may be used as a static of dynamic library,

@file{libsim.a} or @file{libsim.so}.  When compiling with the static

library, the flag, @code{-lsim} should be added to the link command.

The header file @file{or1ksim.h} contains appropriate declarations of

the functions exported by the @value{OR1KSIM} library.  These are:

@deftypefn {@file{or1ksim.h}} int or1ksim_init (const char

*@var{config_file}, const char *@var{image_file}, void *@var{class_ptr},

int (*@var{upr})(void *@var{class_ptr}, unsigned long int @var{addr},

unsigned char @var{mask}[], unsigned char @var{rdata}[], int

@var{data_len}), int (*@var{upw})(void *@var{class_ptr}, unsigned long

int @var{addr}, unsigned char @var{mask}[], unsigned char @var{wdata}[],

int @var{data_len}))

The initialization function is supplied with the name of a

configuration file, @var{config_file}, an executable image, @var{image_file}, a pointer to the calling

class, @var{class_ptr} (since the library may be used from C++) and

two up-call functions, one for reads, @var{upr}, and one for writes,

@var{upw}.

@xref{Configuration, , Configuration}, for detailed information on

configuring @value{OR1KSIM} and the format of the configuration file.

@var{upw} is called for any write to an address external to the model

(determined by a @code{generic} section in the configuration

file).  @var{upr} is called for any reads to an external address.  The

@var{class_ptr} is passed back with these upcalls, allowing the

function to associate the call with the class which originally

initialized the library.  Both @var{upw} and @var{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.

@var{mask} indicates which bytes in the data are to be written or

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

@var{mask}.  Otherwise the byte should be zero.  The adddress,

@var{addr}, is the @emph{full} address, since the upcall function must

handle all generic devices, using the full address for decoding.

Endianness is not completely transparent, since @value{OR1KSIM} is

transferring byte vectors, not multi-byte values.

@quotation Caution

This is a change from version 0.3.0. It simplifies the interface, and

makes @value{OR1KSIM} more consistent with payload representation in

SystemC TLM 2.0.

@end quotation

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

@end quotation

@end deftypefn

@deftypefn {@file{or1ksim.h}} int or1ksim_run (double  @var{duration})

Run the simulator for the simulated duration specified (in seconds).

@end deftypefn

@deftypefn {@file{or1ksim.h}} void or1ksim_reset_duration (double @var{duration})

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

@code{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 @code{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 @emph{now}, not the duration from the original

call to @code{or1ksim_run}).

@end deftypefn

@deftypefn {@file{or1ksim.h}} void  or1ksim_set_time_point ()

Set a timing point.  For use with @code{or1ksim_get_time_period}.

@end deftypefn

@deftypefn {@file{or1ksim.h}} double  or1ksim_get_time_period ()

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

call to @code{or1ksim_set_time_point}.

@end deftypefn

@deftypefn {@file{or1ksim.h}} int  or1ksim_is_le ()

Return 1 (logical true) if the @value{OR1KSIM} simulation is

little-endian, 0 otherwise.

@end deftypefn

@deftypefn {@file{or1ksim.h}} unsigned long int  or1ksim_clock_rate ()

Return the @value{OR1KSIM} clock rate (in Hz).  This is the value

specified in the configuration file.

@end deftypefn

@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt (int  @var{i})

Generate an edge-triggered interrupt on interrupt line @var{i}.  The interrupt

is then immediately cleared automatically.  A warning will be generated and the

interrupt request ignored if level sensitive interrupts have been configured

with the programmable interrupt controller (@pxref{Interrupt Configuration, ,

Interrupt Configuration}).

@end deftypefn

@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_set (int  @var{i})

Assert a level-triggered interrupt on interrupt line @var{i}.  The interrupt

must be cleared separately by an explicit call to

@code{or1ksim_interrupt_clear}.  A warning will be generated, and the interrupt

request ignored if edge sensitive interrupts have been configured with the

programmable interrupt controller (@pxref{Interrupt Configuration, , Interrupt

Configuration}).

@end deftypefn

@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_clear (int  @var{i})

Clear a level-triggered interrupt on interrupt line @var{i}, which was

previously asserted by a call to @code{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

(@pxref{Interrupt Configuration, , Interrupt Configuration}).

@end deftypefn

The libraries will be installed in the @file{lib} sub-directory of the

main installation directory (as specified with the @option{--prefix}

option to the @command{configure} script).

For example if the main installation directory is @file{/opt/or1ksim},

the library will be found in the @file{/opt/or1ksim/lib} directory.  It

is available as both a static library (@file{libsim.a}) and a shared

object (@file{libsim.so}).

To link against the library add the @option{-lsim} flag when linking

and do one of the following:

@itemize @bullet

@item

Add the library directory to the @code{LD_LIBRARY_PATH} environment

variable during execution.  For example:

@example

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

@end example

@item

Add the library directory to the @code{LD_RUN_PATH} environment

variable during linking.  For example:

@example

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

@end example

@item

Use the linker @option{--rpath} option and specify the library

directory when linking your program.  For example

@example

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

@end example

@item

Add the library directory to @file{/etc/ld.so.conf}

@end itemize

@node Configuration

@chapter Configuration

@cindex configuring @value{OR1KSIM}

@value{OR1KSIM} is configured through a configuration file.  This is specified

through the @code{-f} parameter to the @value{OR1KSIM} command, or passed as a

string when initializing the @value{OR1KSIM} library.  If no file is specified,

the default @file{sim.cfg} is used.  The file is looked for first in the

current directory, then in the @file{$HOME/.or1k} directory of the user.

@menu

* Configuration File Format::

* Simulator Configuration::

* Core OpenRISC Configuration::

* Peripheral Configuration::

@end menu

@node Configuration File Format

@section Configuration File Format

@cindex configuration file structure

The configuration file is a plain text file.

@menu

* Configuration File Preprocessing::

* Configuration File Syntax::

@end menu

@node Configuration File Preprocessing

@subsection Configuration File Preprocessing

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

@code{/*} and @code{*/}).

Configure files may be included, using

@example

include @var{filename_to_include}

@end example

@node Configuration File Syntax

@subsection Configuration File Syntax

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

form:

@example

section @var{section_name}

  <contents>...

end

@end example

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

@example

  @var{parameter} = @var{value}

@end example

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

@example

section memory

  type    = random

  pattern = 0x00

  name    = "FLASH"

  ...

end

@end example

Many parameters are optional and take reasonable default values if not

specified.  However there are some parameters (for example the

@code{ce} parameter in @code{@w{section memory}}) @emph{must} be

specified.

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

@code{=} sign), and end with the same keyword prefixed by

@code{end}.  Thus the ATA/ATAPI inteface (@code{@w{section ata}}) has a

@code{device} subsection, thus:

@example

section ata

  ...

  device 0

    type    = 1

    file = "@var{filename}"

    ...

  enddevice

  ...

end

@end example

Some sections (for example @code{@w{section sim}}) should appear only

once.  Others (for example @code{@w{section memory}} may appear

multiple times.

Sections may be omitted, @emph{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 @code{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 @value{OR1KSIM} command line (@pxref{Interactive Command Line, ,

Interactive Command Line}).

@quotation Tip

It generally clearer to have sections describing @emph{all}

components, with omitted functionality explicitly indicated by setting

the @code{enabled} parameter to 0

@end quotation

The following sections describe the various configuration sections and the

parameters which may be set in each.

@node Simulator Configuration

@section Simulator Configuration

@menu

* Simulator Behavior::

* Verification API Configuration::

* CUC Configuration::

@end menu

@node Simulator Behavior

@subsection Simulator Behavior

@cindex configuring the behavior of @value{OR1KSIM}

@cindex simulator configuration

@cindex @code{section sim}

Simulator behavior is described in @code{section sim}.  This section

should appear only once.  The following parameters may be specified.