OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

Compare Revisions

  • This comparison shows the changes necessary to convert path 
    /openrisc/trunk/or1ksim/doc
    from Rev 80 to Rev 82
    ↔ Reverse comparison
  •

Rev 80 → Rev 82

/or1ksim.info
1,4 → 1,4
This is ../../doc/or1ksim.info, produced by makeinfo version 4.11 from
This is ../../doc/or1ksim.info, produced by makeinfo version 4.13 from
../../doc/or1ksim.texi.
 
INFO-DIR-SECTION Embedded development
64,7 → 64,7
Unpack the software and create a _separate_ directory in which to build
it:
 
tar jxf or1ksim-0.3.0.tar.bz2
tar jxf or1ksim-0.3.1-2010-04-20.tar.bz2
mkdir builddir_or1ksim
cd builddir_or1ksim
 
78,23 → 78,23
directory.
 
The most significant argument is `--target', which should specify the
OpenRISC 1000 32-bit architecture. If this argument is omitted, it will
OpenRISC 1000 32-bit architecture. If this argument is omitted, it will
default to OpenRISC 1000 32-bit with a warning
 
../or1ksim-0.3.0/configure --target=or32-uclinux ...
../or1ksim-0.3.1-2010-04-20/configure --target=or32-uclinux ...
 
There are several other options available, many of which are standard
to GNU `configure' scripts. Use `configure --help' to see all the
options. The most useful is `--prefix' to specify a directory for
to GNU `configure' scripts. Use `configure --help' to see all the
options. The most useful is `--prefix' to specify a directory for
installation of the tools.
 
A number of Or1ksim features in the simulator do require enabling at
configuration. These include
configuration. These include
 
`--enable-profiling'
`--disable-profiling'
If enabled, Or1ksim is compiled for profiling with `gprof'. This
is disabled by default. Only really of value for developers of
If enabled, Or1ksim is compiled for profiling with `gprof'. This
is disabled by default. Only really of value for developers of
Or1ksim.
 
`--enable-execution=simple'
107,15 → 107,15
Build the original simple interpreting simulator
 
`--enable-execution=complex'
Build a more complex interpreting simulator. Experiments
suggest this is 50% faster than the simple simulator. This is
the default.
Build a more complex interpreting simulator. Experiments
suggest this is 50% faster than the simple simulator. This
is the default.
 
`--enable-execution=dynamic'
Build a dynamically compiling simulator. This is the way many
modern ISS are built. This represents a work in progress.
Currently Or1ksim will compile, but segfaults if configured
with this option.
Build a dynamically compiling simulator. This is the way
many modern ISS are built. This represents a work in
progress. Currently Or1ksim will compile, but segfaults if
configured with this option.
 
 
The default is `--enable-execution=complex'.
124,8 → 124,8
`--disable-ethphy'
If enabled, this option allows the Ethernet to be simulated by
connecting via a socket (the alternative reads and writes, from
and to files). This must then be configured using the relevant
fields in the `ethernet' section of the configuration file. *Note
and to files). This must then be configured using the relevant
fields in the `ethernet' section of the configuration file. *Note
Ethernet Configuration: Ethernet Configuration.
 
The default is for this to be disabled.
133,13 → 133,13
`--enable-range-stats'
`--disable-range-stats'
If enabled, this option allows statistics to be collected to
analyse register access over time. The default is for this to be
analyse register access over time. The default is for this to be
disabled.
 
`--enable-ov-flag'
`--disable-ov-flag'
If enabled, this option causes instructions to set the overflow
flag. The instructions affected by this are `l.add', `l.addc',
flag. The instructions affected by this are `l.add', `l.addc',
`l.addi', `l.and', `l.andi', `l.div', `l.divu', `l.mul', `l.muli',
`l.or', `l.ori', `l.sll', `l.slli', `l.srl', `l.srli', `l.sra',
`l.srai', `l.sub', `l.xor' and `l.xori'.
147,14 → 147,14
The default is for this to be disabled.
 
Caution: This appears a very dangerous option, to the extent
of arguably being a bug. Whether or not flags are set is part
of the OpenRISC 1000 architectural specification. Within the
above list, the arithmetic instructions (`l.add', `l.addc',
`l.addi', `l.div', `l.divu', `l.mul', `l.muli' and `l.sub'),
together with `l.addic' which is missed out, set the overflow
flag. All the others (`l.and', `l.andi', `l.or', `l.ori',
`l.sll', `l.slli', `l.srl', `l.srli', `l.sra', `l.srai',
`l.xor' and `l.xori') do not.
of arguably being a bug. Whether or not flags are set is
part of the OpenRISC 1000 architectural specification.
Within the above list, the arithmetic instructions (`l.add',
`l.addc', `l.addi', `l.div', `l.divu', `l.mul', `l.muli' and
`l.sub'), together with `l.addic' which is missed out, set
the overflow flag. All the others (`l.and', `l.andi',
`l.or', `l.ori', `l.sll', `l.slli', `l.srl', `l.srli',
`l.sra', `l.srai', `l.xor' and `l.xori') do not.
 
Thus it is impossible to get correct behavior whichever way
this option is set.
162,7 → 162,7
`--enable-arith-flag'
`--disable-arith-flag'
If enabled, this option causes instructions to set the flag (`F'
bit) in the supervision register. The instructions affected by
bit) in the supervision register. The instructions affected by
this are `l.add', `l.addc', `l.addi', `l.and' and `l.andi'.
 
The default is for this to be disabled.
173,7 → 173,7
the instructions early in the alphabet?
 
Whether or not flags are set is part of the OpenRISC 1000
architectural specification. The only flags which should set
architectural specification. The only flags which should set
this are the "set flag" instructions: `l.sfeq', `l.sfeqi',
`l.sfges', `l.sfgesi', `l.sfgeu', `l.sfgeui', `l.sfgts',
`l.sfgtsi', `l.sfgtu', `l.sfgtui', `l.sfles', `l.sflesi',
190,11 → 190,20
`--enable-debug'
`--disable-debug'
This is a feature of the Argtable2 package used to process
arguments. If enabled, some debugging features are turned on in
Argtable2. It is provided for completeness, but there is no reason
why this feature should ever be needed by any Or1ksim user.
arguments. If enabled, some debugging features are turned on in
Argtable2. It is provided for completeness, but there is no
reason why this feature should ever be needed by any Or1ksim user.
 
`--enable-all-tests'
`--disable-all-tests'
Some of the tests (at the time of writing just one) will not
compile without error. If enabled with this flag, all test
programs will be compiled with `make check'.
 
This flag is intended for those working on the test package, who
wish to get the missing test(s) working.
 
 

File: or1ksim.info, Node: Build and Install, Next: Known Issues, Prev: Configuring the Build, Up: Installation
 
201,9 → 210,17
1.3 Building and Installing
===========================
 
The tool is then built with:
Build the tool with:
 
make all
 
If you have the OpenRISC tool chain and DejaGNU installed, you can
verify the tool as follows (otherwise omit this step):
 
make check
 
Install the tool with:
 
make install
 
This will install the three variations of the Or1ksim tool,
225,24 → 242,25
1.4 Known Problems and Issues
=============================
 
The following problems and issues are known about with Or1ksim 0.3.0.
The OpenRISC tracker may be used to see the current state of these
issues and to raise new problems and feature requests. It may be found
at `http://www.opencores.org/ptracker.cgi/view/or1k/398'.
The following problems and issues are known about with Or1ksim
0.3.1-2010-04-20. The OpenRISC tracker may be used to see the current
state of these issues and to raise new problems and feature requests.
It may be found at
`http://www.opencores.org/ptracker.cgi/view/or1k/398'.
 
* The Supervision Register Little Endian Enable (LEE) bit is
ignored. Or1ksim can be built for either little endian or big
ignored. Or1ksim can be built for either little endian or big
endian use, but that behavior cannot be changed dynamically.
 
* The NPC is a read/write register, but after being written it
clears the pipeline. This means that if the processor is stalled,
clears the pipeline. This means that if the processor is stalled,
the value should subsequently read back as 0, until the processor
is unstalled and able to refill its pipeline. By default Or1ksim
is unstalled and able to refill its pipeline. By default Or1ksim
always reports back the value of NPC, even when it has been
written while stalled.
 
There is now an option, `--strict-npc', which will enforce this
behavior. At some stage in the future it will become the default
behavior. At some stage in the future it will become the default
behavior, but for now it is an option, since its use will break
GDB.
 
252,18 → 270,18
corresponds to a particular access).
 
* Or1ksim allows the processor to be stalled (from the command
line), even if there is no debugger present. This seems to be a
line), even if there is no debugger present. This seems to be a
meaningless operation.
 
* Or1ksim is not reentrant, so a program cannot instantiate multiple
instances using the library. This is clearly a problem when
considering multi-core applications. However it stems from the
original design, and can only be fixed by a complete rewrite. The
instances using the library. This is clearly a problem when
considering multi-core applications. However it stems from the
original design, and can only be fixed by a complete rewrite. The
entire source code uses static global constants liberally!
 
* There is no support for floating point instructions currently in
Or1ksim. However this is a work in progress and should be
available in the near future.
Or1ksim. However this is a work in progress and should be
available in the future.
 
 

290,8 → 308,8
or32-uclinux-sim [-vhi] [-f FILE] [--nosrv] [--srv=[N]] [-d STR]
[--enable-profile] [--enable-mprofile] [FILE]
 
Many of the options have both a short and a long form. For example `-h'
or `--help'.
Many of the options have both a short and a long form. For example
`-h' or `--help'.
 
`-v'
`--version'
305,30 → 323,30
`--file FILE'
Read configuration commands from the specified file, looking first
in the current directory, and otherwise in the `$HOME/.or1k'
directory. If this argument is not specified, the file `sim.cfg'
in those two locations is used. Failure to find the file is a fatal
error. *Note Configuration: Configuration, for detailed information
on configuring Or1ksim.
directory. If this argument is not specified, the file `sim.cfg'
in those two locations is used. Failure to find the file is a
fatal error. *Note Configuration: Configuration, for detailed
information on configuring Or1ksim.
 
`--nosrv'
Do not start up the debug server. This overrides any setting
specified in the configuration file. This option may not be
specified with `--srv'. If it is, a rude message is printed and the
`--nosrv' option is ignored.
Do not start up the debug server. This overrides any setting
specified in the configuration file. This option may not be
specified with `--srv'. If it is, a rude message is printed and
the `--nosrv' option is ignored.
 
`--srv'
 
`--srv=N'
Start up the debug server. If the parameter, N, is specified, use
Start up the debug server. If the parameter, N, is specified, use
that as the TCP/IP port for the server, otherwise a random value
from the private port range (41920-65535) will be used. This option
may not be specified with `--nosrv'. If it is, a rude message is
printed and the `--nosrv' option is ignored.
from the private port range (41920-65535) will be used. This
option may not be specified with `--nosrv'. If it is, a rude
message is printed and the `--nosrv' option is ignored.
 
`-d=CONFIG_STRING'
`--debug-config=CONFIG_STRING'
Enable selected debug messages in Or1ksim. This parameter is for
use by developers only, and is not covered further here. See the
Enable selected debug messages in Or1ksim. This parameter is for
use by developers only, and is not covered further here. See the
source code for more details.
 
`-i'
337,15 → 355,15
 
`--strict-npc'
In real hardware, setting the next program counter (NPC, SPR 16),
flushes the processor pipeline. The consequence of this is that
until the pipeline refills, reading the NPC will return zero. This
is typically the case when debugging, since the processor is
flushes the processor pipeline. The consequence of this is that
until the pipeline refills, reading the NPC will return zero.
This is typically the case when debugging, since the processor is
stalled.
 
Historically, Or1ksim has always returned the value of the NPC,
irrespective of when it is changed. If the `--strict-npc' option is
used, then Or1ksim will mirror real hardware more accurately. If
the NPC is changed while the processor is stalled, subsequent
irrespective of when it is changed. If the `--strict-npc' option
is used, then Or1ksim will mirror real hardware more accurately.
If the NPC is changed while the processor is stalled, subsequent
reads of its value will return 0 until the processor is unstalled.
 
This is not currently the default behavior, since tools such as
365,14 → 383,14
2.2 Profiling Utility
=====================
 
This utility analyses instruction profile data generated by Or1ksim. It
may be invoked as a standalone command, or from the Or1ksim CLI. The
general form the standalone command is:
This utility analyses instruction profile data generated by Or1ksim.
It may be invoked as a standalone command, or from the Or1ksim CLI.
The general form the standalone command is:
 
or32-uclinux-profile [-vhcq] [-g=FILE]
 
Many of the options have both a short and a long form. For example `-h'
or `--help'.
Many of the options have both a short and a long form. For example
`-h' or `--help'.
 
`-v'
`--version'
393,7 → 411,7
 
`-g=FILE'
`--generate=FILE'
The data file to analyse. If omitted, the default file,
The data file to analyse. If omitted, the default file,
`sim.profile' is used.
 
 
403,14 → 421,14
2.3 Memory Profiling Utility
============================
 
This utility analyses memory profile data generated by Or1ksim. It may
be invoked as a standalone command, or from the Or1ksim CLI. The
This utility analyses memory profile data generated by Or1ksim. It may
be invoked as a standalone command, or from the Or1ksim CLI. The
general form the standalone command is:
 
or32-uclinux-mprofile [-vh] [-m=M] [-g=N] [-f=FILE] FROM TO
 
Many of the options have both a short and a long form. For example `-h'
or `--help'.
Many of the options have both a short and a long form. For example
`-h' or `--help'.
 
`-v'
`--version'
423,11 → 441,11
 
`-m=M'
`--mode=M'
Specify the mode out output. Permitted options are
Specify the mode out output. Permitted options are
 
`detailed'
`d'
Detailed output. This is the default if no mode is specified.
Detailed output. This is the default if no mode is specified.
 
`pretty'
`p'
448,7 → 466,7
 
`-f=FILE'
`--filename=FILE'
The data file to analyse. If not specified, the default,
The data file to analyse. If not specified, the default,
`sim.profile' is used.
 
`FROM'
464,11 → 482,11
=====================
 
Or1ksim may be used as a static of dynamic library, `libsim.a' or
`libsim.so'. When compiling with the static library, the flag, `-lsim'
`libsim.so'. When compiling with the static library, the flag, `-lsim'
should be added to the link command.
 
The header file `or1ksim.h' contains appropriate declarations of the
functions exported by the Or1ksim library. These are:
functions exported by the Or1ksim library. These are:
 
-- `or1ksim.h': int or1ksim_init (const char *CONFIG_FILE, const char
*IMAGE_FILE, void *CLASS_PTR, unsigned long int (*UPR)(void
485,17 → 503,18
configuring Or1ksim and the format of the configuration file.
 
UPW is called for any write to an address external to the model
(determined by a `generic' section in the configuration file). UPR
is called for any reads to an external address. The CLASS_PTR is
passed back with these upcalls, allowing the function to associate
the call with the class which originally initialized the library.
(determined by a `generic' section in the configuration file).
UPR is called for any reads to an external address. The CLASS_PTR
is passed back with these upcalls, allowing the function to
associate the call with the class which originally initialized the
library.
 
MASK indicates which bytes in the word are to be written or read.
Bytes to be read/written should have 0xff set in MASK. Otherwise
Bytes to be read/written should have 0xff set in MASK. Otherwise
the byte should be zero.
 
ADDR, MASK, WDATA and the result from UPR all use host-endianess,
_not_ model-endianess. The internal Or1ksim routines manage all
_not_ model-endianess. The internal Or1ksim routines manage all
the conversion.
 
 
506,7 → 525,7
 
-- `or1ksim.h': void or1ksim_reset_duration (double DURATION)
Change the duration of a run specified in an earlier call to
`or1ksim_run'. Typically this is called from an upcall, which
`or1ksim_run'. Typically this is called from an upcall, which
realizes it needs to change the duration of the run specified in
the call to `or1ksim_run' that has been interrupted by the upcall.
 
516,7 → 535,7
 
 
-- `or1ksim.h': void or1ksim_set_time_point ()
Set a timing point. For use with `or1ksim_get_time_period'.
Set a timing point. For use with `or1ksim_get_time_period'.
 
 
-- `or1ksim.h': double or1ksim_get_time_period ()
530,13 → 549,13
 
 
-- `or1ksim.h': unsigned long int or1ksim_clock_rate ()
Return the Or1ksim clock rate (in Hz). This is the value specified
in the configuration file.
Return the Or1ksim clock rate (in Hz). This is the value
specified in the configuration file.
 
 
-- `or1ksim.h': void or1ksim_interrupt (int I)
Generate an edge-triggered interrupt on interrupt line I. The
interrupt is then immediately cleared automatically. A warning
Generate an edge-triggered interrupt on interrupt line I. The
interrupt is then immediately cleared automatically. A warning
will be generated and the interrupt request ignored if level
sensitive interrupts have been configured with the programmable
interrupt controller (*note Interrupt Configuration: Interrupt
544,9 → 563,9
 
 
-- `or1ksim.h': void or1ksim_interrupt_set (int I)
Assert a level-triggered interrupt on interrupt line I. The
Assert a level-triggered interrupt on interrupt line I. The
interrupt must be cleared separately by an explicit call to
`or1ksim_interrupt_clear'. A warning will be generated, and the
`or1ksim_interrupt_clear'. A warning will be generated, and the
interrupt request ignored if edge sensitive interrupts have been
configured with the programmable interrupt controller (*note
Interrupt Configuration: Interrupt Configuration.).
554,7 → 573,7
 
-- `or1ksim.h': void or1ksim_interrupt_clear (int I)
Clear a level-triggered interrupt on interrupt line I, which was
previously asserted by a call to `or1ksim_interrupt_set'. A
previously asserted by a call to `or1ksim_interrupt_set'. A
warning will be generated, and the interrupt request ignored if
edge sensitive interrupts have been configured with the
programmable interrupt controller (*note Interrupt Configuration:
566,7 → 585,7
`configure' script).
 
For example if the main installation directory is `/opt/or1ksim', the
library will be found in the `/opt/or1ksim/lib' directory. It is
library will be found in the `/opt/or1ksim/lib' directory. It is
available as both a static library (`libsim.a') and a shared object
(`libsim.so').
 
574,19 → 593,19
one of the following:
 
* Add the library directory to the `LD_LIBRARY_PATH' environment
variable during execution. For example:
variable during execution. For example:
 
export LD_LIBRARY_PATH=/opt/or1ksim/lib:$LD_LIBRARY_PATH
 
* Add the library directory to the `LD_RUN_PATH' environment
variable during linking. For example:
variable during linking. For example:
 
export LD_RUN_PATH=/opt/or1ksim/lib:$LD_RUN_PATH
 
* Use the linker `--rpath' option and specify the library directory
when linking your program. For example
when linking your program. For example
 
gcc ... -Wl,--rpath -Wl,/opt/or1ksim/lib ...
gcc ... -Wl,--rpath -Wl,/opt/or1ksim/lib ...
 
* Add the library directory to `/etc/ld.so.conf'
 
597,10 → 616,10
3 Configuration
***************
 
Or1ksim is configured through a configuration file. This is specified
Or1ksim is configured through a configuration file. This is specified
through the `-f' parameter to the Or1ksim command, or passed as a
string when initializing the Or1ksim library. If no file is specified,
the default `sim.cfg' is used. The file is looked for first in the
string when initializing the Or1ksim library. If no file is specified,
the default `sim.cfg' is used. The file is looked for first in the
current directory, then in the `$HOME/.or1k' directory of the user.
 
* Menu:
629,7 → 648,7
3.1.1 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
`/*' and `*/').
 
Configure files may be included, using
661,8 → 680,8
 
Depending on the parameter, the value may be a named value (an
enumeration), an integer (specified in any format acceptable in C) or a
string in doubple quotes. For flag parameters, the value 1 is used to
mean "true" or "on" and the value "0" to mean "false" or "off". An
string in doubple quotes. For flag parameters, the value 1 is used to
mean "true" or "on" and the value "0" to mean "false" or "off". An
example from a memory section shows each of these
 
section memory
673,11 → 692,11
end
 
Many parameters are optional and take reasonable default values if not
specified. However there are some parameters (for example the `ce'
specified. However there are some parameters (for example the `ce'
parameter in `section memory') _must_ be specified.
 
Subsections are introduced by a keyword, with a parameter value (no `='
sign), and end with the same keyword prefixed by `end'. Thus the
sign), and end with the same keyword prefixed by `end'. Thus the
ATA/ATAPI inteface (`section ata') has a `device' subsection, thus:
 
section ata
694,9 → 713,9
Others (for example `section memory' may appear multiple times.
 
Sections may be omitted, _unless they contain parameters which are
non-optional_. If the section describes a part of the simulator which
non-optional_. If the section describes a part of the simulator which
is optional (for example whether it has a UART), then that
functionality will not be provided. If the section describes a part of
functionality will not be provided. If the section describes a part of
the simulator which is not optional (for example the CPU), then all the
parameters of that section will take their default values.
 
705,8 → 724,8
ensure that functionality is explicitly omitted.
 
Even if a section is disabled, all its parameters will be read and
stored. This is helpful if the section is subsequently enabled from the
Or1ksim command line (*note Interactive Command Line: Interactive
stored. This is helpful if the section is subsequently enabled from
the Or1ksim command line (*note Interactive Command Line: Interactive
Command Line.).
 
Tip: It generally clearer to have sections describing _all_
734,40 → 753,41
3.2.1 Simulator Behavior
------------------------
 
Simulator behavior is described in `section sim'. This section should
appear only once. The following parameters may be specified.
Simulator behavior is described in `section sim'. This section should
appear only once. The following parameters may be specified.
 
`verbose = 0|1'
If 1 (true), print extra messages. Default 0.
If 1 (true), print extra messages. Default 0.
 
`debug = 0-9'
0 means no debug messages. 1-9 means produce debug messages. The
higher the value the greater the number of messages. Default 0.
Negative values will be treated as 0 (with a warning). Values that
are too large will be treated as 9 (with a warning).
0 means no debug messages. 1-9 means produce debug messages. The
higher the value the greater the number of messages. Default 0.
Negative values will be treated as 0 (with a warning). Values
that are too large will be treated as 9 (with a warning).
 
`profile = 0|1'
If 1 (true) generate a profiling file using the file specified in
the `prof_file' parameter or otherwise `sim.profile'. Default 0.
the `prof_file' parameter or otherwise `sim.profile'. Default 0.
 
`prof_file = ``FILENAME'''
Specifies the file to be used with the `profile' parameter. Default
`sim.profile'. For backwards compatibility, the alternative name
`prof_fn' is supported for this parameter, but deprecated.
Specifies the file to be used with the `profile' parameter.
Default `sim.profile'. For backwards compatibility, the
alternative name `prof_fn' is supported for this parameter, but
deprecated.
 
`mprofile = 0|1'
If 1 (true) generate a memory profiling file using the file
specified in the `mprof_file' parameter or otherwise
`sim.mprofile'. Default 0.
`sim.mprofile'. Default 0.
 
`mprof_fn = ``FILENAME'''
Specifies the file to be used with the `mprofile' parameter.
Default `sim.mprofile'. For backwards compatibility, the
Default `sim.mprofile'. For backwards compatibility, the
alternative name `mprof_fn' is supported for this parameter, but
deprecated.
 
`history = 0|1'
If 1 (true) track execution flow. Default 0.
If 1 (true) track execution flow. Default 0.
 
Note: Setting this parameter seriously degrades performance.
 
776,8 → 796,8
section (*note CPU Configuration: CPU Configuration.).
 
`exe_log = 0|1'
If 1 (true), generate an execution log. Log is written to the file
specified in parameter `exe_log_file'. Default 0.
If 1 (true), generate an execution log. Log is written to the
file specified in parameter `exe_log_file'. Default 0.
 
Note: Setting this parameter seriously degrades performance.
 
785,7 → 805,7
Type of execution log to produce.
 
`default'
Produce default output for the execution log. In the current
Produce default output for the execution log. In the current
implementation this is the equivalent of `hardware'.
 
`hardware'
803,35 → 823,35
`software'
After each instruction execution, log the number of
instructions executed so far and the next instruction to
execute, symbolically disassembled. Also show the value of
execute, symbolically disassembled. Also show the value of
each operand to the instruction.
 
 
Default value `hardware'. Any unrecognized keyword (case
Default value `hardware'. Any unrecognized keyword (case
insensitive) will be treated as the default with a warning.
 
Note: Execution logs can be _very_ big.
 
`exe_log_start = VALUE'
Address of the first instruction to start logging. Default 0.
Address of the first instruction to start logging. Default 0.
 
`exe_log_end = VALUE'
Address of the last instruction to log. Default no limit (i.e once
started logging will continue until the simulator exits).
Address of the last instruction to log. Default no limit (i.e
once started logging will continue until the simulator exits).
 
`exe_log_marker = VALUE'
Specifies the number of instructions between printing horizontal
markers. Default is to produce no markers.
markers. Default is to produce no markers.
 
`exe_log_file = FILENAME'
Filename for the execution log filename if `exe_log' is enabled.
Default `executed.log'. For backwards compatibility, the
Default `executed.log'. For backwards compatibility, the
alternative name `exe_log_fn' is supported for this parameter, but
deprecated.
 
`clkcycle = VALUE[ps|ns|us|ms]'
Specify the time taken by one clock cycle. If no units are
specified, `ps' is assumed. Default 4000ps (250MHz).
Specify the time taken by one clock cycle. If no units are
specified, `ps' is assumed. Default 4000ps (250MHz).
 
 

841,11 → 861,11
-------------------------------------------
 
The Verification API (VAPI) provides a TCP/IP interface to allow
components of the simulation to be controlled externally. *Note
components of the simulation to be controlled externally. *Note
Verification API: Verification API, for more details.
 
Verification API configuration is described in `section vapi'. This
section may appear at most once. The following parameters may be
Verification API configuration is described in `section vapi'. This
section may appear at most once. The following parameters may be
specified.
 
`enabled = 0|1'
854,16 → 874,16
 
`server_port = VALUE'
When VAPI is enabled, communication will be via TCP/IP on the port
specified by VALUE. The value must lie in the range 1 to 65535.
specified by VALUE. The value must lie in the range 1 to 65535.
The default value is 50000.
 
Tip: There is no registered port for Or1ksim VAPI. Good
Tip: There is no registered port for Or1ksim VAPI. Good
practice suggests users should adopt port values in the
"Dynamic" or "Private" port range, i.e. 49152-65535.
"Dynamic" or "Private" port range, i.e. 49152-65535.
 
`log_enabled = 0|1'
If 1 (true), all VAPI requests and sent commands will be logged.
If 0 (the default), logging is diabled. Logs are written to the
If 0 (the default), logging is diabled. Logs are written to the
file specified by the `vapi_log_file' field (see below).
 
Caution: This can generate a substantial amount of file I/O
870,13 → 890,13
and seriously degrade simulator performance.
 
`hide_device_id = 0|1'
If 1 (true) don't log the device ID. If 0 (the default), log the
device ID. This feature (when set to 1) is provided for backwards
If 1 (true) don't log the device ID. If 0 (the default), log the
device ID. This feature (when set to 1) is provided for backwards
compatibility with an old version of VAPI.
 
`vapi_log_file = "FILENAME"'
Use `filename' as the file for logged data is logging is enabled
(see `log_enabled' above). The default is `"vapi.log"'. For
(see `log_enabled' above). The default is `"vapi.log"'. For
backwards compatibility, the alternative name `vapi_log_fn' is
supported for this parameter, but deprecated.
 
888,12 → 908,12
----------------------------------------------
 
The Custom Unit Compiler (CUC) was a project by Marko Mlinar to generate
Verilog from ANSI C functions. The project seems to not have progressed
beyond the initial prototype phase. The configuration parameters are
Verilog from ANSI C functions. The project seems to not have progressed
beyond the initial prototype phase. The configuration parameters are
described here for the record.
 
CUC configuration is described in `section cuc'. This section may
appear at most once. The following parameters may be specified.
CUC configuration is described in `section cuc'. This section may
appear at most once. The following parameters may be specified.
 
`memory_order = none|weak|strong|exact'
This parameter specifies the memory ordering required:
902,33 → 922,33
Different memory ordering, even if there are dependencies.
Bursts can be made, width can change.
 
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.
 
Same memory ordering. Bursts can be made, width can change.
Same memory ordering. Bursts can be made, width can change.
 
Exactly the same memory ordering and widths.
 
 
The default value is `memory_order=exact'. Invalid memory
The default value is `memory_order=exact'. Invalid memory
orderings are ignored with a warning.
 
`calling_convention = 0|1'
If 1 (true), programs follow OpenRISC calling conventions. If 0
If 1 (true), programs follow OpenRISC calling conventions. If 0
(the default), they may use other convenitions.
 
`enable_bursts = 0 | 1'
If 1 (true), bursts are detected. If 0 (the default), bursts are
If 1 (true), bursts are detected. If 0 (the default), bursts are
not detected.
 
`no_multicycle = 0 | 1'
If 1 (true), no multicycle logic paths will be generated. If 0 (the
default), multicycle logic paths will be generated.
If 1 (true), no multicycle logic paths will be generated. If 0
(the default), multicycle logic paths will be generated.
 
`timings_file = "FILENAME"'
FILENAME specifies a file containing timing information. The
default value is `"virtex.tim"'. For backwards compatibility, the
FILENAME specifies a file containing timing information. The
default value is `"virtex.tim"'. For backwards compatibility, the
alternative name `timings_fn' is supported for this parameter, but
deprecated.
 
956,8 → 976,8
3.3.1 CPU Configuration
-----------------------
 
CPU configuration is described in `section cpu'. This section should
appear only once. At present Or1ksim does not model multi-CPU systems.
CPU configuration is described in `section cpu'. This section should
appear only once. At present Or1ksim does not model multi-CPU systems.
The following parameters may be specified.
 
`ver = VALUE'
966,13 → 986,13
 
`rev = VALUE'
The values are used to form the corresponding fields in the `VR'
Special Purpose Register (SPR 0). Default values 0. A warning is
Special Purpose Register (SPR 0). Default values 0. A warning is
given and the value truncated if it is too large (8 bits for `ver'
and `cfg', 6 bits for `rev').
 
`upr = VALUE'
Used as the value of the Unit Present Register (UPR) Special
Purpose Register (SPR 1) to VALUE. Default value is 0x0000075f,
Purpose Register (SPR 1) to VALUE. Default value is 0x0000075f,
i.e.
* UPR present (0x00000001)
 
998,17 → 1018,17
 
`cfgr = VALUE'
Sets the CPU configuration register (Special Purpose Register 2) to
VALUE. Default value is 0x00000020, i.e. support for the ORBIS32
instruction set. Attempts to set any other value are accepted, but
VALUE. Default value is 0x00000020, i.e. support for the ORBIS32
instruction set. Attempts to set any other value are accepted, but
issue a warning that there is no support for the instruction set.
 
`sr = VALUE'
Sets the supervision register Special Purpose Register (SPR 0x11)
to VALUE. Default value is 0x00008001, i.e. start in supervision
to VALUE. Default value is 0x00008001, i.e. start in supervision
mode (0x00000001) and set the "Fixed One" bit (0x00008000).
 
`superscalar = 0|1'
If 1, the processor operates in superscalar mode. Default value is
If 1, the processor operates in superscalar mode. Default value is
0.
 
In the current simulator, the only functional effect of superscalar
1019,8 → 1039,8
well tested, so users are advised not to use this option.
 
`hazards = 0|1'
If 1, data hazards are tracked in a superscalar CPU. Default value
is 0.
If 1, data hazards are tracked in a superscalar CPU. Default
value is 0.
 
In the current simulator, the only functional effect is to cause
logging of hazard waiting information if the CPU is superscalar.
1034,8 → 1054,8
well tested, so users are advised not to use this option.
 
`dependstats = 0|1'
If 1, inter-instruction dependencies are calculated. Default value
0.
If 1, inter-instruction dependencies are calculated. Default
value 0.
 
If these values are calculated, the depencies can be displayed
using the simulator's `stat' command.
1047,9 → 1067,9
 
`sbuf_len = VALUE'
The length of the store buffer is set to VALUE, which must be no
greater than 256. Larger values will be truncated to 256 with a
warning. Negative values will be treated as 0 with a warning. Use
0 to disable the store buffer.
greater than 256. Larger values will be truncated to 256 with a
warning. Negative values will be treated as 0 with a warning.
Use 0 to disable the store buffer.
 
When the store buffer is active, stores are accumulated and
committed when I/O is idle.
1061,16 → 1081,16
3.3.2 Memory Configuration
--------------------------
 
Memory configuration is described in `section memory'. This section may
appear multiple times, specifying multiple blocks of memory. The
Memory configuration is described in `section memory'. This section
may appear multiple times, specifying multiple blocks of memory. The
following parameters may be specified.
 
`type=random|pattern|unknown|zero'
Specifies the values to which memory should be initialized. The
Specifies the values to which memory should be initialized. The
default value is `unknown'.
 
`random'
Set the memory values to be a random value. A seed for the
Set the memory values to be a random value. A seed for the
random generator may be set using the `random_seed' field in
this section (see below), thus ensuring the same "random"
values are used each time.
1080,11 → 1100,11
using the `pattern' field in this section (see below).
 
`unknown'
The memory values are not initialized (i.e. left "unknown").
The memory values are not initialized (i.e. left "unknown").
This option will yield faster initialization of the simulator.
 
`zero'
Set the memory values to be 0. This is the equivalent of
Set the memory values to be 0. This is the equivalent of
`type=pattern' and a `pattern' value of 0, and implemented as
such.
 
1095,35 → 1115,36
 
 
`random_seed = VALUE'
Set the seed for the random number generator to VALUE. This only
Set the seed for the random number generator to VALUE. This only
has any effect for memory type `random'.
 
The default value is -1, which means the seed will be set from a
call to the `time' function, thus ensuring different random values
are used on each run. The simulator prints out the seed used in
are used on each run. The simulator prints out the seed used in
this case, allowing repeat runs to regenerate the same random
values used in any particular run.
 
`pattern = VALUE'
Set the pattern to be used when initializing memory to VALUE. The
default value is 0. This only has any effect for memory type
`pattern'. The least significant 8 bits of this value is used to
initialize each byte. More than 8 bits can be specified, but will
Set the pattern to be used when initializing memory to VALUE. The
default value is 0. This only has any effect for memory type
`pattern'. The least significant 8 bits of this value is used to
initialize each byte. More than 8 bits can be specified, but will
ignored with a warning.
 
Tip: The default value, is equivalent to setting the memory
`type' to be `zero'. If that is what is intended, then using
`type' to be `zero'. If that is what is intended, then using
`type=zero' explicitly is better than using `type=pattern'
and not specifying a value for `pattern'.
 
`baseaddr = VALUE'
Set the base address of the memory to VALUE. It should be aligned
Set the base address of the memory to VALUE. It should be aligned
to a multiple of the memory size rounded up to the nearest 2^n.
The default value is 0.
 
`size = VALUE'
Set the size of the memory block to be VALUE bytes. This should be
a multiple of 4 (i.e. word aligned). The default value is 1024.
Set the size of the memory block to be VALUE bytes. This should
be a multiple of 4 (i.e. word aligned). The default value is
1024.
 
Note: When allocating memory, the simulator will allocate the
nearest 2^n bytes greater than or equal to VALUE, and will not
1131,53 → 1152,53
and the amount allocated.
 
As a consequence users are strongly recommended to specify
memory sizes that are an exact power of 2. If some other
memory sizes that are an exact power of 2. If some other
amount of memory is required, it should be specified as
separate, contiguous blocks, each of which is a power of 2 in
size.
 
`name = "TEXT"'
Name the block. Typically these describe the type of memory being
modeled (thus `"SRAM"' or `"Flash"'. The default is
Name the block. Typically these describe the type of memory being
modeled (thus `"SRAM"' or `"Flash"'. The default is
`"anonymous memory block"'.
 
Note: It is not clear that this information is currently ever
used in normal operation of the simulator. Even the `info'
used in normal operation of the simulator. Even the `info'
command of the simulator ignores it.
 
`ce = VALUE'
Set the chip enable index of the memory instance. Each memory
Set the chip enable index of the memory instance. Each memory
instance should have a unique chip enable index, which should be
greater than or equal to zero. This is used by the memory
greater than or equal to zero. This is used by the memory
controller when identifying different memory instances.
 
The default value is -1 (invalid).
 
`mc = VALUE'
Specifies the memory controller this memory is connected to. It
Specifies the memory controller this memory is connected to. It
should correspond to the `index' field specified in a `section mc'
for a memory controller (*note Memory Controller Configuration:
Memory Controller Configuration.).
 
Default value is 0, which is also the default value of a memory
controller `index' field. This is suitable therefore for designs
controller `index' field. This is suitable therefore for designs
with just one memory controller.
 
`delayr = VALUE'
The number of cycles required for a read access. Set to -1 if the
memory does not support reading. Default value 1. The simulator
The number of cycles required for a read access. Set to -1 if the
memory does not support reading. Default value 1. The simulator
will add this number of cycles to the total instruction cycle
count when reading from main memory.
 
`delayw = VALUE'
The number of cycles required for a write access. Set to -1 if the
memory does not support writing. Default value 1. The simulator
The number of cycles required for a write access. Set to -1 if the
memory does not support writing. Default value 1. The simulator
will add this number of cycles to the total instruction cycle
count when writing to main memory.
 
`log = "FILE"'
If specified, `file' names a file for all memory accesses to be
logged. If not specified, the default value, NULL is used, meaning
logged. If not specified, the default value, NULL is used, meaning
that the memory is not logged.
 
 
1189,55 → 1210,55
 
Memory Management Unit (MMU) configuration is described in `section
dmmu' (for the data MMU) and `section immu' (for the instruction MMU).
Each section should appear at most once. The following parameters may
Each section should appear at most once. The following parameters may
be specified.
 
`enabled = 0|1'
If 1 (true), the data or instruction (as appropriate) MMU is
enabled. If 0 (the default), it is disabled.
enabled. If 0 (the default), it is disabled.
 
`nsets = VALUE'
Sets the number of data or instruction (as appropriate) TLB sets to
VALUE, which must be a power of two, not exceeding 128. Values
which do not fit these criteria are ignored with a warning. The
VALUE, which must be a power of two, not exceeding 128. Values
which do not fit these criteria are ignored with a warning. The
default value is 1.
 
`nways = VALUE'
Sets the number of data or instruction (as appropriate) TLB ways to
VALUE. The value must be in the range 1 to 4. Values outside this
range are ignored with a warning. The default value is 1.
VALUE. The value must be in the range 1 to 4. Values outside
this range are ignored with a warning. The default value is 1.
 
`pagesize = VALUE'
The data or instruction (as appropriate) MMU page size is set to
VALUE, which must be a power of 2. Values which are not a power of
2 are ignored with a warning. The default is 8192 (0x2000).
VALUE, which must be a power of 2. Values which are not a power
of 2 are ignored with a warning. The default is 8192 (0x2000).
 
`entrysize = VALUE'
The data or instruction (as appropriate) MMU entry size is set to
VALUE, which must be a power of 2. Values which are not a power of
2 are ignored with a warning. The default value is 1.
VALUE, which must be a power of 2. Values which are not a power
of 2 are ignored with a warning. The default value is 1.
 
Note: Or1ksim does not appear to use the `entrysize' parameter
in its simulation of the MMUs. Thus setting this value does
in its simulation of the MMUs. Thus setting this value does
not seem to matter.
 
`ustates = VALUE'
The number of instruction usage states for the data or instruction
(as appropriate) MMU is set to VALUE, which must be 2, 3 or 4.
Values outside this range are ignored with a warning. The default
Values outside this range are ignored with a warning. The default
value is 2.
 
Note: Or1ksim does not appear to use the `ustates' parameter
in its simulation of the MMUs. Thus setting this value does
in its simulation of the MMUs. Thus setting this value does
not seem to matter.
 
`hitdelay = VALUE'
Set the number of cycles a data or instruction (as appropriate) MMU
hit costs. Default value 1.
hit costs. Default value 1.
 
`missdelay = VALUE'
Set the number of cycles a data or instruction (as appropriate) MMU
miss costs. Default value 1.
miss costs. Default value 1.
 
 

1247,30 → 1268,30
-------------------------
 
Cache configuration is described in `section dc' (for the data cache)
and `seciton ic' (for the instruction cache). Each section should
appear at most once. The following parameters may be specified.
and `seciton ic' (for the instruction cache). Each section should
appear at most once. The following parameters may be specified.
 
`enabled = 0|1'
If 1 (true), the data or instruction (as appropriate) cache is
enabled. If 0 (the default), it is disabled.
enabled. If 0 (the default), it is disabled.
 
`nsets = VALUE'
Sets the number of data or instruction (as appropriate) cache sets
to VALUE, which must be a power of two, not exceeding
`MAX_DC_SETS' (for the data cache) or `MAX_IC_SETS' (for the
instruction cache). At the time of writing, these constants are
both defined in the code to be 1024). The default value is 1.
instruction cache). At the time of writing, these constants are
both defined in the code to be 1024). The default value is 1.
 
`nways = VALUE'
Sets the number of data or instruction (as appropriate) cache ways
to VALUE, which must be a power of two, not exceeding
`MAX_DC_WAYS' (for the data cache) or `MAX_IC_WAYS' (for the
instruction cache). At the time of writing, these constants are
both defined in the code to be 32). The default value is 1.
instruction cache). At the time of writing, these constants are
both defined in the code to be 32). The default value is 1.
 
`blocksize = VALUE'
The data or instruction (as appropriate) cache block size is set to
VALUE bytes, which must be either 16 or 32. The default is 16.
VALUE bytes, which must be either 16 or 32. The default is 16.
 
`ustates = VALUE'
The number of instruction usage states for the data or instruction
1278,28 → 1299,28
The default value is 2.
 
`hitdelay = VALUE'
_Instruction cache only_. Set the number of cycles an instruction
cache hit costs. Default value 1.
_Instruction cache only_. Set the number of cycles an instruction
cache hit costs. Default value 1.
 
`missdelay = VALUE'
_Instruction cache only_. Set the number of cycles an instruction
cache miss costs. Default value 1.
_Instruction cache only_. Set the number of cycles an instruction
cache miss costs. Default value 1.
 
`load_hitdelay = VALUE'
_Data cache only_. Set the number of cycles a data load cache hit
costs. Default value 2.
_Data cache only_. Set the number of cycles a data load cache hit
costs. Default value 2.
 
`load_missdelay = VALUE'
_Data cache only_. Set the number of cycles a data load cache miss
costs. Default value 2.
_Data cache only_. Set the number of cycles a data load cache
miss costs. Default value 2.
 
`store_hitdelay = VALUE'
_Data cache only_. Set the number of cycles a data store cache hit
costs. Default value 0.
_Data cache only_. Set the number of cycles a data store cache hit
costs. Default value 0.
 
`store_missdelay = VALUE'
_Data cache only_. Set the number of cycles a data store cache
miss costs. Default value 0.
_Data cache only_. Set the number of cycles a data store cache
miss costs. Default value 0.
 
 

1309,17 → 1330,17
-----------------------------
 
Programmable Interrupt Controller (PIC) configuration is described in
`section pic'. This section may appear at most once--Or1ksim has no
mechanism for handling multiple interrupt controllers. The following
`section pic'. This section may appear at most once--Or1ksim has no
mechanism for handling multiple interrupt controllers. The following
parameters may be specified.
 
`enabled = 0|1'
If 1 (true), the programmable interrupt controller is enabled. If 0
(the default), it is disabled.
If 1 (true), the programmable interrupt controller is enabled. If
0 (the default), it is disabled.
 
`edge_trigger = 0|1'
If 1 (true, the default), the programmable interrupt controller is
edge triggered. If 0 (false), it is level triggered.
edge triggered. If 0 (false), it is level triggered.
 
 

1328,7 → 1349,7
3.3.6 Power Management Configuration
------------------------------------
 
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
setting the different bits in the power management Special Purpose
Register (PMR, SPR 0x4000) is
1339,7 → 1360,7
`DME (bit mask 0x00000010)'
`SME (bit mask 0x00000020)'
Both these bits cause the processor to stop executing
instructions. However all other functions (debug interaction, CLI,
instructions. However all other functions (debug interaction, CLI,
VAPI etc) carry on as normal.
 
`DCGE (bit mask 0x00000004)'
1352,13 → 1373,13
 
On reset all bits are cleared.
 
Power management configuration is described in `section pm'. This
section may appear at most once. The following parameter may be
Power management configuration is described in `section pm'. This
section may appear at most once. The following parameter may be
specified.
 
`enabled = 0|1'
If 1 (true), power management is enabled. If 0 (the default), it is
disabled.
If 1 (true), power management is enabled. If 0 (the default), it
is disabled.
 
 

1368,15 → 1389,15
-------------------------------------
 
From examining the code base, it seems the branch prediction function
is not fully implemented. At present the functionality seems restricted
to collection of statistics.
is not fully implemented. At present the functionality seems
restricted to collection of statistics.
 
Branch prediction configuration is described in `section bpb'. This
section may appear at most once. The following parameters may be
Branch prediction configuration is described in `section bpb'. This
section may appear at most once. The following parameters may be
specified.
 
`enabled = 0|1'
If 1 (true), branch prediction is enabled. If 0 (the default), it
If 1 (true), branch prediction is enabled. If 0 (the default), it
is disabled.
 
`btic = 0|1'
1384,21 → 1405,21
If 0 (the default), it is disabled.
 
`sbp_bf_fwd = 0|1'
If 1 (true), use forward prediction for the `l.bf' instruction. If
If 1 (true), use forward prediction for the `l.bf' instruction. If
0 (the default), do not use forward prediction for this
instruction.
 
`sbp_bnf_fwd = 0|1'
If 1 (true), use forward prediction for the `l.bnf' instruction. If
0 (the default), do not use forward prediction for this
If 1 (true), use forward prediction for the `l.bnf' instruction.
If 0 (the default), do not use forward prediction for this
instruction.
 
`hitdelay = VALUE'
Set the number of cycles a branch prediction hit costs. Default
Set the number of cycles a branch prediction hit costs. Default
value 0.
 
`missdelay = VALUE'
Set the number of cycles a branch prediction miss costs. Default
Set the number of cycles a branch prediction miss costs. Default
value 0.
 
 
1409,16 → 1430,16
-----------------------------------
 
The debug unit and debug interface configuration is described in
`section debug'. This section may appear at most once. The following
`section debug'. This section may appear at most once. The following
parameters may be specified.
 
`enabled = 0|1'
If 1 (true), the debug unit is enabled. If 0 (the default), it is
If 1 (true), the debug unit is enabled. If 0 (the default), it is
disabled.
 
Note: This enables the functionality of the debug unit (its
registers etc) within the mode. It does not provide any
external interface to the debug unit. For that, see
registers etc) within the mode. It does not provide any
external interface to the debug unit. For that, see
`gdb_enabled' and `rsp_enabled' below.
 
`rsp_enabled = 0|1'
1425,7 → 1446,7
If 1 (true), the GDB "Remote Serial Protocol" server is started,
provding an interface to an external GNU debugger, using the port
specified in the `rsp_port' field (see below), or the
`or1ksim-rsp' TCP/IP service. If 0 (the default), the server is
`or1ksim-rsp' TCP/IP service. If 0 (the default), the server is
not started, and no external interface is provided.
 
For more detailed information on the interface to the GNU Debugger
1433,27 → 1454,27
Practical Experience with the OpenRISC 1000 Architecture', by
Jeremy Bennett, published by Embecosm Limited (`www.embecosm.com').
 
Note: `rsp_enabled' may not be enabled with `gdb_enabled'
(see below). If both are enabled, a warning is issued and
only the "Remote Serial Protocol" interface is enabled.
Note: `rsp_enabled' may not be enabled with `gdb_enabled' (see
below). If both are enabled, a warning is issued and only
the "Remote Serial Protocol" interface is enabled.
 
`rsp_port = VALUE'
VALUE specifies the port to be used for the GDB "Remote Serial
Protocol" interface to the GNU Debugger (GDB). Default value
51000. If the value 0 is specified, Or1ksim will instead look for
Protocol" interface to the GNU Debugger (GDB). Default value
51000. If the value 0 is specified, Or1ksim will instead look for
a TCP/IP service named `or1ksim-rsp'.
 
Tip: There is no registered port for Or1ksim "Remote Serial
Protocol" service `or1ksim-rsp'. Good practice suggests users
should adopt port values in the "Dynamic" or "Private" port
range, i.e. 49152-65535.
Protocol" service `or1ksim-rsp'. Good practice suggests
users should adopt port values in the "Dynamic" or "Private"
port range, i.e. 49152-65535.
 
`gdb_enabled = 0|1'
If 1 (true), the OpenRISC Remote JTAG protocol server is started,
provding an interface to an external GNU debugger, using the port
specified in the `server_port' field (see below), or the `or1ksim'
TCP/IP service. If 0 (the default), the server is not started, and
no external interface is provided.
TCP/IP service. If 0 (the default), the server is not started,
and no external interface is provided.
 
For more detailed information on the interface to the GNU Debugger
see Embecosm Application Note 2, `Howto: Porting the GNU Debugger
1461,35 → 1482,35
Jeremy Bennett, published by Embecosm Limited (`www.embecosm.com').
 
Note: The OpenRISC Remote JTAG protocol is unique to
OpenRISC, and remains only for backward compatibility. New
OpenRISC, and remains only for backward compatibility. New
users should adopt the standard GDB "Remote Serial Protocol"
interface (see `rsp_enabled' above) providing access to a
wider range of GDB functionality.
 
Note: `gdb_enabled' may not be enabled with `rsp_enabled'. If
both are enabled, a warning is issued and only the "Remote
Note: `gdb_enabled' may not be enabled with `rsp_enabled'.
If both are enabled, a warning is issued and only the "Remote
Serial Protocol" interface is enabled.
 
`server_port = VALUE'
VALUE specifies the port to be used for the OpenRISC Rmote JTAG
protocol interface to the GNU Debugger (GDB). Default value 51000.
If the value 0 is specified, Or1ksim will instead look for a TCP/IP
service named `or1ksim'.
protocol interface to the GNU Debugger (GDB). Default value
51000. If the value 0 is specified, Or1ksim will instead look for
a TCP/IP service named `or1ksim'.
 
Tip: There is no registered port for Or1ksim Remote JTAG
Interface or service `or1ksim'. Good practice suggests users
Interface or service `or1ksim'. Good practice suggests users
should adopt port values in the "Dynamic" or "Private" port
range, i.e. 49152-65535.
range, i.e. 49152-65535.
 
`vapi_id = VALUE'
VALUE specifies the value of the Verification API (VAPI) base
address to be used with the debug unit. *Note Verification API:
address to be used with the debug unit. *Note Verification API:
Verification API, for more details.
 
If this is specified and VALUE is non-zero, all OpenRISC Remote
JTAG protocol transactions will be logged to the VAPI log file, if
enabled. This is the only functionality associated with VAPI for
the debug unit. No VAPI commands are sent, nor requests handled.
enabled. This is the only functionality associated with VAPI for
the debug unit. No VAPI commands are sent, nor requests handled.
 
 

1498,7 → 1519,7
3.4 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.
 
* Menu:
1521,22 → 1542,23
-------------------------------------
 
The memory controller used in Or1ksim is the component implemented at
OpenCores, and found in the top level CVS directory, `mem_ctrl'. It is
OpenCores, and found in the top level CVS directory, `mem_ctrl'. It is
described in the document `Memory Controller IP Core' by Rudolf
Usselmann, which can be found in the `doc' subdirectory. It is a memory
mapped component, which resides on the main OpenRISC Wishbone data bus.
Usselmann, which can be found in the `doc' subdirectory. It is a
memory mapped component, which resides on the main OpenRISC Wishbone
data bus.
 
The memory controller configuration is described in `section mc'. This
The memory controller configuration is described in `section mc'. This
section may appear multiple times, specifying multiple memory
controllers. The following parameters may be specified.
controllers. The following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this memory controller is enabled. If 0,
it is disabled.
If 1 (true, the default), this memory controller is enabled. If
0, it is disabled.
 
Note: The memory controller can effectively also be disabled
by setting an appropriate power on control register value
(see below). However this should only be used if it is
(see below). However this should only be used if it is
desired to specifically model this behavior of the memory
controller, not as a way of disabling the memory controller
in general.
1543,7 → 1565,7
 
`baseaddr = VALUE'
Set the base address of the memory controller's memory mapped
registers to VALUE. The default is 0, which is probably not a
registers to VALUE. The default is 0, which is probably not a
sensible value.
 
The memory controller has a 7 bit address bus, with a total of 19
1565,7 → 1587,7
 
`index = VALUE'
Specify the index of this memory controller amongst all the memory
controllers. This value should be unique for each memory
controllers. This value should be unique for each memory
controller, and is used to associate specific memories with the
controller, through the `mc' field in the `section memory'
configuration (*note Memory Configuration: Memory Configuration.).
1581,23 → 1603,23
------------------------
 
The UART implemented in 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.
 
The component provides a number of interfaces to emulate the behavior
of an external terminal connected to the UART.
 
UART configuration is described in `section uart'. This section may
appear multiple times, specifying multiple UARTs. The following
UART configuration is described in `section uart'. This section may
appear multiple times, specifying multiple UARTs. The following
parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this UART is enabled. If 0, it is
If 1 (true, the default), this UART is enabled. If 0, it is
disabled.
 
`baseaddr = VALUE'
Set the base address of the UART's memory mapped registers to
VALUE. The default is 0, which is probably not a sensible value.
VALUE. The default is 0, which is probably not a sensible value.
 
The UART has a 3 bit address bus, with a total of 8 8-bit
registers, at addresses 0x0 through 0x7.
1614,9 → 1636,9
`channel="xterm:ARGS"'
Create an xterm on startup, write UART Tx traffic to the
xterm and take Rx traffic from the keyboard when the xterm
window is selected. Additional arguments to the xterm command
(for example specifying window size may be specified in ARGS,
or this may be left blank.
window is selected. Additional arguments to the xterm
command (for example specifying window size may be specified
in ARGS, or this may be left blank.
 
`channel="tcp:VALUE"'
Open the TCP/IP port specified by VALUE and read and write
1626,10 → 1648,10
this port.
 
Tip: There is no registered port for Or1ksim telnet UART
connection. Priviledged access is required to read
connection. Priviledged access is required to read
traffic on the registered "well-known" telnet port (23).
Instead users should use port values in the "Dynamic" or
"Private" port range, i.e. 49152-65535.
"Private" port range, i.e. 49152-65535.
 
`channel="fd:`rxfd',`txfd'"'
Read and write characters from and to the existing open
1644,16 → 1666,16
The default value for this field is `"xterm:"'.
 
`irq = VALUE'
Use VALUE as the IRQ number of this UART. Default value 0.
Use VALUE as the IRQ number of this UART. Default value 0.
 
`16550 = 0|1'
If 1 (true), the UART has the functionality of a 16550. If 0 (the
default), it has the functionality of a 16450. The principal
If 1 (true), the UART has the functionality of a 16550. If 0 (the
default), it has the functionality of a 16450. The principal
difference is that the 16550 can buffer multiple characters.
 
`jitter = VALUE'
Set the jitter, modeled as a time to block, to VALUE milliseconds.
Set to -1 to disable jitter modeling. Default value 0.
Set to -1 to disable jitter modeling. Default value 0.
 
Note: This functionality has yet to be implemented, so this
parameter has no effect.
1660,7 → 1682,7
 
`vapi_id = VALUE'
VALUE specifies the value of the Verification API (VAPI) base
address to be used with the UART. *Note Verification API:
address to be used with the UART. *Note Verification API:
Verification API, for more details, which details the use of the
VAPI with the UART.
 
1672,39 → 1694,39
-----------------------
 
The DMA controller used in Or1ksim is the component implemented at
OpenCores, and found in the top level CVS directory, `wb_dma'. It is
OpenCores, and found in the top level CVS directory, `wb_dma'. It is
described in the document `Wishbone DMA/Bridge IP Core' by Rudolf
Usselmann, which can be found in the `doc' subdirectory. It is a memory
mapped component, which resides on the main OpenRISC Wishbone data bus.
The present implementation is incomplete, intended only to support the
Ethernet interface (*note Ethernet Configuration::), although the
Ethernet interface is not yet completed.
Usselmann, which can be found in the `doc' subdirectory. It is a
memory mapped component, which resides on the main OpenRISC Wishbone
data bus. The present implementation is incomplete, intended only to
support the Ethernet interface (*note Ethernet Configuration::),
although the Ethernet interface is not yet completed.
 
DMA configuration is described in `section dma'. This section may
appear multiple times, specifying multiple DMA controllers. The
DMA configuration is described in `section dma'. This section may
appear multiple times, specifying multiple DMA controllers. The
following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this DMA controller is enabled. If 0, it
is disabled.
If 1 (true, the default), this DMA controller is enabled. If 0,
it is disabled.
 
`baseaddr = VALUE'
Set the base address of the DMA's memory mapped registers to
VALUE. The default is 0, which is probably not a sensible value.
VALUE. The default is 0, which is probably not a sensible value.
 
The DMA controller has a 10 bit address bus, with a total of 253
32-bit registers. The first 5 registers at addresses 0x000 through
0x010 control the overall behavior of the DMA controller. There are
then 31 blocks of 8 registers, controlling each of the 31 DMA
channels available. Addresses 0x014 through 0x01c are not used.
32-bit registers. The first 5 registers at addresses 0x000 through
0x010 control the overall behavior of the DMA controller. There
are then 31 blocks of 8 registers, controlling each of the 31 DMA
channels available. Addresses 0x014 through 0x01c are not used.
 
`irq = VALUE'
Use VALUE as the IRQ number of this DMA controller. Default value
Use VALUE as the IRQ number of this DMA controller. Default value
0.
 
`vapi_id = VALUE'
VALUE specifies the value of the Verification API (VAPI) base
address to be used with the DMA controller. *Note Verification
address to be used with the DMA controller. *Note Verification
API: Verification API, for more details, which details the use of
the VAPI with the DMA controller.
 
1716,52 → 1738,52
----------------------------
 
The Ethernet MAC used in Or1ksim is the component implemented at
OpenCores, and found in the top level CVS directory, `ethernet'. It
also forms part of the OpenRISC SoC, ORPSoC. It is described in the
OpenCores, and found in the top level CVS directory, `ethernet'. It
also forms part of the OpenRISC SoC, ORPSoC. It is described in the
document `Ethernet IP Core Specification' by Igor Mohor, which can be
found in the `doc' subdirectory. It is a memory mapped component, which
resides on the main OpenRISC Wishbone data bus.
found in the `doc' subdirectory. It is a memory mapped component,
which resides on the main OpenRISC Wishbone data bus.
 
Ethernet configuration is described in `section ethernet'. This section
may appear multiple times, specifying multiple Ethernet interfaces. The
following parameters may be specified.
Ethernet configuration is described in `section ethernet'. This
section may appear multiple times, specifying multiple Ethernet
interfaces. The following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this Ethernet MAC is enabled. If 0, it is
disabled.
If 1 (true, the default), this Ethernet MAC is enabled. If 0, it
is disabled.
 
`baseaddr = VALUE'
Set the base address of the MAC's memory mapped registers to
VALUE. The default is 0, which is probably not a sensible value.
VALUE. The default is 0, which is probably not a sensible value.
 
The Ethernet MAC has a 7-bit address bus, with a total of 21
32-bit registers. Addresses 0x54 through 0x7c are not used.
32-bit registers. Addresses 0x54 through 0x7c are not used.
 
Note: The Ethernet specification describes a Tx control
register, `TXCTRL', at address 0x50. However this register is
not implemented in the Or1ksim model.
register, `TXCTRL', at address 0x50. However this register
is not implemented in the Or1ksim model.
 
`dma = VALUE'
VALUE specifies the DMA controller with which this Ethernet is
associated. The default value is 0.
associated. The default value is 0.
 
Note: Support for external DMA is not provided in the current
implementation, and this value is ignored. In any case there
implementation, and this value is ignored. In any case there
is no equivalent field to which this can be matched in the
current DMA component implementation (*note DMA
Configuration: DMA Configuration.).
 
`irq = VALUE'
Use VALUE as the IRQ number of this Ethernet MAC. Default value 0.
Use VALUE as the IRQ number of this Ethernet MAC. Default value 0.
 
`rtx_type = 0|1'
If 1 (true) use a socket interface to the Ethernet (see parameter
`sockif' below). If 0 (the default), use a file interface, reading
and writing from and to the files specified in the `rxfile' and
`txfile' parameters (see below).
`sockif' below). If 0 (the default), use a file interface,
reading and writing from and to the files specified in the
`rxfile' and `txfile' parameters (see below).
 
Note: By default the socket interface is not provided in
Or1ksim. If it is required, this must be requested when
Or1ksim. If it is required, this must be requested when
configuring, by use of the `--enable-ethphy' option to
`configure'.
 
1770,7 → 1792,7
`rx_channel = RXVALUE'
`tx_channel = TXVALUE'
RXVALUE specifies the DMA channel to use for receive and TXVALUE
the DMA channel to use for transmit. Both default to 0.
the DMA channel to use for transmit. Both default to 0.
 
Note: As noted above, support for external DMA is not
provided in the current implementation, and so these values
1781,24 → 1803,24
When `rtx_type' is 0 (see above), RXFILE specifies the file to use
as input and TXFILE specifies the fie to use as output.
 
The file contains a sequence of packets. Each packet consists of a
packet length (32 bits), followed by that many bytes of data. Once
the input file is empty, the Ethernet MAC behaves as though there
were no data on the Ethernet. The default values of these
The file contains a sequence of packets. Each packet consists of a
packet length (32 bits), followed by that many bytes of data.
Once the input file is empty, the Ethernet MAC behaves as though
there were no data on the Ethernet. The default values of these
parameters are `"eth_rx"' and `"eth_tx"' respectively.
 
The input file must exist and be readable. The output file must be
writable and will be created if necessary. If either of these
The input file must exist and be readable. The output file must be
writable and will be created if necessary. If either of these
conditions is not met, a warning will be given.
 
`sockif = "SERVICE"'
When `rtx_type' is 1 (see above), SERVICE specifies the service to
use for communication. This may be TCP/IP or UDP/IP. The default
use for communication. This may be TCP/IP or UDP/IP. The default
value of this parameter is `"or1ksim_eth"'.
 
`vapi_id = VALUE'
VALUE specifies the value of the Verification API (VAPI) base
address to be used with the Ethernet PHY. *Note Verification API:
address to be used with the Ethernet PHY. *Note Verification API:
Verification API, for more details, which details the use of the
VAPI with the DMA controller.
 
1810,35 → 1832,35
------------------------
 
The GPIO used in Or1ksim is the component implemented at OpenCores, and
found in the top level CVS directory, `gpio'. It is described in the
found in the top level CVS directory, `gpio'. It is described in the
document `GPIO IP Core Specification' by Damjan Lampret and Goran
Djakovic, which can be found in the `doc' subdirectory. It is a memory
Djakovic, which can be found in the `doc' subdirectory. It is a memory
mapped component, which resides on the main OpenRISC Wishbone data bus.
 
GPIO configuration is described in `section gpio'. This section may
appear multiple times, specifying multiple GPIO devices. The following
GPIO configuration is described in `section gpio'. This section may
appear multiple times, specifying multiple GPIO devices. The following
parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this GPIO is enabled. If 0, it is
If 1 (true, the default), this GPIO is enabled. If 0, it is
disabled.
 
`baseaddr = VALUE'
Set the base address of the GPIO's memory mapped registers to
VALUE. The default is 0, which is probably not a sensible value.
VALUE. The default is 0, which is probably not a sensible value.
 
The GPIO has a 6 bit address bus, with a total of 10 32-bit
registers, although the number of bits that are actively used
varies. Addresses 0x28 through 0x3c are not used.
varies. Addresses 0x28 through 0x3c are not used.
 
`irq = VALUE'
Use VALUE as the IRQ number of this GPIO. Default value 0.
Use VALUE as the IRQ number of this GPIO. Default value 0.
 
`vapi_id = VALUE'
VALUE specifies the value of the Verification API (VAPI) base
address to be used with the GPIO. *Note Verification API:
address to be used with the GPIO. *Note Verification API:
Verification API, for more details, which details the use of the
VAPI with the GPIO controller. For backwards compatibility, the
VAPI with the GPIO controller. For backwards compatibility, the
alternative name `base_vapi_id' is supported for this parameter,
but deprecated.
 
1852,39 → 1874,39
Or1ksim models a VGA interface to an external monitor. The VGA
controller used in Or1ksim is the component implemented at OpenCores,
and found in the top level CVS directory, `vga_lcd', with no support
for the optional hardware cursors. It is described in the document
for the optional hardware cursors. It is described in the document
`VGA/LCD Core v2.0 Specifications' by Richard Herveille, which can be
found in the `doc' subdirectory. It is a memory mapped component, which
resides on the main OpenRISC Wishbone data bus.
found in the `doc' subdirectory. It is a memory mapped component,
which resides on the main OpenRISC Wishbone data bus.
 
The current implementation provides only functionality to dump the
screen to a file at intervals.
 
VGA controller configuration is described in `section vga'. This
VGA controller configuration is described in `section vga'. This
section may appear multiple times, specifying multiple VGA controllers.
The following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this VGA is enabled. If 0, it is
If 1 (true, the default), this VGA is enabled. If 0, it is
disabled.
 
`baseaddr = VALUE'
Set the base address of the VGA controller's memory mapped
registers to VALUE. The default is 0, which is probably not a
registers to VALUE. The default is 0, which is probably not a
sensible value.
 
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 0x800 through 0xfff. The hardware cursor
tables at addresses 0x800 through 0xfff. The hardware cursor
registers are not implemented, so addresses 0x01c through 0x7fc
are not used.
 
`irq = VALUE'
Use VALUE as the IRQ number of this VGA controller. Default value
Use VALUE as the IRQ number of this VGA controller. Default value
0.
 
`refresh_rate = VALUE'
VALUE specifies number of cycles between screen dumps. Default
VALUE specifies number of cycles between screen dumps. Default
value is derived from the simulation clock cycle time (*note
Simulator Behavior: Simulator Behavior.), to correspond to dumping
50 times per simulated second.
1893,7 → 1915,7
FILE specifies the base of the filename for screen dumps.
Successive screen dumps will be in BMP format, in files with the
name `FILENNNN.bmp', where NNNN is a sequential count of the
screen dumps starting at zero. The default value is `"vga_out"'.
screen dumps starting at zero. The default value is `"vga_out"'.
For backwards compatibility, the alternative name `filename' is
supported for this parameter, but deprecated.
 
1904,30 → 1926,31
3.4.7 Frame Buffer Configuration
--------------------------------
 
Caution: The frame buffer is only partially implemented. Its
Caution: The frame buffer is only partially implemented. Its
configuration fields are described here, but the component should
not be used at this time. Like the VGA controller, it is designed
not be used at this time. Like the VGA controller, it is designed
to make screen dumps to file.
 
Frame buffer configuration is described in `section fb'. This section
may appear multiple times, specifying multiple frame buffers. The
Frame buffer configuration is described in `section fb'. This section
may appear multiple times, specifying multiple frame buffers. The
following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this frame buffer is enabled. If 0, it
If 1 (true, the default), this frame buffer is enabled. If 0, it
is disabled.
 
`baseaddr = VALUE'
Set the base address of the frame buffer's memory mapped registers
to VALUE. The default is 0, which is probably not a sensible value.
to 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, at addresses 0x000 through 0x00c, and a PAL lookup
table at addresses 0x400 through 0x4ff. Addresses 0x010 through
table at addresses 0x400 through 0x4ff. Addresses 0x010 through
0x3fc and addresses 0x500 through 0x7ff are not used.
 
`refresh_rate = VALUE'
VALUE specifies number of cycles between screen dumps. Default
VALUE specifies number of cycles between screen dumps. Default
value is derived from the simulation clock cycle time (*note
Simulator Behavior: Simulator Behavior.), to correspond to dumping
50 times per simulated second.
1936,7 → 1959,7
FILE specifies the base of the filename for screen dumps.
Successive screen dumps will be in BMP format, in files with the
name `FILENNNN.bmp', where NNNN is a sequential count of the
screen dumps starting at zero. The default value is `"fb_out"'.
screen dumps starting at zero. The default value is `"fb_out"'.
For backwards compatibility, the alternative name `filename' is
supported for this parameter, but deprecated.
 
1947,38 → 1970,38
3.4.8 Keyboard Configuration (PS2)
----------------------------------
 
The PS2 interface provided by Or1ksim is not documented. It may be
The PS2 interface provided by Or1ksim is not documented. It may be
based on the PS2 project at OpenCores, and found in the top level CVS
directory, `ps2'. However this project lacks any documentation beyond
its project webpage. Since most PS2 interfaces follow the Intel i8042
directory, `ps2'. However this project lacks any documentation beyond
its project webpage. Since most PS2 interfaces follow the Intel i8042
standard, this is presumably what is expected with this device.
 
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.
 
Caution: A standard i8042 device has two registers at addresses
0x60 (command) and 0x64 (status). Inspection of the code, suggests
that the Or1ksim component places these registers at addresses
0x00 and 0x04.
0x60 (command) and 0x64 (status). Inspection of the code,
suggests that the Or1ksim component places these registers at
addresses 0x00 and 0x04.
 
The port of Linux for the OpenRISC 1000, which runs on Or1ksim
implements the i8042 device driver, anticipating these registers
reside at their conventional address. It seems unlikel that this
reside at their conventional address. It seems unlikel that this
code will work.
 
This component should be used with caution.
 
Keyboard configuration is described in `section kbd'. This section may
appear multiple times, specifying multiple keyboard interfaces. The
Keyboard configuration is described in `section kbd'. This section may
appear multiple times, specifying multiple keyboard interfaces. The
following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this keyboard is enabled. If 0, it is
If 1 (true, the default), this keyboard is enabled. If 0, it is
disabled.
 
`baseaddr = VALUE'
Set the base address of the keyboard's memory mapped registers to
VALUE. The default is 0, which is probably not a sensible value.
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, at addresses 0x000 and 0x004.
1988,12 → 2011,12
0x64, thus requiring at least a 7-bit bus.
 
`irq = VALUE'
Use VALUE as the IRQ number of this Keyboard interface. Default
Use VALUE as the IRQ number of this Keyboard interface. Default
value 0.
 
`rxfile = "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
`"kbd_in"'.
 
 
2005,36 → 2028,36
 
The ATA/ATAPI disc controller used in Or1ksim is the OCIDEC (OpenCores
IDE Controller) component implemented at OpenCores, and found in the
top level CVS directory, `ata'. It is described in the document
top level CVS directory, `ata'. It is described in the document
`ATA/ATAPI-5 Core Specification' by Richard Herveille, which can be
found in the `doc' subdirectory. It is a memory mapped component, which
resides on the main OpenRISC Wishbone data bus.
found in the `doc' subdirectory. It is a memory mapped component,
which resides on the main OpenRISC Wishbone data bus.
 
ATA/ATAPI configuration is described in `section ata'. This section may
appear multiple times, specifying multiple disc controllers. The
ATA/ATAPI configuration is described in `section ata'. This section
may appear multiple times, specifying multiple disc controllers. The
following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this ATA/ATAPI interface is enabled. If
If 1 (true, the default), this ATA/ATAPI interface is enabled. If
0, it is disabled.
 
`baseaddr = VALUE'
Set the base address of the ATA/ATAPI interface's memory mapped
registers to VALUE. The default is 0, which is probably not a
registers to VALUE. The default is 0, which is probably not a
sensible value.
 
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 selected (see `dev_id' below), not all registers will be
available.
32-bit registers. Depending on the version of the OCIDEC
ATA/ATAPI interface selected (see `dev_id' below), not all
registers will be available.
 
`irq = VALUE'
Use VALUE as the IRQ number of this ATA/ATAPI interface. Default
Use VALUE as the IRQ number of this ATA/ATAPI interface. Default
value 0.
 
`dev_id = 1|2|3'
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 `CTRL', `STAT' and `PCTR' registers.
Versions 2 & 3 add the `FCTR' registers, Version 3 adds the `DTR'
2042,8 → 2065,8
 
`rev = VALUE'
Set the VALUE as the revision of the OCIDEC ATA/ATAPI 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 warning.
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 warning.
This only affects the reset value of the `STAT' register, where it
forms bits 24-27.
 
2052,13 → 2075,13
`pio_mode0_t4 = VALUE'
`pio_mode0_teoc = VALUE'
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 that would be negative. The values should not exceed 255. If
if that would be negative. The values should not exceed 255. If
they do, they will be ignored with a warning.
 
See the ATA/ATAPI-5 specification for explanations of each of these
timing parameters. The default values are:
timing parameters. The default values are:
 
pio_mode0_t1 = 6
pio_mode0_t2 = 28
2071,11 → 2094,11
These parameters specify the timings for use with DMA transfers.
They 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 should not exceed 255. If they do, they will be ignored
with a warning.
The values should not exceed 255. If they do, they will be
ignored with a warning.
 
See the ATA/ATAPI-5 specification for explanations of each of these
timing parameters. The default values are:
timing parameters. The default values are:
 
dma_mode0_tm = 4
dma_mode0_td = 21
2085,15 → 2108,15
3.4.9.1 ATA/ATAPI Device Configuration
......................................
 
Within the `section ata', each device is specified separately. The
Within the `section ata', each device is specified separately. The
device subsection is introduced by
 
device VALUE
 
VALUE is the device number, which should be 0 or 1. The subsection ends
with `enddevice'. Note that if the same device number is specified more
than once, the previous values will be overwritten. Within the `device'
subsection, the following parameters may appear:
VALUE is the device number, which should be 0 or 1. The subsection
ends with `enddevice'. Note that if the same device number is
specified more than once, the previous values will be overwritten.
Within the `device' subsection, the following parameters may appear:
 
`type = VALUE'
VALUEspecifies the type of device: 0 (the default) for "not
2102,15 → 2125,15
 
`file = "FILENAME"'
`filename' specifies the file to be used for a simulated ATA
device if the file type (see `type' above) is 1. Default value
device if the file type (see `type' above) is 1. Default value
`"ata-FileN"', where N is the device number.
 
`size = VALUE'
VALUE specifies the size of a simulated ATA device if the file
type (see `type' above) is 1. The default value is zero.
type (see `type' above) is 1. The default value is zero.
 
`packet = 0|1'
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.
 
`firmware = "STR"'
2118,18 → 2141,18
Default `"02207031"'.
 
`heads = VALUE'
Number of heads in the device. Default 7, use -1 to disable all
Number of heads in the device. Default 7, use -1 to disable all
heads.
 
`sectors = VALUE'
Number of sectors per track in the device. Default 32.
Number of sectors per track in the device. Default 32.
 
`mwdma = 0|1|2|-1'
Highest multi-word DMA mode supported. Default 2, use -1 to
Highest multi-word DMA mode supported. Default 2, use -1 to
disable.
 
`pio = 0|1|2|3|4'
Highest PIO mode supported. Default 4.
Highest PIO mode supported. Default 4.
 
 

2140,22 → 2163,22
 
When used as a library (*note Simulator Library: Simulator Library.),
Or1ksim makes provision for any additional peripheral to be implemented
externally. Any read or write access to this peripheral's memory map
generates "upcall"s to an external handler. This interface can support
externally. Any read or write access to this peripheral's memory map
generates "upcall"s to an external handler. This interface can support
either C or C++, and was particularly designed to facilitate support
for OSCI SystemC (see `http://www.systemc.org').
 
Generic peripheral configuration is described in `section generic'.
This section may appear multiple times, specifying multiple external
peripherals. The following parameters may be specified.
peripherals. The following parameters may be specified.
 
`enabled = 0|1'
If 1 (true, the default), this ATA/ATAPI interface is enabled. If
If 1 (true, the default), this ATA/ATAPI interface is enabled. If
0, it is disabled.
 
`baseaddr = VALUE'
Set the base address of the generic peripheral's memory mapped
registers to VALUE. The default is 0, which is probably not a
registers to VALUE. The default is 0, which is probably not a
sensible value.
 
The size of the memory mapped register space is controlled by the
2163,20 → 2186,20
 
`size = VALUE'
Set the size of the generic peripheral's memory mapped register
space to VALUE bytes. Any read or write accesses to addresses with
space to VALUE bytes. Any read or write accesses to addresses with
offsets of 0 to VALUE-1 bytes from the base address specified in
parameter `baseaddr' (see above) will be directed to the external
interface.
 
VALUE will be rounded up the nearest power of 2. It's default
value is zero. If VALUE is not an exact power of two, accesses to
VALUE will be rounded up the nearest power of 2. It's default
value is zero. If VALUE is not an exact power of two, accesses to
address offsets of VALUE or above up to the next power of 2 will
generate a warning, and have no effect (reads will return zero).
 
`name = "STR"'
This gives the peripheral the name `"STR"'. This is used to
This gives the peripheral the name `"STR"'. This is used to
identify the peripheral in error messages and warnings, and when
reporting its status. The default value is
reporting its status. The default value is
`"anonymous external peripheral"'.
 
`byte_enabled = 0|1'
2183,7 → 2206,7
`hw_enabled = 0|1'
`word_enabled = 0|1'
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.
 
 
2194,7 → 2217,7
**************************
 
If started with the `-f' flag, or if interrupted with `ctrl-C', Or1ksim
provides the user with an interactive command line. The commands
provides the user with an interactive command line. The commands
available, which may not be abbreviated, are:
 
`q'
2201,7 → 2224,7
Exit the simulator
 
`r'
Display all the General Purpose Registers (GPRs). Also shows the
Display all the General Purpose Registers (GPRs). Also shows the
just executed and next to be executed instructions symbolically
and the state of the flag in the Supervision Register.
 
2210,7 → 2233,7
information as with the `r' command (see above).
 
`run NUM [ hush ]'
Execute NUM instructions. The register/instruction information is
Execute NUM instructions. The register/instruction information is
displayed after each instruction, as with the `r' command (see
above) _unless_ `hush' is specified.
 
2218,17 → 2241,17
Patch register REG with VALUE.
 
`dm FROMADDR [ TOADDR ]'
Display memory bytes between FROMADDR and TOADDR. If TOADDR is not
given, 64 bytes are displayed, starting at FROMADDR.
Display memory bytes between FROMADDR and TOADDR. If TOADDR is
not given, 64 bytes are displayed, starting at FROMADDR.
 
Caution: The output from this command is broken (a bug).
Or1ksim attempts to print out 16 bytes per row. However,
Or1ksim 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 the first of the 16 bytes) before
_each_ byte.
 
`de FROMADDR [ TOADDR ]'
Disassemble code between FROMADDR and TOADDR. If TOADDR is not
Disassemble code between FROMADDR and TOADDR. If TOADDR is not
given, 16 instructions are disassembled.
 
The disassembly is entirely numerical, and gives no symbolic
2250,8 → 2273,8
List all set breakpoints
 
`reset'
Reset the simulator. Includes modeling a reset of the processor, so
execution will restart from the reset vector location, 0x100.
Reset the simulator. Includes modeling a reset of the processor,
so execution will restart from the reset vector location, 0x100.
 
`hist'
If saving the execution history has been configured (*note
2260,18 → 2283,18
 
`stall'
Stall the processor, so that control is passed to the debug unit.
When stalled, the processor can execute no instructions. This
When stalled, the processor can execute no instructions. This
command is useful when debugging the JTAG interface, used by
debuggers such as GDB.
 
`unstall'
Unstall the processor, so that normal execution can continue. This
command is useful when debugging the JTAG interface, used by
Unstall the processor, so that normal execution can continue.
This command is useful when debugging the JTAG interface, used by
debuggers such as GDB.
 
`stats CATEGORY | clear'
Print the statistics for the given CATEGORY, if available, or
clear if `clear' is specified. The categories are:
clear if `clear' is specified. The categories are:
 
1
Miscellaneous statistics: branch predictions (if branch
2284,24 → 2307,24
various features.
 
2
Instruction usage statistics. Requires hazard analysis to be
Instruction usage statistics. Requires hazard analysis to be
enabled (*note CPU Configuration: CPU Configuration.).
 
3
Instruction dependency statistics. Requires hazard analysis
Instruction dependency statistics. Requires hazard analysis
to be enabled (*note CPU Configuration: CPU Configuration.).
 
4
Functional unit dependency statistics. Requires hazard
Functional unit dependency statistics. Requires hazard
analysis to be enabled (*note CPU Configuration: CPU
Configuration.).
 
5
Raw register usage over time. Requires hazard analysis to be
Raw register usage over time. Requires hazard analysis to be
enabled (*note CPU Configuration: CPU Configuration.).
 
6
Store buffer statistics. Requires the store buffer to be
Store buffer statistics. Requires the store buffer to be
enabled (*note CPU Configuration: CPU Configuration.).
 
 
2312,9 → 2335,9
 
`dv FROMADDR [ TOADDR ] [ MODULE ]'
Dump the area of memory between FROMADDR and TOADDR as Verilog
code for a synchronous, 23-bit wide SRAM module, named MODULE. If
code for a synchronous, 23-bit wide SRAM module, named MODULE. If
TOADDR is not specified, then 64 bytes are dumped (as 16 32-bit
words). If MODULE is not specified, `or1k_mem' is used.
words). If MODULE is not specified, `or1k_mem' is used.
 
To save to a file, use the redirection function (described after
this table, below).
2321,7 → 2344,7
 
`dh FROMADDR [ TOADDR ]'
Dump the area of memory between FROMADDR and TOADDR as 32-bit hex
numbers (no `0x', or `32'h' prefix). If TOADDR is not specified,
numbers (no `0x', or `32'h' prefix). If TOADDR is not specified,
then 64 bytes are dumped (as 16 32-bit words).
 
To save to a file, use the redirection function (described after
2328,7 → 2351,7
this table, below).
 
`setdbch'
Toggle debug channels on/off. *Note Standalone Simulator:
Toggle debug channels on/off. *Note Standalone Simulator:
Standalone Simulator, for a description of specifying debug
channels on the command line.
 
2338,12 → 2361,12
parameters and their settings.
 
`debug'
Toggle the simulator debug mode. *Note Debug Interface
Toggle the simulator debug mode. *Note Debug Interface
Configuration: Debug Interface Configuration, for information on
this parameter.
 
Caution: This is effectively enabling or disabling the debug
unit. It does not effect the remote GDB debug interface.
unit. It does not effect the remote GDB debug interface.
However using the remote debug interface while the debug unit
is disabled will lead to undefined behavior and likely crash
Or1ksim
2353,21 → 2376,21
Configuration: CUC Configuration.).
 
Caution: The CUC must be properly configured, for this to
succeed. In particular a timing file must be available and
readable. Otherwise Or1ksim will crash.
succeed. In particular a timing file must be available and
readable. Otherwise Or1ksim will crash.
 
`help'
Print out brief information about each command available.
 
`mprofile [-vh] [-m M] [-g N] [-f FILE] FROM TO'
Run the memory profiling utility. This follows the same usage as
Run the memory profiling utility. This follows the same usage as
the standalone command (*note Memory Profiling Utility: Memory
Profiling Utility.).
 
`profile [-vhcq] [-g FILE]'
Run the instruction profiling utility. This follows the same usage
as the standalone command (*note Profiling Utility: Profiling
Utility.).
Run the instruction profiling utility. This follows the same
usage as the standalone command (*note Profiling Utility:
Profiling Utility.).
 
 
For all commands, it is possible to redirect the output to a file, by
2379,8 → 2402,8
output, such as `dv'.
 
Caution: Unfortunately there is a serious bug with the redirection
operator. It does not return output to standard output after the
command completes. Until this bug is fixed, file redirection
operator. It does not return output to standard output after the
command completes. Until this bug is fixed, file redirection
should not be used.
 

2390,21 → 2413,21
*************************
 
The Verification API (VAPI) provides a TCP/IP interface to allow
components of the simulation to be controlled externally. The interface
is polled for new requests on each simulated clock cycle. Components
within the simulator may send responses to such requests.
components of the simulation to be controlled externally. The
interface is polled for new requests on each simulated clock cycle.
Components within the simulator may send responses to such requests.
 
The inteface is an asynchronous duplex protocol. On the request side 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,
it provides for sending a single VAPI ID and data. However there is no
explicit command-response structure. Some components just accept
requests (e.g. to set values), some just generate sends (to report
The inteface is an asynchronous duplex protocol. On the request side
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,
it provides for sending a single VAPI ID and data. However there is no
explicit command-response structure. Some components just accept
requests (e.g. to set values), some just generate sends (to report
values), and some do both.
 
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
amongst components. Request commands will be directed to the component
that base ID. This provides a simple partitioning of the command space
amongst components. Request commands will be directed to the component
with 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
2450,9 → 2473,9
 
`0x04'
If the 16th most significant bit of the data is 1, start
sending breaks, otherwise stop sending breaks. The breaks are
sent or cleared after the number of UART clock divider ticks
specified by the data (immediately if the data is zero).
sending breaks, otherwise stop sending breaks. The breaks
are sent or cleared after the number of UART clock divider
ticks specified by the data (immediately if the data is zero).
 
 
DMA
2461,9 → 2484,9
implemented.
 
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
Ethernet. At present no implementation is provided behind these
Ethernet. At present no implementation is provided behind these
VAPI requests.
 
`ETH_VAPI_DATA (0)'
2475,7 → 2498,7
VAPI ID (symbolically, GPIO_VAPI_DATA (0) offset from the base
VAPI ID) any 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
GPIO.
 
2512,10 → 2535,10
6 A Guide to Or1ksim Internals
******************************
 
These are notes to help those wanting to extend Or1ksim. This section
These are notes to help those wanting to extend Or1ksim. This 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
Linux manual page for `etags'. A tag file can be created with:
definitions are not in general provided. For more on tags, see the
Linux manual page for `etags'. A tag file can be created with:
 
make tags
 
2537,7 → 2560,7
 
_GNU Coding Standard_
Code should follow the GNU coding standard for C
(`http://www.gnu.org/prep/standards/'. If in doubt, put your code
(`http://www.gnu.org/prep/standards/'. If in doubt, put your code
through the `indent' program.
 
_`#include' headers_
2552,8 → 2575,8
be included after the system headers.
 
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 having already included it. The two exceptions are
system or package header they depend on, i.e. not rely on any
other header having already included it. The two exceptions are
 
1. All header files may assume that `config.h' has already been
included.
2560,7 → 2583,7
 
2. System headers which impose portability problems should be
included by using the package header `port.h', rather than
the system headers themselves. This is the case for code
the system headers themselves. This is the case for code
requiring
 
* `strndup' (from `string.h')
2573,7 → 2596,7
 
_`#include' files once only_
All include files should be protected by `#ifndef' to ensure their
definitions are only included once. For instance a header file
definitions are only included once. For instance a header file
`X-Y.H' should surround its contents with:
 
#ifndef X_Y__H
2585,9 → 2608,9
 
_Avoid `typedef'_
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
`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 `typedef' declarations in the `argtable2' library
and the ELF and COFF headers, because this code is taken from
2609,12 → 2632,12
 
 
Where new types are defined, they should appear in one of these two
files as appropriate. Or1ksim specific types appearing in `arch.h'
should always have the suffix `_h'.
files as appropriate. Or1ksim specific types appearing in
`arch.h' should always have the suffix `_h'.
 
_Don't begin names with underscore_
Names beginning with `_' 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.
 
_Keep Non-global top level entities static_
All top level entities (functions, variables), which are not
2623,16 → 2646,16
across the program.
 
_Use of `inline'_
Code should not be declared `inline'. Modern compilers can work
Code should not be declared `inline'. Modern compilers can work
out for themselves what is best in this respect.
 
_Initialization_
All data structures should be explicitly initialized. In particular
code should not rely on static data structures being initialized to
zero.
All data structures should be explicitly initialized. In
particular code should not rely on static data structures being
initialized to zero.
 
The rationale is that in future static data structures may become
dynamic. This has been a particular source of bugs in Or1ksim
dynamic. This has been a particular source of bugs in Or1ksim
historically.
 
A specific case is with new peripherals, which should always
2654,7 → 2677,7
`config'
The global variable `config' of type `struct config' holds the
configuration data for some of the Or1ksim components which are
always present. At present the components are:
always present. At present the components are:
 
* The simulator defined in `section sim' (*note Simulator
Configuration: Simulator Configuration.).
2690,21 → 2713,21
 
 
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
`config.sim'.
 
`config'
This is a linked list of data structures holding configuration data
for all sections which are not held in the main `config' data
structure. In general these are components (such as peripherals and
memory) which may occur multiple times. However it also handles
some architectural components which may occur only once, such as
the memory management units, the instruction cache, the interrupt
controller and branch prediction.
structure. In general these are components (such as peripherals
and memory) which may occur multiple times. However it also
handles some architectural components which may occur only once,
such as the memory management units, the instruction cache, the
interrupt controller and branch prediction.
 
`runtime'
The global variable `runtime' of type `struct runtime' holds all
the runtime information about the simulation. To access this
the runtime information about the simulation. To access this
variable, `sim-config.h' must be included.
 
This struct is itself made of 3 other structs, `cpu' (for CPU run
2719,7 → 2742,7
============
 
_Output Redirection_
The current output stream is held in `runtime.cpu.fout'. Output
The current output stream is held in `runtime.cpu.fout'. Output
should be explicitly written to this stream, or may use the
`PRINTF' macro, which will write its arguments to this output
stream.
2727,7 → 2750,7
_Reset Hooks_
Any peripheral may register a routine to be called when the the
processor is reset by calling `reg_sim_reset', providing a
function and pointer to a data structure as arguments. On reset
function and pointer to a data structure as arguments. On reset
that function will be called with the data stucture pointer as
argument.
 
2739,11 → 2762,11
======================
 
The function `debug' is like `printf', but with an extra first
argument, which is the debug level. If the debug level specified in the
simulator configuration (*note Simulator Behavior: Simulator Behavior.)
is greater than or equal to this value, the remaining arguments are
printed to the current output stream (*note Output Redirection: Output
Redirection.).
argument, which is the debug level. If the debug level specified in
the simulator configuration (*note Simulator Behavior: Simulator
Behavior.) is greater than or equal to this value, the remaining
arguments are printed to the current output stream (*note Output
Redirection: Output Redirection.).
 

File: or1ksim.info, Node: GNU Free Documentation License, Next: Index, Prev: Code Internals, Up: Top
3189,6 → 3212,8
* --cumulative: Profiling Utility. (line 26)
* --debug-config: Standalone Simulator.
(line 48)
* --disable-all-tests: Configuring the Build.
(line 128)
* --disable-arith-flag: Configuring the Build.
(line 93)
* --disable-debug: Configuring the Build.
3201,6 → 3226,8
(line 25)
* --disable-range-stats: Configuring the Build.
(line 64)
* --enable-all-tests: Configuring the Build.
(line 127)
* --enable-arith-flag: Configuring the Build.
(line 92)
* --enable-debug: Configuring the Build.
3283,6 → 3310,8
* 0x04 UART VAPI sub-command (UART verification): Verification API.
(line 66)
* 16550 (UART configuration): UART Configuration. (line 73)
* all tests enabled: Configuring the Build.
(line 128)
* Argtable2 debugging: Configuring the Build.
(line 121)
* ATA/ATAPI configuration: Disc Interface Configuration.
3306,7 → 3335,7
* baseaddr (memory configuration): Memory Configuration.
(line 62)
* baseaddr (memory controller configuration): Memory Controller Configuration.
(line 28)
(line 29)
* baseaddr (UART configuration): UART Configuration. (line 22)
* baseaddr (VGA configuration): Display Interface Configuration.
(line 26)
3330,12 → 3359,12
* cache configuration: Cache Configuration. (line 6)
* calling_convention (CUC configuration): CUC Configuration. (line 34)
* ce (memory configuration): Memory Configuration.
(line 91)
(line 92)
* cfgr (CPU configuration): CPU Configuration. (line 47)
* channel (UART configuration): UART Configuration. (line 29)
* clear breakpoint (Interactive CLI): Interactive Command Line.
(line 57)
* clkcycle (simulator configuration): Simulator Behavior. (line 102)
* clkcycle (simulator configuration): Simulator Behavior. (line 103)
* cm (Interactive CLI): Interactive Command Line.
(line 54)
* command line for Or1ksim standalone use: Standalone Simulator.
3439,9 → 3468,9
* debugging enabled (Argtable2): Configuring the Build.
(line 121)
* delayr (memory configuration): Memory Configuration.
(line 109)
(line 110)
* delayw (memory configuration): Memory Configuration.
(line 115)
(line 116)
* dependstats (CPU configuration): CPU Configuration. (line 84)
* dev_id (ATA/ATAPI configuration): Disc Interface Configuration.
(line 36)
3506,7 → 3535,7
* enabled (keyboard configuration): Keyboard Configuration.
(line 32)
* enabled (memory controller configuration): Memory Controller Configuration.
(line 17)
(line 18)
* enabled (MMU configuration): Memory Management Configuration.
(line 12)
* enabled (power management configuration): Power Management Configuration.
3527,24 → 3556,24
* Ethernet verification (VAPI): Verification API. (line 78)
* Ethernet via socket, enabling: Configuring the Build.
(line 54)
* exe_log (simulator configuration): Simulator Behavior. (line 48)
* exe_log_end (simulator configuration): Simulator Behavior. (line 88)
* exe_log_file (simulator configuration): Simulator Behavior. (line 96)
* exe_log (simulator configuration): Simulator Behavior. (line 49)
* exe_log_end (simulator configuration): Simulator Behavior. (line 89)
* exe_log_file (simulator configuration): Simulator Behavior. (line 97)
* exe_log_fn (simulator configuration - deprecated): Simulator Behavior.
(line 96)
(line 97)
* exe_log_marker (simulator configuration): Simulator Behavior.
(line 92)
(line 93)
* exe_log_start (simulator configuration): Simulator Behavior.
(line 85)
* exe_log_type (simulator configuration): Simulator Behavior. (line 54)
(line 86)
* exe_log_type (simulator configuration): Simulator Behavior. (line 55)
* exe_log_type=default (simulator configuration): Simulator Behavior.
(line 57)
(line 58)
* exe_log_type=hardware (simulator configuration): Simulator Behavior.
(line 61)
(line 62)
* exe_log_type=simple (simulator configuration): Simulator Behavior.
(line 68)
(line 69)
* exe_log_type=software (simulator configuration): Simulator Behavior.
(line 73)
(line 74)
* executing code (Interactive CLI): Interactive Command Line.
(line 23)
* execution history (Interactive CLI): Interactive Command Line.
3554,7 → 3583,7
* file (keyboard configuration): Keyboard Configuration.
(line 51)
* filename (frame buffer configuration - deprecated): Frame Buffer Configuration.
(line 35)
(line 36)
* filename (VGA configuration - deprecated): Display Interface Configuration.
(line 47)
* firmware (ATA/ATAPI device configuration): Disc Interface Configuration.
3587,7 → 3616,7
(line 36)
* hist (Interactive CLI): Interactive Command Line.
(line 67)
* history (simulator configuration): Simulator Behavior. (line 39)
* history (simulator configuration): Simulator Behavior. (line 40)
* history of execution (Interactive CLI): Interactive Command Line.
(line 67)
* hitdelay (branch prediction configuration): Branch Prediction Configuration.
3601,7 → 3630,7
* IMMU configuration: Memory Management Configuration.
(line 6)
* index (memory controller configuration): Memory Controller Configuration.
(line 50)
(line 51)
* info (Interactive CLI): Interactive Command Line.
(line 119)
* installing Or1ksim: Installation. (line 6)
3636,12 → 3665,12
* load_missdelay (data cache configuration): Cache Configuration.
(line 50)
* log (memory configuration): Memory Configuration.
(line 121)
(line 122)
* log_enabled (verification API configuration): Verification API Configuration.
(line 28)
* long: Simulator Library. (line 73)
* long: Simulator Library. (line 74)
* mc (memory configuration): Memory Configuration.
(line 99)
(line 100)
* memory configuration: Memory Configuration.
(line 6)
* memory controller configuration: Memory Controller Configuration.
3677,18 → 3706,18
(line 55)
* MMU configuration: Memory Management Configuration.
(line 6)
* mprof_file (simulator configuration): Simulator Behavior. (line 33)
* mprof_file (simulator configuration): Simulator Behavior. (line 34)
* mprof_fn (simulator configuration - deprecated): Simulator Behavior.
(line 33)
(line 34)
* mprofile (Interactive CLI): Interactive Command Line.
(line 173)
* mprofile (simulator configuration): Simulator Behavior. (line 28)
* mprofile (simulator configuration): Simulator Behavior. (line 29)
* mwdma (ATA/ATAPI device configuration): Disc Interface Configuration.
(line 128)
* name (generic peripheral configuration): Generic Peripheral Configuration.
(line 42)
* name (memory configuration): Memory Configuration.
(line 82)
(line 83)
* no_multicycle (CUC configuration): CUC Configuration. (line 42)
* nsets (cache configuration): Cache Configuration. (line 15)
* nsets (MMU configuration): Memory Management Configuration.
3696,15 → 3725,15
* nways (cache configuration): Cache Configuration. (line 22)
* nways (MMU configuration): Memory Management Configuration.
(line 22)
* or1ksim_get_time_period: Simulator Library. (line 63)
* or1ksim_get_time_period: Simulator Library. (line 64)
* or1ksim_init: Simulator Library. (line 18)
* or1ksim_interrupt: Simulator Library. (line 78)
* or1ksim_interrupt_clear: Simulator Library. (line 96)
* or1ksim_interrupt_set: Simulator Library. (line 87)
* or1ksim_is_le: Simulator Library. (line 68)
* or1ksim_reset_duration: Simulator Library. (line 48)
* or1ksim_run: Simulator Library. (line 43)
* or1ksim_set_time_point: Simulator Library. (line 59)
* or1ksim_interrupt: Simulator Library. (line 79)
* or1ksim_interrupt_clear: Simulator Library. (line 97)
* or1ksim_interrupt_set: Simulator Library. (line 88)
* or1ksim_is_le: Simulator Library. (line 69)
* or1ksim_reset_duration: Simulator Library. (line 49)
* or1ksim_run: Simulator Library. (line 44)
* or1ksim_set_time_point: Simulator Library. (line 60)
* output rediretion: Concepts. (line 7)
* overflow flag setting by instructions: Configuring the Build.
(line 70)
3749,7 → 3778,7
* PMU configuration: Power Management Configuration.
(line 6)
* poc (memory controller configuration): Memory Controller Configuration.
(line 37)
(line 38)
* port range for TCP/IP: Verification API Configuration.
(line 23)
* power management configuration: Power Management Configuration.
3795,7 → 3824,7
* random_seed (memory configuration): Memory Configuration.
(line 40)
* refresh_rate (frame buffer configuration): Frame Buffer Configuration.
(line 29)
(line 30)
* refresh_rate (VGA configuration): Display Interface Configuration.
(line 41)
* reg_sim_reset: Concepts. (line 13)
3953,6 → 3982,8
(line 74)
* TCP/IP port range for or1ksim-rsp service: Debug Interface Configuration.
(line 41)
* tests, all enabled.: Configuring the Build.
(line 128)
* timings_file (CUC configuration): CUC Configuration. (line 46)
* timings_fn (CUC configuration - deprecated): CUC Configuration.
(line 46)
3967,7 → 3998,7
* txfile (Ethernet configuration): Ethernet Configuration.
(line 69)
* txfile (frame buffer configuration): Frame Buffer Configuration.
(line 35)
(line 36)
* txfile (VGA configuration): Display Interface Configuration.
(line 47)
* type (ATA/ATAPI device configuration): Disc Interface Configuration.
4033,51 → 4064,51
Node: Top814
Node: Installation1224
Node: Preparation1471
Node: Configuring the Build1761
Node: Build and Install6872
Node: Known Issues7561
Node: Usage9691
Node: Standalone Simulator9905
Node: Profiling Utility12794
Node: Memory Profiling Utility13702
Node: Simulator Library15061
Node: Configuration20523
Node: Configuration File Format21129
Node: Configuration File Preprocessing21421
Node: Configuration File Syntax21791
Node: Simulator Configuration24569
Node: Simulator Behavior24860
Node: Verification API Configuration28876
Node: CUC Configuration30805
Node: Core OpenRISC Configuration32710
Node: CPU Configuration33212
Node: Memory Configuration37002
Node: Memory Management Configuration42278
Node: Cache Configuration44639
Node: Interrupt Configuration47005
Node: Power Management Configuration47737
Node: Branch Prediction Configuration49009
Node: Debug Interface Configuration50362
Node: Peripheral Configuration54562
Node: Memory Controller Configuration55187
Node: UART Configuration57784
Node: DMA Configuration61290
Node: Ethernet Configuration63145
Node: GPIO Configuration67101
Node: Display Interface Configuration68724
Node: Frame Buffer Configuration71024
Node: Keyboard Configuration72874
Node: Disc Interface Configuration75100
Node: Generic Peripheral Configuration80015
Node: Interactive Command Line82299
Node: Verification API89247
Node: Code Internals93665
Node: Coding Conventions94222
Node: Global Data Structures98637
Node: Concepts101289
Ref: Output Redirection101434
Node: Internal Debugging101971
Node: GNU Free Documentation License102467
Node: Index124874
Node: Configuring the Build1772
Node: Build and Install7257
Node: Known Issues8103
Node: Usage10249
Node: Standalone Simulator10463
Node: Profiling Utility13366
Node: Memory Profiling Utility14276
Node: Simulator Library15641
Node: Configuration21126
Node: Configuration File Format21735
Node: Configuration File Preprocessing22027
Node: Configuration File Syntax22398
Node: Simulator Configuration25183
Node: Simulator Behavior25474
Node: Verification API Configuration29518
Node: CUC Configuration31458
Node: Core OpenRISC Configuration33375
Node: CPU Configuration33877
Node: Memory Configuration37682
Node: Memory Management Configuration42995
Node: Cache Configuration45372
Node: Interrupt Configuration47758
Node: Power Management Configuration48494
Node: Branch Prediction Configuration49771
Node: Debug Interface Configuration51131
Node: Peripheral Configuration55351
Node: Memory Controller Configuration55977
Node: UART Configuration58582
Node: DMA Configuration62101
Node: Ethernet Configuration63968
Node: GPIO Configuration67946
Node: Display Interface Configuration69579
Node: Frame Buffer Configuration71888
Node: Keyboard Configuration73752
Node: Disc Interface Configuration75990
Node: Generic Peripheral Configuration80933
Node: Interactive Command Line83228
Node: Verification API90202
Node: Code Internals94632
Node: Coding Conventions95192
Node: Global Data Structures99619
Node: Concepts102276
Ref: Output Redirection102421
Node: Internal Debugging102960
Node: GNU Free Documentation License103457
Node: Index125864

End Tag Table
/Makefile.in
1,8 → 1,9
# Makefile.in generated by automake 1.10.1 from Makefile.am.
# Makefile.in generated by automake 1.11.1 from Makefile.am.
# @configure_input@
 
# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation,
# Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
36,8 → 37,9
# with this program. If not, see <http://www.gnu.org/licenses/>.
VPATH = @srcdir@
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibexecdir = $(libexecdir)/@PACKAGE@
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
58,12 → 60,16
$(srcdir)/Makefile.in $(srcdir)/stamp-vti \
$(srcdir)/version.texi mdate-sh texinfo.tex
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/configure.ac
am__aclocal_m4_deps = $(top_srcdir)/m4/libtool.m4 \
$(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \
$(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \
$(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
CONFIG_HEADER = $(top_builddir)/config.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
SOURCES =
DIST_SOURCES =
INFO_DEPS = $(srcdir)/or1ksim.info
84,7 → 90,22
$(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
*) f=$$p;; \
esac;
am__strip_dir = `echo $$p | sed -e 's|^.*/||'`;
am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
am__install_max = 40
am__nobase_strip_setup = \
srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
am__nobase_strip = \
for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
am__nobase_list = $(am__nobase_strip_setup); \
for p in $$list; do echo "$$p $$p"; done | \
sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
$(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
if (++n[$$2] == $(am__install_max)) \
{ print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
END { for (dir in files) print dir, files[dir] }'
am__base_list = \
sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
AMTAR = @AMTAR@
96,27 → 117,26
AWK = @AWK@
BUILD_DIR = @BUILD_DIR@
CC = @CC@
CCAS = @CCAS@
CCASDEPMODE = @CCASDEPMODE@
CCASFLAGS = @CCASFLAGS@
CCDEPMODE = @CCDEPMODE@
CFLAGS = @CFLAGS@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CPU_ARCH = @CPU_ARCH@
CXX = @CXX@
CXXCPP = @CXXCPP@
CXXDEPMODE = @CXXDEPMODE@
CXXFLAGS = @CXXFLAGS@
CYGPATH_W = @CYGPATH_W@
DEBUGFLAGS = @DEBUGFLAGS@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
ECHO = @ECHO@
DSYMUTIL = @DSYMUTIL@
DUMPBIN = @DUMPBIN@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EGREP = @EGREP@
EXEEXT = @EXEEXT@
F77 = @F77@
FFLAGS = @FFLAGS@
FGREP = @FGREP@
GREP = @GREP@
INCLUDES = @INCLUDES@
INSTALL = @INSTALL@
124,10 → 144,12
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
LD = @LD@
LDFLAGS = @LDFLAGS@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIBTOOL = @LIBTOOL@
LIPO = @LIPO@
LN_S = @LN_S@
LOCAL_CFLAGS = @LOCAL_CFLAGS@
LOCAL_DEFS = @LOCAL_DEFS@
136,7 → 158,12
MAKEINFO = @MAKEINFO@
MAKE_SHELL = @MAKE_SHELL@
MKDIR_P = @MKDIR_P@
NM = @NM@
NMEDIT = @NMEDIT@
OBJDUMP = @OBJDUMP@
OBJEXT = @OBJEXT@
OTOOL = @OTOOL@
OTOOL64 = @OTOOL64@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
153,13 → 180,13
SUMVERSION = @SUMVERSION@
TERMCAP_LIB = @TERMCAP_LIB@
VERSION = @VERSION@
_GNU_SOURCE = @_GNU_SOURCE@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
abs_top_builddir = @abs_top_builddir@
abs_top_srcdir = @abs_top_srcdir@
ac_ct_CC = @ac_ct_CC@
ac_ct_CXX = @ac_ct_CXX@
ac_ct_F77 = @ac_ct_F77@
ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
190,6 → 217,7
libexecdir = @libexecdir@
localedir = @localedir@
localstatedir = @localstatedir@
lt_ECHO = @lt_ECHO@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
200,6 → 228,7
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
subdirs = @subdirs@
sysconfdir = @sysconfdir@
target = @target@
target_alias = @target_alias@
206,6 → 235,7
target_cpu = @target_cpu@
target_os = @target_os@
target_vendor = @target_vendor@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
info_TEXINFOS = or1ksim.texi
223,14 → 253,14
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \
&& exit 0; \
( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
&& { if test -f $@; then exit 0; else break; fi; }; \
exit 1;; \
esac; \
done; \
echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \
cd $(top_srcdir) && \
$(AUTOMAKE) --gnu doc/Makefile
echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --gnu doc/Makefile
.PRECIOUS: Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
248,6 → 278,7
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(ACLOCAL_M4): $(am__aclocal_m4_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(am__aclocal_m4_deps):
 
mostlyclean-libtool:
-rm -f *.lo
257,7 → 288,7
 
.texi.info:
restore=: && backupdir="$(am__leading_dot)am$$$$" && \
am__cwd=`pwd` && cd $(srcdir) && \
am__cwd=`pwd` && $(am__cd) $(srcdir) && \
rm -rf $$backupdir && mkdir $$backupdir && \
if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
269,10 → 300,10
-o $@ $<; \
then \
rc=0; \
cd $(srcdir); \
$(am__cd) $(srcdir); \
else \
rc=$$?; \
cd $(srcdir) && \
$(am__cd) $(srcdir) && \
$$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
fi; \
rm -rf $$backupdir; exit $$rc
329,8 → 360,9
 
uninstall-dvi-am:
@$(NORMAL_UNINSTALL)
@list='$(DVIS)'; for p in $$list; do \
f=$(am__strip_dir) \
@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
rm -f "$(DESTDIR)$(dvidir)/$$f"; \
done
337,8 → 369,9
 
uninstall-html-am:
@$(NORMAL_UNINSTALL)
@list='$(HTMLS)'; for p in $$list; do \
f=$(am__strip_dir) \
@list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
done
352,7 → 385,8
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
done; \
else :; fi
@$(NORMAL_UNINSTALL)
368,8 → 402,9
 
uninstall-pdf-am:
@$(NORMAL_UNINSTALL)
@list='$(PDFS)'; for p in $$list; do \
f=$(am__strip_dir) \
@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
done
376,8 → 411,9
 
uninstall-ps-am:
@$(NORMAL_UNINSTALL)
@list='$(PSS)'; for p in $$list; do \
f=$(am__strip_dir) \
@list='$(PSS)'; test -n "$(psdir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
rm -f "$(DESTDIR)$(psdir)/$$f"; \
done
394,18 → 430,21
for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
if test -f $$file; then \
relfile=`expr "$$file" : "$$d/\(.*\)"`; \
test -f $(distdir)/$$relfile || \
cp -p $$file $(distdir)/$$relfile; \
test -f "$(distdir)/$$relfile" || \
cp -p $$file "$(distdir)/$$relfile"; \
else :; fi; \
done; \
done
 
mostlyclean-aminfo:
-rm -rf or1ksim.aux or1ksim.cp or1ksim.cps or1ksim.fn or1ksim.ky or1ksim.kys \
or1ksim.log or1ksim.pg or1ksim.pgs or1ksim.tmp or1ksim.toc \
or1ksim.tp or1ksim.tps or1ksim.vr or1ksim.dvi or1ksim.pdf \
or1ksim.ps or1ksim.html
-rm -rf or1ksim.aux or1ksim.cp or1ksim.cps or1ksim.fn or1ksim.ky \
or1ksim.kys or1ksim.log or1ksim.pg or1ksim.pgs or1ksim.tmp \
or1ksim.toc or1ksim.tp or1ksim.tps or1ksim.vr
 
clean-aminfo:
-test -z "or1ksim.dvi or1ksim.pdf or1ksim.ps or1ksim.html" \
|| rm -rf or1ksim.dvi or1ksim.pdf or1ksim.ps or1ksim.html
 
maintainer-clean-aminfo:
@list='$(INFO_DEPS)'; for i in $$list; do \
i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \
435,13 → 474,17
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
if test -d $$d/$$file; then \
dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
if test -d "$(distdir)/$$file"; then \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
else \
test -f $(distdir)/$$file \
|| cp -p $$d/$$file $(distdir)/$$file \
test -f "$(distdir)/$$file" \
|| cp -p $$d/$$file "$(distdir)/$$file" \
|| exit 1; \
fi; \
done
475,6 → 518,7
 
distclean-generic:
-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
 
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
481,7 → 525,7
@echo "it deletes files that may require special tools to rebuild."
clean: clean-am
 
clean-am: clean-generic clean-libtool mostlyclean-am
clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am
 
distclean: distclean-am
-rm -f Makefile
506,11 → 550,14
install-dvi-am: $(DVIS)
@$(NORMAL_INSTALL)
test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)"
@list='$(DVIS)'; for p in $$list; do \
@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f=$(am__strip_dir) \
echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \
$(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
done
install-exec-am:
 
519,19 → 566,24
install-html-am: $(HTMLS)
@$(NORMAL_INSTALL)
test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)"
@list='$(HTMLS)'; for p in $$list; do \
@list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
for p in $$list; do \
if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
f=$(am__strip_dir) \
$(am__strip_dir) \
if test -d "$$d$$p"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
$(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \
$(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \
$(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
else \
echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \
$(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \
list2="$$list2 $$d$$p"; \
fi; \
done
done; \
test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
done; }
install-info: install-info-am
 
install-info-am: $(INFO_DEPS)
538,7 → 590,7
@$(NORMAL_INSTALL)
test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)"
@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
list='$(INFO_DEPS)'; \
list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
for file in $$list; do \
case $$file in \
$(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
546,18 → 598,19
if test -f $$file; then d=.; else d=$(srcdir); fi; \
file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \
for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \
$$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
$$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
if test -f $$ifile; then \
relfile=`echo "$$ifile" | sed 's|^.*/||'`; \
echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \
$(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \
echo "$$ifile"; \
else : ; fi; \
done; \
done
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
@$(POST_INSTALL)
@if (install-info --version && \
install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \
list='$(INFO_DEPS)'; \
list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\
571,23 → 624,27
install-pdf-am: $(PDFS)
@$(NORMAL_INSTALL)
test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)"
@list='$(PDFS)'; for p in $$list; do \
@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f=$(am__strip_dir) \
echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \
$(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \
done
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
install-ps: install-ps-am
 
install-ps-am: $(PSS)
@$(NORMAL_INSTALL)
test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)"
@list='$(PSS)'; for p in $$list; do \
@list='$(PSS)'; test -n "$(psdir)" || list=; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f=$(am__strip_dir) \
echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \
$(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \
done
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
installcheck-am:
 
maintainer-clean: maintainer-clean-am
613,10 → 670,10
 
.MAKE: install-am install-strip
 
.PHONY: all all-am check check-am clean clean-generic clean-libtool \
dist-info distclean distclean-generic distclean-libtool \
distdir dvi dvi-am html html-am info info-am install \
install-am install-data install-data-am install-dvi \
.PHONY: all all-am check check-am clean clean-aminfo clean-generic \
clean-libtool dist-info distclean distclean-generic \
distclean-libtool distdir dvi dvi-am html html-am info info-am \
install install-am install-data install-data-am install-dvi \
install-dvi-am install-exec install-exec-am install-html \
install-html-am install-info install-info-am install-man \
install-pdf install-pdf-am install-ps install-ps-am \
628,6 → 685,7
uninstall-dvi-am uninstall-html-am uninstall-info-am \
uninstall-pdf-am uninstall-ps-am
 
 
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
/mdate-sh
1,10 → 1,10
#!/bin/sh
# Get modification time of a file or directory and pretty-print it.
 
scriptversion=2007-03-30.02
scriptversion=2009-04-28.21; # UTC
 
# Copyright (C) 1995, 1996, 1997, 2003, 2004, 2005, 2007 Free Software
# Foundation, Inc.
# Copyright (C) 1995, 1996, 1997, 2003, 2004, 2005, 2007, 2009 Free
# Software Foundation, Inc.
# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995
#
# This program is free software; you can redistribute it and/or modify
18,8 → 18,7
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software Foundation,
# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
# along with this program. If not, see <http://www.gnu.org/licenses/>.
 
# As a special exception to the GNU General Public License, if you
# distribute this file as part of a program that contains a
201,5 → 200,6
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
# time-stamp-end: "$"
# time-stamp-time-zone: "UTC"
# time-stamp-end: "; # UTC"
# End:
/texinfo.tex
1,13 → 1,13
% texinfo.tex -- TeX macros to handle Texinfo files.
%
%
% Load plain if necessary, i.e., if running under initex.
\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
%
\def\texinfoversion{2007-12-02.17}
\def\texinfoversion{2009-08-14.15}
%
% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, 2007,
% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
% 2007 Free Software Foundation, Inc.
% 2007, 2008, 2009 Free Software Foundation, Inc.
%
% This texinfo.tex file is free software: you can redistribute it and/or
% modify it under the terms of the GNU General Public License as
97,6 → 97,10
\let\ptexslash=\/
\let\ptexstar=\*
\let\ptext=\t
\let\ptextop=\top
{\catcode`\'=\active
\global\let\ptexquoteright'}% Math-mode def from plain.tex.
\let\ptexraggedright=\raggedright
 
% If this character appears in an error message or help string, it
% starts a new line in the output.
354,7 → 358,7
% We don't want .vr (or whatever) entries like this:
% \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}}
% "\acronym" won't work when it's read back in;
% it needs to be
% it needs to be
% {\code {{\tt \backslashcurfont }acronym}
\shipout\vbox{%
% Do this early so pdf references go to the beginning of the page.
460,7 → 464,7
\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm}
\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm}
 
% Each occurence of `\^^M' or `<space>\^^M' is replaced by a single space.
% Each occurrence of `\^^M' or `<space>\^^M' is replaced by a single space.
%
% \argremovec might leave us with trailing space, e.g.,
% @end itemize @c foo
485,7 → 489,7
% to get _exactly_ the rest of the line, we had to prevent such situation.
% We prepended an \empty token at the very beginning and we expand it now,
% just before passing the control to \argtorun.
% (Similarily, we have to think about #3 of \argcheckspacesY above: it is
% (Similarly, we have to think about #3 of \argcheckspacesY above: it is
% either the null string, or it ends with \^^M---thus there is no danger
% that a pair of braces would be stripped.
%
542,12 → 546,12
% used to check whether the current environment is the one expected.
%
% Non-false conditionals (@iftex, @ifset) don't fit into this, so they
% are not treated as enviroments; they don't open a group. (The
% are not treated as environments; they don't open a group. (The
% implementation of @end takes care not to call \endgroup in this
% special case.)
 
 
% At runtime, environments start with this:
% At run-time, environments start with this:
\def\startenvironment#1{\begingroup\def\thisenv{#1}}
% initialize
\let\thisenv\empty
565,7 → 569,7
\fi
}
 
% Evironment mismatch, #1 expected:
% Environment mismatch, #1 expected:
\def\badenverr{%
\errhelp = \EMsimple
\errmessage{This command can appear only \inenvironment\temp,
649,8 → 653,8
\def\jmacro{j}
\def\dotless#1{%
\def\temp{#1}%
\ifx\temp\imacro \ptexi
\else\ifx\temp\jmacro \j
\ifx\temp\imacro \ifmmode\imath \else\ptexi \fi
\else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi
\else \errmessage{@dotless can be used only with i or j}%
\fi\fi
}
705,7 → 709,7
\def\?{?\spacefactor=\endofsentencespacefactor\space}
 
% @frenchspacing on|off says whether to put extra space after punctuation.
%
%
\def\onword{on}
\def\offword{off}
%
916,7 → 920,7
\temp
}
 
% @include file insert text of that file as input.
% @include FILE -- \input text of FILE.
%
\def\include{\parseargusing\filenamecatcodes\includezzz}
\def\includezzz#1{%
923,8 → 927,13
\pushthisfilestack
\def\thisfile{#1}%
{%
\makevalueexpandable
\def\temp{\input #1 }%
\makevalueexpandable % we want to expand any @value in FILE.
\turnoffactive % and allow special characters in the expansion
\indexnofonts % Allow `@@' and other weird things in file names.
\edef\temp{\noexpand\input #1 }%
%
% This trickery is to read FILE outside of a group, in case it makes
% definitions, etc.
\expandafter
}\temp
\popthisfilestack
939,6 → 948,8
\catcode`>=\other
\catcode`+=\other
\catcode`-=\other
\catcode`\`=\other
\catcode`\'=\other
}
 
\def\pushthisfilestack{%
1114,6 → 1125,16
\mathunderscore
\let\\ = \mathbackslash
\mathactive
% make the texinfo accent commands work in math mode
\let\"=\ddot
\let\'=\acute
\let\==\bar
\let\^=\hat
\let\`=\grave
\let\u=\breve
\let\v=\check
\let\~=\tilde
\let\dotaccent=\dot
$\finishmath
}
\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex.
1127,17 → 1148,21
\catcode`< = \active
\catcode`> = \active
\catcode`+ = \active
\catcode`' = \active
\gdef\mathactive{%
\let^ = \ptexhat
\let< = \ptexless
\let> = \ptexgtr
\let+ = \ptexplus
\let' = \ptexquoteright
}
}
 
% @bullet and @minus need the same treatment as @math, just above.
% Some math mode symbols.
\def\bullet{$\ptexbullet$}
\def\minus{$-$}
\def\geq{\ifmmode \ge\else $\ge$\fi}
\def\leq{\ifmmode \le\else $\le$\fi}
\def\minus{\ifmmode -\else $-$\fi}
 
% @dots{} outputs an ellipsis using the current font.
% We do .5em per period so that it has the same spacing in the cm
1260,7 → 1285,7
% that's what we do).
 
% double active backslashes.
%
%
{\catcode`\@=0 \catcode`\\=\active
@gdef@activebackslashdouble{%
@catcode`@\=@active
1272,11 → 1297,11
% us) handles it with this amazing macro to replace tokens, with minor
% changes for Texinfo. It is included here under the GPL by permission
% from the author, Heiko Oberdiek.
%
%
% #1 is the tokens to replace.
% #2 is the replacement.
% #3 is the control sequence with the string.
%
%
\def\HyPsdSubst#1#2#3{%
\def\HyPsdReplace##1#1##2\END{%
##1%
1307,11 → 1332,17
 
\ifpdf
%
% Color manipulation macros based on pdfcolor.tex.
\def\cmykDarkRed{0.28 1 1 0.35}
\def\cmykBlack{0 0 0 1}
% Color manipulation macros based on pdfcolor.tex,
% except using rgb instead of cmyk; the latter is said to render as a
% very dark gray on-screen and a very dark halftone in print, instead
% of actual black.
\def\rgbDarkRed{0.50 0.09 0.12}
\def\rgbBlack{0 0 0}
%
\def\pdfsetcolor#1{\pdfliteral{#1 k}}
% k sets the color for filling (usual text, etc.);
% K sets the color for stroking (thin rules, e.g., normal _'s).
\def\pdfsetcolor#1{\pdfliteral{#1 rg #1 RG}}
%
% Set color, and create a mark which defines \thiscolor accordingly,
% so that \makeheadline knows which color to restore.
\def\setcolor#1{%
1320,7 → 1351,7
\pdfsetcolor{#1}%
}
%
\def\maincolor{\cmykBlack}
\def\maincolor{\rgbBlack}
\pdfsetcolor{\maincolor}
\edef\thiscolor{\maincolor}
\def\lastcolordefs{}
1362,8 → 1393,11
\openin 1 #1.jpeg \ifeof 1
\openin 1 #1.JPG \ifeof 1
\openin 1 #1.pdf \ifeof 1
\errhelp = \nopdfimagehelp
\errmessage{Could not find image file #1 for pdf}%
\openin 1 #1.PDF \ifeof 1
\errhelp = \nopdfimagehelp
\errmessage{Could not find image file #1 for pdf}%
\else \gdef\pdfimgext{PDF}%
\fi
\else \gdef\pdfimgext{pdf}%
\fi
\else \gdef\pdfimgext{JPG}%
1377,7 → 1411,7
\closein 1
\endgroup
%
% without \immediate, pdftex seg faults when the same image is
% without \immediate, ancient pdftex seg faults when the same image is
% included twice. (Version 3.14159-pre-1.0-unofficial-20010704.)
\ifnum\pdftexversion < 14
\immediate\pdfimage
1412,8 → 1446,8
%
% by default, use a color that is dark enough to print on paper as
% nearly black, but still distinguishable for online viewing.
\def\urlcolor{\cmykDarkRed}
\def\linkcolor{\cmykDarkRed}
\def\urlcolor{\rgbDarkRed}
\def\linkcolor{\rgbDarkRed}
\def\endlink{\setcolor{\maincolor}\pdfendlink}
%
% Adding outlines to PDF; macros for calculating structure of outlines
1542,11 → 1576,15
% tried to figure out what each command should do in the context
% of @url. for now, just make @/ a no-op, that's the only one
% people have actually reported a problem with.
%
%
\normalturnoffactive
\def\@{@}%
\let\/=\empty
\makevalueexpandable
% do we want to go so far as to use \indexnofonts instead of just
% special-casing \var here?
\def\var##1{##1}%
%
\leavevmode\setcolor{\urlcolor}%
\startlink attr{/Border [0 0 0]}%
user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
1577,6 → 1615,7
\setcolor{\linkcolor}#1\endlink}
\def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
\else
% non-pdf mode
\let\pdfmkdest = \gobble
\let\pdfurl = \gobble
\let\endlink = \relax
1607,6 → 1646,10
\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf}
\def\tt{\fam=\ttfam \setfontstyle{tt}}
 
% Unfortunately, we have to override this for titles and the like, since
% in those cases "rm" is bold. Sigh.
\def\rmisbold{\rm\def\curfontstyle{bf}}
 
% Texinfo sort of supports the sans serif font style, which plain TeX does not.
% So we set up a \sf.
\newfam\sffam
1941,7 → 1984,7
 
% Definitions for a main text size of 11pt. This is the default in
% Texinfo.
%
%
\def\definetextfontsizexi{%
% Text fonts (11.2pt, magstep1).
\def\textnominalsize{11pt}
2004,8 → 2047,6
\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
\font\titlei=cmmi12 scaled \magstep3
\font\titlesy=cmsy10 scaled \magstep4
\def\authorrm{\secrm}
\def\authortt{\sectt}
\def\titleecsize{2074}
 
% Chapter (and unnumbered) fonts (17.28pt).
2074,7 → 2115,7
% section, chapter, etc., sizes following suit. This is for the GNU
% Press printing of the Emacs 22 manual. Maybe other manuals in the
% future. Used with @smallbook, which sets the leading to 12pt.
%
%
\def\definetextfontsizex{%
% Text fonts (10pt).
\def\textnominalsize{10pt}
2137,8 → 2178,6
\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
\font\titlei=cmmi12 scaled \magstep3
\font\titlesy=cmsy10 scaled \magstep4
\def\authorrm{\secrm}
\def\authortt{\sectt}
\def\titleecsize{2074}
 
% Chapter fonts (14.4pt).
2165,7 → 2204,7
\setfont\secsf\sfbshape{12}{1000}{OT1}
\let\secbf\secrm
\setfont\secsc\scbshape{10}{\magstep1}{OT1}
\font\seci=cmmi12
\font\seci=cmmi12
\font\secsy=cmsy10 scaled \magstep1
\def\sececsize{1200}
 
2209,7 → 2248,7
% We provide the user-level command
% @fonttextsize 10
% (or 11) to redefine the text font size. pt is assumed.
%
%
\def\xword{10}
\def\xiword{11}
%
2219,7 → 2258,7
%
% Set \globaldefs so that documents can use this inside @tex, since
% makeinfo 4.8 does not support it, but we need it nonetheless.
%
%
\begingroup \globaldefs=1
\ifx\textsizearg\xword \definetextfontsizex
\else \ifx\textsizearg\xiword \definetextfontsizexi
2270,7 → 2309,7
\def\curfontsize{title}%
\def\lsize{chap}\def\lllsize{subsec}%
\resetmathfonts \setleading{25pt}}
\def\titlefont#1{{\titlefonts\rm #1}}
\def\titlefont#1{{\titlefonts\rmisbold #1}}
\def\chapfonts{%
\let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl
\let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc
2321,6 → 2360,16
\def\lsize{smaller}\def\lllsize{smaller}%
\resetmathfonts \setleading{9.5pt}}
 
% Fonts for short table of contents.
\setfont\shortcontrm\rmshape{12}{1000}{OT1}
\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12
\setfont\shortcontsl\slshape{12}{1000}{OT1}
\setfont\shortconttt\ttshape{12}{1000}{OT1TT}
 
% Define these just so they can be easily changed for other fonts.
\def\angleleft{$\langle$}
\def\angleright{$\rangle$}
 
% Set the fonts to use with the @small... environments.
\let\smallexamplefonts = \smallfonts
 
2334,28 → 2383,128
%
% By the way, for comparison, here's what fits with @example (10pt):
% 8.5x11=71 smallbook=60 a4=75 a5=58
%
% I wish the USA used A4 paper.
% --karl, 24jan03.
 
 
% Set up the default fonts, so we can use them for creating boxes.
%
\definetextfontsizexi
 
% Define these so they can be easily changed for other fonts.
\def\angleleft{$\langle$}
\def\angleright{$\rangle$}
 
\message{markup,}
 
% Check if we are currently using a typewriter font. Since all the
% Computer Modern typewriter fonts have zero interword stretch (and
% shrink), and it is reasonable to expect all typewriter fonts to have
% this property, we can check that font parameter.
%
\def\ifmonospace{\ifdim\fontdimen3\font=0pt }
 
% Markup style infrastructure. \defmarkupstylesetup\INITMACRO will
% define and register \INITMACRO to be called on markup style changes.
% \INITMACRO can check \currentmarkupstyle for the innermost
% style and the set of \ifmarkupSTYLE switches for all styles
% currently in effect.
\newif\ifmarkupvar
\newif\ifmarkupsamp
\newif\ifmarkupkey
%\newif\ifmarkupfile % @file == @samp.
%\newif\ifmarkupoption % @option == @samp.
\newif\ifmarkupcode
\newif\ifmarkupkbd
%\newif\ifmarkupenv % @env == @code.
%\newif\ifmarkupcommand % @command == @code.
\newif\ifmarkuptex % @tex (and part of @math, for now).
\newif\ifmarkupexample
\newif\ifmarkupverb
\newif\ifmarkupverbatim
 
\let\currentmarkupstyle\empty
 
\def\setupmarkupstyle#1{%
\csname markup#1true\endcsname
\def\currentmarkupstyle{#1}%
\markupstylesetup
}
 
\let\markupstylesetup\empty
 
\def\defmarkupstylesetup#1{%
\expandafter\def\expandafter\markupstylesetup
\expandafter{\markupstylesetup #1}%
\def#1%
}
 
% Markup style setup for left and right quotes.
\defmarkupstylesetup\markupsetuplq{%
\expandafter\let\expandafter \temp \csname markupsetuplq\currentmarkupstyle\endcsname
\ifx\temp\relax \markupsetuplqdefault \else \temp \fi
}
 
\defmarkupstylesetup\markupsetuprq{%
\expandafter\let\expandafter \temp \csname markupsetuprq\currentmarkupstyle\endcsname
\ifx\temp\relax \markupsetuprqdefault \else \temp \fi
}
 
{
\catcode`\'=\active
\catcode`\`=\active
 
\gdef\markupsetuplqdefault{\let`\lq}
\gdef\markupsetuprqdefault{\let'\rq}
 
\gdef\markupsetcodequoteleft{\let`\codequoteleft}
\gdef\markupsetcodequoteright{\let'\codequoteright}
 
\gdef\markupsetnoligaturesquoteleft{\let`\noligaturesquoteleft}
}
 
\let\markupsetuplqcode \markupsetcodequoteleft
\let\markupsetuprqcode \markupsetcodequoteright
\let\markupsetuplqexample \markupsetcodequoteleft
\let\markupsetuprqexample \markupsetcodequoteright
\let\markupsetuplqverb \markupsetcodequoteleft
\let\markupsetuprqverb \markupsetcodequoteright
\let\markupsetuplqverbatim \markupsetcodequoteleft
\let\markupsetuprqverbatim \markupsetcodequoteright
 
\let\markupsetuplqsamp \markupsetnoligaturesquoteleft
\let\markupsetuplqkbd \markupsetnoligaturesquoteleft
 
% Allow an option to not replace quotes with a regular directed right
% quote/apostrophe (char 0x27), but instead use the undirected quote
% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it
% the default, but it works for pasting with more pdf viewers (at least
% evince), the lilypond developers report. xpdf does work with the
% regular 0x27.
%
\def\codequoteright{%
\expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax
\expandafter\ifx\csname SETcodequoteundirected\endcsname\relax
'%
\else \char'15 \fi
\else \char'15 \fi
}
%
% and a similar option for the left quote char vs. a grave accent.
% Modern fonts display ASCII 0x60 as a grave accent, so some people like
% the code environments to do likewise.
%
\def\codequoteleft{%
\expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax
\expandafter\ifx\csname SETcodequotebacktick\endcsname\relax
% [Knuth] pp. 380,381,391
% \relax disables Spanish ligatures ?` and !` of \tt font.
\relax`%
\else \char'22 \fi
\else \char'22 \fi
}
 
% [Knuth] pp. 380,381,391, disable Spanish ligatures ?` and !` of \tt font.
\def\noligaturesquoteleft{\relax\lq}
 
% Count depth in font-changes, for error checks
\newcount\fontdepth \fontdepth=0
 
% Fonts for short table of contents.
\setfont\shortcontrm\rmshape{12}{1000}{OT1}
\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12
\setfont\shortcontsl\slshape{12}{1000}{OT1}
\setfont\shortconttt\ttshape{12}{1000}{OT1TT}
 
%% Add scribe-like font environments, plus @l for inline lisp (usually sans
%% serif) and @ii for TeX italic
 
2370,17 → 2519,22
% @var is set to this for defun arguments.
\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx}
 
% like \smartslanted except unconditionally use \sl. We never want
% @cite is like \smartslanted except unconditionally use \sl. We never want
% ttsl for book titles, do we?
\def\cite#1{{\sl #1}\futurelet\next\smartitalicx}
 
\let\i=\smartitalic
\let\slanted=\smartslanted
\let\var=\smartslanted
\def\var#1{{\setupmarkupstyle{var}\smartslanted{#1}}}
\let\dfn=\smartslanted
\let\emph=\smartitalic
 
% @b, explicit bold.
% Explicit font changes: @r, @sc, undocumented @ii.
\def\r#1{{\rm #1}} % roman font
\def\sc#1{{\smallcaps#1}} % smallcaps font
\def\ii#1{{\it #1}} % italic font
 
% @b, explicit bold. Also @strong.
\def\b#1{{\bf #1}}
\let\strong=\b
 
2412,22 → 2566,35
\catcode`@=\other
\def\endofsentencespacefactor{3000}% default
 
% @t, explicit typewriter.
\def\t#1{%
{\tt \rawbackslash \plainfrenchspacing #1}%
\null
}
\def\samp#1{`\tclose{#1}'\null}
\setfont\keyrm\rmshape{8}{1000}{OT1}
\font\keysy=cmsy9
\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
\raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
\vbox{\hrule\kern-0.4pt
\hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
\kern-0.4pt\hrule}%
\kern-.06em\raise0.4pt\hbox{\angleright}}}}
\def\key #1{{\nohyphenation \uppercase{#1}}\null}
% The old definition, with no lozenge:
%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null}
 
% @samp.
\def\samp#1{{\setupmarkupstyle{samp}\lq\tclose{#1}\rq\null}}
 
% definition of @key that produces a lozenge. Doesn't adjust to text size.
%\setfont\keyrm\rmshape{8}{1000}{OT1}
%\font\keysy=cmsy9
%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
% \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
% \vbox{\hrule\kern-0.4pt
% \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
% \kern-0.4pt\hrule}%
% \kern-.06em\raise0.4pt\hbox{\angleright}}}}
 
% definition of @key with no lozenge. If the current font is already
% monospace, don't change it; that way, we respect @kbdinputstyle. But
% if it isn't monospace, then use \tt.
%
\def\key#1{{\setupmarkupstyle{key}%
\nohyphenation
\ifmonospace\else\tt\fi
#1}\null}
 
% ctrl is no longer a Texinfo command.
\def\ctrl #1{{\tt \rawbackslash \hat}#1}
 
% @file, @option are the same as @samp.
2469,11 → 2636,11
{
\catcode`\-=\active \catcode`\_=\active
\catcode`\'=\active \catcode`\`=\active
\global\let'=\rq \global\let`=\lq % default definitions
%
\global\def\code{\begingroup
\catcode\rquoteChar=\active \catcode\lquoteChar=\active
\let'\codequoteright \let`\codequoteleft
%
\setupmarkupstyle{code}%
% The following should really be moved into \setupmarkupstyle handlers.
\catcode\dashChar=\active \catcode\underChar=\active
\ifallowcodebreaks
\let-\codedash
2505,7 → 2672,7
% each of the four underscores in __typeof__. This is undesirable in
% some manuals, especially if they don't have long identifiers in
% general. @allowcodebreaks provides a way to control this.
%
%
\newif\ifallowcodebreaks \allowcodebreakstrue
 
\def\keywordtrue{true}
2525,6 → 2692,7
 
% @kbd is like @code, except that if the argument is just one @key command,
% then @kbd has no effect.
\def\kbd#1{{\setupmarkupstyle{kbd}\def\look{#1}\expandafter\kbdfoo\look??\par}}
 
% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),
% `example' (@kbd uses ttsl only inside of @example and friends),
2546,14 → 2714,14
\def\wordexample{example}
\def\wordcode{code}
 
% Default is `distinct.'
% Default is `distinct'.
\kbdinputstyle distinct
 
\def\xkey{\key}
\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}%
\ifx\one\xkey\ifx\threex\three \key{#2}%
\else{\tclose{\kbdfont\look}}\fi
\else{\tclose{\kbdfont\look}}\fi}
\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi
\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi}
 
% For @indicateurl, @env, @command quotes seem unnecessary, so use \code.
\let\indicateurl=\code
2560,6 → 2728,13
\let\env=\code
\let\command=\code
 
% @clicksequence{File @click{} Open ...}
\def\clicksequence#1{\begingroup #1\endgroup}
 
% @clickstyle @arrow (by default)
\parseargdef\clickstyle{\def\click{#1}}
\def\click{\arrow}
 
% @uref (abbreviation for `urlref') takes an optional (comma-separated)
% second argument specifying the text to display and an optional third
% arg as text to display instead of (rather than in addition to) the url
2609,34 → 2784,20
\let\email=\uref
\fi
 
% Check if we are currently using a typewriter font. Since all the
% Computer Modern typewriter fonts have zero interword stretch (and
% shrink), and it is reasonable to expect all typewriter fonts to have
% this property, we can check that font parameter.
%
\def\ifmonospace{\ifdim\fontdimen3\font=0pt }
 
% Typeset a dimension, e.g., `in' or `pt'. The only reason for the
% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt.
%
\def\dmn#1{\thinspace #1}
 
\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par}
 
% @l was never documented to mean ``switch to the Lisp font'',
% and it is not used as such in any manual I can find. We need it for
% Polish suppressed-l. --karl, 22sep96.
%\def\l#1{{\li #1}\null}
 
% Explicit font changes: @r, @sc, undocumented @ii.
\def\r#1{{\rm #1}} % roman font
\def\sc#1{{\smallcaps#1}} % smallcaps font
\def\ii#1{{\it #1}} % italic font
 
% @acronym for "FBI", "NATO", and the like.
% We print this one point size smaller, since it's intended for
% all-uppercase.
%
%
\def\acronym#1{\doacronym #1,,\finish}
\def\doacronym#1,#2,#3\finish{%
{\selectfonts\lsize #1}%
2648,7 → 2809,7
 
% @abbr for "Comput. J." and the like.
% No font change, but don't do end-of-sentence spacing.
%
%
\def\abbr#1{\doabbr #1,,\finish}
\def\doabbr#1,#2,#3\finish{%
{\plainfrenchspacing #1}%
2658,6 → 2819,44
\fi
}
 
 
\message{glyphs,}
 
% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
%
% Since these characters are used in examples, they should be an even number of
% \tt widths. Each \tt character is 1en, so two makes it 1em.
%
\def\point{$\star$}
\def\arrow{\leavevmode\raise.05ex\hbox to 1em{\hfil$\rightarrow$\hfil}}
\def\result{\leavevmode\raise.05ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
\def\expansion{\leavevmode\hbox to 1em{\hfil$\mapsto$\hfil}}
\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
\def\equiv{\leavevmode\hbox to 1em{\hfil$\ptexequiv$\hfil}}
 
% The @error{} command.
% Adapted from the TeXbook's \boxit.
%
\newbox\errorbox
%
{\tentt \global\dimen0 = 3em}% Width of the box.
\dimen2 = .55pt % Thickness of rules
% The text. (`r' is open on the right, `e' somewhat less so on the left.)
\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt}
%
\setbox\errorbox=\hbox to \dimen0{\hfil
\hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
\advance\hsize by -2\dimen2 % Rules.
\vbox{%
\hrule height\dimen2
\hbox{\vrule width\dimen2 \kern3pt % Space to left of text.
\vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
\kern3pt\vrule width\dimen2}% Space to right.
\hrule height\dimen2}
\hfil}
%
\def\error{\leavevmode\lower.7ex\copy\errorbox}
 
% @pounds{} is a sterling sign, which Knuth put in the CM italic font.
%
\def\pounds{{\it\$}}
2667,24 → 2866,24
% Theiling, which support regular, slanted, bold and bold slanted (and
% "outlined" (blackboard board, sort of) versions, which we don't need).
% It is available from http://www.ctan.org/tex-archive/fonts/eurosym.
%
%
% Although only regular is the truly official Euro symbol, we ignore
% that. The Euro is designed to be slightly taller than the regular
% font height.
%
%
% feymr - regular
% feymo - slanted
% feybr - bold
% feybo - bold slanted
%
%
% There is no good (free) typewriter version, to my knowledge.
% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide.
% Hmm.
%
%
% Also doesn't work in math. Do we need to do math with euro symbols?
% Hope not.
%
%
%
%
\def\euro{{\eurofont e}}
\def\eurofont{%
% We set the font at each command, rather than predefining it in
2691,19 → 2890,19
% \textfonts and the other font-switching commands, so that
% installations which never need the symbol don't have to have the
% font installed.
%
%
% There is only one designed size (nominal 10pt), so we always scale
% that to the current nominal size.
%
%
% By the way, simply using "at 1em" works for cmr10 and the like, but
% does not work for cmbx10 and other extended/shrunken fonts.
%
%
\def\eurosize{\csname\curfontsize nominalsize\endcsname}%
%
\ifx\curfontstyle\bfstylename
\ifx\curfontstyle\bfstylename
% bold:
\font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize
\else
\else
% regular:
\font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize
\fi
2710,9 → 2909,16
\thiseurofont
}
 
% Hacks for glyphs from the EC fonts similar to \euro. We don't
% use \let for the aliases, because sometimes we redefine the original
% macro, and the alias should reflect the redefinition.
% Glyphs from the EC fonts. We don't use \let for the aliases, because
% sometimes we redefine the original macro, and the alias should reflect
% the redefinition.
%
% Use LaTeX names for the Icelandic letters.
\def\DH{{\ecfont \char"D0}} % Eth
\def\dh{{\ecfont \char"F0}} % eth
\def\TH{{\ecfont \char"DE}} % Thorn
\def\th{{\ecfont \char"FE}} % thorn
%
\def\guillemetleft{{\ecfont \char"13}}
\def\guillemotleft{\guillemetleft}
\def\guillemetright{{\ecfont \char"14}}
2722,8 → 2928,36
\def\quotedblbase{{\ecfont \char"12}}
\def\quotesinglbase{{\ecfont \char"0D}}
%
% This positioning is not perfect (see the ogonek LaTeX package), but
% we have the precomposed glyphs for the most common cases. We put the
% tests to use those glyphs in the single \ogonek macro so we have fewer
% dummy definitions to worry about for index entries, etc.
%
% ogonek is also used with other letters in Lithuanian (IOU), but using
% the precomposed glyphs for those is not so easy since they aren't in
% the same EC font.
\def\ogonek#1{{%
\def\temp{#1}%
\ifx\temp\macrocharA\Aogonek
\else\ifx\temp\macrochara\aogonek
\else\ifx\temp\macrocharE\Eogonek
\else\ifx\temp\macrochare\eogonek
\else
\ecfont \setbox0=\hbox{#1}%
\ifdim\ht0=1ex\accent"0C #1%
\else\ooalign{\unhbox0\crcr\hidewidth\char"0C \hidewidth}%
\fi
\fi\fi\fi\fi
}%
}
\def\Aogonek{{\ecfont \char"81}}\def\macrocharA{A}
\def\aogonek{{\ecfont \char"A1}}\def\macrochara{a}
\def\Eogonek{{\ecfont \char"86}}\def\macrocharE{E}
\def\eogonek{{\ecfont \char"A6}}\def\macrochare{e}
%
% Use the ec* fonts (cm-super in outline format) for non-CM glyphs.
\def\ecfont{%
% We can't distinguish serif/sanserif and italic/slanted, but this
% We can't distinguish serif/sans and italic/slanted, but this
% is used for crude hacks anyway (like adding French and German
% quotes to documents typeset with CM, where we lose kerning), so
% hopefully nobody will notice/care.
2756,7 → 2990,7
% Laurent Siebenmann reports \Orb undefined with:
% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38
% so we'll define it if necessary.
%
%
\ifx\Orb\undefined
\def\Orb{\mathhexbox20D}
\fi
2851,12 → 3085,9
\let\subtitlerm=\tenrm
\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}
 
\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines
\let\tt=\authortt}
 
\parseargdef\title{%
\checkenv\titlepage
\leftline{\titlefonts\rm #1}
\leftline{\titlefonts\rmisbold #1}
% print a rule at the page bottom also.
\finishedtitlepagefalse
\vskip4pt \hrule height 4pt width \hsize \vskip4pt
2877,7 → 3108,7
\else
\checkenv\titlepage
\ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi
{\authorfont \leftline{#1}}%
{\secfonts\rmisbold \leftline{#1}}%
\fi
}
 
3105,7 → 3336,7
% cause the example and the item to crash together. So we use this
% bizarre value of 10001 as a signal to \aboveenvbreak to insert
% \parskip glue after all. Section titles are handled this way also.
%
%
\penalty 10001
\endgroup
\itemxneedsnegativevskipfalse
3199,9 → 3430,18
\parindent=0pt
\parskip=\smallskipamount
\ifdim\parskip=0pt \parskip=2pt \fi
%
% Try typesetting the item mark that if the document erroneously says
% something like @itemize @samp (intending @table), there's an error
% right away at the @itemize. It's not the best error message in the
% world, but it's better than leaving it to the @item. This means if
% the user wants an empty mark, they have to say @w{} not just @w.
\def\itemcontents{#1}%
\setbox0 = \hbox{\itemcontents}%
%
% @itemize with no arg is equivalent to @itemize @bullet.
\ifx\itemcontents\empty\def\itemcontents{\bullet}\fi
%
\let\item=\itemizeitem
}
 
3222,6 → 3462,7
\ifnum\lastpenalty<10000 \parskip=0in \fi
\noindent
\hbox to 0pt{\hss \itemcontents \kern\itemmargin}%
%
\vadjust{\penalty 1200}}% not good to break after first line of item.
\flushcr
}
3443,12 → 3684,19
%
% @headitem starts a heading row, which we typeset in bold.
% Assignments have to be global since we are inside the implicit group
% of an alignment entry. Note that \everycr resets \everytab.
\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}%
% of an alignment entry. \everycr resets \everytab so we don't have to
% undo it ourselves.
\def\headitemfont{\b}% for people to use in the template row; not changeable
\def\headitem{%
\checkenv\multitable
\crcr
\global\everytab={\bf}% can't use \headitemfont since the parsing differs
\the\everytab % for the first item
}%
%
% A \tab used to include \hskip1sp. But then the space in a template
% line is not enough. That is bad. So let's go back to just `&' until
% we encounter the problem it was intended to solve again.
% we again encounter the problem the 1sp was intended to solve.
% --karl, nathan@acm.org, 20apr99.
\def\tab{\checkenv\multitable &\the\everytab}%
 
3847,11 → 4095,11
\def\dosynindex#1#2#3{%
% Only do \closeout if we haven't already done it, else we'll end up
% closing the target index.
\expandafter \ifx\csname donesynindex#2\endcsname \undefined
\expandafter \ifx\csname donesynindex#2\endcsname \relax
% The \closeout helps reduce unnecessary open files; the limit on the
% Acorn RISC OS is a mere 16 files.
\expandafter\closeout\csname#2indfile\endcsname
\expandafter\let\csname\donesynindex#2\endcsname = 1
\expandafter\let\csname donesynindex#2\endcsname = 1
\fi
% redefine \fooindfile:
\expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname
3901,7 → 4149,7
% processing continues to some further point. On the other hand, it
% seems \endinput does not hurt in the printed index arg, since that
% is still getting written without apparent harm.
%
%
% Sample source (mac-idx3.tex, reported by Graham Percival to
% help-texinfo, 22may06):
% @macro funindex {WORD}
3909,12 → 4157,12
% @end macro
% ...
% @funindex commtest
%
%
% The above is not enough to reproduce the bug, but it gives the flavor.
%
%
% Sample whatsit resulting:
% .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}}
%
%
% So:
\let\endinput = \empty
%
3966,19 → 4214,23
% Non-English letters.
\definedummyword\AA
\definedummyword\AE
\definedummyword\DH
\definedummyword\L
\definedummyword\O
\definedummyword\OE
\definedummyword\O
\definedummyword\TH
\definedummyword\aa
\definedummyword\ae
\definedummyword\dh
\definedummyword\exclamdown
\definedummyword\l
\definedummyword\o
\definedummyword\oe
\definedummyword\o
\definedummyword\ss
\definedummyword\exclamdown
\definedummyword\questiondown
\definedummyword\ordf
\definedummyword\ordm
\definedummyword\questiondown
\definedummyword\ss
\definedummyword\th
%
% Although these internal commands shouldn't show up, sometimes they do.
\definedummyword\bf
4009,6 → 4261,7
\definedummyword\guilsinglright
\definedummyword\expansion
\definedummyword\minus
\definedummyword\ogonek
\definedummyword\pounds
\definedummyword\point
\definedummyword\print
4052,6 → 4305,7
\definedummyword\v
\definedummyword\H
\definedummyword\dotaccent
\definedummyword\ogonek
\definedummyword\ringaccent
\definedummyword\tieaccent
\definedummyword\ubaraccent
4071,6 → 4325,7
\definedummyword\code
\definedummyword\command
\definedummyword\dfn
\definedummyword\email
\definedummyword\emph
\definedummyword\env
\definedummyword\file
4119,19 → 4374,23
% Non-English letters.
\def\AA{AA}%
\def\AE{AE}%
\def\DH{DZZ}%
\def\L{L}%
\def\OE{OE}%
\def\O{O}%
\def\TH{ZZZ}%
\def\aa{aa}%
\def\ae{ae}%
\def\dh{dzz}%
\def\exclamdown{!}%
\def\l{l}%
\def\oe{oe}%
\def\ordf{a}%
\def\ordm{o}%
\def\o{o}%
\def\questiondown{?}%
\def\ss{ss}%
\def\exclamdown{!}%
\def\questiondown{?}%
\def\ordf{a}%
\def\ordm{o}%
\def\th{zzz}%
%
\def\LaTeX{LaTeX}%
\def\TeX{TeX}%
4141,20 → 4400,19
\def\bullet{bullet}%
\def\comma{,}%
\def\copyright{copyright}%
\def\registeredsymbol{R}%
\def\dots{...}%
\def\enddots{...}%
\def\equiv{==}%
\def\error{error}%
\def\euro{euro}%
\def\expansion{==>}%
\def\guillemetleft{<<}%
\def\guillemetright{>>}%
\def\guilsinglleft{<}%
\def\guilsinglright{>}%
\def\expansion{==>}%
\def\minus{-}%
\def\point{.}%
\def\pounds{pounds}%
\def\point{.}%
\def\print{-|}%
\def\quotedblbase{"}%
\def\quotedblleft{"}%
4162,8 → 4420,9
\def\quoteleft{`}%
\def\quoteright{'}%
\def\quotesinglbase{,}%
\def\registeredsymbol{R}%
\def\result{=>}%
\def\textdegree{degrees}%
\def\textdegree{o}%
%
% We need to get rid of all macros, leaving only the arguments (if present).
% Of course this is not nearly correct, but it is the best we can do for now.
4170,11 → 4429,11
% makeinfo does not expand macros in the argument to @deffn, which ends up
% writing an index entry, and texindex isn't prepared for an index sort entry
% that starts with \.
%
%
% Since macro invocations are followed by braces, we can just redefine them
% to take a single TeX argument. The case of a macro invocation that
% goes to end-of-line is not handled.
%
%
\macrolist
}
 
4302,7 → 4561,7
% to re-insert the same penalty (values >10000 are used for various
% signals); since we just inserted a non-discardable item, any
% following glue (such as a \parskip) would be a breakpoint. For example:
%
%
% @deffn deffn-whatever
% @vindex index-whatever
% Description.
4432,7 → 4691,7
%
% A straightforward implementation would start like this:
% \def\entry#1#2{...
% But this frozes the catcodes in the argument, and can cause problems to
% But this freezes the catcodes in the argument, and can cause problems to
% @code, which sets - active. This problem was fixed by a kludge---
% ``-'' was active throughout whole index, but this isn't really right.
%
4883,7 → 5142,9
\gdef\chaplevelprefix{\the\chapno.}%
\resetallfloatnos
%
\message{\putwordChapter\space \the\chapno}%
% \putwordChapter can contain complex things in translations.
\toks0=\expandafter{\putwordChapter}%
\message{\the\toks0 \space \the\chapno}%
%
% Write the actual heading.
\chapmacro{#1}{Ynumbered}{\the\chapno}%
4894,7 → 5155,8
\global\let\subsubsection = \numberedsubsubsec
}
 
\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz
\outer\parseargdef\appendix{\apphead0{#1}} % normally calls appendixzzz
%
\def\appendixzzz#1{%
\global\secno=0 \global\subsecno=0 \global\subsubsecno=0
\global\advance\appendixno by 1
4901,8 → 5163,9
\gdef\chaplevelprefix{\appendixletter.}%
\resetallfloatnos
%
\def\appendixnum{\putwordAppendix\space \appendixletter}%
\message{\appendixnum}%
% \putwordAppendix can contain complex things in translations.
\toks0=\expandafter{\putwordAppendix}%
\message{\the\toks0 \space \appendixletter}%
%
\chapmacro{#1}{Yappendix}{\appendixletter}%
%
5034,7 → 5297,6
% 3) Likewise, headings look best if no \parindent is used, and
% if justification is not attempted. Hence \raggedright.
 
 
\def\majorheading{%
{\advance\chapheadingskip by 10pt \chapbreak }%
\parsearg\chapheadingzzz
5043,8 → 5305,8
\def\chapheading{\chapbreak \parsearg\chapheadingzzz}
\def\chapheadingzzz#1{%
{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
\parindent=0pt\raggedright
\rm #1\hfill}}%
\parindent=0pt\ptexraggedright
\rmisbold #1\hfill}}%
\bigskip \par\penalty 200\relax
\suppressfirstparagraphindent
}
5136,7 → 5398,10
\xdef\lastchapterdefs{%
\gdef\noexpand\thischaptername{\the\toks0}%
\gdef\noexpand\thischapternum{\appendixletter}%
\gdef\noexpand\thischapter{\putwordAppendix{} \noexpand\thischapternum:
% \noexpand\putwordAppendix avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thischapter{\noexpand\putwordAppendix{}
\noexpand\thischapternum:
\noexpand\thischaptername}%
}%
\else
5144,7 → 5409,10
\xdef\lastchapterdefs{%
\gdef\noexpand\thischaptername{\the\toks0}%
\gdef\noexpand\thischapternum{\the\chapno}%
\gdef\noexpand\thischapter{\putwordChapter{} \noexpand\thischapternum:
% \noexpand\putwordChapter avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thischapter{\noexpand\putwordChapter{}
\noexpand\thischapternum:
\noexpand\thischaptername}%
}%
\fi\fi\fi
5163,7 → 5431,7
\domark
%
{%
\chapfonts \rm
\chapfonts \rmisbold
%
% Have to define \lastsection before calling \donoderef, because the
% xref code eventually uses it. On the other hand, it has to be called
5200,7 → 5468,7
%
% Typeset the actual heading.
\nobreak % Avoid page breaks at the interline glue.
\vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
\vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright
\hangindent=\wd0 \centerparametersmaybe
\unhbox0 #1\par}%
}%
5224,8 → 5492,8
%
\def\unnchfopen #1{%
\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
\parindent=0pt\raggedright
\rm #1\hfill}}\bigskip \par\nobreak
\parindent=0pt\ptexraggedright
\rmisbold #1\hfill}}\bigskip \par\nobreak
}
\def\chfopen #1#2{\chapoddpage {\chapfonts
\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
5234,7 → 5502,7
\def\centerchfopen #1{%
\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
\parindent=0pt
\hfill {\rm #1}\hfill}}\bigskip \par\nobreak
\hfill {\rmisbold #1}\hfill}}\bigskip \par\nobreak
}
\def\CHAPFopen{%
\global\let\chapmacro=\chfopen
5267,7 → 5535,7
\def\sectionheading#1#2#3#4{%
{%
% Switch to the right set of fonts.
\csname #2fonts\endcsname \rm
\csname #2fonts\endcsname \rmisbold
%
\def\sectionlevel{#2}%
\def\temptype{#3}%
5287,7 → 5555,10
\xdef\lastsectiondefs{%
\gdef\noexpand\thissectionname{\the\toks0}%
\gdef\noexpand\thissectionnum{#4}%
\gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum:
% \noexpand\putwordSection avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thissection{\noexpand\putwordSection{}
\noexpand\thissectionnum:
\noexpand\thissectionname}%
}%
\fi
5297,12 → 5568,20
\xdef\lastsectiondefs{%
\gdef\noexpand\thissectionname{\the\toks0}%
\gdef\noexpand\thissectionnum{#4}%
\gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum:
% \noexpand\putwordSection avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thissection{\noexpand\putwordSection{}
\noexpand\thissectionnum:
\noexpand\thissectionname}%
}%
\fi
\fi\fi\fi
%
% Go into vertical mode. Usually we'll already be there, but we
% don't want the following whatsit to end up in a preceding paragraph
% if the document didn't happen to have a blank line.
\par
%
% Output the mark. Pass it through \safewhatsit, to take care of
% the preceding space.
\safewhatsit\domark
5352,7 → 5631,7
\nobreak
%
% Output the actual section heading.
\vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
\vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright
\hangindent=\wd0 % zero if no section number
\unhbox0 #1}%
}%
5368,11 → 5647,11
% glue accumulate. (Not a breakpoint because it's preceded by a
% discardable item.)
\vskip-\parskip
%
%
% This is purely so the last item on the list is a known \penalty >
% 10000. This is so \startdefun can avoid allowing breakpoints after
% section headings. Otherwise, it would insert a valid breakpoint between:
%
%
% @section sec-whatever
% @deffn def-whatever
\penalty 10001
5430,7 → 5709,7
% These characters do not print properly in the Computer Modern roman
% fonts, so we must take special care. This is more or less redundant
% with the Texinfo input format setup at the end of this file.
%
%
\def\activecatcodes{%
\catcode`\"=\active
\catcode`\$=\active
5480,7 → 5759,7
 
% redefined for the two-volume lispref. We always output on
% \jobname.toc even if this is redefined.
%
%
\def\tocreadfilename{\jobname.toc}
 
% Normal (long) toc.
5650,45 → 5929,12
\message{environments,}
% @foo ... @end foo.
 
% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
%
% Since these characters are used in examples, it should be an even number of
% \tt widths. Each \tt character is 1en, so two makes it 1em.
%
\def\point{$\star$}
\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}}
\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}}
 
% The @error{} command.
% Adapted from the TeXbook's \boxit.
%
\newbox\errorbox
%
{\tentt \global\dimen0 = 3em}% Width of the box.
\dimen2 = .55pt % Thickness of rules
% The text. (`r' is open on the right, `e' somewhat less so on the left.)
\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt}
%
\setbox\errorbox=\hbox to \dimen0{\hfil
\hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
\advance\hsize by -2\dimen2 % Rules.
\vbox{%
\hrule height\dimen2
\hbox{\vrule width\dimen2 \kern3pt % Space to left of text.
\vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
\kern3pt\vrule width\dimen2}% Space to right.
\hrule height\dimen2}
\hfil}
%
\def\error{\leavevmode\lower.7ex\copy\errorbox}
 
% @tex ... @end tex escapes into raw Tex temporarily.
% One exception: @ is still an escape character, so that @end tex works.
% But \@ or @@ will get a plain tex @ character.
 
\envdef\tex{%
\setupmarkupstyle{tex}%
\catcode `\\=0 \catcode `\{=1 \catcode `\}=2
\catcode `\$=3 \catcode `\&=4 \catcode `\#=6
\catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie
5698,6 → 5944,8
\catcode `\|=\other
\catcode `\<=\other
\catcode `\>=\other
\catcode`\`=\other
\catcode`\'=\other
\escapechar=`\\
%
\let\b=\ptexb
5717,6 → 5965,7
\let\/=\ptexslash
\let\*=\ptexstar
\let\t=\ptext
\expandafter \let\csname top\endcsname=\ptextop % outer
\let\frenchspacing=\plainfrenchspacing
%
\def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
5832,6 → 6081,7
 
% This macro is called at the beginning of all the @example variants,
% inside a group.
\newdimen\nonfillparindent
\def\nonfillstart{%
\aboveenvbreak
\hfuzz = 12pt % Don't be fussy
5839,7 → 6089,12
\let\par = \lisppar % don't ignore blank lines
\obeylines % each line of input is a line of output
\parskip = 0pt
% Turn off paragraph indentation but redefine \indent to emulate
% the normal \indent.
\nonfillparindent=\parindent
\parindent = 0pt
\let\indent\nonfillindent
%
\emergencystretch = 0pt % don't try to avoid overfull boxes
\ifx\nonarrowing\relax
\advance \leftskip by \lispnarrowing
5850,6 → 6105,24
\let\exdent=\nofillexdent
}
 
\begingroup
\obeyspaces
% We want to swallow spaces (but not other tokens) after the fake
% @indent in our nonfill-environments, where spaces are normally
% active and set to @tie, resulting in them not being ignored after
% @indent.
\gdef\nonfillindent{\futurelet\temp\nonfillindentcheck}%
\gdef\nonfillindentcheck{%
\ifx\temp %
\expandafter\nonfillindentgobble%
\else%
\leavevmode\nonfillindentbox%
\fi%
}%
\endgroup
\def\nonfillindentgobble#1{\nonfillindent}
\def\nonfillindentbox{\hbox to \nonfillparindent{\hss}}
 
% If you want all examples etc. small: @set dispenvsize small.
% If you want even small examples the full size: @set dispenvsize nosmall.
% This affects the following displayed environments:
5898,7 → 6171,7
%
\maketwodispenvs {lisp}{example}{%
\nonfillstart
\tt\quoteexpand
\tt\setupmarkupstyle{example}%
\let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.
\gobble % eat return
}
5936,12 → 6209,36
\let\Eflushright = \afterenvbreak
 
 
% @raggedright does more-or-less normal line breaking but no right
% justification. From plain.tex.
\envdef\raggedright{%
\rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax
}
\let\Eraggedright\par
 
\envdef\raggedleft{%
\parindent=0pt \leftskip0pt plus2em
\spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
\hbadness=10000 % Last line will usually be underfull, so turn off
% badness reporting.
}
\let\Eraggedleft\par
 
\envdef\raggedcenter{%
\parindent=0pt \rightskip0pt plus1em \leftskip0pt plus1em
\spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
\hbadness=10000 % Last line will usually be underfull, so turn off
% badness reporting.
}
\let\Eraggedcenter\par
 
 
% @quotation does normal linebreaking (hence we can't use \nonfillstart)
% and narrows the margins. We keep \parskip nonzero in general, since
% we're doing normal filling. So, when using \aboveenvbreak and
% \afterenvbreak, temporarily make \parskip 0.
%
\envdef\quotation{%
\def\quotationstart{%
{\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
\parindent=0pt
%
5956,6 → 6253,17
\parsearg\quotationlabel
}
 
\envdef\quotation{%
\setnormaldispenv
\quotationstart
}
 
\envdef\smallquotation{%
\setsmalldispenv
\quotationstart
}
\let\Esmallquotation = \Equotation
 
% We have retained a nonzero parskip for the environment, since we're
% doing normal filling.
%
5991,6 → 6299,10
\do\ \do\\\do\{\do\}\do\$\do\&%
\do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~%
\do\<\do\>\do\|\do\@\do+\do\"%
% Don't do the quotes -- if we do, @set txicodequoteundirected and
% @set txicodequotebacktick will not have effect on @verb and
% @verbatim, and ?` and !` ligatures won't get disabled.
%\do\`\do\'%
}
%
% [Knuth] p. 380
5997,12 → 6309,6
\def\uncatcodespecials{%
\def\do##1{\catcode`##1=\other}\dospecials}
%
% [Knuth] pp. 380,381,391
% Disable Spanish ligatures ?` and !` of \tt font
\begingroup
\catcode`\`=\active\gdef`{\relax\lq}
\endgroup
%
% Setup for the @verb command.
%
% Eight spaces for a tab
6014,7 → 6320,7
\def\setupverb{%
\tt % easiest (and conventionally used) font for verbatim
\def\par{\leavevmode\endgraf}%
\catcode`\`=\active
\setupmarkupstyle{verb}%
\tabeightspaces
% Respect line breaks,
% print special symbols as themselves, and
6029,34 → 6335,7
\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount
%
\def\starttabbox{\setbox0=\hbox\bgroup}
 
% Allow an option to not replace quotes with a regular directed right
% quote/apostrophe (char 0x27), but instead use the undirected quote
% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it
% the default, but it works for pasting with more pdf viewers (at least
% evince), the lilypond developers report. xpdf does work with the
% regular 0x27.
%
\def\codequoteright{%
\expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax
\expandafter\ifx\csname SETcodequoteundirected\endcsname\relax
'%
\else \char'15 \fi
\else \char'15 \fi
}
%
% and a similar option for the left quote char vs. a grave accent.
% Modern fonts display ASCII 0x60 as a grave accent, so some people like
% the code environments to do likewise.
%
\def\codequoteleft{%
\expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax
\expandafter\ifx\csname SETcodequotebacktick\endcsname\relax
`%
\else \char'22 \fi
\else \char'22 \fi
}
%
\begingroup
\catcode`\^^I=\active
\gdef\tabexpand{%
6069,13 → 6348,6
\wd0=\dimen0 \box0 \starttabbox
}%
}
\catcode`\'=\active
\gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}%
%
\catcode`\`=\active
\gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}%
%
\gdef\quoteexpand{\rquoteexpand \lquoteexpand}%
\endgroup
 
% start the verbatim environment.
6085,9 → 6357,8
% Easiest (and conventionally used) font for verbatim
\tt
\def\par{\leavevmode\egroup\box0\endgraf}%
\catcode`\`=\active
\tabexpand
\quoteexpand
\setupmarkupstyle{verbatim}%
% Respect line breaks,
% print special symbols as themselves, and
% make each space count
6147,6 → 6418,7
{%
\makevalueexpandable
\setupverbatim
\indexnofonts % Allow `@@' and other weird things in file names.
\input #1
\afterenvbreak
}%
6246,7 → 6518,7
\def\Edefun{\endgraf\medbreak}
 
% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn;
% the only thing remainnig is to define \deffnheader.
% the only thing remaining is to define \deffnheader.
%
\def\makedefun#1{%
\expandafter\let\csname E#1\endcsname = \Edefun
6425,7 → 6697,7
%
% On the other hand, if an argument has two dashes (for instance), we
% want a way to get ttsl. Let's try @var for that.
\let\var=\ttslanted
\def\var##1{{\setupmarkupstyle{var}\ttslanted{##1}}}%
#1%
\sl\hyphenchar\font=45
}
6579,7 → 6851,7
% This does \let #1 = #2, with \csnames; that is,
% \let \csname#1\endcsname = \csname#2\endcsname
% (except of course we have to play expansion games).
%
%
\def\cslet#1#2{%
\expandafter\let
\csname#1\expandafter\endcsname
6953,20 → 7225,22
%
% Make link in pdf output.
\ifpdf
\leavevmode
\getfilename{#4}%
{\indexnofonts
\turnoffactive
% This expands tokens, so do it after making catcode changes, so _
% etc. don't get their TeX definitions.
\getfilename{#4}%
%
% See comments at \activebackslashdouble.
{\activebackslashdouble \xdef\pdfxrefdest{#1}%
\backslashparens\pdfxrefdest}%
%
\leavevmode
\startlink attr{/Border [0 0 0]}%
\ifnum\filenamelength>0
\startlink attr{/Border [0 0 0]}%
goto file{\the\filename.pdf} name{\pdfxrefdest}%
goto file{\the\filename.pdf} name{\pdfxrefdest}%
\else
\startlink attr{/Border [0 0 0]}%
goto name{\pdfmkpgn{\pdfxrefdest}}%
goto name{\pdfmkpgn{\pdfxrefdest}}%
\fi
}%
\setcolor{\linkcolor}%
7317,7 → 7591,7
% In case a @footnote appears in a vbox, save the footnote text and create
% the real \insert just after the vbox finished. Otherwise, the insertion
% would be lost.
% Similarily, if a @footnote appears inside an alignment, save the footnote
% Similarly, if a @footnote appears inside an alignment, save the footnote
% text to a box and make the \insert when a row of the table is finished.
% And the same can be done for other insert classes. --kasal, 16nov03.
 
7421,15 → 7695,19
% If the image is by itself, center it.
\ifvmode
\imagevmodetrue
\nobreak\bigskip
\nobreak\medskip
% Usually we'll have text after the image which will insert
% \parskip glue, so insert it here too to equalize the space
% above and below.
\nobreak\vskip\parskip
\nobreak
\line\bgroup
\fi
%
% Leave vertical mode so that indentation from an enclosing
% environment such as @quotation is respected. On the other hand, if
% it's at the top level, we don't want the normal paragraph indentation.
\noindent
%
% Output the image.
\ifpdf
\dopdfimage{#1}{#2}{#3}%
7440,7 → 7718,7
\epsfbox{#1.eps}%
\fi
%
\ifimagevmode \egroup \bigbreak \fi % space after the image
\ifimagevmode \medskip \fi % space after the standalone image
\endgroup}
 
 
7712,10 → 7990,9
 
\message{localization,}
 
% @documentlanguage is usually given very early, just after
% @setfilename. If done too late, it may not override everything
% properly. Single argument is the language (de) or locale (de_DE)
% abbreviation. It would be nice if we could set up a hyphenation file.
% For single-language documents, @documentlanguage is usually given very
% early, just after @documentencoding. Single argument is the language
% (de) or locale (de_DE) abbreviation.
%
{
\catcode`\_ = \active
7728,31 → 8005,60
\ifeof 1
\documentlanguagetrywithoutunderscore{#1_\finish}%
\else
\globaldefs = 1 % everything in the txi-LL files needs to persist
\input txi-#1.tex
\fi
\closein 1
\endgroup
\endgroup % end raw TeX
\endgroup}
}
%
% If they passed de_DE, and txi-de_DE.tex doesn't exist,
% try txi-de.tex.
%
\def\documentlanguagetrywithoutunderscore#1_#2\finish{%
%
\gdef\documentlanguagetrywithoutunderscore#1_#2\finish{%
\openin 1 txi-#1.tex
\ifeof 1
\errhelp = \nolanghelp
\errmessage{Cannot read language file txi-#1.tex}%
\else
\globaldefs = 1 % everything in the txi-LL files needs to persist
\input txi-#1.tex
\fi
\closein 1
}
}% end of special _ catcode
%
\newhelp\nolanghelp{The given language definition file cannot be found or
is empty. Maybe you need to install it? In the current directory
should work if nowhere else does.}
is empty. Maybe you need to install it? Putting it in the current
directory should work if nowhere else does.}
 
% This macro is called from txi-??.tex files; the first argument is the
% \language name to set (without the "\lang@" prefix), the second and
% third args are \{left,right}hyphenmin.
%
% The language names to pass are determined when the format is built.
% See the etex.log file created at that time, e.g.,
% /usr/local/texlive/2008/texmf-var/web2c/pdftex/etex.log.
%
% With TeX Live 2008, etex now includes hyphenation patterns for all
% available languages. This means we can support hyphenation in
% Texinfo, at least to some extent. (This still doesn't solve the
% accented characters problem.)
%
\catcode`@=11
\def\txisetlanguage#1#2#3{%
% do not set the language if the name is undefined in the current TeX.
\expandafter\ifx\csname lang@#1\endcsname \relax
\message{no patterns for #1}%
\else
\global\language = \csname lang@#1\endcsname
\fi
% but there is no harm in adjusting the hyphenmin values regardless.
\global\lefthyphenmin = #2\relax
\global\righthyphenmin = #3\relax
}
 
% Helpers for encodings.
% Set the catcode of characters 128 through 255 to the specified number.
%
\def\setnonasciicharscatcode#1{%
7793,7 → 8099,7
\setnonasciicharscatcode\active
\lattwochardefs
%
\else \ifx \declaredencoding \latone
\else \ifx \declaredencoding \latone
\setnonasciicharscatcode\active
\latonechardefs
%
7805,7 → 8111,7
\setnonasciicharscatcode\active
\utfeightchardefs
%
\else
\else
\message{Unknown document encoding #1, ignoring.}%
%
\fi % utfeight
7817,7 → 8123,7
 
% A message to be logged when using a character that isn't available
% the default font encoding (OT1).
%
%
\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}}
 
% Take account of \c (plain) vs. \, (Texinfo) difference.
7830,21 → 8136,21
%
% Latin1 (ISO-8859-1) character definitions.
\def\latonechardefs{%
\gdef^^a0{~}
\gdef^^a0{~}
\gdef^^a1{\exclamdown}
\gdef^^a2{\missingcharmsg{CENT SIGN}}
\gdef^^a2{\missingcharmsg{CENT SIGN}}
\gdef^^a3{{\pounds}}
\gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
\gdef^^a5{\missingcharmsg{YEN SIGN}}
\gdef^^a6{\missingcharmsg{BROKEN BAR}}
\gdef^^a6{\missingcharmsg{BROKEN BAR}}
\gdef^^a7{\S}
\gdef^^a8{\"{}}
\gdef^^a9{\copyright}
\gdef^^a8{\"{}}
\gdef^^a9{\copyright}
\gdef^^aa{\ordf}
\gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}}
\gdef^^ab{\guillemetleft}
\gdef^^ac{$\lnot$}
\gdef^^ad{\-}
\gdef^^ae{\registeredsymbol}
\gdef^^ad{\-}
\gdef^^ae{\registeredsymbol}
\gdef^^af{\={}}
%
\gdef^^b0{\textdegree}
7860,7 → 8166,7
\gdef^^b9{$^1$}
\gdef^^ba{\ordm}
%
\gdef^^bb{\missingcharmsg{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}}
\gdef^^bb{\guilletright}
\gdef^^bc{$1\over4$}
\gdef^^bd{$1\over2$}
\gdef^^be{$3\over4$}
7871,7 → 8177,7
\gdef^^c2{\^A}
\gdef^^c3{\~A}
\gdef^^c4{\"A}
\gdef^^c5{\ringaccent A}
\gdef^^c5{\ringaccent A}
\gdef^^c6{\AE}
\gdef^^c7{\cedilla C}
\gdef^^c8{\`E}
7883,7 → 8189,7
\gdef^^ce{\^I}
\gdef^^cf{\"I}
%
\gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER ETH}}
\gdef^^d0{\DH}
\gdef^^d1{\~N}
\gdef^^d2{\`O}
\gdef^^d3{\'O}
7897,7 → 8203,7
\gdef^^db{\^U}
\gdef^^dc{\"U}
\gdef^^dd{\'Y}
\gdef^^de{\missingcharmsg{LATIN CAPITAL LETTER THORN}}
\gdef^^de{\TH}
\gdef^^df{\ss}
%
\gdef^^e0{\`a}
7917,7 → 8223,7
\gdef^^ee{\^{\dotless i}}
\gdef^^ef{\"{\dotless i}}
%
\gdef^^f0{\missingcharmsg{LATIN SMALL LETTER ETH}}
\gdef^^f0{\dh}
\gdef^^f1{\~n}
\gdef^^f2{\`o}
\gdef^^f3{\'o}
7931,7 → 8237,7
\gdef^^fb{\^u}
\gdef^^fc{\"u}
\gdef^^fd{\'y}
\gdef^^fe{\missingcharmsg{LATIN SMALL LETTER THORN}}
\gdef^^fe{\th}
\gdef^^ff{\"y}
}
 
7953,7 → 8259,7
% Latin2 (ISO-8859-2) character definitions.
\def\lattwochardefs{%
\gdef^^a0{~}
\gdef^^a1{\missingcharmsg{LATIN CAPITAL LETTER A WITH OGONEK}}
\gdef^^a1{\ogonek{A}}
\gdef^^a2{\u{}}
\gdef^^a3{\L}
\gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
7970,8 → 8276,8
\gdef^^af{\dotaccent Z}
%
\gdef^^b0{\textdegree}
\gdef^^b1{\missingcharmsg{LATIN SMALL LETTER A WITH OGONEK}}
\gdef^^b2{\missingcharmsg{OGONEK}}
\gdef^^b1{\ogonek{a}}
\gdef^^b2{\ogonek{ }}
\gdef^^b3{\l}
\gdef^^b4{\'{}}
\gdef^^b5{\v l}
7996,7 → 8302,7
\gdef^^c7{\cedilla C}
\gdef^^c8{\v C}
\gdef^^c9{\'E}
\gdef^^ca{\missingcharmsg{LATIN CAPITAL LETTER E WITH OGONEK}}
\gdef^^ca{\ogonek{E}}
\gdef^^cb{\"E}
\gdef^^cc{\v E}
\gdef^^cd{\'I}
8003,7 → 8309,7
\gdef^^ce{\^I}
\gdef^^cf{\v D}
%
\gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER D WITH STROKE}}
\gdef^^d0{\DH}
\gdef^^d1{\'N}
\gdef^^d2{\v N}
\gdef^^d3{\'O}
8012,7 → 8318,7
\gdef^^d6{\"O}
\gdef^^d7{$\times$}
\gdef^^d8{\v R}
\gdef^^d9{\ringaccent U}
\gdef^^d9{\ringaccent U}
\gdef^^da{\'U}
\gdef^^db{\H U}
\gdef^^dc{\"U}
8030,7 → 8336,7
\gdef^^e7{\cedilla c}
\gdef^^e8{\v c}
\gdef^^e9{\'e}
\gdef^^ea{\missingcharmsg{LATIN SMALL LETTER E WITH OGONEK}}
\gdef^^ea{\ogonek{e}}
\gdef^^eb{\"e}
\gdef^^ec{\v e}
\gdef^^ed{\'\i}
8037,7 → 8343,7
\gdef^^ee{\^\i}
\gdef^^ef{\v d}
%
\gdef^^f0{\missingcharmsg{LATIN SMALL LETTER D WITH STROKE}}
\gdef^^f0{\dh}
\gdef^^f1{\'n}
\gdef^^f2{\v n}
\gdef^^f3{\'o}
8056,11 → 8362,11
}
 
% UTF-8 character definitions.
%
%
% This code to support UTF-8 is based on LaTeX's utf8.def, with some
% changes for Texinfo conventions. It is included here under the GPL by
% permission from Frank Mittelbach and the LaTeX team.
%
%
\newcount\countUTFx
\newcount\countUTFy
\newcount\countUTFz
8210,6 → 8516,7
\DeclareUnicodeCharacter{00CE}{\^I}
\DeclareUnicodeCharacter{00CF}{\"I}
 
\DeclareUnicodeCharacter{00D0}{\DH}
\DeclareUnicodeCharacter{00D1}{\~N}
\DeclareUnicodeCharacter{00D2}{\`O}
\DeclareUnicodeCharacter{00D3}{\'O}
8222,6 → 8529,7
\DeclareUnicodeCharacter{00DB}{\^U}
\DeclareUnicodeCharacter{00DC}{\"U}
\DeclareUnicodeCharacter{00DD}{\'Y}
\DeclareUnicodeCharacter{00DE}{\TH}
\DeclareUnicodeCharacter{00DF}{\ss}
 
\DeclareUnicodeCharacter{00E0}{\`a}
8241,6 → 8549,7
\DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}}
\DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}}
 
\DeclareUnicodeCharacter{00F0}{\dh}
\DeclareUnicodeCharacter{00F1}{\~n}
\DeclareUnicodeCharacter{00F2}{\`o}
\DeclareUnicodeCharacter{00F3}{\'o}
8253,6 → 8562,7
\DeclareUnicodeCharacter{00FB}{\^u}
\DeclareUnicodeCharacter{00FC}{\"u}
\DeclareUnicodeCharacter{00FD}{\'y}
\DeclareUnicodeCharacter{00FE}{\th}
\DeclareUnicodeCharacter{00FF}{\"y}
 
\DeclareUnicodeCharacter{0100}{\=A}
8259,10 → 8569,14
\DeclareUnicodeCharacter{0101}{\=a}
\DeclareUnicodeCharacter{0102}{\u{A}}
\DeclareUnicodeCharacter{0103}{\u{a}}
\DeclareUnicodeCharacter{0104}{\ogonek{A}}
\DeclareUnicodeCharacter{0105}{\ogonek{a}}
\DeclareUnicodeCharacter{0106}{\'C}
\DeclareUnicodeCharacter{0107}{\'c}
\DeclareUnicodeCharacter{0108}{\^C}
\DeclareUnicodeCharacter{0109}{\^c}
\DeclareUnicodeCharacter{0118}{\ogonek{E}}
\DeclareUnicodeCharacter{0119}{\ogonek{e}}
\DeclareUnicodeCharacter{010A}{\dotaccent{C}}
\DeclareUnicodeCharacter{010B}{\dotaccent{c}}
\DeclareUnicodeCharacter{010C}{\v{C}}
8410,6 → 8724,8
\DeclareUnicodeCharacter{0233}{\=y}
\DeclareUnicodeCharacter{0237}{\dotless{j}}
 
\DeclareUnicodeCharacter{02DB}{\ogonek{ }}
 
\DeclareUnicodeCharacter{1E02}{\dotaccent{B}}
\DeclareUnicodeCharacter{1E03}{\dotaccent{b}}
\DeclareUnicodeCharacter{1E04}{\udotaccent{B}}
8791,6 → 9107,9
 
\message{and turning on texinfo input format.}
 
% DEL is a comment character, in case @c does not suffice.
\catcode`\^^? = 14
 
% Define macros to output various characters with catcode for normal text.
\catcode`\"=\other
\catcode`\~=\other
8900,7 → 9219,7
 
% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of
% the literal character `\'.
%
%
@def@normalturnoffactive{%
@let\=@normalbackslash
@let"=@normaldoublequote
8912,6 → 9231,8
@let>=@normalgreater
@let+=@normalplus
@let$=@normaldollar %$ font-lock fix
@markupsetuplqdefault
@markupsetuprqdefault
@unsepspaces
}
 
8946,6 → 9267,14
@catcode`@# = @other
@catcode`@% = @other
 
@c Finally, make ` and ' active, so that txicodequoteundirected and
@c txicodequotebacktick work right in, e.g., @w{@code{`foo'}}. If we
@c don't make ` and ' active, @code will not get them as active chars.
@c Do this last of all since we use ` in the previous @catcode assignments.
@catcode`@'=@active
@catcode`@`=@active
@markupsetuplqdefault
@markupsetuprqdefault
 
@c Local variables:
@c eval: (add-hook 'write-file-hooks 'time-stamp)
/or1ksim.texi
98,7 → 98,7
main directory.
 
The most significant argument is @code{--target}, which should specify
the OpenRISC 1000 32-bit architecture. If this argument is omitted, it will
the OpenRISC 1000 32-bit architecture. If this argument is omitted, it will
default to OpenRISC 1000 32-bit with a warning
 
@example
106,12 → 106,12
@end example
 
There are several other options available, many of which are standard
to GNU @command{configure} scripts. Use @kbd{configure --help} to see
all the options. The most useful is @code{--prefix} to specify a
to GNU @command{configure} scripts. Use @kbd{configure --help} to see
all the options. The most useful is @code{--prefix} to specify a
directory for installation of the tools.
 
A number of @value{OR1KSIM} features in the simulator do require enabling at
configuration. These include
configuration. These include
 
@table @code
@item --enable-profiling
119,7 → 119,7
@itemx --disable-profiling
@cindex @code{--disable-profiling}
If enabled, @value{OR1KSIM} is compiled for profiling with
@command{gprof}. This is disabled by default. Only really of value for
@command{gprof}. This is disabled by default. Only really of value for
developers of @value{OR1KSIM}.
 
@item --enable-execution=simple
130,7 → 130,7
@cindex complex model
@cindex dynamic model
@value{OR1KSIM} has developed to improve functionality and
performance. This feature allows three versions of @value{OR1KSIM} to be built
performance. This feature allows three versions of @value{OR1KSIM} to be built
 
@table @code
 
138,12 → 138,12
Build the original simple interpreting simulator
 
@item --enable-execution=complex
Build a more complex interpreting simulator. Experiments suggest this
is 50% faster than the simple simulator. This is the default.
Build a more complex interpreting simulator. Experiments suggest this
is 50% faster than the simple simulator. This is the default.
 
@item --enable-execution=dynamic
Build a dynamically compiling simulator. This is the way many modern ISS are
built. This represents a work in progress. Currently @value{OR1KSIM} will
Build a dynamically compiling simulator. This is the way many modern ISS are
built. This represents a work in progress. Currently @value{OR1KSIM} will
compile, but segfaults if configured with this option.
 
@end table
157,9 → 157,9
@cindex Ethernet via socket, enabling
@cindex enabling Ethernet via socket
If enabled, this option allows the Ethernet to be simulated by connecting via a
socket (the alternative reads and writes, from and to files). This
socket (the alternative reads and writes, from and to files). This
must then be configured using the relevant fields in the
@code{ethernet} section of the configuration file. @xref{Ethernet
@code{ethernet} section of the configuration file. @xref{Ethernet
Configuration, , Ethernet Configuration}.
 
The default is for this to be disabled.
171,7 → 171,7
@cindex statistics, register over time
@cindex register over time statistics
If enabled, this option allows statistics to be collected to analyse
register access over time. The default is for this to be disabled.
register access over time. The default is for this to be disabled.
 
@item --enable-ov-flag
@cindex @code{--enable-ov-flag}
179,7 → 179,7
@cindex @code{--disable-ov-flag}
@cindex overflow flag setting by instructions
If enabled, this option causes instructions to set the overflow
flag. The instructions affected by this are @code{l.add},
flag. The instructions affected by this are @code{l.add},
@code{l.addc}, @code{l.addi}, @code{l.and}, @code{l.andi},
@code{l.div}, @code{l.divu}, @code{l.mul}, @code{l.muli}, @code{l.or},
@code{l.ori}, @code{l.sll}, @code{l.slli}, @code{l.srl},
190,12 → 190,12
 
@quotation Caution
This appears a very dangerous option, to the extent of arguably being
a bug. Whether or not flags are set is part of the OpenRISC 1000
architectural specification. Within the above list, the arithmetic
a bug. Whether or not flags are set is part of the OpenRISC 1000
architectural specification. Within the above list, the arithmetic
instructions (@code{l.add}, @code{l.addc}, @code{l.addi},
@code{l.div}, @code{l.divu}, @code{l.mul}, @code{l.muli} and
@code{l.sub}), together with @code{l.addic} which is missed out, set
the overflow flag. All the others (@code{l.and}, @code{l.andi},
the overflow flag. All the others (@code{l.and}, @code{l.andi},
@code{l.or}, @code{l.ori}, @code{l.sll}, @code{l.slli}, @code{l.srl},
@code{l.srli}, @code{l.sra}, @code{l.srai}, @code{l.xor} and
@code{l.xori}) do not.
210,7 → 210,7
@cindex @code{--disable-arith-flag}
@cindex flag setting by instructions
If enabled, this option causes instructions to set the flag (@code{F} bit) in
the supervision register. The instructions affected by this are @code{l.add},
the supervision register. The instructions affected by this are @code{l.add},
@code{l.addc}, @code{l.addi}, @code{l.and} and @code{l.andi}.
 
The default is for this to be disabled.
217,11 → 217,11
 
@quotation Caution
As with @code{--enable-ov-flag}, this appears another very dangerous option,
to the extent of arguably being a bug. It also appears to be only partially
to the extent of arguably being a bug. It also appears to be only partially
implemented---why only the instructions early in the alphabet?
 
Whether or not flags are set is part of the OpenRISC 1000 architectural
specification. The only flags which should set this are the ``set flag''
specification. The only flags which should set this are the ``set flag''
instructions: @code{l.sfeq}, @code{l.sfeqi}, @code{l.sfges}, @code{l.sfgesi},
@code{l.sfgeu}, @code{l.sfgeui}, @code{l.sfgts}, @code{l.sfgtsi},
@code{l.sfgtu}, @code{l.sfgtui}, @code{l.sfles}, @code{l.sflesi},
241,19 → 241,44
@cindex @code{--disable-debug}
@cindex debugging enabled (Argtable2)
@cindex Argtable2 debugging
This is a feature of the Argtable2 package used to process arguments. If
enabled, some debugging features are turned on in Argtable2. It is provided for
This is a feature of the Argtable2 package used to process arguments. If
enabled, some debugging features are turned on in Argtable2. It is provided for
completeness, but there is no reason why this feature should ever be needed by
any @value{OR1KSIM} user.
 
@item --enable-all-tests
@cindex @code{--enable-all-tests}
@itemx --disable-all-tests
@cindex @code{--disable-all-tests}
@cindex all tests enabled
@cindex tests, all enabled.
Some of the tests (at the time of writing just one) will not compile
without error. If enabled with this flag, all test programs will be
compiled with @command{make check}.
 
This flag is intended for those working on the test package, who wish to
get the missing test(s) working.
 
@end table
 
@node Build and Install
@section Building and Installing
The tool is then built with:
Build the tool with:
 
@example
@kbd{make all}
@end example
 
If you have the OpenRISC tool chain and DejaGNU installed, you can
verify the tool as follows (otherwise omit this step):
 
@example
@kbd{make check}
@end example
 
Install the tool with:
 
@example
@kbd{make install}
@end example
 
278,29 → 303,29
@section Known Problems and Issues
 
The following problems and issues are known about with @value{OR1KSIM}
@value{VERSION}. The OpenRISC tracker may be used to see the current
state of these issues and to raise new problems and feature requests. It
@value{VERSION}. The OpenRISC tracker may be used to see the current
state of these issues and to raise new problems and feature requests. It
may be found at @url{http://www.opencores.org/ptracker.cgi/view/or1k/398}.
 
@itemize @bullet
@item
The Supervision Register Little Endian Enable (LEE) bit is
ignored. @value{OR1KSIM} can be built for either little endian or big endian
ignored. @value{OR1KSIM} can be built for either little endian or big endian
use, but that behavior cannot be changed dynamically.
 
@item
The NPC is a read/write register, but after being written it clears the
pipeline. This means that if the processor is stalled, the value should
pipeline. This means that if the processor is stalled, the value should
subsequently read back as 0, until the processor is unstalled and able
to refill its pipeline. By default @value{OR1KSIM} always reports back the value
to refill its pipeline. By default @value{OR1KSIM} always reports back the value
of NPC, even when it has been written while stalled.
 
There is now an option, @code{--strict-npc}, which will enforce this
behavior. At some stage in the future it will become the default
behavior. At some stage in the future it will become the default
behavior, but for now it is an option, since its use will break GDB.
 
@item
The memory components are given names in the configuration file. However
The memory components are given names in the configuration file. However
there is currently no way for @value{OR1KSIM} to report that name back to the
user (for example to identify which memory block corresponds to a
particular access).
307,20 → 332,20
 
@item
@value{OR1KSIM} allows the processor to be stalled (from the command
line), even if there is no debugger present. This seems to be a
line), even if there is no debugger present. This seems to be a
meaningless operation.
 
@item
@value{OR1KSIM} is not reentrant, so a program cannot instantiate
multiple instances using the library. This is clearly a problem when
considering multi-core applications. However it stems from the original
design, and can only be fixed by a complete rewrite. The entire source
multiple instances using the library. This is clearly a problem when
considering multi-core applications. However it stems from the original
design, and can only be fixed by a complete rewrite. The entire source
code uses static global constants liberally!
 
@item
There is no support for floating point instructions currently in
@value{OR1KSIM}. However this is a work in progress and should be available in
the near future.
@value{OR1KSIM}. However this is a work in progress and should be available in
the future.
 
@end itemize
 
346,7 → 371,7
[--enable-profile] [--enable-mprofile] [@var{file}]
@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}.
 
@table @code
370,25 → 395,25
@cindex @code{--file}
Read configuration commands from the specified file, looking first in
the current directory, and otherwise in the @file{$HOME/.or1k}
directory. If this argument is not specified, the file @file{sim.cfg}
in those two locations is used. Failure to find the file is a fatal
error. @xref{Configuration, , Configuration}, for detailed information
directory. If this argument is not specified, the file @file{sim.cfg}
in those two locations is used. Failure to find the file is a fatal
error. @xref{Configuration, , Configuration}, for detailed information
on configuring @value{OR1KSIM}.
 
@item --nosrv
@cindex @code{--nosrv}
Do not start up the debug server. This overrides any setting specified
in the configuration file. This option may not be specified with
@code{--srv}. If it is, a rude message is printed and the
Do not start up the debug server. This overrides any setting specified
in the configuration file. This option may not be specified with
@code{--srv}. If it is, a rude message is printed and the
@code{--nosrv} option is ignored.
 
@item --srv
@item --srv=@var{n}
@cindex @code{--srv}
Start up the debug server. If the parameter, @var{n}, is specified,
Start up the debug server. If the parameter, @var{n}, is specified,
use that as the TCP/IP port for the server, otherwise a random value
from the private port range (41920-65535) will be used. This option
may not be specified with @code{--nosrv}. If it is, a rude message is
from the private port range (41920-65535) will be used. This option
may not be specified with @code{--nosrv}. If it is, a rude message is
printed and the @code{--nosrv} option is ignored.
 
@item -d=@var{config_string}
395,8 → 420,8
@itemx --debug-config=@var{config_string}
@cindex @code{-d}
@cindex @code{--debug-config}
Enable selected debug messages in @value{OR1KSIM}. This parameter is
for use by developers only, and is not covered further here. See the
Enable selected debug messages in @value{OR1KSIM}. This parameter is
for use by developers only, and is not covered further here. See the
source code for more details.
 
@item -i
409,18 → 434,18
@item --strict-npc
@cindex @code{--strict-npc}
In real hardware, setting the next program counter (NPC, SPR 16),
flushes the processor pipeline. The consequence of this is that until
the pipeline refills, reading the NPC will return zero. This is typically
flushes the processor pipeline. The consequence of this is that until
the pipeline refills, reading the NPC will return zero. This is typically
the case when debugging, since the processor is stalled.
 
Historically, @value{OR1KSIM} has always returned the value of the NPC,
irrespective of when it is changed. If the @code{--strict-npc} option is
used, then @value{OR1KSIM} will mirror real hardware more accurately. If the NPC
irrespective of when it is changed. If the @code{--strict-npc} option is
used, then @value{OR1KSIM} will mirror real hardware more accurately. If the NPC
is changed while the processor is stalled, subsequent reads of its value
will return 0 until the processor is unstalled.
 
This is not currently the default behavior, since tools such as GDB have
been implemented assuming the historic @value{OR1KSIM} behavior. However at some
been implemented assuming the historic @value{OR1KSIM} behavior. However at some
time in the future it will become the default.
 
@item --enable-profile
439,14 → 464,14
@cindex instruction profiling for @value{OR1KSIM}
 
This utility analyses instruction profile data generated by
@value{OR1KSIM}. It may be invoked as a standalone command, or from
the @value{OR1KSIM} CLI. The general form the standalone command is:
@value{OR1KSIM}. It may be invoked as a standalone command, or from
the @value{OR1KSIM} CLI. The general form the standalone command is:
 
@example
or32-uclinux-profile [-vhcq] [-g=@var{file}]
@end example
 
Many of the options have both a short and a long form. For example
Many of the options have both a short and a long form. For example
@code{-h} or @code{--help}.
 
@table @code
480,7 → 505,7
@itemx --generate=@var{file}
@cindex @code{-g}
@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.
 
@end table
490,14 → 515,14
@cindex memory profiling version of @value{OR1KSIM}
 
This utility analyses memory profile data generated by
@value{OR1KSIM}. It may be invoked as a standalone command, or from
the @value{OR1KSIM} CLI. The general form the standalone command is:
@value{OR1KSIM}. It may be invoked as a standalone command, or from
the @value{OR1KSIM} CLI. The general form the standalone command is:
 
@example
or32-uclinux-mprofile [-vh] [-m=@var{m}] [-g=@var{n}] [-f=@var{file}] @var{from} @var{to}
@end example
 
Many of the options have both a short and a long form. For example
Many of the options have both a short and a long form. For example
@code{-h} or @code{--help}.
 
@table @code
519,13 → 544,13
@itemx --mode=@var{m}
@cindex @code{-m}
@cindex @code{--mode}
Specify the mode out output. Permitted options are
Specify the mode out output. Permitted options are
 
@table @code
 
@item detailed
@itemx d
Detailed output. This is the default if no mode is specified.
Detailed output. This is the default if no mode is specified.
 
@item pretty
@itemx p
551,7 → 576,7
@itemx --filename=@var{file}
@cindex @code{-f}
@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.
 
@item @var{from}
568,11 → 593,11
@cindex library version of @value{OR1KSIM}
 
@value{OR1KSIM} may be used as a static of dynamic library,
@file{libsim.a} or @file{libsim.so}. When compiling with the static
@file{libsim.a} or @file{libsim.so}. When compiling with the static
library, the flag, @code{-lsim} should be added to the link command.
 
The header file @file{or1ksim.h} contains appropriate declarations of
the functions exported by the @value{OR1KSIM} library. These are:
the functions exported by the @value{OR1KSIM} library. These are:
 
@deftypefn {@file{or1ksim.h}} int or1ksim_init (const char *@var{config_file}, const char *@var{image_file}, void *@var{class_ptr}, unsigned long int (*@var{upr})(void *@var{class_ptr}, unsigned long int @var{addr}, unsigned long int @var{mask}), void (*@var{upw})(void *@var{class_ptr}, unsigned long int @var{addr}, unsigned long int @var{mask}, unsigned long int @var{wdata}))
 
587,17 → 612,17
 
@var{upw} is called for any write to an address external to the model
(determined by a @code{generic} section in the configuration
file). @var{upr} is called for any reads to an external address. The
file). @var{upr} is called for any reads to an external address. The
@var{class_ptr} is passed back with these upcalls, allowing the
function to associate the call with the class which originally
initialized the library.
 
@var{mask} indicates which bytes in the word are to be written or
read. Bytes to be read/written should have 0xff set in
@var{mask}. Otherwise the byte should be zero.
read. Bytes to be read/written should have 0xff set in
@var{mask}. Otherwise the byte should be zero.
 
@var{addr}, @var{mask}, @var{wdata} and the result from @var{upr} all
use host-endianess, @emph{not} model-endianess. The internal
use host-endianess, @emph{not} model-endianess. The internal
@value{OR1KSIM} routines manage all the conversion.
 
@end deftypefn
611,7 → 636,7
@deftypefn {@file{or1ksim.h}} void or1ksim_reset_duration (double @var{duration})
 
Change the duration of a run specified in an earlier call to
@code{or1ksim_run}. Typically this is called from an upcall, which
@code{or1ksim_run}. Typically this is called from an upcall, which
realizes it needs to change the duration of the run specified in the
call to @code{or1ksim_run} that has been interrupted by the upcall.
 
623,7 → 648,7
 
@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
 
643,7 → 668,7
 
@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.
 
@end deftypefn
650,8 → 675,8
 
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt (int @var{i})
 
Generate an edge-triggered interrupt on interrupt line @var{i}. The interrupt
is then immediately cleared automatically. A warning will be generated and the
Generate an edge-triggered interrupt on interrupt line @var{i}. The interrupt
is then immediately cleared automatically. A warning will be generated and the
interrupt request ignored if level sensitive interrupts have been configured
with the programmable interrupt controller (@pxref{Interrupt Configuration, ,
Interrupt Configuration}).
660,9 → 685,9
 
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_set (int @var{i})
 
Assert a level-triggered interrupt on interrupt line @var{i}. The interrupt
Assert a level-triggered interrupt on interrupt line @var{i}. The interrupt
must be cleared separately by an explicit call to
@code{or1ksim_interrupt_clear}. A warning will be generated, and the interrupt
@code{or1ksim_interrupt_clear}. A warning will be generated, and the interrupt
request ignored if edge sensitive interrupts have been configured with the
programmable interrupt controller (@pxref{Interrupt Configuration, , Interrupt
Configuration}).
672,7 → 697,7
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_clear (int @var{i})
 
Clear a level-triggered interrupt on interrupt line @var{i}, which was
previously asserted by a call to @code{or1ksim_interrupt_set}. A warning will
previously asserted by a call to @code{or1ksim_interrupt_set}. A warning will
be generated, and the interrupt request ignored if edge sensitive interrupts
have been configured with the programmable interrupt controller
(@pxref{Interrupt Configuration, , Interrupt Configuration}).
684,7 → 709,7
option to the @command{configure} script).
 
For example if the main installation directory is @file{/opt/or1ksim},
the library will be found in the @file{/opt/or1ksim/lib} directory. It
the library will be found in the @file{/opt/or1ksim/lib} directory. It
is available as both a static library (@file{libsim.a}) and a shared
object (@file{libsim.so}).
 
695,7 → 720,7
 
@item
Add the library directory to the @code{LD_LIBRARY_PATH} environment
variable during execution. For example:
variable during execution. For example:
 
@example
export LD_LIBRARY_PATH=/opt/or1ksim/lib:$LD_LIBRARY_PATH
703,7 → 728,7
 
@item
Add the library directory to the @code{LD_RUN_PATH} environment
variable during linking. For example:
variable during linking. For example:
 
@example
export LD_RUN_PATH=/opt/or1ksim/lib:$LD_RUN_PATH
711,10 → 736,10
 
@item
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
gcc ... -Wl,--rpath -Wl,/opt/or1ksim/lib ...
gcc ... -Wl,--rpath -Wl,/opt/or1ksim/lib ...
@end example
 
@item
726,10 → 751,10
@chapter Configuration
@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
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
string when initializing the @value{OR1KSIM} library. If no file is specified,
the default @file{sim.cfg} is used. The file is looked for first in the
current directory, then in the @file{$HOME/.or1k} directory of the user.
 
@menu
753,7 → 778,7
@node 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{*/}).
 
Configure files may be included, using
788,8 → 813,8
 
Depending on the parameter, the value may be a named value (an enumeration),
an integer (specified in any format acceptable in C) or a string in doubple
quotes. For flag parameters, the value 1 is used to mean ``true'' or ``on''
and the value ``0'' to mean ``false'' or ``off''. An example from a memory
quotes. For flag parameters, the value 1 is used to mean ``true'' or ``on''
and the value ``0'' to mean ``false'' or ``off''. An example from a memory
section shows each of these
 
@example
802,13 → 827,13
@end example
 
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
specified.
 
Subsections are introduced by a keyword, with a parameter value (no
@code{=} sign), and end with the same keyword prefixed by
@code{end}. Thus the ATA/ATAPI inteface (@code{@w{section ata}}) has a
@code{end}. Thus the ATA/ATAPI inteface (@code{@w{section ata}}) has a
@code{device} subsection, thus:
 
@example
824,13 → 849,13
@end example
 
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.
 
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
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
parameters of that section will take their default values.
 
839,7 → 864,7
to ensure that functionality is explicitly omitted.
 
Even if a section is disabled, all its parameters will be read and
stored. This is helpful if the section is subsequently enabled from
stored. This is helpful if the section is subsequently enabled from
the @value{OR1KSIM} command line (@pxref{Interactive Command Line, ,
Interactive Command Line}).
 
866,49 → 891,49
@cindex configuring the behavior of @value{OR1KSIM}
@cindex simulator configuration
@cindex @code{section sim}
Simulator behavior is described in @code{section sim}. This section
should appear only once. The following parameters may be specified.
Simulator behavior is described in @code{section sim}. This section
should appear only once. The following parameters may be specified.
 
@table @code
 
@item verbose = 0|1
@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
@cindex @code{debug} (simulator configuration)
0 means no debug messages. 1-9 means produce debug messages. The higher the
value the greater the number of messages. Default 0. Negative values
will be treated as 0 (with a warning). Values that are too large will
0 means no debug messages. 1-9 means produce debug messages. The higher the
value the greater the number of messages. Default 0. Negative values
will be treated as 0 (with a warning). Values that are too large will
be treated as 9 (with a warning).
 
@item profile = 0|1
@cindex @code{profile} (simulator configuration)
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}''
@cindex @code{prof_file} (simulator configuration)
@cindex @code{prof_fn} (simulator configuration - deprecated)
Specifies the file to be used with the @code{profile} parameter. Default
@file{sim.profile}. For backwards compatibility, the alternative name
Specifies the file to be used with the @code{profile} parameter. Default
@file{sim.profile}. For backwards compatibility, the alternative name
@code{prof_fn} is supported for this parameter, but deprecated.
 
@item mprofile = 0|1
@cindex @code{mprofile} (simulator configuration)
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_fn = ``@var{filename}''
@cindex @code{mprof_file} (simulator configuration)
@cindex @code{mprof_fn} (simulator configuration - deprecated)
Specifies the file to be used with the @code{mprofile} parameter. Default
@file{sim.mprofile}. For backwards compatibility, the alternative name
Specifies the file to be used with the @code{mprofile} parameter. Default
@file{sim.mprofile}. For backwards compatibility, the alternative name
@code{mprof_fn} is supported for this parameter, but deprecated.
 
@item history = 0|1
@cindex @code{history} (simulator configuration)
If 1 (true) track execution flow. Default 0.
If 1 (true) track execution flow. Default 0.
 
@quotation Note
Setting this parameter seriously degrades performance.
922,8 → 947,8
 
@item exe_log = 0|1
@cindex @code{exe_log} (simulator configuration)
If 1 (true), generate an execution log. Log is written to the file specified
in parameter @code{exe_log_file}. Default 0.
If 1 (true), generate an execution log. Log is written to the file specified
in parameter @code{exe_log_file}. Default 0.
 
@quotation Note
Setting this parameter seriously degrades performance.
937,7 → 962,7
 
@item default
@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}.
 
@item hardware
955,12 → 980,12
@item software
@cindex @code{exe_log_type=software} (simulator configuration)
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.
 
@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.
 
@quotation Note
969,29 → 994,29
 
@item exe_log_start = @var{value}
@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}
@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).
 
@item exe_log_marker = @var{value}
@cindex @code{exe_log_marker} (simulator configuration)
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}
@cindex @code{exe_log_file} (simulator configuration)
@cindex @code{exe_log_fn} (simulator configuration - deprecated)
Filename for the execution log filename if @code{exe_log} is enabled. Default
@file{executed.log}. For backwards compatibility, the alternative name
Filename for the execution log filename if @code{exe_log} is enabled. Default
@file{executed.log}. For backwards compatibility, the alternative name
@code{exe_log_fn} is supported for this parameter, but deprecated.
 
@item clkcycle = @var{value}[ps|ns|us|ms]
@cindex @code{clkcycle} (simulator configuration)
Specify the time taken by one clock cycle. If no units are specified,
@code{ps} is assumed. Default 4000ps (250MHz).
Specify the time taken by one clock cycle. If no units are specified,
@code{ps} is assumed. Default 4000ps (250MHz).
 
@end table
 
1003,11 → 1028,11
@cindex @code{section vapi}
The Verification API (VAPI) provides a TCP/IP interface to allow
components of the simulation to be controlled
externally. @xref{Verification API, , Verification API}, for more
externally. @xref{Verification API, , Verification API}, for more
details.
 
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.
 
@table @code
1014,13 → 1039,13
 
@item enabled = 0|1
@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.
 
@item server_port = @var{value}
@cindex @code{server_port} (verification API configuration)
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.
 
@quotation Tip
1028,15 → 1053,15
@cindex port range for TCP/IP
@cindex dynamic 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
@dfn{Private} port range, i.e. 49152-65535.
@dfn{Private} port range, i.e. 49152-65535.
@end quotation
 
@item log_enabled = 0|1
@cindex @code{log_enabled} (verification API configuration)
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
If 1 (true), all VAPI requests and sent commands will be logged. If 0
(the default), logging is diabled. Logs are written to the file
specified by the @code{vapi_log_file} field (see below).
 
@quotation Caution
1046,8 → 1071,8
 
@item hide_device_id = 0|1
@cindex @code{hide_device_id} (verification API configuration)
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
If 1 (true) don't log the device ID. If 0 (the default), log the
device ID. This feature (when set to 1) is provided for backwards
compatibility with an old version of VAPI.
 
@item vapi_log_file = "@var{filename}"
1054,7 → 1079,7
@cindex @code{vapi_log_file} (verification API configuration)
@cindex @code{vapi_log_fn} (verification API configuration - deprecated)
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
supported for this parameter, but deprecated.
 
1067,12 → 1092,12
@cindex CUC configuration
@cindex @code{section cuc}
The Custom Unit Compiler (CUC) was a project by Marko Mlinar to generate
Verilog from ANSI C functions. The project seems to not have progressed
beyond the initial prototype phase. The configuration parameters are
Verilog from ANSI C functions. The project seems to not have progressed
beyond the initial prototype phase. The configuration parameters are
described here for the record.
 
CUC configuration is described in @code{@w{section cuc}}. This section
may appear at most once. The following parameters may be specified.
CUC configuration is described in @code{@w{section cuc}}. This section
may appear at most once. The following parameters may be specified.
 
@table @code
 
1084,15 → 1109,15
 
@item memory_order=none
@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.
 
@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.
 
@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.
 
@cindex @code{memory_order=exact} (CUC configuration)
Exactly the same memory ordering and widths.
1099,29 → 1124,29
 
@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.
 
@item calling_convention = 0|1
@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.
 
@item enable_bursts = 0 | 1
@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.
 
@item no_multicycle = 0 | 1
@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.
 
@item timings_file = "@var{filename}"
@cindex @code{timings_file} (CUC configuration)
@cindex @code{timings_fn} (CUC configuration - deprecated)
@var{filename} specifies a file containing timing information. The
default value is @code{"virtex.tim"}. For backwards compatibility, the
@var{filename} specifies a file containing timing information. The
default value is @code{"virtex.tim"}. For backwards compatibility, the
alternative name @code{timings_fn} is supported for this parameter,
but deprecated.
 
1148,9 → 1173,9
@cindex CPU configuration
@cindex processor configuration
@cindex @code{section cpu}
CPU configuration is described in @code{section cpu}. This section
should appear only once. At present @value{OR1KSIM} does not model multi-CPU
systems. The following parameters may be specified.
CPU configuration is described in @code{section cpu}. This section
should appear only once. At present @value{OR1KSIM} does not model multi-CPU
systems. The following parameters may be specified.
 
@table @code
 
1160,7 → 1185,7
@cindex @code{ver} (CPU configuration)
@cindex @code{rev} (CPU configuration)
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
@code{cfg}, 6 bits for @code{rev}).
 
1167,7 → 1192,7
@item upr = @var{value}
@cindex @code{upr} (CPU configuration)
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
@item
UPR present (0x00000001)
1197,19 → 1222,19
@item cfgr = @var{value}
@cindex @code{cfgr} (CPU configuration)
Sets the CPU configuration register (Special Purpose Register 2) to
@var{value}. Default value is 0x00000020, i.e. support for the ORBIS32
instruction set. Attempts to set any other value are accepted, but
@var{value}. Default value is 0x00000020, i.e. support for the ORBIS32
instruction set. Attempts to set any other value are accepted, but
issue a warning that there is no support for the instruction set.
 
@item sr = @var{value}
@cindex @code{sr} (CPU configuration)
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).
 
@item superscalar = 0|1
@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.
 
In the current simulator, the only functional effect of superscalar
1223,12 → 1248,12
 
@item hazards = 0|1
@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.
 
In the current simulator, the only functional effect is to cause
logging of hazard waiting information if the CPU is
superscalar. However nowhere in the simulator is this data actually
superscalar. However nowhere in the simulator is this data actually
computed, so the net result is probably to have no effect.
 
if harzards are tracked, current hazards can be displayed using the
1241,7 → 1266,7
 
@item dependstats = 0|1
@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
the simulator's @command{stat} command.
1256,8 → 1281,8
@item sbuf_len = @var{value}
@cindex @code{sbuf_len} (CPU configuration)
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
warning. Negative values will be treated as 0 with a warning. Use 0 to
greater than 256. Larger values will be truncated to 256 with a
warning. Negative values will be treated as 0 with a warning. Use 0 to
disable the store buffer.
 
When the store buffer is active, stores are accumulated and committed
1270,15 → 1295,15
@cindex configuring memory
@cindex memory configuration
@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
memory. The following parameters may be specified.
memory. The following parameters may be specified.
 
@table @code
 
@item type=random|pattern|unknown|zero
@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}.
 
@table @code
1285,7 → 1310,7
 
@item random
@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
section (see below), thus ensuring the same ``random'' values are used
each time.
1297,12 → 1322,12
 
@item unknown
@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.
 
@item zero
@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
as such.
 
1316,13 → 1341,13
 
@item random_seed = @var{value}
@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}.
 
The default value is -1,
which means the seed will be set from a call to the @code{time}
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
particular run.
 
1329,14 → 1354,14
@item pattern = @var{value}
@cindex @code{pattern} (memory configuration)
Set the pattern to be used when initializing memory to
@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
is used to initialize each byte. More than 8 bits can be specified,
@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
is used to initialize each byte. More than 8 bits can be specified,
but will ignored with a warning.
 
@quotation Tip
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}
and not specifying a value for @code{pattern}.
@end quotation
1343,14 → 1368,14
 
@item baseaddr = @var{value}
@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
@math{2^n}. The default value is 0.
@math{2^n}. The default value is 0.
 
@item size = @var{value}
@cindex @code{size} (memory configuration)
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.
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.
 
@quotation Note
When allocating memory, the simulator will allocate the nearest
1359,7 → 1384,7
the amount allocated.
 
As a consequence users are strongly recommended to specify memory
sizes that are an exact power of 2. If some other amount of memory is
sizes that are an exact power of 2. If some other amount of memory is
required, it should be specified as separate, contiguous blocks, each
of which is a power of 2 in size.
@end quotation
1366,21 → 1391,21
 
@item name = "@var{text}"
@cindex @code{name} (memory configuration)
Name the block. Typically these describe the type of memory being
modeled (thus @code{"SRAM"} or @code{"Flash"}. The default is
Name the block. Typically these describe the type of memory being
modeled (thus @code{"SRAM"} or @code{"Flash"}. The default is
@code{@w{"anonymous memory block"}}.
 
@quotation Note
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.
@end quotation
 
@item ce = @var{value}
@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
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.
 
The default value is -1 (invalid).
1387,26 → 1412,26
 
@item mc = @var{value}
@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
mc}} for a memory controller (@pxref{Memory Controller Configuration,
, Memory Controller Configuration}).
 
Default value is 0, which is also the default value of a memory
controller @code{index} field. This is suitable therefore for designs
controller @code{index} field. This is suitable therefore for designs
with just one memory controller.
 
@item delayr = @var{value}
@cindex @code{delayr} (memory configuration)
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
The number of cycles required for a read access. Set to -1 if the
memory does not support reading. Default value 1. The simulator will
add this number of cycles to the total instruction cycle count when
reading from main memory.
 
@item delayw = @var{value}
@cindex @code{delayw} (memory configuration)
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
The number of cycles required for a write access. Set to -1 if the
memory does not support writing. Default value 1. The simulator will
add this number of cycles to the total instruction cycle count when
writing to main memory.
 
1413,7 → 1438,7
@item log = "@var{file}"
@cindex @code{log} (memory configuration)
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.
 
@end table
1430,7 → 1455,7
@cindex @code{section immu}
Memory Management Unit (MMU) configuration is described in
@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.
 
@table @code
1438,36 → 1463,36
@item enabled = 0|1
@cindex @code{enabled} (MMU configuration)
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}
@cindex @code{nsets} (MMU configuration)
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
which do not fit these criteria are ignored with a warning. The
default value is 1.
@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
default value is 1.
 
@item nways = @var{value}
@cindex @code{nways} (MMU configuration)
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
this range are ignored with a warning. The default value is 1.
@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.
 
@item pagesize = @var{value}
@cindex @code{pagesize} (MMU configuration)
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
of 2 are ignored with a warning. The default is 8192 (0x2000).
@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).
 
@item entrysize = @var{value}
@cindex @code{entrysize} (MMU configuration)
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
of 2 are ignored with a warning. The default value is 1.
@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.
 
@quotation Note
@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.
@end quotation
 
1475,12 → 1500,12
@cindex @code{ustates} (MMU configuration)
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
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.
 
@quotation Note
@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.
@end quotation
 
1487,12 → 1512,12
@item hitdelay = @var{value}
@cindex @code{hitdelay} (MMU configuration)
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}
@cindex @code{missdelay} (MMU configuration)
Set the number of cycles a data or instruction (as appropriate) MMU
miss costs. Default value 1.
miss costs. Default value 1.
 
@end table
 
1505,8 → 1530,8
@cindex @code{section dc}
@cindex @code{section ic}
Cache configuration is described in @code{section dc} (for the data
cache) and @code{seciton ic} (for the instruction cache). Each section
should appear at most once. The following parameters may be specified.
cache) and @code{seciton ic} (for the instruction cache). Each section
should appear at most once. The following parameters may be specified.
 
@table @code
 
1513,7 → 1538,7
@item enabled = 0|1
@cindex @code{enabled} (cache configuration)
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}
@cindex @code{nsets} (cache configuration)
1520,8 → 1545,8
Sets the number of data or instruction (as appropriate) cache sets to
@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
instruction cache). At the time of writing, these constants are
both defined in the code to be 1024). The default value is 1.
instruction cache). At the time of writing, these constants are
both defined in the code to be 1024). The default value is 1.
 
@item nways = @var{value}
@cindex @code{nways} (cache configuration)
1528,49 → 1553,49
Sets the number of data or instruction (as appropriate) cache ways to
@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
instruction cache). At the time of writing, these constants are both
defined in the code to be 32). The default value is 1.
instruction cache). At the time of writing, these constants are both
defined in the code to be 32). The default value is 1.
 
@item blocksize = @var{value}
@cindex @code{blocksize} (cache configuration)
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}
@cindex @code{ustates} (cache configuration)
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.
 
@item hitdelay = @var{value}
@cindex @code{hitdelay} (instruction cache configuration)
@emph{Instruction cache only}. Set the number of cycles an instruction
cache hit costs. Default value 1.
@emph{Instruction cache only}. Set the number of cycles an instruction
cache hit costs. Default value 1.
 
@item missdelay = @var{value}
@cindex @code{missdelay} (instruction cache configuration)
@emph{Instruction cache only}. Set the number of cycles an instruction
cache miss costs. Default value 1.
@emph{Instruction cache only}. Set the number of cycles an instruction
cache miss costs. Default value 1.
 
@item load_hitdelay = @var{value}
@cindex @code{load_hitdelay} (data cache configuration)
@emph{Data cache only}. Set the number of cycles a data load cache hit
costs. Default value 2.
@emph{Data cache only}. Set the number of cycles a data load cache hit
costs. Default value 2.
 
@item load_missdelay = @var{value}
@cindex @code{load_missdelay} (data cache configuration)
@emph{Data cache only}. Set the number of cycles a data load cache
miss costs. Default value 2.
@emph{Data cache only}. Set the number of cycles a data load cache
miss costs. Default value 2.
 
@item store_hitdelay = @var{value}
@cindex @code{store_hitdelay} (data cache configuration)
@emph{Data cache only}. Set the number of cycles a data store cache hit
costs. Default value 0.
@emph{Data cache only}. Set the number of cycles a data store cache hit
costs. Default value 0.
 
@item store_missdelay = @var{value}
@cindex @code{store_missdelay} (data cache configuration)
@emph{Data cache only}. Set the number of cycles a data store cache
miss costs. Default value 0.
@emph{Data cache only}. Set the number of cycles a data store cache
miss costs. Default value 0.
 
@end table
 
1582,21 → 1607,21
@cindex PIC configuration
@cindex @code{section pic}
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
interrupt controllers. The following parameters may be specified.
interrupt controllers. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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.
 
@item edge_trigger = 0|1
@cindex @code{edge_trigger} (interrupt controller)
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.
 
@end table
 
1606,7 → 1631,7
@cindex power management configuration
@cindex PMU configuration
@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
setting the different bits in the power management Special Purpose
Register (PMR, SPR 0x4000) is
1631,7 → 1656,7
@cindex power management register, SME
@cindex PMR - SME
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.
 
@item DCGE (bit mask 0x00000004)
1653,14 → 1678,14
 
On reset all bits are cleared.
 
Power management configuration is described in @code{section pm}. This
section may appear at most once. The following parameter may be specified.
Power management configuration is described in @code{section pm}. This
section may appear at most once. The following parameter may be specified.
 
@table @code
 
@item enabled = 0|1
@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.
 
@end table
1672,42 → 1697,42
@cindex BPB configuration
@cindex @code{section bpb}
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.
 
Branch prediction configuration is described in @code{section bpb}. This
section may appear at most once. The following parameters may be specified.
Branch prediction configuration is described in @code{section bpb}. This
section may appear at most once. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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.
 
@item btic = 0|1
@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.
 
@item sbp_bf_fwd = 0|1
@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.
 
@item sbp_bnf_fwd = 0|1
@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.
 
@item hitdelay = @var{value}
@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.
 
@item missdelay = @var{value}
@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.
 
@end table
1719,7 → 1744,7
@cindex debug interface configuration
@cindex @code{section debug}
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.
 
@table @code
1726,11 → 1751,12
 
@item enabled = 0|1
@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
This enables the functionality of the debug unit (its registers etc) within
the mode. It does not provide any external interface to the debug unit. For
the mode. It does not provide any external interface to the debug unit.
For
that, see @code{gdb_enabled} and @code{rsp_enabled} below.
@end quotation
 
1740,7 → 1766,7
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
@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.
 
For more detailed information on the interface to the GNU Debugger see
1749,7 → 1775,8
by Embecosm Limited (@url{www.embecosm.com}).
 
@quotation Note
@code{rsp_enabled} may not be enabled with @code{gdb_enabled} (see below). If
@code{rsp_enabled} may not be enabled with @code{gdb_enabled} (see
below). If
both are enabled, a warning is issued and only the @dfn{Remote Serial
Protocol} interface is enabled.
@end quotation
1757,7 → 1784,7
@item rsp_port = @var{value}
@cindex @code{rsp_port} (debug interface configuration)
@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
service named @code{or1ksim-rsp}.
 
1764,8 → 1791,8
@quotation Tip
@cindex TCP/IP port range for @code{or1ksim-rsp} service
There is no registered port for @value{OR1KSIM} @dfn{Remote Serial Protocol}
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.
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.
@end quotation
 
@item gdb_enabled = 0|1
1772,7 → 1799,8
@cindex @code{gdb_enabled} (debug interface configuration)
If 1 (true), the OpenRISC Remote JTAG protocol server is started, provding an
interface to an external GNU debugger, using the port specified in the
@code{server_port} field (see below), or the @code{or1ksim} TCP/IP service. If
@code{server_port} field (see below), or the @code{or1ksim} TCP/IP
service. If
0 (the default), the server is not started, and no external interface is
provided.
 
1783,13 → 1811,13
 
@quotation Note
The OpenRISC Remote JTAG protocol is unique to OpenRISC, and remains only for
backward compatibility. New users should adopt the standard GDB @dfn{Remote
backward compatibility. New users should adopt the standard GDB @dfn{Remote
Serial Protocol} interface (see @code{rsp_enabled} above) providing access to
a wider range of GDB functionality.
@end quotation
 
@quotation Note
@code{gdb_enabled} may not be enabled with @code{rsp_enabled}. If both are
@code{gdb_enabled} may not be enabled with @code{rsp_enabled}. If both are
enabled, a warning is issued and only the @dfn{Remote Serial Protocol}
interface is enabled.
@end quotation
1797,7 → 1825,7
@item server_port = @var{value}
@cindex @code{server_port} (debug interface configuration)
@var{value} specifies the port to be used for the OpenRISC Rmote JTAG
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
service named @code{or1ksim}.
 
1804,21 → 1832,21
@quotation Tip
@cindex TCP/IP port range for @code{or1ksim} service
There is no registered port for @value{OR1KSIM} Remote JTAG Interface
or service @code{or1ksim}. Good practice suggests users should adopt
or service @code{or1ksim}. Good practice suggests users should adopt
port values in the @dfn{Dynamic} or @dfn{Private} port range,
i.e. 49152-65535.
i.e. 49152-65535.
@end quotation
 
@item vapi_id = @var{value}
@cindex @code{vapi_id} (debug interface configuration)
@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.
 
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
enabled. This is the only functionality associated with VAPI for the
debug unit. No VAPI commands are sent, nor requests handled.
enabled. This is the only functionality associated with VAPI for the
debug unit. No VAPI commands are sent, nor requests handled.
 
@end table
 
1825,7 → 1853,7
@node Peripheral Configuration
@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.
 
@menu
1848,25 → 1876,25
@cindex @code{section mc}
The memory controller used in @value{OR1KSIM} is the component
implemented at OpenCores, and found in the top level CVS 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
@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 memory controller configuration is described in @code{@w{section
mc}}. This section may appear multiple times, specifying multiple
memory controllers. The following parameters may be specified.
mc}}. This section may appear multiple times, specifying multiple
memory controllers. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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.
 
@quotation Note
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
behavior of the memory controller, not as a way of disabling the
memory controller in general.
1875,7 → 1903,7
@item baseaddr = @var{value}
@cindex @code{baseaddr} (memory controller configuration)
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.
 
The memory controller has a 7 bit address bus, with a total of 19
1900,7 → 1928,7
@item index = @var{value}
@cindex @code{index} (memory controller configuration)
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,
through the @code{mc} field in the @code{@w{section memory}}
configuration (@pxref{Memory Configuration, , Memory Configuration}).
1915,14 → 1943,14
@cindex UART configuration
@cindex @code{section uart}
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.
 
The component provides a number of interfaces to emulate the behavior
of an external terminal connected to the UART.
 
UART configuration is described in @code{section uart}. This section
may appear multiple times, specifying multiple UARTs. The following
UART configuration is described in @code{section uart}. This section
may appear multiple times, specifying multiple UARTs. The following
parameters may be specified.
 
@table @code
1929,12 → 1957,12
 
@item enabled = 0|1
@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}
@cindex @code{baseaddr} (UART configuration)
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.
 
The UART has a 3 bit address bus, with a total of 8 8-bit registers,
1957,7 → 1985,7
@cindex UART I/O from/to an @command{xterm}
Create an xterm on startup, write UART Tx traffic to the xterm and
take Rx traffic from the keyboard when the xterm window is
selected. Additional arguments to the xterm command (for example
selected. Additional arguments to the xterm command (for example
specifying window size may be specified in @var{args}, or this may be
left blank.
 
1970,10 → 1998,10
 
@quotation Tip
There is no registered port for @value{OR1KSIM} telnet UART
connection. Priviledged access is required to read traffic on the
registered ``well-known'' telnet port (23). Instead users should use
connection. Priviledged access is required to read traffic on the
registered ``well-known'' telnet port (23). Instead users should use
port values in the @dfn{Dynamic} or @dfn{Private} port range,
i.e. 49152-65535.
i.e. 49152-65535.
@end quotation
 
@item channel="fd:@code{rxfd},@code{txfd}"
1983,7 → 2011,7
 
@item channel="tty:device=/dev/ttyS0,baud=9600"
@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
to machine.
 
1993,18 → 2021,18
 
@item irq = @var{value}
@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
@cindex @code{16550} (UART configuration)
If 1 (true), the UART has the functionality of a 16550. If 0 (the
default), it has the functionality of a 16450. The principal
If 1 (true), the UART has the functionality of a 16550. If 0 (the
default), it has the functionality of a 16450. The principal
difference is that the 16550 can buffer multiple characters.
 
@item jitter = @var{value}
@cindex @code{jitter} (UART configuration)
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
This functionality has yet to be implemented, so this parameter has no
2014,7 → 2042,7
@item vapi_id = @var{value}
@cindex @code{vapi_id} (UART configuration)
@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
with the UART.
 
2027,16 → 2055,16
@cindex @code{section dma}
The DMA controller used in @value{OR1KSIM} is the component
implemented at OpenCores, and found in the top level CVS 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
@file{doc} subdirectory. It is a memory mapped component, which
resides on the main OpenRISC Wishbone data bus. The present
@file{doc} subdirectory. It is a memory mapped component, which
resides on the main OpenRISC Wishbone data bus. The present
implementation is incomplete, intended only to support the Ethernet
interface (@pxref{Ethernet Configuration}), although the Ethernet
interface is not yet completed.
 
DMA configuration is described in @code{@w{section dma}}. This section
may appear multiple times, specifying multiple DMA controllers. The
DMA configuration is described in @code{@w{section dma}}. This section
may appear multiple times, specifying multiple DMA controllers. The
following parameters may be specified.
 
@table @code
2043,28 → 2071,28
 
@item enabled = 0|1
@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}
@cindex @code{baseaddr} (DMA configuration)
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.
 
The DMA controller has a 10 bit address bus, with a total of 253
32-bit registers. The first 5 registers at addresses 0x000 through
0x010 control the overall behavior of the DMA controller. There are
32-bit registers. The first 5 registers at addresses 0x000 through
0x010 control the overall behavior of the DMA controller. There are
then 31 blocks of 8 registers, controlling each of the 31 DMA channels
available. Addresses 0x014 through 0x01c are not used.
available. Addresses 0x014 through 0x01c are not used.
 
@item irq = @var{value}
@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}
@cindex @code{vapi_id} (DMA configuration)
@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
with the DMA controller.
 
2077,34 → 2105,34
@cindex @code{section ethernet}
The Ethernet MAC used in @value{OR1KSIM} is the component implemented
at OpenCores, and found in the top level CVS directory,
@file{ethernet}. It also forms part of the OpenRISC SoC, ORPSoC. It is
@file{ethernet}. It also forms part of the OpenRISC SoC, ORPSoC. It is
described in the document @cite{Ethernet IP Core Specification} by
Igor Mohor, which can be found in the @file{doc} subdirectory. It is a
Igor Mohor, which can be found in the @file{doc} subdirectory. It is a
memory mapped component, which resides on the main OpenRISC Wishbone
data bus.
 
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
interfaces. The following parameters may be specified.
interfaces. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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.
 
@item baseaddr = @var{value}
@cindex @code{baseaddr} (Ethernet configuration)
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
32-bit registers. Addresses 0x54 through 0x7c are not used.
32-bit registers. Addresses 0x54 through 0x7c are not used.
 
@quotation Note
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.
@end quotation
 
2111,11 → 2139,11
@item dma = @var{value}
@cindex @code{dma} (Ethernet configuration)
@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
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
component implementation (@pxref{DMA Configuration, , DMA
Configuration}).
2123,17 → 2151,17
 
@item irq = @var{value}
@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 = 0|1
@cindex @code{rtx_type} (Ethernet configuration)
If 1 (true) use a socket interface to the Ethernet (see parameter
@code{sockif} below). If 0 (the default), use a file interface,
@code{sockif} below). If 0 (the default), use a file interface,
reading and writing from and to the files specified in the
@code{rxfile} and @code{txfile} parameters (see below).
 
@quotation Note
By default the socket interface is not provided in @value{OR1KSIM}. If
By default the socket interface is not provided in @value{OR1KSIM}. If
it is required, this must be requested when configuring, by use of the
@code{--enable-ethphy} option to @command{configure}.
 
2147,7 → 2175,7
@itemx tx_channel = @var{txvalue}
@cindex @code{tx_channel} (Ethernet configuration)
@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
As noted above, support for external DMA is not provided in the
2162,26 → 2190,26
to use as input and @var{txfile} specifies the fie to use as
output.
 
The file contains a sequence of packets. Each packet consists of a
packet length (32 bits), followed by that many bytes of data. Once the
The file contains a sequence of packets. Each packet consists of a
packet length (32 bits), followed by that many bytes of data. Once the
input file is empty, the Ethernet MAC behaves as though there were no
data on the Ethernet. The default values of these parameters are
data on the Ethernet. The default values of these parameters are
@code{"eth_rx"} and @code{"eth_tx"} respectively.
 
The input file must exist and be readable. The output file must be
writable and will be created if necessary. If either of these
The input file must exist and be readable. The output file must be
writable and will be created if necessary. If either of these
conditions is not met, a warning will be given.
 
@item sockif = "@var{service}"
@cindex @code{sockif} (Ethernet configuration)
When @code{rtx_type} is 1 (see above), @var{service} specifies the
service to use for communication. This may be TCP/IP or UDP/IP. The
service to use for communication. This may be TCP/IP or UDP/IP. The
default value of this parameter is @code{"or1ksim_eth"}.
 
@item vapi_id = @var{value}
@cindex @code{vapi_id} (DMA configuration)
@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
with the DMA controller.
 
2193,14 → 2221,14
@cindex GPIO configuration
@cindex @code{section cpio}
The GPIO used in @value{OR1KSIM} is the component implemented at
OpenCores, and found in the top level CVS directory, @file{gpio}. It
OpenCores, and found in the top level CVS directory, @file{gpio}. It
is described in the document @cite{GPIO IP Core Specification} by
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.
 
GPIO configuration is described in @code{@w{section gpio}}. This section
may appear multiple times, specifying multiple GPIO devices. The
GPIO configuration is described in @code{@w{section gpio}}. This section
may appear multiple times, specifying multiple GPIO devices. The
following parameters may be specified.
 
@table @code
2207,29 → 2235,29
 
@item enabled = 0|1
@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}
@cindex @code{baseaddr} (GPIO configuration)
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.
 
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.
 
@item irq = @var{value}
@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}
@cindex @code{vapi_id} (GPIO configuration)
@cindex @code{base_vapi_id} (GPIO configuration - deprecated)
@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
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,
but deprecated.
 
2244,9 → 2272,9
@value{OR1KSIM} models a VGA interface to an external monitor. The
VGA controller used in @value{OR1KSIM} is the component implemented at
OpenCores, and found in the top level CVS 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
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
data bus.
 
2254,34 → 2282,34
screen to a file at intervals.
 
VGA controller configuration is described in @code{@w{section
vga}}. This section may appear multiple times, specifying multiple
VGA controllers. The following parameters may be specified.
vga}}. This section may appear multiple times, specifying multiple
VGA controllers. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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}
@cindex @code{baseaddr} (VGA configuration)
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.
 
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 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.
 
@item irq = @var{value}
@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.
 
@item refresh_rate = @var{value}
@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
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond
to dumping 50 times per simulated second.
2290,10 → 2318,10
@cindex @code{txfile} (VGA configuration)
@cindex @code{filename} (VGA configuration - deprecated)
@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
sequential count of the screen dumps starting at zero. The default
value is @code{"vga_out"}. For backwards compatibility, the
sequential count of the screen dumps starting at zero. The default
value is @code{"vga_out"}. For backwards compatibility, the
alternative name @code{filename} is supported for this parameter,
but deprecated.
 
2305,35 → 2333,35
@cindex frame buffer configuration
@cindex @code{section fb}
@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
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.
@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
buffers. The following parameters may be specified.
buffers. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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}
@cindex @code{baseaddr} (frame buffer configuration)
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,
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.
 
@item refresh_rate = @var{value}
@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
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond to
dumping 50 times per simulated second.
2342,10 → 2370,10
@cindex @code{txfile} (frame buffer configuration)
@cindex @code{filename} (frame buffer configuration - deprecated)
@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
sequential count of the screen dumps starting at zero. The default
value is @code{"fb_out"}. For backwards compatibility, the
sequential count of the screen dumps starting at zero. The default
value is @code{"fb_out"}. For backwards compatibility, the
alternative name @code{filename} is supported for this parameter,
but deprecated.
 
2358,44 → 2386,44
@cindex keyboard configuration
@cindex PS2 configuration
@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
the top level CVS directory, @file{ps2}. However this project lacks
any documentation beyond its project webpage. Since most PS2
the top level CVS directory, @file{ps2}. However this project lacks
any documentation beyond its project webpage. Since most PS2
interfaces follow the Intel i8042 standard, this is presumably what is
expected with this device.
 
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
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
0x04.
 
The port of Linux for the OpenRISC 1000, which runs on @value{OR1KSIM}
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.
 
This component should be used with caution.
@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
interfaces. The following parameters may be specified.
interfaces. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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}
@cindex @code{baseaddr} (keyboard configuration)
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,
at addresses 0x000 and 0x004.
2408,13 → 2436,13
 
@item irq = @var{value}
@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.
 
@item rxfile = "@var{file}"
@cindex @code{file} (keyboard configuration)
@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"}.
 
@end table
2427,14 → 2455,14
@cindex @code{section ata}
The ATA/ATAPI disc controller used in @value{OR1KSIM} is the OCIDEC
(OpenCores IDE Controller) component implemented at OpenCores, and
found in the top level CVS directory, @file{ata}. It is described in
found in the top level CVS directory, @file{ata}. It is described in
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
data bus.
 
ATA/ATAPI configuration is described in @code{@w{section ata}}. This section
may appear multiple times, specifying multiple disc controllers. The
ATA/ATAPI configuration is described in @code{@w{section ata}}. This section
may appear multiple times, specifying multiple disc controllers. The
following parameters may be specified.
 
@table @code
2441,39 → 2469,39
 
@item enabled = 0|1
@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.
 
@item baseaddr = @var{value}
@cindex @code{baseaddr} (ATA/ATAPI configuration)
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.
 
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.
 
@item irq = @var{value}
@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.
 
@item dev_id = 1|2|3
@cindex @code{dev_id} (ATA/ATAPI configuration)
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}
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.
 
@item rev = @var{value}
@cindex @code{rev} (ATA/ATAPI configuration)
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
should be in the range 0-15. Larger values are truncated with a
warning. This only affects the reset value of the @code{STAT}
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
warning. This only affects the reset value of the @code{STAT}
register, where it forms bits 24-27.
 
@item pio_mode0_t1 = @var{value}
2485,13 → 2513,13
@itemx pio_mode0_teoc = @var{value}
@cindex @code{pio_mode0_teoc} (ATA/ATAPI configuration)
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
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.
 
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
pio_mode0_t1 = 6
2506,14 → 2534,14
@cindex @code{dma_mode0_td} (ATA/ATAPI configuration)
@itemx dma_mode0_teoc = @var{value}
@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
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
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
warning.
 
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
dma_mode0_tm = 4
2527,16 → 2555,16
@cindex disc interface device configuration
@cindex ATA/ATAPI device configuration
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
device @var{value}
@end example
 
@var{value} is the device number, which should be 0 or 1. The
subsection ends with @code{enddevice}. Note that if the same device
@var{value} is the device number, which should be 0 or 1. The
subsection ends with @code{enddevice}. Note that if the same device
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:
 
@table @code
2550,39 → 2578,39
@item file = "@var{filename}"
@cindex @code{file} (ATA/ATAPI device configuration)
@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.
 
@item size = @var{value}
@cindex @code{size} (ATA/ATAPI device configuration)
@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
@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.
 
@item firmware = "@var{str}"
@cindex @code{firmware} (ATA/ATAPI device configuration)
Firmware to report in response to the ``Identify Device''
command. Default @code{"02207031"}.
command. Default @code{"02207031"}.
 
@item heads = @var{value}
@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}
@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
@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
@cindex @code{pio} (ATA/ATAPI device configuration)
Highest PIO mode supported. Default 4.
Highest PIO mode supported. Default 4.
 
@end table
 
2593,26 → 2621,26
@cindex @code{section generic}
When used as a library (@pxref{Simulator Library, , Simulator
Library}), @value{OR1KSIM} makes provision for any additional peripheral to be
implemented externally. Any read or write access to this peripheral's
memory map generates @dfn{upcall}s to an external handler. This
implemented externally. Any read or write access to this peripheral's
memory map generates @dfn{upcall}s to an external handler. This
interface can support either C or C++, and was particularly designed
to facilitate support for OSCI SystemC (see @url{http://www.systemc.org}).
 
Generic peripheral configuration is described in @code{@w{section
generic}}. This section may appear multiple times, specifying multiple
external peripherals. The following parameters may be specified.
generic}}. This section may appear multiple times, specifying multiple
external peripherals. The following parameters may be specified.
 
@table @code
 
@item enabled = 0|1
@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.
 
@item baseaddr = @var{value}
@cindex @code{baseaddr} (generic peripheral configuration)
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.
 
The size of the memory mapped register space is controlled by the
2621,21 → 2649,21
@item size = @var{value}
@cindex @code{size} (generic peripheral configuration)
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
parameter @code{baseaddr} (see above) will be directed to the external
interface.
 
@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
@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
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).
 
@item name = "@var{str}"
@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
reporting its status. The default value is @code{@w{"anonymous
reporting its status. The default value is @code{@w{"anonymous
external peripheral"}}.
 
@item byte_enabled = 0|1
2645,7 → 2673,7
@itemx word_enabled = 0|1
@cindex @code{word_enabled} (generic peripheral configuration)
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.
 
@end table
2655,7 → 2683,7
 
If started with the @code{-f} flag, or if interrupted with
@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
 
2668,7 → 2696,7
@cindex @code{r} (Interactive CLI)
@cindex displaying registers (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
state of the flag in the Supervision Register.
 
2682,7 → 2710,7
@cindex @code{run} (Interactive CLI)
@cindex running 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
above) @emph{unless} @code{hush} is specified.
 
2696,13 → 2724,13
@cindex @code{dm} (Interactive CLI)
@cindex displaying memory (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{fromaddr}.
 
@quotation Caution
The output from this command is broken (a bug). @value{OR1KSIM}
attempts to print out 16 bytes per row. However, instead of printing
The output from this command is broken (a bug). @value{OR1KSIM}
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
the first of the 16 bytes) before @emph{each} byte.
@end quotation
2710,7 → 2738,7
@item de @var{fromaddr} [ @var{toaddr} ]
@cindex @code{dm} (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.
 
The disassembly is entirely numerical, and gives no symbolic
2753,7 → 2781,7
@cindex @code{reset} (Interactive CLI)
@cindex simulator reset (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.
 
@item hist
2767,8 → 2795,8
@cindex @code{stall} (Interactive CLI)
@cindex processor stall (Interactive CLI)
@cindex stall the processor (Interactive CLI)
Stall the processor, so that control is passed to the debug unit. When
stalled, the processor can execute no instructions. This command is
Stall the processor, so that control is passed to the debug unit. When
stalled, the processor can execute no instructions. This command is
useful when debugging the JTAG interface, used by debuggers such as
GDB.
 
2776,7 → 2804,7
@cindex @code{unstall} (Interactive CLI)
@cindex processor unstall (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.
 
@item stats @var{category} | clear
2784,7 → 2812,7
@cindex simulator statistics (Interactive CLI)
@cindex statistics, simulation (Interactive CLI)
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
 
2799,23 → 2827,23
features.
 
@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}).
 
@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}).
 
@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}).
 
@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}).
 
@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}).
 
@end table
2824,7 → 2852,7
@cindex @code{info} (Interactive CLI)
@cindex simulator 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.
 
@item dv @var{fromaddr} [ @var{toaddr} ] [ @var{module} ]
2833,8 → 2861,8
@cindex memory dump, Verilog (Interactive CLI)
Dump the area of memory between @var{fromaddr} and @var{toaddr} as
Verilog code for a synchronous, 23-bit wide SRAM module, named
@var{module}. If @var{toaddr} is not specified, then 64 bytes are
dumped (as 16 32-bit words). If @var{module} is not specified,
@var{module}. If @var{toaddr} is not specified, then 64 bytes are
dumped (as 16 32-bit words). If @var{module} is not specified,
@code{or1k_mem} is used.
 
To save to a file, use the redirection function (described after this
2845,7 → 2873,7
@cindex hexadecimal memory dump (Interactive CLI)
@cindex memory dump, hexadecimal (Interactive CLI)
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
words).
 
2856,7 → 2884,7
@cindex @code{setdbch} (Interactive CLI)
@cindex debug channel toggle (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
command line.
 
2864,7 → 2892,7
@cindex @code{set} (Interactive CLI)
@cindex configuration parameter setting (Interactive CLI)
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.
 
@item debug
2871,12 → 2899,12
@cindex @code{debug} (Interactive CLI)
@cindex debug mode toggle (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.
 
@quotation Caution
This is effectively enabling or disabling the debug unit. It does not
effect the remote GDB debug interface. However using the remote debug
This is effectively enabling or disabling the debug unit. It does not
effect the remote GDB debug interface. However using the remote debug
interface while the debug unit is disabled will lead to undefined
behavior and likely crash @value{OR1KSIM}
@end quotation
2888,8 → 2916,8
Configuration, , CUC Configuration}).
 
@quotation Caution
The CUC must be properly configured, for this to succeed. In
particular a timing file must be available and readable. Otherwise
The CUC must be properly configured, for this to succeed. In
particular a timing file must be available and readable. Otherwise
@value{OR1KSIM} will crash.
@end quotation
 
2901,7 → 2929,7
@item mprofile [-vh] [-m @var{m}] [-g @var{n}] [-f @var{file}] @var{from} @var{to}
@cindex @code{mprofile} (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
Profiling Utility}).
 
2909,7 → 2937,7
@cindex @code{mprofile} (Interactive CLI)
@cindex 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}).
 
@end table
2925,9 → 2953,9
output, such as @code{dv}.
 
@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
completes. Until this bug is fixed, file redirection should not be
completes. Until this bug is fixed, file redirection should not be
used.
@end quotation
 
2935,22 → 2963,22
@chapter Verification API (VAPI)
 
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
cycle. Components within the simulator may send responses to such
cycle. Components within the simulator may send responses to such
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),
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
explicit command-response structure. Some components just accept
requests (e.g. to set values), some just generate sends (to report
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
explicit command-response structure. Some components just accept
requests (e.g. to set values), some just generate sends (to report
values), and some do both.
 
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
amongst components. Request commands will be directed to the component with
that base ID. This provides a simple partitioning of the command space
amongst components. Request commands will be directed to the component with
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
3009,7 → 3037,7
@item 0x04
@cindex 0x04 UART VAPI sub-command (UART verification)
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
(immediately if the data is zero).
 
3025,9 → 3053,9
@item Ethernet
@cindex Ethernet verification (VAPI)
@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
Ethernet. At present no implementation is provided behind these VAPI
Ethernet. At present no implementation is provided behind these VAPI
requests.
 
@table @code
3047,7 → 3075,7
(symbolically, GPIO_VAPI_DATA (0) offset from the base VAPI ID) any
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
GPIO.
 
3092,10 → 3120,10
@node Code 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'
definitions are not in general provided. For more on tags, see the
Linux manual page for @command{etags}. A tag file can be created
definitions are not in general provided. For more on tags, see the
Linux manual page for @command{etags}. A tag file can be created
with:
 
@example
3119,7 → 3147,7
 
@item GNU Coding Standard
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.
 
@item @code{#include} headers
3134,8 → 3162,8
be included after the system headers.
 
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
having already included it. The two exceptions are
or package header they depend on, i.e. not rely on any other header
having already included it. The two exceptions are
 
@enumerate
@item
3145,7 → 3173,7
@item
System headers which impose portability problems should be included by
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
 
3165,7 → 3193,7
 
@item @code{#include} files once only
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:
 
@example
3179,9 → 3207,9
 
@item Avoid @code{typedef}
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
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}
library and the @acronym{ELF} and @acronym{COFF} headers, because this
3207,30 → 3235,30
@end itemize
 
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}.
 
@item Don't begin names with underscore
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
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
the program.
 
@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.
 
@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
zero.
 
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.
 
A specific case is with new peripherals, which should always include a
3254,7 → 3282,7
@vindex config
The global variable @code{config} of type @code{struct config} holds
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
 
3310,7 → 3338,7
@end itemize
 
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}.
 
@item config
3318,8 → 3346,8
@vindex sections
This is a linked list of data structures holding configuration data
for all sections which are not held in the main @code{config} data
structure. In general these are components (such as peripherals and
memory) which may occur multiple times. However it also handles some
structure. In general these are components (such as peripherals and
memory) which may occur multiple times. However it also handles some
architectural components which may occur only once, such as the memory
management units, the instruction cache, the interrupt controller and
branch prediction.
3328,7 → 3356,7
@cindex runtime global structure
@vindex runtime
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.
 
@vindex runtime.cpu
3349,7 → 3377,7
@item Output Redirection
@cindex output rediretion
@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
@code{PRINTF} macro, which will write its arguments to this output stream.
 
3358,7 → 3386,7
@findex reg_sim_reset
Any peripheral may register a routine to be called when the the
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.
 
@end table
3368,7 → 3396,7
@cindex internal debugging
 
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
Behavior}) is greater than or equal to this value, the remaining
arguments are printed to the current output stream (@pxref{Output
/version.texi
1,4 → 1,4
@set UPDATED 2 March 2009
@set UPDATED-MONTH March 2009
@set EDITION 0.3.0
@set VERSION 0.3.0
@set UPDATED 20 April 2010
@set UPDATED-MONTH April 2010
@set EDITION 0.3.1-2010-04-20
@set VERSION 0.3.1-2010-04-20

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.