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

Subversion Repositories openrisc

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

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

powered by: WebSVN 2.1.0

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