Subversion Repositories openrisc_2011-10-31

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

@setfilename or1ksim.info

@afourpaper

@include version.texi

@include config.texi

@dircategory Embedded development

@direntry

* Or1ksim: (or32-elf-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

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

mkdir builddir_or1ksim

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

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

@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

may be specified, to allow the target tool chain to be selected.  If not

specified, it will default to @code{or32-elf}, which is the same prefix

used with the standard OpenRISC toolchain installation script.

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

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

make check

@end example

Install the tool with:

@example

make install

@end example

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

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

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

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

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

Postscript, DVI, HTML) with for example:

@example

make pdf

make install-pdf

@end example

@node Known Issues

@section Known Problems and Issues

Full details of outstanding issues may be found in the @file{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

@url{http://opencores.org/project,or1k,bugtracker}.

The following issues are long standing and unlikely to be fixed in

@value{OR1KSIM} in the near future.

@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

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

@end itemize

@node Usage

@chapter Usage

@cindex running @value{OR1KSIM}

@menu

* Standalone Simulator::

* Profiling Utility::

* Memory Profiling Utility::

* Trace Generation::

* Simulator Library::

* Ethernet TUN/TAP Interface::

* l.nop Support::

@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-elf-sim [-vhiqVt] [-f @var{file}] [--nosrv] [--srv=[@var{n}]]

                 [-m <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 -i

@itemx --interactive

@cindex @code{-i}

@cindex @code{--interactive}

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

shell.

@item -q

@itemx --quiet

@cindex @code{-q}

@cindex @code{--quiet}

Do not generate any information messages, only error messages.

@item -V

@itemx --verbose

@cindex @code{-V}

@cindex @code{--verbose}

Generate extra output messages (equivalent of specifying the ``verbose''

option in the simulator configuration section (see @pxref{Simulator Behavior, , Simulator Behavior}).

@item -t

@itemx --trace

@cindex @code{-t}

@cindex @code{--trace}

Dump instruction just executed and any register/memory location chaged

after each instruction (one line per instruction).

@item --trace-physical

@itemx --trace-virtual

@cindex @code{--trace-physical}

@cindex @code{--trace-virtual}

When tracing instructions, show the physical address

(@code{--trace-physical}) and/or the virtual address

(@code{--trace-virtual}) of the instruction being executed.  Both flags

may be specified, in which case both physical and virtual addresses are

shown, physical first.

@quotation Note

Either or both flags may be specified without @code{--trace}, to

indicate how addresses should be shown if subsequently enabled by a

@code{SIGUSER1} signal or @code{l.nop 8} opcode (@pxref{Trace

Generation, , Trace Generation}).

@end quotation

@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 -m @var{size}

@itemx --memory=@var{size}

@cindex @code{-m}

@cindex @code{--memory}

Configure a memory block of @var{size} bytes, starting at address

zero.  The size may be followed by @samp{k}, @samp{K}, @samp{m},

@samp{M}, @samp{g}, @samp{G}, to indicate kilobytes (@math{2^{10}}

bytes), megabytes (@math{2^{20}} bytes) and gigabytes (@math{2^{30}}

bytes).

This is mainly intended for use when @value{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 @code{baseaddr = 0} and @code{size = @var{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.

@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 --report-memory-errors

@cindex @code{--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 @value{OR1KSIM} 0.4.0.  This flag is

provided for those who wish to keep that behavior.

@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-elf-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-elf-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 Trace Generation

@section Trace Generation

@cindex trace generation of @value{OR1KSIM}

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 @code{l.nop} opcodes in an application program.

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

@table @code

@item -t

@itemx --trace

@cindex @code{-t}

@cindex @code{--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 @emph{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.

@end table

Passing a signal @code{SIGUSR1} while the simulator is running toggles

trace generation. This can be done with the following command, assuming

@value{OR1KSIM}'s executable name is @code{or32-elf-sim}:

@example

pkill -SIGUSR1 or32-elf-sim

@end example

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 @code{pkill} utility is not available, the @code{kill} utility

can be used if @value{OR1KSIM}'s process number is known. Use the

following to determine the process ID of the @code{or32-elf-sim} and

then send the @code{SIGUSR1} command to toggle execution trace

generation:

@example

ps a | grep or32-elf-sim

kill -SIGUSR1 @emph{process-number}

@end example

@cindex l.nop 8 (turn on tracing)

@cindex l.nop 8 (turn off tracing)

Tracing can also be enabled and disabled from within a target program

using the @code{l.nop 8} and @code{l.nop 9} opcodes to enable and

disable tracing respectively.

@cindex @code{--trace-physical}

@cindex @code{--trace-virtual}

By default tracing will show the virtual address of each instruction

traced.  This may be controlled by two options, @code{--trace-physical}

to show the physical address and/or @code{--trace-virtual} to show the

virtual address. If neither is specified, the virtual address is shown.

@quotation Note

Either or both flags may be specified without @code{--trace}, to

indicate how addresses should be shown if subsequently enabled by a

@code{SIGUSER1} signal or @code{l.nop 8} opcode.

@end quotation

@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 (int @var{argc}, @

           char *@var{argv}, 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 a vector of arguments,

which are interpreted as arguments to the standalone version (see

@pxref{Standalone Simulator, , Standalone Simulator}), 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}.

@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 a concern, since @value{OR1KSIM} is transferring byte

vectors, not multi-byte values.

The result indicates whether the initialization was successful.  The

integer values are available as an @code{enum or1ksim}, with possible

values @code{OR1KSIM_RC_OK} and @code{OR1KSIM_RC_BADINIT}.

@quotation Caution

This is a change from versions 0.3.0 and 0.4.0.  It further 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 @value{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).  A

duration of -1 indicates `run forever'

The result indicates how the run terminated.  The integer values are

available as an @code{enum or1ksim}, with possible values

@code{OR1KSIM_RC_OK} (ran for the full duration),

@code{OR1KSIM_RC_BRKPT} (terminated early due to hitting a breakpoint)

and @code{OR1KSIM_RC_HALTED} (terminated early due to hitting

@code{l.nop 1}).

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