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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [or1ksim/] [doc/] [or1ksim.texi] - Blame information for rev 483

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 19 jeremybenn
\input texinfo   @c -*- texinfo -*-
2
@setfilename or1ksim.info
3
@afourpaper
4
@include version.texi
5
@include config.texi
6
@dircategory Embedded development
7
@direntry
8 442 julius
* Or1ksim: (or32-elf-or1ksim).  The OpenRISC 1000 Architectural
9 19 jeremybenn
                                        Simulator
10
@end direntry
11
 
12
@copying
13
This file documents the OpenRISC Architectural Simulator, @value{OR1KSIM}.
14
 
15
Copyright @copyright{} 2008, 2009 Embecosm Limited.
16
 
17
@quotation
18
Permission is granted to copy, distribute and/or modify this document
19
under the terms of the GNU Free Documentation License, Version 1.2 or
20
any later version published by the Free Software Foundation; with no
21
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
22
Texts.  A copy of the license is included in the section entitled ``GNU
23
Free Documentation License''.
24
@end quotation
25
@end copying
26
 
27
@setchapternewpage on
28
@settitle @value{OR1KSIM} User Guide
29
 
30
@syncodeindex fn cp
31
@syncodeindex vr cp
32
 
33
@titlepage
34
@title @value{OR1KSIM} User Guide
35
@author Jeremy Bennett
36
@author Embecosm Limited
37
@author Issue 1 for @value{OR1KSIM} @value{VERSION}
38
 
39
@page
40
@vskip 0pt plus 1filll
41
@insertcopying
42
 
43
Published by Embecosm Limited
44
@end titlepage
45
 
46
@contents
47
 
48
@node Top
49
@c Perhaps this should be the title of the document (but only for info,
50
@c not for TeX).  Existing GNU manuals seem inconsistent on this point.
51
@top Scope of this Document
52
 
53
This document is the user guide for @value{OR1KSIM}, the OpenRISC 1000
54
Architectural Simulator.
55
 
56
@menu
57
* Installation::
58
* Usage::
59
* Configuration::
60
* Interactive Command Line::
61
* Verification API::
62
 
63
* Code Internals::
64
 
65
* GNU Free Documentation License::  The license for this documentation
66
* Index::
67
@end menu
68
 
69
@node Installation
70
@chapter Installation
71
@cindex installing @value{OR1KSIM}
72
 
73
Installation follows standard GNU protocols.
74
 
75
@menu
76
* Preparation::
77
* Configuring the Build::
78
* Build and Install::
79
* Known Issues::
80
@end menu
81
 
82
@node Preparation
83
@section Preparation
84
 
85
Unpack the software and create a @emph{separate} directory in which to
86
build it:
87
 
88
@example
89 440 jeremybenn
tar jxf or1ksim-@value{VERSION}.tar.bz2
90
mkdir builddir_or1ksim
91
cd builddir_or1ksim
92 19 jeremybenn
@end example
93
 
94
@node Configuring the Build
95
@section Configuring the Build
96
 
97
Configure the software using the @command{configure} script in the
98
main directory.
99
 
100
The most significant argument is @code{--target}, which should specify
101 82 jeremybenn
the OpenRISC 1000 32-bit architecture.  If this argument is omitted, it will
102 19 jeremybenn
default to OpenRISC 1000 32-bit with a warning
103
 
104
@example
105 442 julius
../or1ksim-@value{VERSION}/configure --target=or32-elf ...
106 19 jeremybenn
@end example
107
 
108
There are several other options available, many of which are standard
109 82 jeremybenn
to GNU @command{configure} scripts.  Use @kbd{configure --help} to see
110
all the options.  The most useful is @code{--prefix} to specify a
111 19 jeremybenn
directory for installation of the tools.
112
 
113 104 jeremybenn
For testing (using @command{make check}), the @code{--target} parameter
114 385 jeremybenn
may be specified, to allow the target tool chain to be selected.  If not
115
specified, it will default to @code{or32-elf}, which is the same prefix
116
used with the standard OpenRISC toolchain installation script.
117 19 jeremybenn
 
118 104 jeremybenn
A number of @value{OR1KSIM} specific features in the simulator do
119
require enabling at configuration.  These include
120
 
121 19 jeremybenn
@table @code
122
@item --enable-profiling
123
@cindex @code{--enable-profiling}
124
@itemx --disable-profiling
125
@cindex @code{--disable-profiling}
126
If enabled, @value{OR1KSIM} is compiled for profiling with
127 82 jeremybenn
@command{gprof}.  This is disabled by default.  Only really of value for
128 19 jeremybenn
developers of @value{OR1KSIM}.
129
 
130
@item --enable-execution=simple
131
@itemx --enable-execution=complex
132
@itemx --enable-execution=dynamic
133
@cindex @code{--enable-execution}
134
@cindex simple model
135
@cindex complex model
136
@cindex dynamic model
137
@value{OR1KSIM} has developed to improve functionality and
138 82 jeremybenn
performance.  This feature allows three versions of @value{OR1KSIM} to be built
139 19 jeremybenn
 
140
@table @code
141
 
142
@item --enable-execution=simple
143
Build the original simple interpreting simulator
144
 
145
@item --enable-execution=complex
146 82 jeremybenn
Build a more complex interpreting simulator.  Experiments suggest this
147
is 50% faster than the simple simulator.  This is the default.
148 19 jeremybenn
 
149
@item --enable-execution=dynamic
150 82 jeremybenn
Build a dynamically compiling simulator.  This is the way many modern ISS are
151
built.  This represents a work in progress.  Currently @value{OR1KSIM} will
152 19 jeremybenn
compile, but segfaults if configured with this option.
153
 
154
@end table
155
 
156
The default is @code{--enable-execution=complex}.
157
 
158
@item --enable-ethphy
159
@cindex @code{--enable-ethphy}
160
@itemx --disable-ethphy
161
@cindex @code{--disable-ethphy}
162
@cindex Ethernet via socket, enabling
163
@cindex enabling Ethernet via socket
164
If enabled, this option allows the Ethernet to be simulated by connecting via a
165 82 jeremybenn
socket (the alternative reads and writes, from and to files).  This
166 19 jeremybenn
must then be configured using the relevant fields in the
167 82 jeremybenn
@code{ethernet} section of the configuration file.  @xref{Ethernet
168 19 jeremybenn
Configuration, , Ethernet Configuration}.
169
 
170
The default is for this to be disabled.
171
 
172 127 jeremybenn
@item --enable-unsigned-xori
173
@cindex @code{--enable-unsigned-xori}
174
@itemx --disable-unsigned-xori
175
@cindex @code{--disable-unsigned-xori}
176
@cindex exclusive-OR immediate operand
177 346 jeremybenn
Historically, @code{l.xori}, has sign extended its operand.  This is
178 127 jeremybenn
inconsistent with the other logical opcodes (@code{l.andi},
179
@code{l.ori}), but in the absence of @code{l.not}, it allows a register
180
to be inverted in a single instruction using:
181
 
182
@example
183
@code{l.xori  rD,rA,-1}
184
@end example
185
 
186 440 jeremybenn
This flag causes @value{OR1KSIM} to treat the immediate operand as unsigned (i.e
187 127 jeremybenn
to zero-extend rather than sign-extend).
188
 
189
The default is to sign-extend, so that existing code will continue to
190
work.
191
 
192
@quotation Caution
193
The GNU compiler tool chain makes heavy use of this instruction.  Using
194
unsigned behavior will require the compiler to be modified accordingly.
195
 
196
This option is provided for experimentation.  A future version of
197
OpenRISC may adopt this more consistent behavior and also provide a
198
@code{l.not} opcode.
199
@end quotation
200
 
201 19 jeremybenn
@item --enable-range-stats
202
@cindex @code{--enable-range-stats}
203
@itemx --disable-range-stats
204
@cindex @code{--disable-range-stats}
205
@cindex statistics, register over time
206
@cindex register over time statistics
207
If enabled, this option allows statistics to be collected to analyse
208 82 jeremybenn
register access over time.  The default is for this to be disabled.
209 19 jeremybenn
 
210
@item --enable-debug
211
@cindex @code{--enable-debug}
212
@itemx --disable-debug
213
@cindex @code{--disable-debug}
214
@cindex debugging enabled (Argtable2)
215
@cindex Argtable2 debugging
216 82 jeremybenn
This is a feature of the Argtable2 package used to process arguments.  If
217
enabled, some debugging features are turned on in Argtable2.  It is provided for
218 19 jeremybenn
completeness, but there is no reason why this feature should ever be needed by
219
any @value{OR1KSIM} user.
220
 
221 82 jeremybenn
@item --enable-all-tests
222
@cindex @code{--enable-all-tests}
223
@itemx --disable-all-tests
224
@cindex @code{--disable-all-tests}
225
@cindex all tests enabled
226
@cindex tests, all enabled.
227
Some of the tests (at the time of writing just one) will not compile
228
without error.  If enabled with this flag, all test programs will be
229
compiled with @command{make check}.
230
 
231
This flag is intended for those working on the test package, who wish to
232
get the missing test(s) working.
233
 
234 19 jeremybenn
@end table
235
 
236 112 jeremybenn
A number of configuration flags have been removed since version 0.3.0,
237 440 jeremybenn
because they led to invalid behavior of @value{OR1KSIM}.  Those removed are:
238 112 jeremybenn
 
239
@table @code
240
 
241 124 jeremybenn
@item --enable-arith-flag
242
@cindex @code{--enable-arith-flag}
243
@itemx --disable-arith-flag
244
@cindex @code{--disable-arith-flag}
245
@cindex flag setting by instructions
246
If enabled, this option caused certain instructions to set the flag
247
(@code{F} bit) in the supervision register if the result were zero.
248
The instructions affected by this were @code{l.add}, @code{l.addc},
249
@code{l.addi}, @code{l.and} and @code{l.andi}.
250
 
251 346 jeremybenn
If set, this caused incorrect behavior.  Whether or not flags are set is part
252 124 jeremybenn
of the OpenRISC 1000 architectural specification.  The only flags which
253
should set this are the ``set flag'' instructions: @code{l.sfeq},
254
@code{l.sfeqi}, @code{l.sfges}, @code{l.sfgesi}, @code{l.sfgeu},
255
@code{l.sfgeui}, @code{l.sfgts}, @code{l.sfgtsi}, @code{l.sfgtu},
256
@code{l.sfgtui}, @code{l.sfles}, @code{l.sflesi}, @code{l.sfleu},
257
@code{l.sfleui}, @code{l.sflts}, @code{l.sfltsi}, @code{l.sfltu},
258
@code{l.sfltui}, @code{l.sfne} and @code{l.sfnei}.
259
 
260 112 jeremybenn
@item --enable-ov-flag
261
@cindex @code{--enable-ov-flag}
262
@itemx --disable-ov-flag
263
@cindex @code{--disable-ov-flag}
264
@cindex overflow flag setting by instructions
265 124 jeremybenn
This flag caused certain instructions to set the overflow flag.  If not,
266
those instructions would not set the overflow flat.  The instructions
267
affected by this were @code{l.add}, @code{l.addc}, @code{l.addi},
268
@code{l.and}, @code{l.andi}, @code{l.div}, @code{l.divu}, @code{l.mul},
269
@code{l.muli}, @code{l.or}, @code{l.ori}, @code{l.sll}, @code{l.slli},
270
@code{l.srl}, @code{l.srli}, @code{l.sra}, @code{l.srai}, @code{l.sub},
271
@code{l.xor} and @code{l.xori}.
272 112 jeremybenn
 
273
This guaranteed incorrect behavior.  The OpenRISC 1000 architecture
274
specification defines which flags are set by which instructions.
275
 
276
Within the above list, the arithmetic instructions (@code{l.add},
277
@code{l.addc}, @code{l.addi}, @code{l.div}, @code{l.divu}, @code{l.mul},
278
@code{l.muli} and @code{l.sub}), together with @code{l.addic} which is
279
missed out, set the overflow flag.  All the others (@code{l.and},
280
@code{l.andi}, @code{l.or}, @code{l.ori}, @code{l.sll}, @code{l.slli},
281
@code{l.srl}, @code{l.srli}, @code{l.sra}, @code{l.srai}, @code{l.xor}
282
and @code{l.xori}) do not.
283
 
284
@end table
285
 
286 19 jeremybenn
@node Build and Install
287
@section Building and Installing
288 82 jeremybenn
Build the tool with:
289 19 jeremybenn
 
290
@example
291 440 jeremybenn
make all
292 82 jeremybenn
@end example
293
 
294
If you have the OpenRISC tool chain and DejaGNU installed, you can
295
verify the tool as follows (otherwise omit this step):
296
 
297
@example
298 440 jeremybenn
make check
299 82 jeremybenn
@end example
300
 
301
Install the tool with:
302
 
303
@example
304 440 jeremybenn
make install
305 19 jeremybenn
@end example
306
 
307
This will install the three variations of the @value{OR1KSIM} tool,
308 442 julius
@command{or32-elf-sim}, @command{or32-elf-psim} and
309
@command{or32-elf-mpsim}, the @value{OR1KSIM} library, @file{libsim}, the
310 19 jeremybenn
header file, @file{or1ksim.h} and this documentation in @command{info} format.
311
 
312
The documentation may be created and installed in alternative formats (PDF,
313
Postscript, DVI, HTML) with for example:
314
 
315
@example
316 440 jeremybenn
make pdf
317
make install-pdf
318 19 jeremybenn
@end example
319
 
320
@node Known Issues
321
@section Known Problems and Issues
322
 
323 346 jeremybenn
Full details of outstanding issues may be found in the @file{NEWS} file in
324
the main directory of the distribution.  The OpenRISC tracker may be used
325
to see the current state of these issues and to raise new problems and
326
feature requests.  It may be found at
327
@url{http://opencores.org/project,or1k,bugtracker}.
328 19 jeremybenn
 
329 346 jeremybenn
The following issues are long standing and unlikely to be fixed in
330 440 jeremybenn
@value{OR1KSIM} in the near future.
331 346 jeremybenn
 
332 19 jeremybenn
@itemize @bullet
333
@item
334
The Supervision Register Little Endian Enable (LEE) bit is
335 82 jeremybenn
ignored.  @value{OR1KSIM} can be built for either little endian or big endian
336 19 jeremybenn
use, but that behavior cannot be changed dynamically.
337
 
338
@item
339
@value{OR1KSIM} is not reentrant, so a program cannot instantiate
340 82 jeremybenn
multiple instances using the library.  This is clearly a problem when
341
considering multi-core applications.  However it stems from the original
342
design, and can only be fixed by a complete rewrite.  The entire source
343 19 jeremybenn
code uses static global constants liberally!
344
 
345
@end itemize
346
 
347
@node Usage
348
@chapter Usage
349
@cindex running @value{OR1KSIM}
350
 
351
@menu
352
* Standalone Simulator::
353
* Profiling Utility::
354
* Memory Profiling Utility::
355 442 julius
* Trace Generation::
356 19 jeremybenn
* Simulator Library::
357 440 jeremybenn
* Ethernet TUN/TAP Interface::
358 460 jeremybenn
* l.nop Support::
359 19 jeremybenn
@end menu
360
 
361
@node Standalone Simulator
362
@section Standalone Simulator
363
@cindex command line for @value{OR1KSIM} standalone use
364
 
365
The general form the standalone command is:
366
 
367
@example
368 442 julius
or32-elf-sim [-vhiqVt] [-f @var{file}] [--nosrv] [--srv=[@var{n}]]
369 346 jeremybenn
                 [-m <n>][-d @var{str}]
370 19 jeremybenn
                 [--enable-profile] [--enable-mprofile] [@var{file}]
371
@end example
372
 
373 82 jeremybenn
Many of the options have both a short and a long form.  For example
374 19 jeremybenn
@code{-h} or @code{--help}.
375
 
376
@table @code
377
 
378
@item -v
379
@itemx --version
380
@cindex @code{-v}
381
@cindex @code{--version}
382
Print out the version and copyright notice for @value{OR1KSIM} and
383
exit.
384
 
385
@item -h
386
@itemx --help
387
@cindex @code{-h}
388
@cindex @code{--help}
389
Print out help about the command line options and what they mean.
390
 
391 346 jeremybenn
@item -i
392
@itemx --interactive
393
@cindex @code{-i}
394
@cindex @code{--interactive}
395
After starting, drop into the @value{OR1KSIM} interactive command
396
shell.
397
 
398
@item -q
399
@itemx --quiet
400
@cindex @code{-q}
401
@cindex @code{--quiet}
402
Do not generate any information messages, only error messages.
403
 
404
@item -V
405
@itemx --verbose
406
@cindex @code{-V}
407
@cindex @code{--verbose}
408
Generate extra output messages (equivalent of specifying the ``verbose''
409
option in the simulator configuration section (see @pxref{Simulator Behavior, , Simulator Behavior}).
410
 
411 385 jeremybenn
@item -t
412
@itemx --trace
413 420 jeremybenn
@cindex @code{-t}
414
@cindex @code{--trace}
415
Dump instruction just executed and any register/memory location chaged
416
after each instruction (one line per instruction).
417 385 jeremybenn
 
418 472 jeremybenn
@item --trace-physical
419
@itemx --trace-virtual
420
@cindex @code{--trace-physical}
421
@cindex @code{--trace-virtual}
422
When tracing instructions, show the physical address
423
(@code{--trace-physical}) and/or the virtual address
424
(@code{--trace-virtual}) of the instruction being executed.  Both flags
425
may be specified, in which case both physical and virtual addresses are
426
shown, physical first.
427
 
428
@quotation Note
429
Either or both flags may be specified without @code{--trace}, to
430
indicate how addresses should be shown if subsequently enabled by a
431
@code{SIGUSER1} signal or @code{l.nop 8} opcode (@pxref{Trace
432
Generation, , Trace Generation}).
433
@end quotation
434
 
435 19 jeremybenn
@item -f @var{file}
436 385 jeremybenn
@itemx --file=@var{file}
437 19 jeremybenn
@cindex @code{-f}
438
@cindex @code{--file}
439
Read configuration commands from the specified file, looking first in
440
the current directory, and otherwise in the @file{$HOME/.or1k}
441 82 jeremybenn
directory.  If this argument is not specified, the file @file{sim.cfg}
442
in those two locations is used.  Failure to find the file is a fatal
443
error.  @xref{Configuration, , Configuration}, for detailed information
444 19 jeremybenn
on configuring @value{OR1KSIM}.
445
 
446
@item --nosrv
447
@cindex @code{--nosrv}
448 235 jeremybenn
@cindex Remote Serial Protocol, @code{--nosrv}
449
Do not start up the @dfn{Remote Serial Protocol} debug server.  This
450
overrides any setting specified in the configuration file.  This
451
option may not be specified with @code{--srv}.  If it is, a rude
452
message is printed and the @code{--nosrv} option is ignored.
453 19 jeremybenn
 
454
@item --srv
455
@item --srv=@var{n}
456
@cindex @code{--srv}
457 235 jeremybenn
@cindex Remote Serial Protocol, @code{--srv}
458
Start up the @dfn{Remote Serial Protocol} debug server.  This
459
overrides any setting specified in the configuration file.  If the
460
parameter, @var{n}, is specified, use that as the TCP/IP port for the
461
server, otherwise a random value from the private port range
462
(41920-65535) will be used.  This option may not be specified with
463
@code{--nosrv}.  If it is, a rude message is printed and the
464
@code{--nosrv} option is ignored.
465 19 jeremybenn
 
466 385 jeremybenn
@item -m @var{size}
467 346 jeremybenn
@itemx --memory=@var{size}
468
@cindex @code{-m}
469
@cindex @code{--memory}
470
Configure a memory block of @var{size} bytes, starting at address
471
zero.  The size may be followed by @samp{k}, @samp{K}, @samp{m},
472
@samp{M}, @samp{g}, @samp{G}, to indicate kilobytes (@math{2^{10}}
473
bytes), megabytes (@math{2^{20}} bytes) and gigabytes (@math{2^{30}}
474
bytes).
475
 
476 440 jeremybenn
This is mainly intended for use when @value{OR1KSIM} is used without a
477 346 jeremybenn
configuration file, to allow just the processor and memory to be set
478
up.  This is the equivalent of specifying a configuration memory section
479
with @code{baseaddr = 0} and @code{size = @var{size}} and all other
480
parameters taking their default value.
481
 
482
If a configuration file is also used, it should be sure not to specify
483
an overlapping memory block.
484
 
485 385 jeremybenn
@item -d @var{config_string}
486 19 jeremybenn
@itemx --debug-config=@var{config_string}
487
@cindex @code{-d}
488
@cindex @code{--debug-config}
489 82 jeremybenn
Enable selected debug messages in @value{OR1KSIM}.  This parameter is
490
for use by developers only, and is not covered further here.  See the
491 19 jeremybenn
source code for more details.
492
 
493 346 jeremybenn
@item --report-memory-errors
494
@cindex @code{--report-memory-errors}
495
By default all exceptions are now handled silently.  If this option is
496
specified, bus exceptions will be reported with a message to standard
497
error indicating the address at which the exception occurred.
498 19 jeremybenn
 
499 440 jeremybenn
This was the default behaviour up to @value{OR1KSIM} 0.4.0.  This flag is
500 346 jeremybenn
provided for those who wish to keep that behavior.
501
 
502 19 jeremybenn
@item --strict-npc
503
@cindex @code{--strict-npc}
504
In real hardware, setting the next program counter (NPC, SPR 16),
505 82 jeremybenn
flushes the processor pipeline.  The consequence of this is that until
506
the pipeline refills, reading the NPC will return zero.  This is typically
507 19 jeremybenn
the case when debugging, since the processor is stalled.
508
 
509
Historically, @value{OR1KSIM} has always returned the value of the NPC,
510 82 jeremybenn
irrespective of when it is changed.  If the @code{--strict-npc} option is
511
used, then @value{OR1KSIM} will mirror real hardware more accurately.  If the NPC
512 19 jeremybenn
is changed while the processor is stalled, subsequent reads of its value
513
will return 0 until the processor is unstalled.
514
 
515
This is not currently the default behavior, since tools such as GDB have
516 346 jeremybenn
been implemented assuming the historic @value{OR1KSIM} behavior.
517
However at some time in the future it will become the default.
518 19 jeremybenn
 
519
@item --enable-profile
520
@cindex @code{--enable-profile}
521
Enable instruction profiling.
522
 
523
@item --enable-mprofile
524
@cindex @code{--enable-mprofile}
525
Enable memory profiling.
526
 
527
@end table
528
 
529
@node Profiling Utility
530
@section Profiling Utility
531
@cindex profiling for @value{OR1KSIM}
532
@cindex instruction profiling for @value{OR1KSIM}
533
 
534
This utility analyses instruction profile data generated by
535 82 jeremybenn
@value{OR1KSIM}.  It may be invoked as a standalone command, or from
536
the @value{OR1KSIM} CLI.  The general form the standalone command is:
537 19 jeremybenn
 
538
@example
539 442 julius
or32-elf-profile [-vhcq] [-g=@var{file}]
540 19 jeremybenn
@end example
541
 
542 82 jeremybenn
Many of the options have both a short and a long form.  For example
543 19 jeremybenn
@code{-h} or @code{--help}.
544
 
545
@table @code
546
 
547
@item -v
548
@itemx --version
549
@cindex @code{-v} (profiling utility)
550
@cindex @code{--version} (profiling utility)
551
Print out the version and copyright notice for the @value{OR1KSIM}
552
profiling utility and exit.
553
 
554
@item -h
555
@itemx --help
556
@cindex @code{-h} (profiling utility)
557
@cindex @code{--help} (profiling utility)
558
Print out help about the command line options and what they mean.
559
 
560
@item -c
561
@itemx --cumulative
562
@cindex @code{-c}
563
@cindex @code{--cumulative}
564
Show cumulative sum of cycles in functions
565
 
566
@item -q
567
@itemx --quiet
568
@cindex @code{-q}
569
@cindex @code{--quiet}
570
Suppress messages
571
 
572
@item -g=@var{file}
573
@itemx --generate=@var{file}
574
@cindex @code{-g}
575
@cindex @code{--generate}
576 82 jeremybenn
The data file to analyse.  If omitted, the default file,
577 19 jeremybenn
@file{sim.profile} is used.
578
 
579
@end table
580
 
581
@node Memory Profiling Utility
582
@section Memory Profiling Utility
583
@cindex memory profiling version of @value{OR1KSIM}
584
 
585
This utility analyses memory profile data generated by
586 82 jeremybenn
@value{OR1KSIM}.  It may be invoked as a standalone command, or from
587
the @value{OR1KSIM} CLI.  The general form the standalone command is:
588 19 jeremybenn
 
589
@example
590 442 julius
or32-elf-mprofile  [-vh] [-m=@var{m}] [-g=@var{n}] [-f=@var{file}] @var{from} @var{to}
591 19 jeremybenn
@end example
592
 
593 82 jeremybenn
Many of the options have both a short and a long form.  For example
594 19 jeremybenn
@code{-h} or @code{--help}.
595
 
596
@table @code
597
 
598
@item -v
599
@itemx --version
600
@cindex @code{-v} (memory profiling utility)
601
@cindex @code{--version} (memory profiling utility)
602
Print out the version and copyright notice for the @value{OR1KSIM}
603
memory profiling utility and exit.
604
 
605
@item -h
606
@itemx --help
607
@cindex @code{-h} (memory profiling utility)
608
@cindex @code{--help} (memory profiling utility)
609
Print out help about the command line options and what they mean.
610
 
611
@item -m=@var{m}
612
@itemx --mode=@var{m}
613
@cindex @code{-m}
614
@cindex @code{--mode}
615 82 jeremybenn
Specify the mode out output.  Permitted options are
616 19 jeremybenn
 
617
@table @code
618
 
619
@item detailed
620
@itemx d
621 82 jeremybenn
Detailed output.  This is the default if no mode is specified.
622 19 jeremybenn
 
623
@item pretty
624
@itemx p
625
Pretty printed output.
626
 
627
@item access
628
@itemx a
629
Memory accesses only.
630
 
631
@item width
632
@itemx w
633
Access width only.
634
 
635
@end table
636
 
637
@item -g=@var{n}
638
@itemx --group=@var{n}
639
@cindex @code{-g}
640
@cindex @code{--group}
641
Group @math{2^n} bits of successive addresses together.
642
 
643
@item -f=@var{file}
644
@itemx --filename=@var{file}
645
@cindex @code{-f}
646
@cindex @code{--filename}
647 82 jeremybenn
The data file to analyse.  If not specified, the default,
648 19 jeremybenn
@file{sim.profile} is used.
649
 
650
@item @var{from}
651
@itemx @var{to}
652
@cindex memory profiling start address
653
@cindex memory profiling end address
654
@var{from} and @var{to} are respectively the start and end address of
655
the region of memory to be analysed.
656
 
657
@end table
658
 
659 442 julius
@node Trace Generation
660
@section Trace Generation
661
@cindex trace generation of @value{OR1KSIM}
662
 
663 443 jeremybenn
An execution trace can be generated at run time with options passed by
664
the command line, or via the operating system's signal passing
665 472 jeremybenn
mechanism, or by @code{l.nop} opcodes in an application program.
666 442 julius
 
667 472 jeremybenn
The following flag can be used to create an execution dump.
668 442 julius
 
669
@table @code
670
 
671
@item -t
672
@itemx --trace
673
@cindex @code{-t}
674
@cindex @code{--trace}
675 472 jeremybenn
Dump instruction just executed and any register/memory location changed
676
after each instruction (one line per instruction).  Each line starts
677
with either ``S'' or ``U'' to indicate whether the processor was in
678
supervisor or user mode @emph{when the instruction completed}.  It is
679
worth bearing in mind that tracing happens at completion of instruction
680
execution and shows the state at that time.
681 442 julius
@end table
682
 
683 443 jeremybenn
Passing a signal @code{SIGUSR1} while the simulator is running toggles
684
trace generation. This can be done with the following command, assuming
685
@value{OR1KSIM}'s executable name is @code{or32-elf-sim}:
686 442 julius
 
687
@example
688
pkill -SIGUSR1 or32-elf-sim
689
@end example
690
 
691 443 jeremybenn
This is useful in the case where trace output is desired after a
692
significant amount of simulation time, where it would be inconvenient to
693
generate trace up to that point.
694 442 julius
 
695 443 jeremybenn
If the @code{pkill} utility is not available, the @code{kill} utility
696
can be used if @value{OR1KSIM}'s process number is known. Use the
697
following to determine the process ID of the @code{or32-elf-sim} and
698
then send the @code{SIGUSR1} command to toggle execution trace
699
generation:
700 442 julius
 
701
@example
702
ps a | grep or32-elf-sim
703
kill -SIGUSR1 @emph{process-number}
704
@end example
705
 
706 472 jeremybenn
@cindex l.nop 8 (turn on tracing)
707
@cindex l.nop 8 (turn off tracing)
708
Tracing can also be enabled and disabled from within a target program
709
using the @code{l.nop 8} and @code{l.nop 9} opcodes to enable and
710
disable tracing respectively.
711 442 julius
 
712 472 jeremybenn
@cindex @code{--trace-physical}
713
@cindex @code{--trace-virtual}
714
By default tracing will show the virtual address of each instruction
715
traced.  This may be controlled by two options, @code{--trace-physical}
716
to show the physical address and/or @code{--trace-virtual} to show the
717
virtual address. If neither is specified, the virtual address is shown.
718
 
719
@quotation Note
720
Either or both flags may be specified without @code{--trace}, to
721
indicate how addresses should be shown if subsequently enabled by a
722
@code{SIGUSER1} signal or @code{l.nop 8} opcode.
723
@end quotation
724
 
725 19 jeremybenn
@node Simulator Library
726
@section Simulator Library
727
@cindex library version of @value{OR1KSIM}
728
 
729
@value{OR1KSIM} may be used as a static of dynamic library,
730 82 jeremybenn
@file{libsim.a} or @file{libsim.so}.  When compiling with the static
731 19 jeremybenn
library, the flag, @code{-lsim} should be added to the link command.
732
 
733
The header file @file{or1ksim.h} contains appropriate declarations of
734 82 jeremybenn
the functions exported by the @value{OR1KSIM} library.  These are:
735 19 jeremybenn
 
736 432 jeremybenn
@deftypefn {@file{or1ksim.h}} int or1ksim_init (int @var{argc}, @
737
           char *@var{argv}, void *@var{class_ptr}, @
738
           int (*@var{upr})(void *@var{class_ptr}, @
739
           unsigned long int @var{addr}, unsigned char @var{mask}[], @
740
           unsigned char @var{rdata}[], int @var{data_len}), @
741
           int (*@var{upw})(void *@var{class_ptr}, @
742
           unsigned long int @var{addr}, @
743
           unsigned char @var{mask}[], unsigned char @var{wdata}[], @
744
           int @var{data_len}))
745 19 jeremybenn
 
746 346 jeremybenn
The initialization function is supplied with a vector of arguments,
747
which are interpreted as arguments to the standalone version (see
748
@pxref{Standalone Simulator, , Standalone Simulator}), a pointer to the
749
calling class, @var{class_ptr} (since the library may be used from C++)
750
and two up-call functions, one for reads, @var{upr}, and one for writes,
751 19 jeremybenn
@var{upw}.
752
 
753
@var{upw} is called for any write to an address external to the model
754
(determined by a @code{generic} section in the configuration
755 82 jeremybenn
file).  @var{upr} is called for any reads to an external address.  The
756 19 jeremybenn
@var{class_ptr} is passed back with these upcalls, allowing the
757
function to associate the call with the class which originally
758 93 jeremybenn
initialized the library.  Both @var{upw} and @var{upr} should return
759
zero on success and non-zero otherwise.  At the present time the meaning
760
of non-zero values is not defined but this may change in the future.
761 19 jeremybenn
 
762 93 jeremybenn
@var{mask} indicates which bytes in the data are to be written or
763 82 jeremybenn
read.  Bytes to be read/written should have 0xff set in
764 93 jeremybenn
@var{mask}.  Otherwise the byte should be zero.  The adddress,
765
@var{addr}, is the @emph{full} address, since the upcall function must
766
handle all generic devices, using the full address for decoding.
767 19 jeremybenn
 
768 346 jeremybenn
Endianness is not a concern, since @value{OR1KSIM} is transferring byte
769
vectors, not multi-byte values.
770 19 jeremybenn
 
771 346 jeremybenn
The result indicates whether the initialization was successful.  The
772
integer values are available as an @code{enum or1ksim}, with possible
773
values @code{OR1KSIM_RC_OK} and @code{OR1KSIM_RC_BADINIT}.
774
 
775 93 jeremybenn
@quotation Caution
776 346 jeremybenn
This is a change from versions 0.3.0 and 0.4.0.  It further simplifies
777
the interface, and makes @value{OR1KSIM} more consistent with payload
778
representation in SystemC TLM 2.0.
779 93 jeremybenn
@end quotation
780
 
781
@quotation Note
782 440 jeremybenn
The current implementation of @value{OR1KSIM} always transfers single words (4
783 93 jeremybenn
bytes), using masks if smaller values are required.  In this it mimcs the
784
behavior of the WishBone bus.
785
@end quotation
786
 
787 19 jeremybenn
@end deftypefn
788
 
789
@deftypefn {@file{or1ksim.h}} int or1ksim_run (double  @var{duration})
790
 
791 346 jeremybenn
Run the simulator for the simulated duration specified (in seconds).  A
792
duration of -1 indicates `run forever'
793 19 jeremybenn
 
794 346 jeremybenn
The result indicates how the run terminated.  The integer values are
795
available as an @code{enum or1ksim}, with possible values
796
@code{OR1KSIM_RC_OK} (ran for the full duration),
797
@code{OR1KSIM_RC_BRKPT} (terminated early due to hitting a breakpoint)
798
and @code{OR1KSIM_RC_HALTED} (terminated early due to hitting
799
@code{l.nop 1}).
800
 
801 19 jeremybenn
@end deftypefn
802
 
803
@deftypefn {@file{or1ksim.h}} void or1ksim_reset_duration (double @var{duration})
804
 
805
Change the duration of a run specified in an earlier call to
806 82 jeremybenn
@code{or1ksim_run}.  Typically this is called from an upcall, which
807 19 jeremybenn
realizes it needs to change the duration of the run specified in the
808
call to @code{or1ksim_run} that has been interrupted by the upcall.
809
 
810
The time specified is the amount of time that the run must continue
811
for (i.e the duration from @emph{now}, not the duration from the original
812
call to @code{or1ksim_run}).
813
 
814
@end deftypefn
815
 
816
@deftypefn {@file{or1ksim.h}} void  or1ksim_set_time_point ()
817
 
818 82 jeremybenn
Set a timing point.  For use with @code{or1ksim_get_time_period}.
819 19 jeremybenn
 
820
@end deftypefn
821
 
822
@deftypefn {@file{or1ksim.h}} double  or1ksim_get_time_period ()
823
 
824
Return the simulated time (in seconds) that has elapsed since the last
825
call to @code{or1ksim_set_time_point}.
826
 
827
@end deftypefn
828
 
829
@deftypefn {@file{or1ksim.h}} int  or1ksim_is_le ()
830
 
831
Return 1 (logical true) if the @value{OR1KSIM} simulation is
832
little-endian, 0 otherwise.
833
 
834
@end deftypefn
835
 
836
@deftypefn {@file{or1ksim.h}} unsigned long int  or1ksim_clock_rate ()
837
 
838 82 jeremybenn
Return the @value{OR1KSIM} clock rate (in Hz).  This is the value
839 19 jeremybenn
specified in the configuration file.
840
 
841
@end deftypefn
842
 
843
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt (int  @var{i})
844
 
845 432 jeremybenn
Generate an edge-triggered interrupt on interrupt line @var{i}.  The
846
interrupt must be cleared separately by clearing the corresponding bit
847
in the PICSR SPR.  Until the interrupt is cleared, any further
848
interrupts on the same line will be ignored with a warning.  A warning
849
will be generated and the interrupt request ignored if level sensitive
850
interrupts have been configured with the programmable interrupt
851
controller (@pxref{Interrupt Configuration, , Interrupt Configuration}).
852 19 jeremybenn
 
853
@end deftypefn
854
 
855
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_set (int  @var{i})
856
 
857 432 jeremybenn
Assert a level-triggered interrupt on interrupt line @var{i}.  The
858
interrupt must be cleared separately by an explicit call to
859
@code{or1ksim_interrupt_clear}.  Until the interrupt is cleared, any
860
further setting of interrupts on the same line will be ignored with a
861
warning.  A warning will be generated, and the interrupt request ignored
862
if edge sensitive interrupts have been configured with the programmable
863
interrupt controller (@pxref{Interrupt Configuration, , Interrupt
864 19 jeremybenn
Configuration}).
865
 
866
@end deftypefn
867
 
868
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_clear (int  @var{i})
869
 
870
Clear a level-triggered interrupt on interrupt line @var{i}, which was
871 82 jeremybenn
previously asserted by a call to @code{or1ksim_interrupt_set}.  A warning will
872 19 jeremybenn
be generated, and the interrupt request ignored if edge sensitive interrupts
873
have been configured with the programmable interrupt controller
874
(@pxref{Interrupt Configuration, , Interrupt Configuration}).
875
 
876
@end deftypefn
877
 
878 104 jeremybenn
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_reset ()
879
 
880 346 jeremybenn
Drive a reset sequence through the JTAG interface.  Return the (model)
881 104 jeremybenn
time taken for this action.  Remember that the JTAG has its own clock,
882
which can be an order of magnitude slower than the main clock, so even a
883
reset (5 JTAG cycles) could take 50 processor clock cycles to complete.
884
 
885
@end deftypefn
886
 
887 432 jeremybenn
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_ir @
888
           (unsigned char *@var{jreg}, int @var{num_bits})
889 104 jeremybenn
 
890 346 jeremybenn
Shift the supplied register through the JTAG instruction register.
891
Return the (model) time taken for this action.  The register is supplied
892
as a byte vector, with the least significant bits in the least
893 104 jeremybenn
significant byte.  If the total number of bits is not an exact number of
894
bytes, then the odd bits are found in the least significant end of the
895
highest numbered byte.
896
 
897
For example a 12-bit register would have bits 0-7 in byte 0 and bits
898
11-8 in the least significant 4 bits of byte 1.
899
 
900
@end deftypefn
901
 
902 432 jeremybenn
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_dr @
903
           (unsigned char *@var{jreg}, int @var{num_bits})
904 104 jeremybenn
 
905
Shift the supplied register through the JTAG data register.  Return the
906 346 jeremybenn
(model) time taken for this action.  The register is supplied as a byte
907 104 jeremybenn
vector, with the least significant bits in the least significant byte.
908
If the total number of bits is not an exact number of bytes, then the
909
odd bits are found in the least significant end of the highest numbered
910
byte.
911
 
912
For example a 12-bit register would have bits 0-7 in byte 0 and bits
913
11-8 in the least significant 4 bits of byte 1.
914
 
915
@end deftypefn
916
 
917 432 jeremybenn
@deftypefn {@file{or1ksim.h}} int or1ksim_read_mem @
918
           (unsigned long int @var{addr}, unsigned char *@var{buf}, @
919
           int @var{len})
920 346 jeremybenn
 
921
Read @var{len} bytes from @var{addr}, placing the result in @var{buf}.
922
Return @var{len} on success and 0 on failure.
923
 
924
@quotation Note
925 440 jeremybenn
This function was added in @value{OR1KSIM} 0.5.0.
926 346 jeremybenn
@end quotation
927
 
928
@end deftypefn
929
 
930 432 jeremybenn
@deftypefn {@file{or1ksim.h}} int or1ksim_write_mem @
931
           (unsigned long int @var{addr}, const unsigned char *@var{buf}, @
932
           int @var{len})
933 346 jeremybenn
 
934
Write @var{len} bytes to @var{addr}, taking the data from @var{buf}.
935
Return @var{len} on success and 0 on failure.
936
 
937
@quotation Note
938 440 jeremybenn
This function was added in @value{OR1KSIM} 0.5.0.
939 346 jeremybenn
@end quotation
940
 
941
@end deftypefn
942
 
943 432 jeremybenn
@deftypefn {@file{or1ksim.h}} int or1ksim_read_spr (int @var{sprnum}, @
944
           unsigned long int *@var{sprval_ptr})
945 346 jeremybenn
 
946
Read the SPR specified by @var{sprnum}, placing the result in
947
@var{sprval_ptr}.  Return non-zero on success and 0 on failure.
948
 
949
@quotation Note
950 440 jeremybenn
This function was added in @value{OR1KSIM} 0.5.0.
951 346 jeremybenn
@end quotation
952
 
953
@end deftypefn
954
 
955 432 jeremybenn
@deftypefn {@file{or1ksim.h}} int or1ksim_write_spr (int @var{sprnum}, @
956
           unsigned long int @var{sprva})
957 346 jeremybenn
 
958
Write @var{sprval} to the SPR specified by @var{sprnum}.  Return
959
non-zero on success and 0 on failure.
960
 
961
@quotation Note
962 440 jeremybenn
This function was added in @value{OR1KSIM} 0.5.0.
963 346 jeremybenn
@end quotation
964
 
965
@end deftypefn
966
 
967 432 jeremybenn
@deftypefn {@file{or1ksim.h}} int or1ksim_read_reg (int @var{regnum}, @
968
           unsigned long int *@var{regval_ptr})
969 346 jeremybenn
 
970
Read the general purpose register specified by @var{regnum}, placing the
971
result in @var{regval_ptr}.  Return non-zero on success and 0 on
972
failure.
973
 
974
@quotation Note
975 440 jeremybenn
This function was added in @value{OR1KSIM} 0.5.0.
976 346 jeremybenn
@end quotation
977
 
978
@end deftypefn
979
 
980 432 jeremybenn
@deftypefn {@file{or1ksim.h}} int or1ksim_write_reg (int @var{regnum}, @
981
           unsigned long int @var{regva})
982 346 jeremybenn
 
983
Write @var{regval} to the general purpose register specified by
984
@var{regnum}.  Return non-zero on success and 0 on failure.
985
 
986
@quotation Note
987 440 jeremybenn
This function was added in @value{OR1KSIM} 0.5.0.
988 346 jeremybenn
@end quotation
989
 
990
@end deftypefn
991
 
992 432 jeremybenn
@deftypefn {@file{or1ksim.h}} void or1ksim_set_stall_state (int @var{state})
993 346 jeremybenn
 
994
Set the processor's state according to @var{state} (1 = stalled, 0 = not
995
stalled).
996
 
997
@quotation Note
998 440 jeremybenn
This function was added in @value{OR1KSIM} 0.5.0.
999 346 jeremybenn
@end quotation
1000
 
1001
@end deftypefn
1002
 
1003 19 jeremybenn
The libraries will be installed in the @file{lib} sub-directory of the
1004
main installation directory (as specified with the @option{--prefix}
1005
option to the @command{configure} script).
1006
 
1007
For example if the main installation directory is @file{/opt/or1ksim},
1008 82 jeremybenn
the library will be found in the @file{/opt/or1ksim/lib} directory.  It
1009 19 jeremybenn
is available as both a static library (@file{libsim.a}) and a shared
1010
object (@file{libsim.so}).
1011
 
1012
To link against the library add the @option{-lsim} flag when linking
1013
and do one of the following:
1014
 
1015
@itemize @bullet
1016
 
1017
@item
1018
Add the library directory to the @code{LD_LIBRARY_PATH} environment
1019 82 jeremybenn
variable during execution.  For example:
1020 19 jeremybenn
 
1021
@example
1022
export LD_LIBRARY_PATH=/opt/or1ksim/lib:$LD_LIBRARY_PATH
1023
@end example
1024
 
1025
@item
1026
Add the library directory to the @code{LD_RUN_PATH} environment
1027 82 jeremybenn
variable during linking.  For example:
1028 19 jeremybenn
 
1029
@example
1030
export LD_RUN_PATH=/opt/or1ksim/lib:$LD_RUN_PATH
1031
@end example
1032
 
1033
@item
1034
Use the linker @option{--rpath} option and specify the library
1035 82 jeremybenn
directory when linking your program.  For example
1036 19 jeremybenn
 
1037
@example
1038 82 jeremybenn
gcc ...  -Wl,--rpath -Wl,/opt/or1ksim/lib ...
1039 19 jeremybenn
@end example
1040
 
1041
@item
1042
Add the library directory to @file{/etc/ld.so.conf}
1043
 
1044
@end itemize
1045
 
1046 440 jeremybenn
@node Ethernet TUN/TAP Interface
1047
@section Ethernet TUN/TAP Interface
1048
@cindex configuring the Ethernet TUN/TAP interface
1049
 
1050
When an Ethernet peripheral is configured (@pxref{Ethernet
1051
Configuration, , Ethernet Configuration}), one option is to tunnel
1052
traffic through a TUN/TAP interface.  The low level TAP interface is used
1053
to tunnel raw Ethernet datagrams.
1054
 
1055
The TAP interface can then be connected to a physical Ethernet through a
1056
bridge, allowing the @value{OR1KSIM} model to connect to a physical
1057
network.  This is particularly when @value{OR1KSIM} is running the
1058
OpenRISC Linux kernel image.
1059
 
1060
This section explains how to set up a bridge for use by @value{OR1KSIM}. It does
1061
require superuser access to the host machine (or at least the relevant
1062
network capabilities). A system administrator can modify these
1063
guidelines so they are executed on reboot if appropriate.
1064
 
1065
@menu
1066
* Setting Up a Persistent TAP device::
1067
* Establishing a Bridge::
1068
* Opening the Firewall::
1069
* Disabling Ethernet Filtering::
1070
* Networking from OpenRISC Linux and BusyBox::
1071
* Tearing Down a Bridge::
1072
@end menu
1073
 
1074
@node Setting Up a Persistent TAP device
1075
@subsection Setting Up a Persistent TAP device
1076
@cindex persistent TAP device creation
1077
@cindex TAP device creation
1078
 
1079
TUN/TAP devices can be created dynamically, but this requires superuser
1080
privileges (or at least @code{CAP_NET_ADMIN} capability).  The solution
1081
is to create a persistent TAP device.  This can be done using either
1082
@command{openvpn} or @command{tunctl}.  In either case the package must
1083
be installed on the host system.  Using @command{openvpn}, the following
1084
would set up a TAP interface for a specified user and group.
1085
 
1086
@example
1087
openvpn --mktun --dev tap@emph{n} --user @emph{username} --group @emph{groupname}
1088
@end example
1089
 
1090
@node Establishing a Bridge
1091
@subsection Establishing a Bridge
1092
@cindex bridge setup
1093
@cindex Ethernet bridge setup
1094
 
1095
A bridge is a ``virtual'' local area network interfaces, subsuming two or more
1096
existing network interfaces.  In this case we will bridge the physical
1097
Ethernet interface of the host with the TAP interface that will be used
1098
by @value{OR1KSIM}.
1099
 
1100
The Ethernet and TAP must lose their own individual IP addresses (by
1101
setting them to 0.0.0.0) and are replaced by the IP address of the
1102
bridge interface. To do this we use the @command{bridge-utils} package,
1103
which must be installed on the host system. These commands are require
1104
superuser privileges or @code{CAP_NET_ADMIN} capability. To create a new
1105
interface @code{br@emph{n}} the following commands are appropriate.
1106
 
1107
@example
1108
brctl addbr br@emph{n}
1109
brctl addif br@emph{n} eth@emph{x}
1110
brctl addif br@emph{n} tap@emph{y}
1111
 
1112
ifconfig eth@emph{x} 0.0.0.0 promisc up
1113
ifconfig tap@emph{y} 0.0.0.0 promisc up
1114
 
1115
dhclient br@emph{n}
1116
@end example
1117
 
1118
The last command instructs the bridge to obtain its IP address, netmask,
1119
broadcast address, gateway and nameserver information using DHCP.  In a
1120
network without DHCP it should be replaced by @command{ifconfig} to set
1121
a static IP address, netmask and broadcast address.
1122
 
1123
@quotation Note
1124
This will leave a spare dhclient process running in the background,
1125
which should be killed for tidiness. There is a technique to avoid this
1126
using @command{omshell}, but that is beyond the scope of this guide.
1127
@end quotation
1128
 
1129
@quotation Note
1130
It is not clear to the author why the existing interfaces need to be
1131
brought up in promiscuous mode, but it seems to cure various problems.
1132
@end quotation
1133
 
1134
@node Opening the Firewall
1135
@subsection  Opening the Firewall
1136
@cindex firewall with Ethernet bridge and TAP/TUN
1137
 
1138
Firewall rules should be added to ensure traffic flows freely through
1139
the TAP and bridge interfaces. As superuser the following commands are
1140
appropriate.
1141
 
1142
@example
1143
iptables -A INPUT -i tap@emph{y} -j ACCEPT
1144
iptables -A INPUT -i br@emph{n} -j ACCEPT
1145
iptables -A FORWARD -i br@emph{n} -j ACCEPT
1146
@end example
1147
 
1148
@node Disabling Ethernet Filtering
1149
@subsection Disabling Ethernet Filtering
1150
 
1151
Some systems may have ethernet filtering enabled (@command{ebtables},
1152
@command{bridge-nf}, @command{arptables}) which will stop traffic
1153
flowing through the bridge.
1154
 
1155
The easiest way to disable this is by writing zero to all
1156
@file{bridge-nf-*} entries in @file{/proc/sys/net/bridge}. As superuser
1157
the following commands will achieve this.
1158
 
1159
@example
1160
cd /proc/sys/net/bridge
1161
for f in bridge-nf-*; do echo 0 > $f; done
1162
@end example
1163
 
1164
@node Networking from OpenRISC Linux and BusyBox
1165
@subsection Networking from OpenRISC Linux and BusyBox
1166
@cindex BusyBox and Ethernet
1167
@cindex Linux (OpenRISC) and Ethernet
1168
 
1169
The main use of this style of Ethernet interface to @value{OR1KSIM} is when
1170
running the OpenRISC Linux kernel with BusyBox. The following commands
1171
in the BusyBox console window will configure the Ethernet interface
1172
(assumed to be @code{eth0}) and bring it up with a DHCP assigned
1173
address.
1174
 
1175
@example
1176
ifconfig eth0
1177
ifup eth0
1178
@end example
1179
 
1180
At this stage interface to IP addresses will work correctly.
1181
 
1182
For DNS to work the BusyBox system needs to know where to find a
1183
nameserver.  Under BusyBox, @command{udhcp} does not configure
1184
@file{/etc/resolv.conf} automatically.
1185
 
1186
The solution is to duplicate the nameserver entry from the
1187
@file{/etc/resolv.conf} file of the host on the BusyBox system. A
1188
typical file might be as follows:
1189
 
1190
@example
1191
@code{nameserver 192.168.0.1}
1192
@end example
1193
 
1194
It is convenient to make this permanent within the Linux initramfs. Add
1195
the file as @code{arch/openrisc/support/initramfs/etc/resolv.conf}
1196
within the Linux source tree and rebuild @code{vmlinux}. It will then be
1197
present automatically.
1198
 
1199
One of the most useful functions that is possible is to mount
1200
the host file system through NFS. For example, from the BusyBox console:
1201
 
1202
@example
1203
mount -t nfs -o nolock 192.168.0.60:/home /mnt
1204
@end example
1205
 
1206
Another useful technique is to telnet into the BusyBox system from the
1207
host. This is particularly valuable when a console process locks up,
1208
since the @command{xterm} console will not recognize ctrl-C. Instead the
1209
rogue process can be killed from a telnet connection.
1210
 
1211
@node Tearing Down a Bridge
1212
@subsection Tearing Down a Bridge
1213
 
1214
There is little reason why a bridge should ever need to be torn down,
1215
but if desired, the following commands will achieve the effect.
1216
 
1217
@example
1218
ifconfig br@emph{n} down
1219
brctl delbr br@emph{n}
1220
 
1221
dhclient eth@emph{x}
1222
@end example
1223
 
1224
As before this will leave a spare @command{dhclient} process in the
1225
background which should be killed.
1226
 
1227
If desired the TAP interface can be deleted using
1228
 
1229
@example
1230
openvpn --rmtun -dev tap@emph{y}
1231
@end example
1232
 
1233
@quotation Caution
1234
The TAP interface should not be in use when running this command. For
1235
example any OpenRISC Linux/BusyBox sessions should be closed first.
1236
@end quotation
1237
 
1238 460 jeremybenn
@node l.nop Support
1239
@section l.nop Opcode Support
1240
@cindex l.nop opcode effects
1241
 
1242
The OpenRISC @code{l.nop} opcode can take a parameter.  This has no
1243
effect on the semantics of the opcode, but can be used to trigger side
1244
effect behavior in a simulator.  Within Or1ksim, the following parameters
1245
are supported.
1246
 
1247
@table @code
1248
 
1249
@item l.nop 0
1250
@cindex @code{l.nop 0}
1251
 
1252
The equivalent to @code{l.nop} with no parameter. Has no side effects.
1253
 
1254
@item l.nop 1
1255
@cindex @code{l.nop 1} (end simulation)
1256
 
1257
Execution of Or1ksim is terminated. This is used to implement the
1258
library @code{exit} functions.
1259
 
1260
@item l.nop 2
1261
@cindex @code{l.nop 2} (report)
1262
 
1263
Report the value in @code{r3} on the console as a 32-bit hex value.
1264
 
1265
@item l.nop 3
1266
@cindex @code{l.nop 3} (printf, now obsolete)
1267
 
1268
In earlier versions of @value{OR1KSIM} this treated @code{r3} as a
1269
pointer to a @code{printf} style format string, and regsiters @code{r4}
1270
through @code{r8} as parameters for that format string.
1271
 
1272
This opcode is no longer supported, and has no effect if used.
1273
 
1274
@item l.nop 4
1275
@cindex @code{l.nop 4} (putc)
1276
 
1277
The value in @code{r3} is printed to standard output as an ASCII
1278
character.  All library output routines are implemented using this opcode.
1279
 
1280
@item l.nop 5
1281
@cindex @code{l.nop 5} (reset statistics counters)
1282
 
1283
The statistics counters are reset.
1284
 
1285
@item l.nop 6
1286
@cindex @code{l.nop 6} (get clock ticks)
1287
 
1288
The number of clock ticks since start of execution (a 64-bit value) is
1289
returned in @code{r11} (low 32 bits) and @code{r12} (high 32 bits).
1290
 
1291
@item l.nop 7
1292
@cindex @code{l.nop 7} (get picoseconds per cycle)
1293
 
1294
The number of picoseconds per clock cycle is returned in @code{r11}.
1295
This is used with @code{l.nop 6} to implement timing functions.
1296
 
1297
@item l.nop 8
1298
@cindex @code{l.nop 8} (turn on tracing)
1299
 
1300
Instruction tracing is turned on.
1301
 
1302
@item l.nop 9
1303
@cindex @code{l.nop 9} (turn off tracing)
1304
 
1305
Instruction tracing is turned off.
1306
 
1307 483 jeremybenn
@item l.nop 10
1308
@cindex @code{l.nop 10} (return a random number)
1309
 
1310
A 32-bit random number is returned in @code{r11}.
1311
 
1312
The random numbers are generated using @code{random}, which in turn is
1313
seeded through @code{srandom} using the host @file{/dev/urandom} if
1314
available, or else the process ID of the @value{OR1KSIM} instance.
1315
 
1316
This opcode is particularly useful for situations where a target
1317
program running on Or1ksim needs to obtain genuine system entropy to
1318
generate random numbers.
1319
 
1320
@item l.nop 11
1321
@cindex @code{l.nop 11} (return a non-zero value)
1322
 
1323
Return a non-zero value in @code{r11}.
1324
 
1325
This opcode can be used to detect if a target is running under
1326
Or1ksim.  Set @code{r11} to zero, issue this opcode, and look to see
1327
if @code{r11} is non-zero.
1328
 
1329 460 jeremybenn
@end table
1330
 
1331 19 jeremybenn
@node Configuration
1332
@chapter Configuration
1333
@cindex configuring @value{OR1KSIM}
1334
 
1335 82 jeremybenn
@value{OR1KSIM} is configured through a configuration file.  This is specified
1336 19 jeremybenn
through the @code{-f} parameter to the @value{OR1KSIM} command, or passed as a
1337 82 jeremybenn
string when initializing the @value{OR1KSIM} library.  If no file is specified,
1338
the default @file{sim.cfg} is used.  The file is looked for first in the
1339 224 jeremybenn
current directory, then in the @file{$HOME/.or1ksim} directory of the user.
1340 19 jeremybenn
 
1341
@menu
1342
* Configuration File Format::
1343
* Simulator Configuration::
1344
* Core OpenRISC Configuration::
1345
* Peripheral Configuration::
1346
@end menu
1347
 
1348
@node Configuration File Format
1349
@section Configuration File Format
1350
@cindex configuration file structure
1351
 
1352 346 jeremybenn
The configuration file is a plain text file.  A reference example,
1353
@file{sim.cfg}, is included in the top level directory of the
1354
distribution.
1355 19 jeremybenn
 
1356
@menu
1357
* Configuration File Preprocessing::
1358
* Configuration File Syntax::
1359
@end menu
1360
 
1361
@node Configuration File Preprocessing
1362
@subsection Configuration File Preprocessing
1363
 
1364 82 jeremybenn
The configuration file may include C style comments (i.e.  delimited by
1365 19 jeremybenn
@code{/*} and @code{*/}).
1366
 
1367
@node Configuration File Syntax
1368
@subsection Configuration File Syntax
1369
 
1370
The configuration file is divided into a series of sections, with the general
1371
form:
1372
 
1373
@example
1374
section @var{section_name}
1375
 
1376
  <contents>...
1377
 
1378
end
1379
@end example
1380
 
1381
Sections may also have sub-sections within them (currently only the
1382
ATA/ATAPI disc interface uses this).
1383
 
1384
Within a section, or sub-section are a series of parameter assignments, one
1385
per line, withe the general form
1386
 
1387
@example
1388
  @var{parameter} = @var{value}
1389
@end example
1390
 
1391
Depending on the parameter, the value may be a named value (an enumeration),
1392
an integer (specified in any format acceptable in C) or a string in doubple
1393 82 jeremybenn
quotes.  For flag parameters, the value 1 is used to mean ``true'' or ``on''
1394
and the value ``0'' to mean ``false'' or ``off''.  An example from a memory
1395 19 jeremybenn
section shows each of these
1396
 
1397
@example
1398
section memory
1399
  type    = random
1400
  pattern = 0x00
1401
  name    = "FLASH"
1402
  ...
1403
end
1404
@end example
1405
 
1406
Many parameters are optional and take reasonable default values if not
1407 82 jeremybenn
specified.  However there are some parameters (for example the
1408 19 jeremybenn
@code{ce} parameter in @code{@w{section memory}}) @emph{must} be
1409
specified.
1410
 
1411
Subsections are introduced by a keyword, with a parameter value (no
1412
@code{=} sign), and end with the same keyword prefixed by
1413 82 jeremybenn
@code{end}.  Thus the ATA/ATAPI inteface (@code{@w{section ata}}) has a
1414 19 jeremybenn
@code{device} subsection, thus:
1415
 
1416
@example
1417
section ata
1418
  ...
1419
  device 0
1420
    type    = 1
1421
    file = "@var{filename}"
1422
    ...
1423
  enddevice
1424
  ...
1425
end
1426
@end example
1427
 
1428
Some sections (for example @code{@w{section sim}}) should appear only
1429 82 jeremybenn
once.  Others (for example @code{@w{section memory}} may appear
1430 19 jeremybenn
multiple times.
1431
 
1432
Sections may be omitted, @emph{unless they contain parameters which
1433 82 jeremybenn
are non-optional}.  If the section describes a part of the simulator
1434 19 jeremybenn
which is optional (for example whether it has a UART), then that
1435 82 jeremybenn
functionality will not be provided.  If the section describes a part of
1436 19 jeremybenn
the simulator which is not optional (for example the CPU), then all the
1437
parameters of that section will take their default values.
1438
 
1439
All optional parts of the functionality are always described by
1440
sections including a @code{enabled} parameter, which can be set to 0
1441
to ensure that functionality is explicitly omitted.
1442
 
1443
Even if a section is disabled, all its parameters will be read and
1444 82 jeremybenn
stored.  This is helpful if the section is subsequently enabled from
1445 19 jeremybenn
the @value{OR1KSIM} command line (@pxref{Interactive Command Line, ,
1446
Interactive Command Line}).
1447
 
1448
@quotation Tip
1449
It generally clearer to have sections describing @emph{all}
1450
components, with omitted functionality explicitly indicated by setting
1451
the @code{enabled} parameter to 0
1452
@end quotation
1453
 
1454
The following sections describe the various configuration sections and the
1455
parameters which may be set in each.
1456
 
1457
@node Simulator Configuration
1458
@section Simulator Configuration
1459
 
1460
@menu
1461
* Simulator Behavior::
1462
* Verification API Configuration::
1463
* CUC Configuration::
1464
@end menu
1465
 
1466
@node Simulator Behavior
1467
@subsection Simulator Behavior
1468
@cindex configuring the behavior of @value{OR1KSIM}
1469
@cindex simulator configuration
1470
@cindex @code{section sim}
1471 82 jeremybenn
Simulator behavior is described in @code{section sim}.  This section
1472
should appear only once.  The following parameters may be specified.
1473 19 jeremybenn
 
1474
@table @code
1475
 
1476
@item verbose = 0|1
1477
@cindex @code{verbose} (simulator configuration)
1478 82 jeremybenn
If 1 (true), print extra messages.  Default 0.
1479 19 jeremybenn
 
1480
@item debug = 0-9
1481
@cindex @code{debug} (simulator configuration)
1482 82 jeremybenn
 
1483
value the greater the number of messages.  Default 0.  Negative values
1484
will be treated as 0 (with a warning).  Values that are too large will
1485 19 jeremybenn
be treated as 9 (with a warning).
1486
 
1487
@item profile = 0|1
1488
@cindex @code{profile} (simulator configuration)
1489
If 1 (true) generate a profiling file using the file specified in the
1490 82 jeremybenn
@code{prof_file} parameter or otherwise @file{sim.profile}.  Default 0.
1491 19 jeremybenn
 
1492
@item prof_file = ``@var{filename}''
1493
@cindex @code{prof_file} (simulator configuration)
1494
@cindex @code{prof_fn} (simulator configuration - deprecated)
1495 82 jeremybenn
Specifies the file to be used with the @code{profile} parameter.  Default
1496
@file{sim.profile}.  For backwards compatibility, the alternative name
1497 346 jeremybenn
@code{prof_fn} is supported for this parameter, but deprecated.  Default
1498
@file{sim.profile}.
1499 19 jeremybenn
 
1500 346 jeremybenn
 
1501 19 jeremybenn
@item mprofile = 0|1
1502
@cindex @code{mprofile} (simulator configuration)
1503
If 1 (true) generate a memory profiling file using the file specified in the
1504 82 jeremybenn
@code{mprof_file} parameter or otherwise @file{sim.mprofile}.  Default 0.
1505 19 jeremybenn
 
1506 346 jeremybenn
@item mprof_file = ``@var{filename}''
1507 19 jeremybenn
@cindex @code{mprof_file} (simulator configuration)
1508
@cindex @code{mprof_fn} (simulator configuration - deprecated)
1509 82 jeremybenn
Specifies the file to be used with the @code{mprofile} parameter.  Default
1510
@file{sim.mprofile}.  For backwards compatibility, the alternative name
1511 19 jeremybenn
@code{mprof_fn} is supported for this parameter, but deprecated.
1512 346 jeremybenn
Default @file{sim.mprofile}.
1513 19 jeremybenn
 
1514
@item history = 0|1
1515
@cindex @code{history} (simulator configuration)
1516 82 jeremybenn
If 1 (true) track execution flow.  Default 0.
1517 19 jeremybenn
 
1518
@quotation Note
1519
Setting this parameter seriously degrades performance.
1520
@end quotation
1521
 
1522
@quotation Note
1523
If this execution flow tracking is enabled, then @code{dependstats}
1524
must be enabled in the CPU configuration section (@pxref{CPU
1525
Configuration, , CPU Configuration}).
1526
@end quotation
1527
 
1528
@item exe_log = 0|1
1529
@cindex @code{exe_log} (simulator configuration)
1530 82 jeremybenn
If 1 (true), generate an execution log.  Log is written to the file specified
1531
in parameter @code{exe_log_file}.  Default 0.
1532 19 jeremybenn
 
1533
@quotation Note
1534
Setting this parameter seriously degrades performance.
1535
@end quotation
1536
 
1537
@item exe_log_type = default|hardware|simple|software
1538
@cindex @code{exe_log_type} (simulator configuration)
1539
Type of execution log to produce.
1540
 
1541
@table @code
1542
 
1543
@item default
1544
@cindex @code{exe_log_type=default} (simulator configuration)
1545 82 jeremybenn
Produce default output for the execution log.  In the current implementation
1546 19 jeremybenn
this is the equivalent of @code{hardware}.
1547
 
1548
@item hardware
1549
@cindex @code{exe_log_type=hardware} (simulator configuration)
1550
After each instruction execution, log the number of instructions executed so
1551
far, the next instruction to execute (in hex), the general purpose registers
1552
(GPRs), status register, exception program counter, exception, effective
1553
address register and exception status register.
1554
 
1555
@item simple
1556
@cindex @code{exe_log_type=simple} (simulator configuration)
1557
After each instruction execution, log the number of instructions executed so
1558
far and the next instruction to execute, symbolically disassembled.
1559
 
1560
@item software
1561
@cindex @code{exe_log_type=software} (simulator configuration)
1562
After each instruction execution, log the number of instructions executed so
1563 82 jeremybenn
far and the next instruction to execute, symbolically disassembled.  Also show
1564 19 jeremybenn
the value of each operand to the instruction.
1565
 
1566
@end table
1567
 
1568 82 jeremybenn
Default value @code{hardware}.  Any unrecognized keyword (case
1569 19 jeremybenn
insensitive) will be treated as the default with a warning.
1570
 
1571
@quotation Note
1572
Execution logs can be @emph{very} big.
1573
@end quotation
1574
 
1575
@item exe_log_start = @var{value}
1576
@cindex @code{exe_log_start} (simulator configuration)
1577 82 jeremybenn
Address of the first instruction to start logging.  Default 0.
1578 19 jeremybenn
 
1579
@item exe_log_end = @var{value}
1580
@cindex @code{exe_log_end} (simulator configuration)
1581 82 jeremybenn
Address of the last instruction to log.  Default no limit (i.e once started
1582 19 jeremybenn
logging will continue until the simulator exits).
1583
 
1584
@item exe_log_marker = @var{value}
1585
@cindex @code{exe_log_marker} (simulator configuration)
1586
Specifies the number of instructions between printing horizontal
1587 82 jeremybenn
markers.  Default is to produce no markers.
1588 19 jeremybenn
 
1589
@item exe_log_file = @var{filename}
1590
@cindex @code{exe_log_file} (simulator configuration)
1591
@cindex @code{exe_log_fn} (simulator configuration - deprecated)
1592 82 jeremybenn
Filename for the execution log filename if @code{exe_log} is enabled.  Default
1593
@file{executed.log}.  For backwards compatibility, the alternative name
1594 19 jeremybenn
@code{exe_log_fn} is supported for this parameter, but deprecated.
1595
 
1596 202 julius
@item exe_bin_insn_log = 0|1
1597
@cindex @code{exe_bin_insn_log} (simulator configuration)
1598 346 jeremybenn
Enable logging of executed instructions to a file in binary format.
1599
This is helpful for off-line dynamic execution analysis.
1600 202 julius
 
1601
@quotation Note
1602 346 jeremybenn
Execution logs can be @emph{very} big.  For example, while booting the
1603
Linux kernel, version 2.6.34, a log file 1.2GB in size was generated.
1604 202 julius
@end quotation
1605
 
1606
@item exe_bin_insn_log_file = @var{filename}
1607
@cindex @code{exe_bin_insn_log_file} (simulator configuration)
1608
Filename for the binary execution log filename if @code{exe_bin_insn_log} is
1609
enabled.  Default @file{exe-insn.bin}.
1610
 
1611
 
1612 19 jeremybenn
@item clkcycle = @var{value}[ps|ns|us|ms]
1613
@cindex @code{clkcycle} (simulator configuration)
1614 82 jeremybenn
Specify the time taken by one clock cycle.  If no units are specified,
1615
@code{ps} is assumed.  Default 4000ps (250MHz).
1616 19 jeremybenn
 
1617
@end table
1618
 
1619
@node Verification API Configuration
1620
@subsection Verification API (VAPI) Configuration
1621
@cindex configuring the Verification API (VAPI)
1622
@cindex Verification API configuration
1623
@cindex VAPI configuration
1624
@cindex @code{section vapi}
1625
The Verification API (VAPI) provides a TCP/IP interface to allow
1626
components of the simulation to be controlled
1627 82 jeremybenn
externally.  @xref{Verification API, , Verification API}, for more
1628 19 jeremybenn
details.
1629
 
1630
Verification API configuration is described in @code{section
1631 82 jeremybenn
vapi}.  This section may appear at most once.  The following parameters
1632 19 jeremybenn
may be specified.
1633
 
1634
@table @code
1635
 
1636
@item enabled = 0|1
1637
@cindex @code{enabled} (verification API configuration)
1638 82 jeremybenn
If 1 (true), verification API is enabled and its server started.  If 0
1639 19 jeremybenn
(the default), it is disabled.
1640
 
1641
@item server_port = @var{value}
1642
@cindex @code{server_port} (verification API configuration)
1643
When VAPI is enabled, communication will be via TCP/IP on the port
1644 82 jeremybenn
specified by @var{value}.  The value must lie in the range 1 to 65535.
1645 19 jeremybenn
The default value is 50000.
1646
 
1647
@quotation Tip
1648
@cindex TCP/IP port range
1649
@cindex port range for TCP/IP
1650
@cindex dynamic ports, use of
1651
@cindex private ports, use of
1652 82 jeremybenn
There is no registered port for @value{OR1KSIM} VAPI.  Good practice
1653 19 jeremybenn
suggests users should adopt port values in the @dfn{Dynamic} or
1654 82 jeremybenn
@dfn{Private} port range, i.e.  49152-65535.
1655 19 jeremybenn
@end quotation
1656
 
1657
@item log_enabled = 0|1
1658
@cindex @code{log_enabled} (verification API configuration)
1659 82 jeremybenn
If 1 (true), all VAPI requests and sent commands will be logged.  If 0
1660
(the default), logging is diabled.  Logs are written to the file
1661 19 jeremybenn
specified by the @code{vapi_log_file} field (see below).
1662
 
1663
@quotation Caution
1664
This can generate a substantial amount of file I/O and seriously
1665
degrade simulator performance.
1666
@end quotation
1667
 
1668
@item hide_device_id = 0|1
1669
@cindex @code{hide_device_id} (verification API configuration)
1670 82 jeremybenn
If 1 (true) don't log the device ID.  If 0 (the default), log the
1671
device ID.  This feature (when set to 1) is provided for backwards
1672 19 jeremybenn
compatibility with an old version of VAPI.
1673
 
1674
@item vapi_log_file = "@var{filename}"
1675
@cindex @code{vapi_log_file} (verification API configuration)
1676
@cindex @code{vapi_log_fn} (verification API configuration - deprecated)
1677
Use @file{filename} as the file for logged data is logging is enabled
1678 82 jeremybenn
(see @code{log_enabled} above).  The default is @code{"vapi.log"}.  For
1679 19 jeremybenn
backwards compatibility, the alternative name @code{vapi_log_fn} is
1680
supported for this parameter, but deprecated.
1681
 
1682
@end table
1683
 
1684
@node CUC Configuration
1685
@subsection Custom Unit Compiler (CUC) Configuration
1686
@cindex configuring the Custom Unit Compiler (CUC)
1687
@cindex Custom Unit Compiler Configuration
1688
@cindex CUC configuration
1689
@cindex @code{section cuc}
1690
The Custom Unit Compiler (CUC) was a project by Marko Mlinar to generate
1691 82 jeremybenn
Verilog from ANSI C functions.  The project seems to not have progressed
1692
beyond the initial prototype phase.  The configuration parameters are
1693 19 jeremybenn
described here for the record.
1694
 
1695 82 jeremybenn
CUC configuration is described in @code{@w{section cuc}}.  This section
1696
may appear at most once.  The following parameters may be specified.
1697 19 jeremybenn
 
1698
@table @code
1699
 
1700
@item memory_order = none|weak|strong|exact
1701
@cindex @code{memory_order} (CUC configuration)
1702
This parameter specifies the memory ordering required:
1703
 
1704
@table @code
1705
 
1706
@item memory_order=none
1707
@cindex @code{memory_order=none} (CUC configuration)
1708 82 jeremybenn
Different memory ordering, even if there are dependencies.  Bursts can
1709 19 jeremybenn
be made, width can change.
1710
 
1711 346 jeremybenn
@item memory_order=weak
1712 19 jeremybenn
@cindex @code{memory_order=weak} (CUC configuration)
1713 82 jeremybenn
Different memory ordering, even if there are dependencies.  If
1714 19 jeremybenn
dependencies cannot occur, then bursts can be made, width can change.
1715
 
1716 346 jeremybenn
@item memory_order=strong
1717 19 jeremybenn
@cindex @code{memory_order=strong} (CUC configuration)
1718 82 jeremybenn
Same memory ordering.  Bursts can be made, width can change.
1719 19 jeremybenn
 
1720 346 jeremybenn
@item memory_order=exact
1721 19 jeremybenn
@cindex @code{memory_order=exact} (CUC configuration)
1722
Exactly the same memory ordering and widths.
1723
 
1724
@end table
1725
 
1726 82 jeremybenn
The default value is @code{memory_order=exact}.  Invalid memory
1727 19 jeremybenn
orderings are ignored with a warning.
1728
 
1729
@item calling_convention = 0|1
1730
@cindex @code{calling_convention} (CUC configuration)
1731 82 jeremybenn
If 1 (true), programs follow OpenRISC calling conventions.  If 0 (the
1732 19 jeremybenn
default), they may use other convenitions.
1733
 
1734
@item enable_bursts = 0 | 1
1735
@cindex @code{enable_bursts} (CUC configuration)
1736 82 jeremybenn
If 1 (true), bursts are detected.  If 0 (the default), bursts are not
1737 19 jeremybenn
detected.
1738
 
1739
@item no_multicycle = 0 | 1
1740
@cindex @code{no_multicycle} (CUC configuration)
1741 82 jeremybenn
If 1 (true), no multicycle logic paths will be generated.  If 0 (the
1742 19 jeremybenn
default), multicycle logic paths will be generated.
1743
 
1744
@item timings_file = "@var{filename}"
1745
@cindex @code{timings_file} (CUC configuration)
1746
@cindex @code{timings_fn} (CUC configuration - deprecated)
1747 82 jeremybenn
@var{filename} specifies a file containing timing information.  The
1748
default value is @code{"virtex.tim"}.  For backwards compatibility, the
1749 19 jeremybenn
alternative name @code{timings_fn} is supported for this parameter,
1750
but deprecated.
1751
 
1752
@end table
1753
 
1754
@node Core OpenRISC Configuration
1755
@section Configuring the OpenRISC Architectural Components
1756
 
1757
@menu
1758
* CPU Configuration::
1759
* Memory Configuration::
1760
* Memory Management Configuration::
1761
* Cache Configuration::
1762
* Interrupt Configuration::
1763
* Power Management Configuration::
1764
* Branch Prediction Configuration::
1765
* Debug Interface Configuration::
1766
@end menu
1767
 
1768
@node CPU Configuration
1769
@subsection CPU Configuration
1770
@cindex configuring the CPU
1771
@cindex configuring the processor
1772
@cindex CPU configuration
1773
@cindex processor configuration
1774
@cindex @code{section cpu}
1775 82 jeremybenn
CPU configuration is described in @code{section cpu}.  This section
1776
should appear only once.  At present @value{OR1KSIM} does not model multi-CPU
1777
systems.  The following parameters may be specified.
1778 19 jeremybenn
 
1779
@table @code
1780
 
1781
@item ver = @var{value}
1782
@item cfg = @var{value}
1783
@item rev = @var{value}
1784
@cindex @code{ver} (CPU configuration)
1785
@cindex @code{rev} (CPU configuration)
1786
The values are used to form the corresponding fields in the @code{VR}
1787 82 jeremybenn
Special Purpose Register (SPR 0).  Default values 0.  A warning is given
1788 19 jeremybenn
and the value truncated if it is too large (8 bits for @code{ver} and
1789
@code{cfg}, 6 bits for @code{rev}).
1790
 
1791
@item upr = @var{value}
1792
@cindex @code{upr} (CPU configuration)
1793
Used as the value of the Unit Present Register (UPR) Special Purpose Register
1794 82 jeremybenn
(SPR 1) to @var{value}.  Default value is 0x0000075f, i.e.
1795 19 jeremybenn
@itemize @bullet
1796
@item
1797
UPR present (0x00000001)
1798
@item
1799
Data cache present (0x00000002)
1800
@item
1801
Instruction cache present (0x00000004)
1802
@item
1803
Data MMY present (0x00000008)
1804
@item
1805
Instruction MMU present (0x00000010)
1806
@item
1807
Debug unit present (0x00000040)
1808
@item
1809
Power management unit present (0x00000100)
1810
@item
1811
Programmable interrupt controller present (0x00000200)
1812
@item
1813
Tick timer present (0x00000400)
1814
@end itemize
1815
 
1816
However, with the exection of the UPR present (0x00000001) and tick
1817
timer present, the various
1818
fields will be modified with the values specified in their corresponding
1819
configuration sections.
1820
 
1821
@item cfgr = @var{value}
1822
@cindex @code{cfgr} (CPU configuration)
1823
Sets the CPU configuration register (Special Purpose Register 2) to
1824 82 jeremybenn
@var{value}.  Default value is 0x00000020, i.e.  support for the ORBIS32
1825
instruction set.  Attempts to set any other value are accepted, but
1826 19 jeremybenn
issue a warning that there is no support for the instruction set.
1827
 
1828
@item sr = @var{value}
1829
@cindex @code{sr} (CPU configuration)
1830
Sets the supervision register Special Purpose Register (SPR 0x11) to
1831 82 jeremybenn
@var{value}.  Default value is 0x00008001, i.e.  start in supervision
1832 19 jeremybenn
mode (0x00000001) and set the ``Fixed One'' bit (0x00008000).
1833
 
1834 98 jeremybenn
@quotation Note
1835
This is particularly useful when an image is held in Flash at high
1836
memory (0xf0000000).  The EPH  bit can be set, so that interrupt
1837
vectors are basedf at 0xf0000000, rather than 0x0.
1838
@end quotation
1839
 
1840 19 jeremybenn
@item superscalar = 0|1
1841
@cindex @code{superscalar} (CPU configuration)
1842 82 jeremybenn
If 1, the processor operates in superscalar mode.  Default value is
1843 19 jeremybenn
0.
1844
 
1845
In the current simulator, the only functional effect of superscalar
1846
mode is to affect the calculation of the number of cycles taken to
1847
execute an instruction.
1848
 
1849
@quotation Caution
1850
The code for this does not appear to be complete or well tested, so
1851
users are advised not to use this option.
1852
@end quotation
1853
 
1854
@item hazards = 0|1
1855
@cindex @code{hazards} (CPU configuration)
1856 82 jeremybenn
If 1, data hazards are tracked in a superscalar CPU.  Default value is
1857 19 jeremybenn
0.
1858
 
1859
In the current simulator, the only functional effect is to cause
1860
logging of hazard waiting information if the CPU is
1861 82 jeremybenn
superscalar.  However nowhere in the simulator is this data actually
1862 19 jeremybenn
computed, so the net result is probably to have no effect.
1863
 
1864
if harzards are tracked, current hazards can be displayed using the
1865
simulator's @command{r} command.
1866
 
1867
@quotation Caution
1868
The code for this does not appear to be complete or well tested, so
1869
users are advised not to use this option.
1870
@end quotation
1871
 
1872
@item dependstats = 0|1
1873
@cindex @code{dependstats} (CPU configuration)
1874 82 jeremybenn
If 1, inter-instruction dependencies are calculated.  Default value 0.
1875 19 jeremybenn
 
1876
If these values are calculated, the depencies can be displayed using
1877
the simulator's @command{stat} command.
1878
 
1879
@quotation Note
1880
This field must be enabled, if execution execution flow tracking
1881
(field @code{history}) has been requested in the simulator
1882
configuration section (@pxref{Simulator Behavior, , Simulator
1883
Behavior}).
1884
@end quotation
1885
 
1886
@item sbuf_len = @var{value}
1887
@cindex @code{sbuf_len} (CPU configuration)
1888
The length of the store buffer is set to @var{value}, which must be no
1889 82 jeremybenn
greater than 256.  Larger values will be truncated to 256 with a
1890
warning.  Negative values will be treated as 0 with a warning.  Use 0 to
1891 19 jeremybenn
disable the store buffer.
1892
 
1893
When the store buffer is active, stores are accumulated and committed
1894
when I/O is idle.
1895
 
1896 100 julius
@item hardfloat = 0|1
1897
@cindex @code{hardfloat} (CPU configuration)
1898 346 jeremybenn
If 1, hardfloat instructions are enabled.  Default value 0.
1899 101 jeremybenn
 
1900 19 jeremybenn
@end table
1901
 
1902
@node Memory Configuration
1903
@subsection Memory Configuration
1904
@cindex configuring memory
1905
@cindex memory configuration
1906
@cindex @code{section memory}
1907 82 jeremybenn
Memory configuration is described in @code{section memory}.  This
1908 19 jeremybenn
section may appear multiple times, specifying multiple blocks of
1909 98 jeremybenn
memory.
1910 19 jeremybenn
 
1911 98 jeremybenn
@quotation Caution
1912 346 jeremybenn
The user may choose whether or not to enable a memory controller.  If a
1913 385 jeremybenn
memory controller is enabled, then appropriate initalization code must
1914
be provided.  The section describing memory controller configuration
1915
describes the steps necessary for using smaller or larger memory
1916
sections (@pxref{Memory Controller Configuration, , Memory Controller
1917
Configuration}).
1918 98 jeremybenn
 
1919 385 jeremybenn
The @dfn{uClibc} startup code initalizes a memory controller, assumed to
1920
be mapped at 0x93000000.  If a memory controller is @emph{not} enabled,
1921
then the standard C library code will generate memory access errors.
1922
The solution is to declare an additional writable memory block, mimicing
1923
the memory controller's register bank as follows.
1924 98 jeremybenn
 
1925
@example
1926
section memory
1927
  pattern = 0x00
1928
  type = unknown
1929
  name = "MC shadow"
1930
  baseaddr = 0x93000000
1931
  size     = 0x00000080
1932
  delayr = 2
1933
  delayw = 4
1934
end
1935
@end example
1936
 
1937
@end quotation
1938
 
1939
 
1940
The following parameters may be specified.
1941
 
1942 19 jeremybenn
@table @code
1943
 
1944 418 julius
@item type=random|pattern|unknown|zero|exitnops
1945 19 jeremybenn
@cindex @code{type} (memory configuration)
1946 82 jeremybenn
Specifies the values to which memory should be initialized.  The
1947 19 jeremybenn
default value is @code{unknown}.
1948
 
1949
@table @code
1950
 
1951
@item random
1952
@cindex @code{type=random} (memory configuration)
1953 82 jeremybenn
Set the memory values to be a random value.  A seed for the random
1954 19 jeremybenn
generator may be set using the @code{random_seed} field in this
1955
section (see below), thus ensuring the same ``random'' values are used
1956
each time.
1957
 
1958
@item pattern
1959
@cindex @code{type=pattern} (memory configuration)
1960
Set the memory values to be a pattern value, which is set using the
1961
@code{pattern} field in this section (see below).
1962
 
1963
@item unknown
1964
@cindex @code{type=unknown} (memory configuration)
1965 82 jeremybenn
The memory values are not initialized (i.e.  left ``unknown'').  This
1966 346 jeremybenn
option will yield faster initialization of the simulator.  This is the
1967
default.
1968 19 jeremybenn
 
1969
@item zero
1970
@cindex @code{type=zero} (memory configuration)
1971 82 jeremybenn
Set the memory values to be 0.  This is the equivalent of
1972 19 jeremybenn
@code{type=pattern} and a @code{pattern} value of 0, and implemented
1973
as such.
1974
 
1975
@quotation Note
1976
As a consequence, if the @code{pattern} field is @emph{subsequently}
1977
specified in this section, the value in that field will be used
1978
instead of zero to initialize the memory.
1979
@end quotation
1980
 
1981 418 julius
@item exitnops
1982
@cindex @code{type=exitnops} (memory configuration)
1983
Set the memory values to be an instruction used to signal end of
1984
simulation. This is useful for causing immediate end of simulation
1985
when PC corruption occurs.
1986
 
1987 19 jeremybenn
@end table
1988
 
1989
@item random_seed = @var{value}
1990
@cindex @code{random_seed} (memory configuration)
1991 82 jeremybenn
Set the seed for the random number generator to @var{value}.  This only
1992 19 jeremybenn
has any effect for memory type @code{random}.
1993
 
1994
The default value is -1,
1995
which means the seed will be set from a call to the @code{time}
1996
function, thus ensuring different random values are used on each
1997 82 jeremybenn
run.  The simulator prints out the seed used in this case, allowing
1998 19 jeremybenn
repeat runs to regenerate the same random values used in any
1999
particular run.
2000
 
2001
@item pattern = @var{value}
2002
@cindex @code{pattern} (memory configuration)
2003
Set the pattern to be used when initializing memory to
2004 82 jeremybenn
@var{value}.  The default value is 0.  This only has any effect for
2005
memory type @code{pattern}.  The least significant 8 bits of this value
2006
is used to initialize each byte.  More than 8 bits can be specified,
2007 19 jeremybenn
but will ignored with a warning.
2008
 
2009
@quotation Tip
2010
The default value, is equivalent to setting the memory @code{type} to
2011 82 jeremybenn
be @code{zero}.  If that is what is intended, then using
2012 19 jeremybenn
@code{type=zero} explicitly is better than using @code{type=pattern}
2013
and not specifying a value for @code{pattern}.
2014
@end quotation
2015
 
2016
@item baseaddr = @var{value}
2017
@cindex @code{baseaddr} (memory configuration)
2018 82 jeremybenn
Set the base address of the memory to @var{value}.  It should be
2019 19 jeremybenn
aligned to a multiple of the memory size rounded up to the nearest
2020 82 jeremybenn
@math{2^n}.  The default value is 0.
2021 19 jeremybenn
 
2022
@item size = @var{value}
2023
@cindex @code{size} (memory configuration)
2024 82 jeremybenn
Set the size of the memory block to be @var{value} bytes.  This should be a
2025
multiple of 4 (i.e.  word aligned).  The default value is 1024.
2026 19 jeremybenn
 
2027
@quotation Note
2028
When allocating memory, the simulator will allocate the nearest
2029
@math{2^n} bytes greater than or equal to @var{value}, and will not
2030
notice memory misses in any part of the memory between @var{value} and
2031
the amount allocated.
2032
 
2033
As a consequence users are strongly recommended to specify memory
2034 82 jeremybenn
sizes that are an exact power of 2.  If some other amount of memory is
2035 19 jeremybenn
required, it should be specified as separate, contiguous blocks, each
2036
of which is a power of 2 in size.
2037
@end quotation
2038
 
2039
@item name = "@var{text}"
2040
@cindex @code{name} (memory configuration)
2041 82 jeremybenn
Name the block.  Typically these describe the type of memory being
2042
modeled (thus @code{"SRAM"} or @code{"Flash"}.  The default is
2043 19 jeremybenn
@code{@w{"anonymous memory block"}}.
2044
 
2045
@quotation Note
2046
It is not clear that this information is currently ever used in normal
2047 82 jeremybenn
operation of the simulator.  Even the @command{info} command of the simulator
2048 19 jeremybenn
ignores it.
2049
@end quotation
2050
 
2051
@item ce = @var{value}
2052
@cindex @code{ce} (memory configuration)
2053 82 jeremybenn
Set the chip enable index of the memory instance.  Each memory instance
2054 19 jeremybenn
should have a unique chip enable index, which should be greater
2055 82 jeremybenn
than or equal to zero.  This is used by the memory controller when
2056 19 jeremybenn
identifying different memory instances.
2057
 
2058 346 jeremybenn
There is no requirement to set @code{ce} if a memory controller is not
2059
enabled.  The default value is -1 (invalid).
2060 19 jeremybenn
 
2061
@item mc = @var{value}
2062
@cindex @code{mc} (memory configuration)
2063 82 jeremybenn
Specifies the memory controller this memory is connected to.  It should
2064 19 jeremybenn
correspond to the @code{index} field specified in a @code{@w{section
2065
mc}} for a memory controller (@pxref{Memory Controller Configuration,
2066
, Memory Controller Configuration}).
2067
 
2068 346 jeremybenn
There is no requirement to set @code{mc} if a memory controller is not
2069
enabled.  Default value is 0, which is also the default value of a
2070
memory controller @code{index} field.  This is suitable therefore for
2071
designs with just one memory controller.
2072 19 jeremybenn
 
2073
@item delayr = @var{value}
2074
@cindex @code{delayr} (memory configuration)
2075 82 jeremybenn
The number of cycles required for a read access.  Set to -1 if the
2076
memory does not support reading.  Default value 1.  The simulator will
2077 19 jeremybenn
add this number of cycles to the total instruction cycle count when
2078
reading from main memory.
2079
 
2080
@item delayw = @var{value}
2081
@cindex @code{delayw} (memory configuration)
2082 82 jeremybenn
The number of cycles required for a write access.  Set to -1 if the
2083
memory does not support writing.  Default value 1.  The simulator will
2084 19 jeremybenn
add this number of cycles to the total instruction cycle count when
2085
writing to main memory.
2086
 
2087
@item log = "@var{file}"
2088
@cindex @code{log} (memory configuration)
2089
If specified, @file{file} names a file for all memory accesses to be
2090 82 jeremybenn
logged.  If not specified, the default value, NULL is used, meaning
2091 19 jeremybenn
that the memory is not logged.
2092
 
2093
@end table
2094
 
2095
@node Memory Management Configuration
2096
@subsection Memory Management Configuration
2097
@cindex configuring data & instruction MMUs
2098
@cindex MMU configuration
2099
@cindex DMMU configuration
2100
@cindex data MMU configuration
2101
@cindex IMMU configuration
2102
@cindex instruction MMU configuration
2103
@cindex @code{section dmmu}
2104
@cindex @code{section immu}
2105
Memory Management Unit (MMU) configuration is described in
2106
@code{section dmmu} (for the data MMU) and @code{section immu} (for
2107 82 jeremybenn
the instruction MMU).  Each section should appear at most once.  The
2108 19 jeremybenn
following parameters may be specified.
2109
 
2110
@table @code
2111
 
2112
@item enabled = 0|1
2113
@cindex @code{enabled} (MMU configuration)
2114
If 1 (true), the data or instruction (as appropriate) MMU is
2115 82 jeremybenn
enabled.  If 0 (the default), it is disabled.
2116 19 jeremybenn
 
2117
@item nsets = @var{value}
2118
@cindex @code{nsets} (MMU configuration)
2119
Sets the number of data or instruction (as appropriate) TLB sets to
2120 82 jeremybenn
@var{value}, which must be a power of two, not exceeding 128.  Values
2121
which do not fit these criteria are ignored with a warning.  The
2122
default value is 1.
2123 19 jeremybenn
 
2124
@item nways = @var{value}
2125
@cindex @code{nways} (MMU configuration)
2126
Sets the number of data or instruction (as appropriate) TLB ways to
2127 82 jeremybenn
@var{value}.  The value must be in the range 1 to 4.  Values outside
2128
this range are ignored with a warning.  The default value is 1.
2129 19 jeremybenn
 
2130
@item pagesize = @var{value}
2131
@cindex @code{pagesize} (MMU configuration)
2132
The data or instruction (as appropriate) MMU page size is set to
2133 82 jeremybenn
@var{value}, which must be a power of 2.  Values which are not a power
2134
of 2 are ignored with a warning.  The default is 8192 (0x2000).
2135 19 jeremybenn
 
2136
@item entrysize = @var{value}
2137
@cindex @code{entrysize} (MMU configuration)
2138
The data or instruction (as appropriate) MMU entry size is set to
2139 82 jeremybenn
@var{value}, which must be a power of 2.  Values which are not a power
2140
of 2 are ignored with a warning.  The default value is 1.
2141 19 jeremybenn
 
2142
@quotation Note
2143
@value{OR1KSIM} does not appear to use the @code{entrysize} parameter
2144 82 jeremybenn
in its simulation of the MMUs.  Thus setting this value does not seem
2145 19 jeremybenn
to matter.
2146
@end quotation
2147
 
2148
@item ustates = @var{value}
2149
@cindex @code{ustates} (MMU configuration)
2150
The number of instruction usage states for the data or instruction (as
2151
appropriate) MMU is set to @var{value}, which must be 2, 3 or
2152 82 jeremybenn
4.  Values outside this range are ignored with a warning.  The default
2153 19 jeremybenn
value is 2.
2154
 
2155
@quotation Note
2156
@value{OR1KSIM} does not appear to use the @code{ustates} parameter in
2157 82 jeremybenn
its simulation of the MMUs.  Thus setting this value does not seem to
2158 19 jeremybenn
matter.
2159
@end quotation
2160
 
2161
@item hitdelay = @var{value}
2162
@cindex @code{hitdelay} (MMU configuration)
2163
Set the number of cycles a data or instruction (as appropriate) MMU
2164 82 jeremybenn
hit costs.  Default value 1.
2165 19 jeremybenn
 
2166
@item missdelay = @var{value}
2167
@cindex @code{missdelay} (MMU configuration)
2168
Set the number of cycles a data or instruction (as appropriate) MMU
2169 82 jeremybenn
miss costs.  Default value 1.
2170 19 jeremybenn
 
2171
@end table
2172
 
2173
@node Cache Configuration
2174
@subsection Cache Configuration
2175
@cindex configuring data & instruction caches
2176
@cindex cache configuration
2177
@cindex data cache configuration
2178
@cindex instruction cache configuration
2179
@cindex @code{section dc}
2180
@cindex @code{section ic}
2181
Cache configuration is described in @code{section dc} (for the data
2182 82 jeremybenn
cache) and @code{seciton ic} (for the instruction cache).  Each section
2183
should appear at most once.  The following parameters may be specified.
2184 19 jeremybenn
 
2185
@table @code
2186
 
2187
@item enabled = 0|1
2188
@cindex @code{enabled} (cache configuration)
2189
If 1 (true), the data or instruction (as appropriate) cache is
2190 82 jeremybenn
enabled.  If 0 (the default), it is disabled.
2191 19 jeremybenn
 
2192
@item nsets = @var{value}
2193
@cindex @code{nsets} (cache configuration)
2194
Sets the number of data or instruction (as appropriate) cache sets to
2195
@var{value}, which must be a power of two, not exceeding
2196
@code{MAX_DC_SETS} (for the data cache) or @code{MAX_IC_SETS} (for the
2197 82 jeremybenn
instruction cache).  At the time of writing, these constants are
2198
both defined in the code to be 1024).  The default value is 1.
2199 19 jeremybenn
 
2200
@item nways = @var{value}
2201
@cindex @code{nways} (cache configuration)
2202
Sets the number of data or instruction (as appropriate) cache ways to
2203
@var{value}, which must be a power of two, not exceeding
2204
@code{MAX_DC_WAYS} (for the data cache) or @code{MAX_IC_WAYS} (for the
2205 82 jeremybenn
instruction cache).  At the time of writing, these constants are both
2206
defined in the code to be 32).  The default value is 1.
2207 19 jeremybenn
 
2208
@item blocksize = @var{value}
2209
@cindex @code{blocksize} (cache configuration)
2210
The data or instruction (as appropriate) cache block size is set to
2211 82 jeremybenn
@var{value} bytes, which must be either 16 or 32.  The default is 16.
2212 19 jeremybenn
 
2213
@item ustates = @var{value}
2214
@cindex @code{ustates} (cache configuration)
2215
The number of instruction usage states for the data or instruction (as
2216 82 jeremybenn
appropriate) cache is set to @var{value}, which must be 2, 3 or 4.  The
2217 19 jeremybenn
default value is 2.
2218
 
2219
@item hitdelay = @var{value}
2220
@cindex @code{hitdelay} (instruction cache configuration)
2221 82 jeremybenn
@emph{Instruction cache only}.  Set the number of cycles an instruction
2222
cache hit costs.  Default value 1.
2223 19 jeremybenn
 
2224
@item missdelay = @var{value}
2225
@cindex @code{missdelay} (instruction cache configuration)
2226 82 jeremybenn
@emph{Instruction cache only}.  Set the number of cycles an instruction
2227
cache miss costs.  Default value 1.
2228 19 jeremybenn
 
2229
@item load_hitdelay = @var{value}
2230
@cindex @code{load_hitdelay} (data cache configuration)
2231 82 jeremybenn
@emph{Data cache only}.  Set the number of cycles a data load cache hit
2232
costs.  Default value 2.
2233 19 jeremybenn
 
2234
@item load_missdelay = @var{value}
2235
@cindex @code{load_missdelay} (data cache configuration)
2236 82 jeremybenn
@emph{Data cache only}.  Set the number of cycles a data load cache
2237
miss costs.  Default value 2.
2238 19 jeremybenn
 
2239
@item store_hitdelay = @var{value}
2240
@cindex @code{store_hitdelay} (data cache configuration)
2241 82 jeremybenn
@emph{Data cache only}.  Set the number of cycles a data store cache hit
2242
costs.  Default value 0.
2243 19 jeremybenn
 
2244
@item store_missdelay = @var{value}
2245
@cindex @code{store_missdelay} (data cache configuration)
2246 82 jeremybenn
@emph{Data cache only}.  Set the number of cycles a data store cache
2247
miss costs.  Default value 0.
2248 19 jeremybenn
 
2249
@end table
2250
 
2251
@node Interrupt Configuration
2252
@subsection Interrupt Configuration
2253
@cindex configuring the interrupt controller
2254
@cindex interrupt controller configuration
2255
@cindex programmable interrupt controller configuration
2256
@cindex PIC configuration
2257
@cindex @code{section pic}
2258
Programmable Interrupt Controller (PIC) configuration is described in
2259 82 jeremybenn
@code{section pic}.  This section may appear at most
2260 19 jeremybenn
once---@value{OR1KSIM} has no mechanism for handling multiple
2261 82 jeremybenn
interrupt controllers.  The following parameters may be specified.
2262 19 jeremybenn
 
2263
@table @code
2264
 
2265
@item enabled = 0|1
2266
@cindex @code{enabled} (interrupt controller)
2267 82 jeremybenn
If 1 (true), the programmable interrupt controller is enabled.  If 0
2268 19 jeremybenn
(the default), it is disabled.
2269
 
2270
@item edge_trigger = 0|1
2271
@cindex @code{edge_trigger} (interrupt controller)
2272
If 1 (true, the default), the programmable interrupt controller is
2273 82 jeremybenn
edge triggered.  If 0 (false), it is level triggered.
2274 19 jeremybenn
 
2275 432 jeremybenn
The library interface (@pxref{Simulator Library, , Simulator Library})
2276
provides different functions for setting the different types of
2277
interrupt, and a function to clear level sensitive interrupts. Edge
2278
sensitive interrupts must be cleared by clearing the corresponding bit
2279
in the PICSR SPR.
2280 430 julius
 
2281 432 jeremybenn
Internal functions to set and clear interrupts are also provided for
2282 440 jeremybenn
peripherals implemented within @value{OR1KSIM}. @xref{Interrupts Internal, ,
2283 432 jeremybenn
Interrupts Internal} for more details.
2284 430 julius
 
2285 432 jeremybenn
@item use_nmi = 0|1
2286
@cindex @code{use_nmi} (interrupt controller)
2287
If 1 (true, the default), interrupt lines 0 and 1 are non-maskable. In
2288
other words the least significant 2 bits of the PICMR SPR are hard-wired
2289
to 1.  If 0 (false), all interrupt lines are treated as equivalent.
2290
 
2291
@quotation Note
2292
These are not non-maskable in the true sense that they will pre-empt
2293
other interrupts.  Rather they can never be masked out using the PICMR
2294
register. It is up the interrupt exception handler to give these
2295
interrupt lines priority, and indeed to decide on the priority order in
2296
general.
2297 430 julius
@end quotation
2298
 
2299 19 jeremybenn
@end table
2300
 
2301
@node Power Management Configuration
2302
@subsection Power Management Configuration
2303
@cindex configuring power management
2304
@cindex power management configuration
2305
@cindex PMU configuration
2306
@cindex @code{section pmu}
2307 82 jeremybenn
Power management implementation is incomplete.  At present the effect
2308 19 jeremybenn
(which only happens when the power management unit is enabled) of
2309
setting the different bits in the power management Special Purpose
2310
Register (PMR, SPR 0x4000) is
2311
 
2312
@table @code
2313
 
2314
@item SDF (bit mask 0x0000000f)
2315
@cindex SDF (power management register)
2316
@cindex slow down factor (power management register)
2317
@cindex power management register, SDF
2318
@cindex PMR - SDF
2319
No effect - these bits are ignored
2320
 
2321
@item DME (bit mask 0x00000010)
2322
@cindex DME (power management register)
2323
@cindex doze mode (power management register)
2324
@cindex power management register, DME
2325
@cindex PMR - DME
2326
@itemx SME (bit mask 0x00000020)
2327
@cindex SME (power management register)
2328
@cindex sleep mode (power management register)
2329
@cindex power management register, SME
2330
@cindex PMR - SME
2331
Both these bits cause the processor to stop executing
2332 82 jeremybenn
instructions.  However all other functions (debug interaction, CLI,
2333 19 jeremybenn
VAPI etc) carry on as normal.
2334
 
2335
@item DCGE (bit mask 0x00000004)
2336
@cindex DCGE (power management register)
2337
@cindex dynamic clock gating (power management register)
2338
@cindex power management register, DGCE
2339
@cindex PMR - DGCE
2340
No effect - this bit is ignored
2341
 
2342
@item SUME (bit mask 0x00000008)
2343
@cindex SUME (power management register)
2344
@cindex suspend mode (power management register)
2345
@cindex power management register, SUME
2346
@cindex PMR - SUME
2347
Enabling this bit causes a message to be printed, advising that the
2348
processor is suspending and the simulator exits.
2349
 
2350
@end table
2351
 
2352
On reset all bits are cleared.
2353
 
2354 82 jeremybenn
Power management configuration is described in @code{section pm}.  This
2355
section may appear at most once.  The following parameter may be specified.
2356 19 jeremybenn
 
2357
@table @code
2358
 
2359
@item enabled = 0|1
2360
@cindex @code{enabled} (power management configuration)
2361 82 jeremybenn
If 1 (true), power management is enabled.  If 0 (the default), it is
2362 19 jeremybenn
disabled.
2363
 
2364
@end table
2365
 
2366
@node Branch Prediction Configuration
2367
@subsection Branch Prediction Configuration
2368
@cindex configuring branch prediction
2369
@cindex branch prediction configuration
2370
@cindex BPB configuration
2371
@cindex @code{section bpb}
2372
From examining the code base, it seems the branch prediction function
2373 82 jeremybenn
is not fully implemented.  At present the functionality seems
2374 19 jeremybenn
restricted to collection of statistics.
2375
 
2376 82 jeremybenn
Branch prediction configuration is described in @code{section bpb}.  This
2377
section may appear at most once.  The following parameters may be specified.
2378 19 jeremybenn
 
2379
@table @code
2380
 
2381
@item enabled = 0|1
2382
@cindex @code{enabled} (branch prediction configuration)
2383 82 jeremybenn
If 1 (true), branch prediction is enabled.  If 0 (the default), it is
2384 19 jeremybenn
disabled.
2385
 
2386
@item btic = 0|1
2387
@cindex @code{btic} (branch prediction configuration)
2388 82 jeremybenn
If 1 (true), the branch target instruction cache model is enabled.  If
2389 19 jeremybenn
 
2390
 
2391
@item sbp_bf_fwd = 0|1
2392
@cindex @code{sbp_bf_fwd} (branch prediction configuration)
2393 82 jeremybenn
If 1 (true), use forward prediction for the @code{l.bf} instruction.  If
2394 19 jeremybenn
 
2395
 
2396
@item sbp_bnf_fwd = 0|1
2397
@cindex @code{sbp_bnf_fwd} (branch prediction configuration)
2398 82 jeremybenn
If 1 (true), use forward prediction for the @code{l.bnf} instruction.  If
2399 19 jeremybenn
 
2400
 
2401
@item hitdelay = @var{value}
2402
@cindex @code{hitdelay} (branch prediction configuration)
2403 82 jeremybenn
Set the number of cycles a branch prediction hit costs.  Default value
2404 19 jeremybenn
0.
2405
 
2406
@item missdelay = @var{value}
2407
@cindex @code{missdelay} (branch prediction configuration)
2408 82 jeremybenn
Set the number of cycles a branch prediction miss costs.  Default value
2409 19 jeremybenn
0.
2410
 
2411
@end table
2412
 
2413
@node Debug Interface Configuration
2414
@subsection Debug Interface Configuration
2415
@cindex configuring the debug unit and interface to external debuggers
2416
@cindex debug unit configuration
2417
@cindex debug interface configuration
2418
@cindex @code{section debug}
2419
The debug unit and debug interface configuration is described in
2420 82 jeremybenn
@code{@w{section debug}}.  This section may appear at most once.  The
2421 19 jeremybenn
following parameters may be specified.
2422
 
2423
@table @code
2424
 
2425
@item enabled = 0|1
2426
@cindex @code{enabled} (debug interface configuration)
2427 82 jeremybenn
If 1 (true), the debug unit is enabled.  If 0 (the default), it is disabled.
2428 19 jeremybenn
 
2429
@quotation Note
2430
This enables the functionality of the debug unit (its registers etc) within
2431 82 jeremybenn
the mode.  It does not provide any external interface to the debug unit.
2432
For
2433 235 jeremybenn
that, see @code{rsp_enabled} below.
2434 19 jeremybenn
@end quotation
2435
 
2436
@item rsp_enabled = 0|1
2437
@cindex @code{rsp_enabled} (debug interface configuration)
2438
@cindex Remote Serial Protocol
2439
If 1 (true), the GDB @dfn{Remote Serial Protocol} server is started, provding
2440
an interface to an external GNU debugger, using the port specified in the
2441
@code{rsp_port} field (see below), or the @code{or1ksim-rsp} TCP/IP
2442 82 jeremybenn
service.  If 0 (the default), the server is not started, and no external
2443 19 jeremybenn
interface is provided.
2444
 
2445
For more detailed information on the interface to the GNU Debugger see
2446
Embecosm Application Note 2, @cite{Howto: Porting the GNU Debugger Practical
2447
Experience with the OpenRISC 1000 Architecture}, by Jeremy Bennett, published
2448
by Embecosm Limited (@url{www.embecosm.com}).
2449
 
2450
@item rsp_port = @var{value}
2451
@cindex @code{rsp_port} (debug interface configuration)
2452
@var{value} specifies the port to be used for the GDB @dfn{Remote Serial
2453 82 jeremybenn
Protocol} interface to the GNU Debugger (GDB).  Default value 51000.  If
2454 19 jeremybenn
the value 0 is specified, @value{OR1KSIM} will instead look for a TCP/IP
2455
service named @code{or1ksim-rsp}.
2456
 
2457
@quotation Tip
2458
@cindex TCP/IP port range for @code{or1ksim-rsp} service
2459
There is no registered port for @value{OR1KSIM} @dfn{Remote Serial Protocol}
2460 82 jeremybenn
service @code{or1ksim-rsp}.  Good practice suggests users should adopt port
2461
values in the @dfn{Dynamic} or @dfn{Private} port range, i.e.  49152-65535.
2462 19 jeremybenn
@end quotation
2463
 
2464
@item vapi_id = @var{value}
2465
@cindex @code{vapi_id} (debug interface configuration)
2466
@var{value} specifies the value of the Verification API (VAPI) base
2467 82 jeremybenn
address to be used with the debug unit.  @xref{Verification API, ,
2468 19 jeremybenn
Verification API}, for more details.
2469
 
2470
If this is specified and @var{value} is non-zero, all OpenRISC Remote
2471
JTAG protocol transactions will be logged to the VAPI log file, if
2472 82 jeremybenn
enabled.  This is the only functionality associated with VAPI for the
2473
debug unit.  No VAPI commands are sent, nor requests handled.
2474 19 jeremybenn
 
2475
@end table
2476
 
2477
@node Peripheral Configuration
2478
@section Configuring Memory Mapped Peripherals
2479
 
2480 82 jeremybenn
All peripheral components are optional.  If they are specified, then
2481 19 jeremybenn
(unlike other components) by default they are enabled.
2482
 
2483
@menu
2484
* Memory Controller Configuration::
2485
* UART Configuration::
2486
* DMA Configuration::
2487
* Ethernet Configuration::
2488
* GPIO Configuration::
2489
* Display Interface Configuration::
2490
* Frame Buffer Configuration::
2491
* Keyboard Configuration::
2492
* Disc Interface Configuration::
2493
* Generic Peripheral Configuration::
2494
@end menu
2495
 
2496
@node Memory Controller Configuration
2497
@subsection Memory Controller Configuration
2498
@cindex configuring the memory controller
2499
@cindex memory controller configuration
2500
@cindex @code{section mc}
2501
The memory controller used in @value{OR1KSIM} is the component
2502 98 jeremybenn
implemented at OpenCores, and found in the top level SVN directory,
2503 82 jeremybenn
@file{mem_ctrl}.  It is described in the document @cite{Memory
2504 19 jeremybenn
Controller IP Core} by Rudolf Usselmann, which can be found in the
2505 82 jeremybenn
@file{doc} subdirectory.  It is a memory mapped component, which
2506 19 jeremybenn
resides on the main OpenRISC Wishbone data bus.
2507
 
2508
The memory controller configuration is described in @code{@w{section
2509 82 jeremybenn
mc}}.  This section may appear multiple times, specifying multiple
2510 98 jeremybenn
memory controllers.
2511 19 jeremybenn
 
2512 385 jeremybenn
@quotation Warning
2513
There are known to be problems with the current memory controller, which
2514
currently is not included in the regression test suite. Users are
2515
advised not to use the memory controller in the current release.
2516
@end quotation
2517
 
2518 98 jeremybenn
@quotation Caution
2519 385 jeremybenn
There is no initialization code in the standard @dfn{newlib}
2520
library.
2521 98 jeremybenn
 
2522 385 jeremybenn
The standard @dfn{uClibc} library assumes a memory controller
2523
mapped at 0x93000000 and will initialize the memory controller to expect
2524
64MB memory blocks, and any memory declarations @emph{must} reflect
2525
this.
2526
 
2527 98 jeremybenn
If smaller memory blocks are declared with a memory controller, then
2528
sufficient memory will not be allocated by @value{OR1KSIM}, but out of
2529 346 jeremybenn
range memory accesses will not be trapped.  For example declaring a
2530 98 jeremybenn
memory section from 0-4MB with a memory controller enabled would mean
2531
that accesses between 4MB and 64MB would be permitted, but having no
2532
allocated memory would likely cause a segmentation fault.
2533
 
2534
If the user is determined to use smaller memories with the memory
2535
controller, then custom initialization code must be provided, to
2536
ensure the memory controller traps out-of-memory accesses.
2537
@end quotation
2538
 
2539
The following parameters may be specified.
2540
 
2541 19 jeremybenn
@table @code
2542
 
2543
@item enabled = 0|1
2544
@cindex @code{enabled} (memory controller configuration)
2545 82 jeremybenn
If 1 (true, the default), this memory controller is enabled.  If 0, it is
2546 19 jeremybenn
disabled.
2547
 
2548
@quotation Note
2549
The memory controller can effectively also be disabled by setting an
2550 82 jeremybenn
appropriate power on control register value (see below).  However this
2551 19 jeremybenn
should only be used if it is desired to specifically model this
2552
behavior of the memory controller, not as a way of disabling the
2553
memory controller in general.
2554
@end quotation
2555
 
2556
@item baseaddr = @var{value}
2557
@cindex @code{baseaddr} (memory controller configuration)
2558
Set the base address of the memory controller's memory mapped
2559 82 jeremybenn
registers to @var{value}.  The default is 0, which is probably not a
2560 19 jeremybenn
sensible value.
2561
 
2562
The memory controller has a 7 bit address bus, with a total of 19
2563
32-bit registers, at addresses 0x00 through 0x4c (address 0x0c and
2564
addresses 0x50 through 0x7c are not used).
2565
 
2566
@item poc = @var{value}
2567
@cindex @code{poc} (memory controller configuration)
2568
Specifies the value of the power on control register, The least
2569
signficant two bits specify the bus width (use 0 for an 8-bit bus, 1
2570
for a 16-bit bus and 2 for a 32-bit bus) and the next two bits the
2571
type of memory connected (use 0 for a disabled interface, 1 for SSRAM,
2572
2 for asyncrhonous devices and 3 for synchronous devices).
2573
 
2574
If other bits are specified, they are ignored with a warning.
2575
 
2576
@quotation Caution
2577
The default value, 0, corresponds to a disabled 8-bit bus, and
2578
is likely not the most suitable value
2579
@end quotation
2580
 
2581
@item index = @var{value}
2582
@cindex @code{index} (memory controller configuration)
2583
Specify the index of this memory controller amongst all the memory
2584 82 jeremybenn
controllers.  This value should be unique for each memory controller,
2585 19 jeremybenn
and is used to associate specific memories with the controller,
2586
through the @code{mc} field in the @code{@w{section memory}}
2587
configuration (@pxref{Memory Configuration, , Memory Configuration}).
2588
 
2589
The default value, 0, is suitable when there is only one memory controller.
2590
 
2591
@end table
2592
 
2593
@node UART Configuration
2594
@subsection UART Configuration
2595
@cindex configuring the UART
2596
@cindex UART configuration
2597
@cindex @code{section uart}
2598
The UART implemented in @value{OR1KSIM} follows the specification of the
2599 82 jeremybenn
National Semiconductor 16450 and 16550 parts.  It is a memory mapped
2600 19 jeremybenn
component, which resides on the main OpenRISC Wishbone data bus.
2601
 
2602
The component provides a number of interfaces to emulate the behavior
2603
of an external terminal connected to the UART.
2604
 
2605 82 jeremybenn
UART configuration is described in @code{section uart}.  This section
2606
may appear multiple times, specifying multiple UARTs.  The following
2607 19 jeremybenn
parameters may be specified.
2608
 
2609
@table @code
2610
 
2611
@item enabled = 0|1
2612
@cindex @code{enabled} (UART configuration)
2613 82 jeremybenn
If 1 (true, the default), this UART is enabled.  If 0, it is disabled.
2614 19 jeremybenn
 
2615
@item baseaddr = @var{value}
2616
@cindex @code{baseaddr} (UART configuration)
2617
Set the base address of the UART's memory mapped
2618 82 jeremybenn
registers to @var{value}.  The default is 0, which is probably not a
2619 19 jeremybenn
sensible value.
2620
 
2621
The UART has a 3 bit address bus, with a total of 8 8-bit registers,
2622
at addresses 0x0 through 0x7.
2623
 
2624
@item channel = "@var{type}:@var{args}"
2625
@cindex @code{channel} (UART configuration)
2626
Specify the channel representing the terminal connected to the UART
2627
Rx & Tx pins.
2628
 
2629
@table @code
2630
 
2631
@item channel="file:@file{rxfile},@file{txfile}"
2632
@cindex UART I/O from/to files
2633
Read input characters from the file @file{rxfile} and write output
2634
characters to the file @file{txfile} (which will be created if
2635
required).
2636
 
2637
@item channel="xterm:@var{args}"
2638
@cindex UART I/O from/to an @command{xterm}
2639
Create an xterm on startup, write UART Tx traffic to the xterm and
2640
take Rx traffic from the keyboard when the xterm window is
2641 82 jeremybenn
selected.  Additional arguments to the xterm command (for example
2642 19 jeremybenn
specifying window size may be specified in @var{args}, or this may be
2643
left blank.
2644
 
2645
@item channel="tcp:@var{value}"
2646
@cindex UART I/O from/to TCP/IP
2647
Open the TCP/IP port specified by @var{value} and read and write UART
2648
traffic from and to it.
2649
 
2650
Typically a telnet session is connected to the other end of this port.
2651
 
2652
@quotation Tip
2653
There is no registered port for @value{OR1KSIM} telnet UART
2654 82 jeremybenn
connection.  Priviledged access is required to read traffic on the
2655
registered ``well-known'' telnet port (23).  Instead users should use
2656 19 jeremybenn
port values in the @dfn{Dynamic} or @dfn{Private} port range,
2657 82 jeremybenn
i.e.  49152-65535.
2658 19 jeremybenn
@end quotation
2659
 
2660
@item channel="fd:@code{rxfd},@code{txfd}"
2661
@cindex UART I/O from/to open file descriptors
2662
Read and write characters from and to the existing open numerical file
2663
descriptors, file @code{rxfd} and @code{txfd}.
2664
 
2665
@item channel="tty:device=/dev/ttyS0,baud=9600"
2666
@cindex UART I/O from/to a physical serial port
2667 82 jeremybenn
Read and write characters from and to a physical serial port.  The
2668 19 jeremybenn
precise device (shown here as @code{/dev/ttyS0}) may vary from machine
2669
to machine.
2670
 
2671
@end table
2672
 
2673
The default value for this field is @code{"xterm:"}.
2674
 
2675
@item irq = @var{value}
2676
@cindex @code{irq} (UART configuration)
2677 82 jeremybenn
Use @var{value} as the IRQ number of this UART.  Default value 0.
2678 19 jeremybenn
 
2679
@item 16550 = 0|1
2680
@cindex @code{16550} (UART configuration)
2681 82 jeremybenn
If 1 (true), the UART has the functionality of a 16550.  If 0 (the
2682
default), it has the functionality of a 16450.  The principal
2683 19 jeremybenn
difference is that the 16550 can buffer multiple characters.
2684
 
2685
@item jitter = @var{value}
2686
@cindex @code{jitter} (UART configuration)
2687
Set the jitter, modeled as a time to block, to @var{value}
2688 82 jeremybenn
milliseconds.  Set to -1 to disable jitter modeling.  Default value 0.
2689 19 jeremybenn
 
2690
@quotation Note
2691
This functionality has yet to be implemented, so this parameter has no
2692
effect.
2693
@end quotation
2694
 
2695
@item vapi_id = @var{value}
2696
@cindex @code{vapi_id} (UART configuration)
2697
@var{value} specifies the value of the Verification API (VAPI) base
2698 82 jeremybenn
address to be used with the UART.  @xref{Verification API, ,
2699 19 jeremybenn
Verification API}, for more details, which details the use of the VAPI
2700
with the UART.
2701
 
2702
@end table
2703
 
2704
@node DMA Configuration
2705
@subsection DMA Configuration
2706
@cindex configuring DMA
2707
@cindex DMA configuration
2708
@cindex @code{section dma}
2709
The DMA controller used in @value{OR1KSIM} is the component
2710 98 jeremybenn
implemented at OpenCores, and found in the top level SVN directory,
2711 82 jeremybenn
@file{wb_dma}.  It is described in the document @cite{Wishbone
2712 19 jeremybenn
DMA/Bridge IP Core} by Rudolf Usselmann, which can be found in the
2713 82 jeremybenn
@file{doc} subdirectory.  It is a memory mapped component, which
2714
resides on the main OpenRISC Wishbone data bus.  The present
2715 19 jeremybenn
implementation is incomplete, intended only to support the Ethernet
2716
interface (@pxref{Ethernet Configuration}), although the Ethernet
2717
interface is not yet completed.
2718
 
2719 82 jeremybenn
DMA configuration is described in @code{@w{section dma}}.  This section
2720
may appear multiple times, specifying multiple DMA controllers.  The
2721 19 jeremybenn
following parameters may be specified.
2722
 
2723
@table @code
2724
 
2725
@item enabled = 0|1
2726
@cindex @code{enabled} (DMA configuration)
2727 82 jeremybenn
If 1 (true, the default), this DMA controller is enabled.  If 0, it is disabled.
2728 19 jeremybenn
 
2729
@item baseaddr = @var{value}
2730
@cindex @code{baseaddr} (DMA configuration)
2731
Set the base address of the DMA's memory mapped
2732 82 jeremybenn
registers to @var{value}.  The default is 0, which is probably not a
2733 19 jeremybenn
sensible value.
2734
 
2735
The DMA controller has a 10 bit address bus, with a total of 253
2736 82 jeremybenn
32-bit registers.  The first 5 registers at addresses 0x000 through
2737
0x010 control the overall behavior of the DMA controller.  There are
2738 19 jeremybenn
then 31 blocks of 8 registers, controlling each of the 31 DMA channels
2739 82 jeremybenn
available.  Addresses 0x014 through 0x01c are not used.
2740 19 jeremybenn
 
2741
@item irq = @var{value}
2742
@cindex @code{irq} (DMA configuration)
2743 82 jeremybenn
Use @var{value} as the IRQ number of this DMA controller.  Default value 0.
2744 19 jeremybenn
 
2745
@item vapi_id = @var{value}
2746
@cindex @code{vapi_id} (DMA configuration)
2747
@var{value} specifies the value of the Verification API (VAPI) base
2748 82 jeremybenn
address to be used with the DMA controller.  @xref{Verification API, ,
2749 19 jeremybenn
Verification API}, for more details, which details the use of the VAPI
2750
with the DMA controller.
2751
 
2752
@end table
2753
 
2754
@node Ethernet Configuration
2755
@subsection Ethernet Configuration
2756
@cindex configuring the Ethernet interface
2757
@cindex Ethernet configuration
2758
@cindex @code{section ethernet}
2759 82 jeremybenn
Ethernet configuration is described in @code{section ethernet}.  This
2760 19 jeremybenn
section may appear multiple times, specifying multiple Ethernet
2761 82 jeremybenn
interfaces.  The following parameters may be specified.
2762 19 jeremybenn
 
2763 440 jeremybenn
The Ethernet MAC used in @value{OR1KSIM} corresponds to the Verilog
2764
implementation in project @dfn{ethmac}. It's source code can be found in
2765
the top level SVN directory, @file{ethmac}.  It also forms part of the
2766
OpenRISC reference SoC, ORPSoC.  It is described in the document
2767
@cite{Ethernet IP Core Specification} by Igor Mohor, which can be found
2768
in the @file{doc} subdirectory.  It is a memory mapped component, which
2769
resides on the main OpenRISC Wishbone data bus.
2770
 
2771 19 jeremybenn
@table @code
2772
 
2773
@item enabled = 0|1
2774
@cindex @code{enabled} (Ethernet configuration)
2775 82 jeremybenn
If 1 (true, the default), this Ethernet MAC is enabled.  If 0, it is
2776 19 jeremybenn
disabled.
2777
 
2778
@item baseaddr = @var{value}
2779
@cindex @code{baseaddr} (Ethernet configuration)
2780
Set the base address of the MAC's memory mapped registers to
2781 82 jeremybenn
@var{value}.  The default is 0, which is probably not a sensible value.
2782 19 jeremybenn
 
2783
The Ethernet MAC has a 7-bit address bus, with a total of 21
2784 82 jeremybenn
32-bit registers.  Addresses 0x54 through 0x7c are not used.
2785 19 jeremybenn
 
2786
@quotation Note
2787
The Ethernet specification describes a Tx control register,
2788 82 jeremybenn
@code{TXCTRL}, at address 0x50.  However this register is not
2789 19 jeremybenn
implemented in the @value{OR1KSIM} model.
2790
@end quotation
2791
 
2792
@item dma = @var{value}
2793
@cindex @code{dma} (Ethernet configuration)
2794
@var{value} specifies the DMA controller with which this Ethernet is
2795 82 jeremybenn
associated.  The default value is 0.
2796 19 jeremybenn
 
2797
@quotation Note
2798
Support for external DMA is not provided in the current
2799 82 jeremybenn
implementation, and this value is ignored.  In any case there is no
2800 19 jeremybenn
equivalent field to which this can be matched in the current DMA
2801
component implementation (@pxref{DMA Configuration, , DMA
2802
Configuration}).
2803
@end quotation
2804
 
2805
@item irq = @var{value}
2806
@cindex @code{dma} (Ethernet configuration)
2807 82 jeremybenn
Use @var{value} as the IRQ number of this Ethernet MAC.  Default value 0.
2808 19 jeremybenn
 
2809 440 jeremybenn
@item rtx_type = "file"|"tap"
2810 19 jeremybenn
@cindex @code{rtx_type} (Ethernet configuration)
2811 440 jeremybenn
Specifies whether to use a TUN/TAP interface or file interface (the default)
2812
to model the external connection of the Ethernet.
2813
 
2814
If a TUN/TAP interface is requested, Ethernet packets will be sent and
2815
received through the pesistent TAP interface specified in parameter
2816
@code{tap_dev} (see below).
2817
 
2818
More details on configuring the TUN/TAP interface are given in the Usage
2819
section (@pxref{Ethernet TUN/TAP Interface, , Ethernet TUN/TAP
2820
Interface}).
2821
 
2822
If a file interface (the default), is requested, the Ethernet will be
2823
modelled by reading and writing from and to the files specified in the
2824 19 jeremybenn
@code{rxfile} and @code{txfile} parameters (see below).
2825
 
2826 440 jeremybenn
@quotation Caution
2827
If a file interface is specified, @value{OR1KSIM} will terminate once the
2828
receive file specified by @code{rxfile} is exhausted.
2829 19 jeremybenn
@end quotation
2830
 
2831
@item rx_channel = @var{rxvalue}
2832
@cindex @code{rx_channel} (Ethernet configuration)
2833
@itemx tx_channel = @var{txvalue}
2834
@cindex @code{tx_channel} (Ethernet configuration)
2835
@var{rxvalue} specifies the DMA channel to use for receive and
2836 82 jeremybenn
@var{txvalue} the DMA channel to use for transmit.  Both default to 0.
2837 19 jeremybenn
 
2838
@quotation Note
2839
As noted above, support for external DMA is not provided in the
2840
current implementation, and so these values are ignored.
2841
@end quotation
2842
 
2843
@item rxfile = "@var{rxfile}"
2844
@cindex @code{rxfile} (Ethernet configuration)
2845
@itemx txfile = "@var{txfile}"
2846
@cindex @code{txfile} (Ethernet configuration)
2847
When @code{rtx_type} is 0 (see above), @var{rxfile} specifies the file
2848
to use as input and @var{txfile} specifies the fie to use as
2849
output.
2850
 
2851 82 jeremybenn
The file contains a sequence of packets.  Each packet consists of a
2852
packet length (32 bits), followed by that many bytes of data.  Once the
2853 19 jeremybenn
input file is empty, the Ethernet MAC behaves as though there were no
2854 82 jeremybenn
data on the Ethernet.  The default values of these parameters are
2855 19 jeremybenn
@code{"eth_rx"} and @code{"eth_tx"} respectively.
2856
 
2857 82 jeremybenn
The input file must exist and be readable.  The output file must be
2858
writable and will be created if necessary.  If either of these
2859 19 jeremybenn
conditions is not met, a warning will be given.
2860
 
2861 440 jeremybenn
@quotation Caution
2862
@value{OR1KSIM} will terminate once the @var{rxfile} is exhausted.
2863
@end quotation
2864 19 jeremybenn
 
2865 440 jeremybenn
@item tap_dev = "@var{tap}"
2866
@cindex @code{tap_dev} (Ethernet configuration)
2867
When @code{rtx_type} is @code{"tap"} (see above), @var{tap_dev}
2868
specifies the TAP device to use for communication.  This should be a
2869
persistent TAP device configured for the system (@pxref{Ethernet TUN/TAP
2870
Interface, , Ethernet TUN/TAP Interface})
2871
 
2872 451 jeremybenn
@item phy_addr = @var{value}
2873
@cindex @code{phy_addr}
2874
@var{value} specifies the address for emulated ethernet PHY (default
2875
0). If there are multiple Ethernet peripherals, they should each have a
2876
different PHY value.
2877
 
2878
@item dummy_crc = 0|1
2879
@cindex @code{dummy_crc} (Ethernet configuration)
2880
If 1 (true, the default), the length of the data transferred to the core
2881
will be increased by 4 bytes, as though the CRC were included.
2882
 
2883
@quotation Note
2884
This is for historical consistency with the OpenRISC Ethernet hardware
2885
MAC, which passes on the CRC in the data packet. This is unusual
2886
behavior for a MAC, but the OpenRISC Linux device drivers have been
2887
written to expect it.
2888
@end quotation
2889
 
2890
@item phy_addr = @var{value}
2891
@cindex @code{phy_addr}
2892
@var{value} specifies the address for emulated ethernet PHY (default
2893
0). If there are multiple Ethernet peripherals, they should each have a
2894
different PHY value.
2895
 
2896 19 jeremybenn
@item vapi_id = @var{value}
2897
@cindex @code{vapi_id} (DMA configuration)
2898
@var{value} specifies the value of the Verification API (VAPI) base
2899 82 jeremybenn
address to be used with the Ethernet PHY.  @xref{Verification API, ,
2900 19 jeremybenn
Verification API}, for more details, which details the use of the VAPI
2901
with the DMA controller.
2902
 
2903
@end table
2904
 
2905
@node GPIO Configuration
2906
@subsection GPIO Configuration
2907
@cindex configuring the GPIO
2908
@cindex GPIO configuration
2909
@cindex @code{section cpio}
2910
The GPIO used in @value{OR1KSIM} is the component implemented at
2911 98 jeremybenn
OpenCores, and found in the top level SVN directory, @file{gpio}.  It
2912 19 jeremybenn
is described in the document @cite{GPIO IP Core Specification} by
2913
Damjan Lampret and Goran Djakovic, which can be found in the
2914 82 jeremybenn
@file{doc} subdirectory.  It is a memory mapped component, which
2915 19 jeremybenn
resides on the main OpenRISC Wishbone data bus.
2916
 
2917 82 jeremybenn
GPIO configuration is described in @code{@w{section gpio}}.  This section
2918
may appear multiple times, specifying multiple GPIO devices.  The
2919 19 jeremybenn
following parameters may be specified.
2920
 
2921
@table @code
2922
 
2923
@item enabled = 0|1
2924
@cindex @code{enabled} (GPIO configuration)
2925 82 jeremybenn
If 1 (true, the default), this GPIO is enabled.  If 0, it is disabled.
2926 19 jeremybenn
 
2927
@item baseaddr = @var{value}
2928
@cindex @code{baseaddr} (GPIO configuration)
2929
Set the base address of the GPIO's memory mapped
2930 82 jeremybenn
registers to @var{value}.  The default is 0, which is probably not a
2931 19 jeremybenn
sensible value.
2932
 
2933
The GPIO has a 6 bit address bus, with a total of 10 32-bit registers,
2934 82 jeremybenn
although the number of bits that are actively used varies.  Addresses
2935 19 jeremybenn
0x28 through 0x3c are not used.
2936
 
2937
@item irq = @var{value}
2938
@cindex @code{irq} (GPIO configuration)
2939 82 jeremybenn
Use @var{value} as the IRQ number of this GPIO.  Default value 0.
2940 19 jeremybenn
 
2941
@item vapi_id = @var{value}
2942
@cindex @code{vapi_id} (GPIO configuration)
2943
@cindex @code{base_vapi_id} (GPIO configuration - deprecated)
2944
@var{value} specifies the value of the Verification API (VAPI) base
2945 82 jeremybenn
address to be used with the GPIO.  @xref{Verification API, ,
2946 19 jeremybenn
Verification API}, for more details, which details the use of the VAPI
2947 82 jeremybenn
with the GPIO controller.  For backwards compatibility, the
2948 19 jeremybenn
alternative name @code{base_vapi_id} is supported for this parameter,
2949
but deprecated.
2950
 
2951
@end table
2952
 
2953
@node Display Interface Configuration
2954
@subsection Display Interface Configuration
2955
@cindex configuring the VGA interface
2956
@cindex display interface configuration
2957
@cindex VGA configuration
2958
@cindex @code{section vga}
2959
@value{OR1KSIM} models a VGA interface to an external monitor.  The
2960
VGA controller used in @value{OR1KSIM} is the component implemented at
2961 98 jeremybenn
OpenCores, and found in the top level SVN directory, @file{vga_lcd},
2962 82 jeremybenn
with no support for the optional hardware cursors.  It is described in
2963 19 jeremybenn
the document @cite{VGA/LCD Core v2.0 Specifications} by Richard
2964 82 jeremybenn
Herveille, which can be found in the @file{doc} subdirectory.  It is a
2965 19 jeremybenn
memory mapped component, which resides on the main OpenRISC Wishbone
2966
data bus.
2967
 
2968
The current implementation provides only functionality to dump the
2969
screen to a file at intervals.
2970
 
2971
VGA controller configuration is described in @code{@w{section
2972 82 jeremybenn
vga}}.  This section may appear multiple times, specifying multiple
2973
VGA controllers.  The following parameters may be specified.
2974 19 jeremybenn
 
2975
@table @code
2976
 
2977
@item enabled = 0|1
2978
@cindex @code{enabled} (VGA configuration)
2979 82 jeremybenn
If 1 (true, the default), this VGA is enabled.  If 0, it is disabled.
2980 19 jeremybenn
 
2981
@item baseaddr = @var{value}
2982
@cindex @code{baseaddr} (VGA configuration)
2983
Set the base address of the VGA controller's memory mapped
2984 82 jeremybenn
registers to @var{value}.  The default is 0, which is probably not a
2985 19 jeremybenn
sensible value.
2986
 
2987
The VGA controller has a 12-bit address bus, with 7 32-bit registers, at
2988
addresses 0x000 through 0x018, and two color lookup tables at
2989 82 jeremybenn
addresses 0x800 through 0xfff.  The hardware cursor registers are not
2990 19 jeremybenn
implemented, so addresses 0x01c through 0x7fc are not used.
2991
 
2992
@item irq = @var{value}
2993
@cindex @code{irq} (VGA configuration)
2994 82 jeremybenn
Use @var{value} as the IRQ number of this VGA controller.  Default
2995 19 jeremybenn
value 0.
2996
 
2997
@item refresh_rate = @var{value}
2998
@cindex @code{refresh_rate} (VGA configuration)
2999 82 jeremybenn
@var{value} specifies number of cycles between screen dumps.  Default
3000 19 jeremybenn
value is derived from the simulation clock cycle time
3001
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond
3002
to dumping 50 times per simulated second.
3003
 
3004
@item txfile = "@var{file}"
3005
@cindex @code{txfile} (VGA configuration)
3006
@cindex @code{filename} (VGA configuration - deprecated)
3007
@var{file} specifies the base of the filename for screen
3008 82 jeremybenn
dumps.  Successive screen dumps will be in BMP format, in files with
3009 19 jeremybenn
the name @file{@var{file}@var{nnnn}.bmp}, where @var{nnnn} is a
3010 82 jeremybenn
sequential count of the screen dumps starting at zero.  The default
3011
value is @code{"vga_out"}.  For backwards compatibility, the
3012 19 jeremybenn
alternative name @code{filename} is supported for this parameter,
3013
but deprecated.
3014
 
3015
@end table
3016
 
3017
@node Frame Buffer Configuration
3018
@subsection Frame Buffer Configuration
3019
@cindex configuring the frame buffer
3020
@cindex frame buffer configuration
3021
@cindex @code{section fb}
3022
@quotation Caution
3023 82 jeremybenn
The frame buffer is only partially implemented.  Its configuration
3024 19 jeremybenn
fields are described here, but the component should not be used at
3025 82 jeremybenn
this time.  Like the VGA controller, it is designed to make screen
3026 19 jeremybenn
dumps to file.
3027
@end quotation
3028
 
3029 82 jeremybenn
Frame buffer configuration is described in @code{section fb}.  This
3030 19 jeremybenn
section may appear multiple times, specifying multiple frame
3031 82 jeremybenn
buffers.  The following parameters may be specified.
3032 19 jeremybenn
 
3033
@table @code
3034
 
3035
@item enabled = 0|1
3036
@cindex @code{enabled} (frame buffer configuration)
3037 82 jeremybenn
If 1 (true, the default), this frame buffer is enabled.  If 0, it is disabled.
3038 19 jeremybenn
 
3039
@item baseaddr = @var{value}
3040
@cindex @code{baseaddr} (frame buffer configuration)
3041
Set the base address of the frame buffer's memory mapped registers to
3042 82 jeremybenn
@var{value}.  The default is 0, which is probably not a sensible value.
3043 19 jeremybenn
 
3044
The frame buffer has an 121-bit address bus, with 4 32-bit registers,
3045
at addresses 0x000 through 0x00c, and a PAL lookup table at addresses
3046 82 jeremybenn
0x400 through 0x4ff.  Addresses 0x010 through 0x3fc and addresses 0x500
3047 19 jeremybenn
through 0x7ff are not used.
3048
 
3049
@item refresh_rate = @var{value}
3050
@cindex @code{refresh_rate} (frame buffer configuration)
3051 82 jeremybenn
@var{value} specifies number of cycles between screen dumps.  Default
3052 19 jeremybenn
value is derived from the simulation clock cycle time
3053
(@pxref{Simulator Behavior, , Simulator Behavior}), to correspond to
3054
dumping 50 times per simulated second.
3055
 
3056
@item txfile = "@var{file}"
3057
@cindex @code{txfile} (frame buffer configuration)
3058
@cindex @code{filename} (frame buffer configuration - deprecated)
3059
@var{file} specifies the base of the filename for screen
3060 82 jeremybenn
dumps.  Successive screen dumps will be in BMP format, in files with
3061 19 jeremybenn
the name @file{@var{file}@var{nnnn}.bmp}, where @var{nnnn} is a
3062 82 jeremybenn
sequential count of the screen dumps starting at zero.  The default
3063
value is @code{"fb_out"}.  For backwards compatibility, the
3064 19 jeremybenn
alternative name @code{filename} is supported for this parameter,
3065
but deprecated.
3066
 
3067
@end table
3068
 
3069
@node Keyboard Configuration
3070
@subsection Keyboard Configuration (PS2)
3071
@cindex configuring the keyboard interface
3072
@cindex configuring the PS2 interface
3073
@cindex keyboard configuration
3074
@cindex PS2 configuration
3075
@cindex @code{section kb}
3076 82 jeremybenn
The PS2 interface provided by @value{OR1KSIM} is not documented.  It
3077 19 jeremybenn
may be based on the PS2 project at OpenCores, and found in
3078 98 jeremybenn
the top level SVN directory, @file{ps2}.  However this project lacks
3079 82 jeremybenn
any documentation beyond its project webpage.  Since most PS2
3080 19 jeremybenn
interfaces follow the Intel i8042 standard, this is presumably what is
3081
expected with this device.
3082
 
3083
The implementation only provides for keyboard support, which is
3084 82 jeremybenn
modelled as a file of keystrokes.  There is no mouse support.
3085 19 jeremybenn
 
3086
@quotation Caution
3087
A standard i8042 device has two registers at addresses 0x60 (command)
3088 82 jeremybenn
and 0x64 (status).  Inspection of the code, suggests that the
3089 19 jeremybenn
@value{OR1KSIM} component places these registers at addresses 0x00 and
3090
0x04.
3091
 
3092
The port of Linux for the OpenRISC 1000, which runs on @value{OR1KSIM}
3093
implements the i8042 device driver, anticipating these registers
3094 82 jeremybenn
reside at their conventional address.  It seems unlikel that this code
3095 19 jeremybenn
will work.
3096
 
3097
This component should be used with caution.
3098
@end quotation
3099
 
3100 82 jeremybenn
Keyboard configuration is described in @code{section kbd}.  This
3101 19 jeremybenn
section may appear multiple times, specifying multiple keyboard
3102 82 jeremybenn
interfaces.  The following parameters may be specified.
3103 19 jeremybenn
 
3104
@table @code
3105
 
3106
@item enabled = 0|1
3107
@cindex @code{enabled} (keyboard configuration)
3108 82 jeremybenn
If 1 (true, the default), this keyboard is enabled.  If 0, it is disabled.
3109 19 jeremybenn
 
3110
@item baseaddr = @var{value}
3111
@cindex @code{baseaddr} (keyboard configuration)
3112
Set the base address of the keyboard's memory mapped registers to
3113 82 jeremybenn
@var{value}.  The default is 0, which is probably not a sensible value.
3114 19 jeremybenn
 
3115
The keyboard PS/2 interface has an 3-bit address bus, with 2 8-bit registers,
3116
at addresses 0x000 and 0x004.
3117
 
3118
@quotation Caution
3119
As noted above, a standard Intel 8042 interface would expect to find
3120
these registers at locations 0x60 and 0x64, thus requiring at least a
3121
7-bit bus.
3122
@end quotation
3123
 
3124
@item irq = @var{value}
3125
@cindex @code{irq} (keyboard configuration)
3126 82 jeremybenn
Use @var{value} as the IRQ number of this Keyboard interface.  Default
3127 19 jeremybenn
value 0.
3128
 
3129
@item rxfile = "@var{file}"
3130
@cindex @code{file} (keyboard configuration)
3131
@file{file} specifies a file containing raw key stroke data, which
3132 82 jeremybenn
models the input from a physical keyboard.  The default value is
3133 19 jeremybenn
@code{"kbd_in"}.
3134
 
3135
@end table
3136
 
3137
@node Disc Interface Configuration
3138
@subsection Disc Interface Configuration
3139
@cindex configuring the ATA/ATAPI interfaces
3140
@cindex disc interface configuration
3141
@cindex ATA/ATAPI configuration
3142
@cindex @code{section ata}
3143
The ATA/ATAPI disc controller used in @value{OR1KSIM} is the OCIDEC
3144
(OpenCores IDE Controller) component implemented at OpenCores, and
3145 98 jeremybenn
found in the top level SVN directory, @file{ata}.  It is described in
3146 19 jeremybenn
the document @cite{ATA/ATAPI-5 Core Specification} by Richard
3147 82 jeremybenn
Herveille, which can be found in the @file{doc} subdirectory.  It is a
3148 19 jeremybenn
memory mapped component, which resides on the main OpenRISC Wishbone
3149
data bus.
3150
 
3151 385 jeremybenn
@quotation Warning
3152 440 jeremybenn
In the current release of @value{OR1KSIM}, parsing of the ATA section is
3153 385 jeremybenn
broken. Users should not configure the disc interface in this release.
3154
@end quotation
3155
 
3156 82 jeremybenn
ATA/ATAPI configuration is described in @code{@w{section ata}}.  This section
3157
may appear multiple times, specifying multiple disc controllers.  The
3158 19 jeremybenn
following parameters may be specified.
3159
 
3160
@table @code
3161
 
3162
@item enabled = 0|1
3163
@cindex @code{enabled} (ATA/ATAPI configuration)
3164 82 jeremybenn
If 1 (true, the default), this ATA/ATAPI interface is enabled.  If 0,
3165 19 jeremybenn
it is disabled.
3166
 
3167
@item baseaddr = @var{value}
3168
@cindex @code{baseaddr} (ATA/ATAPI configuration)
3169
Set the base address of the ATA/ATAPI interface's memory mapped
3170 82 jeremybenn
registers to @var{value}.  The default is 0, which is probably not a
3171 19 jeremybenn
sensible value.
3172
 
3173
The ATA/ATAPI PS/2 interface has an 5-bit address bus, with 8 32-bit
3174 82 jeremybenn
registers.  Depending on the version of the OCIDEC ATA/ATAPI interface
3175 19 jeremybenn
selected (see @code{dev_id} below), not all registers will be available.
3176
 
3177
@item irq = @var{value}
3178
@cindex @code{irq} (ATA/ATAPI configuration)
3179 82 jeremybenn
Use @var{value} as the IRQ number of this ATA/ATAPI interface.  Default
3180 19 jeremybenn
value 0.
3181
 
3182
@item dev_id = 1|2|3
3183
@cindex @code{dev_id} (ATA/ATAPI configuration)
3184
This parameter specifies which version of the OCIDEC ATA/ATAPI
3185 82 jeremybenn
interface to model.  The default value is 1.
3186 19 jeremybenn
 
3187
Version 1 supports only the @code{CTRL}, @code{STAT} and @code{PCTR}
3188 82 jeremybenn
registers.  Versions 2 & 3 add the @code{FCTR} registers, Version 3
3189 19 jeremybenn
adds the @code{DTR} registers and the @code{RXD}/@code{TXD} registers.
3190
 
3191
@item rev = @var{value}
3192
@cindex @code{rev} (ATA/ATAPI configuration)
3193
Set the @var{value} as the revision of the OCIDEC ATA/ATAPI
3194 82 jeremybenn
interface.  The default value is 1.  The default value is 0.  Its value
3195
should be in the range 0-15.  Larger values are truncated with a
3196
warning.  This only affects the reset value of the @code{STAT}
3197 19 jeremybenn
register, where it forms bits 24-27.
3198
 
3199
@item pio_mode0_t1 = @var{value}
3200
@cindex @code{pio_mode0_t1} (ATA/ATAPI configuration)
3201
@itemx pio_mode0_t2 = @var{value}
3202
@cindex @code{pio_mode0_t2} (ATA/ATAPI configuration)
3203
@itemx pio_mode0_t4 = @var{value}
3204
@cindex @code{pio_mode0_t4} (ATA/ATAPI configuration)
3205
@itemx pio_mode0_teoc = @var{value}
3206
@cindex @code{pio_mode0_teoc} (ATA/ATAPI configuration)
3207
These parameters specify the timings for use with Programmed
3208 82 jeremybenn
Input/Output (PIO) transfers.  They are specified as the number of
3209 19 jeremybenn
clock cycles - 2, rounded up to the next highest integer, or zero if
3210 82 jeremybenn
that would be negative.  The values should not exceed 255.  If they do,
3211 19 jeremybenn
they will be ignored with a warning.
3212
 
3213
See the ATA/ATAPI-5 specification for explanations of each of these
3214 82 jeremybenn
timing parameters.  The default values are:
3215 19 jeremybenn
 
3216
@example
3217
pio_mode0_t1   =  6
3218
pio_mode0_t2   = 28
3219
pio_mode0_t4   =  2
3220
pio_mode0_teoc = 23
3221
@end example
3222
 
3223
@item dma_mode0_tm = @var{value}
3224
@cindex @code{dma_mode0_tm} (ATA/ATAPI configuration)
3225
@itemx dma_mode0_td = @var{value}
3226
@cindex @code{dma_mode0_td} (ATA/ATAPI configuration)
3227
@itemx dma_mode0_teoc = @var{value}
3228
@cindex @code{dma_mode0_teoc} (ATA/ATAPI configuration)
3229 82 jeremybenn
These parameters specify the timings for use with DMA transfers.  They
3230 19 jeremybenn
are specified as the number of clock cycles - 2, rounded up to the
3231 82 jeremybenn
next highest integer, or zero if that would be negative.  The values
3232
should not exceed 255.  If they do, they will be ignored with a
3233 19 jeremybenn
warning.
3234
 
3235
See the ATA/ATAPI-5 specification for explanations of each of these
3236 82 jeremybenn
timing parameters.  The default values are:
3237 19 jeremybenn
 
3238
@example
3239
dma_mode0_tm   =  4
3240
dma_mode0_td   = 21
3241
dma_mode0_teoc = 21
3242
@end example
3243
 
3244
@end table
3245
 
3246
@subsubsection ATA/ATAPI Device Configuration
3247
@cindex disc interface device configuration
3248
@cindex ATA/ATAPI device configuration
3249
Within the @code{@w{section ata}}, each device is specified
3250 82 jeremybenn
separately.  The device subsection is introduced by
3251 19 jeremybenn
 
3252
@example
3253
device @var{value}
3254
@end example
3255
 
3256 82 jeremybenn
@var{value} is the device number, which should be 0 or 1.  The
3257
subsection ends with @code{enddevice}.  Note that if the same device
3258 19 jeremybenn
number is specified more than once, the previous values will be
3259 82 jeremybenn
overwritten.  Within the @code{device} subsection, the following
3260 19 jeremybenn
parameters may appear:
3261
 
3262
@table @code
3263
 
3264
@item type = @var{value}
3265
@cindex @code{type} (ATA/ATAPI device configuration)
3266
@var{value}specifies the type of device: 0 (the default) for ``not
3267
connected'', 1 for hard disk simulated in a file and 2 for local system
3268
hard disk.
3269
 
3270
@item file = "@var{filename}"
3271
@cindex @code{file} (ATA/ATAPI device configuration)
3272
@file{filename} specifies the file to be used for a simulated ATA
3273 82 jeremybenn
device if the file type (see @code{type} above) is 1.  Default value
3274 346 jeremybenn
@code{"ata_file@var{n}"}, where @var{n} is the device number.
3275 19 jeremybenn
 
3276
@item size = @var{value}
3277
@cindex @code{size} (ATA/ATAPI device configuration)
3278
@var{value} specifies the size of a simulated ATA device if the file
3279 82 jeremybenn
type (see @code{type} above) is 1.  The default value is zero.
3280 19 jeremybenn
 
3281
@item packet = 0|1
3282
@cindex @code{packet} (ATA/ATAPI device configuration)
3283 82 jeremybenn
If 1 (true), implement the PACKET command feature set.  If 0 (the
3284 19 jeremybenn
default), do not implement the PACKET command feature set.
3285
 
3286
@item firmware = "@var{str}"
3287
@cindex @code{firmware} (ATA/ATAPI device configuration)
3288
Firmware to report in response to the ``Identify Device''
3289 82 jeremybenn
command.  Default @code{"02207031"}.
3290 19 jeremybenn
 
3291
@item heads = @var{value}
3292
@cindex @code{heads} (ATA/ATAPI device configuration)
3293 82 jeremybenn
Number of heads in the device.  Default 7, use -1 to disable all heads.
3294 19 jeremybenn
 
3295
@item sectors = @var{value}
3296
@cindex @code{sectors} (ATA/ATAPI device configuration)
3297 82 jeremybenn
Number of sectors per track in the device.  Default 32.
3298 19 jeremybenn
 
3299
@item mwdma = 0|1|2|-1
3300
@cindex @code{mwdma} (ATA/ATAPI device configuration)
3301 82 jeremybenn
Highest multi-word DMA mode supported.  Default 2, use -1 to disable.
3302 19 jeremybenn
 
3303
@item pio = 0|1|2|3|4
3304
@cindex @code{pio} (ATA/ATAPI device configuration)
3305 82 jeremybenn
Highest PIO mode supported.  Default 4.
3306 19 jeremybenn
 
3307
@end table
3308
 
3309
@node Generic Peripheral Configuration
3310
@subsection Generic Peripheral Configuration
3311
@cindex generic peripheral configuration
3312
@cindex configuration of generic peripherals
3313
@cindex @code{section generic}
3314
When used as a library (@pxref{Simulator Library, , Simulator
3315
Library}), @value{OR1KSIM} makes provision for any additional peripheral to be
3316 82 jeremybenn
implemented externally.  Any read or write access to this peripheral's
3317
memory map generates @dfn{upcall}s to an external handler.  This
3318 19 jeremybenn
interface can support either C or C++, and was particularly designed
3319
to facilitate support for OSCI SystemC (see @url{http://www.systemc.org}).
3320
 
3321
Generic peripheral configuration is described in @code{@w{section
3322 82 jeremybenn
generic}}.  This section may appear multiple times, specifying multiple
3323
external peripherals.  The following parameters may be specified.
3324 19 jeremybenn
 
3325
@table @code
3326
 
3327
@item enabled = 0|1
3328
@cindex @code{enabled} (generic peripheral configuration)
3329 82 jeremybenn
If 1 (true, the default), this ATA/ATAPI interface is enabled.  If 0,
3330 19 jeremybenn
it is disabled.
3331
 
3332
@item baseaddr = @var{value}
3333
@cindex @code{baseaddr} (generic peripheral configuration)
3334
Set the base address of the generic peripheral's memory mapped
3335 82 jeremybenn
registers to @var{value}.  The default is 0, which is probably not a
3336 19 jeremybenn
sensible value.
3337
 
3338
The size of the memory mapped register space is controlled by the
3339
@code{size} paramter, described below.
3340
 
3341
@item size = @var{value}
3342
@cindex @code{size} (generic peripheral configuration)
3343
Set the size of the generic peripheral's memory mapped register space
3344 82 jeremybenn
to @var{value} bytes.  Any read or write accesses to addresses with
3345 19 jeremybenn
offsets of 0 to @var{value}-1 bytes from the base address specified in
3346
parameter @code{baseaddr} (see above) will be directed to the external
3347
interface.
3348
 
3349 82 jeremybenn
@var{value} will be rounded up the nearest power of 2.  It's default
3350
value is zero.  If @var{value} is not an exact power of two, accesses
3351 19 jeremybenn
to address offsets of @var{value} or above up to the next power of 2
3352
will generate a warning, and have no effect (reads will return zero).
3353
 
3354
@item name = "@var{str}"
3355
@cindex @code{name} (generic peripheral configuration)
3356 82 jeremybenn
This gives the peripheral the name @code{"@var{str}"}.  This is used to
3357 19 jeremybenn
identify the peripheral in error messages and warnings, and when
3358 82 jeremybenn
reporting its status.  The default value is @code{@w{"anonymous
3359 19 jeremybenn
external peripheral"}}.
3360
 
3361
@item byte_enabled = 0|1
3362
@cindex @code{byte_enabled} (generic peripheral configuration)
3363
@itemx hw_enabled = 0|1
3364
@cindex @code{hw_enabled} (generic peripheral configuration)
3365
@itemx word_enabled = 0|1
3366
@cindex @code{word_enabled} (generic peripheral configuration)
3367
If 1 (true, the default), these parameters respectively enable the
3368 82 jeremybenn
device for byte wide, half-word wide and word wide accesses.  If 0,
3369 19 jeremybenn
accesses of that width will fail.
3370
 
3371
@end table
3372
 
3373
@node Interactive Command Line
3374
@chapter Interactive Command Line
3375
 
3376
If started with the @code{-f} flag, or if interrupted with
3377
@kbd{ctrl-C}, @value{OR1KSIM} provides the user with an interactive
3378 82 jeremybenn
command line.  The commands available, which may not be abbreviated, are:
3379 19 jeremybenn
 
3380
@table @code
3381
 
3382
@item q
3383
@cindex @code{q} (Interactive CLI)
3384
@cindex quitting (Interactive CLI)
3385
Exit the simulator
3386
 
3387
@item r
3388
@cindex @code{r} (Interactive CLI)
3389
@cindex displaying registers (Interactive CLI)
3390
@cindex register display (Interactive CLI)
3391 82 jeremybenn
Display all the General Purpose Registers (GPRs).  Also shows the just
3392 19 jeremybenn
executed and next to be executed instructions symbolically and the
3393
state of the flag in the Supervision Register.
3394
 
3395
@item t
3396
@cindex @code{t} (Interactive CLI)
3397
@cindex stepping code (Interactive CLI)
3398
Execute the next instruction and then display register/instruction
3399
information as with the @code{r} command (see above).
3400
 
3401
@item run @var{num} [ hush ]
3402
@cindex @code{run} (Interactive CLI)
3403
@cindex running code (Interactive CLI)
3404
@cindex executing code (Interactive CLI)
3405 82 jeremybenn
Execute @var{num} instructions.  The register/instruction information
3406 19 jeremybenn
is displayed after each instruction, as with the @code{r} command (see
3407
above) @emph{unless} @code{hush} is specified.
3408
 
3409
@item pr @var{reg} @var{value}
3410
@cindex @code{pr} (Interactive CLI)
3411
@cindex patching registers (Interactive CLI)
3412
@cindex register patching (Interactive CLI)
3413
Patch register @var{reg} with @var{value}.
3414
 
3415
@item dm @var{fromaddr} [ @var{toaddr} ]
3416
@cindex @code{dm} (Interactive CLI)
3417
@cindex displaying memory (Interactive CLI)
3418
@cindex memory display (Interactive CLI)
3419 82 jeremybenn
Display memory bytes between @var{fromaddr} and @var{toaddr}.  If
3420 19 jeremybenn
@var{toaddr} is not given, 64 bytes are displayed, starting at
3421
@var{fromaddr}.
3422
 
3423
@quotation Caution
3424 82 jeremybenn
The output from this command is broken (a bug).  @value{OR1KSIM}
3425
attempts to print out 16 bytes per row.  However, instead of printing
3426 19 jeremybenn
out the address at the start of each row, it prints the address (of
3427
the first of the 16 bytes) before @emph{each} byte.
3428
@end quotation
3429
 
3430
@item de @var{fromaddr} [ @var{toaddr} ]
3431
@cindex @code{dm} (Interactive CLI)
3432
@cindex disassemble (Interactive CLI)
3433 82 jeremybenn
Disassemble code between @var{fromaddr} and @var{toaddr}.  If
3434 19 jeremybenn
@var{toaddr} is not given, 16 instructions are disassembled.
3435
 
3436
The disassembly is entirely numerical, and gives no symbolic
3437
information.
3438
 
3439
@item pm @var{addr} @var{value}
3440
@cindex @code{pm} (Interactive CLI)
3441
@cindex patching memory (Interactive CLI)
3442
@cindex memory patching (Interactive CLI)
3443
Patch the 4 bytes in memory starting at @var{addr} with the 32-bit
3444
@var{value}.
3445
 
3446
@item pc @var{value}
3447
@cindex @code{pc} (Interactive CLI)
3448
@cindex patching the program counter (Interactive CLI)
3449
@cindex program counter patching (Interactive CLI)
3450
Patch the program counter with @var{value}.
3451
 
3452
@item cm @var{fromaddr} @var{toaddr} @var{size}
3453
@cindex @code{cm} (Interactive CLI)
3454
@cindex copying memory (Interactive CLI)
3455
@cindex memory copying (Interactive CLI)
3456
Copy @var{size} bytes in memory from @var{fromaddr} to @var{toaddr}.
3457
 
3458
@item break @var{addr}
3459
@cindex @code{break} (Interactive CLI)
3460
@cindex breakpoint set/clear (Interactive CLI)
3461
@cindex set breakpoint (Interactive CLI)
3462
@cindex clear breakpoint (Interactive CLI)
3463
@cindex toggle breakpoint (Interactive CLI)
3464
Toggle the breakpoint set at @var{addr}.
3465
 
3466
@item breaks
3467
@cindex @code{breaks} (Interactive CLI)
3468
@cindex breakpoint list (Interactive CLI)
3469
@cindex list breakpoints (Interactive CLI)
3470
List all set breakpoints
3471
 
3472
@item reset
3473
@cindex @code{reset} (Interactive CLI)
3474
@cindex simulator reset (Interactive CLI)
3475
@cindex reset the simulator (Interactive CLI)
3476 82 jeremybenn
Reset the simulator.  Includes modeling a reset of the processor, so
3477 19 jeremybenn
execution will restart from the reset vector location, 0x100.
3478
 
3479
@item hist
3480
@cindex @code{hist} (Interactive CLI)
3481
@cindex execution history (Interactive CLI)
3482
@cindex history of execution (Interactive CLI)
3483
If saving the execution history has been configured (@pxref{Simulator
3484
Behavior, , Simulator Behavior}), display the execution history.
3485
 
3486
@item stall
3487
@cindex @code{stall} (Interactive CLI)
3488
@cindex processor stall (Interactive CLI)
3489
@cindex stall the processor (Interactive CLI)
3490 82 jeremybenn
Stall the processor, so that control is passed to the debug unit.  When
3491
stalled, the processor can execute no instructions.  This command is
3492 19 jeremybenn
useful when debugging the JTAG interface, used by debuggers such as
3493
GDB.
3494
 
3495
@item unstall
3496
@cindex @code{unstall} (Interactive CLI)
3497
@cindex processor unstall (Interactive CLI)
3498
@cindex unstall the processor (Interactive CLI)
3499 82 jeremybenn
Unstall the processor, so that normal execution can continue.  This command is
3500 19 jeremybenn
useful when debugging the JTAG interface, used by debuggers such as GDB.
3501
 
3502
@item stats @var{category} | clear
3503
@cindex @code{stats} (Interactive CLI)
3504
@cindex simulator statistics (Interactive CLI)
3505
@cindex statistics, simulation (Interactive CLI)
3506
Print the statistics for the given @var{category}, if available, or
3507 82 jeremybenn
clear if @code{clear} is specified.  The categories are:
3508 19 jeremybenn
 
3509
@table @asis
3510
 
3511
@item 1
3512
Miscellaneous statistics: branch predictions (if branch predictions
3513
are enabled), branch target cache model (if enabled), cache (if
3514
enbaled), MMU (if enabled) and number of addtional load & store
3515
cycles.
3516
 
3517
@xref{Core OpenRISC Configuration, , Configuring the OpenRisc
3518
Achitectural Components}, for details of how to enable these various
3519
features.
3520
 
3521
@item 2
3522 82 jeremybenn
Instruction usage statistics.  Requires hazard analysis to be enabled
3523 19 jeremybenn
(@pxref{CPU Configuration, ,CPU Configuration}).
3524
 
3525
@item 3
3526 82 jeremybenn
Instruction dependency statistics.  Requires hazard analysis to be enabled
3527 19 jeremybenn
(@pxref{CPU Configuration, ,CPU Configuration}).
3528
 
3529
@item 4
3530 82 jeremybenn
Functional unit dependency statistics.  Requires hazard analysis to be enabled
3531 19 jeremybenn
(@pxref{CPU Configuration, ,CPU Configuration}).
3532
 
3533
@item 5
3534 82 jeremybenn
Raw register usage over time.  Requires hazard analysis to be enabled
3535 19 jeremybenn
(@pxref{CPU Configuration, ,CPU Configuration}).
3536
 
3537
@item 6
3538 82 jeremybenn
Store buffer statistics.  Requires the store buffer to be enabled
3539 19 jeremybenn
(@pxref{CPU Configuration, ,CPU Configuration}).
3540
 
3541
@end table
3542
 
3543
@item info
3544
@cindex @code{info} (Interactive CLI)
3545
@cindex simulator configuration info (Interactive CLI)
3546
@cindex configuration info (Interactive CLI)
3547 82 jeremybenn
Display detailed information about the simulator configuration.  This
3548 19 jeremybenn
is quite a lengthy about, because all MMU TLB information is displayed.
3549
 
3550
@item dv @var{fromaddr} [ @var{toaddr} ] [ @var{module} ]
3551
@cindex @code{dv} (Interactive CLI)
3552
@cindex Verilog memory dump (Interactive CLI)
3553
@cindex memory dump, Verilog (Interactive CLI)
3554
Dump the area of memory between @var{fromaddr} and @var{toaddr} as
3555
Verilog code for a synchronous, 23-bit wide SRAM module, named
3556 82 jeremybenn
@var{module}.  If @var{toaddr} is not specified, then 64 bytes are
3557
dumped (as 16 32-bit words).  If @var{module} is not specified,
3558 19 jeremybenn
@code{or1k_mem} is used.
3559
 
3560
To save to a file, use the redirection function (described after this
3561
table, below).
3562
 
3563
@item dh @var{fromaddr} [ @var{toaddr} ]
3564
@cindex @code{dv} (Interactive CLI)
3565
@cindex hexadecimal memory dump (Interactive CLI)
3566
@cindex memory dump, hexadecimal (Interactive CLI)
3567
Dump the area of memory between @var{fromaddr} and @var{toaddr} as
3568 82 jeremybenn
32-bit hex numbers (no @code{0x}, or @code{32'h} prefix).  If
3569 19 jeremybenn
@var{toaddr} is not specified, then 64 bytes are dumped (as 16 32-bit
3570
words).
3571
 
3572
To save to a file, use the redirection function (described after this
3573
table, below).
3574
 
3575
@item setdbch
3576
@cindex @code{setdbch} (Interactive CLI)
3577
@cindex debug channel toggle (Interactive CLI)
3578
@cindex toggle debug channels (Interactive CLI)
3579 82 jeremybenn
Toggle debug channels on/off.  @xref{Standalone Simulator, , Standalone
3580 19 jeremybenn
Simulator}, for a description of specifying debug channels on the
3581
command line.
3582
 
3583
@item set @var{section} @var{param} = @var{value}
3584
@cindex @code{set} (Interactive CLI)
3585
@cindex configuration parameter setting (Interactive CLI)
3586
Set the configuration parameter @var{para} in section @var{section} to
3587 82 jeremybenn
@var{value}.  @xref{Configuration, , Configuration}, for details of
3588 19 jeremybenn
configuration parameters and their settings.
3589
 
3590
@item debug
3591
@cindex @code{debug} (Interactive CLI)
3592
@cindex debug mode toggle (Interactive CLI)
3593
@cindex toggle debug mode (Interactive CLI)
3594 82 jeremybenn
Toggle the simulator debug mode.  @xref{Debug Interface Configuration,
3595 19 jeremybenn
, Debug Interface Configuration}, for information on this parameter.
3596
 
3597
@quotation Caution
3598 82 jeremybenn
This is effectively enabling or disabling the debug unit.  It does not
3599
effect the remote GDB debug interface.  However using the remote debug
3600 19 jeremybenn
interface while the debug unit is disabled will lead to undefined
3601
behavior and likely crash @value{OR1KSIM}
3602
@end quotation
3603
 
3604
@item cuc
3605
@cindex @code{debug} (Interactive CLI)
3606
@cindex Custom Unit Compiler (Interactive CLI)
3607
Enter the the Custom Unit Compiler command prompt (@pxref{CUC
3608
Configuration, , CUC Configuration}).
3609
 
3610
@quotation Caution
3611 82 jeremybenn
The CUC must be properly configured, for this to succeed.  In
3612
particular a timing file must be available and readable.  Otherwise
3613 19 jeremybenn
@value{OR1KSIM} will crash.
3614
@end quotation
3615
 
3616
@item help
3617
@cindex @code{help} (Interactive CLI)
3618
@cindex Custom Unit Compiler (Interactive CLI)
3619
Print out brief information about each command available.
3620
 
3621
@item mprofile [-vh] [-m @var{m}] [-g @var{n}] [-f @var{file}] @var{from} @var{to}
3622
@cindex @code{mprofile} (Interactive CLI)
3623
@cindex memory profiling utility (Interactive CLI)
3624 82 jeremybenn
Run the memory profiling utility.  This follows the same usage as the
3625 19 jeremybenn
standalone command (@pxref{Memory Profiling Utility, , Memory
3626
Profiling Utility}).
3627
 
3628
@item profile [-vhcq] [-g @var{file}]
3629
@cindex @code{mprofile} (Interactive CLI)
3630
@cindex profiling utility (Interactive CLI)
3631
@cindex instruction profiling utility (Interactive CLI)
3632 82 jeremybenn
Run the instruction profiling utility.  This follows the same usage as the
3633 19 jeremybenn
standalone command (@pxref{Profiling Utility, , Profiling Utility}).
3634
 
3635
@end table
3636
 
3637
For all commands, it is possible to redirect the output to a file, by
3638
using the redirection operator, @code{>}.
3639
 
3640
@example
3641
@var{command} > @var{filename}
3642
@end example
3643
 
3644
This is particularly useful for commands dumping a large amount of
3645
output, such as @code{dv}.
3646
 
3647
@quotation Caution
3648 82 jeremybenn
Unfortunately there is a serious bug with the redirection operator.  It
3649 19 jeremybenn
does not return output to standard output after the command
3650 82 jeremybenn
completes.  Until this bug is fixed, file redirection should not be
3651 19 jeremybenn
used.
3652
@end quotation
3653
 
3654
@node Verification API
3655
@chapter Verification API (VAPI)
3656
 
3657
The Verification API (VAPI) provides a TCP/IP interface to allow
3658 82 jeremybenn
components of the simulation to be controlled externally.  The
3659 19 jeremybenn
interface is polled for new requests on each simulated clock
3660 82 jeremybenn
cycle.  Components within the simulator may send responses to such
3661 19 jeremybenn
requests.
3662
 
3663 82 jeremybenn
The inteface is an asynchronous duplex protocol.  On the request side
3664 19 jeremybenn
it provides for simple commands, known as VAPI IDs (a 32 bit integer),
3665 82 jeremybenn
with a single piece of data (also a 32 bit integer).  On the send side,
3666
it provides for sending a single VAPI ID and data.  However there is no
3667
explicit command-response structure.  Some components just accept
3668
requests (e.g.  to set values), some just generate sends (to report
3669 19 jeremybenn
values), and some do both.
3670
 
3671
Each component has a base ID (32 bit) and its commands will start from
3672 82 jeremybenn
that base ID.  This provides a simple partitioning of the command space
3673
amongst components.  Request commands will be directed to the component with
3674 19 jeremybenn
the closest base ID lower than the VAPI ID of the command.
3675
 
3676
Thus if there are two components with base IDs of 0x200 and 0x300, and
3677
a request with VAPI ID of 0x203 is received, it will be directed to
3678
the first component as its command #3.
3679
 
3680
The results of VAPI interactions are logged (by default in
3681
@file{vapi.log} unless an alternative is specified in @code{@w{section
3682
vapi}}).
3683
 
3684
Currently the following components support VAPI:
3685
 
3686
@table @asis
3687
 
3688
@item Debug Unit
3689
@cindex Debug Unit verification (VAPI)
3690
@cindex VAPI for Debug Unit
3691
Although the Debug Unit can specify a base VAPI ID, it is not used to
3692
send commands or receive requests.
3693
 
3694
Instead, if the base VAPI ID is set, all remote JTAG protocol exchanges are
3695
logged in the VAPI log file.
3696
 
3697
@item UART
3698
@cindex UART verification (VAPI)
3699
@cindex VAPI for UART
3700
If a base VAPI ID is specified, the UART sends details of any chars or
3701
break characters sent, with dteails of the line control register etc
3702
encoded in the data packet sent.
3703
 
3704
This supports a single VAPI command request, but encodes a sub-command in the
3705
top 8 bits of the associated data.
3706
 
3707
@table @code
3708
 
3709
@item 0x00
3710
@cindex 0x00 UART VAPI sub-command (UART verification)
3711
This stuffs the least significant 8 bits of the data into the serial
3712
register of the UART and the next 8 bits into the line control
3713
register, effectively providing control of the next character to be
3714
sent or received.
3715
 
3716
@item 0x01
3717
@cindex 0x01 UART VAPI sub-command (UART verification)
3718
The divisor latch bytes are set from the least significant 16 bits of
3719
the data.
3720
 
3721
@item 0x02
3722
@cindex 0x02 UART VAPI sub-command (UART verification)
3723
The line control register is set from bits 15-8 of the data.
3724
 
3725
@item 0x03
3726
@cindex 0x03 UART VAPI sub-command (UART verification)
3727
The UART skew is set from the least significant 16 bits of the data
3728
 
3729
@item 0x04
3730
@cindex 0x04 UART VAPI sub-command (UART verification)
3731
If the 16th most significant bit of the data is 1, start sending
3732 82 jeremybenn
breaks, otherwise stop sending breaks.  The breaks are sent or cleared
3733 19 jeremybenn
after the number of UART clock divider ticks specified by the data
3734
(immediately if the data is zero).
3735
 
3736
@end table
3737
 
3738
@item DMA
3739
@cindex DMA verification (VAPI)
3740
@cindex VAPI for DMA
3741
Although the DMA unit supports a base VAPI ID in its configuration
3742
(@code{@w{section dma}}), no VAPI data is sent, nor VAPI requests
3743
currently implemented.
3744
 
3745
@item Ethernet
3746
@cindex Ethernet verification (VAPI)
3747
@cindex VAPI for Ethernet
3748 82 jeremybenn
The following requests are handled by the Ethernet.  Specified
3749 19 jeremybenn
symbolically, these are the increments from the base VAPI ID of the
3750 82 jeremybenn
Ethernet.  At present no implementation is provided behind these VAPI
3751 19 jeremybenn
requests.
3752
 
3753
@table @code
3754
 
3755
@item ETH_VAPI_DATA (0)
3756
@cindex @code{ETH_VAPI_DATA} (Ethernet verification)
3757
 
3758
@item ETH_VAPI_CTRL (0)
3759
@cindex @code{ETH_VAPI_CTRL} (Ethernet verification)
3760
 
3761
@end table
3762
 
3763
@item GPIO
3764
@cindex GPIO verification (VAPI)
3765
@cindex VAPI for GPIO
3766
If a base VAPI ID is specified, the GPIO sends out on its base VAPI ID
3767
(symbolically, GPIO_VAPI_DATA (0) offset from the base VAPI ID) any
3768
changes in outputs.
3769
 
3770 82 jeremybenn
The following requests are handled by the GPIO.  Specified
3771 19 jeremybenn
symbolically, these are the increments from the VAPI base ID of the
3772
GPIO.
3773
 
3774
@table @code
3775
 
3776
@item GPIO_VAPI_DATA (0)
3777
@cindex @code{GPIO_VAPI_DATA} (GPIO verification)
3778
Set the next input to the commands data field
3779
 
3780
@item GPIO_VAPI_AUX (1)
3781
@cindex @code{GPIO_VAPI_AUX} (GPIO verification)
3782
Set the GPIO auxiliary inputs to the data field
3783
 
3784
@item GPIO_VAPI_CLOCK (2)
3785
@cindex @code{GPIO_VAPI_CLOCK} (GPIO verification)
3786
Add an external GPIO clock trigger of period specified in the data field.
3787
 
3788
@item GPIO_VAPI_RGPIO_OE (3)
3789
@cindex @code{GPIO_VAPI_RGPIO} (GPIO verification)
3790
Set the GPIO output enable to the data field
3791
 
3792
@item GPIO_VAPI_RGPIO_INTE (4)
3793
@cindex @code{GPIO_VAPI_INTE} (GPIO verification)
3794
Set the next interrupt to the data field
3795
 
3796
@item GPIO_VAPI_RGPIO_PTRIG (5)
3797
@cindex @code{GPIO_VAPI_PTRIG} (GPIO verification)
3798
Set the next trigger to the data field
3799
 
3800
@item GPIO_VAPI_RGPIO_AUX (6)
3801
@cindex @code{GPIO_VAPI_AUX} (GPIO verification)
3802
Set the next auxiliary input to the data field
3803
 
3804
@item GPIO_VAPI_RGPIO_CTRL (7)
3805
@cindex @code{GPIO_VAPI_CTRL} (GPIO verification)
3806
Set th next control input to the data field
3807
 
3808
@end table
3809
 
3810
@end table
3811
 
3812
@node Code Internals
3813
@chapter A Guide to @value{OR1KSIM} Internals
3814
 
3815 82 jeremybenn
These are notes to help those wanting to extend @value{OR1KSIM}.  This
3816 19 jeremybenn
section assumes the use of a tag file, so file locations of entities'
3817 82 jeremybenn
definitions are not in general provided.  For more on tags, see the
3818
Linux manual page for @command{etags}.  A tag file can be created
3819 19 jeremybenn
with:
3820
 
3821
@example
3822
make tags
3823
@end example
3824
 
3825
@menu
3826
* Coding Conventions::
3827
* Global Data Structures::
3828
* Concepts::
3829
* Internal Debugging::
3830 104 jeremybenn
* Regression Testing::
3831 19 jeremybenn
@end menu
3832
 
3833
@node Coding Conventions
3834
@section Coding Conventions for @value{OR1KSIM}
3835
 
3836
This chapter provides some guidelines for coding, to facilitate
3837
extensions to @value{OR1KSIM}
3838
 
3839
@table @emph
3840
 
3841
@item GNU Coding Standard
3842
Code should follow the GNU coding standard for C
3843 82 jeremybenn
(@url{http://www.gnu.org/prep/standards/}.  If in doubt, put your code
3844 19 jeremybenn
through the @command{indent} program.
3845
 
3846
@item @code{#include} headers
3847
All C source code files should include @file{config.h} before any
3848
other file.
3849
 
3850
This should be followed by inclusion of any system headers (but see
3851
the comments about portability and @file{port.h} below) and then by
3852
any @value{OR1KSIM} package headers.
3853
 
3854
If @file{port.h} is required, it should be the first package header to
3855
be included after the system headers.
3856
 
3857
All C source code and header files should directly include any system
3858 82 jeremybenn
or package header they depend on, i.e.  not rely on any other header
3859
having already included it.  The two exceptions are
3860 19 jeremybenn
 
3861
@enumerate
3862
@item
3863
All header files may assume that @file{config.h} has already been
3864
included.
3865
 
3866
@item
3867
System headers which impose portability problems should be included by
3868
using the package header @file{port.h}, rather than the system headers
3869 82 jeremybenn
themselves.  This is the case for code requiring
3870 19 jeremybenn
 
3871
@itemize @bullet
3872
 
3873
@item
3874
@code{strndup} (from @file{string.h})
3875
 
3876
@item
3877
Integer types (@code{int@var{n}_t}, @code{uint@var{n}_t}) (from
3878
@file{inttypes.h}).
3879
 
3880
@item
3881
@code{isblank} (from @file{ctype.h})
3882
 
3883
@end itemize
3884
 
3885
@end enumerate
3886
 
3887
@item @code{#include} files once only
3888
All include files should be protected by @code{#ifndef} to ensure
3889 82 jeremybenn
their definitions are only included once.  For instance a header file
3890 19 jeremybenn
@file{@var{x-y.h}} should surround its contents with:
3891
 
3892
@example
3893
#ifndef X_Y__H
3894
#define X_Y__H
3895
 
3896
<body of the include file>
3897
 
3898
#endif  /* X_Y__H */
3899
@end example
3900
 
3901
@item Avoid @code{typedef}
3902
The GNU coding style for C does not have a clear way to distinguish
3903 82 jeremybenn
between user type name and user variables.  For this reason
3904 19 jeremybenn
@code{typedef} should be avoided except for the most ubiquitous user
3905 82 jeremybenn
defined types.  This makes the code much easier to read.
3906 19 jeremybenn
 
3907
There are some @code{typedef} declarations in the @command{argtable2}
3908
library and the @acronym{ELF} and @acronym{COFF} headers, because this
3909
code is taken from other places.
3910
 
3911
Within @value{OR1KSIM} legacy uses of @code{typedef} have largely been
3912
purged, except in the Custom Unit Compiler (@pxref{CUC Configuration,
3913
, Custom Unit Compiler (CUC) Configuration}).
3914
 
3915
The remaining uses of @code{typedef} occur in two places:
3916
 
3917
@itemize @bullet
3918
 
3919
@item
3920
@file{port/port.h} defines types to replace those in header files that
3921
are not available (character functions, string duplication, integer
3922
types).
3923
 
3924
@file{cpu/or1k/arch.h} defines types for the key @value{OR1KSIM}
3925
entities: addresses (@code{oraddr_t}), unsigned register values
3926
(@code{uorreg_t}) and signed register (@code{orreg_t}) values.
3927
 
3928
@end itemize
3929
 
3930
Where new types are defined, they should appear in one of these two
3931 82 jeremybenn
files as appropriate.  @value{OR1KSIM} specific types appearing in
3932 19 jeremybenn
@file{arch.h} should always have the suffix @file{_h}.
3933
 
3934
@item Don't begin names with underscore
3935
Names beginning with @code{_} are intended to be part of the C
3936 82 jeremybenn
infrastructure.  They should not be used in the simulator code.
3937 19 jeremybenn
 
3938
@item Keep Non-global top level entities static
3939
All top level entities (functions, variables), which are not
3940 82 jeremybenn
explicitly part of a global interface should be declared static.  This
3941 19 jeremybenn
ensures that unwanted connections are not inadvertently built across
3942
the program.
3943
 
3944
@item Use of @code{inline}
3945 82 jeremybenn
Code should not be declared @code{inline}.  Modern compilers can work
3946 19 jeremybenn
out for themselves what is best in this respect.
3947
 
3948
@item Initialization
3949 82 jeremybenn
All data structures should be explicitly initialized.  In particular
3950 19 jeremybenn
code should not rely on static data structures being initialized to
3951
zero.
3952
 
3953
The rationale is that in future static data structures may become
3954 82 jeremybenn
dynamic.  This has been a particular source of bugs in @value{OR1KSIM}
3955 19 jeremybenn
historically.
3956
 
3957
A specific case is with new peripherals, which should always include a
3958
@code{start} function to pre-initialize all configuration parameters
3959
to sensible defaults
3960
 
3961
@item Configuration Validation
3962
All configuration values should be validated, preferably when
3963
encountered, if not when the @code{section} is closed, or otherwise
3964
at run time when the parameter is first used.
3965
 
3966
@end table
3967
 
3968
@node Global Data Structures
3969
@section Global Data Structures
3970
 
3971
@table @code
3972
 
3973
@item config
3974
@cindex configuration global structure
3975
@vindex config
3976
The global variable @code{config} of type @code{struct config} holds
3977
the configuration data for some of the @value{OR1KSIM} components which
3978 82 jeremybenn
are always present.  At present the components are:
3979 19 jeremybenn
 
3980
@itemize @bullet
3981
 
3982
@item
3983
@vindex config.sim
3984
The simulator defined in @code{@w{section sim}} (@pxref{Simulator
3985
Configuration, , Simulator Configuration}).
3986
 
3987
@item
3988
@vindex config.vapi
3989
The Verification API (VAPI) defined  in @code{@w{section vapi}}
3990
(@pxref{Verification API Configuration, , Verification API (VAPI)
3991
Configuration}).
3992
 
3993
@item
3994
@vindex config.cuc
3995
The Custom Unit Compiler (CUC), defined in @code{@w{section cuc}}
3996
(@pxref{CUC Configuration, , Custom Unit Compiler (CUC)
3997
Configuration}).
3998
 
3999
@item
4000
@vindex config.cpu
4001
The CPU, defined in @code{@w{section cpu}} (@pxref{CPU Configuration,
4002
, CPU Configuration}).
4003
 
4004
@item
4005
@vindex config.dc
4006
The data cache (but not the instruction cache), defined in
4007
@code{@w{section dc}} (@pxref{Cache Configuration, , Cache
4008
Configuration}).
4009
 
4010
@item
4011
@vindex config.pm
4012
The power management unit, defined in @code{@w{section pm}}
4013
(@pxref{Power Management Configuration, , Power Management
4014
Configuration}).
4015
 
4016
@item
4017
@vindex config.pic
4018
The programmable interrupt controller, defined in @code{@w{section pic}}
4019
(@pxref{Interrupt Configuration, , Interrupt Configuration}).
4020
 
4021
@item
4022
@vindex config.bpb
4023
Branch prediciton, defined in @code{@w{section bpb}} (@pxref{Branch
4024
Prediction Configuration, , Branch Prediction Configuration}).
4025
 
4026
@item
4027
@vindex config.debug
4028
The debug unit, defined in @code{@w{section debug}} (@pxref{Debug
4029
Interface Configuration, , Debug Interface Configuration}).
4030
 
4031
@end itemize
4032
 
4033
This struct is made of a collection of structs, one for each
4034 82 jeremybenn
component.  For example the simulator configuration is held in
4035 19 jeremybenn
@code{config.sim}.
4036
 
4037
@item config
4038
@cindex configuration dynamic structure
4039
@vindex sections
4040
This is a linked list of data structures holding configuration data
4041
for all sections which are not held in the main @code{config} data
4042 82 jeremybenn
structure.  In general these are components (such as peripherals and
4043
memory) which may occur multiple times.  However it also handles some
4044 19 jeremybenn
architectural components which may occur only once, such as the memory
4045
management units, the instruction cache, the interrupt controller and
4046
branch prediction.
4047
 
4048
@item runtime
4049
@cindex runtime global structure
4050
@vindex runtime
4051
The global variable @code{runtime} of type @code{struct runtime} holds
4052 82 jeremybenn
all the runtime information about the simulation.  To access this
4053 19 jeremybenn
variable, @file{sim-config.h} must be included.
4054
 
4055
@vindex runtime.cpu
4056
@vindex runtime.vapi
4057
@vindex runtime.cuc
4058
This struct is itself made of 3 other structs, @code{cpu} (for CPU run
4059
time state), @code{vapi} (for Verification API state) and @code{cuc}
4060
(for Custom Unit Compiler state).
4061
 
4062
@end table
4063
 
4064
@node Concepts
4065
@section Concepts
4066
 
4067
@table @emph
4068
 
4069
@anchor{Output Redirection}
4070
@item Output Redirection
4071
@cindex output rediretion
4072
@vindex runtime.cpu.fout
4073 82 jeremybenn
The current output stream is held in @code{runtime.cpu.fout}.  Output
4074 19 jeremybenn
should be explicitly written to this stream, or may use the
4075
@code{PRINTF} macro, which will write its arguments to this output stream.
4076
 
4077
@item Reset Hooks
4078
@cindex reset hooks
4079
@findex reg_sim_reset
4080
Any peripheral may register a routine to be called when the the
4081
processor is reset by calling @code{reg_sim_reset}, providing a
4082 82 jeremybenn
function and pointer to a data structure as arguments.  On reset that
4083 19 jeremybenn
function will be called with the data stucture pointer as argument.
4084
 
4085 432 jeremybenn
@anchor{Interrupts Internal}
4086
@item Interrupts
4087
@cindex interrupts
4088
@findex report_interrupt
4089
@findex clear_interrupt
4090
@findex mtspr
4091
An internal peripheral can model the effect of an interrupt being
4092
asserted by calling @code{report_interrupt}.  This is used for both edge
4093
and level sensitive interrupts.
4094
 
4095
The effect is to set the corresponding bit in the PICSR SPR and to queue
4096
an interrupt exception to take place after the current instruction
4097
completes execution.
4098
 
4099
Externally, the different interrupts require different mechanisms for
4100
clearing.  Level sensitive interrupts should be cleared by deasserting
4101
the interrupt line, edge sensitive interrupts by clearing the
4102
corresponding bit in the PICSR SPR.
4103
 
4104
Internally this amounts to the same thing (clearing the PICSPR bit), so
4105
a single function is provided, @code{clear_interrupt}.  Note however that
4106
when level sensitive interrupts are configured, PICSR is read only, and
4107
can only be cleared by calling @code{clear_interrupt}.  Using the two
4108
functions provided will ensure the peripheral works correctly whichever
4109
type of interrupt is used.
4110
 
4111
@quotation Note
4112
Until an interrupt is cleared, all subsequent interrupts are ignored
4113
with a warning.
4114
@end quotation
4115
 
4116 19 jeremybenn
@end table
4117
 
4118
@node Internal Debugging
4119
@section Internal Debugging
4120
@cindex internal debugging
4121
 
4122
The function @code{debug} is like @code{printf}, but with an extra
4123 82 jeremybenn
first argument, which is the debug level.  If the debug level specified
4124 19 jeremybenn
in the simulator configuration (@pxref{Simulator Behavior, , Simulator
4125
Behavior}) is greater than or equal to this value, the remaining
4126
arguments are printed to the current output stream (@pxref{Output
4127
Redirection, , Output Redirection}).
4128
 
4129 104 jeremybenn
@node Regression Testing
4130
@section Regression Testing
4131
@cindex regression testing
4132
@cindex testing
4133
@value{OR1KSIM} now includes a regression test suite for both standalone
4134
and library usage as described earlier (@pxref{Build and Install,
4135
, Building and Installing}).  Running the tests requires that the
4136
OpenRISC toolchain and DejaGNU are both installed.
4137
 
4138
Tests are written using @command{expect}, a derivative of TCL.
4139
Documentation of DejaGnu, @command{expect} and TCL are freely available
4140
on the Web.  The Embecosm Application Note 8, @cite{Howto: Using DejaGnu
4141
for Testing: A Simple Introduction}
4142
(@uref{http://www.embecosm.com/download/ean8.html}) provides a concise
4143
introduction.
4144
 
4145
All test code is found in the @file{testsuite} directory.  The key
4146
files and directories used are as follows.
4147
 
4148
@table @code
4149
@item global-conf.exp
4150
@cindex DejaGnu configuration
4151
This is the global DejaGNU configuration file used to set up parameters
4152
common to all tests.  If the user has the environment varialbe
4153
@env{DEJAGNU} defined, it will be used instead, but this is not
4154
recommended.
4155
 
4156
@item Makefile.am
4157
@cindex test make file
4158
@cindex make file for tests
4159
This is the top level @command{automake} file for the testsuite.  The
4160
only changes likely to be needed here is additional local cleanup of
4161
files created by new tests.
4162
 
4163
@item README
4164
@cindex test README
4165
This contains details of all the tests
4166
 
4167
@item config
4168
@cindex DejaGnu board configurations
4169
This contains DejaGnu board configurations.  Since the tests are
4170
generally run on a Unix host, this should just contain @file{Unix.exp}.
4171
 
4172
@item lib
4173
@cindex DejaGnu tool specific configuration
4174
This contains DejaGnu tool specific configurations.  ``Tool'' has a
4175
specific meaning in DejaGNU, referring just to a grouping of tests.  In
4176
this case there are two such ``tools'', ``or1ksim'' and ``libsim''
4177
for tests of the standalone tool and tests of the library.
4178
 
4179
Corresponding to this, there are two tool specific configuration files,
4180
@file{or1ksim.exp} and @file{libsim.exp}.  These contain @command{expect}/TCL
4181
procedures for common use among the tests.
4182
 
4183
@item libsim.tests
4184
@itemx or1ksim.tests
4185
@cindex DejaGNU tests directories
4186 440 jeremybenn
These are the directories of tests of the @value{OR1KSIM} library.  They
4187
also include @value{OR1KSIM} configuration files and each has a
4188
@file{Makefile.am} file.  @file{Makefile.am} should be updated whenever
4189
files are added to this directory, to ensure they are included in the
4190
distribution.
4191 104 jeremybenn
 
4192
@item test-code
4193
@cindex host test code
4194
@cindex test code for host
4195
These are all the test programs to be compiled on the host (each in its
4196
own directory).  In general these are programs to support testing of the
4197
library, and build various programs linking in the library.
4198
 
4199
@item test-code
4200
@cindex target test code
4201
@cindex test code for target
4202
These are all the test programs to be compiled with the OpenRISC tool
4203 346 jeremybenn
chain to run with either standalone @value{OR1KSIM} or the library.
4204
This directory includes its own @file{configure.ac}, since it must set
4205
up a separate tool chain based on the target, not the host.
4206 104 jeremybenn
 
4207
@end table
4208
 
4209
To add a new test needs the following steps.
4210
 
4211
@itemize @bullet
4212
 
4213
@item
4214 346 jeremybenn
Put new host C code in its own directory within @file{test-code}.  Add
4215 104 jeremybenn
the directory to the existing @file{Makefile.am} in the @file{test-code}
4216 346 jeremybenn
directory and create a @file{Makefile.am} in the new directory to drive
4217
building the test program(s).  Don't forget to add the new
4218
@file{Makefile} to the top level @file{configure.ac} so it gets
4219
generated. Not all tests require code here.
4220 104 jeremybenn
 
4221
@item
4222 346 jeremybenn
Put new target C code in its own directory within @file{test-code-or1k}.
4223
Once again modify & create @file{Makefile.am}.  This time modify the
4224
@file{configure.ac} in the @file{test-code-or1k} so the @file{Makefile}
4225
gets generated.  The existing programs provide examples to start from,
4226
including custom linker scripts where needed.
4227 104 jeremybenn
 
4228
@item
4229
Add one or more tests and configuration files to the relevant ``tool''
4230 346 jeremybenn
test directory.  Use the existing tests as templates.  They make heavy
4231
use of the @command{expect}/TCL procedures in the @file{config}
4232
directory to facilitate driving the tests.
4233 104 jeremybenn
 
4234
@end itemize
4235
 
4236 19 jeremybenn
@node  GNU Free Documentation License
4237
@chapter GNU Free Documentation License
4238
@cindex license for @value{OR1KSIM}
4239
 
4240
@include fdl-1.2.texi
4241
 
4242
@node Index
4243
 
4244
@unnumbered Index
4245
 
4246
@printindex cp
4247
 
4248
@bye

powered by: WebSVN 2.1.0

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