\input texinfo @c -*- texinfo -*-
|
\input texinfo @c -*- texinfo -*-
|
@setfilename or1ksim.info
|
@setfilename or1ksim.info
|
@afourpaper
|
@afourpaper
|
@include version.texi
|
@include version.texi
|
@include config.texi
|
@include config.texi
|
@dircategory Embedded development
|
@dircategory Embedded development
|
@direntry
|
@direntry
|
* Or1ksim: (or32-elf-or1ksim). The OpenRISC 1000 Architectural
|
* Or1ksim: (or32-elf-or1ksim). The OpenRISC 1000 Architectural
|
Simulator
|
Simulator
|
@end direntry
|
@end direntry
|
|
|
@copying
|
@copying
|
This file documents the OpenRISC Architectural Simulator, @value{OR1KSIM}.
|
This file documents the OpenRISC Architectural Simulator, @value{OR1KSIM}.
|
|
|
Copyright @copyright{} 2008, 2009 Embecosm Limited.
|
Copyright @copyright{} 2008, 2009 Embecosm Limited.
|
|
|
@quotation
|
@quotation
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
any later version published by the Free Software Foundation; with no
|
any later version published by the Free Software Foundation; with no
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
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
|
Texts. A copy of the license is included in the section entitled ``GNU
|
Free Documentation License''.
|
Free Documentation License''.
|
@end quotation
|
@end quotation
|
@end copying
|
@end copying
|
|
|
@setchapternewpage on
|
@setchapternewpage on
|
@settitle @value{OR1KSIM} User Guide
|
@settitle @value{OR1KSIM} User Guide
|
|
|
@syncodeindex fn cp
|
@syncodeindex fn cp
|
@syncodeindex vr cp
|
@syncodeindex vr cp
|
|
|
@titlepage
|
@titlepage
|
@title @value{OR1KSIM} User Guide
|
@title @value{OR1KSIM} User Guide
|
@author Jeremy Bennett
|
@author Jeremy Bennett
|
@author Embecosm Limited
|
@author Embecosm Limited
|
@author Issue 1 for @value{OR1KSIM} @value{VERSION}
|
@author Issue 1 for @value{OR1KSIM} @value{VERSION}
|
|
|
@page
|
@page
|
@vskip 0pt plus 1filll
|
@vskip 0pt plus 1filll
|
@insertcopying
|
@insertcopying
|
|
|
Published by Embecosm Limited
|
Published by Embecosm Limited
|
@end titlepage
|
@end titlepage
|
|
|
@contents
|
@contents
|
|
|
@node Top
|
@node Top
|
@c Perhaps this should be the title of the document (but only for info,
|
@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.
|
@c not for TeX). Existing GNU manuals seem inconsistent on this point.
|
@top Scope of this Document
|
@top Scope of this Document
|
|
|
This document is the user guide for @value{OR1KSIM}, the OpenRISC 1000
|
This document is the user guide for @value{OR1KSIM}, the OpenRISC 1000
|
Architectural Simulator.
|
Architectural Simulator.
|
|
|
@menu
|
@menu
|
* Installation::
|
* Installation::
|
* Usage::
|
* Usage::
|
* Configuration::
|
* Configuration::
|
* Interactive Command Line::
|
* Interactive Command Line::
|
* Verification API::
|
* Verification API::
|
|
|
* Code Internals::
|
* Code Internals::
|
|
|
* GNU Free Documentation License:: The license for this documentation
|
* GNU Free Documentation License:: The license for this documentation
|
* Index::
|
* Index::
|
@end menu
|
@end menu
|
|
|
@node Installation
|
@node Installation
|
@chapter Installation
|
@chapter Installation
|
@cindex installing @value{OR1KSIM}
|
@cindex installing @value{OR1KSIM}
|
|
|
Installation follows standard GNU protocols.
|
Installation follows standard GNU protocols.
|
|
|
@menu
|
@menu
|
* Preparation::
|
* Preparation::
|
* Configuring the Build::
|
* Configuring the Build::
|
* Build and Install::
|
* Build and Install::
|
* Known Issues::
|
* Known Issues::
|
@end menu
|
@end menu
|
|
|
@node Preparation
|
@node Preparation
|
@section Preparation
|
@section Preparation
|
|
|
Unpack the software and create a @emph{separate} directory in which to
|
Unpack the software and create a @emph{separate} directory in which to
|
build it:
|
build it:
|
|
|
@example
|
@example
|
tar jxf or1ksim-@value{VERSION}.tar.bz2
|
tar jxf or1ksim-@value{VERSION}.tar.bz2
|
mkdir builddir_or1ksim
|
mkdir builddir_or1ksim
|
cd builddir_or1ksim
|
cd builddir_or1ksim
|
@end example
|
@end example
|
|
|
@node Configuring the Build
|
@node Configuring the Build
|
@section Configuring the Build
|
@section Configuring the Build
|
|
|
Configure the software using the @command{configure} script in the
|
Configure the software using the @command{configure} script in the
|
main directory.
|
main directory.
|
|
|
The most significant argument is @code{--target}, which should specify
|
The most significant argument is @code{--target}, which should specify
|
the OpenRISC 1000 32-bit architecture. If this argument is omitted, it will
|
the OpenRISC 1000 32-bit architecture. If this argument is omitted, it will
|
default to OpenRISC 1000 32-bit with a warning
|
default to OpenRISC 1000 32-bit with a warning
|
|
|
@example
|
@example
|
../or1ksim-@value{VERSION}/configure --target=or32-elf ...
|
../or1ksim-@value{VERSION}/configure --target=or32-elf ...
|
@end example
|
@end example
|
|
|
There are several other options available, many of which are standard
|
There are several other options available, many of which are standard
|
to GNU @command{configure} scripts. Use @kbd{configure --help} to see
|
to GNU @command{configure} scripts. Use @kbd{configure --help} to see
|
all the options. The most useful is @code{--prefix} to specify a
|
all the options. The most useful is @code{--prefix} to specify a
|
directory for installation of the tools.
|
directory for installation of the tools.
|
|
|
For testing (using @command{make check}), the @code{--target} parameter
|
For testing (using @command{make check}), the @code{--target} parameter
|
may be specified, to allow the target tool chain to be selected. If not
|
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
|
specified, it will default to @code{or32-elf}, which is the same prefix
|
used with the standard OpenRISC toolchain installation script.
|
used with the standard OpenRISC toolchain installation script.
|
|
|
A number of @value{OR1KSIM} specific features in the simulator do
|
A number of @value{OR1KSIM} specific features in the simulator do
|
require enabling at configuration. These include
|
require enabling at configuration. These include
|
|
|
@table @code
|
@table @code
|
@item --enable-profiling
|
@item --enable-profiling
|
@cindex @code{--enable-profiling}
|
@cindex @code{--enable-profiling}
|
@itemx --disable-profiling
|
@itemx --disable-profiling
|
@cindex @code{--disable-profiling}
|
@cindex @code{--disable-profiling}
|
If enabled, @value{OR1KSIM} is compiled for profiling with
|
If enabled, @value{OR1KSIM} is compiled for profiling with
|
@command{gprof}. This is disabled by default. Only really of value for
|
@command{gprof}. This is disabled by default. Only really of value for
|
developers of @value{OR1KSIM}.
|
developers of @value{OR1KSIM}.
|
|
|
@item --enable-execution=simple
|
@item --enable-execution=simple
|
@itemx --enable-execution=complex
|
@itemx --enable-execution=complex
|
@itemx --enable-execution=dynamic
|
@itemx --enable-execution=dynamic
|
@cindex @code{--enable-execution}
|
@cindex @code{--enable-execution}
|
@cindex simple model
|
@cindex simple model
|
@cindex complex model
|
@cindex complex model
|
@cindex dynamic model
|
@cindex dynamic model
|
@value{OR1KSIM} has developed to improve functionality and
|
@value{OR1KSIM} has developed to improve functionality and
|
performance. This feature allows three versions of @value{OR1KSIM} to be built
|
performance. This feature allows three versions of @value{OR1KSIM} to be built
|
|
|
@table @code
|
@table @code
|
|
|
@item --enable-execution=simple
|
@item --enable-execution=simple
|
Build the original simple interpreting simulator
|
Build the original simple interpreting simulator
|
|
|
@item --enable-execution=complex
|
@item --enable-execution=complex
|
Build a more complex interpreting simulator. Experiments suggest this
|
Build a more complex interpreting simulator. Experiments suggest this
|
is 50% faster than the simple simulator. This is the default.
|
is 50% faster than the simple simulator. This is the default.
|
|
|
@item --enable-execution=dynamic
|
@item --enable-execution=dynamic
|
Build a dynamically compiling simulator. This is the way many modern ISS are
|
Build a dynamically compiling simulator. This is the way many modern ISS are
|
built. This represents a work in progress. Currently @value{OR1KSIM} will
|
built. This represents a work in progress. Currently @value{OR1KSIM} will
|
compile, but segfaults if configured with this option.
|
compile, but segfaults if configured with this option.
|
|
|
@end table
|
@end table
|
|
|
The default is @code{--enable-execution=complex}.
|
The default is @code{--enable-execution=complex}.
|
|
|
@item --enable-ethphy
|
@item --enable-ethphy
|
@cindex @code{--enable-ethphy}
|
@cindex @code{--enable-ethphy}
|
@itemx --disable-ethphy
|
@itemx --disable-ethphy
|
@cindex @code{--disable-ethphy}
|
@cindex @code{--disable-ethphy}
|
@cindex Ethernet via socket, enabling
|
@cindex Ethernet via socket, enabling
|
@cindex enabling Ethernet via socket
|
@cindex enabling Ethernet via socket
|
If enabled, this option allows the Ethernet to be simulated by connecting via a
|
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
|
socket (the alternative reads and writes, from and to files). This
|
must then be configured using the relevant fields in the
|
must then be configured using the relevant fields in the
|
@code{ethernet} section of the configuration file. @xref{Ethernet
|
@code{ethernet} section of the configuration file. @xref{Ethernet
|
Configuration, , Ethernet Configuration}.
|
Configuration, , Ethernet Configuration}.
|
|
|
The default is for this to be disabled.
|
The default is for this to be disabled.
|
|
|
@item --enable-unsigned-xori
|
@item --enable-unsigned-xori
|
@cindex @code{--enable-unsigned-xori}
|
@cindex @code{--enable-unsigned-xori}
|
@itemx --disable-unsigned-xori
|
@itemx --disable-unsigned-xori
|
@cindex @code{--disable-unsigned-xori}
|
@cindex @code{--disable-unsigned-xori}
|
@cindex exclusive-OR immediate operand
|
@cindex exclusive-OR immediate operand
|
Historically, @code{l.xori}, has sign extended its operand. This is
|
Historically, @code{l.xori}, has sign extended its operand. This is
|
inconsistent with the other logical opcodes (@code{l.andi},
|
inconsistent with the other logical opcodes (@code{l.andi},
|
@code{l.ori}), but in the absence of @code{l.not}, it allows a register
|
@code{l.ori}), but in the absence of @code{l.not}, it allows a register
|
to be inverted in a single instruction using:
|
to be inverted in a single instruction using:
|
|
|
@example
|
@example
|
@code{l.xori rD,rA,-1}
|
@code{l.xori rD,rA,-1}
|
@end example
|
@end example
|
|
|
This flag causes @value{OR1KSIM} to treat the immediate operand as unsigned (i.e
|
This flag causes @value{OR1KSIM} to treat the immediate operand as unsigned (i.e
|
to zero-extend rather than sign-extend).
|
to zero-extend rather than sign-extend).
|
|
|
The default is to sign-extend, so that existing code will continue to
|
The default is to sign-extend, so that existing code will continue to
|
work.
|
work.
|
|
|
@quotation Caution
|
@quotation Caution
|
The GNU compiler tool chain makes heavy use of this instruction. Using
|
The GNU compiler tool chain makes heavy use of this instruction. Using
|
unsigned behavior will require the compiler to be modified accordingly.
|
unsigned behavior will require the compiler to be modified accordingly.
|
|
|
This option is provided for experimentation. A future version of
|
This option is provided for experimentation. A future version of
|
OpenRISC may adopt this more consistent behavior and also provide a
|
OpenRISC may adopt this more consistent behavior and also provide a
|
@code{l.not} opcode.
|
@code{l.not} opcode.
|
@end quotation
|
@end quotation
|
|
|
@item --enable-range-stats
|
@item --enable-range-stats
|
@cindex @code{--enable-range-stats}
|
@cindex @code{--enable-range-stats}
|
@itemx --disable-range-stats
|
@itemx --disable-range-stats
|
@cindex @code{--disable-range-stats}
|
@cindex @code{--disable-range-stats}
|
@cindex statistics, register over time
|
@cindex statistics, register over time
|
@cindex register over time statistics
|
@cindex register over time statistics
|
If enabled, this option allows statistics to be collected to analyse
|
If enabled, this option allows statistics to be collected to analyse
|
register access over time. The default is for this to be disabled.
|
register access over time. The default is for this to be disabled.
|
|
|
@item --enable-debug
|
@item --enable-debug
|
@cindex @code{--enable-debug}
|
@cindex @code{--enable-debug}
|
@itemx --disable-debug
|
@itemx --disable-debug
|
@cindex @code{--disable-debug}
|
@cindex @code{--disable-debug}
|
@cindex debugging enabled (Argtable2)
|
@cindex debugging enabled (Argtable2)
|
@cindex Argtable2 debugging
|
@cindex Argtable2 debugging
|
This is a feature of the Argtable2 package used to process arguments. If
|
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
|
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
|
completeness, but there is no reason why this feature should ever be needed by
|
any @value{OR1KSIM} user.
|
any @value{OR1KSIM} user.
|
|
|
@item --enable-all-tests
|
@item --enable-all-tests
|
@cindex @code{--enable-all-tests}
|
@cindex @code{--enable-all-tests}
|
@itemx --disable-all-tests
|
@itemx --disable-all-tests
|
@cindex @code{--disable-all-tests}
|
@cindex @code{--disable-all-tests}
|
@cindex all tests enabled
|
@cindex all tests enabled
|
@cindex tests, all enabled.
|
@cindex tests, all enabled.
|
Some of the tests (at the time of writing just one) will not compile
|
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
|
without error. If enabled with this flag, all test programs will be
|
compiled with @command{make check}.
|
compiled with @command{make check}.
|
|
|
This flag is intended for those working on the test package, who wish to
|
This flag is intended for those working on the test package, who wish to
|
get the missing test(s) working.
|
get the missing test(s) working.
|
|
|
@end table
|
@end table
|
|
|
A number of configuration flags have been removed since version 0.3.0,
|
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:
|
because they led to invalid behavior of @value{OR1KSIM}. Those removed are:
|
|
|
@table @code
|
@table @code
|
|
|
@item --enable-arith-flag
|
@item --enable-arith-flag
|
@cindex @code{--enable-arith-flag}
|
@cindex @code{--enable-arith-flag}
|
@itemx --disable-arith-flag
|
@itemx --disable-arith-flag
|
@cindex @code{--disable-arith-flag}
|
@cindex @code{--disable-arith-flag}
|
@cindex flag setting by instructions
|
@cindex flag setting by instructions
|
If enabled, this option caused certain instructions to set the flag
|
If enabled, this option caused certain instructions to set the flag
|
(@code{F} bit) in the supervision register if the result were zero.
|
(@code{F} bit) in the supervision register if the result were zero.
|
The instructions affected by this were @code{l.add}, @code{l.addc},
|
The instructions affected by this were @code{l.add}, @code{l.addc},
|
@code{l.addi}, @code{l.and} and @code{l.andi}.
|
@code{l.addi}, @code{l.and} and @code{l.andi}.
|
|
|
If set, this caused incorrect behavior. Whether or not flags are set is part
|
If set, this caused incorrect behavior. Whether or not flags are set is part
|
of the OpenRISC 1000 architectural specification. The only flags which
|
of the OpenRISC 1000 architectural specification. The only flags which
|
should set this are the ``set flag'' instructions: @code{l.sfeq},
|
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.sfeqi}, @code{l.sfges}, @code{l.sfgesi}, @code{l.sfgeu},
|
@code{l.sfgeui}, @code{l.sfgts}, @code{l.sfgtsi}, @code{l.sfgtu},
|
@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.sfgtui}, @code{l.sfles}, @code{l.sflesi}, @code{l.sfleu},
|
@code{l.sfleui}, @code{l.sflts}, @code{l.sfltsi}, @code{l.sfltu},
|
@code{l.sfleui}, @code{l.sflts}, @code{l.sfltsi}, @code{l.sfltu},
|
@code{l.sfltui}, @code{l.sfne} and @code{l.sfnei}.
|
@code{l.sfltui}, @code{l.sfne} and @code{l.sfnei}.
|
|
|
@item --enable-ov-flag
|
@item --enable-ov-flag
|
@cindex @code{--enable-ov-flag}
|
@cindex @code{--enable-ov-flag}
|
@itemx --disable-ov-flag
|
@itemx --disable-ov-flag
|
@cindex @code{--disable-ov-flag}
|
@cindex @code{--disable-ov-flag}
|
@cindex overflow flag setting by instructions
|
@cindex overflow flag setting by instructions
|
This flag caused certain instructions to set the overflow flag. If not,
|
This flag caused certain instructions to set the overflow flag. If not,
|
those instructions would not set the overflow flat. The instructions
|
those instructions would not set the overflow flat. The instructions
|
affected by this were @code{l.add}, @code{l.addc}, @code{l.addi},
|
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.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.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.srl}, @code{l.srli}, @code{l.sra}, @code{l.srai}, @code{l.sub},
|
@code{l.xor} and @code{l.xori}.
|
@code{l.xor} and @code{l.xori}.
|
|
|
This guaranteed incorrect behavior. The OpenRISC 1000 architecture
|
This guaranteed incorrect behavior. The OpenRISC 1000 architecture
|
specification defines which flags are set by which instructions.
|
specification defines which flags are set by which instructions.
|
|
|
Within the above list, the arithmetic instructions (@code{l.add},
|
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.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
|
@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},
|
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.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}
|
@code{l.srl}, @code{l.srli}, @code{l.sra}, @code{l.srai}, @code{l.xor}
|
and @code{l.xori}) do not.
|
and @code{l.xori}) do not.
|
|
|
@end table
|
@end table
|
|
|
@node Build and Install
|
@node Build and Install
|
@section Building and Installing
|
@section Building and Installing
|
Build the tool with:
|
Build the tool with:
|
|
|
@example
|
@example
|
make all
|
make all
|
@end example
|
@end example
|
|
|
If you have the OpenRISC tool chain and DejaGNU installed, you can
|
If you have the OpenRISC tool chain and DejaGNU installed, you can
|
verify the tool as follows (otherwise omit this step):
|
verify the tool as follows (otherwise omit this step):
|
|
|
@example
|
@example
|
make check
|
make check
|
@end example
|
@end example
|
|
|
Install the tool with:
|
Install the tool with:
|
|
|
@example
|
@example
|
make install
|
make install
|
@end example
|
@end example
|
|
|
This will install the three variations of the @value{OR1KSIM} tool,
|
This will install the three variations of the @value{OR1KSIM} tool,
|
@command{or32-elf-sim}, @command{or32-elf-psim} and
|
@command{or32-elf-sim}, @command{or32-elf-psim} and
|
@command{or32-elf-mpsim}, the @value{OR1KSIM} library, @file{libsim}, the
|
@command{or32-elf-mpsim}, the @value{OR1KSIM} library, @file{libsim}, the
|
header file, @file{or1ksim.h} and this documentation in @command{info} format.
|
header file, @file{or1ksim.h} and this documentation in @command{info} format.
|
|
|
The documentation may be created and installed in alternative formats (PDF,
|
The documentation may be created and installed in alternative formats (PDF,
|
Postscript, DVI, HTML) with for example:
|
Postscript, DVI, HTML) with for example:
|
|
|
@example
|
@example
|
make pdf
|
make pdf
|
make install-pdf
|
make install-pdf
|
@end example
|
@end example
|
|
|
@node Known Issues
|
@node Known Issues
|
@section Known Problems and Issues
|
@section Known Problems and Issues
|
|
|
Full details of outstanding issues may be found in the @file{NEWS} file in
|
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
|
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
|
to see the current state of these issues and to raise new problems and
|
feature requests. It may be found at
|
feature requests. It may be found at
|
@url{http://opencores.org/project,or1k,bugtracker}.
|
@url{http://opencores.org/project,or1k,bugtracker}.
|
|
|
The following issues are long standing and unlikely to be fixed in
|
The following issues are long standing and unlikely to be fixed in
|
@value{OR1KSIM} in the near future.
|
@value{OR1KSIM} in the near future.
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
The Supervision Register Little Endian Enable (LEE) bit is
|
The Supervision Register Little Endian Enable (LEE) bit is
|
ignored. @value{OR1KSIM} can be built for either little endian or big endian
|
ignored. @value{OR1KSIM} can be built for either little endian or big endian
|
use, but that behavior cannot be changed dynamically.
|
use, but that behavior cannot be changed dynamically.
|
|
|
@item
|
@item
|
@value{OR1KSIM} is not reentrant, so a program cannot instantiate
|
@value{OR1KSIM} is not reentrant, so a program cannot instantiate
|
multiple instances using the library. This is clearly a problem when
|
multiple instances using the library. This is clearly a problem when
|
considering multi-core applications. However it stems from the original
|
considering multi-core applications. However it stems from the original
|
design, and can only be fixed by a complete rewrite. The entire source
|
design, and can only be fixed by a complete rewrite. The entire source
|
code uses static global constants liberally!
|
code uses static global constants liberally!
|
|
|
@end itemize
|
@end itemize
|
|
|
@node Usage
|
@node Usage
|
@chapter Usage
|
@chapter Usage
|
@cindex running @value{OR1KSIM}
|
@cindex running @value{OR1KSIM}
|
|
|
@menu
|
@menu
|
* Standalone Simulator::
|
* Standalone Simulator::
|
* Profiling Utility::
|
* Profiling Utility::
|
* Memory Profiling Utility::
|
* Memory Profiling Utility::
|
* Trace Generation::
|
* Trace Generation::
|
* Simulator Library::
|
* Simulator Library::
|
* Ethernet TUN/TAP Interface::
|
* Ethernet TUN/TAP Interface::
|
* l.nop Support::
|
* l.nop Support::
|
@end menu
|
@end menu
|
|
|
@node Standalone Simulator
|
@node Standalone Simulator
|
@section Standalone Simulator
|
@section Standalone Simulator
|
@cindex command line for @value{OR1KSIM} standalone use
|
@cindex command line for @value{OR1KSIM} standalone use
|
|
|
The general form the standalone command is:
|
The general form the standalone command is:
|
|
|
@example
|
@example
|
or32-elf-sim [-vhiqVt] [-f @var{file}] [--nosrv] [--srv=[@var{n}]]
|
or32-elf-sim [-vhiqVt] [-f @var{file}] [--nosrv] [--srv=[@var{n}]]
|
[-m <n>][-d @var{str}]
|
[-m <n>][-d @var{str}]
|
[--enable-profile] [--enable-mprofile] [@var{file}]
|
[--enable-profile] [--enable-mprofile] [@var{file}]
|
@end example
|
@end example
|
|
|
Many of the options have both a short and a long form. For example
|
Many of the options have both a short and a long form. For example
|
@code{-h} or @code{--help}.
|
@code{-h} or @code{--help}.
|
|
|
@table @code
|
@table @code
|
|
|
@item -v
|
@item -v
|
@itemx --version
|
@itemx --version
|
@cindex @code{-v}
|
@cindex @code{-v}
|
@cindex @code{--version}
|
@cindex @code{--version}
|
Print out the version and copyright notice for @value{OR1KSIM} and
|
Print out the version and copyright notice for @value{OR1KSIM} and
|
exit.
|
exit.
|
|
|
@item -h
|
@item -h
|
@itemx --help
|
@itemx --help
|
@cindex @code{-h}
|
@cindex @code{-h}
|
@cindex @code{--help}
|
@cindex @code{--help}
|
Print out help about the command line options and what they mean.
|
Print out help about the command line options and what they mean.
|
|
|
@item -i
|
@item -i
|
@itemx --interactive
|
@itemx --interactive
|
@cindex @code{-i}
|
@cindex @code{-i}
|
@cindex @code{--interactive}
|
@cindex @code{--interactive}
|
After starting, drop into the @value{OR1KSIM} interactive command
|
After starting, drop into the @value{OR1KSIM} interactive command
|
shell.
|
shell.
|
|
|
@item -q
|
@item -q
|
@itemx --quiet
|
@itemx --quiet
|
@cindex @code{-q}
|
@cindex @code{-q}
|
@cindex @code{--quiet}
|
@cindex @code{--quiet}
|
Do not generate any information messages, only error messages.
|
Do not generate any information messages, only error messages.
|
|
|
@item -V
|
@item -V
|
@itemx --verbose
|
@itemx --verbose
|
@cindex @code{-V}
|
@cindex @code{-V}
|
@cindex @code{--verbose}
|
@cindex @code{--verbose}
|
Generate extra output messages (equivalent of specifying the ``verbose''
|
Generate extra output messages (equivalent of specifying the ``verbose''
|
option in the simulator configuration section (see @pxref{Simulator Behavior, , Simulator Behavior}).
|
option in the simulator configuration section (see @pxref{Simulator Behavior, , Simulator Behavior}).
|
|
|
@item -t
|
@item -t
|
@itemx --trace
|
@itemx --trace
|
@cindex @code{-t}
|
@cindex @code{-t}
|
@cindex @code{--trace}
|
@cindex @code{--trace}
|
Dump instruction just executed and any register/memory location chaged
|
Dump instruction just executed and any register/memory location chaged
|
after each instruction (one line per instruction).
|
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}
|
@item -f @var{file}
|
@itemx --file=@var{file}
|
@itemx --file=@var{file}
|
@cindex @code{-f}
|
@cindex @code{-f}
|
@cindex @code{--file}
|
@cindex @code{--file}
|
Read configuration commands from the specified file, looking first in
|
Read configuration commands from the specified file, looking first in
|
the current directory, and otherwise in the @file{$HOME/.or1k}
|
the current directory, and otherwise in the @file{$HOME/.or1k}
|
directory. If this argument is not specified, the file @file{sim.cfg}
|
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
|
in those two locations is used. Failure to find the file is a fatal
|
error. @xref{Configuration, , Configuration}, for detailed information
|
error. @xref{Configuration, , Configuration}, for detailed information
|
on configuring @value{OR1KSIM}.
|
on configuring @value{OR1KSIM}.
|
|
|
@item --nosrv
|
@item --nosrv
|
@cindex @code{--nosrv}
|
@cindex @code{--nosrv}
|
@cindex Remote Serial Protocol, @code{--nosrv}
|
@cindex Remote Serial Protocol, @code{--nosrv}
|
Do not start up the @dfn{Remote Serial Protocol} debug server. This
|
Do not start up the @dfn{Remote Serial Protocol} debug server. This
|
overrides any setting specified in the configuration file. This
|
overrides any setting specified in the configuration file. This
|
option may not be specified with @code{--srv}. If it is, a rude
|
option may not be specified with @code{--srv}. If it is, a rude
|
message is printed and the @code{--nosrv} option is ignored.
|
message is printed and the @code{--nosrv} option is ignored.
|
|
|
@item --srv
|
@item --srv
|
@item --srv=@var{n}
|
@item --srv=@var{n}
|
@cindex @code{--srv}
|
@cindex @code{--srv}
|
@cindex Remote Serial Protocol, @code{--srv}
|
@cindex Remote Serial Protocol, @code{--srv}
|
Start up the @dfn{Remote Serial Protocol} debug server. This
|
Start up the @dfn{Remote Serial Protocol} debug server. This
|
overrides any setting specified in the configuration file. If the
|
overrides any setting specified in the configuration file. If the
|
parameter, @var{n}, is specified, use that as the TCP/IP port for 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
|
server, otherwise a random value from the private port range
|
(41920-65535) will be used. This option may not be specified with
|
(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}. If it is, a rude message is printed and the
|
@code{--nosrv} option is ignored.
|
@code{--nosrv} option is ignored.
|
|
|
@item -m @var{size}
|
@item -m @var{size}
|
@itemx --memory=@var{size}
|
@itemx --memory=@var{size}
|
@cindex @code{-m}
|
@cindex @code{-m}
|
@cindex @code{--memory}
|
@cindex @code{--memory}
|
Configure a memory block of @var{size} bytes, starting at address
|
Configure a memory block of @var{size} bytes, starting at address
|
zero. The size may be followed by @samp{k}, @samp{K}, @samp{m},
|
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}}
|
@samp{M}, @samp{g}, @samp{G}, to indicate kilobytes (@math{2^{10}}
|
bytes), megabytes (@math{2^{20}} bytes) and gigabytes (@math{2^{30}}
|
bytes), megabytes (@math{2^{20}} bytes) and gigabytes (@math{2^{30}}
|
bytes).
|
bytes).
|
|
|
This is mainly intended for use when @value{OR1KSIM} is used without a
|
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
|
configuration file, to allow just the processor and memory to be set
|
up. This is the equivalent of specifying a configuration memory section
|
up. This is the equivalent of specifying a configuration memory section
|
with @code{baseaddr = 0} and @code{size = @var{size}} and all other
|
with @code{baseaddr = 0} and @code{size = @var{size}} and all other
|
parameters taking their default value.
|
parameters taking their default value.
|
|
|
If a configuration file is also used, it should be sure not to specify
|
If a configuration file is also used, it should be sure not to specify
|
an overlapping memory block.
|
an overlapping memory block.
|
|
|
@item -d @var{config_string}
|
@item -d @var{config_string}
|
@itemx --debug-config=@var{config_string}
|
@itemx --debug-config=@var{config_string}
|
@cindex @code{-d}
|
@cindex @code{-d}
|
@cindex @code{--debug-config}
|
@cindex @code{--debug-config}
|
Enable selected debug messages in @value{OR1KSIM}. This parameter is
|
Enable selected debug messages in @value{OR1KSIM}. This parameter is
|
for use by developers only, and is not covered further here. See the
|
for use by developers only, and is not covered further here. See the
|
source code for more details.
|
source code for more details.
|
|
|
@item --report-memory-errors
|
@item --report-memory-errors
|
@cindex @code{--report-memory-errors}
|
@cindex @code{--report-memory-errors}
|
By default all exceptions are now handled silently. If this option is
|
By default all exceptions are now handled silently. If this option is
|
specified, bus exceptions will be reported with a message to standard
|
specified, bus exceptions will be reported with a message to standard
|
error indicating the address at which the exception occurred.
|
error indicating the address at which the exception occurred.
|
|
|
This was the default behaviour up to @value{OR1KSIM} 0.4.0. This flag is
|
This was the default behaviour up to @value{OR1KSIM} 0.4.0. This flag is
|
provided for those who wish to keep that behavior.
|
provided for those who wish to keep that behavior.
|
|
|
@item --strict-npc
|
@item --strict-npc
|
@cindex @code{--strict-npc}
|
@cindex @code{--strict-npc}
|
In real hardware, setting the next program counter (NPC, SPR 16),
|
In real hardware, setting the next program counter (NPC, SPR 16),
|
flushes the processor pipeline. The consequence of this is that until
|
flushes the processor pipeline. The consequence of this is that until
|
the pipeline refills, reading the NPC will return zero. This is typically
|
the pipeline refills, reading the NPC will return zero. This is typically
|
the case when debugging, since the processor is stalled.
|
the case when debugging, since the processor is stalled.
|
|
|
Historically, @value{OR1KSIM} has always returned the value of the NPC,
|
Historically, @value{OR1KSIM} has always returned the value of the NPC,
|
irrespective of when it is changed. If the @code{--strict-npc} option is
|
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
|
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
|
is changed while the processor is stalled, subsequent reads of its value
|
will return 0 until the processor is unstalled.
|
will return 0 until the processor is unstalled.
|
|
|
This is not currently the default behavior, since tools such as GDB have
|
This is not currently the default behavior, since tools such as GDB have
|
been implemented assuming the historic @value{OR1KSIM} behavior.
|
been implemented assuming the historic @value{OR1KSIM} behavior.
|
However at some time in the future it will become the default.
|
However at some time in the future it will become the default.
|
|
|
@item --enable-profile
|
@item --enable-profile
|
@cindex @code{--enable-profile}
|
@cindex @code{--enable-profile}
|
Enable instruction profiling.
|
Enable instruction profiling.
|
|
|
@item --enable-mprofile
|
@item --enable-mprofile
|
@cindex @code{--enable-mprofile}
|
@cindex @code{--enable-mprofile}
|
Enable memory profiling.
|
Enable memory profiling.
|
|
|
@end table
|
@end table
|
|
|
@node Profiling Utility
|
@node Profiling Utility
|
@section Profiling Utility
|
@section Profiling Utility
|
@cindex profiling for @value{OR1KSIM}
|
@cindex profiling for @value{OR1KSIM}
|
@cindex instruction profiling for @value{OR1KSIM}
|
@cindex instruction profiling for @value{OR1KSIM}
|
|
|
This utility analyses instruction profile data generated by
|
This utility analyses instruction profile data generated by
|
@value{OR1KSIM}. It may be invoked as a standalone command, or from
|
@value{OR1KSIM}. It may be invoked as a standalone command, or from
|
the @value{OR1KSIM} CLI. The general form the standalone command is:
|
the @value{OR1KSIM} CLI. The general form the standalone command is:
|
|
|
@example
|
@example
|
or32-elf-profile [-vhcq] [-g=@var{file}]
|
or32-elf-profile [-vhcq] [-g=@var{file}]
|
@end example
|
@end example
|
|
|
Many of the options have both a short and a long form. For example
|
Many of the options have both a short and a long form. For example
|
@code{-h} or @code{--help}.
|
@code{-h} or @code{--help}.
|
|
|
@table @code
|
@table @code
|
|
|
@item -v
|
@item -v
|
@itemx --version
|
@itemx --version
|
@cindex @code{-v} (profiling utility)
|
@cindex @code{-v} (profiling utility)
|
@cindex @code{--version} (profiling utility)
|
@cindex @code{--version} (profiling utility)
|
Print out the version and copyright notice for the @value{OR1KSIM}
|
Print out the version and copyright notice for the @value{OR1KSIM}
|
profiling utility and exit.
|
profiling utility and exit.
|
|
|
@item -h
|
@item -h
|
@itemx --help
|
@itemx --help
|
@cindex @code{-h} (profiling utility)
|
@cindex @code{-h} (profiling utility)
|
@cindex @code{--help} (profiling utility)
|
@cindex @code{--help} (profiling utility)
|
Print out help about the command line options and what they mean.
|
Print out help about the command line options and what they mean.
|
|
|
@item -c
|
@item -c
|
@itemx --cumulative
|
@itemx --cumulative
|
@cindex @code{-c}
|
@cindex @code{-c}
|
@cindex @code{--cumulative}
|
@cindex @code{--cumulative}
|
Show cumulative sum of cycles in functions
|
Show cumulative sum of cycles in functions
|
|
|
@item -q
|
@item -q
|
@itemx --quiet
|
@itemx --quiet
|
@cindex @code{-q}
|
@cindex @code{-q}
|
@cindex @code{--quiet}
|
@cindex @code{--quiet}
|
Suppress messages
|
Suppress messages
|
|
|
@item -g=@var{file}
|
@item -g=@var{file}
|
@itemx --generate=@var{file}
|
@itemx --generate=@var{file}
|
@cindex @code{-g}
|
@cindex @code{-g}
|
@cindex @code{--generate}
|
@cindex @code{--generate}
|
The data file to analyse. If omitted, the default file,
|
The data file to analyse. If omitted, the default file,
|
@file{sim.profile} is used.
|
@file{sim.profile} is used.
|
|
|
@end table
|
@end table
|
|
|
@node Memory Profiling Utility
|
@node Memory Profiling Utility
|
@section Memory Profiling Utility
|
@section Memory Profiling Utility
|
@cindex memory profiling version of @value{OR1KSIM}
|
@cindex memory profiling version of @value{OR1KSIM}
|
|
|
This utility analyses memory profile data generated by
|
This utility analyses memory profile data generated by
|
@value{OR1KSIM}. It may be invoked as a standalone command, or from
|
@value{OR1KSIM}. It may be invoked as a standalone command, or from
|
the @value{OR1KSIM} CLI. The general form the standalone command is:
|
the @value{OR1KSIM} CLI. The general form the standalone command is:
|
|
|
@example
|
@example
|
or32-elf-mprofile [-vh] [-m=@var{m}] [-g=@var{n}] [-f=@var{file}] @var{from} @var{to}
|
or32-elf-mprofile [-vh] [-m=@var{m}] [-g=@var{n}] [-f=@var{file}] @var{from} @var{to}
|
@end example
|
@end example
|
|
|
Many of the options have both a short and a long form. For example
|
Many of the options have both a short and a long form. For example
|
@code{-h} or @code{--help}.
|
@code{-h} or @code{--help}.
|
|
|
@table @code
|
@table @code
|
|
|
@item -v
|
@item -v
|
@itemx --version
|
@itemx --version
|
@cindex @code{-v} (memory profiling utility)
|
@cindex @code{-v} (memory profiling utility)
|
@cindex @code{--version} (memory profiling utility)
|
@cindex @code{--version} (memory profiling utility)
|
Print out the version and copyright notice for the @value{OR1KSIM}
|
Print out the version and copyright notice for the @value{OR1KSIM}
|
memory profiling utility and exit.
|
memory profiling utility and exit.
|
|
|
@item -h
|
@item -h
|
@itemx --help
|
@itemx --help
|
@cindex @code{-h} (memory profiling utility)
|
@cindex @code{-h} (memory profiling utility)
|
@cindex @code{--help} (memory profiling utility)
|
@cindex @code{--help} (memory profiling utility)
|
Print out help about the command line options and what they mean.
|
Print out help about the command line options and what they mean.
|
|
|
@item -m=@var{m}
|
@item -m=@var{m}
|
@itemx --mode=@var{m}
|
@itemx --mode=@var{m}
|
@cindex @code{-m}
|
@cindex @code{-m}
|
@cindex @code{--mode}
|
@cindex @code{--mode}
|
Specify the mode out output. Permitted options are
|
Specify the mode out output. Permitted options are
|
|
|
@table @code
|
@table @code
|
|
|
@item detailed
|
@item detailed
|
@itemx d
|
@itemx d
|
Detailed output. This is the default if no mode is specified.
|
Detailed output. This is the default if no mode is specified.
|
|
|
@item pretty
|
@item pretty
|
@itemx p
|
@itemx p
|
Pretty printed output.
|
Pretty printed output.
|
|
|
@item access
|
@item access
|
@itemx a
|
@itemx a
|
Memory accesses only.
|
Memory accesses only.
|
|
|
@item width
|
@item width
|
@itemx w
|
@itemx w
|
Access width only.
|
Access width only.
|
|
|
@end table
|
@end table
|
|
|
@item -g=@var{n}
|
@item -g=@var{n}
|
@itemx --group=@var{n}
|
@itemx --group=@var{n}
|
@cindex @code{-g}
|
@cindex @code{-g}
|
@cindex @code{--group}
|
@cindex @code{--group}
|
Group @math{2^n} bits of successive addresses together.
|
Group @math{2^n} bits of successive addresses together.
|
|
|
@item -f=@var{file}
|
@item -f=@var{file}
|
@itemx --filename=@var{file}
|
@itemx --filename=@var{file}
|
@cindex @code{-f}
|
@cindex @code{-f}
|
@cindex @code{--filename}
|
@cindex @code{--filename}
|
The data file to analyse. If not specified, the default,
|
The data file to analyse. If not specified, the default,
|
@file{sim.profile} is used.
|
@file{sim.profile} is used.
|
|
|
@item @var{from}
|
@item @var{from}
|
@itemx @var{to}
|
@itemx @var{to}
|
@cindex memory profiling start address
|
@cindex memory profiling start address
|
@cindex memory profiling end address
|
@cindex memory profiling end address
|
@var{from} and @var{to} are respectively the start and end address of
|
@var{from} and @var{to} are respectively the start and end address of
|
the region of memory to be analysed.
|
the region of memory to be analysed.
|
|
|
@end table
|
@end table
|
|
|
@node Trace Generation
|
@node Trace Generation
|
@section Trace Generation
|
@section Trace Generation
|
@cindex trace generation of @value{OR1KSIM}
|
@cindex trace generation of @value{OR1KSIM}
|
|
|
An execution trace can be generated at run time with options passed by
|
An execution trace can be generated at run time with options passed by
|
the command line, or via the operating system's signal passing
|
the command line, or via the operating system's signal passing
|
mechanism.
|
mechanism, or by @code{l.nop} opcodes in an application program.
|
|
|
The following, passed at run time, can be used to create an execution dump.
|
The following flag can be used to create an execution dump.
|
|
|
@table @code
|
@table @code
|
|
|
@item -t
|
@item -t
|
@itemx --trace
|
@itemx --trace
|
@cindex @code{-t}
|
@cindex @code{-t}
|
@cindex @code{--trace}
|
@cindex @code{--trace}
|
Dump instruction just executed and any register/memory location chaged
|
Dump instruction just executed and any register/memory location changed
|
after each instruction (one line per instruction).
|
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
|
@end table
|
|
|
Passing a signal @code{SIGUSR1} while the simulator is running toggles
|
Passing a signal @code{SIGUSR1} while the simulator is running toggles
|
trace generation. This can be done with the following command, assuming
|
trace generation. This can be done with the following command, assuming
|
@value{OR1KSIM}'s executable name is @code{or32-elf-sim}:
|
@value{OR1KSIM}'s executable name is @code{or32-elf-sim}:
|
|
|
@example
|
@example
|
pkill -SIGUSR1 or32-elf-sim
|
pkill -SIGUSR1 or32-elf-sim
|
@end example
|
@end example
|
|
|
This is useful in the case where trace output is desired after a
|
This is useful in the case where trace output is desired after a
|
significant amount of simulation time, where it would be inconvenient to
|
significant amount of simulation time, where it would be inconvenient to
|
generate trace up to that point.
|
generate trace up to that point.
|
|
|
If the @code{pkill} utility is not available, the @code{kill} utility
|
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
|
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
|
following to determine the process ID of the @code{or32-elf-sim} and
|
then send the @code{SIGUSR1} command to toggle execution trace
|
then send the @code{SIGUSR1} command to toggle execution trace
|
generation:
|
generation:
|
|
|
@example
|
@example
|
ps a | grep or32-elf-sim
|
ps a | grep or32-elf-sim
|
kill -SIGUSR1 @emph{process-number}
|
kill -SIGUSR1 @emph{process-number}
|
@end example
|
@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
|
@node Simulator Library
|
@section Simulator Library
|
@section Simulator Library
|
@cindex library version of @value{OR1KSIM}
|
@cindex library version of @value{OR1KSIM}
|
|
|
@value{OR1KSIM} may be used as a static of dynamic library,
|
@value{OR1KSIM} may be used as a static of dynamic library,
|
@file{libsim.a} or @file{libsim.so}. When compiling with the static
|
@file{libsim.a} or @file{libsim.so}. When compiling with the static
|
library, the flag, @code{-lsim} should be added to the link command.
|
library, the flag, @code{-lsim} should be added to the link command.
|
|
|
The header file @file{or1ksim.h} contains appropriate declarations of
|
The header file @file{or1ksim.h} contains appropriate declarations of
|
the functions exported by the @value{OR1KSIM} library. These are:
|
the functions exported by the @value{OR1KSIM} library. These are:
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_init (int @var{argc}, @
|
@deftypefn {@file{or1ksim.h}} int or1ksim_init (int @var{argc}, @
|
char *@var{argv}, void *@var{class_ptr}, @
|
char *@var{argv}, void *@var{class_ptr}, @
|
int (*@var{upr})(void *@var{class_ptr}, @
|
int (*@var{upr})(void *@var{class_ptr}, @
|
unsigned long int @var{addr}, unsigned char @var{mask}[], @
|
unsigned long int @var{addr}, unsigned char @var{mask}[], @
|
unsigned char @var{rdata}[], int @var{data_len}), @
|
unsigned char @var{rdata}[], int @var{data_len}), @
|
int (*@var{upw})(void *@var{class_ptr}, @
|
int (*@var{upw})(void *@var{class_ptr}, @
|
unsigned long int @var{addr}, @
|
unsigned long int @var{addr}, @
|
unsigned char @var{mask}[], unsigned char @var{wdata}[], @
|
unsigned char @var{mask}[], unsigned char @var{wdata}[], @
|
int @var{data_len}))
|
int @var{data_len}))
|
|
|
The initialization function is supplied with a vector of arguments,
|
The initialization function is supplied with a vector of arguments,
|
which are interpreted as arguments to the standalone version (see
|
which are interpreted as arguments to the standalone version (see
|
@pxref{Standalone Simulator, , Standalone Simulator}), a pointer to the
|
@pxref{Standalone Simulator, , Standalone Simulator}), a pointer to the
|
calling class, @var{class_ptr} (since the library may be used from C++)
|
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,
|
and two up-call functions, one for reads, @var{upr}, and one for writes,
|
@var{upw}.
|
@var{upw}.
|
|
|
@var{upw} is called for any write to an address external to the model
|
@var{upw} is called for any write to an address external to the model
|
(determined by a @code{generic} section in the configuration
|
(determined by a @code{generic} section in the configuration
|
file). @var{upr} is called for any reads to an external address. The
|
file). @var{upr} is called for any reads to an external address. The
|
@var{class_ptr} is passed back with these upcalls, allowing the
|
@var{class_ptr} is passed back with these upcalls, allowing the
|
function to associate the call with the class which originally
|
function to associate the call with the class which originally
|
initialized the library. Both @var{upw} and @var{upr} should return
|
initialized the library. Both @var{upw} and @var{upr} should return
|
zero on success and non-zero otherwise. At the present time the meaning
|
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.
|
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
|
@var{mask} indicates which bytes in the data are to be written or
|
read. Bytes to be read/written should have 0xff set in
|
read. Bytes to be read/written should have 0xff set in
|
@var{mask}. Otherwise the byte should be zero. The adddress,
|
@var{mask}. Otherwise the byte should be zero. The adddress,
|
@var{addr}, is the @emph{full} address, since the upcall function must
|
@var{addr}, is the @emph{full} address, since the upcall function must
|
handle all generic devices, using the full address for decoding.
|
handle all generic devices, using the full address for decoding.
|
|
|
Endianness is not a concern, since @value{OR1KSIM} is transferring byte
|
Endianness is not a concern, since @value{OR1KSIM} is transferring byte
|
vectors, not multi-byte values.
|
vectors, not multi-byte values.
|
|
|
The result indicates whether the initialization was successful. The
|
The result indicates whether the initialization was successful. The
|
integer values are available as an @code{enum or1ksim}, with possible
|
integer values are available as an @code{enum or1ksim}, with possible
|
values @code{OR1KSIM_RC_OK} and @code{OR1KSIM_RC_BADINIT}.
|
values @code{OR1KSIM_RC_OK} and @code{OR1KSIM_RC_BADINIT}.
|
|
|
@quotation Caution
|
@quotation Caution
|
This is a change from versions 0.3.0 and 0.4.0. It further simplifies
|
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
|
the interface, and makes @value{OR1KSIM} more consistent with payload
|
representation in SystemC TLM 2.0.
|
representation in SystemC TLM 2.0.
|
@end quotation
|
@end quotation
|
|
|
@quotation Note
|
@quotation Note
|
The current implementation of @value{OR1KSIM} always transfers single words (4
|
The current implementation of @value{OR1KSIM} always transfers single words (4
|
bytes), using masks if smaller values are required. In this it mimcs the
|
bytes), using masks if smaller values are required. In this it mimcs the
|
behavior of the WishBone bus.
|
behavior of the WishBone bus.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_run (double @var{duration})
|
@deftypefn {@file{or1ksim.h}} int or1ksim_run (double @var{duration})
|
|
|
Run the simulator for the simulated duration specified (in seconds). A
|
Run the simulator for the simulated duration specified (in seconds). A
|
duration of -1 indicates `run forever'
|
duration of -1 indicates `run forever'
|
|
|
The result indicates how the run terminated. The integer values are
|
The result indicates how the run terminated. The integer values are
|
available as an @code{enum or1ksim}, with possible values
|
available as an @code{enum or1ksim}, with possible values
|
@code{OR1KSIM_RC_OK} (ran for the full duration),
|
@code{OR1KSIM_RC_OK} (ran for the full duration),
|
@code{OR1KSIM_RC_BRKPT} (terminated early due to hitting a breakpoint)
|
@code{OR1KSIM_RC_BRKPT} (terminated early due to hitting a breakpoint)
|
and @code{OR1KSIM_RC_HALTED} (terminated early due to hitting
|
and @code{OR1KSIM_RC_HALTED} (terminated early due to hitting
|
@code{l.nop 1}).
|
@code{l.nop 1}).
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} void or1ksim_reset_duration (double @var{duration})
|
@deftypefn {@file{or1ksim.h}} void or1ksim_reset_duration (double @var{duration})
|
|
|
Change the duration of a run specified in an earlier call to
|
Change the duration of a run specified in an earlier call to
|
@code{or1ksim_run}. Typically this is called from an upcall, which
|
@code{or1ksim_run}. Typically this is called from an upcall, which
|
realizes it needs to change the duration of the run specified in the
|
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.
|
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
|
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
|
for (i.e the duration from @emph{now}, not the duration from the original
|
call to @code{or1ksim_run}).
|
call to @code{or1ksim_run}).
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} void or1ksim_set_time_point ()
|
@deftypefn {@file{or1ksim.h}} void or1ksim_set_time_point ()
|
|
|
Set a timing point. For use with @code{or1ksim_get_time_period}.
|
Set a timing point. For use with @code{or1ksim_get_time_period}.
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} double or1ksim_get_time_period ()
|
@deftypefn {@file{or1ksim.h}} double or1ksim_get_time_period ()
|
|
|
Return the simulated time (in seconds) that has elapsed since the last
|
Return the simulated time (in seconds) that has elapsed since the last
|
call to @code{or1ksim_set_time_point}.
|
call to @code{or1ksim_set_time_point}.
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_is_le ()
|
@deftypefn {@file{or1ksim.h}} int or1ksim_is_le ()
|
|
|
Return 1 (logical true) if the @value{OR1KSIM} simulation is
|
Return 1 (logical true) if the @value{OR1KSIM} simulation is
|
little-endian, 0 otherwise.
|
little-endian, 0 otherwise.
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} unsigned long int or1ksim_clock_rate ()
|
@deftypefn {@file{or1ksim.h}} unsigned long int or1ksim_clock_rate ()
|
|
|
Return the @value{OR1KSIM} clock rate (in Hz). This is the value
|
Return the @value{OR1KSIM} clock rate (in Hz). This is the value
|
specified in the configuration file.
|
specified in the configuration file.
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt (int @var{i})
|
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt (int @var{i})
|
|
|
Generate an edge-triggered interrupt on interrupt line @var{i}. The
|
Generate an edge-triggered interrupt on interrupt line @var{i}. The
|
interrupt must be cleared separately by clearing the corresponding bit
|
interrupt must be cleared separately by clearing the corresponding bit
|
in the PICSR SPR. Until the interrupt is cleared, any further
|
in the PICSR SPR. Until the interrupt is cleared, any further
|
interrupts on the same line will be ignored with a warning. A warning
|
interrupts on the same line will be ignored with a warning. A warning
|
will be generated and the interrupt request ignored if level sensitive
|
will be generated and the interrupt request ignored if level sensitive
|
interrupts have been configured with the programmable interrupt
|
interrupts have been configured with the programmable interrupt
|
controller (@pxref{Interrupt Configuration, , Interrupt Configuration}).
|
controller (@pxref{Interrupt Configuration, , Interrupt Configuration}).
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_set (int @var{i})
|
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_set (int @var{i})
|
|
|
Assert a level-triggered interrupt on interrupt line @var{i}. The
|
Assert a level-triggered interrupt on interrupt line @var{i}. The
|
interrupt must be cleared separately by an explicit call to
|
interrupt must be cleared separately by an explicit call to
|
@code{or1ksim_interrupt_clear}. Until the interrupt is cleared, any
|
@code{or1ksim_interrupt_clear}. Until the interrupt is cleared, any
|
further setting of interrupts on the same line will be ignored with a
|
further setting of interrupts on the same line will be ignored with a
|
warning. A warning will be generated, and the interrupt request ignored
|
warning. A warning will be generated, and the interrupt request ignored
|
if edge sensitive interrupts have been configured with the programmable
|
if edge sensitive interrupts have been configured with the programmable
|
interrupt controller (@pxref{Interrupt Configuration, , Interrupt
|
interrupt controller (@pxref{Interrupt Configuration, , Interrupt
|
Configuration}).
|
Configuration}).
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_clear (int @var{i})
|
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_clear (int @var{i})
|
|
|
Clear a level-triggered interrupt on interrupt line @var{i}, which was
|
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
|
previously asserted by a call to @code{or1ksim_interrupt_set}. A warning will
|
be generated, and the interrupt request ignored if edge sensitive interrupts
|
be generated, and the interrupt request ignored if edge sensitive interrupts
|
have been configured with the programmable interrupt controller
|
have been configured with the programmable interrupt controller
|
(@pxref{Interrupt Configuration, , Interrupt Configuration}).
|
(@pxref{Interrupt Configuration, , Interrupt Configuration}).
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_reset ()
|
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_reset ()
|
|
|
Drive a reset sequence through the JTAG interface. Return the (model)
|
Drive a reset sequence through the JTAG interface. Return the (model)
|
time taken for this action. Remember that the JTAG has its own clock,
|
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
|
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.
|
reset (5 JTAG cycles) could take 50 processor clock cycles to complete.
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_ir @
|
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_ir @
|
(unsigned char *@var{jreg}, int @var{num_bits})
|
(unsigned char *@var{jreg}, int @var{num_bits})
|
|
|
Shift the supplied register through the JTAG instruction register.
|
Shift the supplied register through the JTAG instruction register.
|
Return the (model) time taken for this action. The register is supplied
|
Return the (model) time taken for this action. The register is supplied
|
as a byte vector, with the least significant bits in the least
|
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
|
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
|
bytes, then the odd bits are found in the least significant end of the
|
highest numbered byte.
|
highest numbered byte.
|
|
|
For example a 12-bit register would have bits 0-7 in byte 0 and bits
|
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.
|
11-8 in the least significant 4 bits of byte 1.
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_dr @
|
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_dr @
|
(unsigned char *@var{jreg}, int @var{num_bits})
|
(unsigned char *@var{jreg}, int @var{num_bits})
|
|
|
Shift the supplied register through the JTAG data register. Return the
|
Shift the supplied register through the JTAG data register. Return the
|
(model) time taken for this action. The register is supplied as a byte
|
(model) time taken for this action. The register is supplied as a byte
|
vector, with the least significant bits in the least significant 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
|
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
|
odd bits are found in the least significant end of the highest numbered
|
byte.
|
byte.
|
|
|
For example a 12-bit register would have bits 0-7 in byte 0 and bits
|
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.
|
11-8 in the least significant 4 bits of byte 1.
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_read_mem @
|
@deftypefn {@file{or1ksim.h}} int or1ksim_read_mem @
|
(unsigned long int @var{addr}, unsigned char *@var{buf}, @
|
(unsigned long int @var{addr}, unsigned char *@var{buf}, @
|
int @var{len})
|
int @var{len})
|
|
|
Read @var{len} bytes from @var{addr}, placing the result in @var{buf}.
|
Read @var{len} bytes from @var{addr}, placing the result in @var{buf}.
|
Return @var{len} on success and 0 on failure.
|
Return @var{len} on success and 0 on failure.
|
|
|
@quotation Note
|
@quotation Note
|
This function was added in @value{OR1KSIM} 0.5.0.
|
This function was added in @value{OR1KSIM} 0.5.0.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_write_mem @
|
@deftypefn {@file{or1ksim.h}} int or1ksim_write_mem @
|
(unsigned long int @var{addr}, const unsigned char *@var{buf}, @
|
(unsigned long int @var{addr}, const unsigned char *@var{buf}, @
|
int @var{len})
|
int @var{len})
|
|
|
Write @var{len} bytes to @var{addr}, taking the data from @var{buf}.
|
Write @var{len} bytes to @var{addr}, taking the data from @var{buf}.
|
Return @var{len} on success and 0 on failure.
|
Return @var{len} on success and 0 on failure.
|
|
|
@quotation Note
|
@quotation Note
|
This function was added in @value{OR1KSIM} 0.5.0.
|
This function was added in @value{OR1KSIM} 0.5.0.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_read_spr (int @var{sprnum}, @
|
@deftypefn {@file{or1ksim.h}} int or1ksim_read_spr (int @var{sprnum}, @
|
unsigned long int *@var{sprval_ptr})
|
unsigned long int *@var{sprval_ptr})
|
|
|
Read the SPR specified by @var{sprnum}, placing the result in
|
Read the SPR specified by @var{sprnum}, placing the result in
|
@var{sprval_ptr}. Return non-zero on success and 0 on failure.
|
@var{sprval_ptr}. Return non-zero on success and 0 on failure.
|
|
|
@quotation Note
|
@quotation Note
|
This function was added in @value{OR1KSIM} 0.5.0.
|
This function was added in @value{OR1KSIM} 0.5.0.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_write_spr (int @var{sprnum}, @
|
@deftypefn {@file{or1ksim.h}} int or1ksim_write_spr (int @var{sprnum}, @
|
unsigned long int @var{sprva})
|
unsigned long int @var{sprva})
|
|
|
Write @var{sprval} to the SPR specified by @var{sprnum}. Return
|
Write @var{sprval} to the SPR specified by @var{sprnum}. Return
|
non-zero on success and 0 on failure.
|
non-zero on success and 0 on failure.
|
|
|
@quotation Note
|
@quotation Note
|
This function was added in @value{OR1KSIM} 0.5.0.
|
This function was added in @value{OR1KSIM} 0.5.0.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_read_reg (int @var{regnum}, @
|
@deftypefn {@file{or1ksim.h}} int or1ksim_read_reg (int @var{regnum}, @
|
unsigned long int *@var{regval_ptr})
|
unsigned long int *@var{regval_ptr})
|
|
|
Read the general purpose register specified by @var{regnum}, placing the
|
Read the general purpose register specified by @var{regnum}, placing the
|
result in @var{regval_ptr}. Return non-zero on success and 0 on
|
result in @var{regval_ptr}. Return non-zero on success and 0 on
|
failure.
|
failure.
|
|
|
@quotation Note
|
@quotation Note
|
This function was added in @value{OR1KSIM} 0.5.0.
|
This function was added in @value{OR1KSIM} 0.5.0.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} int or1ksim_write_reg (int @var{regnum}, @
|
@deftypefn {@file{or1ksim.h}} int or1ksim_write_reg (int @var{regnum}, @
|
unsigned long int @var{regva})
|
unsigned long int @var{regva})
|
|
|
Write @var{regval} to the general purpose register specified by
|
Write @var{regval} to the general purpose register specified by
|
@var{regnum}. Return non-zero on success and 0 on failure.
|
@var{regnum}. Return non-zero on success and 0 on failure.
|
|
|
@quotation Note
|
@quotation Note
|
This function was added in @value{OR1KSIM} 0.5.0.
|
This function was added in @value{OR1KSIM} 0.5.0.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
@deftypefn {@file{or1ksim.h}} void or1ksim_set_stall_state (int @var{state})
|
@deftypefn {@file{or1ksim.h}} void or1ksim_set_stall_state (int @var{state})
|
|
|
Set the processor's state according to @var{state} (1 = stalled, 0 = not
|
Set the processor's state according to @var{state} (1 = stalled, 0 = not
|
stalled).
|
stalled).
|
|
|
@quotation Note
|
@quotation Note
|
This function was added in @value{OR1KSIM} 0.5.0.
|
This function was added in @value{OR1KSIM} 0.5.0.
|
@end quotation
|
@end quotation
|
|
|
@end deftypefn
|
@end deftypefn
|
|
|
The libraries will be installed in the @file{lib} sub-directory of the
|
The libraries will be installed in the @file{lib} sub-directory of the
|
main installation directory (as specified with the @option{--prefix}
|
main installation directory (as specified with the @option{--prefix}
|
option to the @command{configure} script).
|
option to the @command{configure} script).
|
|
|
For example if the main installation directory is @file{/opt/or1ksim},
|
For example if the main installation directory is @file{/opt/or1ksim},
|
the library will be found in the @file{/opt/or1ksim/lib} directory. It
|
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
|
is available as both a static library (@file{libsim.a}) and a shared
|
object (@file{libsim.so}).
|
object (@file{libsim.so}).
|
|
|
To link against the library add the @option{-lsim} flag when linking
|
To link against the library add the @option{-lsim} flag when linking
|
and do one of the following:
|
and do one of the following:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
|
|
@item
|
@item
|
Add the library directory to the @code{LD_LIBRARY_PATH} environment
|
Add the library directory to the @code{LD_LIBRARY_PATH} environment
|
variable during execution. For example:
|
variable during execution. For example:
|
|
|
@example
|
@example
|
export LD_LIBRARY_PATH=/opt/or1ksim/lib:$LD_LIBRARY_PATH
|
export LD_LIBRARY_PATH=/opt/or1ksim/lib:$LD_LIBRARY_PATH
|
@end example
|
@end example
|
|
|
@item
|
@item
|
Add the library directory to the @code{LD_RUN_PATH} environment
|
Add the library directory to the @code{LD_RUN_PATH} environment
|
variable during linking. For example:
|
variable during linking. For example:
|
|
|
@example
|
@example
|
export LD_RUN_PATH=/opt/or1ksim/lib:$LD_RUN_PATH
|
export LD_RUN_PATH=/opt/or1ksim/lib:$LD_RUN_PATH
|
@end example
|
@end example
|
|
|
@item
|
@item
|
Use the linker @option{--rpath} option and specify the library
|
Use the linker @option{--rpath} option and specify the library
|
directory when linking your program. For example
|
directory when linking your program. For example
|
|
|
@example
|
@example
|
gcc ... -Wl,--rpath -Wl,/opt/or1ksim/lib ...
|
gcc ... -Wl,--rpath -Wl,/opt/or1ksim/lib ...
|
@end example
|
@end example
|
|
|
@item
|
@item
|
Add the library directory to @file{/etc/ld.so.conf}
|
Add the library directory to @file{/etc/ld.so.conf}
|
|
|
@end itemize
|
@end itemize
|
|
|
@node Ethernet TUN/TAP Interface
|
@node Ethernet TUN/TAP Interface
|
@section Ethernet TUN/TAP Interface
|
@section Ethernet TUN/TAP Interface
|
@cindex configuring the Ethernet TUN/TAP interface
|
@cindex configuring the Ethernet TUN/TAP interface
|
|
|
When an Ethernet peripheral is configured (@pxref{Ethernet
|
When an Ethernet peripheral is configured (@pxref{Ethernet
|
Configuration, , Ethernet Configuration}), one option is to tunnel
|
Configuration, , Ethernet Configuration}), one option is to tunnel
|
traffic through a TUN/TAP interface. The low level TAP interface is used
|
traffic through a TUN/TAP interface. The low level TAP interface is used
|
to tunnel raw Ethernet datagrams.
|
to tunnel raw Ethernet datagrams.
|
|
|
The TAP interface can then be connected to a physical Ethernet through a
|
The TAP interface can then be connected to a physical Ethernet through a
|
bridge, allowing the @value{OR1KSIM} model to connect to a physical
|
bridge, allowing the @value{OR1KSIM} model to connect to a physical
|
network. This is particularly when @value{OR1KSIM} is running the
|
network. This is particularly when @value{OR1KSIM} is running the
|
OpenRISC Linux kernel image.
|
OpenRISC Linux kernel image.
|
|
|
This section explains how to set up a bridge for use by @value{OR1KSIM}. It does
|
This section explains how to set up a bridge for use by @value{OR1KSIM}. It does
|
require superuser access to the host machine (or at least the relevant
|
require superuser access to the host machine (or at least the relevant
|
network capabilities). A system administrator can modify these
|
network capabilities). A system administrator can modify these
|
guidelines so they are executed on reboot if appropriate.
|
guidelines so they are executed on reboot if appropriate.
|
|
|
@menu
|
@menu
|
* Setting Up a Persistent TAP device::
|
* Setting Up a Persistent TAP device::
|
* Establishing a Bridge::
|
* Establishing a Bridge::
|
* Opening the Firewall::
|
* Opening the Firewall::
|
* Disabling Ethernet Filtering::
|
* Disabling Ethernet Filtering::
|
* Networking from OpenRISC Linux and BusyBox::
|
* Networking from OpenRISC Linux and BusyBox::
|
* Tearing Down a Bridge::
|
* Tearing Down a Bridge::
|
@end menu
|
@end menu
|
|
|
@node Setting Up a Persistent TAP device
|
@node Setting Up a Persistent TAP device
|
@subsection Setting Up a Persistent TAP device
|
@subsection Setting Up a Persistent TAP device
|
@cindex persistent TAP device creation
|
@cindex persistent TAP device creation
|
@cindex TAP device creation
|
@cindex TAP device creation
|
|
|
TUN/TAP devices can be created dynamically, but this requires superuser
|
TUN/TAP devices can be created dynamically, but this requires superuser
|
privileges (or at least @code{CAP_NET_ADMIN} capability). The solution
|
privileges (or at least @code{CAP_NET_ADMIN} capability). The solution
|
is to create a persistent TAP device. This can be done using either
|
is to create a persistent TAP device. This can be done using either
|
@command{openvpn} or @command{tunctl}. In either case the package must
|
@command{openvpn} or @command{tunctl}. In either case the package must
|
be installed on the host system. Using @command{openvpn}, the following
|
be installed on the host system. Using @command{openvpn}, the following
|
would set up a TAP interface for a specified user and group.
|
would set up a TAP interface for a specified user and group.
|
|
|
@example
|
@example
|
openvpn --mktun --dev tap@emph{n} --user @emph{username} --group @emph{groupname}
|
openvpn --mktun --dev tap@emph{n} --user @emph{username} --group @emph{groupname}
|
@end example
|
@end example
|
|
|
@node Establishing a Bridge
|
@node Establishing a Bridge
|
@subsection Establishing a Bridge
|
@subsection Establishing a Bridge
|
@cindex bridge setup
|
@cindex bridge setup
|
@cindex Ethernet bridge setup
|
@cindex Ethernet bridge setup
|
|
|
A bridge is a ``virtual'' local area network interfaces, subsuming two or more
|
A bridge is a ``virtual'' local area network interfaces, subsuming two or more
|
existing network interfaces. In this case we will bridge the physical
|
existing network interfaces. In this case we will bridge the physical
|
Ethernet interface of the host with the TAP interface that will be used
|
Ethernet interface of the host with the TAP interface that will be used
|
by @value{OR1KSIM}.
|
by @value{OR1KSIM}.
|
|
|
The Ethernet and TAP must lose their own individual IP addresses (by
|
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
|
setting them to 0.0.0.0) and are replaced by the IP address of the
|
bridge interface. To do this we use the @command{bridge-utils} package,
|
bridge interface. To do this we use the @command{bridge-utils} package,
|
which must be installed on the host system. These commands are require
|
which must be installed on the host system. These commands are require
|
superuser privileges or @code{CAP_NET_ADMIN} capability. To create a new
|
superuser privileges or @code{CAP_NET_ADMIN} capability. To create a new
|
interface @code{br@emph{n}} the following commands are appropriate.
|
interface @code{br@emph{n}} the following commands are appropriate.
|
|
|
@example
|
@example
|
brctl addbr br@emph{n}
|
brctl addbr br@emph{n}
|
brctl addif br@emph{n} eth@emph{x}
|
brctl addif br@emph{n} eth@emph{x}
|
brctl addif br@emph{n} tap@emph{y}
|
brctl addif br@emph{n} tap@emph{y}
|
|
|
ifconfig eth@emph{x} 0.0.0.0 promisc up
|
ifconfig eth@emph{x} 0.0.0.0 promisc up
|
ifconfig tap@emph{y} 0.0.0.0 promisc up
|
ifconfig tap@emph{y} 0.0.0.0 promisc up
|
|
|
dhclient br@emph{n}
|
dhclient br@emph{n}
|
@end example
|
@end example
|
|
|
The last command instructs the bridge to obtain its IP address, netmask,
|
The last command instructs the bridge to obtain its IP address, netmask,
|
broadcast address, gateway and nameserver information using DHCP. In a
|
broadcast address, gateway and nameserver information using DHCP. In a
|
network without DHCP it should be replaced by @command{ifconfig} to set
|
network without DHCP it should be replaced by @command{ifconfig} to set
|
a static IP address, netmask and broadcast address.
|
a static IP address, netmask and broadcast address.
|
|
|
@quotation Note
|
@quotation Note
|
This will leave a spare dhclient process running in the background,
|
This will leave a spare dhclient process running in the background,
|
which should be killed for tidiness. There is a technique to avoid this
|
which should be killed for tidiness. There is a technique to avoid this
|
using @command{omshell}, but that is beyond the scope of this guide.
|
using @command{omshell}, but that is beyond the scope of this guide.
|
@end quotation
|
@end quotation
|
|
|
@quotation Note
|
@quotation Note
|
It is not clear to the author why the existing interfaces need to be
|
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.
|
brought up in promiscuous mode, but it seems to cure various problems.
|
@end quotation
|
@end quotation
|
|
|
@node Opening the Firewall
|
@node Opening the Firewall
|
@subsection Opening the Firewall
|
@subsection Opening the Firewall
|
@cindex firewall with Ethernet bridge and TAP/TUN
|
@cindex firewall with Ethernet bridge and TAP/TUN
|
|
|
Firewall rules should be added to ensure traffic flows freely through
|
Firewall rules should be added to ensure traffic flows freely through
|
the TAP and bridge interfaces. As superuser the following commands are
|
the TAP and bridge interfaces. As superuser the following commands are
|
appropriate.
|
appropriate.
|
|
|
@example
|
@example
|
iptables -A INPUT -i tap@emph{y} -j ACCEPT
|
iptables -A INPUT -i tap@emph{y} -j ACCEPT
|
iptables -A INPUT -i br@emph{n} -j ACCEPT
|
iptables -A INPUT -i br@emph{n} -j ACCEPT
|
iptables -A FORWARD -i br@emph{n} -j ACCEPT
|
iptables -A FORWARD -i br@emph{n} -j ACCEPT
|
@end example
|
@end example
|
|
|
@node Disabling Ethernet Filtering
|
@node Disabling Ethernet Filtering
|
@subsection Disabling Ethernet Filtering
|
@subsection Disabling Ethernet Filtering
|
|
|
Some systems may have ethernet filtering enabled (@command{ebtables},
|
Some systems may have ethernet filtering enabled (@command{ebtables},
|
@command{bridge-nf}, @command{arptables}) which will stop traffic
|
@command{bridge-nf}, @command{arptables}) which will stop traffic
|
flowing through the bridge.
|
flowing through the bridge.
|
|
|
The easiest way to disable this is by writing zero to all
|
The easiest way to disable this is by writing zero to all
|
@file{bridge-nf-*} entries in @file{/proc/sys/net/bridge}. As superuser
|
@file{bridge-nf-*} entries in @file{/proc/sys/net/bridge}. As superuser
|
the following commands will achieve this.
|
the following commands will achieve this.
|
|
|
@example
|
@example
|
cd /proc/sys/net/bridge
|
cd /proc/sys/net/bridge
|
for f in bridge-nf-*; do echo 0 > $f; done
|
for f in bridge-nf-*; do echo 0 > $f; done
|
@end example
|
@end example
|
|
|
@node Networking from OpenRISC Linux and BusyBox
|
@node Networking from OpenRISC Linux and BusyBox
|
@subsection Networking from OpenRISC Linux and BusyBox
|
@subsection Networking from OpenRISC Linux and BusyBox
|
@cindex BusyBox and Ethernet
|
@cindex BusyBox and Ethernet
|
@cindex Linux (OpenRISC) and Ethernet
|
@cindex Linux (OpenRISC) and Ethernet
|
|
|
The main use of this style of Ethernet interface to @value{OR1KSIM} is when
|
The main use of this style of Ethernet interface to @value{OR1KSIM} is when
|
running the OpenRISC Linux kernel with BusyBox. The following commands
|
running the OpenRISC Linux kernel with BusyBox. The following commands
|
in the BusyBox console window will configure the Ethernet interface
|
in the BusyBox console window will configure the Ethernet interface
|
(assumed to be @code{eth0}) and bring it up with a DHCP assigned
|
(assumed to be @code{eth0}) and bring it up with a DHCP assigned
|
address.
|
address.
|
|
|
@example
|
@example
|
ifconfig eth0
|
ifconfig eth0
|
ifup eth0
|
ifup eth0
|
@end example
|
@end example
|
|
|
At this stage interface to IP addresses will work correctly.
|
At this stage interface to IP addresses will work correctly.
|
|
|
For DNS to work the BusyBox system needs to know where to find a
|
For DNS to work the BusyBox system needs to know where to find a
|
nameserver. Under BusyBox, @command{udhcp} does not configure
|
nameserver. Under BusyBox, @command{udhcp} does not configure
|
@file{/etc/resolv.conf} automatically.
|
@file{/etc/resolv.conf} automatically.
|
|
|
The solution is to duplicate the nameserver entry from the
|
The solution is to duplicate the nameserver entry from the
|
@file{/etc/resolv.conf} file of the host on the BusyBox system. A
|
@file{/etc/resolv.conf} file of the host on the BusyBox system. A
|
typical file might be as follows:
|
typical file might be as follows:
|
|
|
@example
|
@example
|
@code{nameserver 192.168.0.1}
|
@code{nameserver 192.168.0.1}
|
@end example
|
@end example
|
|
|
It is convenient to make this permanent within the Linux initramfs. Add
|
It is convenient to make this permanent within the Linux initramfs. Add
|
the file as @code{arch/openrisc/support/initramfs/etc/resolv.conf}
|
the file as @code{arch/openrisc/support/initramfs/etc/resolv.conf}
|
within the Linux source tree and rebuild @code{vmlinux}. It will then be
|
within the Linux source tree and rebuild @code{vmlinux}. It will then be
|
present automatically.
|
present automatically.
|
|
|
One of the most useful functions that is possible is to mount
|
One of the most useful functions that is possible is to mount
|
the host file system through NFS. For example, from the BusyBox console:
|
the host file system through NFS. For example, from the BusyBox console:
|
|
|
@example
|
@example
|
mount -t nfs -o nolock 192.168.0.60:/home /mnt
|
mount -t nfs -o nolock 192.168.0.60:/home /mnt
|
@end example
|
@end example
|
|
|
Another useful technique is to telnet into the BusyBox system from the
|
Another useful technique is to telnet into the BusyBox system from the
|
host. This is particularly valuable when a console process locks up,
|
host. This is particularly valuable when a console process locks up,
|
since the @command{xterm} console will not recognize ctrl-C. Instead the
|
since the @command{xterm} console will not recognize ctrl-C. Instead the
|
rogue process can be killed from a telnet connection.
|
rogue process can be killed from a telnet connection.
|
|
|
@node Tearing Down a Bridge
|
@node Tearing Down a Bridge
|
@subsection Tearing Down a Bridge
|
@subsection Tearing Down a Bridge
|
|
|
There is little reason why a bridge should ever need to be torn down,
|
There is little reason why a bridge should ever need to be torn down,
|
but if desired, the following commands will achieve the effect.
|
but if desired, the following commands will achieve the effect.
|
|
|
@example
|
@example
|
ifconfig br@emph{n} down
|
ifconfig br@emph{n} down
|
brctl delbr br@emph{n}
|
brctl delbr br@emph{n}
|
|
|
dhclient eth@emph{x}
|
dhclient eth@emph{x}
|
@end example
|
@end example
|
|
|
As before this will leave a spare @command{dhclient} process in the
|
As before this will leave a spare @command{dhclient} process in the
|
background which should be killed.
|
background which should be killed.
|
|
|
If desired the TAP interface can be deleted using
|
If desired the TAP interface can be deleted using
|
|
|
@example
|
@example
|
openvpn --rmtun -dev tap@emph{y}
|
openvpn --rmtun -dev tap@emph{y}
|
@end example
|
@end example
|
|
|
@quotation Caution
|
@quotation Caution
|
The TAP interface should not be in use when running this command. For
|
The TAP interface should not be in use when running this command. For
|
example any OpenRISC Linux/BusyBox sessions should be closed first.
|
example any OpenRISC Linux/BusyBox sessions should be closed first.
|
@end quotation
|
@end quotation
|
|
|
@node l.nop Support
|
@node l.nop Support
|
@section l.nop Opcode Support
|
@section l.nop Opcode Support
|
@cindex l.nop opcode effects
|
@cindex l.nop opcode effects
|
|
|
The OpenRISC @code{l.nop} opcode can take a parameter. This has no
|
The OpenRISC @code{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 on the semantics of the opcode, but can be used to trigger side
|
effect behavior in a simulator. Within Or1ksim, the following parameters
|
effect behavior in a simulator. Within Or1ksim, the following parameters
|
are supported.
|
are supported.
|
|
|
@table @code
|
@table @code
|
|
|
@item l.nop 0
|
@item l.nop 0
|
@cindex @code{l.nop 0}
|
@cindex @code{l.nop 0}
|
|
|
The equivalent to @code{l.nop} with no parameter. Has no side effects.
|
The equivalent to @code{l.nop} with no parameter. Has no side effects.
|
|
|
@item l.nop 1
|
@item l.nop 1
|
@cindex @code{l.nop 1} (end simulation)
|
@cindex @code{l.nop 1} (end simulation)
|
|
|
Execution of Or1ksim is terminated. This is used to implement the
|
Execution of Or1ksim is terminated. This is used to implement the
|
library @code{exit} functions.
|
library @code{exit} functions.
|
|
|
@item l.nop 2
|
@item l.nop 2
|
@cindex @code{l.nop 2} (report)
|
@cindex @code{l.nop 2} (report)
|
|
|
Report the value in @code{r3} on the console as a 32-bit hex value.
|
Report the value in @code{r3} on the console as a 32-bit hex value.
|
|
|
@item l.nop 3
|
@item l.nop 3
|
@cindex @code{l.nop 3} (printf, now obsolete)
|
@cindex @code{l.nop 3} (printf, now obsolete)
|
|
|
In earlier versions of @value{OR1KSIM} this treated @code{r3} as a
|
In earlier versions of @value{OR1KSIM} this treated @code{r3} as a
|
pointer to a @code{printf} style format string, and regsiters @code{r4}
|
pointer to a @code{printf} style format string, and regsiters @code{r4}
|
through @code{r8} as parameters for that format string.
|
through @code{r8} as parameters for that format string.
|
|
|
This opcode is no longer supported, and has no effect if used.
|
This opcode is no longer supported, and has no effect if used.
|
|
|
@item l.nop 4
|
@item l.nop 4
|
@cindex @code{l.nop 4} (putc)
|
@cindex @code{l.nop 4} (putc)
|
|
|
The value in @code{r3} is printed to standard output as an ASCII
|
The value in @code{r3} is printed to standard output as an ASCII
|
character. All library output routines are implemented using this opcode.
|
character. All library output routines are implemented using this opcode.
|
|
|
@item l.nop 5
|
@item l.nop 5
|
@cindex @code{l.nop 5} (reset statistics counters)
|
@cindex @code{l.nop 5} (reset statistics counters)
|
|
|
The statistics counters are reset.
|
The statistics counters are reset.
|
|
|
@item l.nop 6
|
@item l.nop 6
|
@cindex @code{l.nop 6} (get clock ticks)
|
@cindex @code{l.nop 6} (get clock ticks)
|
|
|
The number of clock ticks since start of execution (a 64-bit value) is
|
The number of clock ticks since start of execution (a 64-bit value) is
|
returned in @code{r11} (low 32 bits) and @code{r12} (high 32 bits).
|
returned in @code{r11} (low 32 bits) and @code{r12} (high 32 bits).
|
|
|
@item l.nop 7
|
@item l.nop 7
|
@cindex @code{l.nop 7} (get picoseconds per cycle)
|
@cindex @code{l.nop 7} (get picoseconds per cycle)
|
|
|
The number of picoseconds per clock cycle is returned in @code{r11}.
|
The number of picoseconds per clock cycle is returned in @code{r11}.
|
This is used with @code{l.nop 6} to implement timing functions.
|
This is used with @code{l.nop 6} to implement timing functions.
|
|
|
@item l.nop 8
|
@item l.nop 8
|
@cindex @code{l.nop 8} (turn on tracing)
|
@cindex @code{l.nop 8} (turn on tracing)
|
|
|
Instruction tracing is turned on.
|
Instruction tracing is turned on.
|
|
|
@item l.nop 9
|
@item l.nop 9
|
@cindex @code{l.nop 9} (turn off tracing)
|
@cindex @code{l.nop 9} (turn off tracing)
|
|
|
Instruction tracing is turned off.
|
Instruction tracing is turned off.
|
|
|
@end table
|
@end table
|
|
|
@node Configuration
|
@node Configuration
|
@chapter Configuration
|
@chapter Configuration
|
@cindex configuring @value{OR1KSIM}
|
@cindex configuring @value{OR1KSIM}
|
|
|
@value{OR1KSIM} is configured through a configuration file. This is specified
|
@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
|
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,
|
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
|
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.
|
current directory, then in the @file{$HOME/.or1ksim} directory of the user.
|
|
|
@menu
|
@menu
|
* Configuration File Format::
|
* Configuration File Format::
|
* Simulator Configuration::
|
* Simulator Configuration::
|
* Core OpenRISC Configuration::
|
* Core OpenRISC Configuration::
|
* Peripheral Configuration::
|
* Peripheral Configuration::
|
@end menu
|
@end menu
|
|
|
@node Configuration File Format
|
@node Configuration File Format
|
@section Configuration File Format
|
@section Configuration File Format
|
@cindex configuration file structure
|
@cindex configuration file structure
|
|
|
The configuration file is a plain text file. A reference example,
|
The configuration file is a plain text file. A reference example,
|
@file{sim.cfg}, is included in the top level directory of the
|
@file{sim.cfg}, is included in the top level directory of the
|
distribution.
|
distribution.
|
|
|
@menu
|
@menu
|
* Configuration File Preprocessing::
|
* Configuration File Preprocessing::
|
* Configuration File Syntax::
|
* Configuration File Syntax::
|
@end menu
|
@end menu
|
|
|
@node Configuration File Preprocessing
|
@node Configuration File Preprocessing
|
@subsection Configuration File Preprocessing
|
@subsection Configuration File Preprocessing
|
|
|
The configuration file may include C style comments (i.e. delimited by
|
The configuration file may include C style comments (i.e. delimited by
|
@code{/*} and @code{*/}).
|
@code{/*} and @code{*/}).
|
|
|
@node Configuration File Syntax
|
@node Configuration File Syntax
|
@subsection Configuration File Syntax
|
@subsection Configuration File Syntax
|
|
|
The configuration file is divided into a series of sections, with the general
|
The configuration file is divided into a series of sections, with the general
|
form:
|
form:
|
|
|
@example
|
@example
|
section @var{section_name}
|
section @var{section_name}
|
|
|
<contents>...
|
<contents>...
|
|
|
end
|
end
|
@end example
|
@end example
|
|
|
Sections may also have sub-sections within them (currently only the
|
Sections may also have sub-sections within them (currently only the
|
ATA/ATAPI disc interface uses this).
|
ATA/ATAPI disc interface uses this).
|
|
|
Within a section, or sub-section are a series of parameter assignments, one
|
Within a section, or sub-section are a series of parameter assignments, one
|
per line, withe the general form
|
per line, withe the general form
|
|
|
@example
|
@example
|
@var{parameter} = @var{value}
|
@var{parameter} = @var{value}
|
@end example
|
@end example
|
|
|
Depending on the parameter, the value may be a named value (an enumeration),
|
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
|
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''
|
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
|
and the value ``0'' to mean ``false'' or ``off''. An example from a memory
|
section shows each of these
|
section shows each of these
|
|
|
@example
|
@example
|
section memory
|
section memory
|
type = random
|
type = random
|
pattern = 0x00
|
pattern = 0x00
|
name = "FLASH"
|
name = "FLASH"
|
...
|
...
|
end
|
end
|
@end example
|
@end example
|
|
|
Many parameters are optional and take reasonable default values if not
|
Many parameters are optional and take reasonable default values if not
|
specified. However there are some parameters (for example the
|
specified. However there are some parameters (for example the
|
@code{ce} parameter in @code{@w{section memory}}) @emph{must} be
|
@code{ce} parameter in @code{@w{section memory}}) @emph{must} be
|
specified.
|
specified.
|
|
|
Subsections are introduced by a keyword, with a parameter value (no
|
Subsections are introduced by a keyword, with a parameter value (no
|
@code{=} sign), and end with the same keyword prefixed by
|
@code{=} sign), and end with the same keyword prefixed by
|
@code{end}. Thus the ATA/ATAPI inteface (@code{@w{section ata}}) has a
|
@code{end}. Thus the ATA/ATAPI inteface (@code{@w{section ata}}) has a
|
@code{device} subsection, thus:
|
@code{device} subsection, thus:
|
|
|
@example
|
@example
|
section ata
|
section ata
|
...
|
...
|
device 0
|
device 0
|
type = 1
|
type = 1
|
file = "@var{filename}"
|
file = "@var{filename}"
|
...
|
...
|
enddevice
|
enddevice
|
...
|
...
|
end
|
end
|
@end example
|
@end example
|
|
|
Some sections (for example @code{@w{section sim}}) should appear only
|
Some sections (for example @code{@w{section sim}}) should appear only
|
once. Others (for example @code{@w{section memory}} may appear
|
once. Others (for example @code{@w{section memory}} may appear
|
multiple times.
|
multiple times.
|
|
|
Sections may be omitted, @emph{unless they contain parameters which
|
Sections may be omitted, @emph{unless they contain parameters which
|
are non-optional}. If the section describes a part of the simulator
|
are non-optional}. If the section describes a part of the simulator
|
which is optional (for example whether it has a UART), then that
|
which is optional (for example whether it has a UART), then that
|
functionality will not be provided. If the section describes a part of
|
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
|
the simulator which is not optional (for example the CPU), then all the
|
parameters of that section will take their default values.
|
parameters of that section will take their default values.
|
|
|
All optional parts of the functionality are always described by
|
All optional parts of the functionality are always described by
|
sections including a @code{enabled} parameter, which can be set to 0
|
sections including a @code{enabled} parameter, which can be set to 0
|
to ensure that functionality is explicitly omitted.
|
to ensure that functionality is explicitly omitted.
|
|
|
Even if a section is disabled, all its parameters will be read and
|
Even if a section is disabled, all its parameters will be read and
|
stored. This is helpful if the section is subsequently enabled from
|
stored. This is helpful if the section is subsequently enabled from
|
the @value{OR1KSIM} command line (@pxref{Interactive Command Line, ,
|
the @value{OR1KSIM} command line (@pxref{Interactive Command Line, ,
|
Interactive Command Line}).
|
Interactive Command Line}).
|
|
|
@quotation Tip
|
@quotation Tip
|
It generally clearer to have sections describing @emph{all}
|
It generally clearer to have sections describing @emph{all}
|
components, with omitted functionality explicitly indicated by setting
|
components, with omitted functionality explicitly indicated by setting
|
the @code{enabled} parameter to 0
|
the @code{enabled} parameter to 0
|
@end quotation
|
@end quotation
|
|
|
The following sections describe the various configuration sections and the
|
The following sections describe the various configuration sections and the
|
parameters which may be set in each.
|
parameters which may be set in each.
|
|
|
@node Simulator Configuration
|
@node Simulator Configuration
|
@section Simulator Configuration
|
@section Simulator Configuration
|
|
|
@menu
|
@menu
|
* Simulator Behavior::
|
* Simulator Behavior::
|
* Verification API Configuration::
|
* Verification API Configuration::
|
* CUC Configuration::
|
* CUC Configuration::
|
@end menu
|
@end menu
|
|
|
@node Simulator Behavior
|
@node Simulator Behavior
|
@subsection Simulator Behavior
|
@subsection Simulator Behavior
|
@cindex configuring the behavior of @value{OR1KSIM}
|
@cindex configuring the behavior of @value{OR1KSIM}
|
@cindex simulator configuration
|
@cindex simulator configuration
|
@cindex @code{section sim}
|
@cindex @code{section sim}
|
Simulator behavior is described in @code{section sim}. This section
|
Simulator behavior is described in @code{section sim}. This section
|
should appear only once. The following parameters may be specified.
|
should appear only once. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item verbose = 0|1
|
@item verbose = 0|1
|
@cindex @code{verbose} (simulator configuration)
|
@cindex @code{verbose} (simulator configuration)
|
If 1 (true), print extra messages. Default 0.
|
If 1 (true), print extra messages. Default 0.
|
|
|
@item debug = 0-9
|
@item debug = 0-9
|
@cindex @code{debug} (simulator configuration)
|
@cindex @code{debug} (simulator configuration)
|
0 means no debug messages. 1-9 means produce debug messages. The higher the
|
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
|
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
|
will be treated as 0 (with a warning). Values that are too large will
|
be treated as 9 (with a warning).
|
be treated as 9 (with a warning).
|
|
|
@item profile = 0|1
|
@item profile = 0|1
|
@cindex @code{profile} (simulator configuration)
|
@cindex @code{profile} (simulator configuration)
|
If 1 (true) generate a profiling file using the file specified in the
|
If 1 (true) generate a profiling file using the file specified in the
|
@code{prof_file} parameter or otherwise @file{sim.profile}. Default 0.
|
@code{prof_file} parameter or otherwise @file{sim.profile}. Default 0.
|
|
|
@item prof_file = ``@var{filename}''
|
@item prof_file = ``@var{filename}''
|
@cindex @code{prof_file} (simulator configuration)
|
@cindex @code{prof_file} (simulator configuration)
|
@cindex @code{prof_fn} (simulator configuration - deprecated)
|
@cindex @code{prof_fn} (simulator configuration - deprecated)
|
Specifies the file to be used with the @code{profile} parameter. Default
|
Specifies the file to be used with the @code{profile} parameter. Default
|
@file{sim.profile}. For backwards compatibility, the alternative name
|
@file{sim.profile}. For backwards compatibility, the alternative name
|
@code{prof_fn} is supported for this parameter, but deprecated. Default
|
@code{prof_fn} is supported for this parameter, but deprecated. Default
|
@file{sim.profile}.
|
@file{sim.profile}.
|
|
|
|
|
@item mprofile = 0|1
|
@item mprofile = 0|1
|
@cindex @code{mprofile} (simulator configuration)
|
@cindex @code{mprofile} (simulator configuration)
|
If 1 (true) generate a memory profiling file using the file specified in the
|
If 1 (true) generate a memory profiling file using the file specified in the
|
@code{mprof_file} parameter or otherwise @file{sim.mprofile}. Default 0.
|
@code{mprof_file} parameter or otherwise @file{sim.mprofile}. Default 0.
|
|
|
@item mprof_file = ``@var{filename}''
|
@item mprof_file = ``@var{filename}''
|
@cindex @code{mprof_file} (simulator configuration)
|
@cindex @code{mprof_file} (simulator configuration)
|
@cindex @code{mprof_fn} (simulator configuration - deprecated)
|
@cindex @code{mprof_fn} (simulator configuration - deprecated)
|
Specifies the file to be used with the @code{mprofile} parameter. Default
|
Specifies the file to be used with the @code{mprofile} parameter. Default
|
@file{sim.mprofile}. For backwards compatibility, the alternative name
|
@file{sim.mprofile}. For backwards compatibility, the alternative name
|
@code{mprof_fn} is supported for this parameter, but deprecated.
|
@code{mprof_fn} is supported for this parameter, but deprecated.
|
Default @file{sim.mprofile}.
|
Default @file{sim.mprofile}.
|
|
|
@item history = 0|1
|
@item history = 0|1
|
@cindex @code{history} (simulator configuration)
|
@cindex @code{history} (simulator configuration)
|
If 1 (true) track execution flow. Default 0.
|
If 1 (true) track execution flow. Default 0.
|
|
|
@quotation Note
|
@quotation Note
|
Setting this parameter seriously degrades performance.
|
Setting this parameter seriously degrades performance.
|
@end quotation
|
@end quotation
|
|
|
@quotation Note
|
@quotation Note
|
If this execution flow tracking is enabled, then @code{dependstats}
|
If this execution flow tracking is enabled, then @code{dependstats}
|
must be enabled in the CPU configuration section (@pxref{CPU
|
must be enabled in the CPU configuration section (@pxref{CPU
|
Configuration, , CPU Configuration}).
|
Configuration, , CPU Configuration}).
|
@end quotation
|
@end quotation
|
|
|
@item exe_log = 0|1
|
@item exe_log = 0|1
|
@cindex @code{exe_log} (simulator configuration)
|
@cindex @code{exe_log} (simulator configuration)
|
If 1 (true), generate an execution log. Log is written to the file specified
|
If 1 (true), generate an execution log. Log is written to the file specified
|
in parameter @code{exe_log_file}. Default 0.
|
in parameter @code{exe_log_file}. Default 0.
|
|
|
@quotation Note
|
@quotation Note
|
Setting this parameter seriously degrades performance.
|
Setting this parameter seriously degrades performance.
|
@end quotation
|
@end quotation
|
|
|
@item exe_log_type = default|hardware|simple|software
|
@item exe_log_type = default|hardware|simple|software
|
@cindex @code{exe_log_type} (simulator configuration)
|
@cindex @code{exe_log_type} (simulator configuration)
|
Type of execution log to produce.
|
Type of execution log to produce.
|
|
|
@table @code
|
@table @code
|
|
|
@item default
|
@item default
|
@cindex @code{exe_log_type=default} (simulator configuration)
|
@cindex @code{exe_log_type=default} (simulator configuration)
|
Produce default output for the execution log. In the current implementation
|
Produce default output for the execution log. In the current implementation
|
this is the equivalent of @code{hardware}.
|
this is the equivalent of @code{hardware}.
|
|
|
@item hardware
|
@item hardware
|
@cindex @code{exe_log_type=hardware} (simulator configuration)
|
@cindex @code{exe_log_type=hardware} (simulator configuration)
|
After each instruction execution, log the number of instructions executed so
|
After each instruction execution, log the number of instructions executed so
|
far, the next instruction to execute (in hex), the general purpose registers
|
far, the next instruction to execute (in hex), the general purpose registers
|
(GPRs), status register, exception program counter, exception, effective
|
(GPRs), status register, exception program counter, exception, effective
|
address register and exception status register.
|
address register and exception status register.
|
|
|
@item simple
|
@item simple
|
@cindex @code{exe_log_type=simple} (simulator configuration)
|
@cindex @code{exe_log_type=simple} (simulator configuration)
|
After each instruction execution, log the number of instructions executed so
|
After each instruction execution, log the number of instructions executed so
|
far and the next instruction to execute, symbolically disassembled.
|
far and the next instruction to execute, symbolically disassembled.
|
|
|
@item software
|
@item software
|
@cindex @code{exe_log_type=software} (simulator configuration)
|
@cindex @code{exe_log_type=software} (simulator configuration)
|
After each instruction execution, log the number of instructions executed so
|
After each instruction execution, log the number of instructions executed so
|
far and the next instruction to execute, symbolically disassembled. Also show
|
far and the next instruction to execute, symbolically disassembled. Also show
|
the value of each operand to the instruction.
|
the value of each operand to the instruction.
|
|
|
@end table
|
@end table
|
|
|
Default value @code{hardware}. Any unrecognized keyword (case
|
Default value @code{hardware}. Any unrecognized keyword (case
|
insensitive) will be treated as the default with a warning.
|
insensitive) will be treated as the default with a warning.
|
|
|
@quotation Note
|
@quotation Note
|
Execution logs can be @emph{very} big.
|
Execution logs can be @emph{very} big.
|
@end quotation
|
@end quotation
|
|
|
@item exe_log_start = @var{value}
|
@item exe_log_start = @var{value}
|
@cindex @code{exe_log_start} (simulator configuration)
|
@cindex @code{exe_log_start} (simulator configuration)
|
Address of the first instruction to start logging. Default 0.
|
Address of the first instruction to start logging. Default 0.
|
|
|
@item exe_log_end = @var{value}
|
@item exe_log_end = @var{value}
|
@cindex @code{exe_log_end} (simulator configuration)
|
@cindex @code{exe_log_end} (simulator configuration)
|
Address of the last instruction to log. Default no limit (i.e once started
|
Address of the last instruction to log. Default no limit (i.e once started
|
logging will continue until the simulator exits).
|
logging will continue until the simulator exits).
|
|
|
@item exe_log_marker = @var{value}
|
@item exe_log_marker = @var{value}
|
@cindex @code{exe_log_marker} (simulator configuration)
|
@cindex @code{exe_log_marker} (simulator configuration)
|
Specifies the number of instructions between printing horizontal
|
Specifies the number of instructions between printing horizontal
|
markers. Default is to produce no markers.
|
markers. Default is to produce no markers.
|
|
|
@item exe_log_file = @var{filename}
|
@item exe_log_file = @var{filename}
|
@cindex @code{exe_log_file} (simulator configuration)
|
@cindex @code{exe_log_file} (simulator configuration)
|
@cindex @code{exe_log_fn} (simulator configuration - deprecated)
|
@cindex @code{exe_log_fn} (simulator configuration - deprecated)
|
Filename for the execution log filename if @code{exe_log} is enabled. Default
|
Filename for the execution log filename if @code{exe_log} is enabled. Default
|
@file{executed.log}. For backwards compatibility, the alternative name
|
@file{executed.log}. For backwards compatibility, the alternative name
|
@code{exe_log_fn} is supported for this parameter, but deprecated.
|
@code{exe_log_fn} is supported for this parameter, but deprecated.
|
|
|
@item exe_bin_insn_log = 0|1
|
@item exe_bin_insn_log = 0|1
|
@cindex @code{exe_bin_insn_log} (simulator configuration)
|
@cindex @code{exe_bin_insn_log} (simulator configuration)
|
Enable logging of executed instructions to a file in binary format.
|
Enable logging of executed instructions to a file in binary format.
|
This is helpful for off-line dynamic execution analysis.
|
This is helpful for off-line dynamic execution analysis.
|
|
|
@quotation Note
|
@quotation Note
|
Execution logs can be @emph{very} big. For example, while booting the
|
Execution logs can be @emph{very} big. For example, while booting the
|
Linux kernel, version 2.6.34, a log file 1.2GB in size was generated.
|
Linux kernel, version 2.6.34, a log file 1.2GB in size was generated.
|
@end quotation
|
@end quotation
|
|
|
@item exe_bin_insn_log_file = @var{filename}
|
@item exe_bin_insn_log_file = @var{filename}
|
@cindex @code{exe_bin_insn_log_file} (simulator configuration)
|
@cindex @code{exe_bin_insn_log_file} (simulator configuration)
|
Filename for the binary execution log filename if @code{exe_bin_insn_log} is
|
Filename for the binary execution log filename if @code{exe_bin_insn_log} is
|
enabled. Default @file{exe-insn.bin}.
|
enabled. Default @file{exe-insn.bin}.
|
|
|
|
|
@item clkcycle = @var{value}[ps|ns|us|ms]
|
@item clkcycle = @var{value}[ps|ns|us|ms]
|
@cindex @code{clkcycle} (simulator configuration)
|
@cindex @code{clkcycle} (simulator configuration)
|
Specify the time taken by one clock cycle. If no units are specified,
|
Specify the time taken by one clock cycle. If no units are specified,
|
@code{ps} is assumed. Default 4000ps (250MHz).
|
@code{ps} is assumed. Default 4000ps (250MHz).
|
|
|
@end table
|
@end table
|
|
|
@node Verification API Configuration
|
@node Verification API Configuration
|
@subsection Verification API (VAPI) Configuration
|
@subsection Verification API (VAPI) Configuration
|
@cindex configuring the Verification API (VAPI)
|
@cindex configuring the Verification API (VAPI)
|
@cindex Verification API configuration
|
@cindex Verification API configuration
|
@cindex VAPI configuration
|
@cindex VAPI configuration
|
@cindex @code{section vapi}
|
@cindex @code{section vapi}
|
The Verification API (VAPI) provides a TCP/IP interface to allow
|
The Verification API (VAPI) provides a TCP/IP interface to allow
|
components of the simulation to be controlled
|
components of the simulation to be controlled
|
externally. @xref{Verification API, , Verification API}, for more
|
externally. @xref{Verification API, , Verification API}, for more
|
details.
|
details.
|
|
|
Verification API configuration is described in @code{section
|
Verification API configuration is described in @code{section
|
vapi}. This section may appear at most once. The following parameters
|
vapi}. This section may appear at most once. The following parameters
|
may be specified.
|
may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (verification API configuration)
|
@cindex @code{enabled} (verification API configuration)
|
If 1 (true), verification API is enabled and its server started. If 0
|
If 1 (true), verification API is enabled and its server started. If 0
|
(the default), it is disabled.
|
(the default), it is disabled.
|
|
|
@item server_port = @var{value}
|
@item server_port = @var{value}
|
@cindex @code{server_port} (verification API configuration)
|
@cindex @code{server_port} (verification API configuration)
|
When VAPI is enabled, communication will be via TCP/IP on the port
|
When VAPI is enabled, communication will be via TCP/IP on the port
|
specified by @var{value}. The value must lie in the range 1 to 65535.
|
specified by @var{value}. The value must lie in the range 1 to 65535.
|
The default value is 50000.
|
The default value is 50000.
|
|
|
@quotation Tip
|
@quotation Tip
|
@cindex TCP/IP port range
|
@cindex TCP/IP port range
|
@cindex port range for TCP/IP
|
@cindex port range for TCP/IP
|
@cindex dynamic ports, use of
|
@cindex dynamic ports, use of
|
@cindex private ports, use of
|
@cindex private ports, use of
|
There is no registered port for @value{OR1KSIM} VAPI. Good practice
|
There is no registered port for @value{OR1KSIM} VAPI. Good practice
|
suggests users should adopt port values in the @dfn{Dynamic} or
|
suggests users should adopt port values in the @dfn{Dynamic} or
|
@dfn{Private} port range, i.e. 49152-65535.
|
@dfn{Private} port range, i.e. 49152-65535.
|
@end quotation
|
@end quotation
|
|
|
@item log_enabled = 0|1
|
@item log_enabled = 0|1
|
@cindex @code{log_enabled} (verification API configuration)
|
@cindex @code{log_enabled} (verification API configuration)
|
If 1 (true), all VAPI requests and sent commands will be logged. If 0
|
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
|
(the default), logging is diabled. Logs are written to the file
|
specified by the @code{vapi_log_file} field (see below).
|
specified by the @code{vapi_log_file} field (see below).
|
|
|
@quotation Caution
|
@quotation Caution
|
This can generate a substantial amount of file I/O and seriously
|
This can generate a substantial amount of file I/O and seriously
|
degrade simulator performance.
|
degrade simulator performance.
|
@end quotation
|
@end quotation
|
|
|
@item hide_device_id = 0|1
|
@item hide_device_id = 0|1
|
@cindex @code{hide_device_id} (verification API configuration)
|
@cindex @code{hide_device_id} (verification API configuration)
|
If 1 (true) don't log the device ID. If 0 (the default), log the
|
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
|
device ID. This feature (when set to 1) is provided for backwards
|
compatibility with an old version of VAPI.
|
compatibility with an old version of VAPI.
|
|
|
@item vapi_log_file = "@var{filename}"
|
@item vapi_log_file = "@var{filename}"
|
@cindex @code{vapi_log_file} (verification API configuration)
|
@cindex @code{vapi_log_file} (verification API configuration)
|
@cindex @code{vapi_log_fn} (verification API configuration - deprecated)
|
@cindex @code{vapi_log_fn} (verification API configuration - deprecated)
|
Use @file{filename} as the file for logged data is logging is enabled
|
Use @file{filename} as the file for logged data is logging is enabled
|
(see @code{log_enabled} above). The default is @code{"vapi.log"}. For
|
(see @code{log_enabled} above). The default is @code{"vapi.log"}. For
|
backwards compatibility, the alternative name @code{vapi_log_fn} is
|
backwards compatibility, the alternative name @code{vapi_log_fn} is
|
supported for this parameter, but deprecated.
|
supported for this parameter, but deprecated.
|
|
|
@end table
|
@end table
|
|
|
@node CUC Configuration
|
@node CUC Configuration
|
@subsection Custom Unit Compiler (CUC) Configuration
|
@subsection Custom Unit Compiler (CUC) Configuration
|
@cindex configuring the Custom Unit Compiler (CUC)
|
@cindex configuring the Custom Unit Compiler (CUC)
|
@cindex Custom Unit Compiler Configuration
|
@cindex Custom Unit Compiler Configuration
|
@cindex CUC configuration
|
@cindex CUC configuration
|
@cindex @code{section cuc}
|
@cindex @code{section cuc}
|
The Custom Unit Compiler (CUC) was a project by Marko Mlinar to generate
|
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
|
Verilog from ANSI C functions. The project seems to not have progressed
|
beyond the initial prototype phase. The configuration parameters are
|
beyond the initial prototype phase. The configuration parameters are
|
described here for the record.
|
described here for the record.
|
|
|
CUC configuration is described in @code{@w{section cuc}}. This section
|
CUC configuration is described in @code{@w{section cuc}}. This section
|
may appear at most once. The following parameters may be specified.
|
may appear at most once. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item memory_order = none|weak|strong|exact
|
@item memory_order = none|weak|strong|exact
|
@cindex @code{memory_order} (CUC configuration)
|
@cindex @code{memory_order} (CUC configuration)
|
This parameter specifies the memory ordering required:
|
This parameter specifies the memory ordering required:
|
|
|
@table @code
|
@table @code
|
|
|
@item memory_order=none
|
@item memory_order=none
|
@cindex @code{memory_order=none} (CUC configuration)
|
@cindex @code{memory_order=none} (CUC configuration)
|
Different memory ordering, even if there are dependencies. Bursts can
|
Different memory ordering, even if there are dependencies. Bursts can
|
be made, width can change.
|
be made, width can change.
|
|
|
@item memory_order=weak
|
@item memory_order=weak
|
@cindex @code{memory_order=weak} (CUC configuration)
|
@cindex @code{memory_order=weak} (CUC configuration)
|
Different memory ordering, even if there are dependencies. If
|
Different memory ordering, even if there are dependencies. If
|
dependencies cannot occur, then bursts can be made, width can change.
|
dependencies cannot occur, then bursts can be made, width can change.
|
|
|
@item memory_order=strong
|
@item memory_order=strong
|
@cindex @code{memory_order=strong} (CUC configuration)
|
@cindex @code{memory_order=strong} (CUC configuration)
|
Same memory ordering. Bursts can be made, width can change.
|
Same memory ordering. Bursts can be made, width can change.
|
|
|
@item memory_order=exact
|
@item memory_order=exact
|
@cindex @code{memory_order=exact} (CUC configuration)
|
@cindex @code{memory_order=exact} (CUC configuration)
|
Exactly the same memory ordering and widths.
|
Exactly the same memory ordering and widths.
|
|
|
@end table
|
@end table
|
|
|
The default value is @code{memory_order=exact}. Invalid memory
|
The default value is @code{memory_order=exact}. Invalid memory
|
orderings are ignored with a warning.
|
orderings are ignored with a warning.
|
|
|
@item calling_convention = 0|1
|
@item calling_convention = 0|1
|
@cindex @code{calling_convention} (CUC configuration)
|
@cindex @code{calling_convention} (CUC configuration)
|
If 1 (true), programs follow OpenRISC calling conventions. If 0 (the
|
If 1 (true), programs follow OpenRISC calling conventions. If 0 (the
|
default), they may use other convenitions.
|
default), they may use other convenitions.
|
|
|
@item enable_bursts = 0 | 1
|
@item enable_bursts = 0 | 1
|
@cindex @code{enable_bursts} (CUC configuration)
|
@cindex @code{enable_bursts} (CUC configuration)
|
If 1 (true), bursts are detected. If 0 (the default), bursts are not
|
If 1 (true), bursts are detected. If 0 (the default), bursts are not
|
detected.
|
detected.
|
|
|
@item no_multicycle = 0 | 1
|
@item no_multicycle = 0 | 1
|
@cindex @code{no_multicycle} (CUC configuration)
|
@cindex @code{no_multicycle} (CUC configuration)
|
If 1 (true), no multicycle logic paths will be generated. If 0 (the
|
If 1 (true), no multicycle logic paths will be generated. If 0 (the
|
default), multicycle logic paths will be generated.
|
default), multicycle logic paths will be generated.
|
|
|
@item timings_file = "@var{filename}"
|
@item timings_file = "@var{filename}"
|
@cindex @code{timings_file} (CUC configuration)
|
@cindex @code{timings_file} (CUC configuration)
|
@cindex @code{timings_fn} (CUC configuration - deprecated)
|
@cindex @code{timings_fn} (CUC configuration - deprecated)
|
@var{filename} specifies a file containing timing information. The
|
@var{filename} specifies a file containing timing information. The
|
default value is @code{"virtex.tim"}. For backwards compatibility, the
|
default value is @code{"virtex.tim"}. For backwards compatibility, the
|
alternative name @code{timings_fn} is supported for this parameter,
|
alternative name @code{timings_fn} is supported for this parameter,
|
but deprecated.
|
but deprecated.
|
|
|
@end table
|
@end table
|
|
|
@node Core OpenRISC Configuration
|
@node Core OpenRISC Configuration
|
@section Configuring the OpenRISC Architectural Components
|
@section Configuring the OpenRISC Architectural Components
|
|
|
@menu
|
@menu
|
* CPU Configuration::
|
* CPU Configuration::
|
* Memory Configuration::
|
* Memory Configuration::
|
* Memory Management Configuration::
|
* Memory Management Configuration::
|
* Cache Configuration::
|
* Cache Configuration::
|
* Interrupt Configuration::
|
* Interrupt Configuration::
|
* Power Management Configuration::
|
* Power Management Configuration::
|
* Branch Prediction Configuration::
|
* Branch Prediction Configuration::
|
* Debug Interface Configuration::
|
* Debug Interface Configuration::
|
@end menu
|
@end menu
|
|
|
@node CPU Configuration
|
@node CPU Configuration
|
@subsection CPU Configuration
|
@subsection CPU Configuration
|
@cindex configuring the CPU
|
@cindex configuring the CPU
|
@cindex configuring the processor
|
@cindex configuring the processor
|
@cindex CPU configuration
|
@cindex CPU configuration
|
@cindex processor configuration
|
@cindex processor configuration
|
@cindex @code{section cpu}
|
@cindex @code{section cpu}
|
CPU configuration is described in @code{section cpu}. This section
|
CPU configuration is described in @code{section cpu}. This section
|
should appear only once. At present @value{OR1KSIM} does not model multi-CPU
|
should appear only once. At present @value{OR1KSIM} does not model multi-CPU
|
systems. The following parameters may be specified.
|
systems. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item ver = @var{value}
|
@item ver = @var{value}
|
@item cfg = @var{value}
|
@item cfg = @var{value}
|
@item rev = @var{value}
|
@item rev = @var{value}
|
@cindex @code{ver} (CPU configuration)
|
@cindex @code{ver} (CPU configuration)
|
@cindex @code{rev} (CPU configuration)
|
@cindex @code{rev} (CPU configuration)
|
The values are used to form the corresponding fields in the @code{VR}
|
The values are used to form the corresponding fields in the @code{VR}
|
Special Purpose Register (SPR 0). Default values 0. A warning is given
|
Special Purpose Register (SPR 0). Default values 0. A warning is given
|
and the value truncated if it is too large (8 bits for @code{ver} and
|
and the value truncated if it is too large (8 bits for @code{ver} and
|
@code{cfg}, 6 bits for @code{rev}).
|
@code{cfg}, 6 bits for @code{rev}).
|
|
|
@item upr = @var{value}
|
@item upr = @var{value}
|
@cindex @code{upr} (CPU configuration)
|
@cindex @code{upr} (CPU configuration)
|
Used as the value of the Unit Present Register (UPR) Special Purpose Register
|
Used as the value of the Unit Present Register (UPR) Special Purpose Register
|
(SPR 1) to @var{value}. Default value is 0x0000075f, i.e.
|
(SPR 1) to @var{value}. Default value is 0x0000075f, i.e.
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
UPR present (0x00000001)
|
UPR present (0x00000001)
|
@item
|
@item
|
Data cache present (0x00000002)
|
Data cache present (0x00000002)
|
@item
|
@item
|
Instruction cache present (0x00000004)
|
Instruction cache present (0x00000004)
|
@item
|
@item
|
Data MMY present (0x00000008)
|
Data MMY present (0x00000008)
|
@item
|
@item
|
Instruction MMU present (0x00000010)
|
Instruction MMU present (0x00000010)
|
@item
|
@item
|
Debug unit present (0x00000040)
|
Debug unit present (0x00000040)
|
@item
|
@item
|
Power management unit present (0x00000100)
|
Power management unit present (0x00000100)
|
@item
|
@item
|
Programmable interrupt controller present (0x00000200)
|
Programmable interrupt controller present (0x00000200)
|
@item
|
@item
|
Tick timer present (0x00000400)
|
Tick timer present (0x00000400)
|
@end itemize
|
@end itemize
|
|
|
However, with the exection of the UPR present (0x00000001) and tick
|
However, with the exection of the UPR present (0x00000001) and tick
|
timer present, the various
|
timer present, the various
|
fields will be modified with the values specified in their corresponding
|
fields will be modified with the values specified in their corresponding
|
configuration sections.
|
configuration sections.
|
|
|
@item cfgr = @var{value}
|
@item cfgr = @var{value}
|
@cindex @code{cfgr} (CPU configuration)
|
@cindex @code{cfgr} (CPU configuration)
|
Sets the CPU configuration register (Special Purpose Register 2) to
|
Sets the CPU configuration register (Special Purpose Register 2) to
|
@var{value}. Default value is 0x00000020, i.e. support for the ORBIS32
|
@var{value}. Default value is 0x00000020, i.e. support for the ORBIS32
|
instruction set. Attempts to set any other value are accepted, but
|
instruction set. Attempts to set any other value are accepted, but
|
issue a warning that there is no support for the instruction set.
|
issue a warning that there is no support for the instruction set.
|
|
|
@item sr = @var{value}
|
@item sr = @var{value}
|
@cindex @code{sr} (CPU configuration)
|
@cindex @code{sr} (CPU configuration)
|
Sets the supervision register Special Purpose Register (SPR 0x11) to
|
Sets the supervision register Special Purpose Register (SPR 0x11) to
|
@var{value}. Default value is 0x00008001, i.e. start in supervision
|
@var{value}. Default value is 0x00008001, i.e. start in supervision
|
mode (0x00000001) and set the ``Fixed One'' bit (0x00008000).
|
mode (0x00000001) and set the ``Fixed One'' bit (0x00008000).
|
|
|
@quotation Note
|
@quotation Note
|
This is particularly useful when an image is held in Flash at high
|
This is particularly useful when an image is held in Flash at high
|
memory (0xf0000000). The EPH bit can be set, so that interrupt
|
memory (0xf0000000). The EPH bit can be set, so that interrupt
|
vectors are basedf at 0xf0000000, rather than 0x0.
|
vectors are basedf at 0xf0000000, rather than 0x0.
|
@end quotation
|
@end quotation
|
|
|
@item superscalar = 0|1
|
@item superscalar = 0|1
|
@cindex @code{superscalar} (CPU configuration)
|
@cindex @code{superscalar} (CPU configuration)
|
If 1, the processor operates in superscalar mode. Default value is
|
If 1, the processor operates in superscalar mode. Default value is
|
0.
|
0.
|
|
|
In the current simulator, the only functional effect of superscalar
|
In the current simulator, the only functional effect of superscalar
|
mode is to affect the calculation of the number of cycles taken to
|
mode is to affect the calculation of the number of cycles taken to
|
execute an instruction.
|
execute an instruction.
|
|
|
@quotation Caution
|
@quotation Caution
|
The code for this does not appear to be complete or well tested, so
|
The code for this does not appear to be complete or well tested, so
|
users are advised not to use this option.
|
users are advised not to use this option.
|
@end quotation
|
@end quotation
|
|
|
@item hazards = 0|1
|
@item hazards = 0|1
|
@cindex @code{hazards} (CPU configuration)
|
@cindex @code{hazards} (CPU configuration)
|
If 1, data hazards are tracked in a superscalar CPU. Default value is
|
If 1, data hazards are tracked in a superscalar CPU. Default value is
|
0.
|
0.
|
|
|
In the current simulator, the only functional effect is to cause
|
In the current simulator, the only functional effect is to cause
|
logging of hazard waiting information if the CPU is
|
logging of hazard waiting information if the CPU is
|
superscalar. However nowhere in the simulator is this data actually
|
superscalar. However nowhere in the simulator is this data actually
|
computed, so the net result is probably to have no effect.
|
computed, so the net result is probably to have no effect.
|
|
|
if harzards are tracked, current hazards can be displayed using the
|
if harzards are tracked, current hazards can be displayed using the
|
simulator's @command{r} command.
|
simulator's @command{r} command.
|
|
|
@quotation Caution
|
@quotation Caution
|
The code for this does not appear to be complete or well tested, so
|
The code for this does not appear to be complete or well tested, so
|
users are advised not to use this option.
|
users are advised not to use this option.
|
@end quotation
|
@end quotation
|
|
|
@item dependstats = 0|1
|
@item dependstats = 0|1
|
@cindex @code{dependstats} (CPU configuration)
|
@cindex @code{dependstats} (CPU configuration)
|
If 1, inter-instruction dependencies are calculated. Default value 0.
|
If 1, inter-instruction dependencies are calculated. Default value 0.
|
|
|
If these values are calculated, the depencies can be displayed using
|
If these values are calculated, the depencies can be displayed using
|
the simulator's @command{stat} command.
|
the simulator's @command{stat} command.
|
|
|
@quotation Note
|
@quotation Note
|
This field must be enabled, if execution execution flow tracking
|
This field must be enabled, if execution execution flow tracking
|
(field @code{history}) has been requested in the simulator
|
(field @code{history}) has been requested in the simulator
|
configuration section (@pxref{Simulator Behavior, , Simulator
|
configuration section (@pxref{Simulator Behavior, , Simulator
|
Behavior}).
|
Behavior}).
|
@end quotation
|
@end quotation
|
|
|
@item sbuf_len = @var{value}
|
@item sbuf_len = @var{value}
|
@cindex @code{sbuf_len} (CPU configuration)
|
@cindex @code{sbuf_len} (CPU configuration)
|
The length of the store buffer is set to @var{value}, which must be no
|
The length of the store buffer is set to @var{value}, which must be no
|
greater than 256. Larger values will be truncated to 256 with a
|
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
|
warning. Negative values will be treated as 0 with a warning. Use 0 to
|
disable the store buffer.
|
disable the store buffer.
|
|
|
When the store buffer is active, stores are accumulated and committed
|
When the store buffer is active, stores are accumulated and committed
|
when I/O is idle.
|
when I/O is idle.
|
|
|
@item hardfloat = 0|1
|
@item hardfloat = 0|1
|
@cindex @code{hardfloat} (CPU configuration)
|
@cindex @code{hardfloat} (CPU configuration)
|
If 1, hardfloat instructions are enabled. Default value 0.
|
If 1, hardfloat instructions are enabled. Default value 0.
|
|
|
@end table
|
@end table
|
|
|
@node Memory Configuration
|
@node Memory Configuration
|
@subsection Memory Configuration
|
@subsection Memory Configuration
|
@cindex configuring memory
|
@cindex configuring memory
|
@cindex memory configuration
|
@cindex memory configuration
|
@cindex @code{section memory}
|
@cindex @code{section memory}
|
Memory configuration is described in @code{section memory}. This
|
Memory configuration is described in @code{section memory}. This
|
section may appear multiple times, specifying multiple blocks of
|
section may appear multiple times, specifying multiple blocks of
|
memory.
|
memory.
|
|
|
@quotation Caution
|
@quotation Caution
|
The user may choose whether or not to enable a memory controller. If a
|
The user may choose whether or not to enable a memory controller. If a
|
memory controller is enabled, then appropriate initalization code must
|
memory controller is enabled, then appropriate initalization code must
|
be provided. The section describing memory controller configuration
|
be provided. The section describing memory controller configuration
|
describes the steps necessary for using smaller or larger memory
|
describes the steps necessary for using smaller or larger memory
|
sections (@pxref{Memory Controller Configuration, , Memory Controller
|
sections (@pxref{Memory Controller Configuration, , Memory Controller
|
Configuration}).
|
Configuration}).
|
|
|
The @dfn{uClibc} startup code initalizes a memory controller, assumed to
|
The @dfn{uClibc} startup code initalizes a memory controller, assumed to
|
be mapped at 0x93000000. If a memory controller is @emph{not} enabled,
|
be mapped at 0x93000000. If a memory controller is @emph{not} enabled,
|
then the standard C library code will generate memory access errors.
|
then the standard C library code will generate memory access errors.
|
The solution is to declare an additional writable memory block, mimicing
|
The solution is to declare an additional writable memory block, mimicing
|
the memory controller's register bank as follows.
|
the memory controller's register bank as follows.
|
|
|
@example
|
@example
|
section memory
|
section memory
|
pattern = 0x00
|
pattern = 0x00
|
type = unknown
|
type = unknown
|
name = "MC shadow"
|
name = "MC shadow"
|
baseaddr = 0x93000000
|
baseaddr = 0x93000000
|
size = 0x00000080
|
size = 0x00000080
|
delayr = 2
|
delayr = 2
|
delayw = 4
|
delayw = 4
|
end
|
end
|
@end example
|
@end example
|
|
|
@end quotation
|
@end quotation
|
|
|
|
|
The following parameters may be specified.
|
The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item type=random|pattern|unknown|zero|exitnops
|
@item type=random|pattern|unknown|zero|exitnops
|
@cindex @code{type} (memory configuration)
|
@cindex @code{type} (memory configuration)
|
Specifies the values to which memory should be initialized. The
|
Specifies the values to which memory should be initialized. The
|
default value is @code{unknown}.
|
default value is @code{unknown}.
|
|
|
@table @code
|
@table @code
|
|
|
@item random
|
@item random
|
@cindex @code{type=random} (memory configuration)
|
@cindex @code{type=random} (memory configuration)
|
Set the memory values to be a random value. A seed for the random
|
Set the memory values to be a random value. A seed for the random
|
generator may be set using the @code{random_seed} field in this
|
generator may be set using the @code{random_seed} field in this
|
section (see below), thus ensuring the same ``random'' values are used
|
section (see below), thus ensuring the same ``random'' values are used
|
each time.
|
each time.
|
|
|
@item pattern
|
@item pattern
|
@cindex @code{type=pattern} (memory configuration)
|
@cindex @code{type=pattern} (memory configuration)
|
Set the memory values to be a pattern value, which is set using the
|
Set the memory values to be a pattern value, which is set using the
|
@code{pattern} field in this section (see below).
|
@code{pattern} field in this section (see below).
|
|
|
@item unknown
|
@item unknown
|
@cindex @code{type=unknown} (memory configuration)
|
@cindex @code{type=unknown} (memory configuration)
|
The memory values are not initialized (i.e. left ``unknown''). This
|
The memory values are not initialized (i.e. left ``unknown''). This
|
option will yield faster initialization of the simulator. This is the
|
option will yield faster initialization of the simulator. This is the
|
default.
|
default.
|
|
|
@item zero
|
@item zero
|
@cindex @code{type=zero} (memory configuration)
|
@cindex @code{type=zero} (memory configuration)
|
Set the memory values to be 0. This is the equivalent of
|
Set the memory values to be 0. This is the equivalent of
|
@code{type=pattern} and a @code{pattern} value of 0, and implemented
|
@code{type=pattern} and a @code{pattern} value of 0, and implemented
|
as such.
|
as such.
|
|
|
@quotation Note
|
@quotation Note
|
As a consequence, if the @code{pattern} field is @emph{subsequently}
|
As a consequence, if the @code{pattern} field is @emph{subsequently}
|
specified in this section, the value in that field will be used
|
specified in this section, the value in that field will be used
|
instead of zero to initialize the memory.
|
instead of zero to initialize the memory.
|
@end quotation
|
@end quotation
|
|
|
@item exitnops
|
@item exitnops
|
@cindex @code{type=exitnops} (memory configuration)
|
@cindex @code{type=exitnops} (memory configuration)
|
Set the memory values to be an instruction used to signal end of
|
Set the memory values to be an instruction used to signal end of
|
simulation. This is useful for causing immediate end of simulation
|
simulation. This is useful for causing immediate end of simulation
|
when PC corruption occurs.
|
when PC corruption occurs.
|
|
|
@end table
|
@end table
|
|
|
@item random_seed = @var{value}
|
@item random_seed = @var{value}
|
@cindex @code{random_seed} (memory configuration)
|
@cindex @code{random_seed} (memory configuration)
|
Set the seed for the random number generator to @var{value}. This only
|
Set the seed for the random number generator to @var{value}. This only
|
has any effect for memory type @code{random}.
|
has any effect for memory type @code{random}.
|
|
|
The default value is -1,
|
The default value is -1,
|
which means the seed will be set from a call to the @code{time}
|
which means the seed will be set from a call to the @code{time}
|
function, thus ensuring different random values are used on each
|
function, thus ensuring different random values are used on each
|
run. The simulator prints out the seed used in this case, allowing
|
run. The simulator prints out the seed used in this case, allowing
|
repeat runs to regenerate the same random values used in any
|
repeat runs to regenerate the same random values used in any
|
particular run.
|
particular run.
|
|
|
@item pattern = @var{value}
|
@item pattern = @var{value}
|
@cindex @code{pattern} (memory configuration)
|
@cindex @code{pattern} (memory configuration)
|
Set the pattern to be used when initializing memory to
|
Set the pattern to be used when initializing memory to
|
@var{value}. The default value is 0. This only has any effect for
|
@var{value}. The default value is 0. This only has any effect for
|
memory type @code{pattern}. The least significant 8 bits of this value
|
memory type @code{pattern}. The least significant 8 bits of this value
|
is used to initialize each byte. More than 8 bits can be specified,
|
is used to initialize each byte. More than 8 bits can be specified,
|
but will ignored with a warning.
|
but will ignored with a warning.
|
|
|
@quotation Tip
|
@quotation Tip
|
The default value, is equivalent to setting the memory @code{type} to
|
The default value, is equivalent to setting the memory @code{type} to
|
be @code{zero}. If that is what is intended, then using
|
be @code{zero}. If that is what is intended, then using
|
@code{type=zero} explicitly is better than using @code{type=pattern}
|
@code{type=zero} explicitly is better than using @code{type=pattern}
|
and not specifying a value for @code{pattern}.
|
and not specifying a value for @code{pattern}.
|
@end quotation
|
@end quotation
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (memory configuration)
|
@cindex @code{baseaddr} (memory configuration)
|
Set the base address of the memory to @var{value}. It should be
|
Set the base address of the memory to @var{value}. It should be
|
aligned to a multiple of the memory size rounded up to the nearest
|
aligned to a multiple of the memory size rounded up to the nearest
|
@math{2^n}. The default value is 0.
|
@math{2^n}. The default value is 0.
|
|
|
@item size = @var{value}
|
@item size = @var{value}
|
@cindex @code{size} (memory configuration)
|
@cindex @code{size} (memory configuration)
|
Set the size of the memory block to be @var{value} bytes. This should be a
|
Set the size of the memory block to be @var{value} bytes. This should be a
|
multiple of 4 (i.e. word aligned). The default value is 1024.
|
multiple of 4 (i.e. word aligned). The default value is 1024.
|
|
|
@quotation Note
|
@quotation Note
|
When allocating memory, the simulator will allocate the nearest
|
When allocating memory, the simulator will allocate the nearest
|
@math{2^n} bytes greater than or equal to @var{value}, and will not
|
@math{2^n} bytes greater than or equal to @var{value}, and will not
|
notice memory misses in any part of the memory between @var{value} and
|
notice memory misses in any part of the memory between @var{value} and
|
the amount allocated.
|
the amount allocated.
|
|
|
As a consequence users are strongly recommended to specify memory
|
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
|
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
|
required, it should be specified as separate, contiguous blocks, each
|
of which is a power of 2 in size.
|
of which is a power of 2 in size.
|
@end quotation
|
@end quotation
|
|
|
@item name = "@var{text}"
|
@item name = "@var{text}"
|
@cindex @code{name} (memory configuration)
|
@cindex @code{name} (memory configuration)
|
Name the block. Typically these describe the type of memory being
|
Name the block. Typically these describe the type of memory being
|
modeled (thus @code{"SRAM"} or @code{"Flash"}. The default is
|
modeled (thus @code{"SRAM"} or @code{"Flash"}. The default is
|
@code{@w{"anonymous memory block"}}.
|
@code{@w{"anonymous memory block"}}.
|
|
|
@quotation Note
|
@quotation Note
|
It is not clear that this information is currently ever used in normal
|
It is not clear that this information is currently ever used in normal
|
operation of the simulator. Even the @command{info} command of the simulator
|
operation of the simulator. Even the @command{info} command of the simulator
|
ignores it.
|
ignores it.
|
@end quotation
|
@end quotation
|
|
|
@item ce = @var{value}
|
@item ce = @var{value}
|
@cindex @code{ce} (memory configuration)
|
@cindex @code{ce} (memory configuration)
|
Set the chip enable index of the memory instance. Each memory instance
|
Set the chip enable index of the memory instance. Each memory instance
|
should have a unique chip enable index, which should be greater
|
should have a unique chip enable index, which should be greater
|
than or equal to zero. This is used by the memory controller when
|
than or equal to zero. This is used by the memory controller when
|
identifying different memory instances.
|
identifying different memory instances.
|
|
|
There is no requirement to set @code{ce} if a memory controller is not
|
There is no requirement to set @code{ce} if a memory controller is not
|
enabled. The default value is -1 (invalid).
|
enabled. The default value is -1 (invalid).
|
|
|
@item mc = @var{value}
|
@item mc = @var{value}
|
@cindex @code{mc} (memory configuration)
|
@cindex @code{mc} (memory configuration)
|
Specifies the memory controller this memory is connected to. It should
|
Specifies the memory controller this memory is connected to. It should
|
correspond to the @code{index} field specified in a @code{@w{section
|
correspond to the @code{index} field specified in a @code{@w{section
|
mc}} for a memory controller (@pxref{Memory Controller Configuration,
|
mc}} for a memory controller (@pxref{Memory Controller Configuration,
|
, Memory Controller Configuration}).
|
, Memory Controller Configuration}).
|
|
|
There is no requirement to set @code{mc} if a memory controller is not
|
There is no requirement to set @code{mc} if a memory controller is not
|
enabled. Default value is 0, which is also the default value of a
|
enabled. Default value is 0, which is also the default value of a
|
memory controller @code{index} field. This is suitable therefore for
|
memory controller @code{index} field. This is suitable therefore for
|
designs with just one memory controller.
|
designs with just one memory controller.
|
|
|
@item delayr = @var{value}
|
@item delayr = @var{value}
|
@cindex @code{delayr} (memory configuration)
|
@cindex @code{delayr} (memory configuration)
|
The number of cycles required for a read access. Set to -1 if the
|
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
|
memory does not support reading. Default value 1. The simulator will
|
add this number of cycles to the total instruction cycle count when
|
add this number of cycles to the total instruction cycle count when
|
reading from main memory.
|
reading from main memory.
|
|
|
@item delayw = @var{value}
|
@item delayw = @var{value}
|
@cindex @code{delayw} (memory configuration)
|
@cindex @code{delayw} (memory configuration)
|
The number of cycles required for a write access. Set to -1 if the
|
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
|
memory does not support writing. Default value 1. The simulator will
|
add this number of cycles to the total instruction cycle count when
|
add this number of cycles to the total instruction cycle count when
|
writing to main memory.
|
writing to main memory.
|
|
|
@item log = "@var{file}"
|
@item log = "@var{file}"
|
@cindex @code{log} (memory configuration)
|
@cindex @code{log} (memory configuration)
|
If specified, @file{file} names a file for all memory accesses to be
|
If specified, @file{file} names a file for all memory accesses to be
|
logged. If not specified, the default value, NULL is used, meaning
|
logged. If not specified, the default value, NULL is used, meaning
|
that the memory is not logged.
|
that the memory is not logged.
|
|
|
@end table
|
@end table
|
|
|
@node Memory Management Configuration
|
@node Memory Management Configuration
|
@subsection Memory Management Configuration
|
@subsection Memory Management Configuration
|
@cindex configuring data & instruction MMUs
|
@cindex configuring data & instruction MMUs
|
@cindex MMU configuration
|
@cindex MMU configuration
|
@cindex DMMU configuration
|
@cindex DMMU configuration
|
@cindex data MMU configuration
|
@cindex data MMU configuration
|
@cindex IMMU configuration
|
@cindex IMMU configuration
|
@cindex instruction MMU configuration
|
@cindex instruction MMU configuration
|
@cindex @code{section dmmu}
|
@cindex @code{section dmmu}
|
@cindex @code{section immu}
|
@cindex @code{section immu}
|
Memory Management Unit (MMU) configuration is described in
|
Memory Management Unit (MMU) configuration is described in
|
@code{section dmmu} (for the data MMU) and @code{section immu} (for
|
@code{section dmmu} (for the data MMU) and @code{section immu} (for
|
the instruction MMU). Each section should appear at most once. The
|
the instruction MMU). Each section should appear at most once. The
|
following parameters may be specified.
|
following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (MMU configuration)
|
@cindex @code{enabled} (MMU configuration)
|
If 1 (true), the data or instruction (as appropriate) MMU is
|
If 1 (true), the data or instruction (as appropriate) MMU is
|
enabled. If 0 (the default), it is disabled.
|
enabled. If 0 (the default), it is disabled.
|
|
|
@item nsets = @var{value}
|
@item nsets = @var{value}
|
@cindex @code{nsets} (MMU configuration)
|
@cindex @code{nsets} (MMU configuration)
|
Sets the number of data or instruction (as appropriate) TLB sets to
|
Sets the number of data or instruction (as appropriate) TLB sets to
|
@var{value}, which must be a power of two, not exceeding 128. Values
|
@var{value}, which must be a power of two, not exceeding 128. Values
|
which do not fit these criteria are ignored with a warning. The
|
which do not fit these criteria are ignored with a warning. The
|
default value is 1.
|
default value is 1.
|
|
|
@item nways = @var{value}
|
@item nways = @var{value}
|
@cindex @code{nways} (MMU configuration)
|
@cindex @code{nways} (MMU configuration)
|
Sets the number of data or instruction (as appropriate) TLB ways to
|
Sets the number of data or instruction (as appropriate) TLB ways to
|
@var{value}. The value must be in the range 1 to 4. Values outside
|
@var{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.
|
this range are ignored with a warning. The default value is 1.
|
|
|
@item pagesize = @var{value}
|
@item pagesize = @var{value}
|
@cindex @code{pagesize} (MMU configuration)
|
@cindex @code{pagesize} (MMU configuration)
|
The data or instruction (as appropriate) MMU page size is set to
|
The data or instruction (as appropriate) MMU page size is set to
|
@var{value}, which must be a power of 2. Values which are not a power
|
@var{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).
|
of 2 are ignored with a warning. The default is 8192 (0x2000).
|
|
|
@item entrysize = @var{value}
|
@item entrysize = @var{value}
|
@cindex @code{entrysize} (MMU configuration)
|
@cindex @code{entrysize} (MMU configuration)
|
The data or instruction (as appropriate) MMU entry size is set to
|
The data or instruction (as appropriate) MMU entry size is set to
|
@var{value}, which must be a power of 2. Values which are not a power
|
@var{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.
|
of 2 are ignored with a warning. The default value is 1.
|
|
|
@quotation Note
|
@quotation Note
|
@value{OR1KSIM} does not appear to use the @code{entrysize} parameter
|
@value{OR1KSIM} does not appear to use the @code{entrysize} parameter
|
in its simulation of the MMUs. Thus setting this value does not seem
|
in its simulation of the MMUs. Thus setting this value does not seem
|
to matter.
|
to matter.
|
@end quotation
|
@end quotation
|
|
|
@item ustates = @var{value}
|
@item ustates = @var{value}
|
@cindex @code{ustates} (MMU configuration)
|
@cindex @code{ustates} (MMU configuration)
|
The number of instruction usage states for the data or instruction (as
|
The number of instruction usage states for the data or instruction (as
|
appropriate) MMU is set to @var{value}, which must be 2, 3 or
|
appropriate) MMU is set to @var{value}, which must be 2, 3 or
|
4. Values outside this range are ignored with a warning. The default
|
4. Values outside this range are ignored with a warning. The default
|
value is 2.
|
value is 2.
|
|
|
@quotation Note
|
@quotation Note
|
@value{OR1KSIM} does not appear to use the @code{ustates} parameter in
|
@value{OR1KSIM} does not appear to use the @code{ustates} parameter in
|
its simulation of the MMUs. Thus setting this value does not seem to
|
its simulation of the MMUs. Thus setting this value does not seem to
|
matter.
|
matter.
|
@end quotation
|
@end quotation
|
|
|
@item hitdelay = @var{value}
|
@item hitdelay = @var{value}
|
@cindex @code{hitdelay} (MMU configuration)
|
@cindex @code{hitdelay} (MMU configuration)
|
Set the number of cycles a data or instruction (as appropriate) MMU
|
Set the number of cycles a data or instruction (as appropriate) MMU
|
hit costs. Default value 1.
|
hit costs. Default value 1.
|
|
|
@item missdelay = @var{value}
|
@item missdelay = @var{value}
|
@cindex @code{missdelay} (MMU configuration)
|
@cindex @code{missdelay} (MMU configuration)
|
Set the number of cycles a data or instruction (as appropriate) MMU
|
Set the number of cycles a data or instruction (as appropriate) MMU
|
miss costs. Default value 1.
|
miss costs. Default value 1.
|
|
|
@end table
|
@end table
|
|
|
@node Cache Configuration
|
@node Cache Configuration
|
@subsection Cache Configuration
|
@subsection Cache Configuration
|
@cindex configuring data & instruction caches
|
@cindex configuring data & instruction caches
|
@cindex cache configuration
|
@cindex cache configuration
|
@cindex data cache configuration
|
@cindex data cache configuration
|
@cindex instruction cache configuration
|
@cindex instruction cache configuration
|
@cindex @code{section dc}
|
@cindex @code{section dc}
|
@cindex @code{section ic}
|
@cindex @code{section ic}
|
Cache configuration is described in @code{section dc} (for the data
|
Cache configuration is described in @code{section dc} (for the data
|
cache) and @code{seciton ic} (for the instruction cache). Each section
|
cache) and @code{seciton ic} (for the instruction cache). Each section
|
should appear at most once. The following parameters may be specified.
|
should appear at most once. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (cache configuration)
|
@cindex @code{enabled} (cache configuration)
|
If 1 (true), the data or instruction (as appropriate) cache is
|
If 1 (true), the data or instruction (as appropriate) cache is
|
enabled. If 0 (the default), it is disabled.
|
enabled. If 0 (the default), it is disabled.
|
|
|
@item nsets = @var{value}
|
@item nsets = @var{value}
|
@cindex @code{nsets} (cache configuration)
|
@cindex @code{nsets} (cache configuration)
|
Sets the number of data or instruction (as appropriate) cache sets to
|
Sets the number of data or instruction (as appropriate) cache sets to
|
@var{value}, which must be a power of two, not exceeding
|
@var{value}, which must be a power of two, not exceeding
|
@code{MAX_DC_SETS} (for the data cache) or @code{MAX_IC_SETS} (for the
|
@code{MAX_DC_SETS} (for the data cache) or @code{MAX_IC_SETS} (for the
|
instruction cache). At the time of writing, these constants are
|
instruction cache). At the time of writing, these constants are
|
both defined in the code to be 1024). The default value is 1.
|
both defined in the code to be 1024). The default value is 1.
|
|
|
@item nways = @var{value}
|
@item nways = @var{value}
|
@cindex @code{nways} (cache configuration)
|
@cindex @code{nways} (cache configuration)
|
Sets the number of data or instruction (as appropriate) cache ways to
|
Sets the number of data or instruction (as appropriate) cache ways to
|
@var{value}, which must be a power of two, not exceeding
|
@var{value}, which must be a power of two, not exceeding
|
@code{MAX_DC_WAYS} (for the data cache) or @code{MAX_IC_WAYS} (for the
|
@code{MAX_DC_WAYS} (for the data cache) or @code{MAX_IC_WAYS} (for the
|
instruction cache). At the time of writing, these constants are both
|
instruction cache). At the time of writing, these constants are both
|
defined in the code to be 32). The default value is 1.
|
defined in the code to be 32). The default value is 1.
|
|
|
@item blocksize = @var{value}
|
@item blocksize = @var{value}
|
@cindex @code{blocksize} (cache configuration)
|
@cindex @code{blocksize} (cache configuration)
|
The data or instruction (as appropriate) cache block size is set to
|
The data or instruction (as appropriate) cache block size is set to
|
@var{value} bytes, which must be either 16 or 32. The default is 16.
|
@var{value} bytes, which must be either 16 or 32. The default is 16.
|
|
|
@item ustates = @var{value}
|
@item ustates = @var{value}
|
@cindex @code{ustates} (cache configuration)
|
@cindex @code{ustates} (cache configuration)
|
The number of instruction usage states for the data or instruction (as
|
The number of instruction usage states for the data or instruction (as
|
appropriate) cache is set to @var{value}, which must be 2, 3 or 4. The
|
appropriate) cache is set to @var{value}, which must be 2, 3 or 4. The
|
default value is 2.
|
default value is 2.
|
|
|
@item hitdelay = @var{value}
|
@item hitdelay = @var{value}
|
@cindex @code{hitdelay} (instruction cache configuration)
|
@cindex @code{hitdelay} (instruction cache configuration)
|
@emph{Instruction cache only}. Set the number of cycles an instruction
|
@emph{Instruction cache only}. Set the number of cycles an instruction
|
cache hit costs. Default value 1.
|
cache hit costs. Default value 1.
|
|
|
@item missdelay = @var{value}
|
@item missdelay = @var{value}
|
@cindex @code{missdelay} (instruction cache configuration)
|
@cindex @code{missdelay} (instruction cache configuration)
|
@emph{Instruction cache only}. Set the number of cycles an instruction
|
@emph{Instruction cache only}. Set the number of cycles an instruction
|
cache miss costs. Default value 1.
|
cache miss costs. Default value 1.
|
|
|
@item load_hitdelay = @var{value}
|
@item load_hitdelay = @var{value}
|
@cindex @code{load_hitdelay} (data cache configuration)
|
@cindex @code{load_hitdelay} (data cache configuration)
|
@emph{Data cache only}. Set the number of cycles a data load cache hit
|
@emph{Data cache only}. Set the number of cycles a data load cache hit
|
costs. Default value 2.
|
costs. Default value 2.
|
|
|
@item load_missdelay = @var{value}
|
@item load_missdelay = @var{value}
|
@cindex @code{load_missdelay} (data cache configuration)
|
@cindex @code{load_missdelay} (data cache configuration)
|
@emph{Data cache only}. Set the number of cycles a data load cache
|
@emph{Data cache only}. Set the number of cycles a data load cache
|
miss costs. Default value 2.
|
miss costs. Default value 2.
|
|
|
@item store_hitdelay = @var{value}
|
@item store_hitdelay = @var{value}
|
@cindex @code{store_hitdelay} (data cache configuration)
|
@cindex @code{store_hitdelay} (data cache configuration)
|
@emph{Data cache only}. Set the number of cycles a data store cache hit
|
@emph{Data cache only}. Set the number of cycles a data store cache hit
|
costs. Default value 0.
|
costs. Default value 0.
|
|
|
@item store_missdelay = @var{value}
|
@item store_missdelay = @var{value}
|
@cindex @code{store_missdelay} (data cache configuration)
|
@cindex @code{store_missdelay} (data cache configuration)
|
@emph{Data cache only}. Set the number of cycles a data store cache
|
@emph{Data cache only}. Set the number of cycles a data store cache
|
miss costs. Default value 0.
|
miss costs. Default value 0.
|
|
|
@end table
|
@end table
|
|
|
@node Interrupt Configuration
|
@node Interrupt Configuration
|
@subsection Interrupt Configuration
|
@subsection Interrupt Configuration
|
@cindex configuring the interrupt controller
|
@cindex configuring the interrupt controller
|
@cindex interrupt controller configuration
|
@cindex interrupt controller configuration
|
@cindex programmable interrupt controller configuration
|
@cindex programmable interrupt controller configuration
|
@cindex PIC configuration
|
@cindex PIC configuration
|
@cindex @code{section pic}
|
@cindex @code{section pic}
|
Programmable Interrupt Controller (PIC) configuration is described in
|
Programmable Interrupt Controller (PIC) configuration is described in
|
@code{section pic}. This section may appear at most
|
@code{section pic}. This section may appear at most
|
once---@value{OR1KSIM} has no mechanism for handling multiple
|
once---@value{OR1KSIM} has no mechanism for handling multiple
|
interrupt controllers. The following parameters may be specified.
|
interrupt controllers. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (interrupt controller)
|
@cindex @code{enabled} (interrupt controller)
|
If 1 (true), the programmable interrupt controller is enabled. If 0
|
If 1 (true), the programmable interrupt controller is enabled. If 0
|
(the default), it is disabled.
|
(the default), it is disabled.
|
|
|
@item edge_trigger = 0|1
|
@item edge_trigger = 0|1
|
@cindex @code{edge_trigger} (interrupt controller)
|
@cindex @code{edge_trigger} (interrupt controller)
|
If 1 (true, the default), the programmable interrupt controller is
|
If 1 (true, the default), the programmable interrupt controller is
|
edge triggered. If 0 (false), it is level triggered.
|
edge triggered. If 0 (false), it is level triggered.
|
|
|
The library interface (@pxref{Simulator Library, , Simulator Library})
|
The library interface (@pxref{Simulator Library, , Simulator Library})
|
provides different functions for setting the different types of
|
provides different functions for setting the different types of
|
interrupt, and a function to clear level sensitive interrupts. Edge
|
interrupt, and a function to clear level sensitive interrupts. Edge
|
sensitive interrupts must be cleared by clearing the corresponding bit
|
sensitive interrupts must be cleared by clearing the corresponding bit
|
in the PICSR SPR.
|
in the PICSR SPR.
|
|
|
Internal functions to set and clear interrupts are also provided for
|
Internal functions to set and clear interrupts are also provided for
|
peripherals implemented within @value{OR1KSIM}. @xref{Interrupts Internal, ,
|
peripherals implemented within @value{OR1KSIM}. @xref{Interrupts Internal, ,
|
Interrupts Internal} for more details.
|
Interrupts Internal} for more details.
|
|
|
@item use_nmi = 0|1
|
@item use_nmi = 0|1
|
@cindex @code{use_nmi} (interrupt controller)
|
@cindex @code{use_nmi} (interrupt controller)
|
If 1 (true, the default), interrupt lines 0 and 1 are non-maskable. In
|
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
|
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.
|
to 1. If 0 (false), all interrupt lines are treated as equivalent.
|
|
|
@quotation Note
|
@quotation Note
|
These are not non-maskable in the true sense that they will pre-empt
|
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
|
other interrupts. Rather they can never be masked out using the PICMR
|
register. It is up the interrupt exception handler to give these
|
register. It is up the interrupt exception handler to give these
|
interrupt lines priority, and indeed to decide on the priority order in
|
interrupt lines priority, and indeed to decide on the priority order in
|
general.
|
general.
|
@end quotation
|
@end quotation
|
|
|
@end table
|
@end table
|
|
|
@node Power Management Configuration
|
@node Power Management Configuration
|
@subsection Power Management Configuration
|
@subsection Power Management Configuration
|
@cindex configuring power management
|
@cindex configuring power management
|
@cindex power management configuration
|
@cindex power management configuration
|
@cindex PMU configuration
|
@cindex PMU configuration
|
@cindex @code{section pmu}
|
@cindex @code{section pmu}
|
Power management implementation is incomplete. At present the effect
|
Power management implementation is incomplete. At present the effect
|
(which only happens when the power management unit is enabled) of
|
(which only happens when the power management unit is enabled) of
|
setting the different bits in the power management Special Purpose
|
setting the different bits in the power management Special Purpose
|
Register (PMR, SPR 0x4000) is
|
Register (PMR, SPR 0x4000) is
|
|
|
@table @code
|
@table @code
|
|
|
@item SDF (bit mask 0x0000000f)
|
@item SDF (bit mask 0x0000000f)
|
@cindex SDF (power management register)
|
@cindex SDF (power management register)
|
@cindex slow down factor (power management register)
|
@cindex slow down factor (power management register)
|
@cindex power management register, SDF
|
@cindex power management register, SDF
|
@cindex PMR - SDF
|
@cindex PMR - SDF
|
No effect - these bits are ignored
|
No effect - these bits are ignored
|
|
|
@item DME (bit mask 0x00000010)
|
@item DME (bit mask 0x00000010)
|
@cindex DME (power management register)
|
@cindex DME (power management register)
|
@cindex doze mode (power management register)
|
@cindex doze mode (power management register)
|
@cindex power management register, DME
|
@cindex power management register, DME
|
@cindex PMR - DME
|
@cindex PMR - DME
|
@itemx SME (bit mask 0x00000020)
|
@itemx SME (bit mask 0x00000020)
|
@cindex SME (power management register)
|
@cindex SME (power management register)
|
@cindex sleep mode (power management register)
|
@cindex sleep mode (power management register)
|
@cindex power management register, SME
|
@cindex power management register, SME
|
@cindex PMR - SME
|
@cindex PMR - SME
|
Both these bits cause the processor to stop executing
|
Both these bits cause the processor to stop executing
|
instructions. However all other functions (debug interaction, CLI,
|
instructions. However all other functions (debug interaction, CLI,
|
VAPI etc) carry on as normal.
|
VAPI etc) carry on as normal.
|
|
|
@item DCGE (bit mask 0x00000004)
|
@item DCGE (bit mask 0x00000004)
|
@cindex DCGE (power management register)
|
@cindex DCGE (power management register)
|
@cindex dynamic clock gating (power management register)
|
@cindex dynamic clock gating (power management register)
|
@cindex power management register, DGCE
|
@cindex power management register, DGCE
|
@cindex PMR - DGCE
|
@cindex PMR - DGCE
|
No effect - this bit is ignored
|
No effect - this bit is ignored
|
|
|
@item SUME (bit mask 0x00000008)
|
@item SUME (bit mask 0x00000008)
|
@cindex SUME (power management register)
|
@cindex SUME (power management register)
|
@cindex suspend mode (power management register)
|
@cindex suspend mode (power management register)
|
@cindex power management register, SUME
|
@cindex power management register, SUME
|
@cindex PMR - SUME
|
@cindex PMR - SUME
|
Enabling this bit causes a message to be printed, advising that the
|
Enabling this bit causes a message to be printed, advising that the
|
processor is suspending and the simulator exits.
|
processor is suspending and the simulator exits.
|
|
|
@end table
|
@end table
|
|
|
On reset all bits are cleared.
|
On reset all bits are cleared.
|
|
|
Power management configuration is described in @code{section pm}. This
|
Power management configuration is described in @code{section pm}. This
|
section may appear at most once. The following parameter may be specified.
|
section may appear at most once. The following parameter may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (power management configuration)
|
@cindex @code{enabled} (power management configuration)
|
If 1 (true), power management is enabled. If 0 (the default), it is
|
If 1 (true), power management is enabled. If 0 (the default), it is
|
disabled.
|
disabled.
|
|
|
@end table
|
@end table
|
|
|
@node Branch Prediction Configuration
|
@node Branch Prediction Configuration
|
@subsection Branch Prediction Configuration
|
@subsection Branch Prediction Configuration
|
@cindex configuring branch prediction
|
@cindex configuring branch prediction
|
@cindex branch prediction configuration
|
@cindex branch prediction configuration
|
@cindex BPB configuration
|
@cindex BPB configuration
|
@cindex @code{section bpb}
|
@cindex @code{section bpb}
|
From examining the code base, it seems the branch prediction function
|
From examining the code base, it seems the branch prediction function
|
is not fully implemented. At present the functionality seems
|
is not fully implemented. At present the functionality seems
|
restricted to collection of statistics.
|
restricted to collection of statistics.
|
|
|
Branch prediction configuration is described in @code{section bpb}. This
|
Branch prediction configuration is described in @code{section bpb}. This
|
section may appear at most once. The following parameters may be specified.
|
section may appear at most once. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (branch prediction configuration)
|
@cindex @code{enabled} (branch prediction configuration)
|
If 1 (true), branch prediction is enabled. If 0 (the default), it is
|
If 1 (true), branch prediction is enabled. If 0 (the default), it is
|
disabled.
|
disabled.
|
|
|
@item btic = 0|1
|
@item btic = 0|1
|
@cindex @code{btic} (branch prediction configuration)
|
@cindex @code{btic} (branch prediction configuration)
|
If 1 (true), the branch target instruction cache model is enabled. If
|
If 1 (true), the branch target instruction cache model is enabled. If
|
0 (the default), it is disabled.
|
0 (the default), it is disabled.
|
|
|
@item sbp_bf_fwd = 0|1
|
@item sbp_bf_fwd = 0|1
|
@cindex @code{sbp_bf_fwd} (branch prediction configuration)
|
@cindex @code{sbp_bf_fwd} (branch prediction configuration)
|
If 1 (true), use forward prediction for the @code{l.bf} instruction. If
|
If 1 (true), use forward prediction for the @code{l.bf} instruction. If
|
0 (the default), do not use forward prediction for this instruction.
|
0 (the default), do not use forward prediction for this instruction.
|
|
|
@item sbp_bnf_fwd = 0|1
|
@item sbp_bnf_fwd = 0|1
|
@cindex @code{sbp_bnf_fwd} (branch prediction configuration)
|
@cindex @code{sbp_bnf_fwd} (branch prediction configuration)
|
If 1 (true), use forward prediction for the @code{l.bnf} instruction. If
|
If 1 (true), use forward prediction for the @code{l.bnf} instruction. If
|
0 (the default), do not use forward prediction for this instruction.
|
0 (the default), do not use forward prediction for this instruction.
|
|
|
@item hitdelay = @var{value}
|
@item hitdelay = @var{value}
|
@cindex @code{hitdelay} (branch prediction configuration)
|
@cindex @code{hitdelay} (branch prediction configuration)
|
Set the number of cycles a branch prediction hit costs. Default value
|
Set the number of cycles a branch prediction hit costs. Default value
|
0.
|
0.
|
|
|
@item missdelay = @var{value}
|
@item missdelay = @var{value}
|
@cindex @code{missdelay} (branch prediction configuration)
|
@cindex @code{missdelay} (branch prediction configuration)
|
Set the number of cycles a branch prediction miss costs. Default value
|
Set the number of cycles a branch prediction miss costs. Default value
|
0.
|
0.
|
|
|
@end table
|
@end table
|
|
|
@node Debug Interface Configuration
|
@node Debug Interface Configuration
|
@subsection Debug Interface Configuration
|
@subsection Debug Interface Configuration
|
@cindex configuring the debug unit and interface to external debuggers
|
@cindex configuring the debug unit and interface to external debuggers
|
@cindex debug unit configuration
|
@cindex debug unit configuration
|
@cindex debug interface configuration
|
@cindex debug interface configuration
|
@cindex @code{section debug}
|
@cindex @code{section debug}
|
The debug unit and debug interface configuration is described in
|
The debug unit and debug interface configuration is described in
|
@code{@w{section debug}}. This section may appear at most once. The
|
@code{@w{section debug}}. This section may appear at most once. The
|
following parameters may be specified.
|
following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (debug interface configuration)
|
@cindex @code{enabled} (debug interface configuration)
|
If 1 (true), the debug unit is enabled. If 0 (the default), it is disabled.
|
If 1 (true), the debug unit is enabled. If 0 (the default), it is disabled.
|
|
|
@quotation Note
|
@quotation Note
|
This enables the functionality of the debug unit (its registers etc) within
|
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.
|
the mode. It does not provide any external interface to the debug unit.
|
For
|
For
|
that, see @code{rsp_enabled} below.
|
that, see @code{rsp_enabled} below.
|
@end quotation
|
@end quotation
|
|
|
@item rsp_enabled = 0|1
|
@item rsp_enabled = 0|1
|
@cindex @code{rsp_enabled} (debug interface configuration)
|
@cindex @code{rsp_enabled} (debug interface configuration)
|
@cindex Remote Serial Protocol
|
@cindex Remote Serial Protocol
|
If 1 (true), the GDB @dfn{Remote Serial Protocol} server is started, provding
|
If 1 (true), the GDB @dfn{Remote Serial Protocol} server is started, provding
|
an interface to an external GNU debugger, using the port specified in the
|
an interface to an external GNU debugger, using the port specified in the
|
@code{rsp_port} field (see below), or the @code{or1ksim-rsp} TCP/IP
|
@code{rsp_port} field (see below), or the @code{or1ksim-rsp} TCP/IP
|
service. If 0 (the default), the server is not started, and no external
|
service. If 0 (the default), the server is not started, and no external
|
interface is provided.
|
interface is provided.
|
|
|
For more detailed information on the interface to the GNU Debugger see
|
For more detailed information on the interface to the GNU Debugger see
|
Embecosm Application Note 2, @cite{Howto: Porting the GNU Debugger Practical
|
Embecosm Application Note 2, @cite{Howto: Porting the GNU Debugger Practical
|
Experience with the OpenRISC 1000 Architecture}, by Jeremy Bennett, published
|
Experience with the OpenRISC 1000 Architecture}, by Jeremy Bennett, published
|
by Embecosm Limited (@url{www.embecosm.com}).
|
by Embecosm Limited (@url{www.embecosm.com}).
|
|
|
@item rsp_port = @var{value}
|
@item rsp_port = @var{value}
|
@cindex @code{rsp_port} (debug interface configuration)
|
@cindex @code{rsp_port} (debug interface configuration)
|
@var{value} specifies the port to be used for the GDB @dfn{Remote Serial
|
@var{value} specifies the port to be used for the GDB @dfn{Remote Serial
|
Protocol} interface to the GNU Debugger (GDB). Default value 51000. If
|
Protocol} interface to the GNU Debugger (GDB). Default value 51000. If
|
the value 0 is specified, @value{OR1KSIM} will instead look for a TCP/IP
|
the value 0 is specified, @value{OR1KSIM} will instead look for a TCP/IP
|
service named @code{or1ksim-rsp}.
|
service named @code{or1ksim-rsp}.
|
|
|
@quotation Tip
|
@quotation Tip
|
@cindex TCP/IP port range for @code{or1ksim-rsp} service
|
@cindex TCP/IP port range for @code{or1ksim-rsp} service
|
There is no registered port for @value{OR1KSIM} @dfn{Remote Serial Protocol}
|
There is no registered port for @value{OR1KSIM} @dfn{Remote Serial Protocol}
|
service @code{or1ksim-rsp}. Good practice suggests users should adopt port
|
service @code{or1ksim-rsp}. Good practice suggests users should adopt port
|
values in the @dfn{Dynamic} or @dfn{Private} port range, i.e. 49152-65535.
|
values in the @dfn{Dynamic} or @dfn{Private} port range, i.e. 49152-65535.
|
@end quotation
|
@end quotation
|
|
|
@item vapi_id = @var{value}
|
@item vapi_id = @var{value}
|
@cindex @code{vapi_id} (debug interface configuration)
|
@cindex @code{vapi_id} (debug interface configuration)
|
@var{value} specifies the value of the Verification API (VAPI) base
|
@var{value} specifies the value of the Verification API (VAPI) base
|
address to be used with the debug unit. @xref{Verification API, ,
|
address to be used with the debug unit. @xref{Verification API, ,
|
Verification API}, for more details.
|
Verification API}, for more details.
|
|
|
If this is specified and @var{value} is non-zero, all OpenRISC Remote
|
If this is specified and @var{value} is non-zero, all OpenRISC Remote
|
JTAG protocol transactions will be logged to the VAPI log file, if
|
JTAG protocol transactions will be logged to the VAPI log file, if
|
enabled. This is the only functionality associated with VAPI for the
|
enabled. This is the only functionality associated with VAPI for the
|
debug unit. No VAPI commands are sent, nor requests handled.
|
debug unit. No VAPI commands are sent, nor requests handled.
|
|
|
@end table
|
@end table
|
|
|
@node Peripheral Configuration
|
@node Peripheral Configuration
|
@section Configuring Memory Mapped Peripherals
|
@section Configuring Memory Mapped Peripherals
|
|
|
All peripheral components are optional. If they are specified, then
|
All peripheral components are optional. If they are specified, then
|
(unlike other components) by default they are enabled.
|
(unlike other components) by default they are enabled.
|
|
|
@menu
|
@menu
|
* Memory Controller Configuration::
|
* Memory Controller Configuration::
|
* UART Configuration::
|
* UART Configuration::
|
* DMA Configuration::
|
* DMA Configuration::
|
* Ethernet Configuration::
|
* Ethernet Configuration::
|
* GPIO Configuration::
|
* GPIO Configuration::
|
* Display Interface Configuration::
|
* Display Interface Configuration::
|
* Frame Buffer Configuration::
|
* Frame Buffer Configuration::
|
* Keyboard Configuration::
|
* Keyboard Configuration::
|
* Disc Interface Configuration::
|
* Disc Interface Configuration::
|
* Generic Peripheral Configuration::
|
* Generic Peripheral Configuration::
|
@end menu
|
@end menu
|
|
|
@node Memory Controller Configuration
|
@node Memory Controller Configuration
|
@subsection Memory Controller Configuration
|
@subsection Memory Controller Configuration
|
@cindex configuring the memory controller
|
@cindex configuring the memory controller
|
@cindex memory controller configuration
|
@cindex memory controller configuration
|
@cindex @code{section mc}
|
@cindex @code{section mc}
|
The memory controller used in @value{OR1KSIM} is the component
|
The memory controller used in @value{OR1KSIM} is the component
|
implemented at OpenCores, and found in the top level SVN directory,
|
implemented at OpenCores, and found in the top level SVN directory,
|
@file{mem_ctrl}. It is described in the document @cite{Memory
|
@file{mem_ctrl}. It is described in the document @cite{Memory
|
Controller IP Core} by Rudolf Usselmann, which can be found in the
|
Controller IP Core} by Rudolf Usselmann, which can be found in the
|
@file{doc} subdirectory. It is a memory mapped component, which
|
@file{doc} subdirectory. It is a memory mapped component, which
|
resides on the main OpenRISC Wishbone data bus.
|
resides on the main OpenRISC Wishbone data bus.
|
|
|
The memory controller configuration is described in @code{@w{section
|
The memory controller configuration is described in @code{@w{section
|
mc}}. This section may appear multiple times, specifying multiple
|
mc}}. This section may appear multiple times, specifying multiple
|
memory controllers.
|
memory controllers.
|
|
|
@quotation Warning
|
@quotation Warning
|
There are known to be problems with the current memory controller, which
|
There are known to be problems with the current memory controller, which
|
currently is not included in the regression test suite. Users are
|
currently is not included in the regression test suite. Users are
|
advised not to use the memory controller in the current release.
|
advised not to use the memory controller in the current release.
|
@end quotation
|
@end quotation
|
|
|
@quotation Caution
|
@quotation Caution
|
There is no initialization code in the standard @dfn{newlib}
|
There is no initialization code in the standard @dfn{newlib}
|
library.
|
library.
|
|
|
The standard @dfn{uClibc} library assumes a memory controller
|
The standard @dfn{uClibc} library assumes a memory controller
|
mapped at 0x93000000 and will initialize the memory controller to expect
|
mapped at 0x93000000 and will initialize the memory controller to expect
|
64MB memory blocks, and any memory declarations @emph{must} reflect
|
64MB memory blocks, and any memory declarations @emph{must} reflect
|
this.
|
this.
|
|
|
If smaller memory blocks are declared with a memory controller, then
|
If smaller memory blocks are declared with a memory controller, then
|
sufficient memory will not be allocated by @value{OR1KSIM}, but out of
|
sufficient memory will not be allocated by @value{OR1KSIM}, but out of
|
range memory accesses will not be trapped. For example declaring a
|
range memory accesses will not be trapped. For example declaring a
|
memory section from 0-4MB with a memory controller enabled would mean
|
memory section from 0-4MB with a memory controller enabled would mean
|
that accesses between 4MB and 64MB would be permitted, but having no
|
that accesses between 4MB and 64MB would be permitted, but having no
|
allocated memory would likely cause a segmentation fault.
|
allocated memory would likely cause a segmentation fault.
|
|
|
If the user is determined to use smaller memories with the memory
|
If the user is determined to use smaller memories with the memory
|
controller, then custom initialization code must be provided, to
|
controller, then custom initialization code must be provided, to
|
ensure the memory controller traps out-of-memory accesses.
|
ensure the memory controller traps out-of-memory accesses.
|
@end quotation
|
@end quotation
|
|
|
The following parameters may be specified.
|
The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (memory controller configuration)
|
@cindex @code{enabled} (memory controller configuration)
|
If 1 (true, the default), this memory controller is enabled. If 0, it is
|
If 1 (true, the default), this memory controller is enabled. If 0, it is
|
disabled.
|
disabled.
|
|
|
@quotation Note
|
@quotation Note
|
The memory controller can effectively also be disabled by setting an
|
The memory controller can effectively also be disabled by setting an
|
appropriate power on control register value (see below). However this
|
appropriate power on control register value (see below). However this
|
should only be used if it is desired to specifically model 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
|
behavior of the memory controller, not as a way of disabling the
|
memory controller in general.
|
memory controller in general.
|
@end quotation
|
@end quotation
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (memory controller configuration)
|
@cindex @code{baseaddr} (memory controller configuration)
|
Set the base address of the memory controller's memory mapped
|
Set the base address of the memory controller's memory mapped
|
registers to @var{value}. The default is 0, which is probably not a
|
registers to @var{value}. The default is 0, which is probably not a
|
sensible value.
|
sensible value.
|
|
|
The memory controller has a 7 bit address bus, with a total of 19
|
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
|
32-bit registers, at addresses 0x00 through 0x4c (address 0x0c and
|
addresses 0x50 through 0x7c are not used).
|
addresses 0x50 through 0x7c are not used).
|
|
|
@item poc = @var{value}
|
@item poc = @var{value}
|
@cindex @code{poc} (memory controller configuration)
|
@cindex @code{poc} (memory controller configuration)
|
Specifies the value of the power on control register, The least
|
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
|
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
|
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,
|
type of memory connected (use 0 for a disabled interface, 1 for SSRAM,
|
2 for asyncrhonous devices and 3 for synchronous devices).
|
2 for asyncrhonous devices and 3 for synchronous devices).
|
|
|
If other bits are specified, they are ignored with a warning.
|
If other bits are specified, they are ignored with a warning.
|
|
|
@quotation Caution
|
@quotation Caution
|
The default value, 0, corresponds to a disabled 8-bit bus, and
|
The default value, 0, corresponds to a disabled 8-bit bus, and
|
is likely not the most suitable value
|
is likely not the most suitable value
|
@end quotation
|
@end quotation
|
|
|
@item index = @var{value}
|
@item index = @var{value}
|
@cindex @code{index} (memory controller configuration)
|
@cindex @code{index} (memory controller configuration)
|
Specify the index of this memory controller amongst all the memory
|
Specify the index of this memory controller amongst all the memory
|
controllers. This value should be unique for each memory controller,
|
controllers. This value should be unique for each memory controller,
|
and is used to associate specific memories with the controller,
|
and is used to associate specific memories with the controller,
|
through the @code{mc} field in the @code{@w{section memory}}
|
through the @code{mc} field in the @code{@w{section memory}}
|
configuration (@pxref{Memory Configuration, , Memory Configuration}).
|
configuration (@pxref{Memory Configuration, , Memory Configuration}).
|
|
|
The default value, 0, is suitable when there is only one memory controller.
|
The default value, 0, is suitable when there is only one memory controller.
|
|
|
@end table
|
@end table
|
|
|
@node UART Configuration
|
@node UART Configuration
|
@subsection UART Configuration
|
@subsection UART Configuration
|
@cindex configuring the UART
|
@cindex configuring the UART
|
@cindex UART configuration
|
@cindex UART configuration
|
@cindex @code{section uart}
|
@cindex @code{section uart}
|
The UART implemented in @value{OR1KSIM} follows the specification of the
|
The UART implemented in @value{OR1KSIM} follows the specification of the
|
National Semiconductor 16450 and 16550 parts. It is a memory mapped
|
National Semiconductor 16450 and 16550 parts. It is a memory mapped
|
component, which resides on the main OpenRISC Wishbone data bus.
|
component, which resides on the main OpenRISC Wishbone data bus.
|
|
|
The component provides a number of interfaces to emulate the behavior
|
The component provides a number of interfaces to emulate the behavior
|
of an external terminal connected to the UART.
|
of an external terminal connected to the UART.
|
|
|
UART configuration is described in @code{section uart}. This section
|
UART configuration is described in @code{section uart}. This section
|
may appear multiple times, specifying multiple UARTs. The following
|
may appear multiple times, specifying multiple UARTs. The following
|
parameters may be specified.
|
parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (UART configuration)
|
@cindex @code{enabled} (UART configuration)
|
If 1 (true, the default), this UART is enabled. If 0, it is disabled.
|
If 1 (true, the default), this UART is enabled. If 0, it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (UART configuration)
|
@cindex @code{baseaddr} (UART configuration)
|
Set the base address of the UART's memory mapped
|
Set the base address of the UART's memory mapped
|
registers to @var{value}. The default is 0, which is probably not a
|
registers to @var{value}. The default is 0, which is probably not a
|
sensible value.
|
sensible value.
|
|
|
The UART has a 3 bit address bus, with a total of 8 8-bit registers,
|
The UART has a 3 bit address bus, with a total of 8 8-bit registers,
|
at addresses 0x0 through 0x7.
|
at addresses 0x0 through 0x7.
|
|
|
@item channel = "@var{type}:@var{args}"
|
@item channel = "@var{type}:@var{args}"
|
@cindex @code{channel} (UART configuration)
|
@cindex @code{channel} (UART configuration)
|
Specify the channel representing the terminal connected to the UART
|
Specify the channel representing the terminal connected to the UART
|
Rx & Tx pins.
|
Rx & Tx pins.
|
|
|
@table @code
|
@table @code
|
|
|
@item channel="file:@file{rxfile},@file{txfile}"
|
@item channel="file:@file{rxfile},@file{txfile}"
|
@cindex UART I/O from/to files
|
@cindex UART I/O from/to files
|
Read input characters from the file @file{rxfile} and write output
|
Read input characters from the file @file{rxfile} and write output
|
characters to the file @file{txfile} (which will be created if
|
characters to the file @file{txfile} (which will be created if
|
required).
|
required).
|
|
|
@item channel="xterm:@var{args}"
|
@item channel="xterm:@var{args}"
|
@cindex UART I/O from/to an @command{xterm}
|
@cindex UART I/O from/to an @command{xterm}
|
Create an xterm on startup, write UART Tx traffic to the xterm and
|
Create an xterm on startup, write UART Tx traffic to the xterm and
|
take Rx traffic from the keyboard when the xterm window is
|
take Rx traffic from the keyboard when the xterm window is
|
selected. Additional arguments to the xterm command (for example
|
selected. Additional arguments to the xterm command (for example
|
specifying window size may be specified in @var{args}, or this may be
|
specifying window size may be specified in @var{args}, or this may be
|
left blank.
|
left blank.
|
|
|
@item channel="tcp:@var{value}"
|
@item channel="tcp:@var{value}"
|
@cindex UART I/O from/to TCP/IP
|
@cindex UART I/O from/to TCP/IP
|
Open the TCP/IP port specified by @var{value} and read and write UART
|
Open the TCP/IP port specified by @var{value} and read and write UART
|
traffic from and to it.
|
traffic from and to it.
|
|
|
Typically a telnet session is connected to the other end of this port.
|
Typically a telnet session is connected to the other end of this port.
|
|
|
@quotation Tip
|
@quotation Tip
|
There is no registered port for @value{OR1KSIM} telnet UART
|
There is no registered port for @value{OR1KSIM} telnet UART
|
connection. Priviledged access is required to read traffic on the
|
connection. Priviledged access is required to read traffic on the
|
registered ``well-known'' telnet port (23). Instead users should use
|
registered ``well-known'' telnet port (23). Instead users should use
|
port values in the @dfn{Dynamic} or @dfn{Private} port range,
|
port values in the @dfn{Dynamic} or @dfn{Private} port range,
|
i.e. 49152-65535.
|
i.e. 49152-65535.
|
@end quotation
|
@end quotation
|
|
|
@item channel="fd:@code{rxfd},@code{txfd}"
|
@item channel="fd:@code{rxfd},@code{txfd}"
|
@cindex UART I/O from/to open file descriptors
|
@cindex UART I/O from/to open file descriptors
|
Read and write characters from and to the existing open numerical file
|
Read and write characters from and to the existing open numerical file
|
descriptors, file @code{rxfd} and @code{txfd}.
|
descriptors, file @code{rxfd} and @code{txfd}.
|
|
|
@item channel="tty:device=/dev/ttyS0,baud=9600"
|
@item channel="tty:device=/dev/ttyS0,baud=9600"
|
@cindex UART I/O from/to a physical serial port
|
@cindex UART I/O from/to a physical serial port
|
Read and write characters from and to a physical serial port. The
|
Read and write characters from and to a physical serial port. The
|
precise device (shown here as @code{/dev/ttyS0}) may vary from machine
|
precise device (shown here as @code{/dev/ttyS0}) may vary from machine
|
to machine.
|
to machine.
|
|
|
@end table
|
@end table
|
|
|
The default value for this field is @code{"xterm:"}.
|
The default value for this field is @code{"xterm:"}.
|
|
|
@item irq = @var{value}
|
@item irq = @var{value}
|
@cindex @code{irq} (UART configuration)
|
@cindex @code{irq} (UART configuration)
|
Use @var{value} as the IRQ number of this UART. Default value 0.
|
Use @var{value} as the IRQ number of this UART. Default value 0.
|
|
|
@item 16550 = 0|1
|
@item 16550 = 0|1
|
@cindex @code{16550} (UART configuration)
|
@cindex @code{16550} (UART configuration)
|
If 1 (true), the UART has the functionality of a 16550. If 0 (the
|
If 1 (true), the UART has the functionality of a 16550. If 0 (the
|
default), it has the functionality of a 16450. The principal
|
default), it has the functionality of a 16450. The principal
|
difference is that the 16550 can buffer multiple characters.
|
difference is that the 16550 can buffer multiple characters.
|
|
|
@item jitter = @var{value}
|
@item jitter = @var{value}
|
@cindex @code{jitter} (UART configuration)
|
@cindex @code{jitter} (UART configuration)
|
Set the jitter, modeled as a time to block, to @var{value}
|
Set the jitter, modeled as a time to block, to @var{value}
|
milliseconds. Set to -1 to disable jitter modeling. Default value 0.
|
milliseconds. Set to -1 to disable jitter modeling. Default value 0.
|
|
|
@quotation Note
|
@quotation Note
|
This functionality has yet to be implemented, so this parameter has no
|
This functionality has yet to be implemented, so this parameter has no
|
effect.
|
effect.
|
@end quotation
|
@end quotation
|
|
|
@item vapi_id = @var{value}
|
@item vapi_id = @var{value}
|
@cindex @code{vapi_id} (UART configuration)
|
@cindex @code{vapi_id} (UART configuration)
|
@var{value} specifies the value of the Verification API (VAPI) base
|
@var{value} specifies the value of the Verification API (VAPI) base
|
address to be used with the UART. @xref{Verification API, ,
|
address to be used with the UART. @xref{Verification API, ,
|
Verification API}, for more details, which details the use of the VAPI
|
Verification API}, for more details, which details the use of the VAPI
|
with the UART.
|
with the UART.
|
|
|
@end table
|
@end table
|
|
|
@node DMA Configuration
|
@node DMA Configuration
|
@subsection DMA Configuration
|
@subsection DMA Configuration
|
@cindex configuring DMA
|
@cindex configuring DMA
|
@cindex DMA configuration
|
@cindex DMA configuration
|
@cindex @code{section dma}
|
@cindex @code{section dma}
|
The DMA controller used in @value{OR1KSIM} is the component
|
The DMA controller used in @value{OR1KSIM} is the component
|
implemented at OpenCores, and found in the top level SVN directory,
|
implemented at OpenCores, and found in the top level SVN directory,
|
@file{wb_dma}. It is described in the document @cite{Wishbone
|
@file{wb_dma}. It is described in the document @cite{Wishbone
|
DMA/Bridge IP Core} by Rudolf Usselmann, which can be found in the
|
DMA/Bridge IP Core} by Rudolf Usselmann, which can be found in the
|
@file{doc} subdirectory. It is a memory mapped component, which
|
@file{doc} subdirectory. It is a memory mapped component, which
|
resides on the main OpenRISC Wishbone data bus. The present
|
resides on the main OpenRISC Wishbone data bus. The present
|
implementation is incomplete, intended only to support the Ethernet
|
implementation is incomplete, intended only to support the Ethernet
|
interface (@pxref{Ethernet Configuration}), although the Ethernet
|
interface (@pxref{Ethernet Configuration}), although the Ethernet
|
interface is not yet completed.
|
interface is not yet completed.
|
|
|
DMA configuration is described in @code{@w{section dma}}. This section
|
DMA configuration is described in @code{@w{section dma}}. This section
|
may appear multiple times, specifying multiple DMA controllers. The
|
may appear multiple times, specifying multiple DMA controllers. The
|
following parameters may be specified.
|
following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (DMA configuration)
|
@cindex @code{enabled} (DMA configuration)
|
If 1 (true, the default), this DMA controller is enabled. If 0, it is disabled.
|
If 1 (true, the default), this DMA controller is enabled. If 0, it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (DMA configuration)
|
@cindex @code{baseaddr} (DMA configuration)
|
Set the base address of the DMA's memory mapped
|
Set the base address of the DMA's memory mapped
|
registers to @var{value}. The default is 0, which is probably not a
|
registers to @var{value}. The default is 0, which is probably not a
|
sensible value.
|
sensible value.
|
|
|
The DMA controller has a 10 bit address bus, with a total of 253
|
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
|
32-bit registers. The first 5 registers at addresses 0x000 through
|
0x010 control the overall behavior of the DMA controller. There are
|
0x010 control the overall behavior of the DMA controller. There are
|
then 31 blocks of 8 registers, controlling each of the 31 DMA channels
|
then 31 blocks of 8 registers, controlling each of the 31 DMA channels
|
available. Addresses 0x014 through 0x01c are not used.
|
available. Addresses 0x014 through 0x01c are not used.
|
|
|
@item irq = @var{value}
|
@item irq = @var{value}
|
@cindex @code{irq} (DMA configuration)
|
@cindex @code{irq} (DMA configuration)
|
Use @var{value} as the IRQ number of this DMA controller. Default value 0.
|
Use @var{value} as the IRQ number of this DMA controller. Default value 0.
|
|
|
@item vapi_id = @var{value}
|
@item vapi_id = @var{value}
|
@cindex @code{vapi_id} (DMA configuration)
|
@cindex @code{vapi_id} (DMA configuration)
|
@var{value} specifies the value of the Verification API (VAPI) base
|
@var{value} specifies the value of the Verification API (VAPI) base
|
address to be used with the DMA controller. @xref{Verification API, ,
|
address to be used with the DMA controller. @xref{Verification API, ,
|
Verification API}, for more details, which details the use of the VAPI
|
Verification API}, for more details, which details the use of the VAPI
|
with the DMA controller.
|
with the DMA controller.
|
|
|
@end table
|
@end table
|
|
|
@node Ethernet Configuration
|
@node Ethernet Configuration
|
@subsection Ethernet Configuration
|
@subsection Ethernet Configuration
|
@cindex configuring the Ethernet interface
|
@cindex configuring the Ethernet interface
|
@cindex Ethernet configuration
|
@cindex Ethernet configuration
|
@cindex @code{section ethernet}
|
@cindex @code{section ethernet}
|
Ethernet configuration is described in @code{section ethernet}. This
|
Ethernet configuration is described in @code{section ethernet}. This
|
section may appear multiple times, specifying multiple Ethernet
|
section may appear multiple times, specifying multiple Ethernet
|
interfaces. The following parameters may be specified.
|
interfaces. The following parameters may be specified.
|
|
|
The Ethernet MAC used in @value{OR1KSIM} corresponds to the Verilog
|
The Ethernet MAC used in @value{OR1KSIM} corresponds to the Verilog
|
implementation in project @dfn{ethmac}. It's source code can be found in
|
implementation in project @dfn{ethmac}. It's source code can be found in
|
the top level SVN directory, @file{ethmac}. It also forms part of the
|
the top level SVN directory, @file{ethmac}. It also forms part of the
|
OpenRISC reference SoC, ORPSoC. It is described in the document
|
OpenRISC reference SoC, ORPSoC. It is described in the document
|
@cite{Ethernet IP Core Specification} by Igor Mohor, which can be found
|
@cite{Ethernet IP Core Specification} by Igor Mohor, which can be found
|
in the @file{doc} subdirectory. It is a memory mapped component, which
|
in the @file{doc} subdirectory. It is a memory mapped component, which
|
resides on the main OpenRISC Wishbone data bus.
|
resides on the main OpenRISC Wishbone data bus.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (Ethernet configuration)
|
@cindex @code{enabled} (Ethernet configuration)
|
If 1 (true, the default), this Ethernet MAC is enabled. If 0, it is
|
If 1 (true, the default), this Ethernet MAC is enabled. If 0, it is
|
disabled.
|
disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (Ethernet configuration)
|
@cindex @code{baseaddr} (Ethernet configuration)
|
Set the base address of the MAC's memory mapped registers to
|
Set the base address of the MAC's memory mapped registers to
|
@var{value}. The default is 0, which is probably not a sensible value.
|
@var{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
|
The Ethernet MAC has a 7-bit address bus, with a total of 21
|
32-bit registers. Addresses 0x54 through 0x7c are not used.
|
32-bit registers. Addresses 0x54 through 0x7c are not used.
|
|
|
@quotation Note
|
@quotation Note
|
The Ethernet specification describes a Tx control register,
|
The Ethernet specification describes a Tx control register,
|
@code{TXCTRL}, at address 0x50. However this register is not
|
@code{TXCTRL}, at address 0x50. However this register is not
|
implemented in the @value{OR1KSIM} model.
|
implemented in the @value{OR1KSIM} model.
|
@end quotation
|
@end quotation
|
|
|
@item dma = @var{value}
|
@item dma = @var{value}
|
@cindex @code{dma} (Ethernet configuration)
|
@cindex @code{dma} (Ethernet configuration)
|
@var{value} specifies the DMA controller with which this Ethernet is
|
@var{value} specifies the DMA controller with which this Ethernet is
|
associated. The default value is 0.
|
associated. The default value is 0.
|
|
|
@quotation Note
|
@quotation Note
|
Support for external DMA is not provided in the current
|
Support for external DMA is not provided in the current
|
implementation, and this value is ignored. In any case there is no
|
implementation, and this value is ignored. In any case there is no
|
equivalent field to which this can be matched in the current DMA
|
equivalent field to which this can be matched in the current DMA
|
component implementation (@pxref{DMA Configuration, , DMA
|
component implementation (@pxref{DMA Configuration, , DMA
|
Configuration}).
|
Configuration}).
|
@end quotation
|
@end quotation
|
|
|
@item irq = @var{value}
|
@item irq = @var{value}
|
@cindex @code{dma} (Ethernet configuration)
|
@cindex @code{dma} (Ethernet configuration)
|
Use @var{value} as the IRQ number of this Ethernet MAC. Default value 0.
|
Use @var{value} as the IRQ number of this Ethernet MAC. Default value 0.
|
|
|
@item rtx_type = "file"|"tap"
|
@item rtx_type = "file"|"tap"
|
@cindex @code{rtx_type} (Ethernet configuration)
|
@cindex @code{rtx_type} (Ethernet configuration)
|
Specifies whether to use a TUN/TAP interface or file interface (the default)
|
Specifies whether to use a TUN/TAP interface or file interface (the default)
|
to model the external connection of the Ethernet.
|
to model the external connection of the Ethernet.
|
|
|
If a TUN/TAP interface is requested, Ethernet packets will be sent and
|
If a TUN/TAP interface is requested, Ethernet packets will be sent and
|
received through the pesistent TAP interface specified in parameter
|
received through the pesistent TAP interface specified in parameter
|
@code{tap_dev} (see below).
|
@code{tap_dev} (see below).
|
|
|
More details on configuring the TUN/TAP interface are given in the Usage
|
More details on configuring the TUN/TAP interface are given in the Usage
|
section (@pxref{Ethernet TUN/TAP Interface, , Ethernet TUN/TAP
|
section (@pxref{Ethernet TUN/TAP Interface, , Ethernet TUN/TAP
|
Interface}).
|
Interface}).
|
|
|
If a file interface (the default), is requested, the Ethernet will be
|
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
|
modelled by reading and writing from and to the files specified in the
|
@code{rxfile} and @code{txfile} parameters (see below).
|
@code{rxfile} and @code{txfile} parameters (see below).
|
|
|
@quotation Caution
|
@quotation Caution
|
If a file interface is specified, @value{OR1KSIM} will terminate once the
|
If a file interface is specified, @value{OR1KSIM} will terminate once the
|
receive file specified by @code{rxfile} is exhausted.
|
receive file specified by @code{rxfile} is exhausted.
|
@end quotation
|
@end quotation
|
|
|
@item rx_channel = @var{rxvalue}
|
@item rx_channel = @var{rxvalue}
|
@cindex @code{rx_channel} (Ethernet configuration)
|
@cindex @code{rx_channel} (Ethernet configuration)
|
@itemx tx_channel = @var{txvalue}
|
@itemx tx_channel = @var{txvalue}
|
@cindex @code{tx_channel} (Ethernet configuration)
|
@cindex @code{tx_channel} (Ethernet configuration)
|
@var{rxvalue} specifies the DMA channel to use for receive and
|
@var{rxvalue} specifies the DMA channel to use for receive and
|
@var{txvalue} the DMA channel to use for transmit. Both default to 0.
|
@var{txvalue} the DMA channel to use for transmit. Both default to 0.
|
|
|
@quotation Note
|
@quotation Note
|
As noted above, support for external DMA is not provided in the
|
As noted above, support for external DMA is not provided in the
|
current implementation, and so these values are ignored.
|
current implementation, and so these values are ignored.
|
@end quotation
|
@end quotation
|
|
|
@item rxfile = "@var{rxfile}"
|
@item rxfile = "@var{rxfile}"
|
@cindex @code{rxfile} (Ethernet configuration)
|
@cindex @code{rxfile} (Ethernet configuration)
|
@itemx txfile = "@var{txfile}"
|
@itemx txfile = "@var{txfile}"
|
@cindex @code{txfile} (Ethernet configuration)
|
@cindex @code{txfile} (Ethernet configuration)
|
When @code{rtx_type} is 0 (see above), @var{rxfile} specifies the file
|
When @code{rtx_type} is 0 (see above), @var{rxfile} specifies the file
|
to use as input and @var{txfile} specifies the fie to use as
|
to use as input and @var{txfile} specifies the fie to use as
|
output.
|
output.
|
|
|
The file contains a sequence of packets. Each packet consists of a
|
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
|
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
|
input file is empty, the Ethernet MAC behaves as though there were no
|
data on the Ethernet. The default values of these parameters are
|
data on the Ethernet. The default values of these parameters are
|
@code{"eth_rx"} and @code{"eth_tx"} respectively.
|
@code{"eth_rx"} and @code{"eth_tx"} respectively.
|
|
|
The input file must exist and be readable. The output file must be
|
The input file must exist and be readable. The output file must be
|
writable and will be created if necessary. If either of these
|
writable and will be created if necessary. If either of these
|
conditions is not met, a warning will be given.
|
conditions is not met, a warning will be given.
|
|
|
@quotation Caution
|
@quotation Caution
|
@value{OR1KSIM} will terminate once the @var{rxfile} is exhausted.
|
@value{OR1KSIM} will terminate once the @var{rxfile} is exhausted.
|
@end quotation
|
@end quotation
|
|
|
@item tap_dev = "@var{tap}"
|
@item tap_dev = "@var{tap}"
|
@cindex @code{tap_dev} (Ethernet configuration)
|
@cindex @code{tap_dev} (Ethernet configuration)
|
When @code{rtx_type} is @code{"tap"} (see above), @var{tap_dev}
|
When @code{rtx_type} is @code{"tap"} (see above), @var{tap_dev}
|
specifies the TAP device to use for communication. This should be a
|
specifies the TAP device to use for communication. This should be a
|
persistent TAP device configured for the system (@pxref{Ethernet TUN/TAP
|
persistent TAP device configured for the system (@pxref{Ethernet TUN/TAP
|
Interface, , Ethernet TUN/TAP Interface})
|
Interface, , Ethernet TUN/TAP Interface})
|
|
|
@item phy_addr = @var{value}
|
@item phy_addr = @var{value}
|
@cindex @code{phy_addr}
|
@cindex @code{phy_addr}
|
@var{value} specifies the address for emulated ethernet PHY (default
|
@var{value} specifies the address for emulated ethernet PHY (default
|
0). If there are multiple Ethernet peripherals, they should each have a
|
0). If there are multiple Ethernet peripherals, they should each have a
|
different PHY value.
|
different PHY value.
|
|
|
@item dummy_crc = 0|1
|
@item dummy_crc = 0|1
|
@cindex @code{dummy_crc} (Ethernet configuration)
|
@cindex @code{dummy_crc} (Ethernet configuration)
|
If 1 (true, the default), the length of the data transferred to the core
|
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.
|
will be increased by 4 bytes, as though the CRC were included.
|
|
|
@quotation Note
|
@quotation Note
|
This is for historical consistency with the OpenRISC Ethernet hardware
|
This is for historical consistency with the OpenRISC Ethernet hardware
|
MAC, which passes on the CRC in the data packet. This is unusual
|
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
|
behavior for a MAC, but the OpenRISC Linux device drivers have been
|
written to expect it.
|
written to expect it.
|
@end quotation
|
@end quotation
|
|
|
@item phy_addr = @var{value}
|
@item phy_addr = @var{value}
|
@cindex @code{phy_addr}
|
@cindex @code{phy_addr}
|
@var{value} specifies the address for emulated ethernet PHY (default
|
@var{value} specifies the address for emulated ethernet PHY (default
|
0). If there are multiple Ethernet peripherals, they should each have a
|
0). If there are multiple Ethernet peripherals, they should each have a
|
different PHY value.
|
different PHY value.
|
|
|
@item vapi_id = @var{value}
|
@item vapi_id = @var{value}
|
@cindex @code{vapi_id} (DMA configuration)
|
@cindex @code{vapi_id} (DMA configuration)
|
@var{value} specifies the value of the Verification API (VAPI) base
|
@var{value} specifies the value of the Verification API (VAPI) base
|
address to be used with the Ethernet PHY. @xref{Verification API, ,
|
address to be used with the Ethernet PHY. @xref{Verification API, ,
|
Verification API}, for more details, which details the use of the VAPI
|
Verification API}, for more details, which details the use of the VAPI
|
with the DMA controller.
|
with the DMA controller.
|
|
|
@end table
|
@end table
|
|
|
@node GPIO Configuration
|
@node GPIO Configuration
|
@subsection GPIO Configuration
|
@subsection GPIO Configuration
|
@cindex configuring the GPIO
|
@cindex configuring the GPIO
|
@cindex GPIO configuration
|
@cindex GPIO configuration
|
@cindex @code{section cpio}
|
@cindex @code{section cpio}
|
The GPIO used in @value{OR1KSIM} is the component implemented at
|
The GPIO used in @value{OR1KSIM} is the component implemented at
|
OpenCores, and found in the top level SVN directory, @file{gpio}. It
|
OpenCores, and found in the top level SVN directory, @file{gpio}. It
|
is described in the document @cite{GPIO IP Core Specification} by
|
is described in the document @cite{GPIO IP Core Specification} by
|
Damjan Lampret and Goran Djakovic, which can be found in the
|
Damjan Lampret and Goran Djakovic, which can be found in the
|
@file{doc} subdirectory. It is a memory mapped component, which
|
@file{doc} subdirectory. It is a memory mapped component, which
|
resides on the main OpenRISC Wishbone data bus.
|
resides on the main OpenRISC Wishbone data bus.
|
|
|
GPIO configuration is described in @code{@w{section gpio}}. This section
|
GPIO configuration is described in @code{@w{section gpio}}. This section
|
may appear multiple times, specifying multiple GPIO devices. The
|
may appear multiple times, specifying multiple GPIO devices. The
|
following parameters may be specified.
|
following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (GPIO configuration)
|
@cindex @code{enabled} (GPIO configuration)
|
If 1 (true, the default), this GPIO is enabled. If 0, it is disabled.
|
If 1 (true, the default), this GPIO is enabled. If 0, it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (GPIO configuration)
|
@cindex @code{baseaddr} (GPIO configuration)
|
Set the base address of the GPIO's memory mapped
|
Set the base address of the GPIO's memory mapped
|
registers to @var{value}. The default is 0, which is probably not a
|
registers to @var{value}. The default is 0, which is probably not a
|
sensible value.
|
sensible value.
|
|
|
The GPIO has a 6 bit address bus, with a total of 10 32-bit registers,
|
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
|
although the number of bits that are actively used varies. Addresses
|
0x28 through 0x3c are not used.
|
0x28 through 0x3c are not used.
|
|
|
@item irq = @var{value}
|
@item irq = @var{value}
|
@cindex @code{irq} (GPIO configuration)
|
@cindex @code{irq} (GPIO configuration)
|
Use @var{value} as the IRQ number of this GPIO. Default value 0.
|
Use @var{value} as the IRQ number of this GPIO. Default value 0.
|
|
|
@item vapi_id = @var{value}
|
@item vapi_id = @var{value}
|
@cindex @code{vapi_id} (GPIO configuration)
|
@cindex @code{vapi_id} (GPIO configuration)
|
@cindex @code{base_vapi_id} (GPIO configuration - deprecated)
|
@cindex @code{base_vapi_id} (GPIO configuration - deprecated)
|
@var{value} specifies the value of the Verification API (VAPI) base
|
@var{value} specifies the value of the Verification API (VAPI) base
|
address to be used with the GPIO. @xref{Verification API, ,
|
address to be used with the GPIO. @xref{Verification API, ,
|
Verification API}, for more details, which details the use of the VAPI
|
Verification API}, for more details, which details the use of the VAPI
|
with the GPIO controller. For backwards compatibility, the
|
with the GPIO controller. For backwards compatibility, the
|
alternative name @code{base_vapi_id} is supported for this parameter,
|
alternative name @code{base_vapi_id} is supported for this parameter,
|
but deprecated.
|
but deprecated.
|
|
|
@end table
|
@end table
|
|
|
@node Display Interface Configuration
|
@node Display Interface Configuration
|
@subsection Display Interface Configuration
|
@subsection Display Interface Configuration
|
@cindex configuring the VGA interface
|
@cindex configuring the VGA interface
|
@cindex display interface configuration
|
@cindex display interface configuration
|
@cindex VGA configuration
|
@cindex VGA configuration
|
@cindex @code{section vga}
|
@cindex @code{section vga}
|
@value{OR1KSIM} models a VGA interface to an external monitor. The
|
@value{OR1KSIM} models a VGA interface to an external monitor. The
|
VGA controller used in @value{OR1KSIM} is the component implemented at
|
VGA controller used in @value{OR1KSIM} is the component implemented at
|
OpenCores, and found in the top level SVN directory, @file{vga_lcd},
|
OpenCores, and found in the top level SVN directory, @file{vga_lcd},
|
with no support for the optional hardware cursors. It is described in
|
with no support for the optional hardware cursors. It is described in
|
the document @cite{VGA/LCD Core v2.0 Specifications} by Richard
|
the document @cite{VGA/LCD Core v2.0 Specifications} by Richard
|
Herveille, which can be found in the @file{doc} subdirectory. It is a
|
Herveille, which can be found in the @file{doc} subdirectory. It is a
|
memory mapped component, which resides on the main OpenRISC Wishbone
|
memory mapped component, which resides on the main OpenRISC Wishbone
|
data bus.
|
data bus.
|
|
|
The current implementation provides only functionality to dump the
|
The current implementation provides only functionality to dump the
|
screen to a file at intervals.
|
screen to a file at intervals.
|
|
|
VGA controller configuration is described in @code{@w{section
|
VGA controller configuration is described in @code{@w{section
|
vga}}. This section may appear multiple times, specifying multiple
|
vga}}. This section may appear multiple times, specifying multiple
|
VGA controllers. The following parameters may be specified.
|
VGA controllers. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (VGA configuration)
|
@cindex @code{enabled} (VGA configuration)
|
If 1 (true, the default), this VGA is enabled. If 0, it is disabled.
|
If 1 (true, the default), this VGA is enabled. If 0, it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (VGA configuration)
|
@cindex @code{baseaddr} (VGA configuration)
|
Set the base address of the VGA controller's memory mapped
|
Set the base address of the VGA controller's memory mapped
|
registers to @var{value}. The default is 0, which is probably not a
|
registers to @var{value}. The default is 0, which is probably not a
|
sensible value.
|
sensible value.
|
|
|
The VGA controller has a 12-bit address bus, with 7 32-bit registers, at
|
The VGA controller has a 12-bit address bus, with 7 32-bit registers, at
|
addresses 0x000 through 0x018, and two color lookup tables at
|
addresses 0x000 through 0x018, and two color lookup tables at
|
addresses 0x800 through 0xfff. The hardware cursor registers are not
|
addresses 0x800 through 0xfff. The hardware cursor registers are not
|
implemented, so addresses 0x01c through 0x7fc are not used.
|
implemented, so addresses 0x01c through 0x7fc are not used.
|
|
|
@item irq = @var{value}
|
@item irq = @var{value}
|
@cindex @code{irq} (VGA configuration)
|
@cindex @code{irq} (VGA configuration)
|
Use @var{value} as the IRQ number of this VGA controller. Default
|
Use @var{value} as the IRQ number of this VGA controller. Default
|
value 0.
|
value 0.
|
|
|
@item refresh_rate = @var{value}
|
@item refresh_rate = @var{value}
|
@cindex @code{refresh_rate} (VGA configuration)
|
@cindex @code{refresh_rate} (VGA configuration)
|
@var{value} specifies number of cycles between screen dumps. Default
|
@var{value} specifies number of cycles between screen dumps. Default
|
value is derived from the simulation clock cycle time
|
value is derived from the simulation clock cycle time
|
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond
|
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond
|
to dumping 50 times per simulated second.
|
to dumping 50 times per simulated second.
|
|
|
@item txfile = "@var{file}"
|
@item txfile = "@var{file}"
|
@cindex @code{txfile} (VGA configuration)
|
@cindex @code{txfile} (VGA configuration)
|
@cindex @code{filename} (VGA configuration - deprecated)
|
@cindex @code{filename} (VGA configuration - deprecated)
|
@var{file} specifies the base of the filename for screen
|
@var{file} specifies the base of the filename for screen
|
dumps. Successive screen dumps will be in BMP format, in files with
|
dumps. Successive screen dumps will be in BMP format, in files with
|
the name @file{@var{file}@var{nnnn}.bmp}, where @var{nnnn} is a
|
the name @file{@var{file}@var{nnnn}.bmp}, where @var{nnnn} is a
|
sequential count of the screen dumps starting at zero. The default
|
sequential count of the screen dumps starting at zero. The default
|
value is @code{"vga_out"}. For backwards compatibility, the
|
value is @code{"vga_out"}. For backwards compatibility, the
|
alternative name @code{filename} is supported for this parameter,
|
alternative name @code{filename} is supported for this parameter,
|
but deprecated.
|
but deprecated.
|
|
|
@end table
|
@end table
|
|
|
@node Frame Buffer Configuration
|
@node Frame Buffer Configuration
|
@subsection Frame Buffer Configuration
|
@subsection Frame Buffer Configuration
|
@cindex configuring the frame buffer
|
@cindex configuring the frame buffer
|
@cindex frame buffer configuration
|
@cindex frame buffer configuration
|
@cindex @code{section fb}
|
@cindex @code{section fb}
|
@quotation Caution
|
@quotation Caution
|
The frame buffer is only partially implemented. Its configuration
|
The frame buffer is only partially implemented. Its configuration
|
fields are described here, but the component should not be used at
|
fields are described here, but the component should not be used at
|
this time. Like the VGA controller, it is designed to make screen
|
this time. Like the VGA controller, it is designed to make screen
|
dumps to file.
|
dumps to file.
|
@end quotation
|
@end quotation
|
|
|
Frame buffer configuration is described in @code{section fb}. This
|
Frame buffer configuration is described in @code{section fb}. This
|
section may appear multiple times, specifying multiple frame
|
section may appear multiple times, specifying multiple frame
|
buffers. The following parameters may be specified.
|
buffers. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (frame buffer configuration)
|
@cindex @code{enabled} (frame buffer configuration)
|
If 1 (true, the default), this frame buffer is enabled. If 0, it is disabled.
|
If 1 (true, the default), this frame buffer is enabled. If 0, it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (frame buffer configuration)
|
@cindex @code{baseaddr} (frame buffer configuration)
|
Set the base address of the frame buffer's memory mapped registers to
|
Set the base address of the frame buffer's memory mapped registers to
|
@var{value}. The default is 0, which is probably not a sensible value.
|
@var{value}. The default is 0, which is probably not a sensible value.
|
|
|
The frame buffer has an 121-bit address bus, with 4 32-bit registers,
|
The frame buffer has an 121-bit address bus, with 4 32-bit registers,
|
at addresses 0x000 through 0x00c, and a PAL lookup table at addresses
|
at addresses 0x000 through 0x00c, and a PAL lookup table at addresses
|
0x400 through 0x4ff. Addresses 0x010 through 0x3fc and addresses 0x500
|
0x400 through 0x4ff. Addresses 0x010 through 0x3fc and addresses 0x500
|
through 0x7ff are not used.
|
through 0x7ff are not used.
|
|
|
@item refresh_rate = @var{value}
|
@item refresh_rate = @var{value}
|
@cindex @code{refresh_rate} (frame buffer configuration)
|
@cindex @code{refresh_rate} (frame buffer configuration)
|
@var{value} specifies number of cycles between screen dumps. Default
|
@var{value} specifies number of cycles between screen dumps. Default
|
value is derived from the simulation clock cycle time
|
value is derived from the simulation clock cycle time
|
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond to
|
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond to
|
dumping 50 times per simulated second.
|
dumping 50 times per simulated second.
|
|
|
@item txfile = "@var{file}"
|
@item txfile = "@var{file}"
|
@cindex @code{txfile} (frame buffer configuration)
|
@cindex @code{txfile} (frame buffer configuration)
|
@cindex @code{filename} (frame buffer configuration - deprecated)
|
@cindex @code{filename} (frame buffer configuration - deprecated)
|
@var{file} specifies the base of the filename for screen
|
@var{file} specifies the base of the filename for screen
|
dumps. Successive screen dumps will be in BMP format, in files with
|
dumps. Successive screen dumps will be in BMP format, in files with
|
the name @file{@var{file}@var{nnnn}.bmp}, where @var{nnnn} is a
|
the name @file{@var{file}@var{nnnn}.bmp}, where @var{nnnn} is a
|
sequential count of the screen dumps starting at zero. The default
|
sequential count of the screen dumps starting at zero. The default
|
value is @code{"fb_out"}. For backwards compatibility, the
|
value is @code{"fb_out"}. For backwards compatibility, the
|
alternative name @code{filename} is supported for this parameter,
|
alternative name @code{filename} is supported for this parameter,
|
but deprecated.
|
but deprecated.
|
|
|
@end table
|
@end table
|
|
|
@node Keyboard Configuration
|
@node Keyboard Configuration
|
@subsection Keyboard Configuration (PS2)
|
@subsection Keyboard Configuration (PS2)
|
@cindex configuring the keyboard interface
|
@cindex configuring the keyboard interface
|
@cindex configuring the PS2 interface
|
@cindex configuring the PS2 interface
|
@cindex keyboard configuration
|
@cindex keyboard configuration
|
@cindex PS2 configuration
|
@cindex PS2 configuration
|
@cindex @code{section kb}
|
@cindex @code{section kb}
|
The PS2 interface provided by @value{OR1KSIM} is not documented. It
|
The PS2 interface provided by @value{OR1KSIM} is not documented. It
|
may be based on the PS2 project at OpenCores, and found in
|
may be based on the PS2 project at OpenCores, and found in
|
the top level SVN directory, @file{ps2}. However this project lacks
|
the top level SVN directory, @file{ps2}. However this project lacks
|
any documentation beyond its project webpage. Since most PS2
|
any documentation beyond its project webpage. Since most PS2
|
interfaces follow the Intel i8042 standard, this is presumably what is
|
interfaces follow the Intel i8042 standard, this is presumably what is
|
expected with this device.
|
expected with this device.
|
|
|
The implementation only provides for keyboard support, which is
|
The implementation only provides for keyboard support, which is
|
modelled as a file of keystrokes. There is no mouse support.
|
modelled as a file of keystrokes. There is no mouse support.
|
|
|
@quotation Caution
|
@quotation Caution
|
A standard i8042 device has two registers at addresses 0x60 (command)
|
A standard i8042 device has two registers at addresses 0x60 (command)
|
and 0x64 (status). Inspection of the code, suggests that the
|
and 0x64 (status). Inspection of the code, suggests that the
|
@value{OR1KSIM} component places these registers at addresses 0x00 and
|
@value{OR1KSIM} component places these registers at addresses 0x00 and
|
0x04.
|
0x04.
|
|
|
The port of Linux for the OpenRISC 1000, which runs on @value{OR1KSIM}
|
The port of Linux for the OpenRISC 1000, which runs on @value{OR1KSIM}
|
implements the i8042 device driver, anticipating these registers
|
implements the i8042 device driver, anticipating these registers
|
reside at their conventional address. It seems unlikel that this code
|
reside at their conventional address. It seems unlikel that this code
|
will work.
|
will work.
|
|
|
This component should be used with caution.
|
This component should be used with caution.
|
@end quotation
|
@end quotation
|
|
|
Keyboard configuration is described in @code{section kbd}. This
|
Keyboard configuration is described in @code{section kbd}. This
|
section may appear multiple times, specifying multiple keyboard
|
section may appear multiple times, specifying multiple keyboard
|
interfaces. The following parameters may be specified.
|
interfaces. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (keyboard configuration)
|
@cindex @code{enabled} (keyboard configuration)
|
If 1 (true, the default), this keyboard is enabled. If 0, it is disabled.
|
If 1 (true, the default), this keyboard is enabled. If 0, it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (keyboard configuration)
|
@cindex @code{baseaddr} (keyboard configuration)
|
Set the base address of the keyboard's memory mapped registers to
|
Set the base address of the keyboard's memory mapped registers to
|
@var{value}. The default is 0, which is probably not a sensible value.
|
@var{value}. The default is 0, which is probably not a sensible value.
|
|
|
The keyboard PS/2 interface has an 3-bit address bus, with 2 8-bit registers,
|
The keyboard PS/2 interface has an 3-bit address bus, with 2 8-bit registers,
|
at addresses 0x000 and 0x004.
|
at addresses 0x000 and 0x004.
|
|
|
@quotation Caution
|
@quotation Caution
|
As noted above, a standard Intel 8042 interface would expect to find
|
As noted above, a standard Intel 8042 interface would expect to find
|
these registers at locations 0x60 and 0x64, thus requiring at least a
|
these registers at locations 0x60 and 0x64, thus requiring at least a
|
7-bit bus.
|
7-bit bus.
|
@end quotation
|
@end quotation
|
|
|
@item irq = @var{value}
|
@item irq = @var{value}
|
@cindex @code{irq} (keyboard configuration)
|
@cindex @code{irq} (keyboard configuration)
|
Use @var{value} as the IRQ number of this Keyboard interface. Default
|
Use @var{value} as the IRQ number of this Keyboard interface. Default
|
value 0.
|
value 0.
|
|
|
@item rxfile = "@var{file}"
|
@item rxfile = "@var{file}"
|
@cindex @code{file} (keyboard configuration)
|
@cindex @code{file} (keyboard configuration)
|
@file{file} specifies a file containing raw key stroke data, which
|
@file{file} specifies a file containing raw key stroke data, which
|
models the input from a physical keyboard. The default value is
|
models the input from a physical keyboard. The default value is
|
@code{"kbd_in"}.
|
@code{"kbd_in"}.
|
|
|
@end table
|
@end table
|
|
|
@node Disc Interface Configuration
|
@node Disc Interface Configuration
|
@subsection Disc Interface Configuration
|
@subsection Disc Interface Configuration
|
@cindex configuring the ATA/ATAPI interfaces
|
@cindex configuring the ATA/ATAPI interfaces
|
@cindex disc interface configuration
|
@cindex disc interface configuration
|
@cindex ATA/ATAPI configuration
|
@cindex ATA/ATAPI configuration
|
@cindex @code{section ata}
|
@cindex @code{section ata}
|
The ATA/ATAPI disc controller used in @value{OR1KSIM} is the OCIDEC
|
The ATA/ATAPI disc controller used in @value{OR1KSIM} is the OCIDEC
|
(OpenCores IDE Controller) component implemented at OpenCores, and
|
(OpenCores IDE Controller) component implemented at OpenCores, and
|
found in the top level SVN directory, @file{ata}. It is described in
|
found in the top level SVN directory, @file{ata}. It is described in
|
the document @cite{ATA/ATAPI-5 Core Specification} by Richard
|
the document @cite{ATA/ATAPI-5 Core Specification} by Richard
|
Herveille, which can be found in the @file{doc} subdirectory. It is a
|
Herveille, which can be found in the @file{doc} subdirectory. It is a
|
memory mapped component, which resides on the main OpenRISC Wishbone
|
memory mapped component, which resides on the main OpenRISC Wishbone
|
data bus.
|
data bus.
|
|
|
@quotation Warning
|
@quotation Warning
|
In the current release of @value{OR1KSIM}, parsing of the ATA section is
|
In the current release of @value{OR1KSIM}, parsing of the ATA section is
|
broken. Users should not configure the disc interface in this release.
|
broken. Users should not configure the disc interface in this release.
|
@end quotation
|
@end quotation
|
|
|
ATA/ATAPI configuration is described in @code{@w{section ata}}. This section
|
ATA/ATAPI configuration is described in @code{@w{section ata}}. This section
|
may appear multiple times, specifying multiple disc controllers. The
|
may appear multiple times, specifying multiple disc controllers. The
|
following parameters may be specified.
|
following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (ATA/ATAPI configuration)
|
@cindex @code{enabled} (ATA/ATAPI configuration)
|
If 1 (true, the default), this ATA/ATAPI interface is enabled. If 0,
|
If 1 (true, the default), this ATA/ATAPI interface is enabled. If 0,
|
it is disabled.
|
it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (ATA/ATAPI configuration)
|
@cindex @code{baseaddr} (ATA/ATAPI configuration)
|
Set the base address of the ATA/ATAPI interface's memory mapped
|
Set the base address of the ATA/ATAPI interface's memory mapped
|
registers to @var{value}. The default is 0, which is probably not a
|
registers to @var{value}. The default is 0, which is probably not a
|
sensible value.
|
sensible value.
|
|
|
The ATA/ATAPI PS/2 interface has an 5-bit address bus, with 8 32-bit
|
The ATA/ATAPI PS/2 interface has an 5-bit address bus, with 8 32-bit
|
registers. Depending on the version of the OCIDEC ATA/ATAPI interface
|
registers. Depending on the version of the OCIDEC ATA/ATAPI interface
|
selected (see @code{dev_id} below), not all registers will be available.
|
selected (see @code{dev_id} below), not all registers will be available.
|
|
|
@item irq = @var{value}
|
@item irq = @var{value}
|
@cindex @code{irq} (ATA/ATAPI configuration)
|
@cindex @code{irq} (ATA/ATAPI configuration)
|
Use @var{value} as the IRQ number of this ATA/ATAPI interface. Default
|
Use @var{value} as the IRQ number of this ATA/ATAPI interface. Default
|
value 0.
|
value 0.
|
|
|
@item dev_id = 1|2|3
|
@item dev_id = 1|2|3
|
@cindex @code{dev_id} (ATA/ATAPI configuration)
|
@cindex @code{dev_id} (ATA/ATAPI configuration)
|
This parameter specifies which version of the OCIDEC ATA/ATAPI
|
This parameter specifies which version of the OCIDEC ATA/ATAPI
|
interface to model. The default value is 1.
|
interface to model. The default value is 1.
|
|
|
Version 1 supports only the @code{CTRL}, @code{STAT} and @code{PCTR}
|
Version 1 supports only the @code{CTRL}, @code{STAT} and @code{PCTR}
|
registers. Versions 2 & 3 add the @code{FCTR} registers, Version 3
|
registers. Versions 2 & 3 add the @code{FCTR} registers, Version 3
|
adds the @code{DTR} registers and the @code{RXD}/@code{TXD} registers.
|
adds the @code{DTR} registers and the @code{RXD}/@code{TXD} registers.
|
|
|
@item rev = @var{value}
|
@item rev = @var{value}
|
@cindex @code{rev} (ATA/ATAPI configuration)
|
@cindex @code{rev} (ATA/ATAPI configuration)
|
Set the @var{value} as the revision of the OCIDEC ATA/ATAPI
|
Set the @var{value} as the revision of the OCIDEC ATA/ATAPI
|
interface. The default value is 1. The default value is 0. Its value
|
interface. The default value is 1. The default value is 0. Its value
|
should be in the range 0-15. Larger values are truncated with a
|
should be in the range 0-15. Larger values are truncated with a
|
warning. This only affects the reset value of the @code{STAT}
|
warning. This only affects the reset value of the @code{STAT}
|
register, where it forms bits 24-27.
|
register, where it forms bits 24-27.
|
|
|
@item pio_mode0_t1 = @var{value}
|
@item pio_mode0_t1 = @var{value}
|
@cindex @code{pio_mode0_t1} (ATA/ATAPI configuration)
|
@cindex @code{pio_mode0_t1} (ATA/ATAPI configuration)
|
@itemx pio_mode0_t2 = @var{value}
|
@itemx pio_mode0_t2 = @var{value}
|
@cindex @code{pio_mode0_t2} (ATA/ATAPI configuration)
|
@cindex @code{pio_mode0_t2} (ATA/ATAPI configuration)
|
@itemx pio_mode0_t4 = @var{value}
|
@itemx pio_mode0_t4 = @var{value}
|
@cindex @code{pio_mode0_t4} (ATA/ATAPI configuration)
|
@cindex @code{pio_mode0_t4} (ATA/ATAPI configuration)
|
@itemx pio_mode0_teoc = @var{value}
|
@itemx pio_mode0_teoc = @var{value}
|
@cindex @code{pio_mode0_teoc} (ATA/ATAPI configuration)
|
@cindex @code{pio_mode0_teoc} (ATA/ATAPI configuration)
|
These parameters specify the timings for use with Programmed
|
These parameters specify the timings for use with Programmed
|
Input/Output (PIO) transfers. They are specified as the number of
|
Input/Output (PIO) transfers. They are specified as the number of
|
clock cycles - 2, rounded up to the next highest integer, or zero if
|
clock cycles - 2, rounded up to the next highest integer, or zero if
|
that would be negative. The values should not exceed 255. If they do,
|
that would be negative. The values should not exceed 255. If they do,
|
they will be ignored with a warning.
|
they will be ignored with a warning.
|
|
|
See the ATA/ATAPI-5 specification for explanations of each of these
|
See the ATA/ATAPI-5 specification for explanations of each of these
|
timing parameters. The default values are:
|
timing parameters. The default values are:
|
|
|
@example
|
@example
|
pio_mode0_t1 = 6
|
pio_mode0_t1 = 6
|
pio_mode0_t2 = 28
|
pio_mode0_t2 = 28
|
pio_mode0_t4 = 2
|
pio_mode0_t4 = 2
|
pio_mode0_teoc = 23
|
pio_mode0_teoc = 23
|
@end example
|
@end example
|
|
|
@item dma_mode0_tm = @var{value}
|
@item dma_mode0_tm = @var{value}
|
@cindex @code{dma_mode0_tm} (ATA/ATAPI configuration)
|
@cindex @code{dma_mode0_tm} (ATA/ATAPI configuration)
|
@itemx dma_mode0_td = @var{value}
|
@itemx dma_mode0_td = @var{value}
|
@cindex @code{dma_mode0_td} (ATA/ATAPI configuration)
|
@cindex @code{dma_mode0_td} (ATA/ATAPI configuration)
|
@itemx dma_mode0_teoc = @var{value}
|
@itemx dma_mode0_teoc = @var{value}
|
@cindex @code{dma_mode0_teoc} (ATA/ATAPI configuration)
|
@cindex @code{dma_mode0_teoc} (ATA/ATAPI configuration)
|
These parameters specify the timings for use with DMA transfers. They
|
These parameters specify the timings for use with DMA transfers. They
|
are specified as the number of clock cycles - 2, rounded up to the
|
are specified as the number of clock cycles - 2, rounded up to the
|
next highest integer, or zero if that would be negative. The values
|
next highest integer, or zero if that would be negative. The values
|
should not exceed 255. If they do, they will be ignored with a
|
should not exceed 255. If they do, they will be ignored with a
|
warning.
|
warning.
|
|
|
See the ATA/ATAPI-5 specification for explanations of each of these
|
See the ATA/ATAPI-5 specification for explanations of each of these
|
timing parameters. The default values are:
|
timing parameters. The default values are:
|
|
|
@example
|
@example
|
dma_mode0_tm = 4
|
dma_mode0_tm = 4
|
dma_mode0_td = 21
|
dma_mode0_td = 21
|
dma_mode0_teoc = 21
|
dma_mode0_teoc = 21
|
@end example
|
@end example
|
|
|
@end table
|
@end table
|
|
|
@subsubsection ATA/ATAPI Device Configuration
|
@subsubsection ATA/ATAPI Device Configuration
|
@cindex disc interface device configuration
|
@cindex disc interface device configuration
|
@cindex ATA/ATAPI device configuration
|
@cindex ATA/ATAPI device configuration
|
Within the @code{@w{section ata}}, each device is specified
|
Within the @code{@w{section ata}}, each device is specified
|
separately. The device subsection is introduced by
|
separately. The device subsection is introduced by
|
|
|
@example
|
@example
|
device @var{value}
|
device @var{value}
|
@end example
|
@end example
|
|
|
@var{value} is the device number, which should be 0 or 1. The
|
@var{value} is the device number, which should be 0 or 1. The
|
subsection ends with @code{enddevice}. Note that if the same device
|
subsection ends with @code{enddevice}. Note that if the same device
|
number is specified more than once, the previous values will be
|
number is specified more than once, the previous values will be
|
overwritten. Within the @code{device} subsection, the following
|
overwritten. Within the @code{device} subsection, the following
|
parameters may appear:
|
parameters may appear:
|
|
|
@table @code
|
@table @code
|
|
|
@item type = @var{value}
|
@item type = @var{value}
|
@cindex @code{type} (ATA/ATAPI device configuration)
|
@cindex @code{type} (ATA/ATAPI device configuration)
|
@var{value}specifies the type of device: 0 (the default) for ``not
|
@var{value}specifies the type of device: 0 (the default) for ``not
|
connected'', 1 for hard disk simulated in a file and 2 for local system
|
connected'', 1 for hard disk simulated in a file and 2 for local system
|
hard disk.
|
hard disk.
|
|
|
@item file = "@var{filename}"
|
@item file = "@var{filename}"
|
@cindex @code{file} (ATA/ATAPI device configuration)
|
@cindex @code{file} (ATA/ATAPI device configuration)
|
@file{filename} specifies the file to be used for a simulated ATA
|
@file{filename} specifies the file to be used for a simulated ATA
|
device if the file type (see @code{type} above) is 1. Default value
|
device if the file type (see @code{type} above) is 1. Default value
|
@code{"ata_file@var{n}"}, where @var{n} is the device number.
|
@code{"ata_file@var{n}"}, where @var{n} is the device number.
|
|
|
@item size = @var{value}
|
@item size = @var{value}
|
@cindex @code{size} (ATA/ATAPI device configuration)
|
@cindex @code{size} (ATA/ATAPI device configuration)
|
@var{value} specifies the size of a simulated ATA device if the file
|
@var{value} specifies the size of a simulated ATA device if the file
|
type (see @code{type} above) is 1. The default value is zero.
|
type (see @code{type} above) is 1. The default value is zero.
|
|
|
@item packet = 0|1
|
@item packet = 0|1
|
@cindex @code{packet} (ATA/ATAPI device configuration)
|
@cindex @code{packet} (ATA/ATAPI device configuration)
|
If 1 (true), implement the PACKET command feature set. If 0 (the
|
If 1 (true), implement the PACKET command feature set. If 0 (the
|
default), do not implement the PACKET command feature set.
|
default), do not implement the PACKET command feature set.
|
|
|
@item firmware = "@var{str}"
|
@item firmware = "@var{str}"
|
@cindex @code{firmware} (ATA/ATAPI device configuration)
|
@cindex @code{firmware} (ATA/ATAPI device configuration)
|
Firmware to report in response to the ``Identify Device''
|
Firmware to report in response to the ``Identify Device''
|
command. Default @code{"02207031"}.
|
command. Default @code{"02207031"}.
|
|
|
@item heads = @var{value}
|
@item heads = @var{value}
|
@cindex @code{heads} (ATA/ATAPI device configuration)
|
@cindex @code{heads} (ATA/ATAPI device configuration)
|
Number of heads in the device. Default 7, use -1 to disable all heads.
|
Number of heads in the device. Default 7, use -1 to disable all heads.
|
|
|
@item sectors = @var{value}
|
@item sectors = @var{value}
|
@cindex @code{sectors} (ATA/ATAPI device configuration)
|
@cindex @code{sectors} (ATA/ATAPI device configuration)
|
Number of sectors per track in the device. Default 32.
|
Number of sectors per track in the device. Default 32.
|
|
|
@item mwdma = 0|1|2|-1
|
@item mwdma = 0|1|2|-1
|
@cindex @code{mwdma} (ATA/ATAPI device configuration)
|
@cindex @code{mwdma} (ATA/ATAPI device configuration)
|
Highest multi-word DMA mode supported. Default 2, use -1 to disable.
|
Highest multi-word DMA mode supported. Default 2, use -1 to disable.
|
|
|
@item pio = 0|1|2|3|4
|
@item pio = 0|1|2|3|4
|
@cindex @code{pio} (ATA/ATAPI device configuration)
|
@cindex @code{pio} (ATA/ATAPI device configuration)
|
Highest PIO mode supported. Default 4.
|
Highest PIO mode supported. Default 4.
|
|
|
@end table
|
@end table
|
|
|
@node Generic Peripheral Configuration
|
@node Generic Peripheral Configuration
|
@subsection Generic Peripheral Configuration
|
@subsection Generic Peripheral Configuration
|
@cindex generic peripheral configuration
|
@cindex generic peripheral configuration
|
@cindex configuration of generic peripherals
|
@cindex configuration of generic peripherals
|
@cindex @code{section generic}
|
@cindex @code{section generic}
|
When used as a library (@pxref{Simulator Library, , Simulator
|
When used as a library (@pxref{Simulator Library, , Simulator
|
Library}), @value{OR1KSIM} makes provision for any additional peripheral to be
|
Library}), @value{OR1KSIM} makes provision for any additional peripheral to be
|
implemented externally. Any read or write access to this peripheral's
|
implemented externally. Any read or write access to this peripheral's
|
memory map generates @dfn{upcall}s to an external handler. This
|
memory map generates @dfn{upcall}s to an external handler. This
|
interface can support either C or C++, and was particularly designed
|
interface can support either C or C++, and was particularly designed
|
to facilitate support for OSCI SystemC (see @url{http://www.systemc.org}).
|
to facilitate support for OSCI SystemC (see @url{http://www.systemc.org}).
|
|
|
Generic peripheral configuration is described in @code{@w{section
|
Generic peripheral configuration is described in @code{@w{section
|
generic}}. This section may appear multiple times, specifying multiple
|
generic}}. This section may appear multiple times, specifying multiple
|
external peripherals. The following parameters may be specified.
|
external peripherals. The following parameters may be specified.
|
|
|
@table @code
|
@table @code
|
|
|
@item enabled = 0|1
|
@item enabled = 0|1
|
@cindex @code{enabled} (generic peripheral configuration)
|
@cindex @code{enabled} (generic peripheral configuration)
|
If 1 (true, the default), this ATA/ATAPI interface is enabled. If 0,
|
If 1 (true, the default), this ATA/ATAPI interface is enabled. If 0,
|
it is disabled.
|
it is disabled.
|
|
|
@item baseaddr = @var{value}
|
@item baseaddr = @var{value}
|
@cindex @code{baseaddr} (generic peripheral configuration)
|
@cindex @code{baseaddr} (generic peripheral configuration)
|
Set the base address of the generic peripheral's memory mapped
|
Set the base address of the generic peripheral's memory mapped
|
registers to @var{value}. The default is 0, which is probably not a
|
registers to @var{value}. The default is 0, which is probably not a
|
sensible value.
|
sensible value.
|
|
|
The size of the memory mapped register space is controlled by the
|
The size of the memory mapped register space is controlled by the
|
@code{size} paramter, described below.
|
@code{size} paramter, described below.
|
|
|
@item size = @var{value}
|
@item size = @var{value}
|
@cindex @code{size} (generic peripheral configuration)
|
@cindex @code{size} (generic peripheral configuration)
|
Set the size of the generic peripheral's memory mapped register space
|
Set the size of the generic peripheral's memory mapped register space
|
to @var{value} bytes. Any read or write accesses to addresses with
|
to @var{value} bytes. Any read or write accesses to addresses with
|
offsets of 0 to @var{value}-1 bytes from the base address specified in
|
offsets of 0 to @var{value}-1 bytes from the base address specified in
|
parameter @code{baseaddr} (see above) will be directed to the external
|
parameter @code{baseaddr} (see above) will be directed to the external
|
interface.
|
interface.
|
|
|
@var{value} will be rounded up the nearest power of 2. It's default
|
@var{value} will be rounded up the nearest power of 2. It's default
|
value is zero. If @var{value} is not an exact power of two, accesses
|
value is zero. If @var{value} is not an exact power of two, accesses
|
to address offsets of @var{value} or above up to the next power of 2
|
to address offsets of @var{value} or above up to the next power of 2
|
will generate a warning, and have no effect (reads will return zero).
|
will generate a warning, and have no effect (reads will return zero).
|
|
|
@item name = "@var{str}"
|
@item name = "@var{str}"
|
@cindex @code{name} (generic peripheral configuration)
|
@cindex @code{name} (generic peripheral configuration)
|
This gives the peripheral the name @code{"@var{str}"}. This is used to
|
This gives the peripheral the name @code{"@var{str}"}. This is used to
|
identify the peripheral in error messages and warnings, and when
|
identify the peripheral in error messages and warnings, and when
|
reporting its status. The default value is @code{@w{"anonymous
|
reporting its status. The default value is @code{@w{"anonymous
|
external peripheral"}}.
|
external peripheral"}}.
|
|
|
@item byte_enabled = 0|1
|
@item byte_enabled = 0|1
|
@cindex @code{byte_enabled} (generic peripheral configuration)
|
@cindex @code{byte_enabled} (generic peripheral configuration)
|
@itemx hw_enabled = 0|1
|
@itemx hw_enabled = 0|1
|
@cindex @code{hw_enabled} (generic peripheral configuration)
|
@cindex @code{hw_enabled} (generic peripheral configuration)
|
@itemx word_enabled = 0|1
|
@itemx word_enabled = 0|1
|
@cindex @code{word_enabled} (generic peripheral configuration)
|
@cindex @code{word_enabled} (generic peripheral configuration)
|
If 1 (true, the default), these parameters respectively enable the
|
If 1 (true, the default), these parameters respectively enable the
|
device for byte wide, half-word wide and word wide accesses. If 0,
|
device for byte wide, half-word wide and word wide accesses. If 0,
|
accesses of that width will fail.
|
accesses of that width will fail.
|
|
|
@end table
|
@end table
|
|
|
@node Interactive Command Line
|
@node Interactive Command Line
|
@chapter Interactive Command Line
|
@chapter Interactive Command Line
|
|
|
If started with the @code{-f} flag, or if interrupted with
|
If started with the @code{-f} flag, or if interrupted with
|
@kbd{ctrl-C}, @value{OR1KSIM} provides the user with an interactive
|
@kbd{ctrl-C}, @value{OR1KSIM} provides the user with an interactive
|
command line. The commands available, which may not be abbreviated, are:
|
command line. The commands available, which may not be abbreviated, are:
|
|
|
@table @code
|
@table @code
|
|
|
@item q
|
@item q
|
@cindex @code{q} (Interactive CLI)
|
@cindex @code{q} (Interactive CLI)
|
@cindex quitting (Interactive CLI)
|
@cindex quitting (Interactive CLI)
|
Exit the simulator
|
Exit the simulator
|
|
|
@item r
|
@item r
|
@cindex @code{r} (Interactive CLI)
|
@cindex @code{r} (Interactive CLI)
|
@cindex displaying registers (Interactive CLI)
|
@cindex displaying registers (Interactive CLI)
|
@cindex register display (Interactive CLI)
|
@cindex register display (Interactive CLI)
|
Display all the General Purpose Registers (GPRs). Also shows the just
|
Display all the General Purpose Registers (GPRs). Also shows the just
|
executed and next to be executed instructions symbolically and the
|
executed and next to be executed instructions symbolically and the
|
state of the flag in the Supervision Register.
|
state of the flag in the Supervision Register.
|
|
|
@item t
|
@item t
|
@cindex @code{t} (Interactive CLI)
|
@cindex @code{t} (Interactive CLI)
|
@cindex stepping code (Interactive CLI)
|
@cindex stepping code (Interactive CLI)
|
Execute the next instruction and then display register/instruction
|
Execute the next instruction and then display register/instruction
|
information as with the @code{r} command (see above).
|
information as with the @code{r} command (see above).
|
|
|
@item run @var{num} [ hush ]
|
@item run @var{num} [ hush ]
|
@cindex @code{run} (Interactive CLI)
|
@cindex @code{run} (Interactive CLI)
|
@cindex running code (Interactive CLI)
|
@cindex running code (Interactive CLI)
|
@cindex executing code (Interactive CLI)
|
@cindex executing code (Interactive CLI)
|
Execute @var{num} instructions. The register/instruction information
|
Execute @var{num} instructions. The register/instruction information
|
is displayed after each instruction, as with the @code{r} command (see
|
is displayed after each instruction, as with the @code{r} command (see
|
above) @emph{unless} @code{hush} is specified.
|
above) @emph{unless} @code{hush} is specified.
|
|
|
@item pr @var{reg} @var{value}
|
@item pr @var{reg} @var{value}
|
@cindex @code{pr} (Interactive CLI)
|
@cindex @code{pr} (Interactive CLI)
|
@cindex patching registers (Interactive CLI)
|
@cindex patching registers (Interactive CLI)
|
@cindex register patching (Interactive CLI)
|
@cindex register patching (Interactive CLI)
|
Patch register @var{reg} with @var{value}.
|
Patch register @var{reg} with @var{value}.
|
|
|
@item dm @var{fromaddr} [ @var{toaddr} ]
|
@item dm @var{fromaddr} [ @var{toaddr} ]
|
@cindex @code{dm} (Interactive CLI)
|
@cindex @code{dm} (Interactive CLI)
|
@cindex displaying memory (Interactive CLI)
|
@cindex displaying memory (Interactive CLI)
|
@cindex memory display (Interactive CLI)
|
@cindex memory display (Interactive CLI)
|
Display memory bytes between @var{fromaddr} and @var{toaddr}. If
|
Display memory bytes between @var{fromaddr} and @var{toaddr}. If
|
@var{toaddr} is not given, 64 bytes are displayed, starting at
|
@var{toaddr} is not given, 64 bytes are displayed, starting at
|
@var{fromaddr}.
|
@var{fromaddr}.
|
|
|
@quotation Caution
|
@quotation Caution
|
The output from this command is broken (a bug). @value{OR1KSIM}
|
The output from this command is broken (a bug). @value{OR1KSIM}
|
attempts to print out 16 bytes per row. However, instead of printing
|
attempts to print out 16 bytes per row. However, instead of printing
|
out the address at the start of each row, it prints the address (of
|
out the address at the start of each row, it prints the address (of
|
the first of the 16 bytes) before @emph{each} byte.
|
the first of the 16 bytes) before @emph{each} byte.
|
@end quotation
|
@end quotation
|
|
|
@item de @var{fromaddr} [ @var{toaddr} ]
|
@item de @var{fromaddr} [ @var{toaddr} ]
|
@cindex @code{dm} (Interactive CLI)
|
@cindex @code{dm} (Interactive CLI)
|
@cindex disassemble (Interactive CLI)
|
@cindex disassemble (Interactive CLI)
|
Disassemble code between @var{fromaddr} and @var{toaddr}. If
|
Disassemble code between @var{fromaddr} and @var{toaddr}. If
|
@var{toaddr} is not given, 16 instructions are disassembled.
|
@var{toaddr} is not given, 16 instructions are disassembled.
|
|
|
The disassembly is entirely numerical, and gives no symbolic
|
The disassembly is entirely numerical, and gives no symbolic
|
information.
|
information.
|
|
|
@item pm @var{addr} @var{value}
|
@item pm @var{addr} @var{value}
|
@cindex @code{pm} (Interactive CLI)
|
@cindex @code{pm} (Interactive CLI)
|
@cindex patching memory (Interactive CLI)
|
@cindex patching memory (Interactive CLI)
|
@cindex memory patching (Interactive CLI)
|
@cindex memory patching (Interactive CLI)
|
Patch the 4 bytes in memory starting at @var{addr} with the 32-bit
|
Patch the 4 bytes in memory starting at @var{addr} with the 32-bit
|
@var{value}.
|
@var{value}.
|
|
|
@item pc @var{value}
|
@item pc @var{value}
|
@cindex @code{pc} (Interactive CLI)
|
@cindex @code{pc} (Interactive CLI)
|
@cindex patching the program counter (Interactive CLI)
|
@cindex patching the program counter (Interactive CLI)
|
@cindex program counter patching (Interactive CLI)
|
@cindex program counter patching (Interactive CLI)
|
Patch the program counter with @var{value}.
|
Patch the program counter with @var{value}.
|
|
|
@item cm @var{fromaddr} @var{toaddr} @var{size}
|
@item cm @var{fromaddr} @var{toaddr} @var{size}
|
@cindex @code{cm} (Interactive CLI)
|
@cindex @code{cm} (Interactive CLI)
|
@cindex copying memory (Interactive CLI)
|
@cindex copying memory (Interactive CLI)
|
@cindex memory copying (Interactive CLI)
|
@cindex memory copying (Interactive CLI)
|
Copy @var{size} bytes in memory from @var{fromaddr} to @var{toaddr}.
|
Copy @var{size} bytes in memory from @var{fromaddr} to @var{toaddr}.
|
|
|
@item break @var{addr}
|
@item break @var{addr}
|
@cindex @code{break} (Interactive CLI)
|
@cindex @code{break} (Interactive CLI)
|
@cindex breakpoint set/clear (Interactive CLI)
|
@cindex breakpoint set/clear (Interactive CLI)
|
@cindex set breakpoint (Interactive CLI)
|
@cindex set breakpoint (Interactive CLI)
|
@cindex clear breakpoint (Interactive CLI)
|
@cindex clear breakpoint (Interactive CLI)
|
@cindex toggle breakpoint (Interactive CLI)
|
@cindex toggle breakpoint (Interactive CLI)
|
Toggle the breakpoint set at @var{addr}.
|
Toggle the breakpoint set at @var{addr}.
|
|
|
@item breaks
|
@item breaks
|
@cindex @code{breaks} (Interactive CLI)
|
@cindex @code{breaks} (Interactive CLI)
|
@cindex breakpoint list (Interactive CLI)
|
@cindex breakpoint list (Interactive CLI)
|
@cindex list breakpoints (Interactive CLI)
|
@cindex list breakpoints (Interactive CLI)
|
List all set breakpoints
|
List all set breakpoints
|
|
|
@item reset
|
@item reset
|
@cindex @code{reset} (Interactive CLI)
|
@cindex @code{reset} (Interactive CLI)
|
@cindex simulator reset (Interactive CLI)
|
@cindex simulator reset (Interactive CLI)
|
@cindex reset the simulator (Interactive CLI)
|
@cindex reset the simulator (Interactive CLI)
|
Reset the simulator. Includes modeling a reset of the processor, so
|
Reset the simulator. Includes modeling a reset of the processor, so
|
execution will restart from the reset vector location, 0x100.
|
execution will restart from the reset vector location, 0x100.
|
|
|
@item hist
|
@item hist
|
@cindex @code{hist} (Interactive CLI)
|
@cindex @code{hist} (Interactive CLI)
|
@cindex execution history (Interactive CLI)
|
@cindex execution history (Interactive CLI)
|
@cindex history of execution (Interactive CLI)
|
@cindex history of execution (Interactive CLI)
|
If saving the execution history has been configured (@pxref{Simulator
|
If saving the execution history has been configured (@pxref{Simulator
|
Behavior, , Simulator Behavior}), display the execution history.
|
Behavior, , Simulator Behavior}), display the execution history.
|
|
|
@item stall
|
@item stall
|
@cindex @code{stall} (Interactive CLI)
|
@cindex @code{stall} (Interactive CLI)
|
@cindex processor stall (Interactive CLI)
|
@cindex processor stall (Interactive CLI)
|
@cindex stall the processor (Interactive CLI)
|
@cindex stall the processor (Interactive CLI)
|
Stall the processor, so that control is passed to the debug unit. When
|
Stall the processor, so that control is passed to the debug unit. When
|
stalled, the processor can execute no instructions. This command is
|
stalled, the processor can execute no instructions. This command is
|
useful when debugging the JTAG interface, used by debuggers such as
|
useful when debugging the JTAG interface, used by debuggers such as
|
GDB.
|
GDB.
|
|
|
@item unstall
|
@item unstall
|
@cindex @code{unstall} (Interactive CLI)
|
@cindex @code{unstall} (Interactive CLI)
|
@cindex processor unstall (Interactive CLI)
|
@cindex processor unstall (Interactive CLI)
|
@cindex unstall the processor (Interactive CLI)
|
@cindex unstall the processor (Interactive CLI)
|
Unstall the processor, so that normal execution can continue. This command is
|
Unstall the processor, so that normal execution can continue. This command is
|
useful when debugging the JTAG interface, used by debuggers such as GDB.
|
useful when debugging the JTAG interface, used by debuggers such as GDB.
|
|
|
@item stats @var{category} | clear
|
@item stats @var{category} | clear
|
@cindex @code{stats} (Interactive CLI)
|
@cindex @code{stats} (Interactive CLI)
|
@cindex simulator statistics (Interactive CLI)
|
@cindex simulator statistics (Interactive CLI)
|
@cindex statistics, simulation (Interactive CLI)
|
@cindex statistics, simulation (Interactive CLI)
|
Print the statistics for the given @var{category}, if available, or
|
Print the statistics for the given @var{category}, if available, or
|
clear if @code{clear} is specified. The categories are:
|
clear if @code{clear} is specified. The categories are:
|
|
|
@table @asis
|
@table @asis
|
|
|
@item 1
|
@item 1
|
Miscellaneous statistics: branch predictions (if branch predictions
|
Miscellaneous statistics: branch predictions (if branch predictions
|
are enabled), branch target cache model (if enabled), cache (if
|
are enabled), branch target cache model (if enabled), cache (if
|
enbaled), MMU (if enabled) and number of addtional load & store
|
enbaled), MMU (if enabled) and number of addtional load & store
|
cycles.
|
cycles.
|
|
|
@xref{Core OpenRISC Configuration, , Configuring the OpenRisc
|
@xref{Core OpenRISC Configuration, , Configuring the OpenRisc
|
Achitectural Components}, for details of how to enable these various
|
Achitectural Components}, for details of how to enable these various
|
features.
|
features.
|
|
|
@item 2
|
@item 2
|
Instruction usage statistics. Requires hazard analysis to be enabled
|
Instruction usage statistics. Requires hazard analysis to be enabled
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
|
|
@item 3
|
@item 3
|
Instruction dependency statistics. Requires hazard analysis to be enabled
|
Instruction dependency statistics. Requires hazard analysis to be enabled
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
|
|
@item 4
|
@item 4
|
Functional unit dependency statistics. Requires hazard analysis to be enabled
|
Functional unit dependency statistics. Requires hazard analysis to be enabled
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
|
|
@item 5
|
@item 5
|
Raw register usage over time. Requires hazard analysis to be enabled
|
Raw register usage over time. Requires hazard analysis to be enabled
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
|
|
@item 6
|
@item 6
|
Store buffer statistics. Requires the store buffer to be enabled
|
Store buffer statistics. Requires the store buffer to be enabled
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
(@pxref{CPU Configuration, ,CPU Configuration}).
|
|
|
@end table
|
@end table
|
|
|
@item info
|
@item info
|
@cindex @code{info} (Interactive CLI)
|
@cindex @code{info} (Interactive CLI)
|
@cindex simulator configuration info (Interactive CLI)
|
@cindex simulator configuration info (Interactive CLI)
|
@cindex configuration info (Interactive CLI)
|
@cindex configuration info (Interactive CLI)
|
Display detailed information about the simulator configuration. This
|
Display detailed information about the simulator configuration. This
|
is quite a lengthy about, because all MMU TLB information is displayed.
|
is quite a lengthy about, because all MMU TLB information is displayed.
|
|
|
@item dv @var{fromaddr} [ @var{toaddr} ] [ @var{module} ]
|
@item dv @var{fromaddr} [ @var{toaddr} ] [ @var{module} ]
|
@cindex @code{dv} (Interactive CLI)
|
@cindex @code{dv} (Interactive CLI)
|
@cindex Verilog memory dump (Interactive CLI)
|
@cindex Verilog memory dump (Interactive CLI)
|
@cindex memory dump, Verilog (Interactive CLI)
|
@cindex memory dump, Verilog (Interactive CLI)
|
Dump the area of memory between @var{fromaddr} and @var{toaddr} as
|
Dump the area of memory between @var{fromaddr} and @var{toaddr} as
|
Verilog code for a synchronous, 23-bit wide SRAM module, named
|
Verilog code for a synchronous, 23-bit wide SRAM module, named
|
@var{module}. If @var{toaddr} is not specified, then 64 bytes are
|
@var{module}. If @var{toaddr} is not specified, then 64 bytes are
|
dumped (as 16 32-bit words). If @var{module} is not specified,
|
dumped (as 16 32-bit words). If @var{module} is not specified,
|
@code{or1k_mem} is used.
|
@code{or1k_mem} is used.
|
|
|
To save to a file, use the redirection function (described after this
|
To save to a file, use the redirection function (described after this
|
table, below).
|
table, below).
|
|
|
@item dh @var{fromaddr} [ @var{toaddr} ]
|
@item dh @var{fromaddr} [ @var{toaddr} ]
|
@cindex @code{dv} (Interactive CLI)
|
@cindex @code{dv} (Interactive CLI)
|
@cindex hexadecimal memory dump (Interactive CLI)
|
@cindex hexadecimal memory dump (Interactive CLI)
|
@cindex memory dump, hexadecimal (Interactive CLI)
|
@cindex memory dump, hexadecimal (Interactive CLI)
|
Dump the area of memory between @var{fromaddr} and @var{toaddr} as
|
Dump the area of memory between @var{fromaddr} and @var{toaddr} as
|
32-bit hex numbers (no @code{0x}, or @code{32'h} prefix). If
|
32-bit hex numbers (no @code{0x}, or @code{32'h} prefix). If
|
@var{toaddr} is not specified, then 64 bytes are dumped (as 16 32-bit
|
@var{toaddr} is not specified, then 64 bytes are dumped (as 16 32-bit
|
words).
|
words).
|
|
|
To save to a file, use the redirection function (described after this
|
To save to a file, use the redirection function (described after this
|
table, below).
|
table, below).
|
|
|
@item setdbch
|
@item setdbch
|
@cindex @code{setdbch} (Interactive CLI)
|
@cindex @code{setdbch} (Interactive CLI)
|
@cindex debug channel toggle (Interactive CLI)
|
@cindex debug channel toggle (Interactive CLI)
|
@cindex toggle debug channels (Interactive CLI)
|
@cindex toggle debug channels (Interactive CLI)
|
Toggle debug channels on/off. @xref{Standalone Simulator, , Standalone
|
Toggle debug channels on/off. @xref{Standalone Simulator, , Standalone
|
Simulator}, for a description of specifying debug channels on the
|
Simulator}, for a description of specifying debug channels on the
|
command line.
|
command line.
|
|
|
@item set @var{section} @var{param} = @var{value}
|
@item set @var{section} @var{param} = @var{value}
|
@cindex @code{set} (Interactive CLI)
|
@cindex @code{set} (Interactive CLI)
|
@cindex configuration parameter setting (Interactive CLI)
|
@cindex configuration parameter setting (Interactive CLI)
|
Set the configuration parameter @var{para} in section @var{section} to
|
Set the configuration parameter @var{para} in section @var{section} to
|
@var{value}. @xref{Configuration, , Configuration}, for details of
|
@var{value}. @xref{Configuration, , Configuration}, for details of
|
configuration parameters and their settings.
|
configuration parameters and their settings.
|
|
|
@item debug
|
@item debug
|
@cindex @code{debug} (Interactive CLI)
|
@cindex @code{debug} (Interactive CLI)
|
@cindex debug mode toggle (Interactive CLI)
|
@cindex debug mode toggle (Interactive CLI)
|
@cindex toggle debug mode (Interactive CLI)
|
@cindex toggle debug mode (Interactive CLI)
|
Toggle the simulator debug mode. @xref{Debug Interface Configuration,
|
Toggle the simulator debug mode. @xref{Debug Interface Configuration,
|
, Debug Interface Configuration}, for information on this parameter.
|
, Debug Interface Configuration}, for information on this parameter.
|
|
|
@quotation Caution
|
@quotation Caution
|
This is effectively enabling or disabling the debug unit. It does not
|
This is effectively enabling or disabling the debug unit. It does not
|
effect the remote GDB debug interface. However using the remote debug
|
effect the remote GDB debug interface. However using the remote debug
|
interface while the debug unit is disabled will lead to undefined
|
interface while the debug unit is disabled will lead to undefined
|
behavior and likely crash @value{OR1KSIM}
|
behavior and likely crash @value{OR1KSIM}
|
@end quotation
|
@end quotation
|
|
|
@item cuc
|
@item cuc
|
@cindex @code{debug} (Interactive CLI)
|
@cindex @code{debug} (Interactive CLI)
|
@cindex Custom Unit Compiler (Interactive CLI)
|
@cindex Custom Unit Compiler (Interactive CLI)
|
Enter the the Custom Unit Compiler command prompt (@pxref{CUC
|
Enter the the Custom Unit Compiler command prompt (@pxref{CUC
|
Configuration, , CUC Configuration}).
|
Configuration, , CUC Configuration}).
|
|
|
@quotation Caution
|
@quotation Caution
|
The CUC must be properly configured, for this to succeed. In
|
The CUC must be properly configured, for this to succeed. In
|
particular a timing file must be available and readable. Otherwise
|
particular a timing file must be available and readable. Otherwise
|
@value{OR1KSIM} will crash.
|
@value{OR1KSIM} will crash.
|
@end quotation
|
@end quotation
|
|
|
@item help
|
@item help
|
@cindex @code{help} (Interactive CLI)
|
@cindex @code{help} (Interactive CLI)
|
@cindex Custom Unit Compiler (Interactive CLI)
|
@cindex Custom Unit Compiler (Interactive CLI)
|
Print out brief information about each command available.
|
Print out brief information about each command available.
|
|
|
@item mprofile [-vh] [-m @var{m}] [-g @var{n}] [-f @var{file}] @var{from} @var{to}
|
@item mprofile [-vh] [-m @var{m}] [-g @var{n}] [-f @var{file}] @var{from} @var{to}
|
@cindex @code{mprofile} (Interactive CLI)
|
@cindex @code{mprofile} (Interactive CLI)
|
@cindex memory profiling utility (Interactive CLI)
|
@cindex memory profiling utility (Interactive CLI)
|
Run the memory profiling utility. This follows the same usage as the
|
Run the memory profiling utility. This follows the same usage as the
|
standalone command (@pxref{Memory Profiling Utility, , Memory
|
standalone command (@pxref{Memory Profiling Utility, , Memory
|
Profiling Utility}).
|
Profiling Utility}).
|
|
|
@item profile [-vhcq] [-g @var{file}]
|
@item profile [-vhcq] [-g @var{file}]
|
@cindex @code{mprofile} (Interactive CLI)
|
@cindex @code{mprofile} (Interactive CLI)
|
@cindex profiling utility (Interactive CLI)
|
@cindex profiling utility (Interactive CLI)
|
@cindex instruction profiling utility (Interactive CLI)
|
@cindex instruction profiling utility (Interactive CLI)
|
Run the instruction profiling utility. This follows the same usage as the
|
Run the instruction profiling utility. This follows the same usage as the
|
standalone command (@pxref{Profiling Utility, , Profiling Utility}).
|
standalone command (@pxref{Profiling Utility, , Profiling Utility}).
|
|
|
@end table
|
@end table
|
|
|
For all commands, it is possible to redirect the output to a file, by
|
For all commands, it is possible to redirect the output to a file, by
|
using the redirection operator, @code{>}.
|
using the redirection operator, @code{>}.
|
|
|
@example
|
@example
|
@var{command} > @var{filename}
|
@var{command} > @var{filename}
|
@end example
|
@end example
|
|
|
This is particularly useful for commands dumping a large amount of
|
This is particularly useful for commands dumping a large amount of
|
output, such as @code{dv}.
|
output, such as @code{dv}.
|
|
|
@quotation Caution
|
@quotation Caution
|
Unfortunately there is a serious bug with the redirection operator. It
|
Unfortunately there is a serious bug with the redirection operator. It
|
does not return output to standard output after the command
|
does not return output to standard output after the command
|
completes. Until this bug is fixed, file redirection should not be
|
completes. Until this bug is fixed, file redirection should not be
|
used.
|
used.
|
@end quotation
|
@end quotation
|
|
|
@node Verification API
|
@node Verification API
|
@chapter Verification API (VAPI)
|
@chapter Verification API (VAPI)
|
|
|
The Verification API (VAPI) provides a TCP/IP interface to allow
|
The Verification API (VAPI) provides a TCP/IP interface to allow
|
components of the simulation to be controlled externally. The
|
components of the simulation to be controlled externally. The
|
interface is polled for new requests on each simulated clock
|
interface is polled for new requests on each simulated clock
|
cycle. Components within the simulator may send responses to such
|
cycle. Components within the simulator may send responses to such
|
requests.
|
requests.
|
|
|
The inteface is an asynchronous duplex protocol. On the request side
|
The inteface is an asynchronous duplex protocol. On the request side
|
it provides for simple commands, known as VAPI IDs (a 32 bit integer),
|
it provides for simple commands, known as VAPI IDs (a 32 bit integer),
|
with a single piece of data (also a 32 bit integer). On the send side,
|
with a single piece of data (also a 32 bit integer). On the send side,
|
it provides for sending a single VAPI ID and data. However there is no
|
it provides for sending a single VAPI ID and data. However there is no
|
explicit command-response structure. Some components just accept
|
explicit command-response structure. Some components just accept
|
requests (e.g. to set values), some just generate sends (to report
|
requests (e.g. to set values), some just generate sends (to report
|
values), and some do both.
|
values), and some do both.
|
|
|
Each component has a base ID (32 bit) and its commands will start from
|
Each component has a base ID (32 bit) and its commands will start from
|
that base ID. This provides a simple partitioning of the command space
|
that base ID. This provides a simple partitioning of the command space
|
amongst components. Request commands will be directed to the component with
|
amongst components. Request commands will be directed to the component with
|
the closest base ID lower than the VAPI ID of the command.
|
the closest base ID lower than the VAPI ID of the command.
|
|
|
Thus if there are two components with base IDs of 0x200 and 0x300, and
|
Thus if there are two components with base IDs of 0x200 and 0x300, and
|
a request with VAPI ID of 0x203 is received, it will be directed to
|
a request with VAPI ID of 0x203 is received, it will be directed to
|
the first component as its command #3.
|
the first component as its command #3.
|
|
|
The results of VAPI interactions are logged (by default in
|
The results of VAPI interactions are logged (by default in
|
@file{vapi.log} unless an alternative is specified in @code{@w{section
|
@file{vapi.log} unless an alternative is specified in @code{@w{section
|
vapi}}).
|
vapi}}).
|
|
|
Currently the following components support VAPI:
|
Currently the following components support VAPI:
|
|
|
@table @asis
|
@table @asis
|
|
|
@item Debug Unit
|
@item Debug Unit
|
@cindex Debug Unit verification (VAPI)
|
@cindex Debug Unit verification (VAPI)
|
@cindex VAPI for Debug Unit
|
@cindex VAPI for Debug Unit
|
Although the Debug Unit can specify a base VAPI ID, it is not used to
|
Although the Debug Unit can specify a base VAPI ID, it is not used to
|
send commands or receive requests.
|
send commands or receive requests.
|
|
|
Instead, if the base VAPI ID is set, all remote JTAG protocol exchanges are
|
Instead, if the base VAPI ID is set, all remote JTAG protocol exchanges are
|
logged in the VAPI log file.
|
logged in the VAPI log file.
|
|
|
@item UART
|
@item UART
|
@cindex UART verification (VAPI)
|
@cindex UART verification (VAPI)
|
@cindex VAPI for UART
|
@cindex VAPI for UART
|
If a base VAPI ID is specified, the UART sends details of any chars or
|
If a base VAPI ID is specified, the UART sends details of any chars or
|
break characters sent, with dteails of the line control register etc
|
break characters sent, with dteails of the line control register etc
|
encoded in the data packet sent.
|
encoded in the data packet sent.
|
|
|
This supports a single VAPI command request, but encodes a sub-command in the
|
This supports a single VAPI command request, but encodes a sub-command in the
|
top 8 bits of the associated data.
|
top 8 bits of the associated data.
|
|
|
@table @code
|
@table @code
|
|
|
@item 0x00
|
@item 0x00
|
@cindex 0x00 UART VAPI sub-command (UART verification)
|
@cindex 0x00 UART VAPI sub-command (UART verification)
|
This stuffs the least significant 8 bits of the data into the serial
|
This stuffs the least significant 8 bits of the data into the serial
|
register of the UART and the next 8 bits into the line control
|
register of the UART and the next 8 bits into the line control
|
register, effectively providing control of the next character to be
|
register, effectively providing control of the next character to be
|
sent or received.
|
sent or received.
|
|
|
@item 0x01
|
@item 0x01
|
@cindex 0x01 UART VAPI sub-command (UART verification)
|
@cindex 0x01 UART VAPI sub-command (UART verification)
|
The divisor latch bytes are set from the least significant 16 bits of
|
The divisor latch bytes are set from the least significant 16 bits of
|
the data.
|
the data.
|
|
|
@item 0x02
|
@item 0x02
|
@cindex 0x02 UART VAPI sub-command (UART verification)
|
@cindex 0x02 UART VAPI sub-command (UART verification)
|
The line control register is set from bits 15-8 of the data.
|
The line control register is set from bits 15-8 of the data.
|
|
|
@item 0x03
|
@item 0x03
|
@cindex 0x03 UART VAPI sub-command (UART verification)
|
@cindex 0x03 UART VAPI sub-command (UART verification)
|
The UART skew is set from the least significant 16 bits of the data
|
The UART skew is set from the least significant 16 bits of the data
|
|
|
@item 0x04
|
@item 0x04
|
@cindex 0x04 UART VAPI sub-command (UART verification)
|
@cindex 0x04 UART VAPI sub-command (UART verification)
|
If the 16th most significant bit of the data is 1, start sending
|
If the 16th most significant bit of the data is 1, start sending
|
breaks, otherwise stop sending breaks. The breaks are sent or cleared
|
breaks, otherwise stop sending breaks. The breaks are sent or cleared
|
after the number of UART clock divider ticks specified by the data
|
after the number of UART clock divider ticks specified by the data
|
(immediately if the data is zero).
|
(immediately if the data is zero).
|
|
|
@end table
|
@end table
|
|
|
@item DMA
|
@item DMA
|
@cindex DMA verification (VAPI)
|
@cindex DMA verification (VAPI)
|
@cindex VAPI for DMA
|
@cindex VAPI for DMA
|
Although the DMA unit supports a base VAPI ID in its configuration
|
Although the DMA unit supports a base VAPI ID in its configuration
|
(@code{@w{section dma}}), no VAPI data is sent, nor VAPI requests
|
(@code{@w{section dma}}), no VAPI data is sent, nor VAPI requests
|
currently implemented.
|
currently implemented.
|
|
|
@item Ethernet
|
@item Ethernet
|
@cindex Ethernet verification (VAPI)
|
@cindex Ethernet verification (VAPI)
|
@cindex VAPI for Ethernet
|
@cindex VAPI for Ethernet
|
The following requests are handled by the Ethernet. Specified
|
The following requests are handled by the Ethernet. Specified
|
symbolically, these are the increments from the base VAPI ID of the
|
symbolically, these are the increments from the base VAPI ID of the
|
Ethernet. At present no implementation is provided behind these VAPI
|
Ethernet. At present no implementation is provided behind these VAPI
|
requests.
|
requests.
|
|
|
@table @code
|
@table @code
|
|
|
@item ETH_VAPI_DATA (0)
|
@item ETH_VAPI_DATA (0)
|
@cindex @code{ETH_VAPI_DATA} (Ethernet verification)
|
@cindex @code{ETH_VAPI_DATA} (Ethernet verification)
|
|
|
@item ETH_VAPI_CTRL (0)
|
@item ETH_VAPI_CTRL (0)
|
@cindex @code{ETH_VAPI_CTRL} (Ethernet verification)
|
@cindex @code{ETH_VAPI_CTRL} (Ethernet verification)
|
|
|
@end table
|
@end table
|
|
|
@item GPIO
|
@item GPIO
|
@cindex GPIO verification (VAPI)
|
@cindex GPIO verification (VAPI)
|
@cindex VAPI for GPIO
|
@cindex VAPI for GPIO
|
If a base VAPI ID is specified, the GPIO sends out on its base VAPI ID
|
If a base VAPI ID is specified, the GPIO sends out on its base VAPI ID
|
(symbolically, GPIO_VAPI_DATA (0) offset from the base VAPI ID) any
|
(symbolically, GPIO_VAPI_DATA (0) offset from the base VAPI ID) any
|
changes in outputs.
|
changes in outputs.
|
|
|
The following requests are handled by the GPIO. Specified
|
The following requests are handled by the GPIO. Specified
|
symbolically, these are the increments from the VAPI base ID of the
|
symbolically, these are the increments from the VAPI base ID of the
|
GPIO.
|
GPIO.
|
|
|
@table @code
|
@table @code
|
|
|
@item GPIO_VAPI_DATA (0)
|
@item GPIO_VAPI_DATA (0)
|
@cindex @code{GPIO_VAPI_DATA} (GPIO verification)
|
@cindex @code{GPIO_VAPI_DATA} (GPIO verification)
|
Set the next input to the commands data field
|
Set the next input to the commands data field
|
|
|
@item GPIO_VAPI_AUX (1)
|
@item GPIO_VAPI_AUX (1)
|
@cindex @code{GPIO_VAPI_AUX} (GPIO verification)
|
@cindex @code{GPIO_VAPI_AUX} (GPIO verification)
|
Set the GPIO auxiliary inputs to the data field
|
Set the GPIO auxiliary inputs to the data field
|
|
|
@item GPIO_VAPI_CLOCK (2)
|
@item GPIO_VAPI_CLOCK (2)
|
@cindex @code{GPIO_VAPI_CLOCK} (GPIO verification)
|
@cindex @code{GPIO_VAPI_CLOCK} (GPIO verification)
|
Add an external GPIO clock trigger of period specified in the data field.
|
Add an external GPIO clock trigger of period specified in the data field.
|
|
|
@item GPIO_VAPI_RGPIO_OE (3)
|
@item GPIO_VAPI_RGPIO_OE (3)
|
@cindex @code{GPIO_VAPI_RGPIO} (GPIO verification)
|
@cindex @code{GPIO_VAPI_RGPIO} (GPIO verification)
|
Set the GPIO output enable to the data field
|
Set the GPIO output enable to the data field
|
|
|
@item GPIO_VAPI_RGPIO_INTE (4)
|
@item GPIO_VAPI_RGPIO_INTE (4)
|
@cindex @code{GPIO_VAPI_INTE} (GPIO verification)
|
@cindex @code{GPIO_VAPI_INTE} (GPIO verification)
|
Set the next interrupt to the data field
|
Set the next interrupt to the data field
|
|
|
@item GPIO_VAPI_RGPIO_PTRIG (5)
|
@item GPIO_VAPI_RGPIO_PTRIG (5)
|
@cindex @code{GPIO_VAPI_PTRIG} (GPIO verification)
|
@cindex @code{GPIO_VAPI_PTRIG} (GPIO verification)
|
Set the next trigger to the data field
|
Set the next trigger to the data field
|
|
|
@item GPIO_VAPI_RGPIO_AUX (6)
|
@item GPIO_VAPI_RGPIO_AUX (6)
|
@cindex @code{GPIO_VAPI_AUX} (GPIO verification)
|
@cindex @code{GPIO_VAPI_AUX} (GPIO verification)
|
Set the next auxiliary input to the data field
|
Set the next auxiliary input to the data field
|
|
|
@item GPIO_VAPI_RGPIO_CTRL (7)
|
@item GPIO_VAPI_RGPIO_CTRL (7)
|
@cindex @code{GPIO_VAPI_CTRL} (GPIO verification)
|
@cindex @code{GPIO_VAPI_CTRL} (GPIO verification)
|
Set th next control input to the data field
|
Set th next control input to the data field
|
|
|
@end table
|
@end table
|
|
|
@end table
|
@end table
|
|
|
@node Code Internals
|
@node Code Internals
|
@chapter A Guide to @value{OR1KSIM} Internals
|
@chapter A Guide to @value{OR1KSIM} Internals
|
|
|
These are notes to help those wanting to extend @value{OR1KSIM}. This
|
These are notes to help those wanting to extend @value{OR1KSIM}. This
|
section assumes the use of a tag file, so file locations of entities'
|
section assumes the use of a tag file, so file locations of entities'
|
definitions are not in general provided. For more on tags, see the
|
definitions are not in general provided. For more on tags, see the
|
Linux manual page for @command{etags}. A tag file can be created
|
Linux manual page for @command{etags}. A tag file can be created
|
with:
|
with:
|
|
|
@example
|
@example
|
make tags
|
make tags
|
@end example
|
@end example
|
|
|
@menu
|
@menu
|
* Coding Conventions::
|
* Coding Conventions::
|
* Global Data Structures::
|
* Global Data Structures::
|
* Concepts::
|
* Concepts::
|
* Internal Debugging::
|
* Internal Debugging::
|
* Regression Testing::
|
* Regression Testing::
|
@end menu
|
@end menu
|
|
|
@node Coding Conventions
|
@node Coding Conventions
|
@section Coding Conventions for @value{OR1KSIM}
|
@section Coding Conventions for @value{OR1KSIM}
|
|
|
This chapter provides some guidelines for coding, to facilitate
|
This chapter provides some guidelines for coding, to facilitate
|
extensions to @value{OR1KSIM}
|
extensions to @value{OR1KSIM}
|
|
|
@table @emph
|
@table @emph
|
|
|
@item GNU Coding Standard
|
@item GNU Coding Standard
|
Code should follow the GNU coding standard for C
|
Code should follow the GNU coding standard for C
|
(@url{http://www.gnu.org/prep/standards/}. If in doubt, put your code
|
(@url{http://www.gnu.org/prep/standards/}. If in doubt, put your code
|
through the @command{indent} program.
|
through the @command{indent} program.
|
|
|
@item @code{#include} headers
|
@item @code{#include} headers
|
All C source code files should include @file{config.h} before any
|
All C source code files should include @file{config.h} before any
|
other file.
|
other file.
|
|
|
This should be followed by inclusion of any system headers (but see
|
This should be followed by inclusion of any system headers (but see
|
the comments about portability and @file{port.h} below) and then by
|
the comments about portability and @file{port.h} below) and then by
|
any @value{OR1KSIM} package headers.
|
any @value{OR1KSIM} package headers.
|
|
|
If @file{port.h} is required, it should be the first package header to
|
If @file{port.h} is required, it should be the first package header to
|
be included after the system headers.
|
be included after the system headers.
|
|
|
All C source code and header files should directly include any system
|
All C source code and header files should directly include any system
|
or package header they depend on, i.e. not rely on any other header
|
or package header they depend on, i.e. not rely on any other header
|
having already included it. The two exceptions are
|
having already included it. The two exceptions are
|
|
|
@enumerate
|
@enumerate
|
@item
|
@item
|
All header files may assume that @file{config.h} has already been
|
All header files may assume that @file{config.h} has already been
|
included.
|
included.
|
|
|
@item
|
@item
|
System headers which impose portability problems should be included by
|
System headers which impose portability problems should be included by
|
using the package header @file{port.h}, rather than the system headers
|
using the package header @file{port.h}, rather than the system headers
|
themselves. This is the case for code requiring
|
themselves. This is the case for code requiring
|
|
|
@itemize @bullet
|
@itemize @bullet
|
|
|
@item
|
@item
|
@code{strndup} (from @file{string.h})
|
@code{strndup} (from @file{string.h})
|
|
|
@item
|
@item
|
Integer types (@code{int@var{n}_t}, @code{uint@var{n}_t}) (from
|
Integer types (@code{int@var{n}_t}, @code{uint@var{n}_t}) (from
|
@file{inttypes.h}).
|
@file{inttypes.h}).
|
|
|
@item
|
@item
|
@code{isblank} (from @file{ctype.h})
|
@code{isblank} (from @file{ctype.h})
|
|
|
@end itemize
|
@end itemize
|
|
|
@end enumerate
|
@end enumerate
|
|
|
@item @code{#include} files once only
|
@item @code{#include} files once only
|
All include files should be protected by @code{#ifndef} to ensure
|
All include files should be protected by @code{#ifndef} to ensure
|
their definitions are only included once. For instance a header file
|
their definitions are only included once. For instance a header file
|
@file{@var{x-y.h}} should surround its contents with:
|
@file{@var{x-y.h}} should surround its contents with:
|
|
|
@example
|
@example
|
#ifndef X_Y__H
|
#ifndef X_Y__H
|
#define X_Y__H
|
#define X_Y__H
|
|
|
<body of the include file>
|
<body of the include file>
|
|
|
#endif /* X_Y__H */
|
#endif /* X_Y__H */
|
@end example
|
@end example
|
|
|
@item Avoid @code{typedef}
|
@item Avoid @code{typedef}
|
The GNU coding style for C does not have a clear way to distinguish
|
The GNU coding style for C does not have a clear way to distinguish
|
between user type name and user variables. For this reason
|
between user type name and user variables. For this reason
|
@code{typedef} should be avoided except for the most ubiquitous user
|
@code{typedef} should be avoided except for the most ubiquitous user
|
defined types. This makes the code much easier to read.
|
defined types. This makes the code much easier to read.
|
|
|
There are some @code{typedef} declarations in the @command{argtable2}
|
There are some @code{typedef} declarations in the @command{argtable2}
|
library and the @acronym{ELF} and @acronym{COFF} headers, because this
|
library and the @acronym{ELF} and @acronym{COFF} headers, because this
|
code is taken from other places.
|
code is taken from other places.
|
|
|
Within @value{OR1KSIM} legacy uses of @code{typedef} have largely been
|
Within @value{OR1KSIM} legacy uses of @code{typedef} have largely been
|
purged, except in the Custom Unit Compiler (@pxref{CUC Configuration,
|
purged, except in the Custom Unit Compiler (@pxref{CUC Configuration,
|
, Custom Unit Compiler (CUC) Configuration}).
|
, Custom Unit Compiler (CUC) Configuration}).
|
|
|
The remaining uses of @code{typedef} occur in two places:
|
The remaining uses of @code{typedef} occur in two places:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
|
|
@item
|
@item
|
@file{port/port.h} defines types to replace those in header files that
|
@file{port/port.h} defines types to replace those in header files that
|
are not available (character functions, string duplication, integer
|
are not available (character functions, string duplication, integer
|
types).
|
types).
|
|
|
@file{cpu/or1k/arch.h} defines types for the key @value{OR1KSIM}
|
@file{cpu/or1k/arch.h} defines types for the key @value{OR1KSIM}
|
entities: addresses (@code{oraddr_t}), unsigned register values
|
entities: addresses (@code{oraddr_t}), unsigned register values
|
(@code{uorreg_t}) and signed register (@code{orreg_t}) values.
|
(@code{uorreg_t}) and signed register (@code{orreg_t}) values.
|
|
|
@end itemize
|
@end itemize
|
|
|
Where new types are defined, they should appear in one of these two
|
Where new types are defined, they should appear in one of these two
|
files as appropriate. @value{OR1KSIM} specific types appearing in
|
files as appropriate. @value{OR1KSIM} specific types appearing in
|
@file{arch.h} should always have the suffix @file{_h}.
|
@file{arch.h} should always have the suffix @file{_h}.
|
|
|
@item Don't begin names with underscore
|
@item Don't begin names with underscore
|
Names beginning with @code{_} are intended to be part of the C
|
Names beginning with @code{_} are intended to be part of the C
|
infrastructure. They should not be used in the simulator code.
|
infrastructure. They should not be used in the simulator code.
|
|
|
@item Keep Non-global top level entities static
|
@item Keep Non-global top level entities static
|
All top level entities (functions, variables), which are not
|
All top level entities (functions, variables), which are not
|
explicitly part of a global interface should be declared static. This
|
explicitly part of a global interface should be declared static. This
|
ensures that unwanted connections are not inadvertently built across
|
ensures that unwanted connections are not inadvertently built across
|
the program.
|
the program.
|
|
|
@item Use of @code{inline}
|
@item Use of @code{inline}
|
Code should not be declared @code{inline}. Modern compilers can work
|
Code should not be declared @code{inline}. Modern compilers can work
|
out for themselves what is best in this respect.
|
out for themselves what is best in this respect.
|
|
|
@item Initialization
|
@item Initialization
|
All data structures should be explicitly initialized. In particular
|
All data structures should be explicitly initialized. In particular
|
code should not rely on static data structures being initialized to
|
code should not rely on static data structures being initialized to
|
zero.
|
zero.
|
|
|
The rationale is that in future static data structures may become
|
The rationale is that in future static data structures may become
|
dynamic. This has been a particular source of bugs in @value{OR1KSIM}
|
dynamic. This has been a particular source of bugs in @value{OR1KSIM}
|
historically.
|
historically.
|
|
|
A specific case is with new peripherals, which should always include a
|
A specific case is with new peripherals, which should always include a
|
@code{start} function to pre-initialize all configuration parameters
|
@code{start} function to pre-initialize all configuration parameters
|
to sensible defaults
|
to sensible defaults
|
|
|
@item Configuration Validation
|
@item Configuration Validation
|
All configuration values should be validated, preferably when
|
All configuration values should be validated, preferably when
|
encountered, if not when the @code{section} is closed, or otherwise
|
encountered, if not when the @code{section} is closed, or otherwise
|
at run time when the parameter is first used.
|
at run time when the parameter is first used.
|
|
|
@end table
|
@end table
|
|
|
@node Global Data Structures
|
@node Global Data Structures
|
@section Global Data Structures
|
@section Global Data Structures
|
|
|
@table @code
|
@table @code
|
|
|
@item config
|
@item config
|
@cindex configuration global structure
|
@cindex configuration global structure
|
@vindex config
|
@vindex config
|
The global variable @code{config} of type @code{struct config} holds
|
The global variable @code{config} of type @code{struct config} holds
|
the configuration data for some of the @value{OR1KSIM} components which
|
the configuration data for some of the @value{OR1KSIM} components which
|
are always present. At present the components are:
|
are always present. At present the components are:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
|
|
@item
|
@item
|
@vindex config.sim
|
@vindex config.sim
|
The simulator defined in @code{@w{section sim}} (@pxref{Simulator
|
The simulator defined in @code{@w{section sim}} (@pxref{Simulator
|
Configuration, , Simulator Configuration}).
|
Configuration, , Simulator Configuration}).
|
|
|
@item
|
@item
|
@vindex config.vapi
|
@vindex config.vapi
|
The Verification API (VAPI) defined in @code{@w{section vapi}}
|
The Verification API (VAPI) defined in @code{@w{section vapi}}
|
(@pxref{Verification API Configuration, , Verification API (VAPI)
|
(@pxref{Verification API Configuration, , Verification API (VAPI)
|
Configuration}).
|
Configuration}).
|
|
|
@item
|
@item
|
@vindex config.cuc
|
@vindex config.cuc
|
The Custom Unit Compiler (CUC), defined in @code{@w{section cuc}}
|
The Custom Unit Compiler (CUC), defined in @code{@w{section cuc}}
|
(@pxref{CUC Configuration, , Custom Unit Compiler (CUC)
|
(@pxref{CUC Configuration, , Custom Unit Compiler (CUC)
|
Configuration}).
|
Configuration}).
|
|
|
@item
|
@item
|
@vindex config.cpu
|
@vindex config.cpu
|
The CPU, defined in @code{@w{section cpu}} (@pxref{CPU Configuration,
|
The CPU, defined in @code{@w{section cpu}} (@pxref{CPU Configuration,
|
, CPU Configuration}).
|
, CPU Configuration}).
|
|
|
@item
|
@item
|
@vindex config.dc
|
@vindex config.dc
|
The data cache (but not the instruction cache), defined in
|
The data cache (but not the instruction cache), defined in
|
@code{@w{section dc}} (@pxref{Cache Configuration, , Cache
|
@code{@w{section dc}} (@pxref{Cache Configuration, , Cache
|
Configuration}).
|
Configuration}).
|
|
|
@item
|
@item
|
@vindex config.pm
|
@vindex config.pm
|
The power management unit, defined in @code{@w{section pm}}
|
The power management unit, defined in @code{@w{section pm}}
|
(@pxref{Power Management Configuration, , Power Management
|
(@pxref{Power Management Configuration, , Power Management
|
Configuration}).
|
Configuration}).
|
|
|
@item
|
@item
|
@vindex config.pic
|
@vindex config.pic
|
The programmable interrupt controller, defined in @code{@w{section pic}}
|
The programmable interrupt controller, defined in @code{@w{section pic}}
|
(@pxref{Interrupt Configuration, , Interrupt Configuration}).
|
(@pxref{Interrupt Configuration, , Interrupt Configuration}).
|
|
|
@item
|
@item
|
@vindex config.bpb
|
@vindex config.bpb
|
Branch prediciton, defined in @code{@w{section bpb}} (@pxref{Branch
|
Branch prediciton, defined in @code{@w{section bpb}} (@pxref{Branch
|
Prediction Configuration, , Branch Prediction Configuration}).
|
Prediction Configuration, , Branch Prediction Configuration}).
|
|
|
@item
|
@item
|
@vindex config.debug
|
@vindex config.debug
|
The debug unit, defined in @code{@w{section debug}} (@pxref{Debug
|
The debug unit, defined in @code{@w{section debug}} (@pxref{Debug
|
Interface Configuration, , Debug Interface Configuration}).
|
Interface Configuration, , Debug Interface Configuration}).
|
|
|
@end itemize
|
@end itemize
|
|
|
This struct is made of a collection of structs, one for each
|
This struct is made of a collection of structs, one for each
|
component. For example the simulator configuration is held in
|
component. For example the simulator configuration is held in
|
@code{config.sim}.
|
@code{config.sim}.
|
|
|
@item config
|
@item config
|
@cindex configuration dynamic structure
|
@cindex configuration dynamic structure
|
@vindex sections
|
@vindex sections
|
This is a linked list of data structures holding configuration data
|
This is a linked list of data structures holding configuration data
|
for all sections which are not held in the main @code{config} data
|
for all sections which are not held in the main @code{config} data
|
structure. In general these are components (such as peripherals and
|
structure. In general these are components (such as peripherals and
|
memory) which may occur multiple times. However it also handles some
|
memory) which may occur multiple times. However it also handles some
|
architectural components which may occur only once, such as the memory
|
architectural components which may occur only once, such as the memory
|
management units, the instruction cache, the interrupt controller and
|
management units, the instruction cache, the interrupt controller and
|
branch prediction.
|
branch prediction.
|
|
|
@item runtime
|
@item runtime
|
@cindex runtime global structure
|
@cindex runtime global structure
|
@vindex runtime
|
@vindex runtime
|
The global variable @code{runtime} of type @code{struct runtime} holds
|
The global variable @code{runtime} of type @code{struct runtime} holds
|
all the runtime information about the simulation. To access this
|
all the runtime information about the simulation. To access this
|
variable, @file{sim-config.h} must be included.
|
variable, @file{sim-config.h} must be included.
|
|
|
@vindex runtime.cpu
|
@vindex runtime.cpu
|
@vindex runtime.vapi
|
@vindex runtime.vapi
|
@vindex runtime.cuc
|
@vindex runtime.cuc
|
This struct is itself made of 3 other structs, @code{cpu} (for CPU run
|
This struct is itself made of 3 other structs, @code{cpu} (for CPU run
|
time state), @code{vapi} (for Verification API state) and @code{cuc}
|
time state), @code{vapi} (for Verification API state) and @code{cuc}
|
(for Custom Unit Compiler state).
|
(for Custom Unit Compiler state).
|
|
|
@end table
|
@end table
|
|
|
@node Concepts
|
@node Concepts
|
@section Concepts
|
@section Concepts
|
|
|
@table @emph
|
@table @emph
|
|
|
@anchor{Output Redirection}
|
@anchor{Output Redirection}
|
@item Output Redirection
|
@item Output Redirection
|
@cindex output rediretion
|
@cindex output rediretion
|
@vindex runtime.cpu.fout
|
@vindex runtime.cpu.fout
|
The current output stream is held in @code{runtime.cpu.fout}. Output
|
The current output stream is held in @code{runtime.cpu.fout}. Output
|
should be explicitly written to this stream, or may use the
|
should be explicitly written to this stream, or may use the
|
@code{PRINTF} macro, which will write its arguments to this output stream.
|
@code{PRINTF} macro, which will write its arguments to this output stream.
|
|
|
@item Reset Hooks
|
@item Reset Hooks
|
@cindex reset hooks
|
@cindex reset hooks
|
@findex reg_sim_reset
|
@findex reg_sim_reset
|
Any peripheral may register a routine to be called when the the
|
Any peripheral may register a routine to be called when the the
|
processor is reset by calling @code{reg_sim_reset}, providing a
|
processor is reset by calling @code{reg_sim_reset}, providing a
|
function and pointer to a data structure as arguments. On reset that
|
function and pointer to a data structure as arguments. On reset that
|
function will be called with the data stucture pointer as argument.
|
function will be called with the data stucture pointer as argument.
|
|
|
@anchor{Interrupts Internal}
|
@anchor{Interrupts Internal}
|
@item Interrupts
|
@item Interrupts
|
@cindex interrupts
|
@cindex interrupts
|
@findex report_interrupt
|
@findex report_interrupt
|
@findex clear_interrupt
|
@findex clear_interrupt
|
@findex mtspr
|
@findex mtspr
|
An internal peripheral can model the effect of an interrupt being
|
An internal peripheral can model the effect of an interrupt being
|
asserted by calling @code{report_interrupt}. This is used for both edge
|
asserted by calling @code{report_interrupt}. This is used for both edge
|
and level sensitive interrupts.
|
and level sensitive interrupts.
|
|
|
The effect is to set the corresponding bit in the PICSR SPR and to queue
|
The effect is to set the corresponding bit in the PICSR SPR and to queue
|
an interrupt exception to take place after the current instruction
|
an interrupt exception to take place after the current instruction
|
completes execution.
|
completes execution.
|
|
|
Externally, the different interrupts require different mechanisms for
|
Externally, the different interrupts require different mechanisms for
|
clearing. Level sensitive interrupts should be cleared by deasserting
|
clearing. Level sensitive interrupts should be cleared by deasserting
|
the interrupt line, edge sensitive interrupts by clearing the
|
the interrupt line, edge sensitive interrupts by clearing the
|
corresponding bit in the PICSR SPR.
|
corresponding bit in the PICSR SPR.
|
|
|
Internally this amounts to the same thing (clearing the PICSPR bit), so
|
Internally this amounts to the same thing (clearing the PICSPR bit), so
|
a single function is provided, @code{clear_interrupt}. Note however that
|
a single function is provided, @code{clear_interrupt}. Note however that
|
when level sensitive interrupts are configured, PICSR is read only, and
|
when level sensitive interrupts are configured, PICSR is read only, and
|
can only be cleared by calling @code{clear_interrupt}. Using the two
|
can only be cleared by calling @code{clear_interrupt}. Using the two
|
functions provided will ensure the peripheral works correctly whichever
|
functions provided will ensure the peripheral works correctly whichever
|
type of interrupt is used.
|
type of interrupt is used.
|
|
|
@quotation Note
|
@quotation Note
|
Until an interrupt is cleared, all subsequent interrupts are ignored
|
Until an interrupt is cleared, all subsequent interrupts are ignored
|
with a warning.
|
with a warning.
|
@end quotation
|
@end quotation
|
|
|
@end table
|
@end table
|
|
|
@node Internal Debugging
|
@node Internal Debugging
|
@section Internal Debugging
|
@section Internal Debugging
|
@cindex internal debugging
|
@cindex internal debugging
|
|
|
The function @code{debug} is like @code{printf}, but with an extra
|
The function @code{debug} is like @code{printf}, but with an extra
|
first argument, which is the debug level. If the debug level specified
|
first argument, which is the debug level. If the debug level specified
|
in the simulator configuration (@pxref{Simulator Behavior, , Simulator
|
in the simulator configuration (@pxref{Simulator Behavior, , Simulator
|
Behavior}) is greater than or equal to this value, the remaining
|
Behavior}) is greater than or equal to this value, the remaining
|
arguments are printed to the current output stream (@pxref{Output
|
arguments are printed to the current output stream (@pxref{Output
|
Redirection, , Output Redirection}).
|
Redirection, , Output Redirection}).
|
|
|
@node Regression Testing
|
@node Regression Testing
|
@section Regression Testing
|
@section Regression Testing
|
@cindex regression testing
|
@cindex regression testing
|
@cindex testing
|
@cindex testing
|
@value{OR1KSIM} now includes a regression test suite for both standalone
|
@value{OR1KSIM} now includes a regression test suite for both standalone
|
and library usage as described earlier (@pxref{Build and Install,
|
and library usage as described earlier (@pxref{Build and Install,
|
, Building and Installing}). Running the tests requires that the
|
, Building and Installing}). Running the tests requires that the
|
OpenRISC toolchain and DejaGNU are both installed.
|
OpenRISC toolchain and DejaGNU are both installed.
|
|
|
Tests are written using @command{expect}, a derivative of TCL.
|
Tests are written using @command{expect}, a derivative of TCL.
|
Documentation of DejaGnu, @command{expect} and TCL are freely available
|
Documentation of DejaGnu, @command{expect} and TCL are freely available
|
on the Web. The Embecosm Application Note 8, @cite{Howto: Using DejaGnu
|
on the Web. The Embecosm Application Note 8, @cite{Howto: Using DejaGnu
|
for Testing: A Simple Introduction}
|
for Testing: A Simple Introduction}
|
(@uref{http://www.embecosm.com/download/ean8.html}) provides a concise
|
(@uref{http://www.embecosm.com/download/ean8.html}) provides a concise
|
introduction.
|
introduction.
|
|
|
All test code is found in the @file{testsuite} directory. The key
|
All test code is found in the @file{testsuite} directory. The key
|
files and directories used are as follows.
|
files and directories used are as follows.
|
|
|
@table @code
|
@table @code
|
@item global-conf.exp
|
@item global-conf.exp
|
@cindex DejaGnu configuration
|
@cindex DejaGnu configuration
|
This is the global DejaGNU configuration file used to set up parameters
|
This is the global DejaGNU configuration file used to set up parameters
|
common to all tests. If the user has the environment varialbe
|
common to all tests. If the user has the environment varialbe
|
@env{DEJAGNU} defined, it will be used instead, but this is not
|
@env{DEJAGNU} defined, it will be used instead, but this is not
|
recommended.
|
recommended.
|
|
|
@item Makefile.am
|
@item Makefile.am
|
@cindex test make file
|
@cindex test make file
|
@cindex make file for tests
|
@cindex make file for tests
|
This is the top level @command{automake} file for the testsuite. The
|
This is the top level @command{automake} file for the testsuite. The
|
only changes likely to be needed here is additional local cleanup of
|
only changes likely to be needed here is additional local cleanup of
|
files created by new tests.
|
files created by new tests.
|
|
|
@item README
|
@item README
|
@cindex test README
|
@cindex test README
|
This contains details of all the tests
|
This contains details of all the tests
|
|
|
@item config
|
@item config
|
@cindex DejaGnu board configurations
|
@cindex DejaGnu board configurations
|
This contains DejaGnu board configurations. Since the tests are
|
This contains DejaGnu board configurations. Since the tests are
|
generally run on a Unix host, this should just contain @file{Unix.exp}.
|
generally run on a Unix host, this should just contain @file{Unix.exp}.
|
|
|
@item lib
|
@item lib
|
@cindex DejaGnu tool specific configuration
|
@cindex DejaGnu tool specific configuration
|
This contains DejaGnu tool specific configurations. ``Tool'' has a
|
This contains DejaGnu tool specific configurations. ``Tool'' has a
|
specific meaning in DejaGNU, referring just to a grouping of tests. In
|
specific meaning in DejaGNU, referring just to a grouping of tests. In
|
this case there are two such ``tools'', ``or1ksim'' and ``libsim''
|
this case there are two such ``tools'', ``or1ksim'' and ``libsim''
|
for tests of the standalone tool and tests of the library.
|
for tests of the standalone tool and tests of the library.
|
|
|
Corresponding to this, there are two tool specific configuration files,
|
Corresponding to this, there are two tool specific configuration files,
|
@file{or1ksim.exp} and @file{libsim.exp}. These contain @command{expect}/TCL
|
@file{or1ksim.exp} and @file{libsim.exp}. These contain @command{expect}/TCL
|
procedures for common use among the tests.
|
procedures for common use among the tests.
|
|
|
@item libsim.tests
|
@item libsim.tests
|
@itemx or1ksim.tests
|
@itemx or1ksim.tests
|
@cindex DejaGNU tests directories
|
@cindex DejaGNU tests directories
|
These are the directories of tests of the @value{OR1KSIM} library. They
|
These are the directories of tests of the @value{OR1KSIM} library. They
|
also include @value{OR1KSIM} configuration files and each has a
|
also include @value{OR1KSIM} configuration files and each has a
|
@file{Makefile.am} file. @file{Makefile.am} should be updated whenever
|
@file{Makefile.am} file. @file{Makefile.am} should be updated whenever
|
files are added to this directory, to ensure they are included in the
|
files are added to this directory, to ensure they are included in the
|
distribution.
|
distribution.
|
|
|
@item test-code
|
@item test-code
|
@cindex host test code
|
@cindex host test code
|
@cindex test code for host
|
@cindex test code for host
|
These are all the test programs to be compiled on the host (each in its
|
These are all the test programs to be compiled on the host (each in its
|
own directory). In general these are programs to support testing of the
|
own directory). In general these are programs to support testing of the
|
library, and build various programs linking in the library.
|
library, and build various programs linking in the library.
|
|
|
@item test-code
|
@item test-code
|
@cindex target test code
|
@cindex target test code
|
@cindex test code for target
|
@cindex test code for target
|
These are all the test programs to be compiled with the OpenRISC tool
|
These are all the test programs to be compiled with the OpenRISC tool
|
chain to run with either standalone @value{OR1KSIM} or the library.
|
chain to run with either standalone @value{OR1KSIM} or the library.
|
This directory includes its own @file{configure.ac}, since it must set
|
This directory includes its own @file{configure.ac}, since it must set
|
up a separate tool chain based on the target, not the host.
|
up a separate tool chain based on the target, not the host.
|
|
|
@end table
|
@end table
|
|
|
To add a new test needs the following steps.
|
To add a new test needs the following steps.
|
|
|
@itemize @bullet
|
@itemize @bullet
|
|
|
@item
|
@item
|
Put new host C code in its own directory within @file{test-code}. Add
|
Put new host C code in its own directory within @file{test-code}. Add
|
the directory to the existing @file{Makefile.am} in the @file{test-code}
|
the directory to the existing @file{Makefile.am} in the @file{test-code}
|
directory and create a @file{Makefile.am} in the new directory to drive
|
directory and create a @file{Makefile.am} in the new directory to drive
|
building the test program(s). Don't forget to add the new
|
building the test program(s). Don't forget to add the new
|
@file{Makefile} to the top level @file{configure.ac} so it gets
|
@file{Makefile} to the top level @file{configure.ac} so it gets
|
generated. Not all tests require code here.
|
generated. Not all tests require code here.
|
|
|
@item
|
@item
|
Put new target C code in its own directory within @file{test-code-or1k}.
|
Put new target C code in its own directory within @file{test-code-or1k}.
|
Once again modify & create @file{Makefile.am}. This time modify the
|
Once again modify & create @file{Makefile.am}. This time modify the
|
@file{configure.ac} in the @file{test-code-or1k} so the @file{Makefile}
|
@file{configure.ac} in the @file{test-code-or1k} so the @file{Makefile}
|
gets generated. The existing programs provide examples to start from,
|
gets generated. The existing programs provide examples to start from,
|
including custom linker scripts where needed.
|
including custom linker scripts where needed.
|
|
|
@item
|
@item
|
Add one or more tests and configuration files to the relevant ``tool''
|
Add one or more tests and configuration files to the relevant ``tool''
|
test directory. Use the existing tests as templates. They make heavy
|
test directory. Use the existing tests as templates. They make heavy
|
use of the @command{expect}/TCL procedures in the @file{config}
|
use of the @command{expect}/TCL procedures in the @file{config}
|
directory to facilitate driving the tests.
|
directory to facilitate driving the tests.
|
|
|
@end itemize
|
@end itemize
|
|
|
@node GNU Free Documentation License
|
@node GNU Free Documentation License
|
@chapter GNU Free Documentation License
|
@chapter GNU Free Documentation License
|
@cindex license for @value{OR1KSIM}
|
@cindex license for @value{OR1KSIM}
|
|
|
@include fdl-1.2.texi
|
@include fdl-1.2.texi
|
|
|
@node Index
|
@node Index
|
|
|
@unnumbered Index
|
@unnumbered Index
|
|
|
@printindex cp
|
@printindex cp
|
|
|
@bye
|
@bye
|
|
|