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 460

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

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

powered by: WebSVN 2.1.0

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