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

Subversion Repositories openrisc

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

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 415 julius
* ML501::
65 397 julius
* GNU Free Documentation License::  The license for this documentation
66
* Index::
67
@end menu
68
 
69 408 julius
@node Document Introduction
70 397 julius
@chapter Introduction
71
 
72
@cindex introduction to this @value{ORPSOC}
73
 
74 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.
75 397 julius
 
76 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.
77 397 julius
 
78 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.
79 397 julius
 
80
@c ****************************************************************************
81
@c Project Organisation
82
@c ****************************************************************************
83
 
84
@node Project Organisation
85
@chapter Project Organisation
86
@cindex organisation of @value{ORPSOC} project
87
 
88
@menu
89
* Overview::
90
* Software::
91
* RTL::
92
* Testbenches::
93
* Reference And Board Designs::
94
@end menu
95
 
96 408 julius
@node Organisation Overview
97
@section Organisation Overview
98 397 julius
 
99 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.
100 397 julius
 
101 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.
102 397 julius
 
103 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.
104
 
105
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.
106
 
107 397 julius
The following sections outline the organisation of the software, RTL, and board designs.
108
 
109 408 julius
@node Software Organisation
110 397 julius
@section Software
111
 
112 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.
113 397 julius
 
114 425 julius
Driver software, implementing access functions for hardware modules, are found under @code{sw/drivers}.
115 397 julius
 
116 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}.
117
 
118
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.
119
 
120 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.
121
 
122 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.
123 397 julius
 
124 425 julius
@node Software Test Naming
125 397 julius
 
126 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}.
127
 
128 408 julius
@node RTL Organisation
129 397 julius
@section RTL
130
 
131
The HDL code layout conforms to those outlined in the OpenCores.org coding guidelines. http://cdn.opencores.org/downloads/opencores_coding_guidelines.pdf
132
 
133 425 julius
There are, however, some naming restrictions for this project.
134 397 julius
 
135 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 (...}.
136
 
137
This will avoid confusion and help the scripts locate modules.
138
 
139
@subsection Verilog HDL
140
 
141
All RTL included in the project at this point is Verilog HDL, although it would be fine to add VHDL to a board build.
142
 
143 408 julius
@node Testbench Organisation
144
@section Testbench
145 397 julius
 
146 425 julius
For each design in @value{ORPSOC} there will be a testbench instantiating the top level, and any required peripherals.
147 397 julius
 
148 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.
149 397 julius
 
150 408 julius
@node Organisation of Reference And Board Designs
151 397 julius
@section Reference And Board Designs
152
 
153
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.
154
 
155 425 julius
@subsection Module Selection
156 397 julius
 
157 425 julius
Typically, a board-targeted design will wish to reuse common components (processor, debug interface, Wishbone arbiters, UART etc.)
158 397 julius
 
159 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}).
160 397 julius
 
161 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.
162
 
163
 
164
 
165 397 julius
@c ****************************************************************************
166
@c Getting started
167
@c ****************************************************************************
168
 
169
@node Getting Started
170
@chapter Getting Started
171
@cindex source files for @value{ORPSOC}, downloading
172
 
173
@menu
174
* Supported Platforms::
175
* Obtaining Project Source::
176
* Required Tools::
177
@end menu
178
 
179 408 julius
@node Getting Started Supported Platforms
180 425 julius
@section Supported Host Platforms
181
@cindex host platforms supported by the @value{ORPSOC} project
182 397 julius
 
183
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.
184
 
185 425 julius
Unless indicated otherwise, support for the project under Cygwin on Microsoft Windows platforms cannot be assumed.
186 397 julius
 
187 408 julius
@node Getting Started Obtaining Project Source
188 397 julius
@section Obtaining Project Source
189
@cindex getting a copy of the @value{ORPSOC} project
190
 
191
The source for @value{ORPSOC} can be obtained from the OpenCores subversion (SVN) server.
192
 
193
@example
194
@kbd{svn export http://opencores.org/ocsvn/openrisc/openrisc/trunk/orpsocv2}
195
@end example
196
 
197 408 julius
@node Getting Started Required Tools
198 397 julius
@section Required Tools
199
@cindex tools and utilities required for @value{ORPSOC}
200
 
201
 
202
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.
203
 
204 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.
205 397 julius
 
206
The required tools can be divided into four groups.
207
 
208
@itemize @bullet
209
@item
210
Host system tools - things like gcc, make, texinfo.
211
 
212
@item
213
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.
214
 
215
@item
216
Electronic design automation (EDA) tools - preprocessors, simulators, FPGA tool suites, etc.
217
 
218
@item
219
Debug tools - tools providing control over the system on target
220
@end itemize
221
 
222
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.
223
 
224
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.
225
 
226
Anyone implementing their own board port is encouraged to document, as best they can, any problematic tool installations and contribute them to this document.
227
 
228
 
229
 
230
@c ****************************************************************************
231
@c Reference Design chapter
232
@c ****************************************************************************
233
 
234
@node Reference Design
235
@chapter Reference Design
236
@cindex reference design
237
 
238
@menu
239
* Overview::
240
* Structure::
241
* Tools::
242
* Simulation::
243
* Synthesis::
244
@end menu
245
 
246 408 julius
@node Reference Design Overview
247 397 julius
@subsection Overview
248
 
249 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.
250 397 julius
 
251 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.
252 397 julius
 
253
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.
254
 
255
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.
256
 
257
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.
258
 
259 408 julius
@node Reference Design Structure
260 397 julius
@subsection Structure
261
 
262
@menu
263
* Overview::
264
* RTL::
265
* Software::
266
* Simulation::
267
@end menu
268
 
269 408 julius
@node Reference Design Overview
270 397 julius
@subsubsection Overview
271
 
272
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.
273
 
274
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}.
275
 
276 408 julius
@node Reference Design RTL
277 397 julius
@subsubsection RTL
278
 
279
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.
280
 
281
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.
282
 
283
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.
284
 
285 408 julius
@node Reference Design Software
286 397 julius
@subsubsection Software
287
 
288
The software run on the reference design is found in the @value{ORPSOC} root directory, under the @code{sw} path.
289
 
290
The test software for the or1200 processor is found under @code{sw/tests/or1200/sim}.
291
 
292
A minimal set of drivers is built into @code{liborpsoc}, and they are found under @code{sw/tests/drivers}.
293
 
294
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.
295
 
296 408 julius
@node Reference Design Simulation
297 397 julius
@subsubsection Simulation
298
 
299
The simulation of the reference design is run from the @code{sim/run} path.
300
 
301
The script controlling simulation is the file @code{sim/bin/Makefile}.
302
 
303
The generated output is kept in the @code{sim/out} path, and is cleared away when @kbd{make clean} is run.
304
 
305
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.
306
 
307 408 julius
@node Reference Design Tools
308 397 julius
@subsection Tools
309
 
310
@menu
311
* Host Tools::
312
* Target System Tools::
313
* EDA Tools::
314
* Debug Tools::
315
@end menu
316
 
317 408 julius
@node Reference Design Host Tools
318 397 julius
@subsubsection Host Tools
319
@cindex host tools required
320
 
321
Standard development suite of tools: gcc, make, etc.
322
 
323 408 julius
@node Reference Design Target System Tools
324 397 julius
@subsubsection Target System Tools
325
@cindex target system tools required
326
 
327
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
328
 
329 408 julius
@node Reference Design EDA Tools
330 397 julius
@subsubsection EDA Tools
331
@cindex EDA tools required
332
 
333
RTL simulation: Icarus Verilog (also compatible with Mentor Graphics' Modelsim)
334
Cycle Accurate Simulation: Verilator, Verilog-Perl, System-Perl, SystemC
335
 
336 408 julius
@node Reference Design Debug Tools
337 397 julius
@subsubsection Debug Tools
338
@cindex Debug tools required
339
 
340
None. The target is purely simulation, no extra utilities are required to debug.
341
 
342
 
343 408 julius
@node Reference Design Simulation
344 397 julius
@subsection Simulation
345
 
346
@menu
347
* RTL::
348
* Cycle Accurate::
349
* Results::
350
@end menu
351
 
352 408 julius
@node Reference Design RTL
353 397 julius
@subsubsection RTL
354
@cindex rtl simulation of reference design
355
 
356
All simulations of the reference design are run from the @code{sim/run} path.
357
 
358
@subsubheading Running RTL Regression Test
359
 
360
The simplest way of starting a run through the regression test, using the default RTL simulator, Icarus Verilog, can be done with:
361
 
362
@example
363
@kbd{make rtl-tests}
364
@end example
365
 
366 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.
367 397 julius
 
368
@subsubheading Running An Individual Test
369
 
370
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.
371
 
372
@example
373
@kbd{make rtl-test TEST=or1200-basic}
374
@end example
375
 
376 408 julius
@node Running A Set Of Specific Reference Design RTL Tests
377 397 julius
@subsubheading Running A Set Of Specific Tests
378
 
379
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.
380
 
381
@example
382
@kbd{make rtl-tests TESTS="sdram-rows uart-simple or1200-mmu or1200-fp"}
383
@end example
384
 
385 408 julius
@node Options For Reference Design RTL Tests
386 397 julius
@subsubheading Options For RTL Tests
387
 
388
There are some options, which can be specified through shell environment variables when running the test.
389
 
390
@table @code
391
 
392
@item VCD
393 408 julius
Set to '1' to enable @emph{value change dump} (VCD) creation in @code{sim/out/@emph{testname}.vcd}
394 397 julius
 
395
@item VCD_DELAY
396
Delay VCD creation start time by this number of timesteps (used as a Verilog @code{#delay} in the testbench.)
397
 
398
@item VCD_DELAY_INSNS
399
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.)
400
 
401
@item END_TIME
402
Force simulation end (@code{$finish}) at this time.
403
 
404
@item DISABLE_PROCESSOR_LOGS
405
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.
406
 
407
@item SIMULATOR
408
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.
409
 
410
@end table
411
 
412
 
413
 
414 408 julius
@node Reference Design Cycle Accurate
415 397 julius
@subsubsection Cycle Accurate
416
@cindex cycle accurate simulation of reference design
417
 
418
@subsubheading Running Cycle Accurate Regression Test
419
 
420
The simplest way of starting a run through the regression test using the cycle accurate model can be done with:
421
 
422
@example
423
@kbd{make vlt-tests}
424
@end example
425
 
426
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.
427
 
428
@subsubheading Running An Individual Test
429
 
430
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.
431
 
432
@example
433
@kbd{make vlt-test TEST=or1200-basic}
434
@end example
435
 
436
@subsubheading Generating Cycle Accurate Simulator Executable
437
 
438
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.
439
 
440
@example
441
@kbd{make prepare-vlt}
442
@end example
443
 
444
The resulting executable will be @emph{Vorpsoc_top} in the @code{sim/vlt} path. Run it with the @emph{-h} option for usage instructions.
445
 
446
@subsubheading Generating Automatically Profiled Cycle Accurate Simulator Executable
447
 
448
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.
449
 
450
@example
451
@kbd{make prepare-vlt-profiled}
452
@end example
453
 
454
@subsubheading Cycle Accurate Model Executable Usage
455
 
456
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.
457
 
458
@example
459
@kbd{Vorpsoc_top --help}
460
@end example
461
 
462
A short list of options is given here.
463
 
464
@table @code
465
 
466
@item -f @var{file}
467
@itemx --program @var{file}
468
@cindex @code{-f}
469
@cindex @code{--program}
470
Load software from OR32 ELF image @var{file}
471
 
472
If unspecified, model attempts to load VMEM file @code{sram.vmem}
473
 
474
@item -v
475
@itemx --vcd
476
@cindex @code{-v}
477
@cindex @code{--vcd}
478
Dump VCD file
479
 
480
@item -e @var{value}
481
@itemx --endtime @var{value}
482
@cindex @code{-e}
483
@cindex @code{--endtime}
484
End simulation after @var{value} simulated ns
485
 
486
@item -l @var{file}
487
@itemx --log @var{file}
488
@cindex @code{-l}
489
@cindex @code{--log}
490
Log processor execution trace to @var{file}
491
 
492
@end table
493
 
494 408 julius
@node Reference Design Results
495 397 julius
@subsubsection Results
496
@cindex output from simulation of reference design
497
 
498 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.
499 397 julius
 
500
@subsubheading Processor Execution Trace
501
 
502
A trace of the processor after each executed instruction is generated by both the event and cycle accurate models.
503
 
504
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}.
505
 
506
@subsubheading Processor SPR Access Log
507
 
508
A list of processor special purpose registers (SPR) accesses is created when processor logging is enabled.
509
 
510
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-sprs.log}.
511
 
512
@subsubheading Processor Instruction Excecution Time Log
513
 
514
A list of when each instruction was executed is generated when processor execution logging is enabled.
515
 
516
This is useful when debugging with VCD, and detecting at what time the problematic instructions were executed.
517
 
518
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-lookup.log}.
519
 
520
@subsubheading Processor Report Mechanism Log
521
 
522
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.
523
 
524
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-general.log}. This is not optional.
525
 
526
@subsubheading Value Change Dump (VCD)
527
 
528
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}.
529
 
530
 
531 408 julius
@node Reference Design Synthesis
532 397 julius
@subsection Synthesis
533
 
534
The reference design is not intended to be synthesised, and thus no backend scripts are provided. See the sections on the board-specific builds.
535
 
536
 
537
@c ****************************************************************************
538 408 julius
@c ORDB1A3PE1500 board build chapter
539 397 julius
@c ****************************************************************************
540
 
541 408 julius
@node ORDB1A3PE1500
542
@chapter ORDB1A3PE1500
543
@cindex ORDB1A3PE1500 board build information
544 397 julius
 
545
@menu
546
* Overview::
547
* Structure::
548
* Tools::
549
* Simulating::
550 408 julius
* Synthesis and Backend::
551
* Programming File Generation::
552
* Customising::
553 397 julius
@end menu
554
 
555 408 julius
@node ORDB1A3PE1500 Overview
556 397 julius
@subsection Overview
557
 
558 408 julius
The ORDB1 (ORSoC development board 1) with Actel A3PE1500 FPGA is supported by this build.
559 397 julius
 
560 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.
561
 
562
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.
563
 
564 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.
565 408 julius
 
566
This guide will overview how to simulation, synthesize and customise the system.
567
 
568
@node ORDB1A3PE1500 Structure
569 397 julius
@subsection Structure
570
 
571 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}.
572 397 julius
 
573 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.
574
 
575
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.
576
 
577
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.
578
 
579
@node ORDB1A3PE1500 Tools
580 397 julius
@subsection Tools
581
 
582
@menu
583
* Host Tools::
584
* Target System Tools::
585
* EDA Tools::
586
* Debug Tools::
587
@end menu
588
 
589 408 julius
@node ORDB1A3PE1500 Host Tools
590 397 julius
@subsubsection Host Tools
591 408 julius
@cindex host tools required ORDB1A3PE1500
592 397 julius
 
593
Standard development suite of tools: gcc, make, etc.
594
 
595 408 julius
@node ORDB1A3PE1500 Target System Tools
596 397 julius
@subsubsection Target System Tools
597 408 julius
@cindex target system tools required ORDB1A3PE1500
598 397 julius
 
599
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
600
 
601 408 julius
@node ORDB1A3PE1500 EDA Tools
602 397 julius
@subsubsection EDA Tools
603 408 julius
@cindex EDA tools required ORDB1A3PE1500
604 397 julius
 
605
RTL, gatelevel simulation: Mentor Graphics' Modelsim
606
Synthesis: Synopsys Synplify (included in Actel Libero Suite)
607
Backend: Actel Designer (included in Actel Libero Suite)
608
Programming: Actel FlashPRO (included in Actel Libero Suite)
609
 
610 408 julius
This has been developed with Libero v8.6 for Linux.
611
 
612
@node ORDB1A3PE1500 Debug Tools
613 397 julius
@subsubsection Debug Tools
614 408 julius
@cindex Debug tools required ORDB1A3PE1500
615 397 julius
 
616
or_debug_proxy, ORPmon
617
 
618 408 julius
@node ORDB1A3PE1500 Simulating
619
@subsection Simulating
620
@cindex simulating ORDB1A3PE1500
621 397 julius
 
622 408 julius
@subsubheading Run RTL Regression Test
623
 
624
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
625
 
626
@example
627
@kbd{make rtl-tests}
628
@end example
629
 
630 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}.
631 408 julius
 
632 409 julius
Options specific to the ORDB1A3PE1500 build.
633
 
634
@table @code
635
 
636
@item PRELOAD_RAM
637
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
638
 
639
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.
640
 
641
 
642
@end table
643
 
644
 
645
 
646 408 julius
@node ORDB1A3PE1500 Synthesis
647
@subsection Synthesis
648
 
649
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.
650
 
651
@example
652
@kbd{make all}
653
@end example
654
 
655
This will create a EDIF netlist in @code{syn/synplify/out}.
656
 
657
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.
658
 
659
@node ORDB1A3PE1500 Synthesis Options
660
@subsubsection Options
661
 
662
The following can be passed as environment variables when running @kbd{make all}.
663
 
664
@table @code
665
 
666
@item RTL_TOP
667
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.
668
 
669
@item FPGA_PART
670
Defaults to A3PE1500 but if targeting any other set it with this.
671
 
672
@item FPGA_FAMILY
673
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
674
 
675
@item FPGA_PACKAGE
676
Defaults to PQFP208 but if targeting any other set it with this.
677
 
678
@item FPGA_SPEED_GRADE
679
Defaults to Std but if targeting any other set it with this.
680
 
681
@item FREQ
682
Target frequency for synthesis.
683
 
684
@item MAXFAN
685
Maximum net fanout.
686
 
687
@item MAXFAN_HARD
688
Hard limit on maximum net fanout.
689
 
690
@item GLOBALTHRESH
691
Threshold of fanout before promoting signal to a global routing net.
692
 
693
@item RETIMING
694
Defaults to '1' (on) but set to '0' to disable.
695
 
696
@item RESOURCE_SHARING
697
Defaults to '1' (on) but set to '0' to disable.
698
 
699
@item DISABLE_IO_INSERTION
700
Defaults to '0' (off) but set to '1' to enable. Useful when synthesizing individual modules not intended as a top level.
701
 
702
@end table
703
 
704
@node ORDB1A3PE1500 Synthesis Warnings
705
@subsubsection Checks
706
 
707
The following is a list of some considerations before synthesis.
708
 
709
@itemize @bullet
710
@item bootrom.v
711
 
712 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.
713 408 julius
 
714
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.
715
 
716
 
717
@item Clean away old leftovers
718
 
719
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.
720
 
721
 
722
@item Check Command Line Options
723
 
724
If using any command line settings, they can be checked by passing them to the following make target: @kbd{make print-config}
725
 
726
 
727
@end itemize
728
 
729
@node ORDB1A3PE1500 Place and Route
730
@subsection Place and Route
731
 
732
Place and route is run from the board's @code{backend/par/run} path with the following command.
733
 
734
@example
735
@kbd{make all}
736
@end example
737
 
738
This will create a @code{.adb} file in the same path.
739
 
740 415 julius
All steps, up to programming file generation are done here. This is mainly a licensing thing (free licenses for Libero under Linux @emph{do not} allow programming file generation - they do, however, under Windows.)
741 408 julius
 
742
@node ORDB1A3PE1500 Place and route options
743
@subsubsection Options
744
 
745 415 julius
Most of the design's parameters are determined by processing the @code{orpsoc-defines.v} file and determining, for example, the frequency of the clocks entering the design.
746 408 julius
 
747
The following can be passed as environment variables when running @kbd{make all}.
748
 
749
@table @code
750
 
751
@item FPGA_PART
752
Defaults to A3PE1500 but if targeting any other set it with this.
753
 
754
@item FPGA_FAMILY
755
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
756
 
757
@item FPGA_PACKAGE
758
Defaults to ``208 PQFP'' but if targeting any other set it with this.
759
 
760
 
761
@item FPGA_SPEED_GRADE
762
Defaults to Std but if targeting any other set it with this.
763
 
764
@item FPGA_VOLTAGE
765
Defaults to 1.5 but if targeting any other set it with this.
766
 
767
@item FPGA_TEMP_RANGE
768
Defaults to COM but if targeting any other set it with this.
769
 
770
@item FPGA_VOLT_RANGE
771
Defaults to COM but if targeting any other set it with this.
772
 
773
@item PLACE_INCREMENTAL
774
Defaults to off.
775
 
776
@item ROUTE_INCREMENTAL
777
Defaults to off.
778
 
779
@item PLACER_HIGH_EFFORT
780
Defaults to off.
781
 
782
@item BOARD_CONFIG
783
Defaults to @code{orsoccpuexpio.mkpinassigns}
784
 
785
@end table
786
 
787
@node ORDB1A3PE1500 Constraints
788
@subsubsection Constraints
789
 
790
 
791
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.
792
 
793
 
794
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}.
795
 
796
 
797
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.
798
 
799
@example
800
@kbd{make pdc-file sdc-file}
801
@end example
802
 
803
These can be generated and edited and then used when running place and route, they will not get replaced.
804
 
805
@node ORDB1A3PE1500 Programming File Generation
806
@subsection Programming File Generation
807
 
808
The @code{.adb} file resulting from place and route can be opened in the Actel @emph{Designer} tool and a programming file generated there.
809
 
810
Once this programming file is created, Actel's @emph{FlashPro} can used to program the ORDB1A3PE1500 board.
811
 
812
@node ORDB1A3PE1500 Customising
813
@subsection Customising
814
 
815
The versatile nature of the ORDB1A3PE1500 means the design that goes on it must be equally versatile, if not more so.
816
 
817
The following sections have information on how to configure the design.
818
 
819
@node ORDB1A3PE1500 Customising Enabling Existing Modules
820
@subsubsection Enabling Existing RTL Modules
821
 
822
The design relies on the Verilog HDL @emph{define} function to indicate which modules are included.
823
 
824 415 julius
There are only a few modules included by default.
825 408 julius
 
826
@itemize @bullet
827
@item Processor - @emph{or1200}
828
@item Clock and reset generation - @emph{clkgen}
829
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
830
@end itemize
831
 
832
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
833
 
834
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.
835
 
836 415 julius
These cores should be supported and ready to go by just defining them (uncomment in the @code{orspco-defines.v} file.)
837 408 julius
 
838
@node ORDB1A3PE1500 Customising Adding Modules
839
@subsubsection Adding RTL Modules
840
 
841
There are a number of steps to take when adding a new module to the design.
842
 
843
@itemize @bullet
844
@item RTL Files
845
 
846
Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
847
 
848
Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
849
 
850
Place any include files into the board's @code{rtl/verilog/include} path.
851
 
852
@item Instantiate in ORPSoC Top Level File
853
 
854
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.
855
@itemize @bullet
856
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
857
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
858
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
859
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
860
@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.
861
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
862
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
863
@end itemize
864
 
865
@item Update ORPSoC Testbench
866
 
867
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
868
 
869
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
870
 
871
@item Add Software Drivers and Tests
872
 
873
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.)
874
 
875
@item Update Backend Scripts
876
 
877 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.
878 408 julius
 
879
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.
880
 
881 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.
882 408 julius
 
883
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.
884
 
885
@example
886
@kbd{   $(Q)if [ ! -z $$FOO1 ]; then \
887
        echo "set_io foo1_srx_i " $(FOO_SRX_BUS_SETTINGS) " \
888 410 julius
        -pinname "$(FOO1_SRX_PIN) >> $@@; \
889 408 julius
        echo "set_io foo1_tx_o\\[0\\] " $(FOO_TX_BUS_SETTINGS) " \
890 410 julius
         -pinname "$(FOO1_TX0_PIN) >> $@@; \
891 408 julius
        echo "set_io foo1_tx_o\\[1\\] " $(FOO_TX_BUS_SETTINGS) "  \
892 410 julius
        -pinname "$(FOO1_TX1_PIN) >> $@@; \
893 408 julius
        echo "set_io foo1_tx_o\\[2\\] " $(FOO_TX_BUS_SETTINGS) "  \
894 410 julius
        -pinname "$(FOO1_TX2_PIN) >> $@@; \
895 408 julius
        echo "set_io foo1_tx_o\\[3\\] " $(FOO_TX_BUS_SETTINGS) "  \
896 410 julius
        -pinname "$(FOO1_TX3_PIN) >> $@@; \
897
fi
898 408 julius
       }
899
@end example
900
 
901
@emph{(ensure there is no whitespace after the trailing backslashes.)}
902
 
903
It's a little hard to follow, but it's essentially one @code{set_io} line for each I/O line.
904
 
905
First the line checks if the module's define was exported (which happens automatically if it's defined in @code{orpsoc-defines.v}.
906
 
907
Note that what is defined can be checked by running @kbd{make print-defines} in the board's @code{backend/par/run} path.
908
 
909
The values of the bus settings variables depend on the desired I/O standards and other examples in the Makefile can be referenced.
910
 
911 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.)
912 408 julius
 
913
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.
914
 
915
The physical constraints file can be generated manually with the @kbd{make pdc-file} command.
916
 
917
@end itemize
918
 
919 415 julius
@c ****************************************************************************
920
@c ML501 board build chapter
921
@c ****************************************************************************
922 408 julius
 
923 415 julius
@node ML501
924
@chapter ML501
925
@cindex ML501 board build information
926 408 julius
 
927 415 julius
@menu
928
* Overview::
929
* Structure::
930
* Tools::
931
* Simulating::
932
* Synthesis and Backend::
933
* Programming File Generation::
934
* Customising::
935
* Running And Debugging Software::
936
@end menu
937 408 julius
 
938 415 julius
@node ML501 Overview
939
@subsection Overview
940 408 julius
 
941 415 julius
The Xilinx ML501 board contains a Virtex LX50 part, varied memories and peripherals. See Xilinx's site for specific details:
942
 
943
http://www.xilinx.com/products/devkits/HW-V5-ML501-UNI-G.htm
944
 
945
Not all peripherals are supported, and adding support for each is a goal.
946
 
947
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.
948
 
949
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.
950
 
951
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.
952
 
953
This guide is far from complete, but provides the basics on running simulations, and building the design.
954
 
955
@node ML501 Structure
956
@subsection Structure
957
 
958
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}.
959
 
960
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.
961
 
962
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.
963
 
964
Backend files, mainly binary NGC files for mapping, are found in the board's @code{backend/bin} path.
965
 
966 425 julius
@node ML501 XILINX_PATH
967
@subsubsection ML501 XILINX_PATH
968
 
969 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.
970
 
971
If the @code{XILINX_PATH} variable is not set correctly, the makefiles will not run.
972
 
973
@node ML501 Tools
974
@subsection Tools
975
 
976
@menu
977
* Host Tools::
978
* Target System Tools::
979
* EDA Tools::
980
* Debug Tools::
981
@end menu
982
 
983
@node ML501 Host Tools
984
@subsubsection Host Tools
985
@cindex host tools required ML501
986
 
987
Standard development suite of tools: gcc, make, etc.
988
 
989
@node ML501 Target System Tools
990
@subsubsection Target System Tools
991
@cindex target system tools required ML501
992
 
993
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
994
 
995
@node ML501 EDA Tools
996
@subsubsection EDA Tools
997
@cindex EDA tools required ML501
998
 
999
RTL, gatelevel simulation: Mentor Graphics' Modelsim
1000
Synthesis: XST (from Xilinx ISE)
1001
Backend: ngdbuild/map/par/bitgen/promgen, etc. (from Xilinx ISE)
1002
Programming: iMPACT (from Xilinx ISE)
1003
 
1004
This has been developed with Xilinx ISE 11.1 under Linux.
1005
 
1006
 
1007
@node ML501 Debug Tools
1008
@subsubsection Debug Tools
1009
@cindex Debug tools required ML501
1010
 
1011
or_debug_proxy, ORPmon
1012
 
1013
@node ML501 Simulating
1014
@subsection Simulating
1015
@cindex simulating ML501
1016
 
1017 425 julius
Ensure the @code{XILINX_PATH} environment variable is set correcetly. @xref{ML501 XILINX_PATH} for information.
1018 415 julius
 
1019 425 julius
Note that if this path is not set, simulations will not compile.
1020 415 julius
 
1021
@subsubheading Run RTL Regression Test
1022
 
1023
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
1024
 
1025
@example
1026
@kbd{make rtl-tests}
1027
@end example
1028
 
1029 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}.
1030 415 julius
 
1031
Options specific to the ML501 build.
1032
 
1033
@table @code
1034
 
1035
@item PRELOAD_RAM
1036
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
1037
 
1038
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.
1039
 
1040
 
1041
@end table
1042
 
1043
 
1044
 
1045
@node ML501 Synthesis
1046
@subsection Synthesis
1047
 
1048
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.
1049
 
1050
@example
1051
@kbd{make all}
1052
@end example
1053
 
1054
This will create an NGC file in @code{syn/xst/run} named @code{orpsoc.ngc}.
1055
 
1056
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.
1057
 
1058
@node ML501 Synthesis Options
1059
@subsubsection Options
1060
 
1061
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}.
1062
 
1063
@example
1064
@kbd{make print-config}
1065
@end example
1066
 
1067
 
1068
@node ML501 Synthesis Warnings
1069
@subsubsection Checks
1070
 
1071
The following is a list of some considerations before synthesis.
1072
 
1073
@itemize @bullet
1074
@item bootrom.v
1075
 
1076
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.
1077
 
1078
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.
1079
 
1080
 
1081
@item Clean away old leftovers
1082
 
1083
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.
1084
 
1085
 
1086
 
1087
@end itemize
1088
 
1089
@node ML501 Synthesised Netlist
1090
@subsubsection Netlist generation
1091
 
1092
To create a Verilog HDL netlist of the post-synthesis design, run the following in the board's @code{syn/xst/run} path.
1093
 
1094
@example
1095
@kbd{make orpsoc.v}
1096
@end example
1097
 
1098
@node ML501 Place and Route
1099
@subsection Place and Route
1100
 
1101
Place and route of the design can be run from the board's @code{backend/par/run} path with the following command.
1102
 
1103
@example
1104
@kbd{make orpsoc.ncd}
1105
@end example
1106
 
1107
@node ML501 Timing Report
1108
@subsection Post-PAR STA Report
1109
 
1110
The @code{trce} tool can be used to generate a timing report of the post-place and route design.
1111
 
1112
@example
1113
@kbd{make timingreport}
1114
@end example
1115
 
1116
@node ML501 Back-annotated Netlist
1117
@subsection Back-annotated Netlist
1118
 
1119
A post-PAR back-annotated netlist can be generated with the following command.
1120
 
1121
@example
1122
@kbd{make netlist}
1123
@end example
1124
 
1125
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.
1126
 
1127
 
1128
@node ML501 Place and route options
1129
@subsubsection Options
1130
 
1131
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.
1132
 
1133
@example
1134
@kbd{make print-config}
1135
@end example
1136
 
1137
@node ML501 Constraints
1138
@subsubsection Constraints
1139
 
1140
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.
1141
 
1142
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.
1143
 
1144
@node ML501 Programming File Generation
1145
@subsection Programming File Generation
1146
 
1147
Programming file generation is run from the board's @code{backend/par/run} path with the following command.
1148
 
1149
@example
1150
@kbd{make orpsoc.bit}
1151
@end example
1152
 
1153
This file can then be loaded into the Xilinx iMPACT program and programmed onto the Virtex 5 part on the ML501.
1154
 
1155
@node ML501 SPI programming file
1156
@subsubsection SPI programming file generation
1157
 
1158
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.
1159
 
1160
@example
1161
@kbd{make orpsoc.mcs}
1162
@end example
1163
 
1164
@node ML501 SPI programming file with software
1165
@subsubsection SPI programming file generation with software
1166
 
1167
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.
1168
 
1169
@example
1170
@kbd{make orpsoc.mcs BOOTLOADER_BIN=/path/to/bootloader-binary-file.bin}
1171
@end example
1172
 
1173
The image is allowed to be up to 256KBytes in size.
1174
 
1175
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.
1176
 
1177
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.
1178
 
1179
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.
1180
 
1181
The file pointed to by @code{BOOTLOADER_BIN} should be a binary image with the  size of the image embedded in the first word.
1182
 
1183
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:
1184
 
1185
@example
1186
@kbd{bin2binsizeword /path/to/orpmon/orpmon.or32.bin orpmon-sizeword.bin}
1187
@end example
1188
 
1189
This @code{orpmon-sizeword.bin} file should then be passed via the BOOTLOADER_BIN option when creating the @code{.mcs} file to embed it.
1190
 
1191
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.
1192
 
1193
@node ML501 SPI flash programming
1194
@subsubsection SPI flash programming
1195
 
1196
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.
1197
 
1198
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.
1199
 
1200
Note that this 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 .
1201
 
1202
Note that the other cable from the progammer (going to the JP1 header) @emph{must} be unplugged from the board before attempting to program the SPI flash.
1203
 
1204
Booting from the SPI flash to ORPmon prompt is about 3 to 4 seconds.
1205
 
1206
 
1207
@node ML501 Customising
1208
@subsection Customising
1209
 
1210
The large amount of peripherals on the ML501 means that things will want to be added or removed to suit the design.
1211
 
1212
The following sections have information on how to configure the design.
1213
 
1214
@node ML501 Customising Enabling Existing Modules
1215
@subsubsection Enabling Existing RTL Modules
1216
 
1217
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.
1218
 
1219
These @code{`defines} will correspond to defines in the board's top level RTL file @code{boardpath/rtl/verilog/orpsoc_top/orpsoc_top.v}.
1220
 
1221
There are only a few modules included by default.
1222
 
1223
@itemize @bullet
1224
@item Processor - @emph{or1200}
1225
@item Clock and reset generation - @emph{clkgen}
1226
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
1227
@end itemize
1228
 
1229
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
1230
 
1231
@node ML501 Customising Adding Modules
1232
@subsubsection Adding RTL Modules
1233
 
1234
There are a number of steps to take when adding a new module to the design.
1235
 
1236
@itemize @bullet
1237
@item RTL Files
1238
 
1239
Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
1240
 
1241
Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
1242
 
1243
Place any include files into the board's @code{rtl/verilog/include} path.
1244
 
1245
@item Instantiate in ORPSoC Top Level File
1246
 
1247
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.
1248
@itemize @bullet
1249
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
1250
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
1251
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
1252
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
1253
@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.
1254
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
1255
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
1256
@end itemize
1257
 
1258
@item Update ORPSoC Testbench
1259
 
1260
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
1261
 
1262
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
1263
 
1264
@item Add Software Drivers and Tests
1265
 
1266
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.)
1267
 
1268
@item Update Backend Scripts
1269
 
1270
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}.
1271
 
1272
@end itemize
1273
 
1274
@node ML501 Running And Debugging Software
1275
@subsection Running And Debugging Software
1276
 
1277
@node ML501 Debug Interface
1278
@subsubsection Debug Interface
1279
 
1280
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.
1281
 
1282
From the USB debugger, a fly lead must take the following signals to the following pins on header J4 on the ML501.
1283
 
1284
@itemize @bullet
1285
@item
1286
tdo - HDR2_6
1287
@item
1288
tdi - HDR2_8
1289
@item
1290
tms - HDR2_10
1291
@item
1292
tck - HDR2_12
1293
@end itemize
1294
 
1295
This corresponds to right-most column of pins on the J4 header, starting on the third row going down.
1296
 
1297
Supply and ground pins must also be hooked up for the USB debugger.
1298
 
1299
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.
1300
 
1301
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.
1302
 
1303
@node ML501 UART
1304
@subsubsection UART
1305
 
1306
There are 2 ways of connecting to the UART in the design.
1307
 
1308
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.
1309
 
1310
There is also a connection available via the USB debugger mentioned in the previous subsection.
1311
 
1312
The following pins are used for RX/TX to/from the design on header J4.
1313
 
1314
@itemize @bullet
1315
@item
1316
UART RX - HDR2_2
1317
@item
1318
UART TX - HDR2_4
1319
@end itemize
1320
 
1321
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.
1322
 
1323
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.
1324
 
1325
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.
1326
 
1327
 
1328 397 julius
@c ****************************************************************************
1329
@c End bits
1330
@c ****************************************************************************
1331
 
1332
@node  GNU Free Documentation License
1333
@chapter GNU Free Documentation License
1334
@cindex license for @value{ORPSOC}
1335
 
1336
@include fdl-1.2.texi
1337
 
1338
@node Index
1339
 
1340
@unnumbered Index
1341
 
1342
@printindex cp
1343
 
1344
@bye
1345
 

powered by: WebSVN 2.1.0

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