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

Subversion Repositories openrisc_me

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

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

powered by: WebSVN 2.1.0

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