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

Subversion Repositories openrisc

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

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 468 julius
Copyright @copyright{} 2010,2011 OpenCores
12 397 julius
 
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 415 julius
* ML501::
65 468 julius
* Software::
66 397 julius
* GNU Free Documentation License::  The license for this documentation
67
* Index::
68
@end menu
69
 
70 408 julius
@node Document Introduction
71 397 julius
@chapter Introduction
72
 
73
@cindex introduction to this @value{ORPSOC}
74
 
75 425 julius
@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. It also provides systems intended to be synthesized and run on physical hardware.
76 397 julius
 
77 425 julius
The reference system is the least complex implementation and consists of just enough to test the processor's functionality. The board-targeted builds include many additional peripherals.
78 397 julius
 
79 425 julius
The next section in this document outlines the organisation and structure of the project. The section ``@emph{Getting Started}'' goes through getting the project source and setting up any necessary tools. Each following section outlines a particular implementation of an OpenRISC-based system, beginning with the reference system. Each implementation section has an overview of the structure of the project (which probably won't vary much between the implementations), a section on setting up the required tools, running simulation, and if applicable, backend and debugging steps. There may be additional sections on modifying or customising each implementation system.
80 397 julius
 
81
@c ****************************************************************************
82
@c Project Organisation
83
@c ****************************************************************************
84
 
85
@node Project Organisation
86
@chapter Project Organisation
87
@cindex organisation of @value{ORPSOC} project
88
 
89
@menu
90
* Overview::
91
* Software::
92
* RTL::
93
* Testbenches::
94
* Reference And Board Designs::
95
@end menu
96
 
97 408 julius
@node Organisation Overview
98
@section Organisation Overview
99 397 julius
 
100 425 julius
The @value{ORPSOC} project is intended to serve dual purposes. One is to act as a development platform for OpenRISC processors, and as a development platform of OpenRISC-based SoCs targeted at specific hardware.
101 397 julius
 
102 425 julius
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.
103 397 julius
 
104 425 julius
The reference implementation based in the root (base directory) of the project contains enough componenets to create a simple OpenRISC-based SoC. Each board build is intended to implement as fully-featured a system as possible, depending on the targeted hardware.
105
 
106
The project is organised in such a way that each board build can use both the reference implementation's RTL modules and software, as well as its own set of RTL and software. The reference implementation is limited to what is available in the RTL and software directories in the root of the project, and is not technology dependent.
107
 
108 397 julius
The following sections outline the organisation of the software, RTL, and board designs.
109
 
110 408 julius
@node Software Organisation
111 397 julius
@section Software
112
 
113 425 julius
The @code{sw} path contains primarily target software (code intended for cross-compilation and execution on an OpenRISC processor.) Thre is also a path, @code{sw/utils} containing custom tools, intended to be run on the host, for manipulation of binary software images.
114 397 julius
 
115 425 julius
Driver software, implementing access functions for hardware modules, are found under @code{sw/drivers}.
116 397 julius
 
117 425 julius
There is 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}.
118
 
119
All CPU-related functions are made available through the file @code{cpu-utils.h} which is located in @code{sw/lib/include} and depending on the CPU being used, can be used to switch between different CPU driver functions. All CPU drivers are under the @code{sw/drivers} path.
120
 
121 397 julius
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.
122
 
123 425 julius
Under each test directory are two directories, @code{board} and @code{sim}, containing appropriate test software. Code for simulation will produce less printfs and aim to execute within realistic timeframes for RTL simulation. Board targeted test software is obviously written with the opposite considerations in mind.
124 397 julius
 
125 425 julius
@node Software Test Naming
126 397 julius
 
127 425 julius
The rules for naming software tests are important to adhere to, 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}.
128
 
129 468 julius
@xref{Software} for further details.
130
 
131 408 julius
@node RTL Organisation
132 397 julius
@section RTL
133
 
134
The HDL code layout conforms to those outlined in the OpenCores.org coding guidelines. http://cdn.opencores.org/downloads/opencores_coding_guidelines.pdf
135
 
136 425 julius
There are, however, some naming restrictions for this project.
137 397 julius
 
138 425 julius
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 (...}.
139
 
140
This will avoid confusion and help the scripts locate modules.
141
 
142
@subsection Verilog HDL
143
 
144
All RTL included in the project at this point is Verilog HDL, although it would be fine to add VHDL to a board build.
145
 
146 408 julius
@node Testbench Organisation
147
@section Testbench
148 397 julius
 
149 425 julius
For each design in @value{ORPSOC} there will be a testbench instantiating the top level, and any required peripherals.
150 397 julius
 
151 425 julius
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.
152 397 julius
 
153 408 julius
@node Organisation of Reference And Board Designs
154 397 julius
@section Reference And Board Designs
155
 
156
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.
157
 
158 425 julius
@subsection Module Selection
159 397 julius
 
160 425 julius
Typically, a board-targeted design will wish to reuse common components (processor, debug interface, Wishbone arbiters, UART etc.)
161 397 julius
 
162 425 julius
The project has been configured so a board build will use modules in the ``common'' RTL path (@code{rtl/verilog/}) @emph{unless} there is a copy in the board's ``local'' RTL path ( @code{boards/vendor/boardname/rtl/verilog}).
163 397 julius
 
164 425 julius
For example, in the event that modification to a module in the common RTL set is required for it to function correctly in a board build, it's advisable to copy that module to the board's @emph{local} RTL path and modify it there. Simulation and backend scripts should then use this board-specific version instead of the one in the common RTL path.
165
 
166
 
167
 
168 397 julius
@c ****************************************************************************
169
@c Getting started
170
@c ****************************************************************************
171
 
172
@node Getting Started
173
@chapter Getting Started
174
@cindex source files for @value{ORPSOC}, downloading
175
 
176
@menu
177
* Supported Platforms::
178
* Obtaining Project Source::
179
* Required Tools::
180
@end menu
181
 
182 408 julius
@node Getting Started Supported Platforms
183 425 julius
@section Supported Host Platforms
184
@cindex host platforms supported by the @value{ORPSOC} project
185 397 julius
 
186
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.
187
 
188 425 julius
Unless indicated otherwise, support for the project under Cygwin on Microsoft Windows platforms cannot be assumed.
189 397 julius
 
190 408 julius
@node Getting Started Obtaining Project Source
191 397 julius
@section Obtaining Project Source
192
@cindex getting a copy of the @value{ORPSOC} project
193
 
194
The source for @value{ORPSOC} can be obtained from the OpenCores subversion (SVN) server.
195
 
196
@example
197
@kbd{svn export http://opencores.org/ocsvn/openrisc/openrisc/trunk/orpsocv2}
198
@end example
199
 
200 408 julius
@node Getting Started Required Tools
201 397 julius
@section Required Tools
202
@cindex tools and utilities required for @value{ORPSOC}
203
 
204
 
205
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.
206
 
207 415 julius
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 greatly improved productivity.
208 397 julius
 
209
The required tools can be divided into four groups.
210
 
211
@itemize @bullet
212
@item
213
Host system tools - things like gcc, make, texinfo.
214
 
215
@item
216
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.
217
 
218
@item
219
Electronic design automation (EDA) tools - preprocessors, simulators, FPGA tool suites, etc.
220
 
221
@item
222
Debug tools - tools providing control over the system on target
223
@end itemize
224
 
225
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.
226
 
227
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.
228
 
229
Anyone implementing their own board port is encouraged to document, as best they can, any problematic tool installations and contribute them to this document.
230
 
231
 
232
 
233
@c ****************************************************************************
234
@c Reference Design chapter
235
@c ****************************************************************************
236
 
237
@node Reference Design
238
@chapter Reference Design
239
@cindex reference design
240
 
241
@menu
242
* Overview::
243
* Structure::
244
* Tools::
245
* Simulation::
246
* Synthesis::
247
@end menu
248
 
249 408 julius
@node Reference Design Overview
250 468 julius
@section Overview
251 397 julius
 
252 425 julius
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. Very little apart from the processor, memory, debug interface and interconnect modules are instantiated.
253 397 julius
 
254 415 julius
The primary role for this design is to implement a system that an OpenRISC processor can be instantiated 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.
255 397 julius
 
256
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.
257
 
258
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.
259
 
260
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.
261
 
262 408 julius
@node Reference Design Structure
263 468 julius
@section Structure
264 397 julius
 
265
@menu
266
* Overview::
267
* RTL::
268
* Software::
269
* Simulation::
270
@end menu
271
 
272 408 julius
@node Reference Design Overview
273 468 julius
@subsection Overview
274 397 julius
 
275
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.
276
 
277
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}.
278
 
279 408 julius
@node Reference Design RTL
280 468 julius
@subsection RTL
281 397 julius
 
282
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.
283
 
284
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.
285
 
286
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.
287
 
288 408 julius
@node Reference Design Software
289 468 julius
@subsection Software
290 397 julius
 
291
The software run on the reference design is found in the @value{ORPSOC} root directory, under the @code{sw} path.
292
 
293
The test software for the or1200 processor is found under @code{sw/tests/or1200/sim}.
294
 
295
A minimal set of drivers is built into @code{liborpsoc}, and they are found under @code{sw/tests/drivers}.
296
 
297
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.
298
 
299 408 julius
@node Reference Design Simulation
300 468 julius
@subsection Simulation
301 397 julius
 
302
The simulation of the reference design is run from the @code{sim/run} path.
303
 
304
The script controlling simulation is the file @code{sim/bin/Makefile}.
305
 
306
The generated output is kept in the @code{sim/out} path, and is cleared away when @kbd{make clean} is run.
307
 
308
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.
309
 
310 408 julius
@node Reference Design Tools
311 468 julius
@section Tools
312 397 julius
 
313
@menu
314
* Host Tools::
315
* Target System Tools::
316
* EDA Tools::
317
* Debug Tools::
318
@end menu
319
 
320 408 julius
@node Reference Design Host Tools
321 468 julius
@subsection Host Tools
322 397 julius
@cindex host tools required
323
 
324
Standard development suite of tools: gcc, make, etc.
325
 
326 408 julius
@node Reference Design Target System Tools
327 468 julius
@subsection Target System Tools
328 397 julius
@cindex target system tools required
329
 
330
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
331
 
332 408 julius
@node Reference Design EDA Tools
333 468 julius
@subsection EDA Tools
334 397 julius
@cindex EDA tools required
335
 
336
RTL simulation: Icarus Verilog (also compatible with Mentor Graphics' Modelsim)
337
Cycle Accurate Simulation: Verilator, Verilog-Perl, System-Perl, SystemC
338
 
339 408 julius
@node Reference Design Debug Tools
340 468 julius
@subsection Debug Tools
341 397 julius
@cindex Debug tools required
342
 
343
None. The target is purely simulation, no extra utilities are required to debug.
344
 
345
 
346 408 julius
@node Reference Design Simulation
347 468 julius
@section Simulation
348 397 julius
 
349
@menu
350
* RTL::
351
* Cycle Accurate::
352
* Results::
353
@end menu
354
 
355 408 julius
@node Reference Design RTL
356 468 julius
@subsection RTL
357 397 julius
@cindex rtl simulation of reference design
358
 
359
All simulations of the reference design are run from the @code{sim/run} path.
360
 
361 468 julius
@subheading Running RTL Regression Test
362 397 julius
 
363
The simplest way of starting a run through the regression test, using the default RTL simulator, Icarus Verilog, can be done with:
364
 
365
@example
366
@kbd{make rtl-tests}
367
@end example
368
 
369 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.
370 397 julius
 
371 468 julius
@subheading Running An Individual Test
372 397 julius
 
373
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.
374
 
375
@example
376
@kbd{make rtl-test TEST=or1200-basic}
377
@end example
378
 
379 408 julius
@node Running A Set Of Specific Reference Design RTL Tests
380 468 julius
@subheading Running A Set Of Specific Tests
381 397 julius
 
382
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.
383
 
384
@example
385
@kbd{make rtl-tests TESTS="sdram-rows uart-simple or1200-mmu or1200-fp"}
386
@end example
387
 
388 468 julius
@node Providing A Precompiled ELF Executable
389
@subheading Providing A Precompiled ELF Executable
390
 
391
It's possible to specify the path to an OR32 ELF executable to be run in simulation instead of test software. Use the @code{USER_ELF} environment variable to specify the path to the ELF to run.
392
 
393
@example
394
@kbd{make rtl-test USER_ELF=/path/to/myapp.elf}
395
@end example
396
 
397
The ELF will be converted to binary format, and then converted to a VMEM to be
398
loaded into the model for execution at runtime.
399
 
400
@node Providing A Custom VMEM Image
401
@subheading Providing A Custom VMEM Image
402
 
403
It's possible to specify the path to a pre-existing VMEM image to be run in simulation instead of test software. Use the @code{USER_VMEM} environment variable to specify the path to the VMEM image to be run.
404
 
405
@example
406
@kbd{make rtl-test USER_VMEM=/path/to/myapp.vmem}
407
@end example
408
 
409
This VMEM file will be copied into the working directory, and renamed according to what the simulated memory expects.
410
 
411 408 julius
@node Options For Reference Design RTL Tests
412 468 julius
@subheading Options For RTL Tests
413 397 julius
 
414
There are some options, which can be specified through shell environment variables when running the test.
415
 
416
@table @code
417
 
418
@item VCD
419 408 julius
Set to '1' to enable @emph{value change dump} (VCD) creation in @code{sim/out/@emph{testname}.vcd}
420 397 julius
 
421
@item VCD_DELAY
422
Delay VCD creation start time by this number of timesteps (used as a Verilog @code{#delay} in the testbench.)
423
 
424
@item VCD_DELAY_INSNS
425
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.)
426
 
427
@item END_TIME
428
Force simulation end (@code{$finish}) at this time.
429
 
430
@item DISABLE_PROCESSOR_LOGS
431
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.
432
 
433
@item SIMULATOR
434
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.
435
 
436
@end table
437
 
438
 
439
 
440 408 julius
@node Reference Design Cycle Accurate
441 468 julius
@subsection Cycle Accurate
442 397 julius
@cindex cycle accurate simulation of reference design
443
 
444 468 julius
@subheading Running Cycle Accurate Regression Test
445 397 julius
 
446
The simplest way of starting a run through the regression test using the cycle accurate model can be done with:
447
 
448
@example
449
@kbd{make vlt-tests}
450
@end example
451
 
452
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.
453
 
454 468 julius
@subheading Running An Individual Test
455 397 julius
 
456
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.
457
 
458
@example
459
@kbd{make vlt-test TEST=or1200-basic}
460
@end example
461
 
462 468 julius
@subheading Generating Cycle Accurate Simulator Executable
463 397 julius
 
464
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.
465
 
466
@example
467
@kbd{make prepare-vlt}
468
@end example
469
 
470
The resulting executable will be @emph{Vorpsoc_top} in the @code{sim/vlt} path. Run it with the @emph{-h} option for usage instructions.
471
 
472 468 julius
@subheading Generating Automatically Profiled Cycle Accurate Simulator Executable
473 397 julius
 
474
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.
475
 
476
@example
477
@kbd{make prepare-vlt-profiled}
478
@end example
479
 
480 468 julius
@subheading Cycle Accurate Model Executable Usage
481 397 julius
 
482
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.
483
 
484
@example
485
@kbd{Vorpsoc_top --help}
486
@end example
487
 
488
A short list of options is given here.
489
 
490
@table @code
491
 
492
@item -f @var{file}
493
@itemx --program @var{file}
494
@cindex @code{-f}
495
@cindex @code{--program}
496
Load software from OR32 ELF image @var{file}
497
 
498
If unspecified, model attempts to load VMEM file @code{sram.vmem}
499
 
500
@item -v
501
@itemx --vcd
502
@cindex @code{-v}
503
@cindex @code{--vcd}
504
Dump VCD file
505
 
506
@item -e @var{value}
507
@itemx --endtime @var{value}
508
@cindex @code{-e}
509
@cindex @code{--endtime}
510
End simulation after @var{value} simulated ns
511
 
512
@item -l @var{file}
513
@itemx --log @var{file}
514
@cindex @code{-l}
515
@cindex @code{--log}
516
Log processor execution trace to @var{file}
517
 
518
@end table
519
 
520 408 julius
@node Reference Design Results
521 468 julius
@subsection Results
522 397 julius
@cindex output from simulation of reference design
523
 
524 415 julius
The following files are generated from the event driven simulation. For output options of the cycle accurate model, see the section on Cycle Accurate Model Executable Usage.
525 397 julius
 
526 468 julius
@subheading Processor Execution Trace
527 397 julius
 
528
A trace of the processor after each executed instruction is generated by both the event and cycle accurate models.
529
 
530
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}.
531
 
532 468 julius
@subheading Processor SPR Access Log
533 397 julius
 
534
A list of processor special purpose registers (SPR) accesses is created when processor logging is enabled.
535
 
536
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-sprs.log}.
537
 
538 468 julius
@subheading Processor Instruction Excecution Time Log
539 397 julius
 
540
A list of when each instruction was executed is generated when processor execution logging is enabled.
541
 
542
This is useful when debugging with VCD, and detecting at what time the problematic instructions were executed.
543
 
544
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-lookup.log}.
545
 
546 468 julius
@subheading Processor Report Mechanism Log
547 397 julius
 
548
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.
549
 
550
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-general.log}. This is not optional.
551
 
552 468 julius
@subheading Value Change Dump (VCD)
553 397 julius
 
554
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}.
555
 
556
 
557 408 julius
@node Reference Design Synthesis
558 468 julius
@section Synthesis
559 397 julius
 
560
The reference design is not intended to be synthesised, and thus no backend scripts are provided. See the sections on the board-specific builds.
561
 
562
 
563
@c ****************************************************************************
564 408 julius
@c ORDB1A3PE1500 board build chapter
565 397 julius
@c ****************************************************************************
566
 
567 408 julius
@node ORDB1A3PE1500
568
@chapter ORDB1A3PE1500
569
@cindex ORDB1A3PE1500 board build information
570 397 julius
 
571
@menu
572
* Overview::
573
* Structure::
574
* Tools::
575
* Simulating::
576 408 julius
* Synthesis and Backend::
577
* Programming File Generation::
578
* Customising::
579 397 julius
@end menu
580
 
581 408 julius
@node ORDB1A3PE1500 Overview
582 468 julius
@section Overview
583 397 julius
 
584 408 julius
The ORDB1 (ORSoC development board 1) with Actel A3PE1500 FPGA is supported by this build.
585 397 julius
 
586 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.
587
 
588
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.
589
 
590 415 julius
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.
591 408 julius
 
592
This guide will overview how to simulation, synthesize and customise the system.
593
 
594
@node ORDB1A3PE1500 Structure
595 468 julius
@section Structure
596 397 julius
 
597 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}.
598 397 julius
 
599 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.
600
 
601
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.
602
 
603
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.
604
 
605
@node ORDB1A3PE1500 Tools
606 468 julius
@section Tools
607 397 julius
 
608
@menu
609
* Host Tools::
610
* Target System Tools::
611
* EDA Tools::
612
* Debug Tools::
613
@end menu
614
 
615 408 julius
@node ORDB1A3PE1500 Host Tools
616 468 julius
@subsection Host Tools
617 408 julius
@cindex host tools required ORDB1A3PE1500
618 397 julius
 
619
Standard development suite of tools: gcc, make, etc.
620
 
621 408 julius
@node ORDB1A3PE1500 Target System Tools
622 468 julius
@subsection Target System Tools
623 408 julius
@cindex target system tools required ORDB1A3PE1500
624 397 julius
 
625
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
626
 
627 408 julius
@node ORDB1A3PE1500 EDA Tools
628 468 julius
@subsection EDA Tools
629 408 julius
@cindex EDA tools required ORDB1A3PE1500
630 397 julius
 
631
RTL, gatelevel simulation: Mentor Graphics' Modelsim
632
Synthesis: Synopsys Synplify (included in Actel Libero Suite)
633
Backend: Actel Designer (included in Actel Libero Suite)
634
Programming: Actel FlashPRO (included in Actel Libero Suite)
635
 
636 439 julius
This has been tested with with Libero v8.6 and v9.0sp1 under Ubuntu Linux.
637 408 julius
 
638
@node ORDB1A3PE1500 Debug Tools
639 468 julius
@subsection Debug Tools
640 408 julius
@cindex Debug tools required ORDB1A3PE1500
641 397 julius
 
642
or_debug_proxy, ORPmon
643
 
644 408 julius
@node ORDB1A3PE1500 Simulating
645 468 julius
@section Simulating
646 408 julius
@cindex simulating ORDB1A3PE1500
647 397 julius
 
648 468 julius
@subheading Run RTL Regression Test
649 408 julius
 
650
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
651
 
652
@example
653
@kbd{make rtl-tests}
654
@end example
655
 
656 425 julius
The same set of options for RTL tests available in the reference design should be available in this build. @xref{Running A Set Of Specific Reference Design RTL Tests}.
657 408 julius
 
658 409 julius
Options specific to the ORDB1A3PE1500 build.
659
 
660
@table @code
661
 
662
@item PRELOAD_RAM
663
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
664
 
665
If the chosen bootROM program (set via a define in software header file in the board's @code{sw/board/include} path) will jump straight to RAM to begin execution, then the software image will need to be in RAM for the simulation to work. This define @emph{must} be used in that case for the simulation to do anything.
666
 
667
 
668
@end table
669
 
670
 
671
 
672 408 julius
@node ORDB1A3PE1500 Synthesis
673 468 julius
@section Synthesis
674 408 julius
 
675
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.
676
 
677
@example
678
@kbd{make all}
679
@end example
680
 
681
This will create a EDIF netlist in @code{syn/synplify/out}.
682
 
683
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.
684
 
685
@node ORDB1A3PE1500 Synthesis Options
686 468 julius
@subsection Options
687 408 julius
 
688
The following can be passed as environment variables when running @kbd{make all}.
689
 
690
@table @code
691
 
692
@item RTL_TOP
693
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.
694
 
695
@item FPGA_PART
696
Defaults to A3PE1500 but if targeting any other set it with this.
697
 
698
@item FPGA_FAMILY
699
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
700
 
701
@item FPGA_PACKAGE
702
Defaults to PQFP208 but if targeting any other set it with this.
703
 
704
@item FPGA_SPEED_GRADE
705
Defaults to Std but if targeting any other set it with this.
706
 
707
@item FREQ
708
Target frequency for synthesis.
709
 
710
@item MAXFAN
711
Maximum net fanout.
712
 
713
@item MAXFAN_HARD
714
Hard limit on maximum net fanout.
715
 
716
@item GLOBALTHRESH
717
Threshold of fanout before promoting signal to a global routing net.
718
 
719
@item RETIMING
720
Defaults to '1' (on) but set to '0' to disable.
721
 
722
@item RESOURCE_SHARING
723
Defaults to '1' (on) but set to '0' to disable.
724
 
725
@item DISABLE_IO_INSERTION
726
Defaults to '0' (off) but set to '1' to enable. Useful when synthesizing individual modules not intended as a top level.
727
 
728
@end table
729
 
730
@node ORDB1A3PE1500 Synthesis Warnings
731 468 julius
@subsection Checks
732 408 julius
 
733
The following is a list of some considerations before synthesis.
734
 
735
@itemize @bullet
736
@item bootrom.v
737
 
738 415 julius
If the bootROM module is being used to provide the processor with a program at startup, check that board software include file, in the board's @code{sw/board/include} path, is selecting the correct bootROM program.
739 408 julius
 
740 449 julius
Do a @kbd{make distclean} from the synthesis run directory to be sure that the previous bootROM file is cleared away and regenerated when synthesis is run.
741 408 julius
 
742
 
743
@item Clean away old leftovers
744
 
745
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.
746
 
747
 
748
@item Check Command Line Options
749
 
750
If using any command line settings, they can be checked by passing them to the following make target: @kbd{make print-config}
751
 
752
 
753
@end itemize
754
 
755
@node ORDB1A3PE1500 Place and Route
756 468 julius
@section Place and Route
757 408 julius
 
758
Place and route is run from the board's @code{backend/par/run} path with the following command.
759
 
760
@example
761
@kbd{make all}
762
@end example
763
 
764
This will create a @code{.adb} file in the same path.
765
 
766 439 julius
All steps, up to and including programming file generation are done here. FPGA device programming must be done using the programming FlashPro tool under Windows if using a free license.
767 408 julius
 
768
@node ORDB1A3PE1500 Place and route options
769 468 julius
@subsection Options
770 408 julius
 
771 439 julius
Most of the design's parameters are determined by processing the @code{orpsoc-defines.v} file and extracting, for example, the frequency of the clocks entering the design.
772 408 julius
 
773
The following can be passed as environment variables when running @kbd{make all}.
774
 
775
@table @code
776
 
777
@item FPGA_PART
778
Defaults to A3PE1500 but if targeting any other set it with this.
779
 
780
@item FPGA_FAMILY
781
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
782
 
783
@item FPGA_PACKAGE
784
Defaults to ``208 PQFP'' but if targeting any other set it with this.
785
 
786
 
787
@item FPGA_SPEED_GRADE
788
Defaults to Std but if targeting any other set it with this.
789
 
790
@item FPGA_VOLTAGE
791
Defaults to 1.5 but if targeting any other set it with this.
792
 
793
@item FPGA_TEMP_RANGE
794
Defaults to COM but if targeting any other set it with this.
795
 
796
@item FPGA_VOLT_RANGE
797
Defaults to COM but if targeting any other set it with this.
798
 
799
@item PLACE_INCREMENTAL
800
Defaults to off.
801
 
802
@item ROUTE_INCREMENTAL
803
Defaults to off.
804
 
805
@item PLACER_HIGH_EFFORT
806
Defaults to off.
807
 
808
@item BOARD_CONFIG
809
Defaults to @code{orsoccpuexpio.mkpinassigns}
810
 
811
@end table
812
 
813
@node ORDB1A3PE1500 Constraints
814 468 julius
@subsection Constraints
815 408 julius
 
816
 
817
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.
818
 
819
 
820
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}.
821
 
822
 
823
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.
824
 
825
@example
826
@kbd{make pdc-file sdc-file}
827
@end example
828
 
829
These can be generated and edited and then used when running place and route, they will not get replaced.
830
 
831
@node ORDB1A3PE1500 Programming File Generation
832 468 julius
@section Programming File Generation
833 408 julius
 
834
The @code{.adb} file resulting from place and route can be opened in the Actel @emph{Designer} tool and a programming file generated there.
835
 
836
Once this programming file is created, Actel's @emph{FlashPro} can used to program the ORDB1A3PE1500 board.
837
 
838
@node ORDB1A3PE1500 Customising
839 468 julius
@section Customising
840 408 julius
 
841
The versatile nature of the ORDB1A3PE1500 means the design that goes on it must be equally versatile, if not more so.
842
 
843
The following sections have information on how to configure the design.
844
 
845
@node ORDB1A3PE1500 Customising Enabling Existing Modules
846 468 julius
@subsection Enabling Existing RTL Modules
847 408 julius
 
848
The design relies on the Verilog HDL @emph{define} function to indicate which modules are included.
849
 
850 415 julius
There are only a few modules included by default.
851 408 julius
 
852
@itemize @bullet
853
@item Processor - @emph{or1200}
854
@item Clock and reset generation - @emph{clkgen}
855
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
856
@end itemize
857
 
858
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
859
 
860
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.
861
 
862 415 julius
These cores should be supported and ready to go by just defining them (uncomment in the @code{orspco-defines.v} file.)
863 408 julius
 
864
@node ORDB1A3PE1500 Customising Adding Modules
865 468 julius
@subsection Adding RTL Modules
866 408 julius
 
867
There are a number of steps to take when adding a new module to the design.
868
 
869
@itemize @bullet
870
@item RTL Files
871
 
872
Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
873
 
874
Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
875
 
876
Place any include files into the board's @code{rtl/verilog/include} path.
877
 
878
@item Instantiate in ORPSoC Top Level File
879
 
880
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.
881
@itemize @bullet
882
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
883
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
884
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
885
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
886
@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.
887
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
888
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
889
@end itemize
890
 
891
@item Update ORPSoC Testbench
892
 
893
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
894
 
895
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
896
 
897
@item Add Software Drivers and Tests
898
 
899
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.)
900
 
901
@item Update Backend Scripts
902
 
903 415 julius
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} will need to be updated.
904 408 julius
 
905
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.
906
 
907 415 julius
Continuing the format already there should be easy enough. Remember 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.
908 408 julius
 
909
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.
910
 
911
@example
912
@kbd{   $(Q)if [ ! -z $$FOO1 ]; then \
913
        echo "set_io foo1_srx_i " $(FOO_SRX_BUS_SETTINGS) " \
914 410 julius
        -pinname "$(FOO1_SRX_PIN) >> $@@; \
915 408 julius
        echo "set_io foo1_tx_o\\[0\\] " $(FOO_TX_BUS_SETTINGS) " \
916 410 julius
         -pinname "$(FOO1_TX0_PIN) >> $@@; \
917 408 julius
        echo "set_io foo1_tx_o\\[1\\] " $(FOO_TX_BUS_SETTINGS) "  \
918 410 julius
        -pinname "$(FOO1_TX1_PIN) >> $@@; \
919 408 julius
        echo "set_io foo1_tx_o\\[2\\] " $(FOO_TX_BUS_SETTINGS) "  \
920 410 julius
        -pinname "$(FOO1_TX2_PIN) >> $@@; \
921 408 julius
        echo "set_io foo1_tx_o\\[3\\] " $(FOO_TX_BUS_SETTINGS) "  \
922 410 julius
        -pinname "$(FOO1_TX3_PIN) >> $@@; \
923
fi
924 408 julius
       }
925
@end example
926
 
927
@emph{(ensure there is no whitespace after the trailing backslashes.)}
928
 
929
It's a little hard to follow, but it's essentially one @code{set_io} line for each I/O line.
930
 
931
First the line checks if the module's define was exported (which happens automatically if it's defined in @code{orpsoc-defines.v}.
932
 
933
Note that what is defined can be checked by running @kbd{make print-defines} in the board's @code{backend/par/run} path.
934
 
935
The values of the bus settings variables depend on the desired I/O standards and other examples in the Makefile can be referenced.
936
 
937 415 julius
The pin numbers need to be set in the @code{.mkpinassigns} which is included into the Makefile (according to the @code{BOARD_CONFIG} variable set when running the @code{make} command.)
938 408 julius
 
939
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.
940
 
941
The physical constraints file can be generated manually with the @kbd{make pdc-file} command.
942
 
943
@end itemize
944
 
945 415 julius
@c ****************************************************************************
946
@c ML501 board build chapter
947
@c ****************************************************************************
948 408 julius
 
949 415 julius
@node ML501
950
@chapter ML501
951
@cindex ML501 board build information
952 408 julius
 
953 415 julius
@menu
954
* Overview::
955
* Structure::
956
* Tools::
957
* Simulating::
958
* Synthesis and Backend::
959
* Programming File Generation::
960
* Customising::
961
* Running And Debugging Software::
962
@end menu
963 408 julius
 
964 415 julius
@node ML501 Overview
965 468 julius
@section Overview
966 408 julius
 
967 415 julius
The Xilinx ML501 board contains a Virtex LX50 part, varied memories and peripherals. See Xilinx's site for specific details:
968
 
969
http://www.xilinx.com/products/devkits/HW-V5-ML501-UNI-G.htm
970
 
971
Not all peripherals are supported, and adding support for each is a goal.
972
 
973
At present the build contains a memory controller for the DDR2 SDRAM (based around a Xilinx MIG derived controller) and SSRAM. None of the other peripherals (VGA/AC97/PS2/USB/LCD) have controllers in the design yet.
974
 
975
The OpenCores 10/100 Ethernet MAC can be used for Ethernet, but still has some bugs to do with memory access, although it appears to be using the RGMII interface to the 10/10/1000 PHY on the ML501 OK.
976
 
977
The project is configured to generate either a @code{.bit} file for direct programming via JTAG, or a @code{.mcs} file with inbuilt bootloader software for the processor, meaning the board can be powered up and an application like ORPmon loaded without having to reprogram it from iMPACT between power cycles.
978
 
979
This guide is far from complete, but provides the basics on running simulations, and building the design.
980
 
981
@node ML501 Structure
982 468 julius
@section Structure
983 415 julius
 
984
Note that in this chapter the term @emph{board path} refers to the path in the project for this board port; @code{boards/xilinx/ml501}.
985
 
986
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.
987
 
988
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.
989
 
990
Backend files, mainly binary NGC files for mapping, are found in the board's @code{backend/bin} path.
991
 
992 425 julius
@node ML501 XILINX_PATH
993 468 julius
@subsection ML501 XILINX_PATH
994 425 julius
 
995 415 julius
Be sure to set the environment variable @code{XILINX_PATH} to the path of the ISE path on the host machine. This can be done with something like @kbd{export XILINX_PATH=/software/xilinx_11.1/ISE} and additionally a symbolic link to the Verilog simulation library sources will be required - see the simulation section on this. Note that it helps to add the @code{XILINX_PATH} variable to the user's @code{.bashrc} script or similar to save setting it each time a new shell is opened.
996
 
997
If the @code{XILINX_PATH} variable is not set correctly, the makefiles will not run.
998
 
999
@node ML501 Tools
1000 468 julius
@section Tools
1001 415 julius
 
1002
@menu
1003
* Host Tools::
1004
* Target System Tools::
1005
* EDA Tools::
1006
* Debug Tools::
1007
@end menu
1008
 
1009
@node ML501 Host Tools
1010 468 julius
@subsection Host Tools
1011 415 julius
@cindex host tools required ML501
1012
 
1013
Standard development suite of tools: gcc, make, etc.
1014
 
1015
@node ML501 Target System Tools
1016 468 julius
@subsection Target System Tools
1017 415 julius
@cindex target system tools required ML501
1018
 
1019
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
1020
 
1021
@node ML501 EDA Tools
1022 468 julius
@subsection EDA Tools
1023 415 julius
@cindex EDA tools required ML501
1024
 
1025
RTL, gatelevel simulation: Mentor Graphics' Modelsim
1026
Synthesis: XST (from Xilinx ISE)
1027
Backend: ngdbuild/map/par/bitgen/promgen, etc. (from Xilinx ISE)
1028
Programming: iMPACT (from Xilinx ISE)
1029
 
1030 439 julius
This has been tested with Xilinx ISE 11.1 under Ubuntu Linux.
1031 415 julius
 
1032
 
1033
@node ML501 Debug Tools
1034 468 julius
@subsection Debug Tools
1035 415 julius
@cindex Debug tools required ML501
1036
 
1037
or_debug_proxy, ORPmon
1038
 
1039
@node ML501 Simulating
1040 468 julius
@section Simulating
1041 415 julius
@cindex simulating ML501
1042
 
1043 425 julius
Ensure the @code{XILINX_PATH} environment variable is set correcetly. @xref{ML501 XILINX_PATH} for information.
1044 415 julius
 
1045 425 julius
Note that if this path is not set, simulations will not compile.
1046 415 julius
 
1047 468 julius
@subheading Run RTL Regression Test
1048 415 julius
 
1049
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
1050
 
1051
@example
1052
@kbd{make rtl-tests}
1053
@end example
1054
 
1055 425 julius
The same set of options for RTL tests available in the reference design should be available in this build. @xref{Running A Set Of Specific Reference Design RTL Tests}.
1056 415 julius
 
1057
Options specific to the ML501 build.
1058
 
1059
@table @code
1060
 
1061
@item PRELOAD_RAM
1062
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
1063
 
1064
If the chosen bootROM program (set via a define in software header file in the board's @code{sw/board/include} path) will jump straight to RAM to begin execution, then the software image will need to be in RAM for the simulation to work. This define @emph{must} be used in that case for the simulation to do anything.
1065
 
1066
 
1067
@end table
1068
 
1069
 
1070
 
1071
@node ML501 Synthesis
1072 468 julius
@section Synthesis
1073 415 julius
 
1074
Synthesis of the board port for the Actel technology with the Synplify tool can be run in the board's @code{syn/xst/run} path with the following command.
1075
 
1076
@example
1077
@kbd{make all}
1078
@end example
1079
 
1080
This will create an NGC file in @code{syn/xst/run} named @code{orpsoc.ngc}.
1081
 
1082
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.
1083
 
1084
@node ML501 Synthesis Options
1085 468 julius
@subsection Options
1086 415 julius
 
1087
Use the following command int the @code{syn/xst/run} path to get a list of the variables used during synthesis. Any can be set on the command line when running @code{make all}.
1088
 
1089
@example
1090
@kbd{make print-config}
1091
@end example
1092
 
1093
 
1094
@node ML501 Synthesis Warnings
1095 468 julius
@subsection Checks
1096 415 julius
 
1097
The following is a list of some considerations before synthesis.
1098
 
1099
@itemize @bullet
1100
@item bootrom.v
1101
 
1102
If the bootROM module is being used to provide the processor with a program at startup (reset address in processor's define file is set to @code{0xf0000100} or similar), check that board software include file, in the board's @code{sw/board/include} path, is selecting the correct bootROM program.
1103
 
1104 449 julius
Do a @kbd{make distclean} from the synthesis run directory to be sure that the previous bootROM file is cleared away and regenerated when synthesis is run.
1105 415 julius
 
1106
 
1107
@item Clean away old leftovers
1108
 
1109
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.
1110
 
1111
 
1112
 
1113
@end itemize
1114
 
1115
@node ML501 Synthesised Netlist
1116 468 julius
@subsection Netlist generation
1117 415 julius
 
1118
To create a Verilog HDL netlist of the post-synthesis design, run the following in the board's @code{syn/xst/run} path.
1119
 
1120
@example
1121
@kbd{make orpsoc.v}
1122
@end example
1123
 
1124
@node ML501 Place and Route
1125 468 julius
@section Place and Route
1126 415 julius
 
1127
Place and route of the design can be run from the board's @code{backend/par/run} path with the following command.
1128
 
1129
@example
1130
@kbd{make orpsoc.ncd}
1131
@end example
1132
 
1133
@node ML501 Timing Report
1134 468 julius
@section Post-PAR STA Report
1135 415 julius
 
1136
The @code{trce} tool can be used to generate a timing report of the post-place and route design.
1137
 
1138
@example
1139
@kbd{make timingreport}
1140
@end example
1141
 
1142
@node ML501 Back-annotated Netlist
1143 468 julius
@section Back-annotated Netlist
1144 415 julius
 
1145
A post-PAR back-annotated netlist can be generated with the following command.
1146
 
1147
@example
1148
@kbd{make netlist}
1149
@end example
1150
 
1151
This will make a new directory under the board's @code{backend/par/run} path named @code{netlist} and will contain a Verilog netlist and SDF file with timing information.
1152
 
1153
 
1154
@node ML501 Place and route options
1155 468 julius
@subsection Options
1156 415 julius
 
1157
To get a list of options that can be set when running the backend flow, run the following in the board's @code{backend/par/run} path.
1158
 
1159
@example
1160
@kbd{make print-config}
1161
@end example
1162
 
1163
@node ML501 Constraints
1164 468 julius
@subsection Constraints
1165 415 julius
 
1166
A Xilinx User Constraints File (UCF) file is in the board's @code{backend/par/bin} path. It is named @code{ml501.ucf}. It should be edited if any extra I/O or constraints are required.
1167
 
1168
Eventually it would be good to dynamically generated this, based on what is included in the design, but for now this must be hand modified if modules are added ore removed from the design.
1169
 
1170
@node ML501 Programming File Generation
1171 468 julius
@section Programming File Generation
1172 415 julius
 
1173
Programming file generation is run from the board's @code{backend/par/run} path with the following command.
1174
 
1175
@example
1176
@kbd{make orpsoc.bit}
1177
@end example
1178
 
1179
This file can then be loaded into the Xilinx iMPACT program and programmed onto the Virtex 5 part on the ML501.
1180
 
1181
@node ML501 SPI programming file
1182 468 julius
@subsection SPI programming file generation
1183 415 julius
 
1184
To generate a file, which can be programmed into the SPI flash on the board (and thus allowing the FPGA to be configured without using iMPACT each time) run the following command in the board's @code{backend/par/run} path.
1185
 
1186
@example
1187
@kbd{make orpsoc.mcs}
1188
@end example
1189
 
1190
@node ML501 SPI programming file with software
1191 468 julius
@subsection SPI programming file generation with software
1192 415 julius
 
1193
To generate a file, which can be programmed into the SPI flash on the board (and thus allowing the FPGA to be configured without using iMPACT each time) and also has a bootloader the processor can run (such as ORPmon) run the following command in the board's @code{backend/par/run} path.
1194
 
1195
@example
1196
@kbd{make orpsoc.mcs BOOTLOADER_BIN=/path/to/bootloader-binary-file.bin}
1197
@end example
1198
 
1199
The image is allowed to be up to 256KBytes in size.
1200
 
1201
As the SPI flash on the ML501 is only 2MBytes in size, and the FPGA configuration image takes up almost 1.5MBytes, the final 256KBytes are reserved for a software image to be loaded at reset by the processor.
1202
 
1203
This mark (the last 256KBytes of memory) is at hex address @code{0x1c0000}. This value is passed to the @code{promgen} tool when creating the @code{.mcs} file, and is set in the board's @code{board.h} file so the embedded bootloader in the design knows which address to load from.
1204
 
1205
If changing the address of the bootloader, to accommodate a larger image for example, be sure to update the address in the @code{board.h} file and set the environment variable @code{SPI_BOOTLOADER_SW_OFFSET_HEX} to the hex address to embed the binary image at (hexadecimal value without the leading ``@code{0x}''.) Note that changing the address to load from in @code{board.h} will require the entire design is re synthesized.
1206
 
1207
The file pointed to by @code{BOOTLOADER_BIN} should be a binary image with the  size of the image embedded in the first word.
1208
 
1209
The tool @code{bin2binsizeword} in ORPSoC's @code{sw/utils} path can add the sizeword to a binary image. A binary image is something created with the processor toolchains @code{objcopy -O binary} option. A tool like ORPmon is a good candidate for being embedded in the SPI flash as bootloader software - a binary image is automatically created when it's compiled, usually named @code{orpmon.or32.bin}. To embed that, it would simply need to be passed to the @code{bin2binsizeword} like the following:
1210
 
1211
@example
1212
@kbd{bin2binsizeword /path/to/orpmon/orpmon.or32.bin orpmon-sizeword.bin}
1213
@end example
1214
 
1215
This @code{orpmon-sizeword.bin} file should then be passed via the BOOTLOADER_BIN option when creating the @code{.mcs} file to embed it.
1216
 
1217
If once the FPGA configuration image, and a bootloader image is embedded in the SPI flash, the FPGA can be configured with ORPSoC and then the processor can load the bootloader (like ORPmon) with a single press of the board's @code{PROG} button. This makes developing on the board very easy.
1218
 
1219
@node ML501 SPI flash programming
1220 468 julius
@subsection SPI flash programming
1221 415 julius
 
1222
For a guide on how to actually set up the ML501 board to program the SPI flash, see the section under ``@emph{My Own SPI Flash Image Demonstration}'' on page 26 of the Xilinx UG228 document, http://www.xilinx.com/support/documentation/boards_and_kits/ug228.pdf . Follow steps 1 to 4, and then 9 to 16, and supply the @code{.mcs} file generated here.
1223
 
1224
Be sure to set the @emph{CONFIG} switches to @code{00010101} (left-to-right when Xilinx logo in North-West of board) before attempting to program the SPI flash. The be sure to switch them back to @code{00000101} before attempting to boot the image.
1225
 
1226 479 julius
@emph{Note}: SPI flash programming will require fly-leads from the Xilinx programming cable to the the board. See page 6 of XAPP1053 for a picture of this for a @emph{different} board, but to get the idea: http://www.xilinx.com/support/documentation/application_notes/xapp1053.pdf .
1227 415 julius
 
1228 479 julius
@emph{Note}: If leaving the SPI programming fly leads in place and attempting to boot the image, be sure to remove the @code{Vref} (@code{VCC3V3} on JP2) connection before attempting to boot. Be sure the configuration DIP SW15 is set back to the @code{00000101} position!
1229 415 julius
 
1230 479 julius
@emph{Note:} The other cable from the programmer (going to the JP1 header) @emph{must} be unplugged from the board before attempting to program the SPI flash.
1231
 
1232
 
1233 415 julius
Booting from the SPI flash to ORPmon prompt is about 3 to 4 seconds.
1234
 
1235
 
1236
@node ML501 Customising
1237 468 julius
@section Customising
1238 415 julius
 
1239
The large amount of peripherals on the ML501 means that things will want to be added or removed to suit the design.
1240
 
1241
The following sections have information on how to configure the design.
1242
 
1243
@node ML501 Customising Enabling Existing Modules
1244 468 julius
@subsection Enabling Existing RTL Modules
1245 415 julius
 
1246
The design relies on the Verilog HDL @emph{define} function to indicate which modules are included. See the board's @code{rtl/verilog/include/orpsoc-defines.v} file to determine which options are enabled by uncommented @code{`define} values.
1247
 
1248
These @code{`defines} will correspond to defines in the board's top level RTL file @code{boardpath/rtl/verilog/orpsoc_top/orpsoc_top.v}.
1249
 
1250
There are only a few modules included by default.
1251
 
1252
@itemize @bullet
1253
@item Processor - @emph{or1200}
1254
@item Clock and reset generation - @emph{clkgen}
1255
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
1256
@end itemize
1257
 
1258
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
1259
 
1260
@node ML501 Customising Adding Modules
1261 468 julius
@subsection Adding RTL Modules
1262 415 julius
 
1263
There are a number of steps to take when adding a new module to the design.
1264
 
1265
@itemize @bullet
1266
@item RTL Files
1267
 
1268
Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
1269
 
1270
Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
1271
 
1272
Place any include files into the board's @code{rtl/verilog/include} path.
1273
 
1274
@item Instantiate in ORPSoC Top Level File
1275
 
1276
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.
1277
@itemize @bullet
1278
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
1279
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
1280
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
1281
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
1282
@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.
1283
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
1284
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
1285
@end itemize
1286
 
1287
@item Update ORPSoC Testbench
1288
 
1289
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
1290
 
1291
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
1292
 
1293
@item Add Software Drivers and Tests
1294
 
1295
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.)
1296
 
1297
@item Update Backend Scripts
1298
 
1299
If any I/O is added, or special timing specified, the board's UCF file will need updating - see @code{boardpath/backend/par/bin/ml501.ucf}.
1300
 
1301
@end itemize
1302
 
1303
@node ML501 Running And Debugging Software
1304 468 julius
@section Running And Debugging Software
1305 415 julius
 
1306
@node ML501 Debug Interface
1307 468 julius
@subsection Debug Interface
1308 415 julius
 
1309
The debug interface uses a separate JTAG tap and some fly-leads must be connected from an @emph{ORSoC USB debugger} (http://opencores.com/shop,item,3) to the ML501.
1310
 
1311
From the USB debugger, a fly lead must take the following signals to the following pins on header J4 on the ML501.
1312
 
1313
@itemize @bullet
1314
@item
1315
tdo - HDR2_6
1316
@item
1317
tdi - HDR2_8
1318
@item
1319
tms - HDR2_10
1320
@item
1321
tck - HDR2_12
1322
@end itemize
1323
 
1324
This corresponds to right-most column of pins on the J4 header, starting on the third row going down.
1325
 
1326
Supply and ground pins must also be hooked up for the USB debugger.
1327
 
1328
The left column of pins on J4 are all tied to ground. All pins on J7 (expansion header located adjacent to J4) are all tied to VCC2V5, 2.5V DC, and this is OK for supplying the buffers on the USB debug cable, and can be used. So essentially put the supply leads anywhere on J7 and ground leads anywhere on the left column of J4.
1329
 
1330
Once the debug interface is connected, the @code{or_debug_proxy} application can be used to provide a stub for GDB to connect to. See http://opencores.org/openrisc,debugging_physical for more information.
1331
 
1332
@node ML501 UART
1333 468 julius
@subsection UART
1334 415 julius
 
1335
There are 2 ways of connecting to the UART in the design.
1336
 
1337
One is via the usual serial port connector, P3, on the ML501. This will obviously require a PC with a serial input and appropriate terminal application.
1338
 
1339
There is also a connection available via the USB debugger mentioned in the previous subsection.
1340
 
1341
The following pins are used for RX/TX to/from the design on header J4.
1342
 
1343
@itemize @bullet
1344
@item
1345
UART RX - HDR2_2
1346
@item
1347
UART TX - HDR2_4
1348
@end itemize
1349
 
1350
Again, supply and ground leads for the UART drivers on the USB debugger can be sourced from J7/left-column J4 as per the debug interface subsection.
1351
 
1352
If both UART and debug interface are connected via the ORSoC USB debugger, this ultimately ends up witht he first 2 pins on the right column of J4 as RX/TX for the UART then the JTAG TDO, TDI, TMS and TCK in succession down the right column of J4.
1353
 
1354
See the ML501 schematic (http://www.xilinx.com/support/documentation/boards_and_kits/ml501_20061010_bw.pdf) for more details on these headers, and refer to the pinouts in the ML501 UCF, in the board's @code{backend/par/bin/ml501.ucf} file.
1355
 
1356 468 julius
@c ****************************************************************************
1357
@c Software section
1358
@c ****************************************************************************
1359 415 julius
 
1360 468 julius
 
1361
@node Software
1362
@chapter Software
1363
 
1364
@cindex software use of @value{ORPSOC}
1365
 
1366
This section details the structure of the software library included in @value{ORPSOC}.
1367
 
1368
@node Software Overview
1369
@section Overview
1370
 
1371
The software provided with ORPSoC is intended to be of sufficient functionality to develop and test the designs, with some additional utility programs for board bring up.
1372
 
1373
The bulk of the software library consists of drivers and tests for the included RTL modules, focusing on the processor. A basic C library, implementing basic support functions such as printf, is included. This alleviates the prerequisite of a compiler with supporting C library installed.
1374
 
1375
Each board port may contain additional software drivers and tests in its own software directory, the structure of which mimics that of the main software directory.
1376
 
1377
@node Software Componenets
1378
@section Components
1379
 
1380
This section outlines the different components of the software library in the @code{sw/} path in the root of @value{ORPSOC}.
1381
 
1382
 
1383
@node Software Components Applications
1384
@subsection Applications
1385
 
1386
There are some included applications, which are neither drivers or tests.
1387
 
1388
Typically these will contain a @code{README} file in their directories which contain information on the software and its use.
1389
 
1390
In general, these are to be run on hardware, and thus will need to be compiled for a specific board. Be sure to pass the @code{BOARD} environment variable when compiling to pick up the appropriate board configuration. @xref{Software For Board Ports} for an example.
1391
 
1392
@node Software Components Drivers
1393
@subsection Drivers
1394
 
1395
Each RTL component may have a driver, which will be compiled into the liborpsoc library and be made available to applications and tests that use the library.
1396
 
1397
Each driver path should contain its source and an include path for driver headers.
1398
 
1399
@node Software Components CPU Drivers
1400
@subsection CPU Drivers
1401
 
1402
An attempt has been made to make the interface to basic CPU functions as generic as possible. This can allow different CPUs to be implemented in @value{ORPSOC}.
1403
 
1404
The header file @code{cpu-utils.h} should be included to gain access to the CPU driver functions, such as timers, special purpose registers, memory access macros, etc. This header will, in turn, include the appropriate CPU driver header.
1405
 
1406
@emph{Note:} What is included in the CPU driver, and how it should be interfaced is not documented yet, but in future every effort should be made to ensure a generic interface to CPU functions is used.
1407
 
1408
At present only the OR1200 has a driver, but it is intended that alternate OpenRISC processors can be implemented into ORPSoC and a driver for it to be easily used in the library.
1409
 
1410
The environment variable @code{CPU_DRIVER} is used to specify which driver is the CPU driver to be used at liborpsoc compile time.
1411
 
1412
@node Software Components Tests
1413
@subsection Tests
1414
 
1415
Each test subdirectory contains directories for each target. Usually there's just @code{sim} and @code{board}, the difference between the two being longer run-time and use of UART for board-targeted tests.
1416
 
1417
@emph{Note:} Test directory names should not contain hyphens or underscores. Test software files should be named with the single test directory name first, followed by a single word, eg. @code{or1200-simple.c}.
1418
 
1419
Test names are referenced using this @code{module}-@code{testname} pair. The automated testing mechanism implemented by the Makefile scripts will always search the @code{sim} paths for tests, rather than the @code{board} paths.
1420
 
1421
@emph{Note:} There is no automated testing mechnism for the board-targeted software yet. It is anticipated that a testing harness for these will be developed, and we encourage users to help solve this problem.
1422
 
1423
@node Software Components Library
1424
@subsection Library
1425
 
1426
The @code{lib} path in the root software directory is where the code for the minimal C library is located, and is the location of the @code{liborpsoc} archive file after its compilation.
1427
 
1428
@node Software Components Board
1429
@subsection Board
1430
 
1431
The @code{board} path in the software directory may, in future, contain other board-specific code, but at present its @code{include} path houses just an important header, @code{board.h} used for configuring the software when compiling programs targeted at a specific board port.
1432
 
1433
This file contains mainly defines of things such as the CPU frequency and timer rate, peripheral base addresses, IRQ numbers, and other board-specific defines. Each board port should contain its own, and is one of the reasons for passing the @code{BOARD} environment variable when compiling software targeted at a specific board port - so its board-specific defines will be used instead of the reference design's.
1434
 
1435
@node Software Components Utilities
1436
@subsection Utilities
1437
 
1438
The @code{utils} path contains tools used to help manipulate binary software images for a variety of purposes. All tools are designed to be run on the host machine, and not on ORPSoC.
1439
 
1440
 
1441
@node Software For Board Ports
1442
@section Software For Board Ports
1443
 
1444
Each board port will have its own software directory, if only to keep its @code{board.h} header file, specifying system parameters specific to the board.
1445
 
1446
It may also contain drivers and tests specific to peripherals for that board.
1447
 
1448
@emph{Note:} For any tests or drivers named the same found in both a board's software path and the root software path, the @emph{board's} software will be used instead.
1449
 
1450
@emph{Note:} When compiling any software in the @emph{root} software path (such as in the applications folder) intended to run on a particular board, make use of the @code{BOARD} variable to indicat which board's configuration (@code{board.h} file, and any board-specific drivers) to use. For example:
1451
 
1452
@example
1453
@kbd{orpsoc/sw/apps/app1$ make app1.elf BOARD=xilinx/ml501}
1454
@end example
1455
 
1456
It's also advisable to do a @code{make distclean} prior to clear out any preexisting libraries that may not contain software appropriate for the targeted board port (it may have been built with the reference design's @code{board.h}, for example.)
1457
 
1458
 
1459
 
1460 397 julius
@c ****************************************************************************
1461
@c End bits
1462
@c ****************************************************************************
1463
 
1464
@node  GNU Free Documentation License
1465
@chapter GNU Free Documentation License
1466
@cindex license for @value{ORPSOC}
1467
 
1468
@include fdl-1.2.texi
1469
 
1470
@node Index
1471
 
1472
@unnumbered Index
1473
 
1474
@printindex cp
1475
 
1476
@bye
1477
 

powered by: WebSVN 2.1.0

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