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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [or1ksim/] [doc/] [or1ksim.info] - Blame information for rev 103

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

Line No. Rev Author Line
1 100 julius
This is
2
/home/jules/Documents/openrisc_svn/openrisc/trunk/or1ksim/doc/or1ksim.info,
3
produced by makeinfo version 4.13 from
4
/home/jules/Documents/openrisc_svn/openrisc/trunk/or1ksim/doc/or1ksim.texi.
5 19 jeremybenn
 
6
INFO-DIR-SECTION Embedded development
7
START-INFO-DIR-ENTRY
8
* Or1ksim: (or32-uclinux-or1ksim).      The OpenRISC 1000 Architectural
9
                                        Simulator
10
END-INFO-DIR-ENTRY
11
 
12
This file documents the OpenRISC Architectural Simulator, Or1ksim.
13
 
14
Copyright (C) 2008, 2009 Embecosm Limited.
15
 
16
     Permission is granted to copy, distribute and/or modify this
17
     document under the terms of the GNU Free Documentation License,
18
     Version 1.2 or any later version published by the Free Software
19
     Foundation; with no Invariant Sections, with no Front-Cover Texts,
20
     and with no Back-Cover Texts.  A copy of the license is included
21
     in the section entitled "GNU Free Documentation License".
22
 
23

24
File: or1ksim.info,  Node: Top,  Next: Installation,  Up: (dir)
25
 
26
Scope of this Document
27
**********************
28
 
29
This document is the user guide for Or1ksim, the OpenRISC 1000
30
Architectural Simulator.
31
 
32
* Menu:
33
 
34
* Installation::
35
* Usage::
36
* Configuration::
37
* Interactive Command Line::
38
* Verification API::
39
 
40
* Code Internals::
41
 
42
* GNU Free Documentation License::  The license for this documentation
43
* Index::
44
 
45

46
File: or1ksim.info,  Node: Installation,  Next: Usage,  Prev: Top,  Up: Top
47
 
48
1 Installation
49
**************
50
 
51
Installation follows standard GNU protocols.
52
 
53
* Menu:
54
 
55
* Preparation::
56
* Configuring the Build::
57
* Build and Install::
58
* Known Issues::
59
 
60

61
File: or1ksim.info,  Node: Preparation,  Next: Configuring the Build,  Up: Installation
62
 
63
1.1 Preparation
64
===============
65
 
66
Unpack the software and create a _separate_ directory in which to build
67
it:
68
 
69 99 jeremybenn
     tar jxf or1ksim-2010-05-20.tar.bz2
70 19 jeremybenn
     mkdir builddir_or1ksim
71
     cd builddir_or1ksim
72
 
73

74
File: or1ksim.info,  Node: Configuring the Build,  Next: Build and Install,  Prev: Preparation,  Up: Installation
75
 
76
1.2 Configuring the Build
77
=========================
78
 
79
Configure the software using the `configure' script in the main
80
directory.
81
 
82
The most significant argument is `--target', which should specify the
83 82 jeremybenn
OpenRISC 1000 32-bit architecture.  If this argument is omitted, it will
84 19 jeremybenn
default to OpenRISC 1000 32-bit with a warning
85
 
86 99 jeremybenn
     ../or1ksim-2010-05-20/configure --target=or32-uclinux ...
87 19 jeremybenn
 
88
There are several other options available, many of which are standard
89 82 jeremybenn
to GNU `configure' scripts.  Use `configure --help' to see all the
90
options.  The most useful is `--prefix' to specify a directory for
91 19 jeremybenn
installation of the tools.
92
 
93
A number of Or1ksim features in the simulator do require enabling at
94 82 jeremybenn
configuration.  These include
95 19 jeremybenn
 
96
`--enable-profiling'
97
`--disable-profiling'
98 82 jeremybenn
     If enabled, Or1ksim is compiled for profiling with `gprof'.  This
99
     is disabled by default.  Only really of value for developers of
100 19 jeremybenn
     Or1ksim.
101
 
102
`--enable-execution=simple'
103
`--enable-execution=complex'
104
`--enable-execution=dynamic'
105
     Or1ksim has developed to improve functionality and performance.
106
     This feature allows three versions of Or1ksim to be built
107
 
108
    `--enable-execution=simple'
109
          Build the original simple interpreting simulator
110
 
111
    `--enable-execution=complex'
112 82 jeremybenn
          Build a more complex interpreting simulator.  Experiments
113
          suggest this is 50% faster than the simple simulator.  This
114
          is the default.
115 19 jeremybenn
 
116
    `--enable-execution=dynamic'
117 82 jeremybenn
          Build a dynamically compiling simulator.  This is the way
118
          many modern ISS are built.  This represents a work in
119
          progress.  Currently Or1ksim will compile, but segfaults if
120
          configured with this option.
121 19 jeremybenn
 
122
 
123
     The default is `--enable-execution=complex'.
124
 
125
`--enable-ethphy'
126
`--disable-ethphy'
127
     If enabled, this option allows the Ethernet to be simulated by
128
     connecting via a socket (the alternative reads and writes, from
129 82 jeremybenn
     and to files).  This must then be configured using the relevant
130
     fields in the `ethernet' section of the configuration file.  *Note
131 19 jeremybenn
     Ethernet Configuration: Ethernet Configuration.
132
 
133
     The default is for this to be disabled.
134
 
135
`--enable-range-stats'
136
`--disable-range-stats'
137
     If enabled, this option allows statistics to be collected to
138 82 jeremybenn
     analyse register access over time.  The default is for this to be
139 19 jeremybenn
     disabled.
140
 
141
`--enable-ov-flag'
142
`--disable-ov-flag'
143
     If enabled, this option causes instructions to set the overflow
144 82 jeremybenn
     flag.  The instructions affected by this are `l.add', `l.addc',
145 19 jeremybenn
     `l.addi', `l.and', `l.andi', `l.div', `l.divu', `l.mul', `l.muli',
146
     `l.or', `l.ori', `l.sll', `l.slli', `l.srl', `l.srli', `l.sra',
147
     `l.srai', `l.sub', `l.xor' and `l.xori'.
148
 
149
     The default is for this to be disabled.
150
 
151
          Caution: This appears a very dangerous option, to the extent
152 82 jeremybenn
          of arguably being a bug.  Whether or not flags are set is
153
          part of the OpenRISC 1000 architectural specification.
154
          Within the above list, the arithmetic instructions (`l.add',
155
          `l.addc', `l.addi', `l.div', `l.divu', `l.mul', `l.muli' and
156
          `l.sub'), together with `l.addic' which is missed out, set
157
          the overflow flag.  All the others (`l.and', `l.andi',
158
          `l.or', `l.ori', `l.sll', `l.slli', `l.srl', `l.srli',
159
          `l.sra', `l.srai', `l.xor' and `l.xori') do not.
160 19 jeremybenn
 
161
          Thus it is impossible to get correct behavior whichever way
162
          this option is set.
163
 
164
`--enable-arith-flag'
165
`--disable-arith-flag'
166
     If enabled, this option causes instructions to set the flag (`F'
167 82 jeremybenn
     bit) in the supervision register.  The instructions affected by
168 19 jeremybenn
     this are `l.add', `l.addc', `l.addi', `l.and' and `l.andi'.
169
 
170
     The default is for this to be disabled.
171
 
172
          Caution: As with `--enable-ov-flag', this appears another
173
          very dangerous option, to the extent of arguably being a bug.
174
          It also appears to be only partially implemented--why only
175
          the instructions early in the alphabet?
176
 
177
          Whether or not flags are set is part of the OpenRISC 1000
178 82 jeremybenn
          architectural specification.  The only flags which should set
179 19 jeremybenn
          this are the "set flag" instructions: `l.sfeq', `l.sfeqi',
180
          `l.sfges', `l.sfgesi', `l.sfgeu', `l.sfgeui', `l.sfgts',
181
          `l.sfgtsi', `l.sfgtu', `l.sfgtui', `l.sfles', `l.sflesi',
182
          `l.sfleu', `l.sfleui', `l.sflts', `l.sfltsi', `l.sfltu',
183
          `l.sfltui', `l.sfne' and `l.sfnei'.
184
 
185
          The flags are correctly set (irrespective of
186
          `--enable-arith_flag').
187
 
188
          Correct behavior is thus achieved if this flag is not set.
189
          `--enable-arith-flag' should never be used.
190
 
191
 
192
`--enable-debug'
193
`--disable-debug'
194
     This is a feature of the Argtable2 package used to process
195 82 jeremybenn
     arguments.  If enabled, some debugging features are turned on in
196
     Argtable2.  It is provided for completeness, but there is no
197
     reason why this feature should ever be needed by any Or1ksim user.
198 19 jeremybenn
 
199 82 jeremybenn
`--enable-all-tests'
200
`--disable-all-tests'
201
     Some of the tests (at the time of writing just one) will not
202
     compile without error.  If enabled with this flag, all test
203
     programs will be compiled with `make check'.
204 19 jeremybenn
 
205 82 jeremybenn
     This flag is intended for those working on the test package, who
206
     wish to get the missing test(s) working.
207
 
208
 
209 19 jeremybenn

210
File: or1ksim.info,  Node: Build and Install,  Next: Known Issues,  Prev: Configuring the Build,  Up: Installation
211
 
212
1.3 Building and Installing
213
===========================
214
 
215 82 jeremybenn
Build the tool with:
216 19 jeremybenn
 
217
     make all
218 82 jeremybenn
 
219
If you have the OpenRISC tool chain and DejaGNU installed, you can
220
verify the tool as follows (otherwise omit this step):
221
 
222
     make check
223
 
224
Install the tool with:
225
 
226 19 jeremybenn
     make install
227
 
228
This will install the three variations of the Or1ksim tool,
229
`or32-uclinux-sim', `or32-uclinux-psim' and `or32-uclinux-mpsim', the
230
Or1ksim library, `libsim', the header file, `or1ksim.h' and this
231
documentation in `info' format.
232
 
233
     Note: Testing Or1ksim with `make check' is not yet supported.
234
 
235
The documentation may be created and installed in alternative formats
236
(PDF, Postscript, DVI, HTML) with for example:
237
 
238
     make pdf
239
     make install-pdf
240
 
241

242
File: or1ksim.info,  Node: Known Issues,  Prev: Build and Install,  Up: Installation
243
 
244
1.4 Known Problems and Issues
245
=============================
246
 
247 82 jeremybenn
The following problems and issues are known about with Or1ksim
248 99 jeremybenn
2010-05-20.  The OpenRISC tracker may be used to see the current state
249 90 jeremybenn
of these issues and to raise new problems and feature requests.  It may
250
be found at `http://www.opencores.org/ptracker.cgi/view/or1k/398'.
251 19 jeremybenn
 
252
   * The Supervision Register Little Endian Enable (LEE) bit is
253 82 jeremybenn
     ignored.  Or1ksim can be built for either little endian or big
254 19 jeremybenn
     endian use, but that behavior cannot be changed dynamically.
255
 
256
   * The NPC is a read/write register, but after being written it
257 82 jeremybenn
     clears the pipeline.  This means that if the processor is stalled,
258 19 jeremybenn
     the value should subsequently read back as 0, until the processor
259 82 jeremybenn
     is unstalled and able to refill its pipeline.  By default Or1ksim
260 19 jeremybenn
     always reports back the value of NPC, even when it has been
261
     written while stalled.
262
 
263
     There is now an option, `--strict-npc', which will enforce this
264 82 jeremybenn
     behavior.  At some stage in the future it will become the default
265 19 jeremybenn
     behavior, but for now it is an option, since its use will break
266
     GDB.
267
 
268
   * The memory components are given names in the configuration file.
269
     However there is currently no way for Or1ksim to report that name
270
     back to the user (for example to identify which memory block
271
     corresponds to a particular access).
272
 
273
   * Or1ksim allows the processor to be stalled (from the command
274 82 jeremybenn
     line), even if there is no debugger present.  This seems to be a
275 19 jeremybenn
     meaningless operation.
276
 
277
   * Or1ksim is not reentrant, so a program cannot instantiate multiple
278 82 jeremybenn
     instances using the library.  This is clearly a problem when
279
     considering multi-core applications.  However it stems from the
280
     original design, and can only be fixed by a complete rewrite.  The
281 19 jeremybenn
     entire source code uses static global constants liberally!
282
 
283
   * There is no support for floating point instructions currently in
284 82 jeremybenn
     Or1ksim.  However this is a work in progress and should be
285
     available in the future.
286 19 jeremybenn
 
287
 
288

289
File: or1ksim.info,  Node: Usage,  Next: Configuration,  Prev: Installation,  Up: Top
290
 
291
2 Usage
292
*******
293
 
294
* Menu:
295
 
296
* Standalone Simulator::
297
* Profiling Utility::
298
* Memory Profiling Utility::
299
* Simulator Library::
300
 
301

302
File: or1ksim.info,  Node: Standalone Simulator,  Next: Profiling Utility,  Up: Usage
303
 
304
2.1 Standalone Simulator
305
========================
306
 
307
The general form the standalone command is:
308
 
309
     or32-uclinux-sim [-vhi] [-f FILE] [--nosrv] [--srv=[N]] [-d STR]
310
                      [--enable-profile] [--enable-mprofile] [FILE]
311
 
312 82 jeremybenn
Many of the options have both a short and a long form.  For example
313
`-h' or `--help'.
314 19 jeremybenn
 
315
`-v'
316
`--version'
317
     Print out the version and copyright notice for Or1ksim and exit.
318
 
319
`-h'
320
`--help'
321
     Print out help about the command line options and what they mean.
322
 
323
`-f FILE'
324
`--file FILE'
325
     Read configuration commands from the specified file, looking first
326
     in the current directory, and otherwise in the `$HOME/.or1k'
327 82 jeremybenn
     directory.  If this argument is not specified, the file `sim.cfg'
328
     in those two locations is used.  Failure to find the file is a
329
     fatal error.  *Note Configuration: Configuration, for detailed
330
     information on configuring Or1ksim.
331 19 jeremybenn
 
332
`--nosrv'
333 82 jeremybenn
     Do not start up the debug server.  This overrides any setting
334
     specified in the configuration file.  This option may not be
335
     specified with `--srv'.  If it is, a rude message is printed and
336
     the `--nosrv' option is ignored.
337 19 jeremybenn
 
338
`--srv'
339
 
340
`--srv=N'
341 82 jeremybenn
     Start up the debug server.  If the parameter, N, is specified, use
342 19 jeremybenn
     that as the TCP/IP port for the server, otherwise a random value
343 82 jeremybenn
     from the private port range (41920-65535) will be used.  This
344
     option may not be specified with `--nosrv'.  If it is, a rude
345
     message is printed and the `--nosrv' option is ignored.
346 19 jeremybenn
 
347
`-d=CONFIG_STRING'
348
`--debug-config=CONFIG_STRING'
349 82 jeremybenn
     Enable selected debug messages in Or1ksim.  This parameter is for
350
     use by developers only, and is not covered further here.  See the
351 19 jeremybenn
     source code for more details.
352
 
353
`-i'
354
`--interactive'
355
     After starting, drop into the Or1ksim interactive command shell.
356
 
357
`--strict-npc'
358
     In real hardware, setting the next program counter (NPC, SPR 16),
359 82 jeremybenn
     flushes the processor pipeline.  The consequence of this is that
360
     until the pipeline refills, reading the NPC will return zero.
361
     This is typically the case when debugging, since the processor is
362 19 jeremybenn
     stalled.
363
 
364
     Historically, Or1ksim has always returned the value of the NPC,
365 82 jeremybenn
     irrespective of when it is changed.  If the `--strict-npc' option
366
     is used, then Or1ksim will mirror real hardware more accurately.
367
     If the NPC is changed while the processor is stalled, subsequent
368 19 jeremybenn
     reads of its value will return 0 until the processor is unstalled.
369
 
370
     This is not currently the default behavior, since tools such as
371
     GDB have been implemented assuming the historic Or1ksim behavior.
372
     However at some time in the future it will become the default.
373
 
374
`--enable-profile'
375
     Enable instruction profiling.
376
 
377
`--enable-mprofile'
378
     Enable memory profiling.
379
 
380
 
381

382
File: or1ksim.info,  Node: Profiling Utility,  Next: Memory Profiling Utility,  Prev: Standalone Simulator,  Up: Usage
383
 
384
2.2 Profiling Utility
385
=====================
386
 
387 82 jeremybenn
This utility analyses instruction profile data generated by Or1ksim.
388
It may be invoked as a standalone command, or from the Or1ksim CLI.
389
The general form the standalone command is:
390 19 jeremybenn
 
391
     or32-uclinux-profile [-vhcq] [-g=FILE]
392
 
393 82 jeremybenn
Many of the options have both a short and a long form.  For example
394
`-h' or `--help'.
395 19 jeremybenn
 
396
`-v'
397
`--version'
398
     Print out the version and copyright notice for the Or1ksim
399
     profiling utility and exit.
400
 
401
`-h'
402
`--help'
403
     Print out help about the command line options and what they mean.
404
 
405
`-c'
406
`--cumulative'
407
     Show cumulative sum of cycles in functions
408
 
409
`-q'
410
`--quiet'
411
     Suppress messages
412
 
413
`-g=FILE'
414
`--generate=FILE'
415 82 jeremybenn
     The data file to analyse.  If omitted, the default file,
416 19 jeremybenn
     `sim.profile' is used.
417
 
418
 
419

420
File: or1ksim.info,  Node: Memory Profiling Utility,  Next: Simulator Library,  Prev: Profiling Utility,  Up: Usage
421
 
422
2.3 Memory Profiling Utility
423
============================
424
 
425 82 jeremybenn
This utility analyses memory profile data generated by Or1ksim.  It may
426
be invoked as a standalone command, or from the Or1ksim CLI.  The
427 19 jeremybenn
general form the standalone command is:
428
 
429
     or32-uclinux-mprofile  [-vh] [-m=M] [-g=N] [-f=FILE] FROM TO
430
 
431 82 jeremybenn
Many of the options have both a short and a long form.  For example
432
`-h' or `--help'.
433 19 jeremybenn
 
434
`-v'
435
`--version'
436
     Print out the version and copyright notice for the Or1ksim memory
437
     profiling utility and exit.
438
 
439
`-h'
440
`--help'
441
     Print out help about the command line options and what they mean.
442
 
443
`-m=M'
444
`--mode=M'
445 82 jeremybenn
     Specify the mode out output.  Permitted options are
446 19 jeremybenn
 
447
    `detailed'
448
    `d'
449 82 jeremybenn
          Detailed output.  This is the default if no mode is specified.
450 19 jeremybenn
 
451
    `pretty'
452
    `p'
453
          Pretty printed output.
454
 
455
    `access'
456
    `a'
457
          Memory accesses only.
458
 
459
    `width'
460
    `w'
461
          Access width only.
462
 
463
 
464
`-g=N'
465
`--group=N'
466
     Group 2^n bits of successive addresses together.
467
 
468
`-f=FILE'
469
`--filename=FILE'
470 82 jeremybenn
     The data file to analyse.  If not specified, the default,
471 19 jeremybenn
     `sim.profile' is used.
472
 
473
`FROM'
474
`TO'
475
     FROM and TO are respectively the start and end address of the
476
     region of memory to be analysed.
477
 
478
 
479

480
File: or1ksim.info,  Node: Simulator Library,  Prev: Memory Profiling Utility,  Up: Usage
481
 
482
2.4 Simulator Library
483
=====================
484
 
485
Or1ksim may be used as a static of dynamic library, `libsim.a' or
486 82 jeremybenn
`libsim.so'.  When compiling with the static library, the flag, `-lsim'
487 19 jeremybenn
should be added to the link command.
488
 
489
The header file `or1ksim.h' contains appropriate declarations of the
490 82 jeremybenn
functions exported by the Or1ksim library.  These are:
491 19 jeremybenn
 
492 93 jeremybenn
 -- `or1ksim.h': int or1ksim_init (const char
493
     *CONFIG_FILE, const char *IMAGE_FILE, void *CLASS_PTR, int
494
     (*UPR)(void *CLASS_PTR, unsigned long int ADDR, unsigned char
495
     MASK[], unsigned char RDATA[], int DATA_LEN), int (*UPW)(void
496
     *CLASS_PTR, unsigned long int ADDR, unsigned char MASK[], unsigned
497
     char WDATA[], int DATA_LEN))
498
 
499 19 jeremybenn
     The initialization function is supplied with the name of a
500
     configuration file, CONFIG_FILE, an executable image, IMAGE_FILE,
501
     a pointer to the calling class, CLASS_PTR (since the library may
502
     be used from C++) and two up-call functions, one for reads, UPR,
503
     and one for writes, UPW.
504
 
505
     *Note Configuration: Configuration, for detailed information on
506
     configuring Or1ksim and the format of the configuration file.
507
 
508
     UPW is called for any write to an address external to the model
509 82 jeremybenn
     (determined by a `generic' section in the configuration file).
510
     UPR is called for any reads to an external address.  The CLASS_PTR
511
     is passed back with these upcalls, allowing the function to
512
     associate the call with the class which originally initialized the
513 93 jeremybenn
     library.  Both UPW and UPR should return zero on success and
514
     non-zero otherwise.  At the present time the meaning of non-zero
515
     values is not defined but this may change in the future.
516 19 jeremybenn
 
517 93 jeremybenn
     MASK indicates which bytes in the data are to be written or read.
518 82 jeremybenn
     Bytes to be read/written should have 0xff set in MASK.  Otherwise
519 93 jeremybenn
     the byte should be zero.  The adddress, ADDR, is the _full_
520
     address, since the upcall function must handle all generic
521
     devices, using the full address for decoding.
522 19 jeremybenn
 
523 93 jeremybenn
     Endianness is not completely transparent, since Or1ksim is
524
     transferring byte vectors, not multi-byte values.
525 19 jeremybenn
 
526 93 jeremybenn
          Caution: This is a change from version 0.3.0. It simplifies
527
          the interface, and makes Or1ksim more consistent with payload
528
          representation in SystemC TLM 2.0.
529 19 jeremybenn
 
530 93 jeremybenn
          Note: The current implementation of Or1ksim always transfers
531
          single words (4 bytes), using masks if smaller values are
532
          required.  In this it mimcs the behavior of the WishBone bus.
533
 
534
 
535 19 jeremybenn
 -- `or1ksim.h': int or1ksim_run (double DURATION)
536
     Run the simulator for the simulated duration specified (in
537
     seconds).
538
 
539
 
540
 -- `or1ksim.h': void or1ksim_reset_duration (double DURATION)
541
     Change the duration of a run specified in an earlier call to
542 82 jeremybenn
     `or1ksim_run'.  Typically this is called from an upcall, which
543 19 jeremybenn
     realizes it needs to change the duration of the run specified in
544
     the call to `or1ksim_run' that has been interrupted by the upcall.
545
 
546
     The time specified is the amount of time that the run must continue
547
     for (i.e the duration from _now_, not the duration from the
548
     original call to `or1ksim_run').
549
 
550
 
551
 -- `or1ksim.h': void or1ksim_set_time_point ()
552 82 jeremybenn
     Set a timing point.  For use with `or1ksim_get_time_period'.
553 19 jeremybenn
 
554
 
555
 -- `or1ksim.h': double or1ksim_get_time_period ()
556
     Return the simulated time (in seconds) that has elapsed since the
557
     last call to `or1ksim_set_time_point'.
558
 
559
 
560
 -- `or1ksim.h': int or1ksim_is_le ()
561
     Return 1 (logical true) if the Or1ksim simulation is
562
     little-endian, 0 otherwise.
563
 
564
 
565
 -- `or1ksim.h': unsigned long int or1ksim_clock_rate ()
566 82 jeremybenn
     Return the Or1ksim clock rate (in Hz).  This is the value
567
     specified in the configuration file.
568 19 jeremybenn
 
569
 
570
 -- `or1ksim.h': void or1ksim_interrupt (int I)
571 82 jeremybenn
     Generate an edge-triggered interrupt on interrupt line I.  The
572
     interrupt is then immediately cleared automatically.  A warning
573 19 jeremybenn
     will be generated and the interrupt request ignored if level
574
     sensitive interrupts have been configured with the programmable
575
     interrupt controller (*note Interrupt Configuration: Interrupt
576
     Configuration.).
577
 
578
 
579
 -- `or1ksim.h': void or1ksim_interrupt_set (int I)
580 82 jeremybenn
     Assert a level-triggered interrupt on interrupt line I.  The
581 19 jeremybenn
     interrupt must be cleared separately by an explicit call to
582 82 jeremybenn
     `or1ksim_interrupt_clear'.  A warning will be generated, and the
583 19 jeremybenn
     interrupt request ignored if edge sensitive interrupts have been
584
     configured with the programmable interrupt controller (*note
585
     Interrupt Configuration: Interrupt Configuration.).
586
 
587
 
588
 -- `or1ksim.h': void or1ksim_interrupt_clear (int I)
589
     Clear a level-triggered interrupt on interrupt line I, which was
590 82 jeremybenn
     previously asserted by a call to `or1ksim_interrupt_set'.  A
591 19 jeremybenn
     warning will be generated, and the interrupt request ignored if
592
     edge sensitive interrupts have been configured with the
593
     programmable interrupt controller (*note Interrupt Configuration:
594
     Interrupt Configuration.).
595
 
596
 
597
The libraries will be installed in the `lib' sub-directory of the main
598
installation directory (as specified with the `--prefix' option to the
599
`configure' script).
600
 
601
For example if the main installation directory is `/opt/or1ksim', the
602 82 jeremybenn
library will be found in the `/opt/or1ksim/lib' directory.  It is
603 19 jeremybenn
available as both a static library (`libsim.a') and a shared object
604
(`libsim.so').
605
 
606
To link against the library add the `-lsim' flag when linking and do
607
one of the following:
608
 
609
   * Add the library directory to the `LD_LIBRARY_PATH' environment
610 82 jeremybenn
     variable during execution.  For example:
611 19 jeremybenn
 
612
          export LD_LIBRARY_PATH=/opt/or1ksim/lib:$LD_LIBRARY_PATH
613
 
614
   * Add the library directory to the `LD_RUN_PATH' environment
615 82 jeremybenn
     variable during linking.  For example:
616 19 jeremybenn
 
617
          export LD_RUN_PATH=/opt/or1ksim/lib:$LD_RUN_PATH
618
 
619
   * Use the linker `--rpath' option and specify the library directory
620 82 jeremybenn
     when linking your program.  For example
621 19 jeremybenn
 
622 82 jeremybenn
          gcc ...  -Wl,--rpath -Wl,/opt/or1ksim/lib ...
623 19 jeremybenn
 
624
   * Add the library directory to `/etc/ld.so.conf'
625
 
626
 
627

628
File: or1ksim.info,  Node: Configuration,  Next: Interactive Command Line,  Prev: Usage,  Up: Top
629
 
630
3 Configuration
631
***************
632
 
633 82 jeremybenn
Or1ksim is configured through a configuration file.  This is specified
634 19 jeremybenn
through the `-f' parameter to the Or1ksim command, or passed as a
635 82 jeremybenn
string when initializing the Or1ksim library.  If no file is specified,
636
the default `sim.cfg' is used.  The file is looked for first in the
637 19 jeremybenn
current directory, then in the `$HOME/.or1k' directory of the user.
638
 
639
* Menu:
640
 
641
* Configuration File Format::
642
* Simulator Configuration::
643
* Core OpenRISC Configuration::
644
* Peripheral Configuration::
645
 
646

647
File: or1ksim.info,  Node: Configuration File Format,  Next: Simulator Configuration,  Up: Configuration
648
 
649
3.1 Configuration File Format
650
=============================
651
 
652
The configuration file is a plain text file.
653
 
654
* Menu:
655
 
656
* Configuration File Preprocessing::
657
* Configuration File Syntax::
658
 
659

660
File: or1ksim.info,  Node: Configuration File Preprocessing,  Next: Configuration File Syntax,  Up: Configuration File Format
661
 
662
3.1.1 Configuration File Preprocessing
663
--------------------------------------
664
 
665 82 jeremybenn
The configuration file may include C style comments (i.e.  delimited by
666 19 jeremybenn
`/*' and `*/').
667
 
668
Configure files may be included, using
669
 
670
     include FILENAME_TO_INCLUDE
671
 
672

673
File: or1ksim.info,  Node: Configuration File Syntax,  Prev: Configuration File Preprocessing,  Up: Configuration File Format
674
 
675
3.1.2 Configuration File Syntax
676
-------------------------------
677
 
678
The configuration file is divided into a series of sections, with the
679
general form:
680
 
681
     section SECTION_NAME
682
 
683
       ...
684
 
685
     end
686
 
687
Sections may also have sub-sections within them (currently only the
688
ATA/ATAPI disc interface uses this).
689
 
690
Within a section, or sub-section are a series of parameter assignments,
691
one per line, withe the general form
692
 
693
       PARAMETER = VALUE
694
 
695
Depending on the parameter, the value may be a named value (an
696
enumeration), an integer (specified in any format acceptable in C) or a
697 82 jeremybenn
string in doubple quotes.  For flag parameters, the value 1 is used to
698
mean "true" or "on" and the value "0" to mean "false" or "off".  An
699 19 jeremybenn
example from a memory section shows each of these
700
 
701
     section memory
702
       type    = random
703
       pattern = 0x00
704
       name    = "FLASH"
705
       ...
706
     end
707
 
708
Many parameters are optional and take reasonable default values if not
709 82 jeremybenn
specified.  However there are some parameters (for example the `ce'
710 19 jeremybenn
parameter in `section memory') _must_ be specified.
711
 
712
Subsections are introduced by a keyword, with a parameter value (no `='
713 82 jeremybenn
sign), and end with the same keyword prefixed by `end'.  Thus the
714 19 jeremybenn
ATA/ATAPI inteface (`section ata') has a `device' subsection, thus:
715
 
716
     section ata
717
       ...
718
       device 0
719
         type    = 1
720
         file = "FILENAME"
721
         ...
722
       enddevice
723
       ...
724
     end
725
 
726
Some sections (for example `section sim') should appear only once.
727
Others (for example `section memory' may appear multiple times.
728
 
729
Sections may be omitted, _unless they contain parameters which are
730 82 jeremybenn
non-optional_.  If the section describes a part of the simulator which
731 19 jeremybenn
is optional (for example whether it has a UART), then that
732 82 jeremybenn
functionality will not be provided.  If the section describes a part of
733 19 jeremybenn
the simulator which is not optional (for example the CPU), then all the
734
parameters of that section will take their default values.
735
 
736
All optional parts of the functionality are always described by
737
sections including a `enabled' parameter, which can be set to 0 to
738
ensure that functionality is explicitly omitted.
739
 
740
Even if a section is disabled, all its parameters will be read and
741 82 jeremybenn
stored.  This is helpful if the section is subsequently enabled from
742
the Or1ksim command line (*note Interactive Command Line: Interactive
743 19 jeremybenn
Command Line.).
744
 
745
     Tip: It generally clearer to have sections describing _all_
746
     components, with omitted functionality explicitly indicated by
747
     setting the `enabled' parameter to 0
748
 
749
The following sections describe the various configuration sections and
750
the parameters which may be set in each.
751
 
752

753
File: or1ksim.info,  Node: Simulator Configuration,  Next: Core OpenRISC Configuration,  Prev: Configuration File Format,  Up: Configuration
754
 
755
3.2 Simulator Configuration
756
===========================
757
 
758
* Menu:
759
 
760
* Simulator Behavior::
761
* Verification API Configuration::
762
* CUC Configuration::
763
 
764

765
File: or1ksim.info,  Node: Simulator Behavior,  Next: Verification API Configuration,  Up: Simulator Configuration
766
 
767
3.2.1 Simulator Behavior
768
------------------------
769
 
770 82 jeremybenn
Simulator behavior is described in `section sim'.  This section should
771
appear only once.  The following parameters may be specified.
772 19 jeremybenn
 
773
`verbose = 0|1'
774 82 jeremybenn
     If 1 (true), print extra messages.  Default 0.
775 19 jeremybenn
 
776
`debug = 0-9'
777 82 jeremybenn
 
778
     higher the value the greater the number of messages.  Default 0.
779
     Negative values will be treated as 0 (with a warning).  Values
780
     that are too large will be treated as 9 (with a warning).
781 19 jeremybenn
 
782
`profile = 0|1'
783
     If 1 (true) generate a profiling file using the file specified in
784 82 jeremybenn
     the `prof_file' parameter or otherwise `sim.profile'.  Default 0.
785 19 jeremybenn
 
786
`prof_file = ``FILENAME'''
787 82 jeremybenn
     Specifies the file to be used with the `profile' parameter.
788
     Default `sim.profile'.  For backwards compatibility, the
789
     alternative name `prof_fn' is supported for this parameter, but
790
     deprecated.
791 19 jeremybenn
 
792
`mprofile = 0|1'
793
     If 1 (true) generate a memory profiling file using the file
794
     specified in the `mprof_file' parameter or otherwise
795 82 jeremybenn
     `sim.mprofile'.  Default 0.
796 19 jeremybenn
 
797
`mprof_fn = ``FILENAME'''
798
     Specifies the file to be used with the `mprofile' parameter.
799 82 jeremybenn
     Default `sim.mprofile'.  For backwards compatibility, the
800 19 jeremybenn
     alternative name `mprof_fn' is supported for this parameter, but
801
     deprecated.
802
 
803
`history = 0|1'
804 82 jeremybenn
     If 1 (true) track execution flow.  Default 0.
805 19 jeremybenn
 
806
          Note: Setting this parameter seriously degrades performance.
807
 
808
          Note: If this execution flow tracking is enabled, then
809
          `dependstats' must be enabled in the CPU configuration
810
          section (*note CPU Configuration: CPU Configuration.).
811
 
812
`exe_log = 0|1'
813 82 jeremybenn
     If 1 (true), generate an execution log.  Log is written to the
814
     file specified in parameter `exe_log_file'.  Default 0.
815 19 jeremybenn
 
816
          Note: Setting this parameter seriously degrades performance.
817
 
818
`exe_log_type = default|hardware|simple|software'
819
     Type of execution log to produce.
820
 
821
    `default'
822 82 jeremybenn
          Produce default output for the execution log.  In the current
823 19 jeremybenn
          implementation this is the equivalent of `hardware'.
824
 
825
    `hardware'
826
          After each instruction execution, log the number of
827
          instructions executed so far, the next instruction to execute
828
          (in hex), the general purpose registers (GPRs), status
829
          register, exception program counter, exception, effective
830
          address register and exception status register.
831
 
832
    `simple'
833
          After each instruction execution, log the number of
834
          instructions executed so far and the next instruction to
835
          execute, symbolically disassembled.
836
 
837
    `software'
838
          After each instruction execution, log the number of
839
          instructions executed so far and the next instruction to
840 82 jeremybenn
          execute, symbolically disassembled.  Also show the value of
841 19 jeremybenn
          each operand to the instruction.
842
 
843
 
844 82 jeremybenn
     Default value `hardware'.  Any unrecognized keyword (case
845 19 jeremybenn
     insensitive) will be treated as the default with a warning.
846
 
847
          Note: Execution logs can be _very_ big.
848
 
849
`exe_log_start = VALUE'
850 82 jeremybenn
     Address of the first instruction to start logging.  Default 0.
851 19 jeremybenn
 
852
`exe_log_end = VALUE'
853 82 jeremybenn
     Address of the last instruction to log.  Default no limit (i.e
854
     once started logging will continue until the simulator exits).
855 19 jeremybenn
 
856
`exe_log_marker = VALUE'
857
     Specifies the number of instructions between printing horizontal
858 82 jeremybenn
     markers.  Default is to produce no markers.
859 19 jeremybenn
 
860
`exe_log_file = FILENAME'
861
     Filename for the execution log filename if `exe_log' is enabled.
862 82 jeremybenn
     Default `executed.log'.  For backwards compatibility, the
863 19 jeremybenn
     alternative name `exe_log_fn' is supported for this parameter, but
864
     deprecated.
865
 
866
`clkcycle = VALUE[ps|ns|us|ms]'
867 82 jeremybenn
     Specify the time taken by one clock cycle.  If no units are
868
     specified, `ps' is assumed.  Default 4000ps (250MHz).
869 19 jeremybenn
 
870
 
871

872
File: or1ksim.info,  Node: Verification API Configuration,  Next: CUC Configuration,  Prev: Simulator Behavior,  Up: Simulator Configuration
873
 
874
3.2.2 Verification API (VAPI) Configuration
875
-------------------------------------------
876
 
877
The Verification API (VAPI) provides a TCP/IP interface to allow
878 82 jeremybenn
components of the simulation to be controlled externally.  *Note
879 19 jeremybenn
Verification API: Verification API, for more details.
880
 
881 82 jeremybenn
Verification API configuration is described in `section vapi'.  This
882
section may appear at most once.  The following parameters may be
883 19 jeremybenn
specified.
884
 
885
`enabled = 0|1'
886
     If 1 (true), verification API is enabled and its server started.
887
     If 0 (the default), it is disabled.
888
 
889
`server_port = VALUE'
890
     When VAPI is enabled, communication will be via TCP/IP on the port
891 82 jeremybenn
     specified by VALUE.  The value must lie in the range 1 to 65535.
892 19 jeremybenn
     The default value is 50000.
893
 
894 82 jeremybenn
          Tip: There is no registered port for Or1ksim VAPI.  Good
895 19 jeremybenn
          practice suggests users should adopt port values in the
896 82 jeremybenn
          "Dynamic" or "Private" port range, i.e.  49152-65535.
897 19 jeremybenn
 
898
`log_enabled = 0|1'
899
     If 1 (true), all VAPI requests and sent commands will be logged.
900 82 jeremybenn
     If 0 (the default), logging is diabled.  Logs are written to the
901 19 jeremybenn
     file specified by the `vapi_log_file' field (see below).
902
 
903
          Caution: This can generate a substantial amount of file I/O
904
          and seriously degrade simulator performance.
905
 
906
`hide_device_id = 0|1'
907 82 jeremybenn
     If 1 (true) don't log the device ID.  If 0 (the default), log the
908
     device ID.  This feature (when set to 1) is provided for backwards
909 19 jeremybenn
     compatibility with an old version of VAPI.
910
 
911
`vapi_log_file = "FILENAME"'
912
     Use `filename' as the file for logged data is logging is enabled
913 82 jeremybenn
     (see `log_enabled' above).  The default is `"vapi.log"'.  For
914 19 jeremybenn
     backwards compatibility, the alternative name `vapi_log_fn' is
915
     supported for this parameter, but deprecated.
916
 
917
 
918

919
File: or1ksim.info,  Node: CUC Configuration,  Prev: Verification API Configuration,  Up: Simulator Configuration
920
 
921
3.2.3 Custom Unit Compiler (CUC) Configuration
922
----------------------------------------------
923
 
924
The Custom Unit Compiler (CUC) was a project by Marko Mlinar to generate
925 82 jeremybenn
Verilog from ANSI C functions.  The project seems to not have progressed
926
beyond the initial prototype phase.  The configuration parameters are
927 19 jeremybenn
described here for the record.
928
 
929 82 jeremybenn
CUC configuration is described in `section cuc'.  This section may
930
appear at most once.  The following parameters may be specified.
931 19 jeremybenn
 
932
`memory_order = none|weak|strong|exact'
933
     This parameter specifies the memory ordering required:
934
 
935
    `memory_order=none'
936
          Different memory ordering, even if there are dependencies.
937
          Bursts can be made, width can change.
938
 
939 82 jeremybenn
          Different memory ordering, even if there are dependencies.  If
940 19 jeremybenn
          dependencies cannot occur, then bursts can be made, width can
941
          change.
942
 
943 82 jeremybenn
          Same memory ordering.  Bursts can be made, width can change.
944 19 jeremybenn
 
945
          Exactly the same memory ordering and widths.
946
 
947
 
948 82 jeremybenn
     The default value is `memory_order=exact'.  Invalid memory
949 19 jeremybenn
     orderings are ignored with a warning.
950
 
951
`calling_convention = 0|1'
952 82 jeremybenn
     If 1 (true), programs follow OpenRISC calling conventions.  If 0
953 19 jeremybenn
     (the default), they may use other convenitions.
954
 
955
`enable_bursts = 0 | 1'
956 82 jeremybenn
     If 1 (true), bursts are detected.  If 0 (the default), bursts are
957 19 jeremybenn
     not detected.
958
 
959
`no_multicycle = 0 | 1'
960 82 jeremybenn
     If 1 (true), no multicycle logic paths will be generated.  If 0
961
     (the default), multicycle logic paths will be generated.
962 19 jeremybenn
 
963
`timings_file = "FILENAME"'
964 82 jeremybenn
     FILENAME specifies a file containing timing information.  The
965
     default value is `"virtex.tim"'.  For backwards compatibility, the
966 19 jeremybenn
     alternative name `timings_fn' is supported for this parameter, but
967
     deprecated.
968
 
969
 
970

971
File: or1ksim.info,  Node: Core OpenRISC Configuration,  Next: Peripheral Configuration,  Prev: Simulator Configuration,  Up: Configuration
972
 
973
3.3 Configuring the OpenRISC Architectural Components
974
=====================================================
975
 
976
* Menu:
977
 
978
* CPU Configuration::
979
* Memory Configuration::
980
* Memory Management Configuration::
981
* Cache Configuration::
982
* Interrupt Configuration::
983
* Power Management Configuration::
984
* Branch Prediction Configuration::
985
* Debug Interface Configuration::
986
 
987

988
File: or1ksim.info,  Node: CPU Configuration,  Next: Memory Configuration,  Up: Core OpenRISC Configuration
989
 
990
3.3.1 CPU Configuration
991
-----------------------
992
 
993 82 jeremybenn
CPU configuration is described in `section cpu'.  This section should
994
appear only once.  At present Or1ksim does not model multi-CPU systems.
995 19 jeremybenn
The following parameters may be specified.
996
 
997
`ver = VALUE'
998
 
999
`cfg = VALUE'
1000
 
1001
`rev = VALUE'
1002
     The values are used to form the corresponding fields in the `VR'
1003 82 jeremybenn
     Special Purpose Register (SPR 0).  Default values 0.  A warning is
1004 19 jeremybenn
     given and the value truncated if it is too large (8 bits for `ver'
1005
     and `cfg', 6 bits for `rev').
1006
 
1007
`upr = VALUE'
1008
     Used as the value of the Unit Present Register (UPR) Special
1009 82 jeremybenn
     Purpose Register (SPR 1) to VALUE.  Default value is 0x0000075f,
1010 19 jeremybenn
     i.e.
1011
        * UPR present (0x00000001)
1012
 
1013
        * Data cache present (0x00000002)
1014
 
1015
        * Instruction cache present (0x00000004)
1016
 
1017
        * Data MMY present (0x00000008)
1018
 
1019
        * Instruction MMU present (0x00000010)
1020
 
1021
        * Debug unit present (0x00000040)
1022
 
1023
        * Power management unit present (0x00000100)
1024
 
1025
        * Programmable interrupt controller present (0x00000200)
1026
 
1027
        * Tick timer present (0x00000400)
1028
 
1029
     However, with the exection of the UPR present (0x00000001) and tick
1030
     timer present, the various fields will be modified with the values
1031
     specified in their corresponding configuration sections.
1032
 
1033
`cfgr = VALUE'
1034
     Sets the CPU configuration register (Special Purpose Register 2) to
1035 82 jeremybenn
     VALUE.  Default value is 0x00000020, i.e.  support for the ORBIS32
1036
     instruction set.  Attempts to set any other value are accepted, but
1037 19 jeremybenn
     issue a warning that there is no support for the instruction set.
1038
 
1039
`sr = VALUE'
1040
     Sets the supervision register Special Purpose Register (SPR 0x11)
1041 82 jeremybenn
     to VALUE.  Default value is 0x00008001, i.e.  start in supervision
1042 19 jeremybenn
     mode (0x00000001) and set the "Fixed One" bit (0x00008000).
1043
 
1044 98 jeremybenn
          Note: This is particularly useful when an image is held in
1045
          Flash at high memory (0xf0000000).  The EPH  bit can be set,
1046
          so that interrupt vectors are basedf at 0xf0000000, rather
1047
          than 0x0.
1048
 
1049 19 jeremybenn
`superscalar = 0|1'
1050 82 jeremybenn
     If 1, the processor operates in superscalar mode.  Default value is
1051 19 jeremybenn
     0.
1052
 
1053
     In the current simulator, the only functional effect of superscalar
1054
     mode is to affect the calculation of the number of cycles taken to
1055
     execute an instruction.
1056
 
1057
          Caution: The code for this does not appear to be complete or
1058
          well tested, so users are advised not to use this option.
1059
 
1060
`hazards = 0|1'
1061 82 jeremybenn
     If 1, data hazards are tracked in a superscalar CPU.  Default
1062
     value is 0.
1063 19 jeremybenn
 
1064
     In the current simulator, the only functional effect is to cause
1065
     logging of hazard waiting information if the CPU is superscalar.
1066
     However nowhere in the simulator is this data actually computed,
1067
     so the net result is probably to have no effect.
1068
 
1069
     if harzards are tracked, current hazards can be displayed using the
1070
     simulator's `r' command.
1071
 
1072
          Caution: The code for this does not appear to be complete or
1073
          well tested, so users are advised not to use this option.
1074
 
1075
`dependstats = 0|1'
1076 82 jeremybenn
     If 1, inter-instruction dependencies are calculated.  Default
1077
     value 0.
1078 19 jeremybenn
 
1079
     If these values are calculated, the depencies can be displayed
1080
     using the simulator's `stat' command.
1081
 
1082
          Note: This field must be enabled, if execution execution flow
1083
          tracking (field `history') has been requested in the simulator
1084
          configuration section (*note Simulator Behavior: Simulator
1085
          Behavior.).
1086
 
1087
`sbuf_len = VALUE'
1088
     The length of the store buffer is set to VALUE, which must be no
1089 82 jeremybenn
     greater than 256.  Larger values will be truncated to 256 with a
1090
     warning.  Negative values will be treated as 0 with a warning.
1091
     Use 0 to disable the store buffer.
1092 19 jeremybenn
 
1093
     When the store buffer is active, stores are accumulated and
1094
     committed when I/O is idle.
1095
 
1096 100 julius
`hardfloat = 0|1'
1097
     If 1, hardfloat instructions are enabled. Default value 0.
1098 19 jeremybenn
 
1099

1100
File: or1ksim.info,  Node: Memory Configuration,  Next: Memory Management Configuration,  Prev: CPU Configuration,  Up: Core OpenRISC Configuration
1101
 
1102
3.3.2 Memory Configuration
1103
--------------------------
1104
 
1105 82 jeremybenn
Memory configuration is described in `section memory'.  This section
1106 98 jeremybenn
may appear multiple times, specifying multiple blocks of memory.
1107 19 jeremybenn
 
1108 98 jeremybenn
     Caution: The user may choose whether or not to enable a memory
1109
     controller. If a memory controller is enabled, then the standard
1110
     OpenRISC C libraries will initialize it to expect 64MB memory
1111
     blocks, and any memory declarations _must_ reflect this.  The
1112
     section describing memory controller configuration describes the
1113
     steps necessary for using smaller or larger memory sections (*note
1114
     Memory Controller Configuration: Memory Controller Configuration.).
1115
 
1116
     If a memory controller is _not_ enabled, then the standard C
1117
     library code will generate memory access errors.  The solution is
1118
     to declare an additional writable memory block, mimicing the memory
1119
     controller's register bank as follows.
1120
 
1121
          section memory
1122
            pattern = 0x00
1123
            type = unknown
1124
            name = "MC shadow"
1125
            baseaddr = 0x93000000
1126
            size     = 0x00000080
1127
            delayr = 2
1128
            delayw = 4
1129
          end
1130
 
1131
 
1132
The following parameters may be specified.
1133
 
1134 19 jeremybenn
`type=random|pattern|unknown|zero'
1135 82 jeremybenn
     Specifies the values to which memory should be initialized.  The
1136 19 jeremybenn
     default value is `unknown'.
1137
 
1138
    `random'
1139 82 jeremybenn
          Set the memory values to be a random value.  A seed for the
1140 19 jeremybenn
          random generator may be set using the `random_seed' field in
1141
          this section (see below), thus ensuring the same "random"
1142
          values are used each time.
1143
 
1144
    `pattern'
1145
          Set the memory values to be a pattern value, which is set
1146
          using the `pattern' field in this section (see below).
1147
 
1148
    `unknown'
1149 82 jeremybenn
          The memory values are not initialized (i.e.  left "unknown").
1150 19 jeremybenn
          This option will yield faster initialization of the simulator.
1151
 
1152
    `zero'
1153 82 jeremybenn
          Set the memory values to be 0.  This is the equivalent of
1154 19 jeremybenn
          `type=pattern' and a `pattern' value of 0, and implemented as
1155
          such.
1156
 
1157
               Note: As a consequence, if the `pattern' field is
1158
               _subsequently_ specified in this section, the value in
1159
               that field will be used instead of zero to initialize
1160
               the memory.
1161
 
1162
 
1163
`random_seed = VALUE'
1164 82 jeremybenn
     Set the seed for the random number generator to VALUE.  This only
1165 19 jeremybenn
     has any effect for memory type `random'.
1166
 
1167
     The default value is -1, which means the seed will be set from a
1168
     call to the `time' function, thus ensuring different random values
1169 82 jeremybenn
     are used on each run.  The simulator prints out the seed used in
1170 19 jeremybenn
     this case, allowing repeat runs to regenerate the same random
1171
     values used in any particular run.
1172
 
1173
`pattern = VALUE'
1174 82 jeremybenn
     Set the pattern to be used when initializing memory to VALUE.  The
1175
     default value is 0.  This only has any effect for memory type
1176
     `pattern'.  The least significant 8 bits of this value is used to
1177
     initialize each byte.  More than 8 bits can be specified, but will
1178 19 jeremybenn
     ignored with a warning.
1179
 
1180
          Tip: The default value, is equivalent to setting the memory
1181 82 jeremybenn
          `type' to be `zero'.  If that is what is intended, then using
1182 19 jeremybenn
          `type=zero' explicitly is better than using `type=pattern'
1183
          and not specifying a value for `pattern'.
1184
 
1185
`baseaddr = VALUE'
1186 82 jeremybenn
     Set the base address of the memory to VALUE.  It should be aligned
1187 19 jeremybenn
     to a multiple of the memory size rounded up to the nearest 2^n.
1188
     The default value is 0.
1189
 
1190
`size = VALUE'
1191 82 jeremybenn
     Set the size of the memory block to be VALUE bytes.  This should
1192
     be a multiple of 4 (i.e.  word aligned).  The default value is
1193
     1024.
1194 19 jeremybenn
 
1195
          Note: When allocating memory, the simulator will allocate the
1196
          nearest 2^n bytes greater than or equal to VALUE, and will not
1197
          notice memory misses in any part of the memory between VALUE
1198
          and the amount allocated.
1199
 
1200
          As a consequence users are strongly recommended to specify
1201 82 jeremybenn
          memory sizes that are an exact power of 2.  If some other
1202 19 jeremybenn
          amount of memory is required, it should be specified as
1203
          separate, contiguous blocks, each of which is a power of 2 in
1204
          size.
1205
 
1206
`name = "TEXT"'
1207 82 jeremybenn
     Name the block.  Typically these describe the type of memory being
1208
     modeled (thus `"SRAM"' or `"Flash"'.  The default is
1209 19 jeremybenn
     `"anonymous memory block"'.
1210
 
1211
          Note: It is not clear that this information is currently ever
1212 82 jeremybenn
          used in normal operation of the simulator.  Even the `info'
1213 19 jeremybenn
          command of the simulator ignores it.
1214
 
1215
`ce = VALUE'
1216 82 jeremybenn
     Set the chip enable index of the memory instance.  Each memory
1217 19 jeremybenn
     instance should have a unique chip enable index, which should be
1218 82 jeremybenn
     greater than or equal to zero.  This is used by the memory
1219 19 jeremybenn
     controller when identifying different memory instances.
1220
 
1221 98 jeremybenn
     There is no requirement to set  `ce' if a memory controller is not
1222
     enabled. The default value is -1 (invalid).
1223 19 jeremybenn
 
1224
`mc = VALUE'
1225 82 jeremybenn
     Specifies the memory controller this memory is connected to.  It
1226 19 jeremybenn
     should correspond to the `index' field specified in a `section mc'
1227
     for a memory controller (*note Memory Controller Configuration:
1228
     Memory Controller Configuration.).
1229
 
1230 98 jeremybenn
     There is no requirement to set  `mc' if a memory controller is not
1231
     enabled. Default value is 0, which is also the default value of a
1232
     memory controller `index' field.  This is suitable therefore for
1233
     designs with just one memory controller.
1234 19 jeremybenn
 
1235
`delayr = VALUE'
1236 82 jeremybenn
     The number of cycles required for a read access.  Set to -1 if the
1237
     memory does not support reading.  Default value 1.  The simulator
1238 19 jeremybenn
     will add this number of cycles to the total instruction cycle
1239
     count when reading from main memory.
1240
 
1241
`delayw = VALUE'
1242 82 jeremybenn
     The number of cycles required for a write access.  Set to -1 if the
1243
     memory does not support writing.  Default value 1.  The simulator
1244 19 jeremybenn
     will add this number of cycles to the total instruction cycle
1245
     count when writing to main memory.
1246
 
1247
`log = "FILE"'
1248
     If specified, `file' names a file for all memory accesses to be
1249 82 jeremybenn
     logged.  If not specified, the default value, NULL is used, meaning
1250 19 jeremybenn
     that the memory is not logged.
1251
 
1252
 
1253

1254
File: or1ksim.info,  Node: Memory Management Configuration,  Next: Cache Configuration,  Prev: Memory Configuration,  Up: Core OpenRISC Configuration
1255
 
1256
3.3.3 Memory Management Configuration
1257
-------------------------------------
1258
 
1259
Memory Management Unit (MMU) configuration is described in `section
1260
dmmu' (for the data MMU) and `section immu' (for the instruction MMU).
1261 82 jeremybenn
Each section should appear at most once.  The following parameters may
1262 19 jeremybenn
be specified.
1263
 
1264
`enabled = 0|1'
1265
     If 1 (true), the data or instruction (as appropriate) MMU is
1266 82 jeremybenn
     enabled.  If 0 (the default), it is disabled.
1267 19 jeremybenn
 
1268
`nsets = VALUE'
1269
     Sets the number of data or instruction (as appropriate) TLB sets to
1270 82 jeremybenn
     VALUE, which must be a power of two, not exceeding 128.  Values
1271
     which do not fit these criteria are ignored with a warning.  The
1272 19 jeremybenn
     default value is 1.
1273
 
1274
`nways = VALUE'
1275
     Sets the number of data or instruction (as appropriate) TLB ways to
1276 82 jeremybenn
     VALUE.  The value must be in the range 1 to 4.  Values outside
1277
     this range are ignored with a warning.  The default value is 1.
1278 19 jeremybenn
 
1279
`pagesize = VALUE'
1280
     The data or instruction (as appropriate) MMU page size is set to
1281 82 jeremybenn
     VALUE, which must be a power of 2.  Values which are not a power
1282
     of 2 are ignored with a warning.  The default is 8192 (0x2000).
1283 19 jeremybenn
 
1284
`entrysize = VALUE'
1285
     The data or instruction (as appropriate) MMU entry size is set to
1286 82 jeremybenn
     VALUE, which must be a power of 2.  Values which are not a power
1287
     of 2 are ignored with a warning.  The default value is 1.
1288 19 jeremybenn
 
1289
          Note: Or1ksim does not appear to use the `entrysize' parameter
1290 82 jeremybenn
          in its simulation of the MMUs.  Thus setting this value does
1291 19 jeremybenn
          not seem to matter.
1292
 
1293
`ustates = VALUE'
1294
     The number of instruction usage states for the data or instruction
1295
     (as appropriate) MMU is set to VALUE, which must be 2, 3 or 4.
1296 82 jeremybenn
     Values outside this range are ignored with a warning.  The default
1297 19 jeremybenn
     value is 2.
1298
 
1299
          Note: Or1ksim does not appear to use the `ustates' parameter
1300 82 jeremybenn
          in its simulation of the MMUs.  Thus setting this value does
1301 19 jeremybenn
          not seem to matter.
1302
 
1303
`hitdelay = VALUE'
1304
     Set the number of cycles a data or instruction (as appropriate) MMU
1305 82 jeremybenn
     hit costs.  Default value 1.
1306 19 jeremybenn
 
1307
`missdelay = VALUE'
1308
     Set the number of cycles a data or instruction (as appropriate) MMU
1309 82 jeremybenn
     miss costs.  Default value 1.
1310 19 jeremybenn
 
1311
 
1312

1313
File: or1ksim.info,  Node: Cache Configuration,  Next: Interrupt Configuration,  Prev: Memory Management Configuration,  Up: Core OpenRISC Configuration
1314
 
1315
3.3.4 Cache Configuration
1316
-------------------------
1317
 
1318
Cache configuration is described in `section dc' (for the data cache)
1319 82 jeremybenn
and `seciton ic' (for the instruction cache).  Each section should
1320
appear at most once.  The following parameters may be specified.
1321 19 jeremybenn
 
1322
`enabled = 0|1'
1323
     If 1 (true), the data or instruction (as appropriate) cache is
1324 82 jeremybenn
     enabled.  If 0 (the default), it is disabled.
1325 19 jeremybenn
 
1326
`nsets = VALUE'
1327
     Sets the number of data or instruction (as appropriate) cache sets
1328
     to VALUE, which must be a power of two, not exceeding
1329
     `MAX_DC_SETS' (for the data cache) or `MAX_IC_SETS' (for the
1330 82 jeremybenn
     instruction cache).  At the time of writing, these constants are
1331
     both defined in the code to be 1024).  The default value is 1.
1332 19 jeremybenn
 
1333
`nways = VALUE'
1334
     Sets the number of data or instruction (as appropriate) cache ways
1335
     to VALUE, which must be a power of two, not exceeding
1336
     `MAX_DC_WAYS' (for the data cache) or `MAX_IC_WAYS' (for the
1337 82 jeremybenn
     instruction cache).  At the time of writing, these constants are
1338
     both defined in the code to be 32).  The default value is 1.
1339 19 jeremybenn
 
1340
`blocksize = VALUE'
1341
     The data or instruction (as appropriate) cache block size is set to
1342 82 jeremybenn
     VALUE bytes, which must be either 16 or 32.  The default is 16.
1343 19 jeremybenn
 
1344
`ustates = VALUE'
1345
     The number of instruction usage states for the data or instruction
1346
     (as appropriate) cache is set to VALUE, which must be 2, 3 or 4.
1347
     The default value is 2.
1348
 
1349
`hitdelay = VALUE'
1350 82 jeremybenn
     _Instruction cache only_.  Set the number of cycles an instruction
1351
     cache hit costs.  Default value 1.
1352 19 jeremybenn
 
1353
`missdelay = VALUE'
1354 82 jeremybenn
     _Instruction cache only_.  Set the number of cycles an instruction
1355
     cache miss costs.  Default value 1.
1356 19 jeremybenn
 
1357
`load_hitdelay = VALUE'
1358 82 jeremybenn
     _Data cache only_.  Set the number of cycles a data load cache hit
1359
     costs.  Default value 2.
1360 19 jeremybenn
 
1361
`load_missdelay = VALUE'
1362 82 jeremybenn
     _Data cache only_.  Set the number of cycles a data load cache
1363
     miss costs.  Default value 2.
1364 19 jeremybenn
 
1365
`store_hitdelay = VALUE'
1366 82 jeremybenn
     _Data cache only_.  Set the number of cycles a data store cache hit
1367
     costs.  Default value 0.
1368 19 jeremybenn
 
1369
`store_missdelay = VALUE'
1370 82 jeremybenn
     _Data cache only_.  Set the number of cycles a data store cache
1371
     miss costs.  Default value 0.
1372 19 jeremybenn
 
1373
 
1374

1375
File: or1ksim.info,  Node: Interrupt Configuration,  Next: Power Management Configuration,  Prev: Cache Configuration,  Up: Core OpenRISC Configuration
1376
 
1377
3.3.5 Interrupt Configuration
1378
-----------------------------
1379
 
1380
Programmable Interrupt Controller (PIC) configuration is described in
1381 82 jeremybenn
`section pic'.  This section may appear at most once--Or1ksim has no
1382
mechanism for handling multiple interrupt controllers.  The following
1383 19 jeremybenn
parameters may be specified.
1384
 
1385
`enabled = 0|1'
1386 82 jeremybenn
     If 1 (true), the programmable interrupt controller is enabled.  If
1387
 
1388 19 jeremybenn
 
1389
`edge_trigger = 0|1'
1390
     If 1 (true, the default), the programmable interrupt controller is
1391 82 jeremybenn
     edge triggered.  If 0 (false), it is level triggered.
1392 19 jeremybenn
 
1393
 
1394

1395
File: or1ksim.info,  Node: Power Management Configuration,  Next: Branch Prediction Configuration,  Prev: Interrupt Configuration,  Up: Core OpenRISC Configuration
1396
 
1397
3.3.6 Power Management Configuration
1398
------------------------------------
1399
 
1400 82 jeremybenn
Power management implementation is incomplete.  At present the effect
1401 19 jeremybenn
(which only happens when the power management unit is enabled) of
1402
setting the different bits in the power management Special Purpose
1403
Register (PMR, SPR 0x4000) is
1404
 
1405
`SDF (bit mask 0x0000000f)'
1406
     No effect - these bits are ignored
1407
 
1408
`DME (bit mask 0x00000010)'
1409
`SME (bit mask 0x00000020)'
1410
     Both these bits cause the processor to stop executing
1411 82 jeremybenn
     instructions.  However all other functions (debug interaction, CLI,
1412 19 jeremybenn
     VAPI etc) carry on as normal.
1413
 
1414
`DCGE (bit mask 0x00000004)'
1415
     No effect - this bit is ignored
1416
 
1417
`SUME (bit mask 0x00000008)'
1418
     Enabling this bit causes a message to be printed, advising that the
1419
     processor is suspending and the simulator exits.
1420
 
1421
 
1422
On reset all bits are cleared.
1423
 
1424 82 jeremybenn
Power management configuration is described in `section pm'.  This
1425
section may appear at most once.  The following parameter may be
1426 19 jeremybenn
specified.
1427
 
1428
`enabled = 0|1'
1429 82 jeremybenn
     If 1 (true), power management is enabled.  If 0 (the default), it
1430
     is disabled.
1431 19 jeremybenn
 
1432
 
1433

1434
File: or1ksim.info,  Node: Branch Prediction Configuration,  Next: Debug Interface Configuration,  Prev: Power Management Configuration,  Up: Core OpenRISC Configuration
1435
 
1436
3.3.7 Branch Prediction Configuration
1437
-------------------------------------
1438
 
1439
From examining the code base, it seems the branch prediction function
1440 82 jeremybenn
is not fully implemented.  At present the functionality seems
1441
restricted to collection of statistics.
1442 19 jeremybenn
 
1443 82 jeremybenn
Branch prediction configuration is described in `section bpb'.  This
1444
section may appear at most once.  The following parameters may be
1445 19 jeremybenn
specified.
1446
 
1447
`enabled = 0|1'
1448 82 jeremybenn
     If 1 (true), branch prediction is enabled.  If 0 (the default), it
1449 19 jeremybenn
     is disabled.
1450
 
1451
`btic = 0|1'
1452
     If 1 (true), the branch target instruction cache model is enabled.
1453
     If 0 (the default), it is disabled.
1454
 
1455
`sbp_bf_fwd = 0|1'
1456 82 jeremybenn
     If 1 (true), use forward prediction for the `l.bf' instruction.  If
1457 19 jeremybenn
 
1458
     instruction.
1459
 
1460
`sbp_bnf_fwd = 0|1'
1461 82 jeremybenn
     If 1 (true), use forward prediction for the `l.bnf' instruction.
1462
     If 0 (the default), do not use forward prediction for this
1463 19 jeremybenn
     instruction.
1464
 
1465
`hitdelay = VALUE'
1466 82 jeremybenn
     Set the number of cycles a branch prediction hit costs.  Default
1467 19 jeremybenn
     value 0.
1468
 
1469
`missdelay = VALUE'
1470 82 jeremybenn
     Set the number of cycles a branch prediction miss costs.  Default
1471 19 jeremybenn
     value 0.
1472
 
1473
 
1474

1475
File: or1ksim.info,  Node: Debug Interface Configuration,  Prev: Branch Prediction Configuration,  Up: Core OpenRISC Configuration
1476
 
1477
3.3.8 Debug Interface Configuration
1478
-----------------------------------
1479
 
1480
The debug unit and debug interface configuration is described in
1481 82 jeremybenn
`section debug'.  This section may appear at most once.  The following
1482 19 jeremybenn
parameters may be specified.
1483
 
1484
`enabled = 0|1'
1485 82 jeremybenn
     If 1 (true), the debug unit is enabled.  If 0 (the default), it is
1486 19 jeremybenn
     disabled.
1487
 
1488
          Note: This enables the functionality of the debug unit (its
1489 82 jeremybenn
          registers etc) within the mode.  It does not provide any
1490
          external interface to the debug unit.  For that, see
1491 19 jeremybenn
          `gdb_enabled' and `rsp_enabled' below.
1492
 
1493
`rsp_enabled = 0|1'
1494
     If 1 (true), the GDB "Remote Serial Protocol" server is started,
1495
     provding an interface to an external GNU debugger, using the port
1496
     specified in the `rsp_port' field (see below), or the
1497 82 jeremybenn
     `or1ksim-rsp' TCP/IP service.  If 0 (the default), the server is
1498 19 jeremybenn
     not started, and no external interface is provided.
1499
 
1500
     For more detailed information on the interface to the GNU Debugger
1501
     see Embecosm Application Note 2, `Howto: Porting the GNU Debugger
1502
     Practical Experience with the OpenRISC 1000 Architecture', by
1503
     Jeremy Bennett, published by Embecosm Limited (`www.embecosm.com').
1504
 
1505 82 jeremybenn
          Note: `rsp_enabled' may not be enabled with `gdb_enabled' (see
1506
          below).  If both are enabled, a warning is issued and only
1507
          the "Remote Serial Protocol" interface is enabled.
1508 19 jeremybenn
 
1509
`rsp_port = VALUE'
1510
     VALUE specifies the port to be used for the GDB "Remote Serial
1511 82 jeremybenn
     Protocol" interface to the GNU Debugger (GDB).  Default value
1512
     51000.  If the value 0 is specified, Or1ksim will instead look for
1513 19 jeremybenn
     a TCP/IP service named `or1ksim-rsp'.
1514
 
1515
          Tip: There is no registered port for Or1ksim "Remote Serial
1516 82 jeremybenn
          Protocol" service `or1ksim-rsp'.  Good practice suggests
1517
          users should adopt port values in the "Dynamic" or "Private"
1518
          port range, i.e.  49152-65535.
1519 19 jeremybenn
 
1520
`gdb_enabled = 0|1'
1521
     If 1 (true), the OpenRISC Remote JTAG protocol server is started,
1522
     provding an interface to an external GNU debugger, using the port
1523
     specified in the `server_port' field (see below), or the `or1ksim'
1524 82 jeremybenn
     TCP/IP service.  If 0 (the default), the server is not started,
1525
     and no external interface is provided.
1526 19 jeremybenn
 
1527
     For more detailed information on the interface to the GNU Debugger
1528
     see Embecosm Application Note 2, `Howto: Porting the GNU Debugger
1529
     Practical Experience with the OpenRISC 1000 Architecture', by
1530
     Jeremy Bennett, published by Embecosm Limited (`www.embecosm.com').
1531
 
1532
          Note: The OpenRISC Remote JTAG protocol is unique to
1533 82 jeremybenn
          OpenRISC, and remains only for backward compatibility.  New
1534 19 jeremybenn
          users should adopt the standard GDB "Remote Serial Protocol"
1535
          interface (see `rsp_enabled' above) providing access to a
1536
          wider range of GDB functionality.
1537
 
1538 82 jeremybenn
          Note: `gdb_enabled' may not be enabled with `rsp_enabled'.
1539
          If both are enabled, a warning is issued and only the "Remote
1540 19 jeremybenn
          Serial Protocol" interface is enabled.
1541
 
1542
`server_port = VALUE'
1543
     VALUE specifies the port to be used for the OpenRISC Rmote JTAG
1544 82 jeremybenn
     protocol interface to the GNU Debugger (GDB).  Default value
1545
     51000.  If the value 0 is specified, Or1ksim will instead look for
1546
     a TCP/IP service named `or1ksim'.
1547 19 jeremybenn
 
1548
          Tip: There is no registered port for Or1ksim Remote JTAG
1549 82 jeremybenn
          Interface or service `or1ksim'.  Good practice suggests users
1550 19 jeremybenn
          should adopt port values in the "Dynamic" or "Private" port
1551 82 jeremybenn
          range, i.e.  49152-65535.
1552 19 jeremybenn
 
1553
`vapi_id = VALUE'
1554
     VALUE specifies the value of the Verification API (VAPI) base
1555 82 jeremybenn
     address to be used with the debug unit.  *Note Verification API:
1556 19 jeremybenn
     Verification API, for more details.
1557
 
1558
     If this is specified and VALUE is non-zero, all OpenRISC Remote
1559
     JTAG protocol transactions will be logged to the VAPI log file, if
1560 82 jeremybenn
     enabled.  This is the only functionality associated with VAPI for
1561
     the debug unit.  No VAPI commands are sent, nor requests handled.
1562 19 jeremybenn
 
1563
 
1564

1565
File: or1ksim.info,  Node: Peripheral Configuration,  Prev: Core OpenRISC Configuration,  Up: Configuration
1566
 
1567
3.4 Configuring Memory Mapped Peripherals
1568
=========================================
1569
 
1570 82 jeremybenn
All peripheral components are optional.  If they are specified, then
1571 19 jeremybenn
(unlike other components) by default they are enabled.
1572
 
1573
* Menu:
1574
 
1575
* Memory Controller Configuration::
1576
* UART Configuration::
1577
* DMA Configuration::
1578
* Ethernet Configuration::
1579
* GPIO Configuration::
1580
* Display Interface Configuration::
1581
* Frame Buffer Configuration::
1582
* Keyboard Configuration::
1583
* Disc Interface Configuration::
1584
* Generic Peripheral Configuration::
1585
 
1586

1587
File: or1ksim.info,  Node: Memory Controller Configuration,  Next: UART Configuration,  Up: Peripheral Configuration
1588
 
1589
3.4.1 Memory Controller Configuration
1590
-------------------------------------
1591
 
1592
The memory controller used in Or1ksim is the component implemented at
1593 98 jeremybenn
OpenCores, and found in the top level SVN directory, `mem_ctrl'.  It is
1594 19 jeremybenn
described in the document `Memory Controller IP Core' by Rudolf
1595 82 jeremybenn
Usselmann, which can be found in the `doc' subdirectory.  It is a
1596
memory mapped component, which resides on the main OpenRISC Wishbone
1597
data bus.
1598 19 jeremybenn
 
1599 82 jeremybenn
The memory controller configuration is described in `section mc'.  This
1600 19 jeremybenn
section may appear multiple times, specifying multiple memory
1601 98 jeremybenn
controllers.
1602 19 jeremybenn
 
1603 98 jeremybenn
     Caution: The standard OpenRISC C libraries will initialize the
1604
     memory controller to expect 64MB memory blocks, and any memory
1605
     declarations _must_ reflect this.
1606
 
1607
     If smaller memory blocks are declared with a memory controller,
1608
     then sufficient memory will not be allocated by Or1ksim, but out of
1609
     range memory accesses will not be trapped. For example declaring a
1610
     memory section from 0-4MB with a memory controller enabled would
1611
     mean that accesses between 4MB and 64MB would be permitted, but
1612
     having no allocated memory would likely cause a segmentation fault.
1613
 
1614
     If the user is determined to use smaller memories with the memory
1615
     controller, then custom initialization code must be provided, to
1616
     ensure the memory controller traps out-of-memory accesses.
1617
 
1618
The following parameters may be specified.
1619
 
1620 19 jeremybenn
`enabled = 0|1'
1621 82 jeremybenn
     If 1 (true, the default), this memory controller is enabled.  If
1622
     0, it is disabled.
1623 19 jeremybenn
 
1624
          Note: The memory controller can effectively also be disabled
1625
          by setting an appropriate power on control register value
1626 82 jeremybenn
          (see below).  However this should only be used if it is
1627 19 jeremybenn
          desired to specifically model this behavior of the memory
1628
          controller, not as a way of disabling the memory controller
1629
          in general.
1630
 
1631
`baseaddr = VALUE'
1632
     Set the base address of the memory controller's memory mapped
1633 82 jeremybenn
     registers to VALUE.  The default is 0, which is probably not a
1634 19 jeremybenn
     sensible value.
1635
 
1636
     The memory controller has a 7 bit address bus, with a total of 19
1637
     32-bit registers, at addresses 0x00 through 0x4c (address 0x0c and
1638
     addresses 0x50 through 0x7c are not used).
1639
 
1640
`poc = VALUE'
1641
     Specifies the value of the power on control register, The least
1642
     signficant two bits specify the bus width (use 0 for an 8-bit bus,
1643
     1 for a 16-bit bus and 2 for a 32-bit bus) and the next two bits
1644
     the type of memory connected (use 0 for a disabled interface, 1
1645
     for SSRAM, 2 for asyncrhonous devices and 3 for synchronous
1646
     devices).
1647
 
1648
     If other bits are specified, they are ignored with a warning.
1649
 
1650
          Caution: The default value, 0, corresponds to a disabled
1651
          8-bit bus, and is likely not the most suitable value
1652
 
1653
`index = VALUE'
1654
     Specify the index of this memory controller amongst all the memory
1655 82 jeremybenn
     controllers.  This value should be unique for each memory
1656 19 jeremybenn
     controller, and is used to associate specific memories with the
1657
     controller, through the `mc' field in the `section memory'
1658
     configuration (*note Memory Configuration: Memory Configuration.).
1659
 
1660
     The default value, 0, is suitable when there is only one memory
1661
     controller.
1662
 
1663
 
1664

1665
File: or1ksim.info,  Node: UART Configuration,  Next: DMA Configuration,  Prev: Memory Controller Configuration,  Up: Peripheral Configuration
1666
 
1667
3.4.2 UART Configuration
1668
------------------------
1669
 
1670
The UART implemented in Or1ksim follows the specification of the
1671 82 jeremybenn
National Semiconductor 16450 and 16550 parts.  It is a memory mapped
1672 19 jeremybenn
component, which resides on the main OpenRISC Wishbone data bus.
1673
 
1674
The component provides a number of interfaces to emulate the behavior
1675
of an external terminal connected to the UART.
1676
 
1677 82 jeremybenn
UART configuration is described in `section uart'.  This section may
1678
appear multiple times, specifying multiple UARTs.  The following
1679 19 jeremybenn
parameters may be specified.
1680
 
1681
`enabled = 0|1'
1682 82 jeremybenn
     If 1 (true, the default), this UART is enabled.  If 0, it is
1683 19 jeremybenn
     disabled.
1684
 
1685
`baseaddr = VALUE'
1686
     Set the base address of the UART's memory mapped registers to
1687 82 jeremybenn
     VALUE.  The default is 0, which is probably not a sensible value.
1688 19 jeremybenn
 
1689
     The UART has a 3 bit address bus, with a total of 8 8-bit
1690
     registers, at addresses 0x0 through 0x7.
1691
 
1692
`channel = "TYPE:ARGS"'
1693
     Specify the channel representing the terminal connected to the UART
1694
     Rx & Tx pins.
1695
 
1696
    `channel="file:`rxfile',`txfile'"'
1697
          Read input characters from the file `rxfile' and write output
1698
          characters to the file `txfile' (which will be created if
1699
          required).
1700
 
1701
    `channel="xterm:ARGS"'
1702
          Create an xterm on startup, write UART Tx traffic to the
1703
          xterm and take Rx traffic from the keyboard when the xterm
1704 82 jeremybenn
          window is selected.  Additional arguments to the xterm
1705
          command (for example specifying window size may be specified
1706
          in ARGS, or this may be left blank.
1707 19 jeremybenn
 
1708
    `channel="tcp:VALUE"'
1709
          Open the TCP/IP port specified by VALUE and read and write
1710
          UART traffic from and to it.
1711
 
1712
          Typically a telnet session is connected to the other end of
1713
          this port.
1714
 
1715
               Tip: There is no registered port for Or1ksim telnet UART
1716 82 jeremybenn
               connection.  Priviledged access is required to read
1717 19 jeremybenn
               traffic on the registered "well-known" telnet port (23).
1718
               Instead users should use port values in the "Dynamic" or
1719 82 jeremybenn
               "Private" port range, i.e.  49152-65535.
1720 19 jeremybenn
 
1721
    `channel="fd:`rxfd',`txfd'"'
1722
          Read and write characters from and to the existing open
1723
          numerical file descriptors, file `rxfd' and `txfd'.
1724
 
1725
    `channel="tty:device=/dev/ttyS0,baud=9600"'
1726
          Read and write characters from and to a physical serial port.
1727
          The precise device (shown here as `/dev/ttyS0') may vary from
1728
          machine to machine.
1729
 
1730
 
1731
     The default value for this field is `"xterm:"'.
1732
 
1733
`irq = VALUE'
1734 82 jeremybenn
     Use VALUE as the IRQ number of this UART.  Default value 0.
1735 19 jeremybenn
 
1736
`16550 = 0|1'
1737 82 jeremybenn
     If 1 (true), the UART has the functionality of a 16550.  If 0 (the
1738
     default), it has the functionality of a 16450.  The principal
1739 19 jeremybenn
     difference is that the 16550 can buffer multiple characters.
1740
 
1741
`jitter = VALUE'
1742
     Set the jitter, modeled as a time to block, to VALUE milliseconds.
1743 82 jeremybenn
     Set to -1 to disable jitter modeling.  Default value 0.
1744 19 jeremybenn
 
1745
          Note: This functionality has yet to be implemented, so this
1746
          parameter has no effect.
1747
 
1748
`vapi_id = VALUE'
1749
     VALUE specifies the value of the Verification API (VAPI) base
1750 82 jeremybenn
     address to be used with the UART.  *Note Verification API:
1751 19 jeremybenn
     Verification API, for more details, which details the use of the
1752
     VAPI with the UART.
1753
 
1754
 
1755

1756
File: or1ksim.info,  Node: DMA Configuration,  Next: Ethernet Configuration,  Prev: UART Configuration,  Up: Peripheral Configuration
1757
 
1758
3.4.3 DMA Configuration
1759
-----------------------
1760
 
1761
The DMA controller used in Or1ksim is the component implemented at
1762 98 jeremybenn
OpenCores, and found in the top level SVN directory, `wb_dma'.  It is
1763 19 jeremybenn
described in the document `Wishbone DMA/Bridge IP Core' by Rudolf
1764 82 jeremybenn
Usselmann, which can be found in the `doc' subdirectory.  It is a
1765
memory mapped component, which resides on the main OpenRISC Wishbone
1766
data bus.  The present implementation is incomplete, intended only to
1767
support the Ethernet interface (*note Ethernet Configuration::),
1768
although the Ethernet interface is not yet completed.
1769 19 jeremybenn
 
1770 82 jeremybenn
DMA configuration is described in `section dma'.  This section may
1771
appear multiple times, specifying multiple DMA controllers.  The
1772 19 jeremybenn
following parameters may be specified.
1773
 
1774
`enabled = 0|1'
1775 82 jeremybenn
     If 1 (true, the default), this DMA controller is enabled.  If 0,
1776
     it is disabled.
1777 19 jeremybenn
 
1778
`baseaddr = VALUE'
1779
     Set the base address of the DMA's memory mapped registers to
1780 82 jeremybenn
     VALUE.  The default is 0, which is probably not a sensible value.
1781 19 jeremybenn
 
1782
     The DMA controller has a 10 bit address bus, with a total of 253
1783 82 jeremybenn
     32-bit registers.  The first 5 registers at addresses 0x000 through
1784
     0x010 control the overall behavior of the DMA controller.  There
1785
     are then 31 blocks of 8 registers, controlling each of the 31 DMA
1786
     channels available.  Addresses 0x014 through 0x01c are not used.
1787 19 jeremybenn
 
1788
`irq = VALUE'
1789 82 jeremybenn
     Use VALUE as the IRQ number of this DMA controller.  Default value
1790 19 jeremybenn
     0.
1791
 
1792
`vapi_id = VALUE'
1793
     VALUE specifies the value of the Verification API (VAPI) base
1794 82 jeremybenn
     address to be used with the DMA controller.  *Note Verification
1795 19 jeremybenn
     API: Verification API, for more details, which details the use of
1796
     the VAPI with the DMA controller.
1797
 
1798
 
1799

1800
File: or1ksim.info,  Node: Ethernet Configuration,  Next: GPIO Configuration,  Prev: DMA Configuration,  Up: Peripheral Configuration
1801
 
1802
3.4.4 Ethernet Configuration
1803
----------------------------
1804
 
1805
The Ethernet MAC used in Or1ksim is the component implemented at
1806 98 jeremybenn
OpenCores, and found in the top level SVN directory, `ethmac'.  It also
1807
forms part of the OpenRISC SoC, ORPSoC.  It is described in the
1808 19 jeremybenn
document `Ethernet IP Core Specification' by Igor Mohor, which can be
1809 82 jeremybenn
found in the `doc' subdirectory.  It is a memory mapped component,
1810
which resides on the main OpenRISC Wishbone data bus.
1811 19 jeremybenn
 
1812 82 jeremybenn
Ethernet configuration is described in `section ethernet'.  This
1813
section may appear multiple times, specifying multiple Ethernet
1814
interfaces.  The following parameters may be specified.
1815 19 jeremybenn
 
1816
`enabled = 0|1'
1817 82 jeremybenn
     If 1 (true, the default), this Ethernet MAC is enabled.  If 0, it
1818
     is disabled.
1819 19 jeremybenn
 
1820
`baseaddr = VALUE'
1821
     Set the base address of the MAC's memory mapped registers to
1822 82 jeremybenn
     VALUE.  The default is 0, which is probably not a sensible value.
1823 19 jeremybenn
 
1824
     The Ethernet MAC has a 7-bit address bus, with a total of 21
1825 82 jeremybenn
     32-bit registers.  Addresses 0x54 through 0x7c are not used.
1826 19 jeremybenn
 
1827
          Note: The Ethernet specification describes a Tx control
1828 82 jeremybenn
          register, `TXCTRL', at address 0x50.  However this register
1829
          is not implemented in the Or1ksim model.
1830 19 jeremybenn
 
1831
`dma = VALUE'
1832
     VALUE specifies the DMA controller with which this Ethernet is
1833 82 jeremybenn
     associated.  The default value is 0.
1834 19 jeremybenn
 
1835
          Note: Support for external DMA is not provided in the current
1836 82 jeremybenn
          implementation, and this value is ignored.  In any case there
1837 19 jeremybenn
          is no equivalent field to which this can be matched in the
1838
          current DMA component implementation (*note DMA
1839
          Configuration: DMA Configuration.).
1840
 
1841
`irq = VALUE'
1842 82 jeremybenn
     Use VALUE as the IRQ number of this Ethernet MAC.  Default value 0.
1843 19 jeremybenn
 
1844
`rtx_type = 0|1'
1845
     If 1 (true) use a socket interface to the Ethernet (see parameter
1846 82 jeremybenn
     `sockif' below).  If 0 (the default), use a file interface,
1847
     reading and writing from and to the files specified in the
1848
     `rxfile' and `txfile' parameters (see below).
1849 19 jeremybenn
 
1850
          Note: By default the socket interface is not provided in
1851 82 jeremybenn
          Or1ksim.  If it is required, this must be requested when
1852 19 jeremybenn
          configuring, by use of the `--enable-ethphy' option to
1853
          `configure'.
1854
 
1855
               configure --target=or32-uclinux --enable-ethphy ...
1856
 
1857
`rx_channel = RXVALUE'
1858
`tx_channel = TXVALUE'
1859
     RXVALUE specifies the DMA channel to use for receive and TXVALUE
1860 82 jeremybenn
     the DMA channel to use for transmit.  Both default to 0.
1861 19 jeremybenn
 
1862
          Note: As noted above, support for external DMA is not
1863
          provided in the current implementation, and so these values
1864
          are ignored.
1865
 
1866
`rxfile = "RXFILE"'
1867
`txfile = "TXFILE"'
1868
     When `rtx_type' is 0 (see above), RXFILE specifies the file to use
1869
     as input and TXFILE specifies the fie to use as output.
1870
 
1871 82 jeremybenn
     The file contains a sequence of packets.  Each packet consists of a
1872
     packet length (32 bits), followed by that many bytes of data.
1873
     Once the input file is empty, the Ethernet MAC behaves as though
1874
     there were no data on the Ethernet.  The default values of these
1875 19 jeremybenn
     parameters are `"eth_rx"' and `"eth_tx"' respectively.
1876
 
1877 82 jeremybenn
     The input file must exist and be readable.  The output file must be
1878
     writable and will be created if necessary.  If either of these
1879 19 jeremybenn
     conditions is not met, a warning will be given.
1880
 
1881
`sockif = "SERVICE"'
1882
     When `rtx_type' is 1 (see above), SERVICE specifies the service to
1883 82 jeremybenn
     use for communication.  This may be TCP/IP or UDP/IP.  The default
1884 19 jeremybenn
     value of this parameter is `"or1ksim_eth"'.
1885
 
1886
`vapi_id = VALUE'
1887
     VALUE specifies the value of the Verification API (VAPI) base
1888 82 jeremybenn
     address to be used with the Ethernet PHY.  *Note Verification API:
1889 19 jeremybenn
     Verification API, for more details, which details the use of the
1890
     VAPI with the DMA controller.
1891
 
1892
 
1893

1894
File: or1ksim.info,  Node: GPIO Configuration,  Next: Display Interface Configuration,  Prev: Ethernet Configuration,  Up: Peripheral Configuration
1895
 
1896
3.4.5 GPIO Configuration
1897
------------------------
1898
 
1899
The GPIO used in Or1ksim is the component implemented at OpenCores, and
1900 98 jeremybenn
found in the top level SVN directory, `gpio'.  It is described in the
1901 19 jeremybenn
document `GPIO IP Core Specification' by Damjan Lampret and Goran
1902 82 jeremybenn
Djakovic, which can be found in the `doc' subdirectory.  It is a memory
1903 19 jeremybenn
mapped component, which resides on the main OpenRISC Wishbone data bus.
1904
 
1905 82 jeremybenn
GPIO configuration is described in `section gpio'.  This section may
1906
appear multiple times, specifying multiple GPIO devices.  The following
1907 19 jeremybenn
parameters may be specified.
1908
 
1909
`enabled = 0|1'
1910 82 jeremybenn
     If 1 (true, the default), this GPIO is enabled.  If 0, it is
1911 19 jeremybenn
     disabled.
1912
 
1913
`baseaddr = VALUE'
1914
     Set the base address of the GPIO's memory mapped registers to
1915 82 jeremybenn
     VALUE.  The default is 0, which is probably not a sensible value.
1916 19 jeremybenn
 
1917
     The GPIO has a 6 bit address bus, with a total of 10 32-bit
1918
     registers, although the number of bits that are actively used
1919 82 jeremybenn
     varies.  Addresses 0x28 through 0x3c are not used.
1920 19 jeremybenn
 
1921
`irq = VALUE'
1922 82 jeremybenn
     Use VALUE as the IRQ number of this GPIO.  Default value 0.
1923 19 jeremybenn
 
1924
`vapi_id = VALUE'
1925
     VALUE specifies the value of the Verification API (VAPI) base
1926 82 jeremybenn
     address to be used with the GPIO.  *Note Verification API:
1927 19 jeremybenn
     Verification API, for more details, which details the use of the
1928 82 jeremybenn
     VAPI with the GPIO controller.  For backwards compatibility, the
1929 19 jeremybenn
     alternative name `base_vapi_id' is supported for this parameter,
1930
     but deprecated.
1931
 
1932
 
1933

1934
File: or1ksim.info,  Node: Display Interface Configuration,  Next: Frame Buffer Configuration,  Prev: GPIO Configuration,  Up: Peripheral Configuration
1935
 
1936
3.4.6 Display Interface Configuration
1937
-------------------------------------
1938
 
1939
Or1ksim models a VGA interface to an external monitor.  The VGA
1940
controller used in Or1ksim is the component implemented at OpenCores,
1941 98 jeremybenn
and found in the top level SVN directory, `vga_lcd', with no support
1942 82 jeremybenn
for the optional hardware cursors.  It is described in the document
1943 19 jeremybenn
`VGA/LCD Core v2.0 Specifications' by Richard Herveille, which can be
1944 82 jeremybenn
found in the `doc' subdirectory.  It is a memory mapped component,
1945
which resides on the main OpenRISC Wishbone data bus.
1946 19 jeremybenn
 
1947
The current implementation provides only functionality to dump the
1948
screen to a file at intervals.
1949
 
1950 82 jeremybenn
VGA controller configuration is described in `section vga'.  This
1951 19 jeremybenn
section may appear multiple times, specifying multiple VGA controllers.
1952
The following parameters may be specified.
1953
 
1954
`enabled = 0|1'
1955 82 jeremybenn
     If 1 (true, the default), this VGA is enabled.  If 0, it is
1956 19 jeremybenn
     disabled.
1957
 
1958
`baseaddr = VALUE'
1959
     Set the base address of the VGA controller's memory mapped
1960 82 jeremybenn
     registers to VALUE.  The default is 0, which is probably not a
1961 19 jeremybenn
     sensible value.
1962
 
1963
     The VGA controller has a 12-bit address bus, with 7 32-bit
1964
     registers, at addresses 0x000 through 0x018, and two color lookup
1965 82 jeremybenn
     tables at addresses 0x800 through 0xfff.  The hardware cursor
1966 19 jeremybenn
     registers are not implemented, so addresses 0x01c through 0x7fc
1967
     are not used.
1968
 
1969
`irq = VALUE'
1970 82 jeremybenn
     Use VALUE as the IRQ number of this VGA controller.  Default value
1971 19 jeremybenn
     0.
1972
 
1973
`refresh_rate = VALUE'
1974 82 jeremybenn
     VALUE specifies number of cycles between screen dumps.  Default
1975 19 jeremybenn
     value is derived from the simulation clock cycle time (*note
1976
     Simulator Behavior: Simulator Behavior.), to correspond to dumping
1977
     50 times per simulated second.
1978
 
1979
`txfile = "FILE"'
1980
     FILE specifies the base of the filename for screen dumps.
1981
     Successive screen dumps will be in BMP format, in files with the
1982
     name `FILENNNN.bmp', where NNNN is a sequential count of the
1983 82 jeremybenn
     screen dumps starting at zero.  The default value is `"vga_out"'.
1984 19 jeremybenn
     For backwards compatibility, the alternative name `filename' is
1985
     supported for this parameter, but deprecated.
1986
 
1987
 
1988

1989
File: or1ksim.info,  Node: Frame Buffer Configuration,  Next: Keyboard Configuration,  Prev: Display Interface Configuration,  Up: Peripheral Configuration
1990
 
1991
3.4.7 Frame Buffer Configuration
1992
--------------------------------
1993
 
1994 82 jeremybenn
     Caution: The frame buffer is only partially implemented.  Its
1995 19 jeremybenn
     configuration fields are described here, but the component should
1996 82 jeremybenn
     not be used at this time.  Like the VGA controller, it is designed
1997 19 jeremybenn
     to make screen dumps to file.
1998
 
1999 82 jeremybenn
Frame buffer configuration is described in `section fb'.  This section
2000
may appear multiple times, specifying multiple frame buffers.  The
2001 19 jeremybenn
following parameters may be specified.
2002
 
2003
`enabled = 0|1'
2004 82 jeremybenn
     If 1 (true, the default), this frame buffer is enabled.  If 0, it
2005 19 jeremybenn
     is disabled.
2006
 
2007
`baseaddr = VALUE'
2008
     Set the base address of the frame buffer's memory mapped registers
2009 82 jeremybenn
     to VALUE.  The default is 0, which is probably not a sensible
2010
     value.
2011 19 jeremybenn
 
2012
     The frame buffer has an 121-bit address bus, with 4 32-bit
2013
     registers, at addresses 0x000 through 0x00c, and a PAL lookup
2014 82 jeremybenn
     table at addresses 0x400 through 0x4ff.  Addresses 0x010 through
2015 19 jeremybenn
     0x3fc and addresses 0x500 through 0x7ff are not used.
2016
 
2017
`refresh_rate = VALUE'
2018 82 jeremybenn
     VALUE specifies number of cycles between screen dumps.  Default
2019 19 jeremybenn
     value is derived from the simulation clock cycle time (*note
2020
     Simulator Behavior: Simulator Behavior.), to correspond to dumping
2021
     50 times per simulated second.
2022
 
2023
`txfile = "FILE"'
2024
     FILE specifies the base of the filename for screen dumps.
2025
     Successive screen dumps will be in BMP format, in files with the
2026
     name `FILENNNN.bmp', where NNNN is a sequential count of the
2027 82 jeremybenn
     screen dumps starting at zero.  The default value is `"fb_out"'.
2028 19 jeremybenn
     For backwards compatibility, the alternative name `filename' is
2029
     supported for this parameter, but deprecated.
2030
 
2031
 
2032

2033
File: or1ksim.info,  Node: Keyboard Configuration,  Next: Disc Interface Configuration,  Prev: Frame Buffer Configuration,  Up: Peripheral Configuration
2034
 
2035
3.4.8 Keyboard Configuration (PS2)
2036
----------------------------------
2037
 
2038 82 jeremybenn
The PS2 interface provided by Or1ksim is not documented.  It may be
2039 98 jeremybenn
based on the PS2 project at OpenCores, and found in the top level SVN
2040 82 jeremybenn
directory, `ps2'.  However this project lacks any documentation beyond
2041
its project webpage.  Since most PS2 interfaces follow the Intel i8042
2042 19 jeremybenn
standard, this is presumably what is expected with this device.
2043
 
2044
The implementation only provides for keyboard support, which is
2045 82 jeremybenn
modelled as a file of keystrokes.  There is no mouse support.
2046 19 jeremybenn
 
2047
     Caution: A standard i8042 device has two registers at addresses
2048 82 jeremybenn
     0x60 (command) and 0x64 (status).  Inspection of the code,
2049
     suggests that the Or1ksim component places these registers at
2050
     addresses 0x00 and 0x04.
2051 19 jeremybenn
 
2052
     The port of Linux for the OpenRISC 1000, which runs on Or1ksim
2053
     implements the i8042 device driver, anticipating these registers
2054 82 jeremybenn
     reside at their conventional address.  It seems unlikel that this
2055 19 jeremybenn
     code will work.
2056
 
2057
     This component should be used with caution.
2058
 
2059 82 jeremybenn
Keyboard configuration is described in `section kbd'.  This section may
2060
appear multiple times, specifying multiple keyboard interfaces.  The
2061 19 jeremybenn
following parameters may be specified.
2062
 
2063
`enabled = 0|1'
2064 82 jeremybenn
     If 1 (true, the default), this keyboard is enabled.  If 0, it is
2065 19 jeremybenn
     disabled.
2066
 
2067
`baseaddr = VALUE'
2068
     Set the base address of the keyboard's memory mapped registers to
2069 82 jeremybenn
     VALUE.  The default is 0, which is probably not a sensible value.
2070 19 jeremybenn
 
2071
     The keyboard PS/2 interface has an 3-bit address bus, with 2 8-bit
2072
     registers, at addresses 0x000 and 0x004.
2073
 
2074
          Caution: As noted above, a standard Intel 8042 interface
2075
          would expect to find these registers at locations 0x60 and
2076
          0x64, thus requiring at least a 7-bit bus.
2077
 
2078
`irq = VALUE'
2079 82 jeremybenn
     Use VALUE as the IRQ number of this Keyboard interface.  Default
2080 19 jeremybenn
     value 0.
2081
 
2082
`rxfile = "FILE"'
2083
     `file' specifies a file containing raw key stroke data, which
2084 82 jeremybenn
     models the input from a physical keyboard.  The default value is
2085 19 jeremybenn
     `"kbd_in"'.
2086
 
2087
 
2088

2089
File: or1ksim.info,  Node: Disc Interface Configuration,  Next: Generic Peripheral Configuration,  Prev: Keyboard Configuration,  Up: Peripheral Configuration
2090
 
2091
3.4.9 Disc Interface Configuration
2092
----------------------------------
2093
 
2094
The ATA/ATAPI disc controller used in Or1ksim is the OCIDEC (OpenCores
2095
IDE Controller) component implemented at OpenCores, and found in the
2096 98 jeremybenn
top level SVN directory, `ata'.  It is described in the document
2097 19 jeremybenn
`ATA/ATAPI-5 Core Specification' by Richard Herveille, which can be
2098 82 jeremybenn
found in the `doc' subdirectory.  It is a memory mapped component,
2099
which resides on the main OpenRISC Wishbone data bus.
2100 19 jeremybenn
 
2101 82 jeremybenn
ATA/ATAPI configuration is described in `section ata'.  This section
2102
may appear multiple times, specifying multiple disc controllers.  The
2103 19 jeremybenn
following parameters may be specified.
2104
 
2105
`enabled = 0|1'
2106 82 jeremybenn
     If 1 (true, the default), this ATA/ATAPI interface is enabled.  If
2107 19 jeremybenn
     0, it is disabled.
2108
 
2109
`baseaddr = VALUE'
2110
     Set the base address of the ATA/ATAPI interface's memory mapped
2111 82 jeremybenn
     registers to VALUE.  The default is 0, which is probably not a
2112 19 jeremybenn
     sensible value.
2113
 
2114
     The ATA/ATAPI PS/2 interface has an 5-bit address bus, with 8
2115 82 jeremybenn
     32-bit registers.  Depending on the version of the OCIDEC
2116
     ATA/ATAPI interface selected (see `dev_id' below), not all
2117
     registers will be available.
2118 19 jeremybenn
 
2119
`irq = VALUE'
2120 82 jeremybenn
     Use VALUE as the IRQ number of this ATA/ATAPI interface.  Default
2121 19 jeremybenn
     value 0.
2122
 
2123
`dev_id = 1|2|3'
2124
     This parameter specifies which version of the OCIDEC ATA/ATAPI
2125 82 jeremybenn
     interface to model.  The default value is 1.
2126 19 jeremybenn
 
2127
     Version 1 supports only the `CTRL', `STAT' and `PCTR' registers.
2128
     Versions 2 & 3 add the `FCTR' registers, Version 3 adds the `DTR'
2129
     registers and the `RXD'/`TXD' registers.
2130
 
2131
`rev = VALUE'
2132
     Set the VALUE as the revision of the OCIDEC ATA/ATAPI interface.
2133 82 jeremybenn
     The default value is 1.  The default value is 0.  Its value should
2134
     be in the range 0-15.  Larger values are truncated with a warning.
2135 19 jeremybenn
     This only affects the reset value of the `STAT' register, where it
2136
     forms bits 24-27.
2137
 
2138
`pio_mode0_t1 = VALUE'
2139
`pio_mode0_t2 = VALUE'
2140
`pio_mode0_t4 = VALUE'
2141
`pio_mode0_teoc = VALUE'
2142
     These parameters specify the timings for use with Programmed
2143 82 jeremybenn
     Input/Output (PIO) transfers.  They are specified as the number of
2144 19 jeremybenn
     clock cycles - 2, rounded up to the next highest integer, or zero
2145 82 jeremybenn
     if that would be negative.  The values should not exceed 255.  If
2146 19 jeremybenn
     they do, they will be ignored with a warning.
2147
 
2148
     See the ATA/ATAPI-5 specification for explanations of each of these
2149 82 jeremybenn
     timing parameters.  The default values are:
2150 19 jeremybenn
 
2151
          pio_mode0_t1   =  6
2152
          pio_mode0_t2   = 28
2153
          pio_mode0_t4   =  2
2154
          pio_mode0_teoc = 23
2155
 
2156
`dma_mode0_tm = VALUE'
2157
`dma_mode0_td = VALUE'
2158
`dma_mode0_teoc = VALUE'
2159
     These parameters specify the timings for use with DMA transfers.
2160
     They are specified as the number of clock cycles - 2, rounded up
2161
     to the next highest integer, or zero if that would be negative.
2162 82 jeremybenn
     The values should not exceed 255.  If they do, they will be
2163
     ignored with a warning.
2164 19 jeremybenn
 
2165
     See the ATA/ATAPI-5 specification for explanations of each of these
2166 82 jeremybenn
     timing parameters.  The default values are:
2167 19 jeremybenn
 
2168
          dma_mode0_tm   =  4
2169
          dma_mode0_td   = 21
2170
          dma_mode0_teoc = 21
2171
 
2172
 
2173
3.4.9.1 ATA/ATAPI Device Configuration
2174
......................................
2175
 
2176 82 jeremybenn
Within the `section ata', each device is specified separately.  The
2177 19 jeremybenn
device subsection is introduced by
2178
 
2179
     device VALUE
2180
 
2181 82 jeremybenn
VALUE is the device number, which should be 0 or 1.  The subsection
2182
ends with `enddevice'.  Note that if the same device number is
2183
specified more than once, the previous values will be overwritten.
2184
Within the `device' subsection, the following parameters may appear:
2185 19 jeremybenn
 
2186
`type = VALUE'
2187
     VALUEspecifies the type of device: 0 (the default) for "not
2188
     connected", 1 for hard disk simulated in a file and 2 for local
2189
     system hard disk.
2190
 
2191
`file = "FILENAME"'
2192
     `filename' specifies the file to be used for a simulated ATA
2193 82 jeremybenn
     device if the file type (see `type' above) is 1.  Default value
2194 19 jeremybenn
     `"ata-FileN"', where N is the device number.
2195
 
2196
`size = VALUE'
2197
     VALUE specifies the size of a simulated ATA device if the file
2198 82 jeremybenn
     type (see `type' above) is 1.  The default value is zero.
2199 19 jeremybenn
 
2200
`packet = 0|1'
2201 82 jeremybenn
     If 1 (true), implement the PACKET command feature set.  If 0 (the
2202 19 jeremybenn
     default), do not implement the PACKET command feature set.
2203
 
2204
`firmware = "STR"'
2205
     Firmware to report in response to the "Identify Device" command.
2206
     Default `"02207031"'.
2207
 
2208
`heads = VALUE'
2209 82 jeremybenn
     Number of heads in the device.  Default 7, use -1 to disable all
2210 19 jeremybenn
     heads.
2211
 
2212
`sectors = VALUE'
2213 82 jeremybenn
     Number of sectors per track in the device.  Default 32.
2214 19 jeremybenn
 
2215
`mwdma = 0|1|2|-1'
2216 82 jeremybenn
     Highest multi-word DMA mode supported.  Default 2, use -1 to
2217 19 jeremybenn
     disable.
2218
 
2219
`pio = 0|1|2|3|4'
2220 82 jeremybenn
     Highest PIO mode supported.  Default 4.
2221 19 jeremybenn
 
2222
 
2223

2224
File: or1ksim.info,  Node: Generic Peripheral Configuration,  Prev: Disc Interface Configuration,  Up: Peripheral Configuration
2225
 
2226
3.4.10 Generic Peripheral Configuration
2227
---------------------------------------
2228
 
2229
When used as a library (*note Simulator Library: Simulator Library.),
2230
Or1ksim makes provision for any additional peripheral to be implemented
2231 82 jeremybenn
externally.  Any read or write access to this peripheral's memory map
2232
generates "upcall"s to an external handler.  This interface can support
2233 19 jeremybenn
either C or C++, and was particularly designed to facilitate support
2234
for OSCI SystemC (see `http://www.systemc.org').
2235
 
2236
Generic peripheral configuration is described in `section generic'.
2237
This section may appear multiple times, specifying multiple external
2238 82 jeremybenn
peripherals.  The following parameters may be specified.
2239 19 jeremybenn
 
2240
`enabled = 0|1'
2241 82 jeremybenn
     If 1 (true, the default), this ATA/ATAPI interface is enabled.  If
2242 19 jeremybenn
     0, it is disabled.
2243
 
2244
`baseaddr = VALUE'
2245
     Set the base address of the generic peripheral's memory mapped
2246 82 jeremybenn
     registers to VALUE.  The default is 0, which is probably not a
2247 19 jeremybenn
     sensible value.
2248
 
2249
     The size of the memory mapped register space is controlled by the
2250
     `size' paramter, described below.
2251
 
2252
`size = VALUE'
2253
     Set the size of the generic peripheral's memory mapped register
2254 82 jeremybenn
     space to VALUE bytes.  Any read or write accesses to addresses with
2255 19 jeremybenn
     offsets of 0 to VALUE-1 bytes from the base address specified in
2256
     parameter `baseaddr' (see above) will be directed to the external
2257
     interface.
2258
 
2259 82 jeremybenn
     VALUE will be rounded up the nearest power of 2.  It's default
2260
     value is zero.  If VALUE is not an exact power of two, accesses to
2261 19 jeremybenn
     address offsets of VALUE or above up to the next power of 2 will
2262
     generate a warning, and have no effect (reads will return zero).
2263
 
2264
`name = "STR"'
2265 82 jeremybenn
     This gives the peripheral the name `"STR"'.  This is used to
2266 19 jeremybenn
     identify the peripheral in error messages and warnings, and when
2267 82 jeremybenn
     reporting its status.  The default value is
2268 19 jeremybenn
     `"anonymous external peripheral"'.
2269
 
2270
`byte_enabled = 0|1'
2271
`hw_enabled = 0|1'
2272
`word_enabled = 0|1'
2273
     If 1 (true, the default), these parameters respectively enable the
2274 82 jeremybenn
     device for byte wide, half-word wide and word wide accesses.  If 0,
2275 19 jeremybenn
     accesses of that width will fail.
2276
 
2277
 
2278

2279
File: or1ksim.info,  Node: Interactive Command Line,  Next: Verification API,  Prev: Configuration,  Up: Top
2280
 
2281
4 Interactive Command Line
2282
**************************
2283
 
2284
If started with the `-f' flag, or if interrupted with `ctrl-C', Or1ksim
2285 82 jeremybenn
provides the user with an interactive command line.  The commands
2286 19 jeremybenn
available, which may not be abbreviated, are:
2287
 
2288
`q'
2289
     Exit the simulator
2290
 
2291
`r'
2292 82 jeremybenn
     Display all the General Purpose Registers (GPRs).  Also shows the
2293 19 jeremybenn
     just executed and next to be executed instructions symbolically
2294
     and the state of the flag in the Supervision Register.
2295
 
2296
`t'
2297
     Execute the next instruction and then display register/instruction
2298
     information as with the `r' command (see above).
2299
 
2300
`run NUM [ hush ]'
2301 82 jeremybenn
     Execute NUM instructions.  The register/instruction information is
2302 19 jeremybenn
     displayed after each instruction, as with the `r' command (see
2303
     above) _unless_ `hush' is specified.
2304
 
2305
`pr REG VALUE'
2306
     Patch register REG with VALUE.
2307
 
2308
`dm FROMADDR [ TOADDR ]'
2309 82 jeremybenn
     Display memory bytes between FROMADDR and TOADDR.  If TOADDR is
2310
     not given, 64 bytes are displayed, starting at FROMADDR.
2311 19 jeremybenn
 
2312
          Caution: The output from this command is broken (a bug).
2313 82 jeremybenn
          Or1ksim attempts to print out 16 bytes per row.  However,
2314 19 jeremybenn
          instead of printing out the address at the start of each row,
2315
          it prints the address (of the first of the 16 bytes) before
2316
          _each_ byte.
2317
 
2318
`de FROMADDR [ TOADDR ]'
2319 82 jeremybenn
     Disassemble code between FROMADDR and TOADDR.  If TOADDR is not
2320 19 jeremybenn
     given, 16 instructions are disassembled.
2321
 
2322
     The disassembly is entirely numerical, and gives no symbolic
2323
     information.
2324
 
2325
`pm ADDR VALUE'
2326
     Patch the 4 bytes in memory starting at ADDR with the 32-bit VALUE.
2327
 
2328
`pc VALUE'
2329
     Patch the program counter with VALUE.
2330
 
2331
`cm FROMADDR TOADDR SIZE'
2332
     Copy SIZE bytes in memory from FROMADDR to TOADDR.
2333
 
2334
`break ADDR'
2335
     Toggle the breakpoint set at ADDR.
2336
 
2337
`breaks'
2338
     List all set breakpoints
2339
 
2340
`reset'
2341 82 jeremybenn
     Reset the simulator.  Includes modeling a reset of the processor,
2342
     so execution will restart from the reset vector location, 0x100.
2343 19 jeremybenn
 
2344
`hist'
2345
     If saving the execution history has been configured (*note
2346
     Simulator Behavior: Simulator Behavior.), display the execution
2347
     history.
2348
 
2349
`stall'
2350
     Stall the processor, so that control is passed to the debug unit.
2351 82 jeremybenn
     When stalled, the processor can execute no instructions.  This
2352 19 jeremybenn
     command is useful when debugging the JTAG interface, used by
2353
     debuggers such as GDB.
2354
 
2355
`unstall'
2356 82 jeremybenn
     Unstall the processor, so that normal execution can continue.
2357
     This command is useful when debugging the JTAG interface, used by
2358 19 jeremybenn
     debuggers such as GDB.
2359
 
2360
`stats CATEGORY | clear'
2361
     Print the statistics for the given CATEGORY, if available, or
2362 82 jeremybenn
     clear if `clear' is specified.  The categories are:
2363 19 jeremybenn
 
2364
    1
2365
          Miscellaneous statistics: branch predictions (if branch
2366
          predictions are enabled), branch target cache model (if
2367
          enabled), cache (if enbaled), MMU (if enabled) and number of
2368
          addtional load & store cycles.
2369
 
2370
          *Note Configuring the OpenRisc Achitectural Components: Core
2371
          OpenRISC Configuration, for details of how to enable these
2372
          various features.
2373
 
2374
    2
2375 82 jeremybenn
          Instruction usage statistics.  Requires hazard analysis to be
2376 19 jeremybenn
          enabled (*note CPU Configuration: CPU Configuration.).
2377
 
2378
    3
2379 82 jeremybenn
          Instruction dependency statistics.  Requires hazard analysis
2380 19 jeremybenn
          to be enabled (*note CPU Configuration: CPU Configuration.).
2381
 
2382
    4
2383 82 jeremybenn
          Functional unit dependency statistics.  Requires hazard
2384 19 jeremybenn
          analysis to be enabled (*note CPU Configuration: CPU
2385
          Configuration.).
2386
 
2387
    5
2388 82 jeremybenn
          Raw register usage over time.  Requires hazard analysis to be
2389 19 jeremybenn
          enabled (*note CPU Configuration: CPU Configuration.).
2390
 
2391
    6
2392 82 jeremybenn
          Store buffer statistics.  Requires the store buffer to be
2393 19 jeremybenn
          enabled (*note CPU Configuration: CPU Configuration.).
2394
 
2395
 
2396
`info'
2397
     Display detailed information about the simulator configuration.
2398
     This is quite a lengthy about, because all MMU TLB information is
2399
     displayed.
2400
 
2401
`dv FROMADDR [ TOADDR ] [ MODULE ]'
2402
     Dump the area of memory between FROMADDR and TOADDR as Verilog
2403 82 jeremybenn
     code for a synchronous, 23-bit wide SRAM module, named MODULE.  If
2404 19 jeremybenn
     TOADDR is not specified, then 64 bytes are dumped (as 16 32-bit
2405 82 jeremybenn
     words).  If MODULE is not specified, `or1k_mem' is used.
2406 19 jeremybenn
 
2407
     To save to a file, use the redirection function (described after
2408
     this table, below).
2409
 
2410
`dh FROMADDR [ TOADDR ]'
2411
     Dump the area of memory between FROMADDR and TOADDR as 32-bit hex
2412 82 jeremybenn
     numbers (no `0x', or `32'h' prefix).  If TOADDR is not specified,
2413 19 jeremybenn
     then 64 bytes are dumped (as 16 32-bit words).
2414
 
2415
     To save to a file, use the redirection function (described after
2416
     this table, below).
2417
 
2418
`setdbch'
2419 82 jeremybenn
     Toggle debug channels on/off.  *Note Standalone Simulator:
2420 19 jeremybenn
     Standalone Simulator, for a description of specifying debug
2421
     channels on the command line.
2422
 
2423
`set SECTION PARAM = VALUE'
2424
     Set the configuration parameter PARA in section SECTION to VALUE.
2425
     *Note Configuration: Configuration, for details of configuration
2426
     parameters and their settings.
2427
 
2428
`debug'
2429 82 jeremybenn
     Toggle the simulator debug mode.  *Note Debug Interface
2430 19 jeremybenn
     Configuration: Debug Interface Configuration, for information on
2431
     this parameter.
2432
 
2433
          Caution: This is effectively enabling or disabling the debug
2434 82 jeremybenn
          unit.  It does not effect the remote GDB debug interface.
2435 19 jeremybenn
          However using the remote debug interface while the debug unit
2436
          is disabled will lead to undefined behavior and likely crash
2437
          Or1ksim
2438
 
2439
`cuc'
2440
     Enter the the Custom Unit Compiler command prompt (*note CUC
2441
     Configuration: CUC Configuration.).
2442
 
2443
          Caution: The CUC must be properly configured, for this to
2444 82 jeremybenn
          succeed.  In particular a timing file must be available and
2445
          readable.  Otherwise Or1ksim will crash.
2446 19 jeremybenn
 
2447
`help'
2448
     Print out brief information about each command available.
2449
 
2450
`mprofile [-vh] [-m M] [-g N] [-f FILE] FROM TO'
2451 82 jeremybenn
     Run the memory profiling utility.  This follows the same usage as
2452 19 jeremybenn
     the standalone command (*note Memory Profiling Utility: Memory
2453
     Profiling Utility.).
2454
 
2455
`profile [-vhcq] [-g FILE]'
2456 82 jeremybenn
     Run the instruction profiling utility.  This follows the same
2457
     usage as the standalone command (*note Profiling Utility:
2458
     Profiling Utility.).
2459 19 jeremybenn
 
2460
 
2461
For all commands, it is possible to redirect the output to a file, by
2462
using the redirection operator, `>'.
2463
 
2464
     COMMAND > FILENAME
2465
 
2466
This is particularly useful for commands dumping a large amount of
2467
output, such as `dv'.
2468
 
2469
     Caution: Unfortunately there is a serious bug with the redirection
2470 82 jeremybenn
     operator.  It does not return output to standard output after the
2471
     command completes.  Until this bug is fixed, file redirection
2472 19 jeremybenn
     should not be used.
2473
 
2474

2475
File: or1ksim.info,  Node: Verification API,  Next: Code Internals,  Prev: Interactive Command Line,  Up: Top
2476
 
2477
5 Verification API (VAPI)
2478
*************************
2479
 
2480
The Verification API (VAPI) provides a TCP/IP interface to allow
2481 82 jeremybenn
components of the simulation to be controlled externally.  The
2482
interface is polled for new requests on each simulated clock cycle.
2483
Components within the simulator may send responses to such requests.
2484 19 jeremybenn
 
2485 82 jeremybenn
The inteface is an asynchronous duplex protocol.  On the request side
2486
it provides for simple commands, known as VAPI IDs (a 32 bit integer),
2487
with a single piece of data (also a 32 bit integer).  On the send side,
2488
it provides for sending a single VAPI ID and data.  However there is no
2489
explicit command-response structure.  Some components just accept
2490
requests (e.g.  to set values), some just generate sends (to report
2491 19 jeremybenn
values), and some do both.
2492
 
2493
Each component has a base ID (32 bit) and its commands will start from
2494 82 jeremybenn
that base ID.  This provides a simple partitioning of the command space
2495
amongst components.  Request commands will be directed to the component
2496 19 jeremybenn
with the closest base ID lower than the VAPI ID of the command.
2497
 
2498
Thus if there are two components with base IDs of 0x200 and 0x300, and
2499
a request with VAPI ID of 0x203 is received, it will be directed to the
2500
first component as its command #3.
2501
 
2502
The results of VAPI interactions are logged (by default in `vapi.log'
2503
unless an alternative is specified in `section vapi').
2504
 
2505
Currently the following components support VAPI:
2506
 
2507
Debug Unit
2508
     Although the Debug Unit can specify a base VAPI ID, it is not used
2509
     to send commands or receive requests.
2510
 
2511
     Instead, if the base VAPI ID is set, all remote JTAG protocol
2512
     exchanges are logged in the VAPI log file.
2513
 
2514
UART
2515
     If a base VAPI ID is specified, the UART sends details of any
2516
     chars or break characters sent, with dteails of the line control
2517
     register etc encoded in the data packet sent.
2518
 
2519
     This supports a single VAPI command request, but encodes a
2520
     sub-command in the top 8 bits of the associated data.
2521
 
2522
    `0x00'
2523
          This stuffs the least significant 8 bits of the data into the
2524
          serial register of the UART and the next 8 bits into the line
2525
          control register, effectively providing control of the next
2526
          character to be sent or received.
2527
 
2528
    `0x01'
2529
          The divisor latch bytes are set from the least significant 16
2530
          bits of the data.
2531
 
2532
    `0x02'
2533
          The line control register is set from bits 15-8 of the data.
2534
 
2535
    `0x03'
2536
          The UART skew is set from the least significant 16 bits of
2537
          the data
2538
 
2539
    `0x04'
2540
          If the 16th most significant bit of the data is 1, start
2541 82 jeremybenn
          sending breaks, otherwise stop sending breaks.  The breaks
2542
          are sent or cleared after the number of UART clock divider
2543
          ticks specified by the data (immediately if the data is zero).
2544 19 jeremybenn
 
2545
 
2546
DMA
2547
     Although the DMA unit supports a base VAPI ID in its configuration
2548
     (`section dma'), no VAPI data is sent, nor VAPI requests currently
2549
     implemented.
2550
 
2551
Ethernet
2552 82 jeremybenn
     The following requests are handled by the Ethernet.  Specified
2553 19 jeremybenn
     symbolically, these are the increments from the base VAPI ID of the
2554 82 jeremybenn
     Ethernet.  At present no implementation is provided behind these
2555 19 jeremybenn
     VAPI requests.
2556
 
2557
    `ETH_VAPI_DATA (0)'
2558
 
2559
    `ETH_VAPI_CTRL (0)'
2560
 
2561
GPIO
2562
     If a base VAPI ID is specified, the GPIO sends out on its base
2563
     VAPI ID (symbolically, GPIO_VAPI_DATA (0) offset from the base
2564
     VAPI ID) any changes in outputs.
2565
 
2566 82 jeremybenn
     The following requests are handled by the GPIO.  Specified
2567 19 jeremybenn
     symbolically, these are the increments from the VAPI base ID of the
2568
     GPIO.
2569
 
2570
    `GPIO_VAPI_DATA (0)'
2571
          Set the next input to the commands data field
2572
 
2573
    `GPIO_VAPI_AUX (1)'
2574
          Set the GPIO auxiliary inputs to the data field
2575
 
2576
    `GPIO_VAPI_CLOCK (2)'
2577
          Add an external GPIO clock trigger of period specified in the
2578
          data field.
2579
 
2580
    `GPIO_VAPI_RGPIO_OE (3)'
2581
          Set the GPIO output enable to the data field
2582
 
2583
    `GPIO_VAPI_RGPIO_INTE (4)'
2584
          Set the next interrupt to the data field
2585
 
2586
    `GPIO_VAPI_RGPIO_PTRIG (5)'
2587
          Set the next trigger to the data field
2588
 
2589
    `GPIO_VAPI_RGPIO_AUX (6)'
2590
          Set the next auxiliary input to the data field
2591
 
2592
    `GPIO_VAPI_RGPIO_CTRL (7)'
2593
          Set th next control input to the data field
2594
 
2595
 
2596
 
2597

2598
File: or1ksim.info,  Node: Code Internals,  Next: GNU Free Documentation License,  Prev: Verification API,  Up: Top
2599
 
2600
6 A Guide to Or1ksim Internals
2601
******************************
2602
 
2603 82 jeremybenn
These are notes to help those wanting to extend Or1ksim.  This section
2604 19 jeremybenn
assumes the use of a tag file, so file locations of entities'
2605 82 jeremybenn
definitions are not in general provided.  For more on tags, see the
2606
Linux manual page for `etags'.  A tag file can be created with:
2607 19 jeremybenn
 
2608
     make tags
2609
 
2610
* Menu:
2611
 
2612
* Coding Conventions::
2613
* Global Data Structures::
2614
* Concepts::
2615
* Internal Debugging::
2616
 
2617

2618
File: or1ksim.info,  Node: Coding Conventions,  Next: Global Data Structures,  Up: Code Internals
2619
 
2620
6.1 Coding Conventions for Or1ksim
2621
==================================
2622
 
2623
This chapter provides some guidelines for coding, to facilitate
2624
extensions to Or1ksim
2625
 
2626
_GNU Coding Standard_
2627
     Code should follow the GNU coding standard for C
2628 82 jeremybenn
     (`http://www.gnu.org/prep/standards/'.  If in doubt, put your code
2629 19 jeremybenn
     through the `indent' program.
2630
 
2631
_`#include' headers_
2632
     All C source code files should include `config.h' before any other
2633
     file.
2634
 
2635
     This should be followed by inclusion of any system headers (but see
2636
     the comments about portability and `port.h' below) and then by any
2637
     Or1ksim package headers.
2638
 
2639
     If `port.h' is required, it should be the first package header to
2640
     be included after the system headers.
2641
 
2642
     All C source code and header files should directly include any
2643 82 jeremybenn
     system or package header they depend on, i.e.  not rely on any
2644
     other header having already included it.  The two exceptions are
2645 19 jeremybenn
 
2646
       1. All header files may assume that `config.h' has already been
2647
          included.
2648
 
2649
       2. System headers which impose portability problems should be
2650
          included by using the package header `port.h', rather than
2651 82 jeremybenn
          the system headers themselves.  This is the case for code
2652 19 jeremybenn
          requiring
2653
 
2654
             * `strndup' (from `string.h')
2655
 
2656
             * Integer types (`intN_t', `uintN_t') (from `inttypes.h').
2657
 
2658
             * `isblank' (from `ctype.h')
2659
 
2660
 
2661
 
2662
_`#include' files once only_
2663
     All include files should be protected by `#ifndef' to ensure their
2664 82 jeremybenn
     definitions are only included once.  For instance a header file
2665 19 jeremybenn
     `X-Y.H' should surround its contents with:
2666
 
2667
          #ifndef X_Y__H
2668
          #define X_Y__H
2669
 
2670
          
2671
 
2672
          #endif  /* X_Y__H */
2673
 
2674
_Avoid `typedef'_
2675
     The GNU coding style for C does not have a clear way to distinguish
2676 82 jeremybenn
     between user type name and user variables.  For this reason
2677 19 jeremybenn
     `typedef' should be avoided except for the most ubiquitous user
2678 82 jeremybenn
     defined types.  This makes the code much easier to read.
2679 19 jeremybenn
 
2680
     There are some `typedef' declarations in the `argtable2' library
2681
     and the ELF and COFF headers, because this code is taken from
2682
     other places.
2683
 
2684
     Within Or1ksim legacy uses of `typedef' have largely been purged,
2685
     except in the Custom Unit Compiler (*note Custom Unit Compiler
2686
     (CUC) Configuration: CUC Configuration.).
2687
 
2688
     The remaining uses of `typedef' occur in two places:
2689
 
2690
        * `port/port.h' defines types to replace those in header files
2691
          that are not available (character functions, string
2692
          duplication, integer types).
2693
 
2694
          `cpu/or1k/arch.h' defines types for the key Or1ksim entities:
2695
          addresses (`oraddr_t'), unsigned register values (`uorreg_t')
2696
          and signed register (`orreg_t') values.
2697
 
2698
 
2699
     Where new types are defined, they should appear in one of these two
2700 82 jeremybenn
     files as appropriate.  Or1ksim specific types appearing in
2701
     `arch.h' should always have the suffix `_h'.
2702 19 jeremybenn
 
2703
_Don't begin names with underscore_
2704
     Names beginning with `_' are intended to be part of the C
2705 82 jeremybenn
     infrastructure.  They should not be used in the simulator code.
2706 19 jeremybenn
 
2707
_Keep Non-global top level entities static_
2708
     All top level entities (functions, variables), which are not
2709
     explicitly part of a global interface should be declared static.
2710
     This ensures that unwanted connections are not inadvertently built
2711
     across the program.
2712
 
2713
_Use of `inline'_
2714 82 jeremybenn
     Code should not be declared `inline'.  Modern compilers can work
2715 19 jeremybenn
     out for themselves what is best in this respect.
2716
 
2717
_Initialization_
2718 82 jeremybenn
     All data structures should be explicitly initialized.  In
2719
     particular code should not rely on static data structures being
2720
     initialized to zero.
2721 19 jeremybenn
 
2722
     The rationale is that in future static data structures may become
2723 82 jeremybenn
     dynamic.  This has been a particular source of bugs in Or1ksim
2724 19 jeremybenn
     historically.
2725
 
2726
     A specific case is with new peripherals, which should always
2727
     include a `start' function to pre-initialize all configuration
2728
     parameters to sensible defaults
2729
 
2730
_Configuration Validation_
2731
     All configuration values should be validated, preferably when
2732
     encountered, if not when the `section' is closed, or otherwise at
2733
     run time when the parameter is first used.
2734
 
2735
 
2736

2737
File: or1ksim.info,  Node: Global Data Structures,  Next: Concepts,  Prev: Coding Conventions,  Up: Code Internals
2738
 
2739
6.2 Global Data Structures
2740
==========================
2741
 
2742
`config'
2743
     The global variable `config' of type `struct config' holds the
2744
     configuration data for some of the Or1ksim components which are
2745 82 jeremybenn
     always present.  At present the components are:
2746 19 jeremybenn
 
2747
        * The simulator defined in `section sim' (*note Simulator
2748
          Configuration: Simulator Configuration.).
2749
 
2750
        * The Verification API (VAPI) defined  in `section vapi' (*note
2751
          Verification API (VAPI) Configuration: Verification API
2752
          Configuration.).
2753
 
2754
        * The Custom Unit Compiler (CUC), defined in `section cuc'
2755
          (*note Custom Unit Compiler (CUC) Configuration: CUC
2756
          Configuration.).
2757
 
2758
        * The CPU, defined in `section cpu' (*note CPU Configuration:
2759
          CPU Configuration.).
2760
 
2761
        * The data cache (but not the instruction cache), defined in
2762
          `section dc' (*note Cache Configuration: Cache
2763
          Configuration.).
2764
 
2765
        * The power management unit, defined in `section pm' (*note
2766
          Power Management Configuration: Power Management
2767
          Configuration.).
2768
 
2769
        * The programmable interrupt controller, defined in
2770
          `section pic' (*note Interrupt Configuration: Interrupt
2771
          Configuration.).
2772
 
2773
        * Branch prediciton, defined in `section bpb' (*note Branch
2774
          Prediction Configuration: Branch Prediction Configuration.).
2775
 
2776
        * The debug unit, defined in `section debug' (*note Debug
2777
          Interface Configuration: Debug Interface Configuration.).
2778
 
2779
 
2780
     This struct is made of a collection of structs, one for each
2781 82 jeremybenn
     component.  For example the simulator configuration is held in
2782 19 jeremybenn
     `config.sim'.
2783
 
2784
`config'
2785
     This is a linked list of data structures holding configuration data
2786
     for all sections which are not held in the main `config' data
2787 82 jeremybenn
     structure.  In general these are components (such as peripherals
2788
     and memory) which may occur multiple times.  However it also
2789
     handles some architectural components which may occur only once,
2790
     such as the memory management units, the instruction cache, the
2791
     interrupt controller and branch prediction.
2792 19 jeremybenn
 
2793
`runtime'
2794
     The global variable `runtime' of type `struct runtime' holds all
2795 82 jeremybenn
     the runtime information about the simulation.  To access this
2796 19 jeremybenn
     variable, `sim-config.h' must be included.
2797
 
2798
     This struct is itself made of 3 other structs, `cpu' (for CPU run
2799
     time state), `vapi' (for Verification API state) and `cuc' (for
2800
     Custom Unit Compiler state).
2801
 
2802
 
2803

2804
File: or1ksim.info,  Node: Concepts,  Next: Internal Debugging,  Prev: Global Data Structures,  Up: Code Internals
2805
 
2806
6.3 Concepts
2807
============
2808
 
2809
_Output Redirection_
2810 82 jeremybenn
     The current output stream is held in `runtime.cpu.fout'.  Output
2811 19 jeremybenn
     should be explicitly written to this stream, or may use the
2812
     `PRINTF' macro, which will write its arguments to this output
2813
     stream.
2814
 
2815
_Reset Hooks_
2816
     Any peripheral may register a routine to be called when the the
2817
     processor is reset by calling `reg_sim_reset', providing a
2818 82 jeremybenn
     function and pointer to a data structure as arguments.  On reset
2819 19 jeremybenn
     that function will be called with the data stucture pointer as
2820
     argument.
2821
 
2822
 
2823

2824
File: or1ksim.info,  Node: Internal Debugging,  Prev: Concepts,  Up: Code Internals
2825
 
2826
6.4 Internal Debugging
2827
======================
2828
 
2829
The function `debug' is like `printf', but with an extra first
2830 82 jeremybenn
argument, which is the debug level.  If the debug level specified in
2831
the simulator configuration (*note Simulator Behavior: Simulator
2832
Behavior.) is greater than or equal to this value, the remaining
2833
arguments are printed to the current output stream (*note Output
2834
Redirection: Output Redirection.).
2835 19 jeremybenn
 
2836

2837
File: or1ksim.info,  Node: GNU Free Documentation License,  Next: Index,  Prev: Code Internals,  Up: Top
2838
 
2839
7 GNU Free Documentation License
2840
********************************
2841
 
2842
                      Version 1.2, November 2002
2843
 
2844
     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
2845
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
2846
 
2847
     Everyone is permitted to copy and distribute verbatim copies
2848
     of this license document, but changing it is not allowed.
2849
 
2850
  0. PREAMBLE
2851
 
2852
     The purpose of this License is to make a manual, textbook, or other
2853
     functional and useful document "free" in the sense of freedom: to
2854
     assure everyone the effective freedom to copy and redistribute it,
2855
     with or without modifying it, either commercially or
2856
     noncommercially.  Secondarily, this License preserves for the
2857
     author and publisher a way to get credit for their work, while not
2858
     being considered responsible for modifications made by others.
2859
 
2860
     This License is a kind of "copyleft", which means that derivative
2861
     works of the document must themselves be free in the same sense.
2862
     It complements the GNU General Public License, which is a copyleft
2863
     license designed for free software.
2864
 
2865
     We have designed this License in order to use it for manuals for
2866
     free software, because free software needs free documentation: a
2867
     free program should come with manuals providing the same freedoms
2868
     that the software does.  But this License is not limited to
2869
     software manuals; it can be used for any textual work, regardless
2870
     of subject matter or whether it is published as a printed book.
2871
     We recommend this License principally for works whose purpose is
2872
     instruction or reference.
2873
 
2874
  1. APPLICABILITY AND DEFINITIONS
2875
 
2876
     This License applies to any manual or other work, in any medium,
2877
     that contains a notice placed by the copyright holder saying it
2878
     can be distributed under the terms of this License.  Such a notice
2879
     grants a world-wide, royalty-free license, unlimited in duration,
2880
     to use that work under the conditions stated herein.  The
2881
     "Document", below, refers to any such manual or work.  Any member
2882
     of the public is a licensee, and is addressed as "you".  You
2883
     accept the license if you copy, modify or distribute the work in a
2884
     way requiring permission under copyright law.
2885
 
2886
     A "Modified Version" of the Document means any work containing the
2887
     Document or a portion of it, either copied verbatim, or with
2888
     modifications and/or translated into another language.
2889
 
2890
     A "Secondary Section" is a named appendix or a front-matter section
2891
     of the Document that deals exclusively with the relationship of the
2892
     publishers or authors of the Document to the Document's overall
2893
     subject (or to related matters) and contains nothing that could
2894
     fall directly within that overall subject.  (Thus, if the Document
2895
     is in part a textbook of mathematics, a Secondary Section may not
2896
     explain any mathematics.)  The relationship could be a matter of
2897
     historical connection with the subject or with related matters, or
2898
     of legal, commercial, philosophical, ethical or political position
2899
     regarding them.
2900
 
2901
     The "Invariant Sections" are certain Secondary Sections whose
2902
     titles are designated, as being those of Invariant Sections, in
2903
     the notice that says that the Document is released under this
2904
     License.  If a section does not fit the above definition of
2905
     Secondary then it is not allowed to be designated as Invariant.
2906
     The Document may contain zero Invariant Sections.  If the Document
2907
     does not identify any Invariant Sections then there are none.
2908
 
2909
     The "Cover Texts" are certain short passages of text that are
2910
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
2911
     that says that the Document is released under this License.  A
2912
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
2913
     be at most 25 words.
2914
 
2915
     A "Transparent" copy of the Document means a machine-readable copy,
2916
     represented in a format whose specification is available to the
2917
     general public, that is suitable for revising the document
2918
     straightforwardly with generic text editors or (for images
2919
     composed of pixels) generic paint programs or (for drawings) some
2920
     widely available drawing editor, and that is suitable for input to
2921
     text formatters or for automatic translation to a variety of
2922
     formats suitable for input to text formatters.  A copy made in an
2923
     otherwise Transparent file format whose markup, or absence of
2924
     markup, has been arranged to thwart or discourage subsequent
2925
     modification by readers is not Transparent.  An image format is
2926
     not Transparent if used for any substantial amount of text.  A
2927
     copy that is not "Transparent" is called "Opaque".
2928
 
2929
     Examples of suitable formats for Transparent copies include plain
2930
     ASCII without markup, Texinfo input format, LaTeX input format,
2931
     SGML or XML using a publicly available DTD, and
2932
     standard-conforming simple HTML, PostScript or PDF designed for
2933
     human modification.  Examples of transparent image formats include
2934
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
2935
     can be read and edited only by proprietary word processors, SGML or
2936
     XML for which the DTD and/or processing tools are not generally
2937
     available, and the machine-generated HTML, PostScript or PDF
2938
     produced by some word processors for output purposes only.
2939
 
2940
     The "Title Page" means, for a printed book, the title page itself,
2941
     plus such following pages as are needed to hold, legibly, the
2942
     material this License requires to appear in the title page.  For
2943
     works in formats which do not have any title page as such, "Title
2944
     Page" means the text near the most prominent appearance of the
2945
     work's title, preceding the beginning of the body of the text.
2946
 
2947
     A section "Entitled XYZ" means a named subunit of the Document
2948
     whose title either is precisely XYZ or contains XYZ in parentheses
2949
     following text that translates XYZ in another language.  (Here XYZ
2950
     stands for a specific section name mentioned below, such as
2951
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
2952
     To "Preserve the Title" of such a section when you modify the
2953
     Document means that it remains a section "Entitled XYZ" according
2954
     to this definition.
2955
 
2956
     The Document may include Warranty Disclaimers next to the notice
2957
     which states that this License applies to the Document.  These
2958
     Warranty Disclaimers are considered to be included by reference in
2959
     this License, but only as regards disclaiming warranties: any other
2960
     implication that these Warranty Disclaimers may have is void and
2961
     has no effect on the meaning of this License.
2962
 
2963
  2. VERBATIM COPYING
2964
 
2965
     You may copy and distribute the Document in any medium, either
2966
     commercially or noncommercially, provided that this License, the
2967
     copyright notices, and the license notice saying this License
2968
     applies to the Document are reproduced in all copies, and that you
2969
     add no other conditions whatsoever to those of this License.  You
2970
     may not use technical measures to obstruct or control the reading
2971
     or further copying of the copies you make or distribute.  However,
2972
     you may accept compensation in exchange for copies.  If you
2973
     distribute a large enough number of copies you must also follow
2974
     the conditions in section 3.
2975
 
2976
     You may also lend copies, under the same conditions stated above,
2977
     and you may publicly display copies.
2978
 
2979
  3. COPYING IN QUANTITY
2980
 
2981
     If you publish printed copies (or copies in media that commonly
2982
     have printed covers) of the Document, numbering more than 100, and
2983
     the Document's license notice requires Cover Texts, you must
2984
     enclose the copies in covers that carry, clearly and legibly, all
2985
     these Cover Texts: Front-Cover Texts on the front cover, and
2986
     Back-Cover Texts on the back cover.  Both covers must also clearly
2987
     and legibly identify you as the publisher of these copies.  The
2988
     front cover must present the full title with all words of the
2989
     title equally prominent and visible.  You may add other material
2990
     on the covers in addition.  Copying with changes limited to the
2991
     covers, as long as they preserve the title of the Document and
2992
     satisfy these conditions, can be treated as verbatim copying in
2993
     other respects.
2994
 
2995
     If the required texts for either cover are too voluminous to fit
2996
     legibly, you should put the first ones listed (as many as fit
2997
     reasonably) on the actual cover, and continue the rest onto
2998
     adjacent pages.
2999
 
3000
     If you publish or distribute Opaque copies of the Document
3001
     numbering more than 100, you must either include a
3002
     machine-readable Transparent copy along with each Opaque copy, or
3003
     state in or with each Opaque copy a computer-network location from
3004
     which the general network-using public has access to download
3005
     using public-standard network protocols a complete Transparent
3006
     copy of the Document, free of added material.  If you use the
3007
     latter option, you must take reasonably prudent steps, when you
3008
     begin distribution of Opaque copies in quantity, to ensure that
3009
     this Transparent copy will remain thus accessible at the stated
3010
     location until at least one year after the last time you
3011
     distribute an Opaque copy (directly or through your agents or
3012
     retailers) of that edition to the public.
3013
 
3014
     It is requested, but not required, that you contact the authors of
3015
     the Document well before redistributing any large number of
3016
     copies, to give them a chance to provide you with an updated
3017
     version of the Document.
3018
 
3019
  4. MODIFICATIONS
3020
 
3021
     You may copy and distribute a Modified Version of the Document
3022
     under the conditions of sections 2 and 3 above, provided that you
3023
     release the Modified Version under precisely this License, with
3024
     the Modified Version filling the role of the Document, thus
3025
     licensing distribution and modification of the Modified Version to
3026
     whoever possesses a copy of it.  In addition, you must do these
3027
     things in the Modified Version:
3028
 
3029
       A. Use in the Title Page (and on the covers, if any) a title
3030
          distinct from that of the Document, and from those of
3031
          previous versions (which should, if there were any, be listed
3032
          in the History section of the Document).  You may use the
3033
          same title as a previous version if the original publisher of
3034
          that version gives permission.
3035
 
3036
       B. List on the Title Page, as authors, one or more persons or
3037
          entities responsible for authorship of the modifications in
3038
          the Modified Version, together with at least five of the
3039
          principal authors of the Document (all of its principal
3040
          authors, if it has fewer than five), unless they release you
3041
          from this requirement.
3042
 
3043
       C. State on the Title page the name of the publisher of the
3044
          Modified Version, as the publisher.
3045
 
3046
       D. Preserve all the copyright notices of the Document.
3047
 
3048
       E. Add an appropriate copyright notice for your modifications
3049
          adjacent to the other copyright notices.
3050
 
3051
       F. Include, immediately after the copyright notices, a license
3052
          notice giving the public permission to use the Modified
3053
          Version under the terms of this License, in the form shown in
3054
          the Addendum below.
3055
 
3056
       G. Preserve in that license notice the full lists of Invariant
3057
          Sections and required Cover Texts given in the Document's
3058
          license notice.
3059
 
3060
       H. Include an unaltered copy of this License.
3061
 
3062
       I. Preserve the section Entitled "History", Preserve its Title,
3063
          and add to it an item stating at least the title, year, new
3064
          authors, and publisher of the Modified Version as given on
3065
          the Title Page.  If there is no section Entitled "History" in
3066
          the Document, create one stating the title, year, authors,
3067
          and publisher of the Document as given on its Title Page,
3068
          then add an item describing the Modified Version as stated in
3069
          the previous sentence.
3070
 
3071
       J. Preserve the network location, if any, given in the Document
3072
          for public access to a Transparent copy of the Document, and
3073
          likewise the network locations given in the Document for
3074
          previous versions it was based on.  These may be placed in
3075
          the "History" section.  You may omit a network location for a
3076
          work that was published at least four years before the
3077
          Document itself, or if the original publisher of the version
3078
          it refers to gives permission.
3079
 
3080
       K. For any section Entitled "Acknowledgements" or "Dedications",
3081
          Preserve the Title of the section, and preserve in the
3082
          section all the substance and tone of each of the contributor
3083
          acknowledgements and/or dedications given therein.
3084
 
3085
       L. Preserve all the Invariant Sections of the Document,
3086
          unaltered in their text and in their titles.  Section numbers
3087
          or the equivalent are not considered part of the section
3088
          titles.
3089
 
3090
       M. Delete any section Entitled "Endorsements".  Such a section
3091
          may not be included in the Modified Version.
3092
 
3093
       N. Do not retitle any existing section to be Entitled
3094
          "Endorsements" or to conflict in title with any Invariant
3095
          Section.
3096
 
3097
       O. Preserve any Warranty Disclaimers.
3098
 
3099
     If the Modified Version includes new front-matter sections or
3100
     appendices that qualify as Secondary Sections and contain no
3101
     material copied from the Document, you may at your option
3102
     designate some or all of these sections as invariant.  To do this,
3103
     add their titles to the list of Invariant Sections in the Modified
3104
     Version's license notice.  These titles must be distinct from any
3105
     other section titles.
3106
 
3107
     You may add a section Entitled "Endorsements", provided it contains
3108
     nothing but endorsements of your Modified Version by various
3109
     parties--for example, statements of peer review or that the text
3110
     has been approved by an organization as the authoritative
3111
     definition of a standard.
3112
 
3113
     You may add a passage of up to five words as a Front-Cover Text,
3114
     and a passage of up to 25 words as a Back-Cover Text, to the end
3115
     of the list of Cover Texts in the Modified Version.  Only one
3116
     passage of Front-Cover Text and one of Back-Cover Text may be
3117
     added by (or through arrangements made by) any one entity.  If the
3118
     Document already includes a cover text for the same cover,
3119
     previously added by you or by arrangement made by the same entity
3120
     you are acting on behalf of, you may not add another; but you may
3121
     replace the old one, on explicit permission from the previous
3122
     publisher that added the old one.
3123
 
3124
     The author(s) and publisher(s) of the Document do not by this
3125
     License give permission to use their names for publicity for or to
3126
     assert or imply endorsement of any Modified Version.
3127
 
3128
  5. COMBINING DOCUMENTS
3129
 
3130
     You may combine the Document with other documents released under
3131
     this License, under the terms defined in section 4 above for
3132
     modified versions, provided that you include in the combination
3133
     all of the Invariant Sections of all of the original documents,
3134
     unmodified, and list them all as Invariant Sections of your
3135
     combined work in its license notice, and that you preserve all
3136
     their Warranty Disclaimers.
3137
 
3138
     The combined work need only contain one copy of this License, and
3139
     multiple identical Invariant Sections may be replaced with a single
3140
     copy.  If there are multiple Invariant Sections with the same name
3141
     but different contents, make the title of each such section unique
3142
     by adding at the end of it, in parentheses, the name of the
3143
     original author or publisher of that section if known, or else a
3144
     unique number.  Make the same adjustment to the section titles in
3145
     the list of Invariant Sections in the license notice of the
3146
     combined work.
3147
 
3148
     In the combination, you must combine any sections Entitled
3149
     "History" in the various original documents, forming one section
3150
     Entitled "History"; likewise combine any sections Entitled
3151
     "Acknowledgements", and any sections Entitled "Dedications".  You
3152
     must delete all sections Entitled "Endorsements."
3153
 
3154
  6. COLLECTIONS OF DOCUMENTS
3155
 
3156
     You may make a collection consisting of the Document and other
3157
     documents released under this License, and replace the individual
3158
     copies of this License in the various documents with a single copy
3159
     that is included in the collection, provided that you follow the
3160
     rules of this License for verbatim copying of each of the
3161
     documents in all other respects.
3162
 
3163
     You may extract a single document from such a collection, and
3164
     distribute it individually under this License, provided you insert
3165
     a copy of this License into the extracted document, and follow
3166
     this License in all other respects regarding verbatim copying of
3167
     that document.
3168
 
3169
  7. AGGREGATION WITH INDEPENDENT WORKS
3170
 
3171
     A compilation of the Document or its derivatives with other
3172
     separate and independent documents or works, in or on a volume of
3173
     a storage or distribution medium, is called an "aggregate" if the
3174
     copyright resulting from the compilation is not used to limit the
3175
     legal rights of the compilation's users beyond what the individual
3176
     works permit.  When the Document is included in an aggregate, this
3177
     License does not apply to the other works in the aggregate which
3178
     are not themselves derivative works of the Document.
3179
 
3180
     If the Cover Text requirement of section 3 is applicable to these
3181
     copies of the Document, then if the Document is less than one half
3182
     of the entire aggregate, the Document's Cover Texts may be placed
3183
     on covers that bracket the Document within the aggregate, or the
3184
     electronic equivalent of covers if the Document is in electronic
3185
     form.  Otherwise they must appear on printed covers that bracket
3186
     the whole aggregate.
3187
 
3188
  8. TRANSLATION
3189
 
3190
     Translation is considered a kind of modification, so you may
3191
     distribute translations of the Document under the terms of section
3192
     4.  Replacing Invariant Sections with translations requires special
3193
     permission from their copyright holders, but you may include
3194
     translations of some or all Invariant Sections in addition to the
3195
     original versions of these Invariant Sections.  You may include a
3196
     translation of this License, and all the license notices in the
3197
     Document, and any Warranty Disclaimers, provided that you also
3198
     include the original English version of this License and the
3199
     original versions of those notices and disclaimers.  In case of a
3200
     disagreement between the translation and the original version of
3201
     this License or a notice or disclaimer, the original version will
3202
     prevail.
3203
 
3204
     If a section in the Document is Entitled "Acknowledgements",
3205
     "Dedications", or "History", the requirement (section 4) to
3206
     Preserve its Title (section 1) will typically require changing the
3207
     actual title.
3208
 
3209
  9. TERMINATION
3210
 
3211
     You may not copy, modify, sublicense, or distribute the Document
3212
     except as expressly provided for under this License.  Any other
3213
     attempt to copy, modify, sublicense or distribute the Document is
3214
     void, and will automatically terminate your rights under this
3215
     License.  However, parties who have received copies, or rights,
3216
     from you under this License will not have their licenses
3217
     terminated so long as such parties remain in full compliance.
3218
 
3219
 10. FUTURE REVISIONS OF THIS LICENSE
3220
 
3221
     The Free Software Foundation may publish new, revised versions of
3222
     the GNU Free Documentation License from time to time.  Such new
3223
     versions will be similar in spirit to the present version, but may
3224
     differ in detail to address new problems or concerns.  See
3225
     `http://www.gnu.org/copyleft/'.
3226
 
3227
     Each version of the License is given a distinguishing version
3228
     number.  If the Document specifies that a particular numbered
3229
     version of this License "or any later version" applies to it, you
3230
     have the option of following the terms and conditions either of
3231
     that specified version or of any later version that has been
3232
     published (not as a draft) by the Free Software Foundation.  If
3233
     the Document does not specify a version number of this License,
3234
     you may choose any version ever published (not as a draft) by the
3235
     Free Software Foundation.
3236
 
3237
ADDENDUM: How to use this License for your documents
3238
====================================================
3239
 
3240
To use this License in a document you have written, include a copy of
3241
the License in the document and put the following copyright and license
3242
notices just after the title page:
3243
 
3244
       Copyright (C)  YEAR  YOUR NAME.
3245
       Permission is granted to copy, distribute and/or modify this document
3246
       under the terms of the GNU Free Documentation License, Version 1.2
3247
       or any later version published by the Free Software Foundation;
3248
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
3249
       Texts.  A copy of the license is included in the section entitled ``GNU
3250
       Free Documentation License''.
3251
 
3252
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
3253
replace the "with...Texts." line with this:
3254
 
3255
         with the Invariant Sections being LIST THEIR TITLES, with
3256
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
3257
         being LIST.
3258
 
3259
If you have Invariant Sections without Cover Texts, or some other
3260
combination of the three, merge those two alternatives to suit the
3261
situation.
3262
 
3263
If your document contains nontrivial examples of program code, we
3264
recommend releasing these examples in parallel under your choice of
3265
free software license, such as the GNU General Public License, to
3266
permit their use in free software.
3267
 
3268

3269
File: or1ksim.info,  Node: Index,  Prev: GNU Free Documentation License,  Up: Top
3270
 
3271
Index
3272
*****
3273
 
3274
 
3275
* Menu:
3276
3277
* --cumulative:                          Profiling Utility.   (line  26)
3278
* --debug-config:                        Standalone Simulator.
3279
                                                              (line  48)
3280 82 jeremybenn
* --disable-all-tests:                   Configuring the Build.
3281
                                                              (line 128)
3282 19 jeremybenn
* --disable-arith-flag:                  Configuring the Build.
3283
                                                              (line  93)
3284
* --disable-debug:                       Configuring the Build.
3285
                                                              (line 121)
3286
* --disable-ethphy:                      Configuring the Build.
3287
                                                              (line  54)
3288
* --disable-ov-flag:                     Configuring the Build.
3289
                                                              (line  70)
3290
* --disable-profiling:                   Configuring the Build.
3291
                                                              (line  25)
3292
* --disable-range-stats:                 Configuring the Build.
3293
                                                              (line  64)
3294 82 jeremybenn
* --enable-all-tests:                    Configuring the Build.
3295
                                                              (line 127)
3296 19 jeremybenn
* --enable-arith-flag:                   Configuring the Build.
3297
                                                              (line  92)
3298
* --enable-debug:                        Configuring the Build.
3299
                                                              (line 120)
3300
* --enable-ethphy:                       Configuring the Build.
3301
                                                              (line  53)
3302
* --enable-execution:                    Configuring the Build.
3303
                                                              (line  32)
3304
* --enable-mprofile:                     Standalone Simulator.
3305
                                                              (line  77)
3306
* --enable-ov-flag:                      Configuring the Build.
3307
                                                              (line  69)
3308
* --enable-profile:                      Standalone Simulator.
3309
                                                              (line  74)
3310
* --enable-profiling:                    Configuring the Build.
3311
                                                              (line  24)
3312
* --enable-range-stats:                  Configuring the Build.
3313
                                                              (line  63)
3314
* --file:                                Standalone Simulator.
3315
                                                              (line  24)
3316
* --filename:                            Memory Profiling Utility.
3317
                                                              (line  51)
3318
* --generate:                            Profiling Utility.   (line  34)
3319
* --group:                               Memory Profiling Utility.
3320
                                                              (line  47)
3321
* --help:                                Standalone Simulator.
3322
                                                              (line  20)
3323
* --help (memory profiling utility):     Memory Profiling Utility.
3324
                                                              (line  22)
3325
* --help (profiling utility):            Profiling Utility.   (line  22)
3326
* --interactive:                         Standalone Simulator.
3327
                                                              (line  54)
3328
* --mode:                                Memory Profiling Utility.
3329
                                                              (line  26)
3330
* --nosrv:                               Standalone Simulator.
3331
                                                              (line  32)
3332
* --quiet:                               Profiling Utility.   (line  30)
3333
* --srv:                                 Standalone Simulator.
3334
                                                              (line  40)
3335
* --strict-npc:                          Standalone Simulator.
3336
                                                              (line  57)
3337
* --version:                             Standalone Simulator.
3338
                                                              (line  16)
3339
* --version (memory profiling utility):  Memory Profiling Utility.
3340
                                                              (line  17)
3341
* --version (profiling utility):         Profiling Utility.   (line  17)
3342
* -c:                                    Profiling Utility.   (line  26)
3343
* -d:                                    Standalone Simulator.
3344
                                                              (line  48)
3345
* -f <1>:                                Memory Profiling Utility.
3346
                                                              (line  51)
3347
* -f:                                    Standalone Simulator.
3348
                                                              (line  24)
3349
* -g <1>:                                Memory Profiling Utility.
3350
                                                              (line  47)
3351
* -g:                                    Profiling Utility.   (line  34)
3352
* -h:                                    Standalone Simulator.
3353
                                                              (line  20)
3354
* -h (memory profiling utility):         Memory Profiling Utility.
3355
                                                              (line  22)
3356
* -h (profiling utility):                Profiling Utility.   (line  22)
3357
* -i:                                    Standalone Simulator.
3358
                                                              (line  54)
3359
* -m:                                    Memory Profiling Utility.
3360
                                                              (line  26)
3361
* -q:                                    Profiling Utility.   (line  30)
3362
* -v:                                    Standalone Simulator.
3363
                                                              (line  16)
3364
* -v (memory profiling utility):         Memory Profiling Utility.
3365
                                                              (line  17)
3366
* -v (profiling utility):                Profiling Utility.   (line  17)
3367
* 0x00 UART VAPI sub-command (UART verification): Verification API.
3368
                                                              (line  49)
3369
* 0x01 UART VAPI sub-command (UART verification): Verification API.
3370
                                                              (line  55)
3371
* 0x02 UART VAPI sub-command (UART verification): Verification API.
3372
                                                              (line  59)
3373
* 0x03 UART VAPI sub-command (UART verification): Verification API.
3374
                                                              (line  62)
3375
* 0x04 UART VAPI sub-command (UART verification): Verification API.
3376
                                                              (line  66)
3377
* 16550 (UART configuration):            UART Configuration.  (line  73)
3378 82 jeremybenn
* all tests enabled:                     Configuring the Build.
3379
                                                              (line 128)
3380 19 jeremybenn
* Argtable2 debugging:                   Configuring the Build.
3381
                                                              (line 121)
3382
* ATA/ATAPI configuration:               Disc Interface Configuration.
3383
                                                              (line   6)
3384
* ATA/ATAPI device configuration:        Disc Interface Configuration.
3385
                                                              (line  88)
3386
* base_vapi_id (GPIO configuration - deprecated): GPIO Configuration.
3387
                                                              (line  32)
3388
* baseaddr (ATA/ATAPI configuration):    Disc Interface Configuration.
3389
                                                              (line  22)
3390
* baseaddr (DMA configuration):          DMA Configuration.   (line  24)
3391
* baseaddr (Ethernet configuration):     Ethernet Configuration.
3392
                                                              (line  22)
3393
* baseaddr (frame buffer configuration): Frame Buffer Configuration.
3394
                                                              (line  20)
3395
* baseaddr (generic peripheral configuration): Generic Peripheral Configuration.
3396
                                                              (line  22)
3397
* baseaddr (GPIO configuration):         GPIO Configuration.  (line  21)
3398
* baseaddr (keyboard configuration):     Keyboard Configuration.
3399
                                                              (line  36)
3400
* baseaddr (memory configuration):       Memory Configuration.
3401 98 jeremybenn
                                                              (line  87)
3402 19 jeremybenn
* baseaddr (memory controller configuration): Memory Controller Configuration.
3403 98 jeremybenn
                                                              (line  46)
3404 19 jeremybenn
* baseaddr (UART configuration):         UART Configuration.  (line  22)
3405
* baseaddr (VGA configuration):          Display Interface Configuration.
3406
                                                              (line  26)
3407
* blocksize (cache configuration):       Cache Configuration. (line  29)
3408
* BPB configuration:                     Branch Prediction Configuration.
3409
                                                              (line   6)
3410
* branch prediction configuration:       Branch Prediction Configuration.
3411
                                                              (line   6)
3412
* break (Interactive CLI):               Interactive Command Line.
3413
                                                              (line  57)
3414
* breakpoint list (Interactive CLI):     Interactive Command Line.
3415
                                                              (line  60)
3416
* breakpoint set/clear (Interactive CLI): Interactive Command Line.
3417
                                                              (line  57)
3418
* breaks (Interactive CLI):              Interactive Command Line.
3419
                                                              (line  60)
3420
* btic (branch prediction configuration): Branch Prediction Configuration.
3421
                                                              (line  19)
3422
* byte_enabled (generic peripheral configuration): Generic Peripheral Configuration.
3423
                                                              (line  48)
3424
* cache configuration:                   Cache Configuration. (line   6)
3425
* calling_convention (CUC configuration): CUC Configuration.  (line  34)
3426
* ce (memory configuration):             Memory Configuration.
3427 98 jeremybenn
                                                              (line 117)
3428 19 jeremybenn
* cfgr (CPU configuration):              CPU Configuration.   (line  47)
3429
* channel (UART configuration):          UART Configuration.  (line  29)
3430
* clear breakpoint (Interactive CLI):    Interactive Command Line.
3431
                                                              (line  57)
3432 82 jeremybenn
* clkcycle (simulator configuration):    Simulator Behavior.  (line 103)
3433 19 jeremybenn
* cm (Interactive CLI):                  Interactive Command Line.
3434
                                                              (line  54)
3435
* command line for Or1ksim standalone use: Standalone Simulator.
3436
                                                              (line   6)
3437
* complex model:                         Configuring the Build.
3438
                                                              (line  32)
3439
* config:                                Global Data Structures.
3440
                                                              (line   7)
3441
* config.bpb:                            Global Data Structures.
3442
                                                              (line  37)
3443
* config.cpu:                            Global Data Structures.
3444
                                                              (line  22)
3445
* config.cuc:                            Global Data Structures.
3446
                                                              (line  18)
3447
* config.dc:                             Global Data Structures.
3448
                                                              (line  25)
3449
* config.debug:                          Global Data Structures.
3450
                                                              (line  40)
3451
* config.pic:                            Global Data Structures.
3452
                                                              (line  33)
3453
* config.pm:                             Global Data Structures.
3454
                                                              (line  29)
3455
* config.sim:                            Global Data Structures.
3456
                                                              (line  11)
3457
* config.vapi:                           Global Data Structures.
3458
                                                              (line  14)
3459
* configuration dynamic structure:       Global Data Structures.
3460
                                                              (line  49)
3461
* configuration file structure:          Configuration File Format.
3462
                                                              (line   6)
3463
* configuration global structure:        Global Data Structures.
3464
                                                              (line   7)
3465
* configuration info (Interactive CLI):  Interactive Command Line.
3466
                                                              (line 119)
3467
* configuration of generic peripherals:  Generic Peripheral Configuration.
3468
                                                              (line   6)
3469
* configuration parameter setting (Interactive CLI): Interactive Command Line.
3470
                                                              (line 146)
3471
* configuring branch prediction:         Branch Prediction Configuration.
3472
                                                              (line   6)
3473
* configuring data & instruction caches: Cache Configuration. (line   6)
3474
* configuring data & instruction MMUs:   Memory Management Configuration.
3475
                                                              (line   6)
3476
* configuring DMA:                       DMA Configuration.   (line   6)
3477
* configuring memory:                    Memory Configuration.
3478
                                                              (line   6)
3479
* configuring Or1ksim:                   Configuration.       (line   6)
3480
* configuring power management:          Power Management Configuration.
3481
                                                              (line   6)
3482
* configuring the ATA/ATAPI interfaces:  Disc Interface Configuration.
3483
                                                              (line   6)
3484
* configuring the behavior of Or1ksim:   Simulator Behavior.  (line   6)
3485
* configuring the CPU:                   CPU Configuration.   (line   6)
3486
* configuring the Custom Unit Compiler (CUC): CUC Configuration.
3487
                                                              (line   6)
3488
* configuring the debug unit and interface to external debuggers: Debug Interface Configuration.
3489
                                                              (line   6)
3490
* configuring the Ethernet interface:    Ethernet Configuration.
3491
                                                              (line   6)
3492
* configuring the frame buffer:          Frame Buffer Configuration.
3493
                                                              (line   6)
3494
* configuring the GPIO:                  GPIO Configuration.  (line   6)
3495
* configuring the interrupt controller:  Interrupt Configuration.
3496
                                                              (line   6)
3497
* configuring the keyboard interface:    Keyboard Configuration.
3498
                                                              (line   6)
3499
* configuring the memory controller:     Memory Controller Configuration.
3500
                                                              (line   6)
3501
* configuring the processor:             CPU Configuration.   (line   6)
3502
* configuring the PS2 interface:         Keyboard Configuration.
3503
                                                              (line   6)
3504
* configuring the UART:                  UART Configuration.  (line   6)
3505
* configuring the Verification API (VAPI): Verification API Configuration.
3506
                                                              (line   6)
3507
* configuring the VGA interface:         Display Interface Configuration.
3508
                                                              (line   6)
3509
* copying memory (Interactive CLI):      Interactive Command Line.
3510
                                                              (line  54)
3511
* CPU configuration:                     CPU Configuration.   (line   6)
3512
* CUC configuration:                     CUC Configuration.   (line   6)
3513
* Custom Unit Compiler (Interactive CLI): Interactive Command Line.
3514
                                                              (line 162)
3515
* Custom Unit Compiler Configuration:    CUC Configuration.   (line   6)
3516
* data cache configuration:              Cache Configuration. (line   6)
3517
* data MMU configuration:                Memory Management Configuration.
3518
                                                              (line   6)
3519
* DCGE (power management register):      Power Management Configuration.
3520
                                                              (line  21)
3521
* debug (Interactive CLI):               Interactive Command Line.
3522
                                                              (line 151)
3523
* debug (simulator configuration):       Simulator Behavior.  (line  13)
3524
* debug channel toggle (Interactive CLI): Interactive Command Line.
3525
                                                              (line 141)
3526
* debug interface configuration:         Debug Interface Configuration.
3527
                                                              (line   6)
3528
* debug mode toggle (Interactive CLI):   Interactive Command Line.
3529
                                                              (line 151)
3530
* debug unit configuration:              Debug Interface Configuration.
3531
                                                              (line   6)
3532
* Debug Unit verification (VAPI):        Verification API.    (line  34)
3533
* debugging enabled (Argtable2):         Configuring the Build.
3534
                                                              (line 121)
3535
* delayr (memory configuration):         Memory Configuration.
3536 98 jeremybenn
                                                              (line 137)
3537 19 jeremybenn
* delayw (memory configuration):         Memory Configuration.
3538 98 jeremybenn
                                                              (line 143)
3539
* dependstats (CPU configuration):       CPU Configuration.   (line  89)
3540 19 jeremybenn
* dev_id (ATA/ATAPI configuration):      Disc Interface Configuration.
3541
                                                              (line  36)
3542
* disassemble (Interactive CLI):         Interactive Command Line.
3543
                                                              (line  41)
3544
* disc interface configuration:          Disc Interface Configuration.
3545
                                                              (line   6)
3546
* disc interface device configuration:   Disc Interface Configuration.
3547
                                                              (line  88)
3548
* display interface configuration:       Display Interface Configuration.
3549
                                                              (line   6)
3550
* displaying memory (Interactive CLI):   Interactive Command Line.
3551
                                                              (line  31)
3552
* displaying registers (Interactive CLI): Interactive Command Line.
3553
                                                              (line  14)
3554
* dm (Interactive CLI):                  Interactive Command Line.
3555
                                                              (line  31)
3556
* dma (Ethernet configuration):          Ethernet Configuration.
3557
                                                              (line  33)
3558
* DMA configuration:                     DMA Configuration.   (line   6)
3559
* DMA verification (VAPI):               Verification API.    (line  73)
3560
* dma_mode0_td (ATA/ATAPI configuration): Disc Interface Configuration.
3561
                                                              (line  70)
3562
* dma_mode0_teoc (ATA/ATAPI configuration): Disc Interface Configuration.
3563
                                                              (line  71)
3564
* dma_mode0_tm (ATA/ATAPI configuration): Disc Interface Configuration.
3565
                                                              (line  69)
3566
* DME (power management register):       Power Management Configuration.
3567
                                                              (line  15)
3568
* DMMU configuration:                    Memory Management Configuration.
3569
                                                              (line   6)
3570
* doze mode (power management register): Power Management Configuration.
3571
                                                              (line  15)
3572
* dv (Interactive CLI):                  Interactive Command Line.
3573
                                                              (line 124)
3574
* dynamic clock gating (power management register): Power Management Configuration.
3575
                                                              (line  21)
3576
* dynamic model:                         Configuring the Build.
3577
                                                              (line  32)
3578
* dynamic ports, use of:                 Verification API Configuration.
3579
                                                              (line  23)
3580
* edge_trigger (interrupt controller):   Interrupt Configuration.
3581
                                                              (line  16)
3582
* enable_bursts (CUC configuration):     CUC Configuration.   (line  38)
3583
* enabled (ATA/ATAPI configuration):     Disc Interface Configuration.
3584
                                                              (line  18)
3585
* enabled (branch prediction configuration): Branch Prediction Configuration.
3586
                                                              (line  15)
3587
* enabled (cache configuration):         Cache Configuration. (line  11)
3588
* enabled (debug interface configuration): Debug Interface Configuration.
3589
                                                              (line  11)
3590
* enabled (DMA configuration):           DMA Configuration.   (line  20)
3591
* enabled (Ethernet configuration):      Ethernet Configuration.
3592
                                                              (line  18)
3593
* enabled (frame buffer configuration):  Frame Buffer Configuration.
3594
                                                              (line  16)
3595
* enabled (generic peripheral configuration): Generic Peripheral Configuration.
3596
                                                              (line  18)
3597
* enabled (GPIO configuration):          GPIO Configuration.  (line  17)
3598
* enabled (interrupt controller):        Interrupt Configuration.
3599
                                                              (line  12)
3600
* enabled (keyboard configuration):      Keyboard Configuration.
3601
                                                              (line  32)
3602
* enabled (memory controller configuration): Memory Controller Configuration.
3603 98 jeremybenn
                                                              (line  35)
3604 19 jeremybenn
* enabled (MMU configuration):           Memory Management Configuration.
3605
                                                              (line  12)
3606
* enabled (power management configuration): Power Management Configuration.
3607
                                                              (line  35)
3608
* enabled (UART configuration):          UART Configuration.  (line  18)
3609
* enabled (verification API configuration): Verification API Configuration.
3610
                                                              (line  15)
3611
* enabled (VGA configuration):           Display Interface Configuration.
3612
                                                              (line  22)
3613
* enabling Ethernet via socket:          Configuring the Build.
3614
                                                              (line  54)
3615
* entrysize (MMU configuration):         Memory Management Configuration.
3616
                                                              (line  32)
3617
* ETH_VAPI_CTRL (Ethernet verification): Verification API.    (line  86)
3618
* ETH_VAPI_DATA (Ethernet verification): Verification API.    (line  84)
3619
* Ethernet configuration:                Ethernet Configuration.
3620
                                                              (line   6)
3621
* Ethernet verification (VAPI):          Verification API.    (line  78)
3622
* Ethernet via socket, enabling:         Configuring the Build.
3623
                                                              (line  54)
3624 82 jeremybenn
* exe_log (simulator configuration):     Simulator Behavior.  (line  49)
3625
* exe_log_end (simulator configuration): Simulator Behavior.  (line  89)
3626
* exe_log_file (simulator configuration): Simulator Behavior. (line  97)
3627 19 jeremybenn
* exe_log_fn (simulator configuration - deprecated): Simulator Behavior.
3628 82 jeremybenn
                                                              (line  97)
3629 19 jeremybenn
* exe_log_marker (simulator configuration): Simulator Behavior.
3630 82 jeremybenn
                                                              (line  93)
3631 19 jeremybenn
* exe_log_start (simulator configuration): Simulator Behavior.
3632 82 jeremybenn
                                                              (line  86)
3633
* exe_log_type (simulator configuration): Simulator Behavior. (line  55)
3634 19 jeremybenn
* exe_log_type=default (simulator configuration): Simulator Behavior.
3635 82 jeremybenn
                                                              (line  58)
3636 19 jeremybenn
* exe_log_type=hardware (simulator configuration): Simulator Behavior.
3637 82 jeremybenn
                                                              (line  62)
3638 19 jeremybenn
* exe_log_type=simple (simulator configuration): Simulator Behavior.
3639 82 jeremybenn
                                                              (line  69)
3640 19 jeremybenn
* exe_log_type=software (simulator configuration): Simulator Behavior.
3641 82 jeremybenn
                                                              (line  74)
3642 19 jeremybenn
* executing code (Interactive CLI):      Interactive Command Line.
3643
                                                              (line  23)
3644
* execution history (Interactive CLI):   Interactive Command Line.
3645
                                                              (line  67)
3646
* file (ATA/ATAPI device configuration): Disc Interface Configuration.
3647
                                                              (line 104)
3648
* file (keyboard configuration):         Keyboard Configuration.
3649
                                                              (line  51)
3650
* filename (frame buffer configuration - deprecated): Frame Buffer Configuration.
3651 82 jeremybenn
                                                              (line  36)
3652 19 jeremybenn
* filename (VGA configuration - deprecated): Display Interface Configuration.
3653
                                                              (line  47)
3654
* firmware (ATA/ATAPI device configuration): Disc Interface Configuration.
3655
                                                              (line 117)
3656
* flag setting by instructions:          Configuring the Build.
3657
                                                              (line  93)
3658
* frame buffer configuration:            Frame Buffer Configuration.
3659
                                                              (line   6)
3660
* gdb_enabled (debug interface configuration): Debug Interface Configuration.
3661
                                                              (line  47)
3662
* generic peripheral configuration:      Generic Peripheral Configuration.
3663
                                                              (line   6)
3664
* GPIO configuration:                    GPIO Configuration.  (line   6)
3665
* GPIO verification (VAPI):              Verification API.    (line  88)
3666
* GPIO_VAPI_AUX (GPIO verification):     Verification API.    (line 100)
3667
* GPIO_VAPI_CLOCK (GPIO verification):   Verification API.    (line 103)
3668
* GPIO_VAPI_CTRL (GPIO verification):    Verification API.    (line 119)
3669
* GPIO_VAPI_DATA (GPIO verification):    Verification API.    (line  97)
3670
* GPIO_VAPI_INTE (GPIO verification):    Verification API.    (line 110)
3671
* GPIO_VAPI_PTRIG (GPIO verification):   Verification API.    (line 113)
3672
* GPIO_VAPI_RGPIO (GPIO verification):   Verification API.    (line 107)
3673 100 julius
* hardfloat (CPU configuration):         CPU Configuration.   (line 110)
3674 98 jeremybenn
* hazards (CPU configuration):           CPU Configuration.   (line  74)
3675 19 jeremybenn
* heads (ATA/ATAPI device configuration): Disc Interface Configuration.
3676
                                                              (line 121)
3677
* help (Interactive CLI):                Interactive Command Line.
3678
                                                              (line 170)
3679
* hexadecimal memory dump (Interactive CLI): Interactive Command Line.
3680
                                                              (line 133)
3681
* hide_device_id (verification API configuration): Verification API Configuration.
3682
                                                              (line  36)
3683
* hist (Interactive CLI):                Interactive Command Line.
3684
                                                              (line  67)
3685 82 jeremybenn
* history (simulator configuration):     Simulator Behavior.  (line  40)
3686 19 jeremybenn
* history of execution (Interactive CLI): Interactive Command Line.
3687
                                                              (line  67)
3688
* hitdelay (branch prediction configuration): Branch Prediction Configuration.
3689
                                                              (line  33)
3690
* hitdelay (instruction cache configuration): Cache Configuration.
3691
                                                              (line  38)
3692
* hitdelay (MMU configuration):          Memory Management Configuration.
3693
                                                              (line  51)
3694
* hw_enabled (generic peripheral configuration): Generic Peripheral Configuration.
3695
                                                              (line  49)
3696
* IMMU configuration:                    Memory Management Configuration.
3697
                                                              (line   6)
3698
* index (memory controller configuration): Memory Controller Configuration.
3699 98 jeremybenn
                                                              (line  68)
3700 19 jeremybenn
* info (Interactive CLI):                Interactive Command Line.
3701
                                                              (line 119)
3702
* installing Or1ksim:                    Installation.        (line   6)
3703
* instruction cache configuration:       Cache Configuration. (line   6)
3704
* instruction MMU configuration:         Memory Management Configuration.
3705
                                                              (line   6)
3706
* instruction profiling for Or1ksim:     Profiling Utility.   (line   6)
3707
* instruction profiling utility (Interactive CLI): Interactive Command Line.
3708
                                                              (line 178)
3709
* internal debugging:                    Internal Debugging.  (line   6)
3710
* interrupt controller configuration:    Interrupt Configuration.
3711
                                                              (line   6)
3712
* irq (ATA/ATAPI configuration):         Disc Interface Configuration.
3713
                                                              (line  32)
3714
* irq (DMA configuration):               DMA Configuration.   (line  34)
3715
* irq (GPIO configuration):              GPIO Configuration.  (line  29)
3716
* irq (keyboard configuration):          Keyboard Configuration.
3717
                                                              (line  47)
3718
* irq (UART configuration):              UART Configuration.  (line  70)
3719
* irq (VGA configuration):               Display Interface Configuration.
3720
                                                              (line  37)
3721
* jitter (UART configuration):           UART Configuration.  (line  78)
3722
* keyboard configuration:                Keyboard Configuration.
3723
                                                              (line   6)
3724
* library version of Or1ksim:            Simulator Library.   (line   6)
3725
* license for Or1ksim:                   GNU Free Documentation License.
3726
                                                              (line   6)
3727
* list breakpoints (Interactive CLI):    Interactive Command Line.
3728
                                                              (line  60)
3729
* load_hitdelay (data cache configuration): Cache Configuration.
3730
                                                              (line  46)
3731
* load_missdelay (data cache configuration): Cache Configuration.
3732
                                                              (line  50)
3733
* log (memory configuration):            Memory Configuration.
3734 98 jeremybenn
                                                              (line 149)
3735 19 jeremybenn
* log_enabled (verification API configuration): Verification API Configuration.
3736
                                                              (line  28)
3737 93 jeremybenn
* long:                                  Simulator Library.   (line  87)
3738 19 jeremybenn
* mc (memory configuration):             Memory Configuration.
3739 98 jeremybenn
                                                              (line 126)
3740 19 jeremybenn
* memory configuration:                  Memory Configuration.
3741
                                                              (line   6)
3742
* memory controller configuration:       Memory Controller Configuration.
3743
                                                              (line   6)
3744
* memory copying (Interactive CLI):      Interactive Command Line.
3745
                                                              (line  54)
3746
* memory display (Interactive CLI):      Interactive Command Line.
3747
                                                              (line  31)
3748
* memory dump, hexadecimal (Interactive CLI): Interactive Command Line.
3749
                                                              (line 133)
3750
* memory dump, Verilog (Interactive CLI): Interactive Command Line.
3751
                                                              (line 124)
3752
* memory patching (Interactive CLI):     Interactive Command Line.
3753
                                                              (line  48)
3754
* memory profiling end address:          Memory Profiling Utility.
3755
                                                              (line  56)
3756
* memory profiling start address:        Memory Profiling Utility.
3757
                                                              (line  56)
3758
* memory profiling utility (Interactive CLI): Interactive Command Line.
3759
                                                              (line 173)
3760
* memory profiling version of Or1ksim:   Memory Profiling Utility.
3761
                                                              (line   6)
3762
* memory_order (CUC configuration):      CUC Configuration.   (line  15)
3763
* memory_order=exact (CUC configuration): CUC Configuration.  (line  27)
3764
* memory_order=none (CUC configuration): CUC Configuration.   (line  18)
3765
* memory_order=strong (CUC configuration): CUC Configuration. (line  25)
3766
* memory_order=weak (CUC configuration): CUC Configuration.   (line  21)
3767
* missdelay (branch prediction configuration): Branch Prediction Configuration.
3768
                                                              (line  37)
3769
* missdelay (instruction cache configuration): Cache Configuration.
3770
                                                              (line  42)
3771
* missdelay (MMU configuration):         Memory Management Configuration.
3772
                                                              (line  55)
3773
* MMU configuration:                     Memory Management Configuration.
3774
                                                              (line   6)
3775 82 jeremybenn
* mprof_file (simulator configuration):  Simulator Behavior.  (line  34)
3776 19 jeremybenn
* mprof_fn (simulator configuration - deprecated): Simulator Behavior.
3777 82 jeremybenn
                                                              (line  34)
3778 19 jeremybenn
* mprofile (Interactive CLI):            Interactive Command Line.
3779
                                                              (line 173)
3780 82 jeremybenn
* mprofile (simulator configuration):    Simulator Behavior.  (line  29)
3781 19 jeremybenn
* mwdma (ATA/ATAPI device configuration): Disc Interface Configuration.
3782
                                                              (line 128)
3783
* name (generic peripheral configuration): Generic Peripheral Configuration.
3784
                                                              (line  42)
3785
* name (memory configuration):           Memory Configuration.
3786 98 jeremybenn
                                                              (line 108)
3787 19 jeremybenn
* no_multicycle (CUC configuration):     CUC Configuration.   (line  42)
3788
* nsets (cache configuration):           Cache Configuration. (line  15)
3789
* nsets (MMU configuration):             Memory Management Configuration.
3790
                                                              (line  16)
3791
* nways (cache configuration):           Cache Configuration. (line  22)
3792
* nways (MMU configuration):             Memory Management Configuration.
3793
                                                              (line  22)
3794 93 jeremybenn
* or1ksim_get_time_period:               Simulator Library.   (line  77)
3795
* or1ksim_init:                          Simulator Library.   (line  14)
3796
* or1ksim_interrupt:                     Simulator Library.   (line  92)
3797
* or1ksim_interrupt_clear:               Simulator Library.   (line 110)
3798
* or1ksim_interrupt_set:                 Simulator Library.   (line 101)
3799
* or1ksim_is_le:                         Simulator Library.   (line  82)
3800
* or1ksim_reset_duration:                Simulator Library.   (line  62)
3801
* or1ksim_run:                           Simulator Library.   (line  57)
3802
* or1ksim_set_time_point:                Simulator Library.   (line  73)
3803 19 jeremybenn
* output rediretion:                     Concepts.            (line   7)
3804
* overflow flag setting by instructions: Configuring the Build.
3805
                                                              (line  70)
3806
* packet (ATA/ATAPI device configuration): Disc Interface Configuration.
3807
                                                              (line 113)
3808
* pagesize (MMU configuration):          Memory Management Configuration.
3809
                                                              (line  27)
3810
* patching memory (Interactive CLI):     Interactive Command Line.
3811
                                                              (line  48)
3812
* patching registers (Interactive CLI):  Interactive Command Line.
3813
                                                              (line  28)
3814
* patching the program counter (Interactive CLI): Interactive Command Line.
3815
                                                              (line  51)
3816
* pattern (memory configuration):        Memory Configuration.
3817 98 jeremybenn
                                                              (line  75)
3818 19 jeremybenn
* pc (Interactive CLI):                  Interactive Command Line.
3819
                                                              (line  51)
3820
* PIC configuration:                     Interrupt Configuration.
3821
                                                              (line   6)
3822
* pio (ATA/ATAPI device configuration):  Disc Interface Configuration.
3823
                                                              (line 132)
3824
* pio_mode0_t1 (ATA/ATAPI configuration): Disc Interface Configuration.
3825
                                                              (line  51)
3826
* pio_mode0_t2 (ATA/ATAPI configuration): Disc Interface Configuration.
3827
                                                              (line  52)
3828
* pio_mode0_t4 (ATA/ATAPI configuration): Disc Interface Configuration.
3829
                                                              (line  53)
3830
* pio_mode0_teoc (ATA/ATAPI configuration): Disc Interface Configuration.
3831
                                                              (line  54)
3832
* pm (Interactive CLI):                  Interactive Command Line.
3833
                                                              (line  48)
3834
* PMR - DGCE:                            Power Management Configuration.
3835
                                                              (line  21)
3836
* PMR - DME:                             Power Management Configuration.
3837
                                                              (line  15)
3838
* PMR - SDF:                             Power Management Configuration.
3839
                                                              (line  12)
3840
* PMR - SME:                             Power Management Configuration.
3841
                                                              (line  16)
3842
* PMR - SUME:                            Power Management Configuration.
3843
                                                              (line  24)
3844
* PMU configuration:                     Power Management Configuration.
3845
                                                              (line   6)
3846
* poc (memory controller configuration): Memory Controller Configuration.
3847 98 jeremybenn
                                                              (line  55)
3848 19 jeremybenn
* port range for TCP/IP:                 Verification API Configuration.
3849
                                                              (line  23)
3850
* power management configuration:        Power Management Configuration.
3851
                                                              (line   6)
3852
* power management register, DGCE:       Power Management Configuration.
3853
                                                              (line  21)
3854
* power management register, DME:        Power Management Configuration.
3855
                                                              (line  15)
3856
* power management register, SDF:        Power Management Configuration.
3857
                                                              (line  12)
3858
* power management register, SME:        Power Management Configuration.
3859
                                                              (line  16)
3860
* power management register, SUME:       Power Management Configuration.
3861
                                                              (line  24)
3862
* pr (Interactive CLI):                  Interactive Command Line.
3863
                                                              (line  28)
3864
* private ports, use of:                 Verification API Configuration.
3865
                                                              (line  23)
3866
* processor configuration:               CPU Configuration.   (line   6)
3867
* processor stall (Interactive CLI):     Interactive Command Line.
3868
                                                              (line  72)
3869
* processor unstall (Interactive CLI):   Interactive Command Line.
3870
                                                              (line  78)
3871
* prof_file (simulator configuration):   Simulator Behavior.  (line  23)
3872
* prof_fn (simulator configuration - deprecated): Simulator Behavior.
3873
                                                              (line  23)
3874
* profile (simulator configuration):     Simulator Behavior.  (line  19)
3875
* profiling for Or1ksim:                 Profiling Utility.   (line   6)
3876
* profiling utility (Interactive CLI):   Interactive Command Line.
3877
                                                              (line 178)
3878
* program counter patching (Interactive CLI): Interactive Command Line.
3879
                                                              (line  51)
3880
* programmable interrupt controller configuration: Interrupt Configuration.
3881
                                                              (line   6)
3882
* PS2 configuration:                     Keyboard Configuration.
3883
                                                              (line   6)
3884
* q (Interactive CLI):                   Interactive Command Line.
3885
                                                              (line  11)
3886
* quitting (Interactive CLI):            Interactive Command Line.
3887
                                                              (line  11)
3888
* r (Interactive CLI):                   Interactive Command Line.
3889
                                                              (line  14)
3890
* random_seed (memory configuration):    Memory Configuration.
3891 98 jeremybenn
                                                              (line  65)
3892 19 jeremybenn
* refresh_rate (frame buffer configuration): Frame Buffer Configuration.
3893 82 jeremybenn
                                                              (line  30)
3894 19 jeremybenn
* refresh_rate (VGA configuration):      Display Interface Configuration.
3895
                                                              (line  41)
3896
* reg_sim_reset:                         Concepts.            (line  13)
3897
* register display (Interactive CLI):    Interactive Command Line.
3898
                                                              (line  14)
3899
* register over time statistics:         Configuring the Build.
3900
                                                              (line  64)
3901
* register patching (Interactive CLI):   Interactive Command Line.
3902
                                                              (line  28)
3903
* Remote Serial Protocol:                Debug Interface Configuration.
3904
                                                              (line  20)
3905
* reset (Interactive CLI):               Interactive Command Line.
3906
                                                              (line  63)
3907
* reset hooks:                           Concepts.            (line  13)
3908
* reset the simulator (Interactive CLI): Interactive Command Line.
3909
                                                              (line  63)
3910
* rev (ATA/ATAPI configuration):         Disc Interface Configuration.
3911
                                                              (line  44)
3912
* rev (CPU configuration):               CPU Configuration.   (line  15)
3913
* rsp_enabled (debug interface configuration): Debug Interface Configuration.
3914
                                                              (line  20)
3915
* rsp_port (debug interface configuration): Debug Interface Configuration.
3916
                                                              (line  36)
3917
* rtx_type (Ethernet configuration):     Ethernet Configuration.
3918
                                                              (line  46)
3919
* run (Interactive CLI):                 Interactive Command Line.
3920
                                                              (line  23)
3921
* running code (Interactive CLI):        Interactive Command Line.
3922
                                                              (line  23)
3923
* running Or1ksim:                       Usage.               (line   6)
3924
* runtime:                               Global Data Structures.
3925
                                                              (line  58)
3926
* runtime global structure:              Global Data Structures.
3927
                                                              (line  58)
3928
* runtime.cpu:                           Global Data Structures.
3929
                                                              (line  62)
3930
* runtime.cpu.fout:                      Concepts.            (line   7)
3931
* runtime.cuc:                           Global Data Structures.
3932
                                                              (line  62)
3933
* runtime.vapi:                          Global Data Structures.
3934
                                                              (line  62)
3935
* rx_channel (Ethernet configuration):   Ethernet Configuration.
3936
                                                              (line  59)
3937
* rxfile (Ethernet configuration):       Ethernet Configuration.
3938
                                                              (line  68)
3939
* sbp_bf_fwd (branch prediction configuration): Branch Prediction Configuration.
3940
                                                              (line  23)
3941
* sbp_bnf_fwd (branch prediction configuration): Branch Prediction Configuration.
3942
                                                              (line  28)
3943 98 jeremybenn
* sbuf_len (CPU configuration):          CPU Configuration.   (line 101)
3944 19 jeremybenn
* SDF (power management register):       Power Management Configuration.
3945
                                                              (line  12)
3946
* section ata:                           Disc Interface Configuration.
3947
                                                              (line   6)
3948
* section bpb:                           Branch Prediction Configuration.
3949
                                                              (line   6)
3950
* section cpio:                          GPIO Configuration.  (line   6)
3951
* section cpu:                           CPU Configuration.   (line   6)
3952
* section cuc:                           CUC Configuration.   (line   6)
3953
* section dc:                            Cache Configuration. (line   6)
3954
* section debug:                         Debug Interface Configuration.
3955
                                                              (line   6)
3956
* section dma:                           DMA Configuration.   (line   6)
3957
* section dmmu:                          Memory Management Configuration.
3958
                                                              (line   6)
3959
* section ethernet:                      Ethernet Configuration.
3960
                                                              (line   6)
3961
* section fb:                            Frame Buffer Configuration.
3962
                                                              (line   6)
3963
* section generic:                       Generic Peripheral Configuration.
3964
                                                              (line   6)
3965
* section ic:                            Cache Configuration. (line   6)
3966
* section immu:                          Memory Management Configuration.
3967
                                                              (line   6)
3968
* section kb:                            Keyboard Configuration.
3969
                                                              (line   6)
3970
* section mc:                            Memory Controller Configuration.
3971
                                                              (line   6)
3972
* section memory:                        Memory Configuration.
3973
                                                              (line   6)
3974
* section pic:                           Interrupt Configuration.
3975
                                                              (line   6)
3976
* section pmu:                           Power Management Configuration.
3977
                                                              (line   6)
3978
* section sim:                           Simulator Behavior.  (line   6)
3979
* section uart:                          UART Configuration.  (line   6)
3980
* section vapi:                          Verification API Configuration.
3981
                                                              (line   6)
3982
* section vga:                           Display Interface Configuration.
3983
                                                              (line   6)
3984
* sections:                              Global Data Structures.
3985
                                                              (line  49)
3986
* sectors (ATA/ATAPI device configuration): Disc Interface Configuration.
3987
                                                              (line 125)
3988
* server_port (debug interface configuration): Debug Interface Configuration.
3989
                                                              (line  69)
3990
* server_port (verification API configuration): Verification API Configuration.
3991
                                                              (line  19)
3992
* set (Interactive CLI):                 Interactive Command Line.
3993
                                                              (line 146)
3994
* set breakpoint (Interactive CLI):      Interactive Command Line.
3995
                                                              (line  57)
3996
* setdbch (Interactive CLI):             Interactive Command Line.
3997
                                                              (line 141)
3998
* simple model:                          Configuring the Build.
3999
                                                              (line  32)
4000
* simulator configuration:               Simulator Behavior.  (line   6)
4001
* simulator configuration info (Interactive CLI): Interactive Command Line.
4002
                                                              (line 119)
4003
* simulator reset (Interactive CLI):     Interactive Command Line.
4004
                                                              (line  63)
4005
* simulator statistics (Interactive CLI): Interactive Command Line.
4006
                                                              (line  83)
4007
* size (ATA/ATAPI device configuration): Disc Interface Configuration.
4008
                                                              (line 109)
4009
* size (generic peripheral configuration): Generic Peripheral Configuration.
4010
                                                              (line  30)
4011
* size (memory configuration):           Memory Configuration.
4012 98 jeremybenn
                                                              (line  92)
4013 19 jeremybenn
* sleep mode (power management register): Power Management Configuration.
4014
                                                              (line  16)
4015
* slow down factor (power management register): Power Management Configuration.
4016
                                                              (line  12)
4017
* SME (power management register):       Power Management Configuration.
4018
                                                              (line  16)
4019
* sockif (Ethernet configuration):       Ethernet Configuration.
4020
                                                              (line  83)
4021
* sr (CPU configuration):                CPU Configuration.   (line  53)
4022
* stall (Interactive CLI):               Interactive Command Line.
4023
                                                              (line  72)
4024
* stall the processor (Interactive CLI): Interactive Command Line.
4025
                                                              (line  72)
4026
* statistics, register over time:        Configuring the Build.
4027
                                                              (line  64)
4028
* statistics, simulation (Interactive CLI): Interactive Command Line.
4029
                                                              (line  83)
4030
* stats (Interactive CLI):               Interactive Command Line.
4031
                                                              (line  83)
4032
* stepping code (Interactive CLI):       Interactive Command Line.
4033
                                                              (line  19)
4034
* store_hitdelay (data cache configuration): Cache Configuration.
4035
                                                              (line  54)
4036
* store_missdelay (data cache configuration): Cache Configuration.
4037
                                                              (line  58)
4038
* SUME (power management register):      Power Management Configuration.
4039
                                                              (line  24)
4040 98 jeremybenn
* superscalar (CPU configuration):       CPU Configuration.   (line  63)
4041 19 jeremybenn
* suspend mode (power management register): Power Management Configuration.
4042
                                                              (line  24)
4043
* t (Interactive CLI):                   Interactive Command Line.
4044
                                                              (line  19)
4045
* TCP/IP port range:                     Verification API Configuration.
4046
                                                              (line  23)
4047
* TCP/IP port range for or1ksim service: Debug Interface Configuration.
4048
                                                              (line  74)
4049
* TCP/IP port range for or1ksim-rsp service: Debug Interface Configuration.
4050
                                                              (line  41)
4051 82 jeremybenn
* tests, all enabled.:                   Configuring the Build.
4052
                                                              (line 128)
4053 19 jeremybenn
* timings_file (CUC configuration):      CUC Configuration.   (line  46)
4054
* timings_fn (CUC configuration - deprecated): CUC Configuration.
4055
                                                              (line  46)
4056
* toggle breakpoint (Interactive CLI):   Interactive Command Line.
4057
                                                              (line  57)
4058
* toggle debug channels (Interactive CLI): Interactive Command Line.
4059
                                                              (line 141)
4060
* toggle debug mode (Interactive CLI):   Interactive Command Line.
4061
                                                              (line 151)
4062
* tx_channel (Ethernet configuration):   Ethernet Configuration.
4063
                                                              (line  60)
4064
* txfile (Ethernet configuration):       Ethernet Configuration.
4065
                                                              (line  69)
4066
* txfile (frame buffer configuration):   Frame Buffer Configuration.
4067 82 jeremybenn
                                                              (line  36)
4068 19 jeremybenn
* txfile (VGA configuration):            Display Interface Configuration.
4069
                                                              (line  47)
4070
* type (ATA/ATAPI device configuration): Disc Interface Configuration.
4071
                                                              (line  99)
4072
* type (memory configuration):           Memory Configuration.
4073 98 jeremybenn
                                                              (line  36)
4074 19 jeremybenn
* type=pattern (memory configuration):   Memory Configuration.
4075 98 jeremybenn
                                                              (line  46)
4076 19 jeremybenn
* type=random (memory configuration):    Memory Configuration.
4077 98 jeremybenn
                                                              (line  40)
4078 19 jeremybenn
* type=unknown (memory configuration):   Memory Configuration.
4079 98 jeremybenn
                                                              (line  50)
4080 19 jeremybenn
* type=zero (memory configuration):      Memory Configuration.
4081 98 jeremybenn
                                                              (line  54)
4082 19 jeremybenn
* UART configuration:                    UART Configuration.  (line   6)
4083
* UART I/O from/to a physical serial port: UART Configuration.
4084
                                                              (line  62)
4085
* UART I/O from/to an xterm:             UART Configuration.  (line  38)
4086
* UART I/O from/to files:                UART Configuration.  (line  33)
4087
* UART I/O from/to open file descriptors: UART Configuration. (line  58)
4088
* UART I/O from/to TCP/IP:               UART Configuration.  (line  45)
4089
* UART verification (VAPI):              Verification API.    (line  41)
4090
* unstall (Interactive CLI):             Interactive Command Line.
4091
                                                              (line  78)
4092
* unstall the processor (Interactive CLI): Interactive Command Line.
4093
                                                              (line  78)
4094
* upr (CPU configuration):               CPU Configuration.   (line  21)
4095
* ustates (cache configuration):         Cache Configuration. (line  33)
4096
* ustates (MMU configuration):           Memory Management Configuration.
4097
                                                              (line  41)
4098
* VAPI configuration:                    Verification API Configuration.
4099
                                                              (line   6)
4100
* VAPI for Debug Unit:                   Verification API.    (line  34)
4101
* VAPI for DMA:                          Verification API.    (line  73)
4102
* VAPI for Ethernet:                     Verification API.    (line  78)
4103
* VAPI for GPIO:                         Verification API.    (line  88)
4104
* VAPI for UART:                         Verification API.    (line  41)
4105
* vapi_id (debug interface configuration): Debug Interface Configuration.
4106
                                                              (line  80)
4107
* vapi_id (DMA configuration) <1>:       Ethernet Configuration.
4108
                                                              (line  88)
4109
* vapi_id (DMA configuration):           DMA Configuration.   (line  38)
4110
* vapi_id (GPIO configuration):          GPIO Configuration.  (line  32)
4111
* vapi_id (UART configuration):          UART Configuration.  (line  85)
4112
* vapi_log_file (verification API configuration): Verification API Configuration.
4113
                                                              (line  41)
4114
* vapi_log_fn (verification API configuration - deprecated): Verification API Configuration.
4115
                                                              (line  41)
4116
* ver (CPU configuration):               CPU Configuration.   (line  15)
4117
* verbose (simulator configuration):     Simulator Behavior.  (line  10)
4118
* Verification API configuration:        Verification API Configuration.
4119
                                                              (line   6)
4120
* Verilog memory dump (Interactive CLI): Interactive Command Line.
4121
                                                              (line 124)
4122
* VGA configuration:                     Display Interface Configuration.
4123
 
4124
 
4125
                                                              (line  50)
4126
4127
4128

4129
Tag Table:
4130 100 julius
Node: Top918
4131
Node: Installation1328
4132
Node: Preparation1575
4133
Node: Configuring the Build1870
4134
Node: Build and Install7349
4135
Node: Known Issues8195
4136
Node: Usage10336
4137
Node: Standalone Simulator10550
4138
Node: Profiling Utility13453
4139
Node: Memory Profiling Utility14363
4140
Node: Simulator Library15728
4141
Node: Configuration21920
4142
Node: Configuration File Format22529
4143
Node: Configuration File Preprocessing22821
4144
Node: Configuration File Syntax23192
4145
Node: Simulator Configuration25977
4146
Node: Simulator Behavior26268
4147
Node: Verification API Configuration30312
4148
Node: CUC Configuration32252
4149
Node: Core OpenRISC Configuration34169
4150
Node: CPU Configuration34671
4151
Node: Memory Configuration38788
4152
Node: Memory Management Configuration45246
4153
Node: Cache Configuration47623
4154
Node: Interrupt Configuration50009
4155
Node: Power Management Configuration50745
4156
Node: Branch Prediction Configuration52022
4157
Node: Debug Interface Configuration53382
4158
Node: Peripheral Configuration57602
4159
Node: Memory Controller Configuration58228
4160
Node: UART Configuration61642
4161
Node: DMA Configuration65161
4162
Node: Ethernet Configuration67028
4163
Node: GPIO Configuration71004
4164
Node: Display Interface Configuration72637
4165
Node: Frame Buffer Configuration74946
4166
Node: Keyboard Configuration76810
4167
Node: Disc Interface Configuration79048
4168
Node: Generic Peripheral Configuration83991
4169
Node: Interactive Command Line86286
4170
Node: Verification API93260
4171
Node: Code Internals97690
4172
Node: Coding Conventions98250
4173
Node: Global Data Structures102677
4174
Node: Concepts105334
4175
Ref: Output Redirection105479
4176
Node: Internal Debugging106018
4177
Node: GNU Free Documentation License106515

powered by: WebSVN 2.1.0

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