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.

For testing (using @command{make check}), the @code{--target} parameter

@emph{must} be specified, to allow the target tool chain to be

selected. If the tools have been installed using the standard OpenRISC

script, then this should be set to @code{or32-elf}.

A number of @value{OR1KSIM} specific 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-unsigned-xori

@cindex @code{--enable-unsigned-xori}

@itemx --disable-unsigned-xori

@cindex @code{--disable-unsigned-xori}

@cindex exclusive-OR immediate operand

Historically, @code{l.xori}, has sign extended its operand. This is

inconsistent with the other logical opcodes (@code{l.andi},

@code{l.ori}), but in the absence of @code{l.not}, it allows a register

to be inverted in a single instruction using:

@example

@code{l.xori  rD,rA,-1}

@end example

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.

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

@code{l.not} opcode.

@end quotation

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

A number of configuration flags have been removed since version 0.3.0,

because they led to invalid behavior of Or1ksim. Those removed are:

@table @code

@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 caused certain instructions to set the flag

(@code{F} bit) in the supervision register if the result were zero.

The instructions affected by this were @code{l.add}, @code{l.addc},

@code{l.addi}, @code{l.and} and @code{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: @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}.

@item --enable-ov-flag

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

@itemx --disable-ov-flag

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

@cindex overflow flag setting by instructions

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

This guaranteed incorrect behavior.  The OpenRISC 1000 architecture

specification defines which flags are set by which instructions.

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.

@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

@cindex floating point support

There is no support for single precision floating point instructions in

@value{OR1KSIM} if configured in the CPU (@pxref{CPU Configuration, ,

CPU Configuration}).  These are implemented using the floating point

support in the host C library, which will usually be IEEE 745 compliant.

There is at present no support for double precision floating point

instructions, since these are meaningless with 32-bit registers.

Floating point support within OpenRISC is intended to follow IEEE 745,

which offers a degree of configurability. However at present the FPSCR

register is not supported, so there is no mechanism for configuring

floating point behavior. Thus the default functionality of the host C

library will be used.

@item

@cindex floating point multiply and add

@cindex lf.madd.s

The single precision floating point multiply and add instruction,

@code{lf.madd.s}, is not clearly specified in the original architectural

manual. User should consult the @cite{OpenRISC 1200 version 2

Supplementary Programmer's Reference Manual} for a specification of the

functionality implemented.

@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}

@cindex Remote Serial Protocol, @code{--nosrv}

Do not start up the @dfn{Remote Serial Protocol} 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}

@cindex Remote Serial Protocol, @code{--srv}

Start up the @dfn{Remote Serial Protocol} debug server.  This

overrides any setting specified in the configuration file.  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

@deftypefn {@file{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.

@end deftypefn

@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_ir (unsigned

char *@var{jreg}, int @var{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.

@end deftypefn

@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_dr (unsigned

char *@var{jreg}, int @var{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.

@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/.or1ksim} 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{*/}).

@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