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

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [orpsocv2/] [doc/] [orpsoc.texi] - Blame information for rev 408

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

Line No. Rev Author Line
1 397 julius
\input texinfo   @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename orpsoc.info
4
@settitle ORPSoC manual 0.1
5
@include config.texi
6
@c %**end of header
7
 
8
@copying
9
This file documents the OpenRISC Reference Platform SoC, @value{ORPSOC}.
10
 
11
Copyright @copyright{} 2010 OpenCores
12
 
13
@quotation
14
Permission is granted to copy, distribute and/or modify this document
15
under the terms of the GNU Free Documentation License, Version 1.2 or
16
any later version published by the Free Software Foundation; with no
17
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
18
Texts.  A copy of the license is included in the section entitled ``GNU
19
Free Documentation License''.
20
@end quotation
21
@end copying
22
 
23
@setchapternewpage on
24
@settitle @value{ORPSOC} User Guide
25
 
26
@syncodeindex fn cp
27
@syncodeindex vr cp
28
 
29
@titlepage
30
@title @value{ORPSOC} User Guide
31
@c @subtitle subtitle-if-any
32
@c @subtitle second-subtitle
33
@author Julius Baxter
34
@author OpenCores
35
@author Issue 1 for @value{ORPSOC}
36
 
37
@c  The following two commands
38
@c  start the copyright page.
39
@page
40
@vskip 0pt plus 1filll
41
@insertcopying
42
 
43
Published by OpenCores
44
@end titlepage
45
 
46
@c So the toc is printed at the start.
47
@contents
48
 
49
@ifnottex
50
@node Top
51
@top Scope of this Document
52
 
53
This document is the user guide for @value{ORPSOC}, the OpenRISC Reference Platform System on Chip project.
54
 
55
@end ifnottex
56
 
57
@menu
58
* Introduction::
59
* Project Organisation::
60
* Getting Started::
61
* Reference Design::
62
* Board Designs::
63 408 julius
* ORDB1A3PE1500::
64 397 julius
* GNU Free Documentation License::  The license for this documentation
65
* Index::
66
@end menu
67
 
68 408 julius
@node Document Introduction
69 397 julius
@chapter Introduction
70
 
71
@cindex introduction to this @value{ORPSOC}
72
 
73
@value{ORPSOC} is intended to be a reference implementation of processors in the OpenRISC family. It provides a smallest-possible reference system, primarily for testing of the processors, and systems intended to be synthesized and run on physical hardware (boards.) The simple refernce system contains just enough to test the processor's functionality, whereas the board targeted builds will include many additional peripherals.
74
 
75
The reference design will contain a minimal set of resources to create an OpenRISC-based SoC. It is expected the board builds will contain their own set of peripheral modules and software, and still draw upon the resources available in the reference implementation. It is hoped that, with this structure, the project can serve dual roles; to be a development platform for OpenRISC family processors, and to provide a platform for development of complex OpenRISC-based systems on chip.
76
 
77
This document, the user guide, focuses on getting the various designs in @value{ORPSOC} up and running. For matters relating to development of a board port, see the development guide included with this documentation.
78
 
79
@c ****************************************************************************
80
@c Project Organisation
81
@c ****************************************************************************
82
 
83
@node Project Organisation
84
@chapter Project Organisation
85
@cindex organisation of @value{ORPSOC} project
86
 
87
@menu
88
* Overview::
89
* Software::
90
* RTL::
91
* Testbenches::
92
* Reference And Board Designs::
93
@end menu
94
 
95 408 julius
@node Organisation Overview
96
@section Organisation Overview
97 397 julius
 
98
The @value{ORPSOC} project is intended for dual uses. One is to act as a development platform for OpenRISC processors, as well as development of complex OpenRISC-based SoCs. Organising a single project to satisfy these requirements can lead to some confusion. This section is intended to make the organisation of the project clear.
99
 
100
In essense, the reference implementation based in the root of the project contains enough to get a simple OpenRISC-based SoC together, the board builds are intended to implement fully-featured systems. The project is organised in such a way that the board builds can use both the reference implementation's RTL and software, as well as its own set of RTL and software. The reference implementation, however, cannot use any board's modules, software or scripts.
101
 
102
The following sections outline the organisation of the software, RTL, and board designs.
103
 
104 408 julius
@node Software Organisation
105 397 julius
@section Software
106
 
107
The @code{sw} path contains primarily target software (code intended for cross-compilation and execution on an OpenRISC processor) and a few custom tools for manipulation of binary software images.
108
 
109
Driver software, implementing access functions for hardware modules, are found under @code{sw/drivers}. There is the concept of a CPU library, providing CPU-specific functions, which can be changed to support different versions of OpenRISC processors. There is also a minimal support library under the @code{sw/lib} path. Both drivers and support library are compiled together to create a library called @code{liborpsoc} which is placed in @code{sw/lib}.
110
 
111
Test software is found under @code{sw/tests}. Typically, each is for a specific module, or for a particular capability (eg. tests for the UART capability are under @code{sw/tests/uart}, rather than @code{sw/tests/uart16550} which.) There are no specific rules here.
112
 
113
Under each test directory are two directories, @code{board} and @code{sim}, containing the test software targeted at each. Code for simulation will produce less printfs and perhaps not run as long as tests intended to run at full speed on target.
114
 
115
There are for naming software tests, so the automation scripts can locate them. The test directory name must be a single word (potentially with underscores), and then the tests must be in files of the format @emph{testdirname}-@emph{testname}.extension, eg. @code{uart-simple.c} or @code{or1200-fp.S}.
116
 
117 408 julius
@node RTL Organisation
118 397 julius
@section RTL
119
 
120
The HDL code layout conforms to those outlined in the OpenCores.org coding guidelines. http://cdn.opencores.org/downloads/opencores_coding_guidelines.pdf
121
 
122
Beyond that, there are some rules for the naming in modules. The directory name (presumably the name of the module, something like @code{uart16550}) should also be the name of the top level file, eg. @code{uart16550.v}, and the top level module should also be simply this name, eg. @code{module uart16550 (...}.
123
 
124 408 julius
@node Testbench Organisation
125
@section Testbench
126 397 julius
 
127
For each design in @value{ORPSOC} there will be a testbench instantiating the top level, and any peripherals (at least, as many as there are models for.)
128
 
129
Despite this being far from a thorough verification platform, it is considered useful to be able to perform enough simulation to ensure that the fundamental system is correctly assembled and can communicate with the peripherals. However, this is not intended as a platform for peripheral development (although, it very well could be) the board designs are not expected to have thorough peripheral tests. They are expected to have just enough to prove that basic functionality.
130
 
131 408 julius
@node Organisation of Reference And Board Designs
132 397 julius
@section Reference And Board Designs
133
 
134
The goal of the reference design is to provide an environment to develop and test OpenRISC processors (also, potentially, basic components.) The goal of the various board-targeted designs is to provide ready-to-go implementations for hardware.
135
 
136
Typically, a board-targeted design will wish to reuse common components (processor, debug interface, Wishbone arbiters, UART etc.) The project has been configured to allow a board build to use either modules available in the ``common'' RTL path (@code{rtl/verilog/}) as well as those in their ``local'' RTL path (something like @code{boards/vendor/boardname/rtl/verilog}). In the event that some particular modification to a module in the common RTL set is desired for a particular board build, that module can simply be copied into the board's ``local'' RTL path and the scripts will that version instead of the common one.
137
 
138
 
139
 
140
@c ****************************************************************************
141
@c Getting started
142
@c ****************************************************************************
143
 
144
@node Getting Started
145
@chapter Getting Started
146
@cindex source files for @value{ORPSOC}, downloading
147
 
148
@menu
149
* Supported Platforms::
150
* Obtaining Project Source::
151
* Required Tools::
152
@end menu
153
 
154 408 julius
@node Getting Started Supported Platforms
155 397 julius
@section Supported Platforms
156
@cindex platforms supported by the @value{ORPSOC} project
157
 
158
At present the majority of  @value{ORPSOC}'s development occurs with tools that run under the GNU/Linux operating system. All of the tools required to run the basic implementation are free, open source, and easily installable in any modern GNU/Linux distribution.
159
 
160
Unless indicated otherwise, support for the project under Cygwin on Microsoft Windows platforms is not a given.
161
 
162
 
163 408 julius
@node Getting Started Obtaining Project Source
164 397 julius
@section Obtaining Project Source
165
@cindex getting a copy of the @value{ORPSOC} project
166
 
167
The source for @value{ORPSOC} can be obtained from the OpenCores subversion (SVN) server.
168
 
169
@example
170
@kbd{svn export http://opencores.org/ocsvn/openrisc/openrisc/trunk/orpsocv2}
171
@end example
172
 
173 408 julius
@node Getting Started Required Tools
174 397 julius
@section Required Tools
175
@cindex tools and utilities required for @value{ORPSOC}
176
 
177
 
178
Performing the installation of tools required to design, simulate, verify, compile and debug a SoC is not for the faint hearted. The various sets of tools must be first installed, and the user's environment configured to allow them to run correctly.
179
 
180
First the host system must be capable of building and running development tools, next the various compilers, simulators and utilities must be installed, and finally, if required, additional tools to interact with the built design are installed. Once complete, the set up rarely needs to be touched, and results in grealty improved productivity.
181
 
182
The required tools can be divided into four groups.
183
 
184
@itemize @bullet
185
@item
186
Host system tools - things like gcc, make, texinfo.
187
 
188
@item
189
Target system toolchain and software - the OpenRISC GNU toolchain, with gcc crosscompiler, support libraries, the GNU debugger (gdb), OpenRISC port of various OSes and RTOS, etc.
190
 
191
@item
192
Electronic design automation (EDA) tools - preprocessors, simulators, FPGA tool suites, etc.
193
 
194
@item
195
Debug tools - tools providing control over the system on target
196
@end itemize
197
 
198
The first two items are likely to be the same for most of the designs included in @value{ORPSOC}, however the final two can vary greatly depending on the FPGA vendor, part and configuration, and the application of the SoC design.
199
 
200
There will be a section on the tools for each design in @value{ORPSOC}. This section is intended to provide a list of tools required for each particular build. Any lengthy instructions on installing a particular tool will be attached as an appendix, which can be references by several build prerequisite lists in order to save repetition of information.
201
 
202
Anyone implementing their own board port is encouraged to document, as best they can, any problematic tool installations and contribute them to this document.
203
 
204
 
205
 
206
@c ****************************************************************************
207
@c Reference Design chapter
208
@c ****************************************************************************
209
 
210
@node Reference Design
211
@chapter Reference Design
212
@cindex reference design
213
 
214
@menu
215
* Overview::
216
* Structure::
217
* Tools::
218
* Simulation::
219
* Synthesis::
220
@end menu
221
 
222 408 julius
@node Reference Design Overview
223 397 julius
@subsection Overview
224
 
225
The reference design included in @value{ORPSOC} is intended to be the minimal implementation (or thereabouts) of a SoC required to exercise an OpenRISC processor. In this regard, very little apart from the processor, memory, debug interface and interconnect modules are instantiated.
226
 
227
The primary role for this design is to implement a system that an OpenRISC processor can be instaniated in for for development purposes. The automated testing mechanism, capable of compiling, executing and checking software on the design, is used as a method of regression testing for the processor as it is developed. After features are added or modified in the processor, new software tests can be added to the existing suite, checking for the expected functionality and ensuring legacy behavior is also unchanged.
228
 
229
The design can be simulated two ways. The first uses the standard event-driven simulators such as Icarus Verilog and Mentor Graphics' Modelsim. The second method involves creating a cycle accurate (C or SystemC) model from the Verilog HDL description using the Verilator tool.
230
 
231
The simulations begin with the desired software image preloaded in memory. For debugging the design, the models provide an interface to the system allowing the GNU debugger to control the target processor in a manner similar to that of physical hardware.
232
 
233
The design is not intended for implementation on an FPGA or ASIC, rather purely for development and testing in simulation environments. The board targeted builds in the @value{ORPSOC} project, however, are intended for implementation on hardware.
234
 
235 408 julius
@node Reference Design Structure
236 397 julius
@subsection Structure
237
 
238
@menu
239
* Overview::
240
* RTL::
241
* Software::
242
* Simulation::
243
@end menu
244
 
245 408 julius
@node Reference Design Overview
246 397 julius
@subsubsection Overview
247
 
248
The reference design's paths are all based in the root directory of @value{ORPSOC}. This is different from the board-targeted builds, which are based in their specific board paths.
249
 
250
As synthesis and physical implementation is not intended for the reference design there are no @code{syn} or @code{backend} paths in the root directory of @value{ORPSOC}.
251
 
252 408 julius
@node Reference Design RTL
253 397 julius
@subsubsection RTL
254
 
255
At present only Verilog HDL is included in the reference implementation of @value{ORPSOC}, as the open source tools intended to simulate the design do not support VHDL.
256
 
257
The directory structure consists of an @code{rtl} directory in the root, and a @code{verilog} path under that. Within the @code{rtl/verilog} path, each module has its own directory.
258
 
259
A common Verilog include path, @code{rtl/verilog/include} directory is used. The Verilog HDL include files for each module should be moved here. This allows each @value{ORPSOC} implementation (board design) to maintain their own include path, and thus configure the modules for their specific implementation.
260
 
261 408 julius
@node Reference Design Software
262 397 julius
@subsubsection Software
263
 
264
The software run on the reference design is found in the @value{ORPSOC} root directory, under the @code{sw} path.
265
 
266
The test software for the or1200 processor is found under @code{sw/tests/or1200/sim}.
267
 
268
A minimal set of drivers is built into @code{liborpsoc}, and they are found under @code{sw/tests/drivers}.
269
 
270
In addition to these drivers, a set of support C functions is build into @code{liborpsoc}, which are found in the @code{sw/lib} path.
271
 
272 408 julius
@node Reference Design Simulation
273 397 julius
@subsubsection Simulation
274
 
275
The simulation of the reference design is run from the @code{sim/run} path.
276
 
277
The script controlling simulation is the file @code{sim/bin/Makefile}.
278
 
279
The generated output is kept in the @code{sim/out} path, and is cleared away when @kbd{make clean} is run.
280
 
281
When the Verilator-processed cycle accurate model is built, it is done in the @code{sim/vlt} path, which is also cleaned away when @kbd{make clean} is run.
282
 
283 408 julius
@node Reference Design Tools
284 397 julius
@subsection Tools
285
 
286
@menu
287
* Host Tools::
288
* Target System Tools::
289
* EDA Tools::
290
* Debug Tools::
291
@end menu
292
 
293 408 julius
@node Reference Design Host Tools
294 397 julius
@subsubsection Host Tools
295
@cindex host tools required
296
 
297
Standard development suite of tools: gcc, make, etc.
298
 
299 408 julius
@node Reference Design Target System Tools
300 397 julius
@subsubsection Target System Tools
301
@cindex target system tools required
302
 
303
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
304
 
305 408 julius
@node Reference Design EDA Tools
306 397 julius
@subsubsection EDA Tools
307
@cindex EDA tools required
308
 
309
RTL simulation: Icarus Verilog (also compatible with Mentor Graphics' Modelsim)
310
Cycle Accurate Simulation: Verilator, Verilog-Perl, System-Perl, SystemC
311
 
312 408 julius
@node Reference Design Debug Tools
313 397 julius
@subsubsection Debug Tools
314
@cindex Debug tools required
315
 
316
None. The target is purely simulation, no extra utilities are required to debug.
317
 
318
 
319 408 julius
@node Reference Design Simulation
320 397 julius
@subsection Simulation
321
 
322
@menu
323
* RTL::
324
* Cycle Accurate::
325
* Results::
326
@end menu
327
 
328 408 julius
@node Reference Design RTL
329 397 julius
@subsubsection RTL
330
@cindex rtl simulation of reference design
331
 
332
All simulations of the reference design are run from the @code{sim/run} path.
333
 
334
@subsubheading Running RTL Regression Test
335
 
336
The simplest way of starting a run through the regression test, using the default RTL simulator, Icarus Verilog, can be done with:
337
 
338
@example
339
@kbd{make rtl-tests}
340
@end example
341
 
342 408 julius
This will compile the software and RTL, and run a new simulation for each software test. Defining which tests are run is the variable @code{TESTS}, set by default in the @code{sw/bin/Makefile} script. Other default options are that a processor execution log is generated (in @code{sim/out/@emph{testname}-executed.log}), but VCDs are not.
343 397 julius
 
344
@subsubheading Running An Individual Test
345
 
346
An individual test can be run, by specifying the test name through the @code{TEST} environment variable (which must correspond to a file in @code{sw/tests/@emph{module}/sim/} where @code{@emph{module}} is the name of the module to be tested. In the following example the test @emph{or1200-basic} is run.
347
 
348
@example
349
@kbd{make rtl-test TEST=or1200-basic}
350
@end example
351
 
352 408 julius
@node Running A Set Of Specific Reference Design RTL Tests
353 397 julius
@subsubheading Running A Set Of Specific Tests
354
 
355
A specific set of tests can be run in the same fashion as the regression tests but with the actual tests to run set in the @code{TESTS} environment variable.
356
 
357
@example
358
@kbd{make rtl-tests TESTS="sdram-rows uart-simple or1200-mmu or1200-fp"}
359
@end example
360
 
361 408 julius
@node Options For Reference Design RTL Tests
362 397 julius
@subsubheading Options For RTL Tests
363
 
364
There are some options, which can be specified through shell environment variables when running the test.
365
 
366
@table @code
367
 
368
@item VCD
369 408 julius
Set to '1' to enable @emph{value change dump} (VCD) creation in @code{sim/out/@emph{testname}.vcd}
370 397 julius
 
371
@item VCD_DELAY
372
Delay VCD creation start time by this number of timesteps (used as a Verilog @code{#delay} in the testbench.)
373
 
374
@item VCD_DELAY_INSNS
375
Delay VCD creation start time until this number of instructions has been executed by the processor. Useful for creating a dump just before a bug exhibited and correlated to an instruction number (from execution trace file.)
376
 
377
@item END_TIME
378
Force simulation end (@code{$finish}) at this time.
379
 
380
@item DISABLE_PROCESSOR_LOGS
381
Turn off processor monitor's execution trace generation. This helps speed up the simulation (less time writing to files) and avoids creating very large execution logs (in the GBs) for very long simulations.
382
 
383
@item SIMULATOR
384
Specify simulator to use. Default is Icarus Verilog, can be set to @code{modelsim} to use Mentor Graphics' Modelsim. No others are supported right now.
385
 
386
@end table
387
 
388
 
389
 
390 408 julius
@node Reference Design Cycle Accurate
391 397 julius
@subsubsection Cycle Accurate
392
@cindex cycle accurate simulation of reference design
393
 
394
@subsubheading Running Cycle Accurate Regression Test
395
 
396
The simplest way of starting a run through the regression test using the cycle accurate model can be done with:
397
 
398
@example
399
@kbd{make vlt-tests}
400
@end example
401
 
402
This will build the cycle accurate model and run a new simulation for each software test. Defining which tests are run is the variable @code{TESTS}, set by default in the @code{sw/bin/Makefile} script.
403
 
404
@subsubheading Running An Individual Test
405
 
406
An individual test can be run, by specifying the test name through the @code{TEST} environment variable (which must correspond to a file in @code{sw/tests/@emph{module}/sim/} where @code{@emph{module}} is the name of the module to be tested. In the following example the test @emph{or1200-basic} is run.
407
 
408
@example
409
@kbd{make vlt-test TEST=or1200-basic}
410
@end example
411
 
412
@subsubheading Generating Cycle Accurate Simulator Executable
413
 
414
The cycle accurate model is somewhat similar to the OpenRISC architectural simulator, in that it can be run as a standalone application, although it is not as configurable at runtime. The standalone application can be built with the following command from the @code{sim/run} path.
415
 
416
@example
417
@kbd{make prepare-vlt}
418
@end example
419
 
420
The resulting executable will be @emph{Vorpsoc_top} in the @code{sim/vlt} path. Run it with the @emph{-h} option for usage instructions.
421
 
422
@subsubheading Generating Automatically Profiled Cycle Accurate Simulator Executable
423
 
424
An automatic profiling and compilation set of commands in the script can be used to create a higher performance cycle accurate model. The following make target will first compile the cycle accurate design to generate profiling outputs, run some software, and recompile using the profiling information.
425
 
426
@example
427
@kbd{make prepare-vlt-profiled}
428
@end example
429
 
430
@subsubheading Cycle Accurate Model Executable Usage
431
 
432
The executable generated by running any of the above commands is in the @code{sim/vlt} path. The usage options can be listed by running it with the @code{--help} switch.
433
 
434
@example
435
@kbd{Vorpsoc_top --help}
436
@end example
437
 
438
A short list of options is given here.
439
 
440
@table @code
441
 
442
@item -f @var{file}
443
@itemx --program @var{file}
444
@cindex @code{-f}
445
@cindex @code{--program}
446
Load software from OR32 ELF image @var{file}
447
 
448
If unspecified, model attempts to load VMEM file @code{sram.vmem}
449
 
450
@item -v
451
@itemx --vcd
452
@cindex @code{-v}
453
@cindex @code{--vcd}
454
Dump VCD file
455
 
456
@item -e @var{value}
457
@itemx --endtime @var{value}
458
@cindex @code{-e}
459
@cindex @code{--endtime}
460
End simulation after @var{value} simulated ns
461
 
462
@item -l @var{file}
463
@itemx --log @var{file}
464
@cindex @code{-l}
465
@cindex @code{--log}
466
Log processor execution trace to @var{file}
467
 
468
@end table
469
 
470 408 julius
@node Reference Design Results
471 397 julius
@subsubsection Results
472
@cindex output from simulation of reference design
473
 
474
The following files are generted from the event driven simulation. For output options of the cycle accurate model, see the section on Cycle Accurate Model Executable Usage.
475
 
476
@subsubheading Processor Execution Trace
477
 
478
A trace of the processor after each executed instruction is generated by both the event and cycle accurate models.
479
 
480
In the event driven simulations, the log is created by default, and is stored in @code{sim/out} and will be named @code{@emph{test-name}-executed.log}.
481
 
482
@subsubheading Processor SPR Access Log
483
 
484
A list of processor special purpose registers (SPR) accesses is created when processor logging is enabled.
485
 
486
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-sprs.log}.
487
 
488
@subsubheading Processor Instruction Excecution Time Log
489
 
490
A list of when each instruction was executed is generated when processor execution logging is enabled.
491
 
492
This is useful when debugging with VCD, and detecting at what time the problematic instructions were executed.
493
 
494
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-lookup.log}.
495
 
496
@subsubheading Processor Report Mechanism Log
497
 
498
The use of the processor's report mechanism is commonplace in the test software, as it allows for the checking of intermediate values after simulation.
499
 
500
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-general.log}. This is not optional.
501
 
502
@subsubheading Value Change Dump (VCD)
503
 
504
When VCD files are generated they are placed in the @code{sim/out} path, and are named @code{@emph{test-name}.vcd}. They should be viewable with programs like @emph{GTKWave}.
505
 
506
 
507 408 julius
@node Reference Design Synthesis
508 397 julius
@subsection Synthesis
509
 
510
The reference design is not intended to be synthesised, and thus no backend scripts are provided. See the sections on the board-specific builds.
511
 
512
 
513
@c ****************************************************************************
514 408 julius
@c ORDB1A3PE1500 board build chapter
515 397 julius
@c ****************************************************************************
516
 
517 408 julius
@node ORDB1A3PE1500
518
@chapter ORDB1A3PE1500
519
@cindex ORDB1A3PE1500 board build information
520 397 julius
 
521
@menu
522
* Overview::
523
* Structure::
524
* Tools::
525
* Simulating::
526 408 julius
* Synthesis and Backend::
527
* Programming File Generation::
528
* Customising::
529 397 julius
@end menu
530
 
531 408 julius
@node ORDB1A3PE1500 Overview
532 397 julius
@subsection Overview
533
 
534 408 julius
The ORDB1 (ORSoC development board 1) with Actel A3PE1500 FPGA is supported by this build.
535 397 julius
 
536 408 julius
As the ORDB1 is intended to be a daughter board for a variety of I/O boards its options for configuration are extensive.
537
 
538
This board port of ORPSoC implements an example of a configurable system, with many cores that can be enabled or disabled as required by the expansion board's capabilities.
539
 
540
The port was mainly developed with the ORSoC ethernet expansion board (OREEB1), and was used with the OpenRISC port of the Linux kernel and BusyBox suite running network applications.
541
 
542
This guide will overview how to simulation, synthesize and customise the system.
543
 
544
@node ORDB1A3PE1500 Structure
545 397 julius
@subsection Structure
546
 
547 408 julius
Note that in this chapter the term @emph{board path} refers to the path in the project for this board port; @code{boards/actel/ordb1a3pe1500}.
548 397 julius
 
549 408 julius
The board port's structure is similar to that of a standalone project which accords with the OpenCores coding guidelines. However, all software and RTL that is available in the reference design is also available to the board port, with any local (ie. in the board's @code{rtl} or @code{sw} paths) versions taking precedence over the versions available in the reference design.
550
 
551
The Verilog RTL specific to this board is under @code{rtl/verilog} in the board path. The @code{include} path in there is the place where all required definitions files, configuring the RTL, are found.
552
 
553
Backend files, things such as PLLs and buffers generated by Actel's @emph{smartgen} tool, are found in the board's @code{backend/rtl/verilog} path.
554
 
555
@node ORDB1A3PE1500 Tools
556 397 julius
@subsection Tools
557
 
558
@menu
559
* Host Tools::
560
* Target System Tools::
561
* EDA Tools::
562
* Debug Tools::
563
@end menu
564
 
565 408 julius
@node ORDB1A3PE1500 Host Tools
566 397 julius
@subsubsection Host Tools
567 408 julius
@cindex host tools required ORDB1A3PE1500
568 397 julius
 
569
Standard development suite of tools: gcc, make, etc.
570
 
571 408 julius
@node ORDB1A3PE1500 Target System Tools
572 397 julius
@subsubsection Target System Tools
573 408 julius
@cindex target system tools required ORDB1A3PE1500
574 397 julius
 
575
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
576
 
577 408 julius
@node ORDB1A3PE1500 EDA Tools
578 397 julius
@subsubsection EDA Tools
579 408 julius
@cindex EDA tools required ORDB1A3PE1500
580 397 julius
 
581
RTL, gatelevel simulation: Mentor Graphics' Modelsim
582
Synthesis: Synopsys Synplify (included in Actel Libero Suite)
583
Backend: Actel Designer (included in Actel Libero Suite)
584
Programming: Actel FlashPRO (included in Actel Libero Suite)
585
 
586 408 julius
This has been developed with Libero v8.6 for Linux.
587
 
588
@node ORDB1A3PE1500 Debug Tools
589 397 julius
@subsubsection Debug Tools
590 408 julius
@cindex Debug tools required ORDB1A3PE1500
591 397 julius
 
592
or_debug_proxy, ORPmon
593
 
594 408 julius
@node ORDB1A3PE1500 Simulating
595
@subsection Simulating
596
@cindex simulating ORDB1A3PE1500
597 397 julius
 
598 408 julius
@subsubheading Run RTL Regression Test
599
 
600
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
601
 
602
@example
603
@kbd{make rtl-tests}
604
@end example
605
 
606
The same set of options for RTL tests available in the reference design should available in this build. @xref{Running A Set Of Specific Reference Design RTL Tests}.
607
 
608
@node ORDB1A3PE1500 Synthesis
609
@subsection Synthesis
610
 
611
Synthesis of the board port for the Actel technology with the Synplify tool can be run in the board's @code{syn/synplify/run} path with the following command.
612
 
613
@example
614
@kbd{make all}
615
@end example
616
 
617
This will create a EDIF netlist in @code{syn/synplify/out}.
618
 
619
Hopefully it's all automated enough so that, as long as the design is simulating as desired, the correct set of RTL will be picked up and synthesized without any need for customising scripts for the tool.
620
 
621
@node ORDB1A3PE1500 Synthesis Options
622
@subsubsection Options
623
 
624
The following can be passed as environment variables when running @kbd{make all}.
625
 
626
@table @code
627
 
628
@item RTL_TOP
629
Default's to the designs top level module, @emph{orpsoc_top}, but if wishing to synthesize a particular module, its name (not instantiated name) should be set here.
630
 
631
@item FPGA_PART
632
Defaults to A3PE1500 but if targeting any other set it with this.
633
 
634
@item FPGA_FAMILY
635
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
636
 
637
@item FPGA_PACKAGE
638
Defaults to PQFP208 but if targeting any other set it with this.
639
 
640
@item FPGA_SPEED_GRADE
641
Defaults to Std but if targeting any other set it with this.
642
 
643
@item FREQ
644
Target frequency for synthesis.
645
 
646
@item MAXFAN
647
Maximum net fanout.
648
 
649
@item MAXFAN_HARD
650
Hard limit on maximum net fanout.
651
 
652
@item GLOBALTHRESH
653
Threshold of fanout before promoting signal to a global routing net.
654
 
655
@item RETIMING
656
Defaults to '1' (on) but set to '0' to disable.
657
 
658
@item RESOURCE_SHARING
659
Defaults to '1' (on) but set to '0' to disable.
660
 
661
@item DISABLE_IO_INSERTION
662
Defaults to '0' (off) but set to '1' to enable. Useful when synthesizing individual modules not intended as a top level.
663
 
664
@end table
665
 
666
@node ORDB1A3PE1500 Synthesis Warnings
667
@subsubsection Checks
668
 
669
The following is a list of some considerations before synthesis.
670
 
671
@itemize @bullet
672
@item bootrom.v
673
 
674
If the bootROM module is being used to provide the processor with a progrm at startup, check that board software include file, in the board's @code{sw/board/include} path, is selecting the correct bootROM program.
675
 
676
Do a @kbd{make clean-all} from the synthesis run directory to be sure that the previous bootROM file is cleared away and regenerated when synthesis is run.
677
 
678
 
679
@item Clean away old leftovers
680
 
681
If the unwanted files from an old synthesis run are still there before the next run, it's best to clean them away with @kbd{make clean} from the synthesis run directory.
682
 
683
 
684
@item Check Command Line Options
685
 
686
If using any command line settings, they can be checked by passing them to the following make target: @kbd{make print-config}
687
 
688
 
689
@end itemize
690
 
691
@node ORDB1A3PE1500 Place and Route
692
@subsection Place and Route
693
 
694
Place and route is run from the board's @code{backend/par/run} path with the following command.
695
 
696
@example
697
@kbd{make all}
698
@end example
699
 
700
This will create a @code{.adb} file in the same path.
701
 
702
All steps, up to programming file generation are done here. This is mainly a licensing thing (free liceneses for Libero under Linux @emph{do not} allow programming file generation - they do, however, under Windows.)
703
 
704
@node ORDB1A3PE1500 Place and route options
705
@subsubsection Options
706
 
707
Most of the design's parameters are deteremined by processing the @code{orpsoc-defines.v} file and determining, for example, the frequency of the clocks entering the design.
708
 
709
The following can be passed as environment variables when running @kbd{make all}.
710
 
711
@table @code
712
 
713
@item FPGA_PART
714
Defaults to A3PE1500 but if targeting any other set it with this.
715
 
716
@item FPGA_FAMILY
717
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
718
 
719
@item FPGA_PACKAGE
720
Defaults to ``208 PQFP'' but if targeting any other set it with this.
721
 
722
 
723
@item FPGA_SPEED_GRADE
724
Defaults to Std but if targeting any other set it with this.
725
 
726
@item FPGA_VOLTAGE
727
Defaults to 1.5 but if targeting any other set it with this.
728
 
729
@item FPGA_TEMP_RANGE
730
Defaults to COM but if targeting any other set it with this.
731
 
732
@item FPGA_VOLT_RANGE
733
Defaults to COM but if targeting any other set it with this.
734
 
735
@item PLACE_INCREMENTAL
736
Defaults to off.
737
 
738
@item ROUTE_INCREMENTAL
739
Defaults to off.
740
 
741
@item PLACER_HIGH_EFFORT
742
Defaults to off.
743
 
744
@item BOARD_CONFIG
745
Defaults to @code{orsoccpuexpio.mkpinassigns}
746
 
747
@end table
748
 
749
@node ORDB1A3PE1500 Constraints
750
@subsubsection Constraints
751
 
752
 
753
A @emph{synposys design constraints} (SDC) file, and @emph{physical design constraints} (PDC) file are generated automatically by the scripts. The main Verilog defines file is parsed to detect which modules are included in the design, and generates the appropriate constraints which are embedded in the Makefile.
754
 
755
 
756
The PDC relies on the @code{BOARD_CONFIG} environment variable to indicate which pin assignment file to pull into the Makefile (they live in @code{backend/par/bin}). The PDC also depends on the actual contents of the main place and route Makefile, @code{backend/par/bin/Makefile}.
757
 
758
 
759
By default these should have support for the peripherals included with ORPSoC. Double check, however, that the correct constraints are set, by running the following command before starting place and route.
760
 
761
@example
762
@kbd{make pdc-file sdc-file}
763
@end example
764
 
765
These can be generated and edited and then used when running place and route, they will not get replaced.
766
 
767
@node ORDB1A3PE1500 Programming File Generation
768
@subsection Programming File Generation
769
 
770
The @code{.adb} file resulting from place and route can be opened in the Actel @emph{Designer} tool and a programming file generated there.
771
 
772
Once this programming file is created, Actel's @emph{FlashPro} can used to program the ORDB1A3PE1500 board.
773
 
774
@node ORDB1A3PE1500 Customising
775
@subsection Customising
776
 
777
The versatile nature of the ORDB1A3PE1500 means the design that goes on it must be equally versatile, if not more so.
778
 
779
The following sections have information on how to configure the design.
780
 
781
@node ORDB1A3PE1500 Customising Enabling Existing Modules
782
@subsubsection Enabling Existing RTL Modules
783
 
784
The design relies on the Verilog HDL @emph{define} function to indicate which modules are included.
785
 
786
There are only a few modules included by deafult.
787
 
788
@itemize @bullet
789
@item Processor - @emph{or1200}
790
@item Clock and reset generation - @emph{clkgen}
791
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
792
@end itemize
793
 
794
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
795
 
796
Inspect that file to see which modules are able to be included. At present the list includes USB 1.1 host controller and/or slave interface, I2C master/slave core, and SPI master cores.
797
 
798
These cores should be supported and ready to go by just defining them (uncommont in the @code{orspco-defines.v} file.)
799
 
800
@node ORDB1A3PE1500 Customising Adding Modules
801
@subsubsection Adding RTL Modules
802
 
803
There are a number of steps to take when adding a new module to the design.
804
 
805
@itemize @bullet
806
@item RTL Files
807
 
808
Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
809
 
810
Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
811
 
812
Place any include files into the board's @code{rtl/verilog/include} path.
813
 
814
@item Instantiate in ORPSoC Top Level File
815
 
816
Instantiate the module in the ORPSoC top level file, @code{rtl/verilog/orpsoc_top/orpsoc_top.v}, and be sure to take care of the following.
817
@itemize @bullet
818
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
819
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
820
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
821
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
822
@item Update board's @code{rtl/verilog/include/orpsoc-params.v} file with appropriate set of parameters for new module, as well as arbiter memory mapping assignment.
823
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
824
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
825
@end itemize
826
 
827
@item Update ORPSoC Testbench
828
 
829
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
830
 
831
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
832
 
833
@item Add Software Drivers and Tests
834
 
835
In a similar fashion to what is already in the board's @code{sw/drivers} and @code{sw/tests} path, create desired driver and test software to be used during simulation (and potentially on target.)
836
 
837
@item Update Backend Scripts
838
 
839
If any I/O is added, or special timing specified, the board's backend main Makefile, @code{backend/par/bin/Makefile} and pinout files (in @code{backend/par/bin} wll need to be updated.
840
 
841
The section in @code{backend/par/bin/Makefile} mapping signals to Makefile variables will need to have these new signals added to them. The section in the file begins with @code{$(PDC_FILE):} and is actually a set of long bash lines.
842
 
843
Continuing the format already there should be easy enough. Rememeber that the @code{orspoc-defines.v} file is parsed and it's possible to tell if the module is included by testing if the variable is defined.
844
 
845
For example, to add I/Os for a module called @code{foo}, and in @code{orpsoc-defines.v} a value @code{FOO1} is defined, we can add I/Os @code{foo1_srx_i} and @code{foo1_tx_o[3:0]} with the following.
846
 
847
@example
848
@kbd{   $(Q)if [ ! -z $$FOO1 ]; then \
849
        echo "set_io foo1_srx_i " $(FOO_SRX_BUS_SETTINGS) " \
850
        -pinname "$(FOO1_SRX_PIN) >> $@; \
851
        echo "set_io foo1_tx_o\\[0\\] " $(FOO_TX_BUS_SETTINGS) " \
852
         -pinname "$(FOO1_TX0_PIN) >> $@; \
853
        echo "set_io foo1_tx_o\\[1\\] " $(FOO_TX_BUS_SETTINGS) "  \
854
        -pinname "$(FOO1_TX1_PIN) >> $@; \
855
        echo "set_io foo1_tx_o\\[2\\] " $(FOO_TX_BUS_SETTINGS) "  \
856
        -pinname "$(FOO1_TX2_PIN) >> $@; \
857
        echo "set_io foo1_tx_o\\[3\\] " $(FOO_TX_BUS_SETTINGS) "  \
858
        -pinname "$(FOO1_TX3_PIN) >> $@; \
859
        fi
860
       }
861
@end example
862
 
863
@emph{(ensure there is no whitespace after the trailing backslashes.)}
864
 
865
It's a little hard to follow, but it's essentially one @code{set_io} line for each I/O line.
866
 
867
First the line checks if the module's define was exported (which happens automatically if it's defined in @code{orpsoc-defines.v}.
868
 
869
Note that what is defined can be checked by running @kbd{make print-defines} in the board's @code{backend/par/run} path.
870
 
871
The values of the bus settings variables depend on the desired I/O standards and other examples in the Makefile can be referenced.
872
 
873
The pin numbers need to be set in the @code{.mkpinassigns} which is included intot he Makefile (according to the @code{BOARD_CONFIG} variable set when running the @code{make} command.)
874
 
875
These files are simple assignments of values to variables (and potentially then to other variables) which correspond to the variables finally used in the main Makefile.
876
 
877
The physical constraints file can be generated manually with the @kbd{make pdc-file} command.
878
 
879
@end itemize
880
 
881
 
882
 
883
 
884
 
885 397 julius
@c ****************************************************************************
886
@c End bits
887
@c ****************************************************************************
888
 
889
@node  GNU Free Documentation License
890
@chapter GNU Free Documentation License
891
@cindex license for @value{ORPSOC}
892
 
893
@include fdl-1.2.texi
894
 
895
@node Index
896
 
897
@unnumbered Index
898
 
899
@printindex cp
900
 
901
@bye
902
 

powered by: WebSVN 2.1.0

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