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

Subversion Repositories openrisc

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

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 655 julius
@author Issue 4 for @value{ORPSOC}
36 397 julius
 
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 408 julius
* ORDB1A3PE1500::
63 415 julius
* ML501::
64 568 julius
* S3ADSP1800::
65 650 julius
* Atlys::
66 485 julius
* Generic Designs::
67 468 julius
* Software::
68 650 julius
* EDA tool notes::
69 397 julius
* GNU Free Documentation License::  The license for this documentation
70
* Index::
71
@end menu
72
 
73 408 julius
@node Document Introduction
74 397 julius
@chapter Introduction
75
 
76
@cindex introduction to this @value{ORPSOC}
77
 
78 560 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 programmed on physical hardware.
79 397 julius
 
80 560 julius
The reference system is the least complex implementation and consists of just enough to test the processor's functionality. The board-targeted builds typically include many additional peripherals.
81 397 julius
 
82 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.
83 397 julius
 
84
@c ****************************************************************************
85
@c Project Organisation
86
@c ****************************************************************************
87
 
88
@node Project Organisation
89
@chapter Project Organisation
90
@cindex organisation of @value{ORPSOC} project
91
 
92
@menu
93
* Overview::
94
* Software::
95
* RTL::
96
* Testbenches::
97
* Reference And Board Designs::
98
@end menu
99
 
100 408 julius
@node Organisation Overview
101
@section Organisation Overview
102 397 julius
 
103 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.
104 397 julius
 
105 530 julius
Organising a single project to satisfy these requirements can lead to some overlap and redundancy. This section is intended to make the organisation of the project clear.
106 397 julius
 
107 530 julius
The reference implementation based in the root (base directory) of the project contains enough components 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.
108 425 julius
 
109
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.
110
 
111 397 julius
The following sections outline the organisation of the software, RTL, and board designs.
112
 
113 408 julius
@node Software Organisation
114 397 julius
@section Software
115
 
116 530 julius
The @code{sw} path contains primarily target software (code intended for cross-compilation and execution on an OpenRISC processor.) There is also a path, @code{sw/utils} containing custom tools, intended to be run on the host, for manipulation of binary software images.
117 397 julius
 
118 530 julius
Driver software, implementing access functions for hardware modules, are found under @code{sw/drivers}.
119 397 julius
 
120 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}.
121
 
122
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.
123
 
124 530 julius
@emph{Note:} It is expected in the future that the OpenRISC toolchain based on newlib will provide all of the necessary support software provided in this CPU-specific driver path. When the first release of the newlib-based toolchain occurs it is expected the software in ORPSoC will be changed to use this toolchain instead.
125
 
126 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.
127
 
128 530 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 and be more verbose and perhaps run orders of magnitudes more tests.
129 397 julius
 
130 425 julius
@node Software Test Naming
131 650 julius
@subsection Software Test Naming
132 397 julius
 
133 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}.
134
 
135 650 julius
@xref{Software}, for further details.
136 468 julius
 
137 408 julius
@node RTL Organisation
138 397 julius
@section RTL
139
 
140 650 julius
The HDL code layout conforms to those outlined in the OpenCores.org coding guidelines. @uref{http://cdn.opencores.org/downloads/opencores_coding_guidelines.pdf}
141 397 julius
 
142 425 julius
There are, however, some naming restrictions for this project.
143 397 julius
 
144 530 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 (...);}.
145 425 julius
 
146
This will avoid confusion and help the scripts locate modules.
147
 
148
@subsection Verilog HDL
149
 
150
All RTL included in the project at this point is Verilog HDL, although it would be fine to add VHDL to a board build.
151
 
152 408 julius
@node Testbench Organisation
153
@section Testbench
154 397 julius
 
155 425 julius
For each design in @value{ORPSOC} there will be a testbench instantiating the top level, and any required peripherals.
156 397 julius
 
157 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.
158 397 julius
 
159 530 julius
It is expected that by running the command @code{make rtl-test} in each board's simulation run path, a basic simulation of the system initialising should be run.
160
 
161 408 julius
@node Organisation of Reference And Board Designs
162 397 julius
@section Reference And Board Designs
163
 
164
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.
165
 
166 425 julius
@subsection Module Selection
167 397 julius
 
168 425 julius
Typically, a board-targeted design will wish to reuse common components (processor, debug interface, Wishbone arbiters, UART etc.)
169 397 julius
 
170 564 olof
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}) or the board includes an external module in @code{boards/vendor/boardname/modules}.
171 397 julius
 
172 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.
173
 
174
 
175
 
176 397 julius
@c ****************************************************************************
177
@c Getting started
178
@c ****************************************************************************
179
 
180
@node Getting Started
181
@chapter Getting Started
182
@cindex source files for @value{ORPSOC}, downloading
183
 
184
@menu
185
* Supported Platforms::
186
* Obtaining Project Source::
187
* Required Tools::
188
@end menu
189
 
190 408 julius
@node Getting Started Supported Platforms
191 425 julius
@section Supported Host Platforms
192
@cindex host platforms supported by the @value{ORPSOC} project
193 397 julius
 
194
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.
195
 
196 425 julius
Unless indicated otherwise, support for the project under Cygwin on Microsoft Windows platforms cannot be assumed.
197 397 julius
 
198 408 julius
@node Getting Started Obtaining Project Source
199 397 julius
@section Obtaining Project Source
200
@cindex getting a copy of the @value{ORPSOC} project
201
 
202
The source for @value{ORPSOC} can be obtained from the OpenCores subversion (SVN) server.
203
 
204
@example
205
@kbd{svn export http://opencores.org/ocsvn/openrisc/openrisc/trunk/orpsocv2}
206
@end example
207
 
208 408 julius
@node Getting Started Required Tools
209 397 julius
@section Required Tools
210
@cindex tools and utilities required for @value{ORPSOC}
211
 
212
 
213
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.
214
 
215 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.
216 397 julius
 
217
The required tools can be divided into four groups.
218
 
219
@itemize @bullet
220
@item
221
Host system tools - things like gcc, make, texinfo.
222
 
223
@item
224 530 julius
Target system toolchain and software - the OpenRISC GNU toolchain, with gcc cross-compiler, support libraries, the GNU debugger (gdb), OpenRISC port of various OSes and RTOS, etc.
225 397 julius
 
226
@item
227
Electronic design automation (EDA) tools - preprocessors, simulators, FPGA tool suites, etc.
228
 
229
@item
230
Debug tools - tools providing control over the system on target
231
@end itemize
232
 
233
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.
234
 
235
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.
236
 
237
Anyone implementing their own board port is encouraged to document, as best they can, any problematic tool installations and contribute them to this document.
238
 
239
 
240
 
241
@c ****************************************************************************
242
@c Reference Design chapter
243
@c ****************************************************************************
244
 
245
@node Reference Design
246
@chapter Reference Design
247
@cindex reference design
248
 
249
@menu
250
* Overview::
251
* Structure::
252
* Tools::
253
* Simulation::
254
* Synthesis::
255
@end menu
256
 
257 408 julius
@node Reference Design Overview
258 468 julius
@section Overview
259 397 julius
 
260 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.
261 397 julius
 
262 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.
263 397 julius
 
264
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.
265
 
266
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.
267
 
268
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.
269
 
270 408 julius
@node Reference Design Structure
271 468 julius
@section Structure
272 397 julius
 
273
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.
274
 
275
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}.
276
 
277 408 julius
@node Reference Design RTL
278 468 julius
@subsection RTL
279 397 julius
 
280
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.
281
 
282
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.
283
 
284 564 olof
External modules using the OpenCores structure can be put under each boards @code{modules} directory. The scripts will the look for verilog files under @code{modules/<module_name>/rtl/verilog}.
285
 
286 397 julius
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 650 julius
@node Reference Design Simulation Instructions
346 468 julius
@section Simulation
347 397 julius
 
348
@menu
349
* RTL::
350
* Cycle Accurate::
351
* Results::
352
@end menu
353
 
354 650 julius
@node Reference Design RTL Simulation
355 468 julius
@subsection RTL
356 397 julius
@cindex rtl simulation of reference design
357
 
358
All simulations of the reference design are run from the @code{sim/run} path.
359
 
360 468 julius
@subheading Running RTL Regression Test
361 397 julius
 
362
The simplest way of starting a run through the regression test, using the default RTL simulator, Icarus Verilog, can be done with:
363
 
364
@example
365
@kbd{make rtl-tests}
366
@end example
367
 
368 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.
369 397 julius
 
370 468 julius
@subheading Running An Individual Test
371 397 julius
 
372
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.
373
 
374
@example
375
@kbd{make rtl-test TEST=or1200-basic}
376
@end example
377
 
378 408 julius
@node Running A Set Of Specific Reference Design RTL Tests
379 468 julius
@subheading Running A Set Of Specific Tests
380 397 julius
 
381
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.
382
 
383
@example
384
@kbd{make rtl-tests TESTS="sdram-rows uart-simple or1200-mmu or1200-fp"}
385
@end example
386
 
387 468 julius
@node Providing A Precompiled ELF Executable
388
@subheading Providing A Precompiled ELF Executable
389
 
390
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.
391
 
392
@example
393
@kbd{make rtl-test USER_ELF=/path/to/myapp.elf}
394
@end example
395
 
396
The ELF will be converted to binary format, and then converted to a VMEM to be
397
loaded into the model for execution at runtime.
398
 
399
@node Providing A Custom VMEM Image
400
@subheading Providing A Custom VMEM Image
401
 
402
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.
403
 
404
@example
405
@kbd{make rtl-test USER_VMEM=/path/to/myapp.vmem}
406
@end example
407
 
408
This VMEM file will be copied into the working directory, and renamed according to what the simulated memory expects.
409
 
410 408 julius
@node Options For Reference Design RTL Tests
411 468 julius
@subheading Options For RTL Tests
412 397 julius
 
413
There are some options, which can be specified through shell environment variables when running the test.
414
 
415
@table @code
416
 
417
@item VCD
418 408 julius
Set to '1' to enable @emph{value change dump} (VCD) creation in @code{sim/out/@emph{testname}.vcd}
419 397 julius
 
420
@item VCD_DELAY
421
Delay VCD creation start time by this number of timesteps (used as a Verilog @code{#delay} in the testbench.)
422
 
423
@item VCD_DELAY_INSNS
424
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.)
425
 
426
@item END_TIME
427
Force simulation end (@code{$finish}) at this time.
428
 
429
@item DISABLE_PROCESSOR_LOGS
430
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.
431
 
432
@item SIMULATOR
433
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.
434
 
435 485 julius
@item MGC_NO_VOPT
436
When using Modelsim (specifying @code{SIMULATOR=modelsim}), if the version does not include the individual @code{vopt} executable, specify @code{MGC_NO_VOPT=1} when compiling.
437
 
438 492 julius
@item VPI
439 530 julius
Pass @code{VPI=1} to have the an external JTAG debug module stall the processor just after bootup, and then provide a GDB stub (interacting with the Verilog sim via the VPI) to allow control of the system in a similar fashion to that of a physical target controlled over JTAG via a debug proxy application. The port for GDB is hard-coded to 50002. See the code in @code{bench/verilog/vpi/c} for more details.
440 492 julius
If running with Modelsim, ensure the path @code{MGC_PATH} is set and points to a directory containing a path named @code{modeltech}, which should be the Modelsim install.
441
 
442 397 julius
@end table
443
 
444
 
445
 
446 485 julius
 
447
 
448 408 julius
@node Reference Design Cycle Accurate
449 468 julius
@subsection Cycle Accurate
450 397 julius
@cindex cycle accurate simulation of reference design
451
 
452 468 julius
@subheading Running Cycle Accurate Regression Test
453 397 julius
 
454
The simplest way of starting a run through the regression test using the cycle accurate model can be done with:
455
 
456
@example
457
@kbd{make vlt-tests}
458
@end example
459
 
460
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.
461
 
462 468 julius
@subheading Running An Individual Test
463 397 julius
 
464
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.
465
 
466
@example
467
@kbd{make vlt-test TEST=or1200-basic}
468
@end example
469
 
470 468 julius
@subheading Generating Cycle Accurate Simulator Executable
471 397 julius
 
472
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.
473
 
474
@example
475
@kbd{make prepare-vlt}
476
@end example
477
 
478
The resulting executable will be @emph{Vorpsoc_top} in the @code{sim/vlt} path. Run it with the @emph{-h} option for usage instructions.
479
 
480 468 julius
@subheading Generating Automatically Profiled Cycle Accurate Simulator Executable
481 397 julius
 
482
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.
483
 
484
@example
485
@kbd{make prepare-vlt-profiled}
486
@end example
487
 
488 468 julius
@subheading Cycle Accurate Model Executable Usage
489 397 julius
 
490
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.
491
 
492
@example
493
@kbd{Vorpsoc_top --help}
494
@end example
495
 
496
A short list of options is given here.
497
 
498
@table @code
499
 
500
@item -f @var{file}
501
@itemx --program @var{file}
502
@cindex @code{-f}
503
@cindex @code{--program}
504
Load software from OR32 ELF image @var{file}
505
 
506
If unspecified, model attempts to load VMEM file @code{sram.vmem}
507
 
508
@item -v
509
@itemx --vcd
510
@cindex @code{-v}
511
@cindex @code{--vcd}
512
Dump VCD file
513
 
514
@item -e @var{value}
515
@itemx --endtime @var{value}
516
@cindex @code{-e}
517
@cindex @code{--endtime}
518
End simulation after @var{value} simulated ns
519
 
520
@item -l @var{file}
521
@itemx --log @var{file}
522
@cindex @code{-l}
523
@cindex @code{--log}
524
Log processor execution trace to @var{file}
525
 
526
@end table
527
 
528 408 julius
@node Reference Design Results
529 468 julius
@subsection Results
530 397 julius
@cindex output from simulation of reference design
531
 
532 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.
533 397 julius
 
534 468 julius
@subheading Processor Execution Trace
535 397 julius
 
536
A trace of the processor after each executed instruction is generated by both the event and cycle accurate models.
537
 
538
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}.
539
 
540 468 julius
@subheading Processor SPR Access Log
541 397 julius
 
542
A list of processor special purpose registers (SPR) accesses is created when processor logging is enabled.
543
 
544
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-sprs.log}.
545
 
546 468 julius
@subheading Processor Instruction Excecution Time Log
547 397 julius
 
548
A list of when each instruction was executed is generated when processor execution logging is enabled.
549
 
550
This is useful when debugging with VCD, and detecting at what time the problematic instructions were executed.
551
 
552
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-lookup.log}.
553
 
554 468 julius
@subheading Processor Report Mechanism Log
555 397 julius
 
556
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.
557
 
558
These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-general.log}. This is not optional.
559
 
560 468 julius
@subheading Value Change Dump (VCD)
561 397 julius
 
562
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}.
563
 
564
 
565 408 julius
@node Reference Design Synthesis
566 468 julius
@section Synthesis
567 397 julius
 
568
The reference design is not intended to be synthesised, and thus no backend scripts are provided. See the sections on the board-specific builds.
569
 
570
 
571
@c ****************************************************************************
572 408 julius
@c ORDB1A3PE1500 board build chapter
573 397 julius
@c ****************************************************************************
574
 
575 408 julius
@node ORDB1A3PE1500
576
@chapter ORDB1A3PE1500
577
@cindex ORDB1A3PE1500 board build information
578 397 julius
 
579
@menu
580
* Overview::
581
* Structure::
582
* Tools::
583
* Simulating::
584 408 julius
* Synthesis and Backend::
585
* Programming File Generation::
586
* Customising::
587 397 julius
@end menu
588
 
589 408 julius
@node ORDB1A3PE1500 Overview
590 468 julius
@section Overview
591 397 julius
 
592 408 julius
The ORDB1 (ORSoC development board 1) with Actel A3PE1500 FPGA is supported by this build.
593 397 julius
 
594 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.
595
 
596
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.
597
 
598 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.
599 408 julius
 
600
This guide will overview how to simulation, synthesize and customise the system.
601
 
602
@node ORDB1A3PE1500 Structure
603 468 julius
@section Structure
604 397 julius
 
605 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}.
606 397 julius
 
607 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.
608
 
609
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.
610
 
611
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.
612
 
613
@node ORDB1A3PE1500 Tools
614 468 julius
@section Tools
615 397 julius
 
616
@menu
617
* Host Tools::
618
* Target System Tools::
619
* EDA Tools::
620
* Debug Tools::
621
@end menu
622
 
623 408 julius
@node ORDB1A3PE1500 Host Tools
624 468 julius
@subsection Host Tools
625 408 julius
@cindex host tools required ORDB1A3PE1500
626 397 julius
 
627
Standard development suite of tools: gcc, make, etc.
628
 
629 408 julius
@node ORDB1A3PE1500 Target System Tools
630 468 julius
@subsection Target System Tools
631 408 julius
@cindex target system tools required ORDB1A3PE1500
632 397 julius
 
633
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
634
 
635 408 julius
@node ORDB1A3PE1500 EDA Tools
636 468 julius
@subsection EDA Tools
637 408 julius
@cindex EDA tools required ORDB1A3PE1500
638 397 julius
 
639
RTL, gatelevel simulation: Mentor Graphics' Modelsim
640
Synthesis: Synopsys Synplify (included in Actel Libero Suite)
641
Backend: Actel Designer (included in Actel Libero Suite)
642
Programming: Actel FlashPRO (included in Actel Libero Suite)
643
 
644 530 julius
This has been tested with with Libero versions 8.6, 9.0sp1 and 9.1 under Ubuntu Linux. It is recommended the very latest version available be used.
645 408 julius
 
646
@node ORDB1A3PE1500 Debug Tools
647 468 julius
@subsection Debug Tools
648 408 julius
@cindex Debug tools required ORDB1A3PE1500
649 397 julius
 
650
or_debug_proxy, ORPmon
651
 
652 408 julius
@node ORDB1A3PE1500 Simulating
653 468 julius
@section Simulating
654 408 julius
@cindex simulating ORDB1A3PE1500
655 397 julius
 
656 468 julius
@subheading Run RTL Regression Test
657 408 julius
 
658
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
659
 
660
@example
661
@kbd{make rtl-tests}
662
@end example
663
 
664 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}.
665 408 julius
 
666 409 julius
Options specific to the ORDB1A3PE1500 build.
667
 
668
@table @code
669
 
670
@item PRELOAD_RAM
671
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
672
 
673
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.
674
 
675
 
676
@end table
677
 
678
 
679
 
680 408 julius
@node ORDB1A3PE1500 Synthesis
681 468 julius
@section Synthesis
682 408 julius
 
683
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.
684
 
685
@example
686
@kbd{make all}
687
@end example
688
 
689
This will create a EDIF netlist in @code{syn/synplify/out}.
690
 
691
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.
692
 
693
@node ORDB1A3PE1500 Synthesis Options
694 468 julius
@subsection Options
695 408 julius
 
696
The following can be passed as environment variables when running @kbd{make all}.
697
 
698
@table @code
699
 
700
@item RTL_TOP
701
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.
702
 
703
@item FPGA_PART
704
Defaults to A3PE1500 but if targeting any other set it with this.
705
 
706
@item FPGA_FAMILY
707
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
708
 
709
@item FPGA_PACKAGE
710
Defaults to PQFP208 but if targeting any other set it with this.
711
 
712
@item FPGA_SPEED_GRADE
713
Defaults to Std but if targeting any other set it with this.
714
 
715
@item FREQ
716
Target frequency for synthesis.
717
 
718
@item MAXFAN
719
Maximum net fanout.
720
 
721
@item MAXFAN_HARD
722
Hard limit on maximum net fanout.
723
 
724
@item GLOBALTHRESH
725
Threshold of fanout before promoting signal to a global routing net.
726
 
727
@item RETIMING
728
Defaults to '1' (on) but set to '0' to disable.
729
 
730
@item RESOURCE_SHARING
731
Defaults to '1' (on) but set to '0' to disable.
732
 
733
@item DISABLE_IO_INSERTION
734
Defaults to '0' (off) but set to '1' to enable. Useful when synthesizing individual modules not intended as a top level.
735
 
736
@end table
737
 
738
@node ORDB1A3PE1500 Synthesis Warnings
739 468 julius
@subsection Checks
740 408 julius
 
741
The following is a list of some considerations before synthesis.
742
 
743
@itemize @bullet
744
@item bootrom.v
745
 
746 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.
747 408 julius
 
748 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.
749 408 julius
 
750
 
751
@item Clean away old leftovers
752
 
753
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.
754
 
755
 
756
@item Check Command Line Options
757
 
758
If using any command line settings, they can be checked by passing them to the following make target: @kbd{make print-config}
759
 
760
 
761
@end itemize
762
 
763
@node ORDB1A3PE1500 Place and Route
764 468 julius
@section Place and Route
765 408 julius
 
766
Place and route is run from the board's @code{backend/par/run} path with the following command.
767
 
768
@example
769
@kbd{make all}
770
@end example
771
 
772
This will create a @code{.adb} file in the same path.
773
 
774 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.
775 408 julius
 
776
@node ORDB1A3PE1500 Place and route options
777 468 julius
@subsection Options
778 408 julius
 
779 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.
780 408 julius
 
781
The following can be passed as environment variables when running @kbd{make all}.
782
 
783
@table @code
784
 
785
@item FPGA_PART
786
Defaults to A3PE1500 but if targeting any other set it with this.
787
 
788
@item FPGA_FAMILY
789
Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.
790
 
791
@item FPGA_PACKAGE
792
Defaults to ``208 PQFP'' but if targeting any other set it with this.
793
 
794
 
795
@item FPGA_SPEED_GRADE
796
Defaults to Std but if targeting any other set it with this.
797
 
798
@item FPGA_VOLTAGE
799
Defaults to 1.5 but if targeting any other set it with this.
800
 
801
@item FPGA_TEMP_RANGE
802
Defaults to COM but if targeting any other set it with this.
803
 
804
@item FPGA_VOLT_RANGE
805
Defaults to COM but if targeting any other set it with this.
806
 
807
@item PLACE_INCREMENTAL
808
Defaults to off.
809
 
810
@item ROUTE_INCREMENTAL
811
Defaults to off.
812
 
813
@item PLACER_HIGH_EFFORT
814
Defaults to off.
815
 
816
@item BOARD_CONFIG
817
Defaults to @code{orsoccpuexpio.mkpinassigns}
818
 
819
@end table
820
 
821
@node ORDB1A3PE1500 Constraints
822 468 julius
@subsection Constraints
823 408 julius
 
824
 
825
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.
826
 
827
 
828
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}.
829
 
830
 
831
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.
832
 
833
@example
834
@kbd{make pdc-file sdc-file}
835
@end example
836
 
837
These can be generated and edited and then used when running place and route, they will not get replaced.
838
 
839
@node ORDB1A3PE1500 Programming File Generation
840 468 julius
@section Programming File Generation
841 408 julius
 
842
The @code{.adb} file resulting from place and route can be opened in the Actel @emph{Designer} tool and a programming file generated there.
843
 
844
Once this programming file is created, Actel's @emph{FlashPro} can used to program the ORDB1A3PE1500 board.
845
 
846
@node ORDB1A3PE1500 Customising
847 468 julius
@section Customising
848 408 julius
 
849
The versatile nature of the ORDB1A3PE1500 means the design that goes on it must be equally versatile, if not more so.
850
 
851
The following sections have information on how to configure the design.
852
 
853
@node ORDB1A3PE1500 Customising Enabling Existing Modules
854 468 julius
@subsection Enabling Existing RTL Modules
855 408 julius
 
856
The design relies on the Verilog HDL @emph{define} function to indicate which modules are included.
857
 
858 415 julius
There are only a few modules included by default.
859 408 julius
 
860
@itemize @bullet
861
@item Processor - @emph{or1200}
862
@item Clock and reset generation - @emph{clkgen}
863
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
864
@end itemize
865
 
866
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
867
 
868
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.
869
 
870 530 julius
These cores should be supported and ready to go by just defining them (uncomment in the @code{orpsoc-defines.v} file.)
871 408 julius
 
872
@node ORDB1A3PE1500 Customising Adding Modules
873 468 julius
@subsection Adding RTL Modules
874 408 julius
 
875
There are a number of steps to take when adding a new module to the design.
876
 
877
@itemize @bullet
878
@item RTL Files
879
 
880 564 olof
Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
881 408 julius
 
882 564 olof
 
883
 
884 408 julius
Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
885
 
886
Place any include files into the board's @code{rtl/verilog/include} path.
887
 
888
@item Instantiate in ORPSoC Top Level File
889
 
890
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.
891
@itemize @bullet
892
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
893
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
894
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
895
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
896
@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.
897
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
898
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
899
@end itemize
900
 
901
@item Update ORPSoC Testbench
902
 
903
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
904
 
905
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
906
 
907
@item Add Software Drivers and Tests
908
 
909
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.)
910
 
911
@item Update Backend Scripts
912
 
913 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.
914 408 julius
 
915
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.
916
 
917 530 julius
Continuing the format already there should be easy enough. Remember that the @code{orpsoc-defines.v} file is parsed and it's possible to tell if the module is included by testing if the variable is defined.
918 408 julius
 
919
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.
920
 
921
@example
922
@kbd{   $(Q)if [ ! -z $$FOO1 ]; then \
923
        echo "set_io foo1_srx_i " $(FOO_SRX_BUS_SETTINGS) " \
924 410 julius
        -pinname "$(FOO1_SRX_PIN) >> $@@; \
925 408 julius
        echo "set_io foo1_tx_o\\[0\\] " $(FOO_TX_BUS_SETTINGS) " \
926 410 julius
         -pinname "$(FOO1_TX0_PIN) >> $@@; \
927 408 julius
        echo "set_io foo1_tx_o\\[1\\] " $(FOO_TX_BUS_SETTINGS) "  \
928 410 julius
        -pinname "$(FOO1_TX1_PIN) >> $@@; \
929 408 julius
        echo "set_io foo1_tx_o\\[2\\] " $(FOO_TX_BUS_SETTINGS) "  \
930 410 julius
        -pinname "$(FOO1_TX2_PIN) >> $@@; \
931 408 julius
        echo "set_io foo1_tx_o\\[3\\] " $(FOO_TX_BUS_SETTINGS) "  \
932 410 julius
        -pinname "$(FOO1_TX3_PIN) >> $@@; \
933
fi
934 408 julius
       }
935
@end example
936
 
937
@emph{(ensure there is no whitespace after the trailing backslashes.)}
938
 
939
It's a little hard to follow, but it's essentially one @code{set_io} line for each I/O line.
940
 
941
First the line checks if the module's define was exported (which happens automatically if it's defined in @code{orpsoc-defines.v}.
942
 
943
Note that what is defined can be checked by running @kbd{make print-defines} in the board's @code{backend/par/run} path.
944
 
945
The values of the bus settings variables depend on the desired I/O standards and other examples in the Makefile can be referenced.
946
 
947 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.)
948 408 julius
 
949
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.
950
 
951
The physical constraints file can be generated manually with the @kbd{make pdc-file} command.
952
 
953
@end itemize
954
 
955 415 julius
@c ****************************************************************************
956
@c ML501 board build chapter
957
@c ****************************************************************************
958 408 julius
 
959 415 julius
@node ML501
960
@chapter ML501
961
@cindex ML501 board build information
962 408 julius
 
963 415 julius
@menu
964
* Overview::
965
* Structure::
966
* Tools::
967
* Simulating::
968
* Synthesis and Backend::
969
* Programming File Generation::
970
* Customising::
971
* Running And Debugging Software::
972
@end menu
973 408 julius
 
974 415 julius
@node ML501 Overview
975 468 julius
@section Overview
976 408 julius
 
977 415 julius
The Xilinx ML501 board contains a Virtex LX50 part, varied memories and peripherals. See Xilinx's site for specific details:
978
 
979 650 julius
@uref{http://www.xilinx.com/products/devkits/HW-V5-ML501-UNI-G.htm}
980 415 julius
 
981 496 julius
The OR1200 core and Wishbone bus is set to run at 66MHz. The OR1200 core, as defined here, is almost fully featured, with every hardware arithmetic option enabled, and the largest possible cache configuration, of 1024 sets with 8 words per line which is 32 kilobytes of cache each for instruction and data buses.
982
 
983 415 julius
Not all peripherals are supported, and adding support for each is a goal.
984
 
985 655 julius
At present the build contains a memory controller for the DDR2 SDRAM (based around a Xilinx MIG derived controller), SSRAM (remains to be verified), and CFI flash. None of the other peripherals (VGA/AC97/PS2/USB/LCD) have controllers in the design yet.
986 415 julius
 
987 530 julius
The OpenCores 10/100 Ethernet MAC can be used for Ethernet, but only with the PHY in 10/100 mode using the MII interface to the Marvel Alaska Ethernet PHY IC. There still may be bugs in the FIFO buffer configuration in the ML501's @code{ethmac_defines.v} file should not be changed.
988 415 julius
 
989 560 julius
The ML501 build's scripts are capable of generating either a programming bitstream, @code{.bit}, file for direct programming of the FPGA via JTAG, or a flash image , @code{.mcs}, file which can be programmed into the on-board SPI flash which the FPGA can configure itself from on power-on. This flash image file may also contain a software image the processor can load at reset to, for example, present the user with the prompt for a boot monitor at power-on.
990 415 julius
 
991 560 julius
This guide is a work in progress, and provides the basics on simulating, building and modifying the design.
992 415 julius
 
993
@node ML501 Structure
994 468 julius
@section Structure
995 415 julius
 
996
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}.
997
 
998
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.
999
 
1000
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.
1001
 
1002 655 julius
The default configuration will result in a design which executes from the RAM at reset. For simulation, the @code{PRELOAD_RAM} option will need to be used to ensure the processor starts up correctly. To configure and simulate the build to boot from flash, see below.
1003
 
1004 415 julius
Backend files, mainly binary NGC files for mapping, are found in the board's @code{backend/bin} path.
1005
 
1006 650 julius
@node ML501 Xilinx Environment Setup
1007
@subsection ML501 Xilinx Environment Setup
1008 425 julius
 
1009 650 julius
Ensure the Xilinx environment has been setup before running all scripts for this board build. @xref{Xilinx Environment Setup}.
1010 415 julius
 
1011 560 julius
 
1012 415 julius
@node ML501 Tools
1013 468 julius
@section Tools
1014 415 julius
 
1015
@menu
1016
* Host Tools::
1017
* Target System Tools::
1018
* EDA Tools::
1019
* Debug Tools::
1020
@end menu
1021
 
1022
@node ML501 Host Tools
1023 468 julius
@subsection Host Tools
1024 415 julius
@cindex host tools required ML501
1025
 
1026
Standard development suite of tools: gcc, make, etc.
1027
 
1028
@node ML501 Target System Tools
1029 468 julius
@subsection Target System Tools
1030 415 julius
@cindex target system tools required ML501
1031
 
1032
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
1033
 
1034
@node ML501 EDA Tools
1035 468 julius
@subsection EDA Tools
1036 415 julius
@cindex EDA tools required ML501
1037
 
1038
RTL, gatelevel simulation: Mentor Graphics' Modelsim
1039
Synthesis: XST (from Xilinx ISE)
1040
Backend: ngdbuild/map/par/bitgen/promgen, etc. (from Xilinx ISE)
1041
Programming: iMPACT (from Xilinx ISE)
1042
 
1043 439 julius
This has been tested with Xilinx ISE 11.1 under Ubuntu Linux.
1044 415 julius
 
1045
 
1046
@node ML501 Debug Tools
1047 468 julius
@subsection Debug Tools
1048 415 julius
@cindex Debug tools required ML501
1049
 
1050
or_debug_proxy, ORPmon
1051
 
1052
@node ML501 Simulating
1053 468 julius
@section Simulating
1054 415 julius
@cindex simulating ML501
1055
 
1056 650 julius
Ensure the Xilinx environment has been setup before running all simulations for this board build. @xref{Xilinx Environment Setup}.
1057 415 julius
 
1058
 
1059 468 julius
@subheading Run RTL Regression Test
1060 415 julius
 
1061
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
1062
 
1063
@example
1064
@kbd{make rtl-tests}
1065
@end example
1066
 
1067 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}.
1068 415 julius
 
1069
Options specific to the ML501 build.
1070
 
1071
@table @code
1072
 
1073
@item PRELOAD_RAM
1074
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
1075
 
1076
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.
1077
 
1078
 
1079
@end table
1080
 
1081 655 julius
@node ML501 Simulating Boot From Flash
1082
@subsection Simulating Boot From Flash
1083
@cindex simulating ML501 flash boot
1084 415 julius
 
1085 655 julius
By default, the build will boot from RAM, but it is often useful to compile the design for FPGA so that it boots from a large software image in the 32MB CFI flash part (u-boot bootloader or a Linux kernel image, etc.)
1086 415 julius
 
1087 655 julius
It is, then, useful to be able to simulate this.
1088
 
1089
@subsubsection Configure the design
1090
 
1091
First, ensure the build is configured to boot from the flash memory. @xref{ML501 boot from flash configuration}.
1092
 
1093
@subsubsection Prepare the image
1094
 
1095
Next, generate an image to preload into the flash. @emph{Note}: this is not done automatically at present and must be done manually.
1096
 
1097
Create the executable for the program you wish to boot out of flash. Generate a binary of it using @code{or32-elf-objcopy} like so:
1098
 
1099
@example
1100
@kbd{or32-elf-objcopy -O binary @emph{yourexe.elf} @emph{youroutputfile.bin}}
1101
@end example
1102
 
1103
@emph{Note}: how to create software to execute out of flash on OpenRISC is not covered here, but it's likely an executable intended to execute from RAM will require subtle modifications to the reset vector code and linker script to ensure it executes from flash correctly. Consulting the OpenRISC project wiki is recommended.
1104
 
1105
Next, turn this into a VMEM image that the flash model can load. To do this use the tool found in the root @kbd{sw/utils} path called @kbd{bin2vmem}. Save this resulting VMEM it into the board's @kbd{sim/run} path and name it @kbd{cfi-flash.vmem}.
1106
 
1107
@example
1108
@kbd{.../orpsocv2/sw/utils/bin2vmem @emph{youroutputfile.bin} -bpw=2 > \}
1109
@kbd{.../orpsocv2/boards/xilinx/ml501/sim/run/cfi-flash.vmem}
1110
@end example
1111
 
1112
The resulting VMEM file should consist of the program in 2-byte words  (the point of the @kbd{-bpw=2} switch.)
1113
 
1114
@subsubsection Run the simulation
1115
 
1116
As the software to be run is potentially not from ORPSoC's testsuite, and there's no way to override the name of the test being run in a way that allows things to compile correctly, simply run the following, and all results will be stored in the board's @kbd{sim/out} path prefixed with the name of the default test, @kbd{or1200-simple}.
1117
 
1118
@example
1119
@kbd{make rtl-test}
1120
@end example
1121
 
1122
The processor will now boot from @kbd{0xf0000100} and begin executing the image from the flash.
1123
 
1124 415 julius
@node ML501 Synthesis
1125 468 julius
@section Synthesis
1126 415 julius
 
1127
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.
1128
 
1129
@example
1130
@kbd{make all}
1131
@end example
1132
 
1133
This will create an NGC file in @code{syn/xst/run} named @code{orpsoc.ngc}.
1134
 
1135
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.
1136
 
1137
@node ML501 Synthesis Options
1138 468 julius
@subsection Options
1139 415 julius
 
1140
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}.
1141
 
1142
@example
1143
@kbd{make print-config}
1144
@end example
1145
 
1146
 
1147
@node ML501 Synthesis Warnings
1148 468 julius
@subsection Checks
1149 415 julius
 
1150
The following is a list of some considerations before synthesis.
1151
 
1152
@itemize @bullet
1153
@item bootrom.v
1154
 
1155
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.
1156
 
1157 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.
1158 415 julius
 
1159
 
1160
@item Clean away old leftovers
1161
 
1162
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.
1163
 
1164
 
1165
 
1166
@end itemize
1167
 
1168
@node ML501 Synthesised Netlist
1169 468 julius
@subsection Netlist generation
1170 415 julius
 
1171
To create a Verilog HDL netlist of the post-synthesis design, run the following in the board's @code{syn/xst/run} path.
1172
 
1173
@example
1174
@kbd{make orpsoc.v}
1175
@end example
1176
 
1177
@node ML501 Place and Route
1178 468 julius
@section Place and Route
1179 415 julius
 
1180
Place and route of the design can be run from the board's @code{backend/par/run} path with the following command.
1181
 
1182
@example
1183
@kbd{make orpsoc.ncd}
1184
@end example
1185
 
1186
@node ML501 Timing Report
1187 468 julius
@section Post-PAR STA Report
1188 415 julius
 
1189
The @code{trce} tool can be used to generate a timing report of the post-place and route design.
1190
 
1191
@example
1192
@kbd{make timingreport}
1193
@end example
1194
 
1195
@node ML501 Back-annotated Netlist
1196 468 julius
@section Back-annotated Netlist
1197 415 julius
 
1198
A post-PAR back-annotated netlist can be generated with the following command.
1199
 
1200
@example
1201
@kbd{make netlist}
1202
@end example
1203
 
1204
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.
1205
 
1206
 
1207
@node ML501 Place and route options
1208 468 julius
@subsection Options
1209 415 julius
 
1210
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.
1211
 
1212
@example
1213
@kbd{make print-config}
1214
@end example
1215
 
1216
@node ML501 Constraints
1217 468 julius
@subsection Constraints
1218 415 julius
 
1219
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.
1220
 
1221
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.
1222
 
1223
@node ML501 Programming File Generation
1224 468 julius
@section Programming File Generation
1225 415 julius
 
1226
Programming file generation is run from the board's @code{backend/par/run} path with the following command.
1227
 
1228
@example
1229
@kbd{make orpsoc.bit}
1230
@end example
1231
 
1232
This file can then be loaded into the Xilinx iMPACT program and programmed onto the Virtex 5 part on the ML501.
1233
 
1234
@node ML501 SPI programming file
1235 468 julius
@subsection SPI programming file generation
1236 415 julius
 
1237
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.
1238
 
1239
@example
1240
@kbd{make orpsoc.mcs}
1241
@end example
1242
 
1243
@node ML501 SPI programming file with software
1244 468 julius
@subsection SPI programming file generation with software
1245 415 julius
 
1246
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.
1247
 
1248
@example
1249
@kbd{make orpsoc.mcs BOOTLOADER_BIN=/path/to/bootloader-binary-file.bin}
1250
@end example
1251
 
1252
The image is allowed to be up to 256KBytes in size.
1253
 
1254
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.
1255
 
1256
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.
1257
 
1258
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.
1259
 
1260
The file pointed to by @code{BOOTLOADER_BIN} should be a binary image with the  size of the image embedded in the first word.
1261
 
1262
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:
1263
 
1264
@example
1265
@kbd{bin2binsizeword /path/to/orpmon/orpmon.or32.bin orpmon-sizeword.bin}
1266
@end example
1267
 
1268
This @code{orpmon-sizeword.bin} file should then be passed via the BOOTLOADER_BIN option when creating the @code{.mcs} file to embed it.
1269
 
1270
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.
1271
 
1272
@node ML501 SPI flash programming
1273 468 julius
@subsection SPI flash programming
1274 415 julius
 
1275 542 julius
There are two ways to program the M25P16 2MByte SPI flash from the Xilinx iMPACT tool - @emph{direct} and @emph{indirect}. Direct programming means the Xilinx programmer has a direct connection from its pins to the SPI bus. It then performs SPI accesses on the bus to erase and program the part. Indirect programming involves the FPGA and sets up connections to the SPI via it. Indirect programming may be slower, but it is the only supported method as of ISE 12 onwards.
1276
 
1277 650 julius
There may be a way of programming directly using the open source @emph{xc3sprog} tool, @uref{http://sourceforge.net/projects/xc3sprog/} , but the author is yet to figure out how, and would greatly appreciate anyone who can provide a quick rundown on how this could be achieved.
1278 542 julius
 
1279
Once programmed, booting from the SPI flash to ORPmon prompt is about 3 to 4 seconds.
1280
 
1281
@node ML501 Direct SPI flash programming
1282
@subsubsection Direct SPI flash programming
1283
 
1284
@emph{Note}: As of ISE 12, direct SPI flash programming is no longer supported. ISE 11 must be used if this method is to be used. Indirect SPI flash programming is the recommended method by Xilinx now. How annoying.
1285
 
1286 650 julius
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, @uref{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.
1287 415 julius
 
1288 650 julius
A more general explanation of direct SPI flash programming can be found in XAPP951- @uref{http://www.xilinx.com/support/documentation/application_notes/xapp951.pdf}
1289 542 julius
 
1290 415 julius
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.
1291
 
1292 650 julius
@emph{Note}: Direct 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: @uref{http://www.xilinx.com/support/documentation/application_notes/xapp1053.pdf}.
1293 415 julius
 
1294 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!
1295 415 julius
 
1296 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.
1297
 
1298 542 julius
@node ML501 Inirect SPI flash programming
1299
@subsubsection Indirect SPI flash programming
1300 479 julius
 
1301 542 julius
The indirect method of programming the SPI flash has the memory show up as an extrnal module off the FPGA when performing an automatic JTAG boundary scan.
1302 415 julius
 
1303 650 julius
The following page has more information about the steps required. @uref{http://www.xilinx.com/support/documentation/sw_manuals/xilinx11/pim_p_configure_spi_bpi_through_fpga.htm} The @code{.mcs} file required is the one generated in previous steps in this guide.
1304 415 julius
 
1305 542 julius
@emph{Note:} As we generate the @code{.mcs} file with bit/byte swapping disabled (with the use of the @code{-spi} option when running the promgen tool) we must disable iMPACT's automatic bit/byte swapping when programming the SPI flash. In ISE 12 this option is found by going to the @emph{Edit menu -> Preferences}, and  in the @emph{Configuration Preferences} category, set the @emph{SPI Byte Swap} option to @emph{Ignore Setting}.
1306
 
1307
@emph{Note:} iMPACT from ISE 12 introduced errors in the software image when being programmed. It is advisable that versions of iMPACT from ISEs other than 12 are used until this bug is fixed.
1308
 
1309 655 julius
@node ML501 platform flash programming file
1310
@subsection platform flash programming file generation
1311 542 julius
 
1312 655 julius
There are options in the backend makefile to generate programming files for the platform flash found on the ML501.
1313
 
1314
The following command will make the @code{orpsoc_platformflash.mcs} file which can be programmed into the flash via the iMPACT tool.
1315
 
1316
@example
1317
@kbd{boards/xilinx/ml501/backend/par/run$ make orpsoc_platformflash.mcs}
1318
@end example
1319
 
1320
This flash is designed to be loaded in the high-speed selectMAP mode, as it is formatted in such a way as it should be read out over a 16-bit data bus.
1321
 
1322
To program the platform flash, launch iMPACT, and initialise the scanchain.
1323
 
1324
Assign the orpsoc_platformflash.mcs file to the xcf32p part. @emph{Note:} I got a warning about the .mcs file not appearing to be a configuration file and that ``This file will not configure a Xilinx device in Serial or SelectMap modes and may not be intended for configuration.''
1325
 
1326
The option where the PROM is slave during programming was left enabled.
1327
 
1328 415 julius
@node ML501 Customising
1329 468 julius
@section Customising
1330 415 julius
 
1331
The large amount of peripherals on the ML501 means that things will want to be added or removed to suit the design.
1332
 
1333
The following sections have information on how to configure the design.
1334
 
1335 655 julius
@node ML501 boot from flash configuration
1336
@subsection Enabling Flash Boot Configuration
1337
 
1338
The following will outline how to make the OR1200 boot from the CFI flash part at reset.
1339
 
1340
In the board's @code{rtl/verilog/include/orpsoc-defines.v} ensure the following is uncommented:
1341
 
1342
@example
1343
@kbd{`define CFI_FLASH}
1344
@end example
1345
 
1346
In the board's @code{rtl/verilog/include/or1200_defines.v} ensure the following is uncommented:
1347
 
1348
@example
1349
@kbd{`define OR1200_BOOT_PCREG_DEFAULT 30'h3c00003f}
1350
@kbd{`define OR1200_BOOT_ADR 32'hf0000100}
1351
@end example
1352
 
1353
All other @code{OR1200_BOOT_*} defines nearby should be commented out.
1354
 
1355
This will ensure that (1) the CFI flash controller is enabled, and (2) the OR1200 will go straight to its reset vector in the flash memory at reset. Note that this will completely bypass the bootrom (at @code{0xe0000000}) so its configuration now is meaningless. This is on purpose, as any init code can and should be handled by software in the flash (such as u-boot.)
1356
 
1357 415 julius
@node ML501 Customising Enabling Existing Modules
1358 468 julius
@subsection Enabling Existing RTL Modules
1359 415 julius
 
1360
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.
1361
 
1362
These @code{`defines} will correspond to defines in the board's top level RTL file @code{boardpath/rtl/verilog/orpsoc_top/orpsoc_top.v}.
1363
 
1364
There are only a few modules included by default.
1365
 
1366
@itemize @bullet
1367
@item Processor - @emph{or1200}
1368
@item Clock and reset generation - @emph{clkgen}
1369
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
1370
@end itemize
1371
 
1372
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
1373
 
1374
@node ML501 Customising Adding Modules
1375 468 julius
@subsection Adding RTL Modules
1376 415 julius
 
1377
There are a number of steps to take when adding a new module to the design.
1378
 
1379
@itemize @bullet
1380
@item RTL Files
1381
 
1382 564 olof
@itemize @bullet
1383
@item Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
1384 415 julius
 
1385 564 olof
@emph{or}
1386 415 julius
 
1387 564 olof
Create a directory under the board's @code{modules} directory, containing a @code{rtl/verilog} directory, and name it the same as the top level of the module
1388 415 julius
 
1389 564 olof
@item Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
1390
 
1391
@item Place any include files into the board's @code{rtl/verilog/include} path.
1392
@end itemize
1393 415 julius
@item Instantiate in ORPSoC Top Level File
1394
 
1395
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.
1396
@itemize @bullet
1397
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
1398
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
1399
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
1400
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
1401
@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.
1402
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
1403
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
1404
@end itemize
1405
 
1406
@item Update ORPSoC Testbench
1407
 
1408
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
1409
 
1410
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
1411
 
1412
@item Add Software Drivers and Tests
1413
 
1414
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.)
1415
 
1416
@item Update Backend Scripts
1417
 
1418
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}.
1419
 
1420
@end itemize
1421
 
1422
@node ML501 Running And Debugging Software
1423 468 julius
@section Running And Debugging Software
1424 415 julius
 
1425
@node ML501 Debug Interface
1426 468 julius
@subsection Debug Interface
1427 415 julius
 
1428 650 julius
The debug interface uses a separate JTAG tap and some fly-leads must be connected from an @emph{ORSoC USB debugger} (@uref{http://opencores.com/shop,item,3}) to the ML501.
1429 415 julius
 
1430
From the USB debugger, a fly lead must take the following signals to the following pins on header J4 on the ML501.
1431
 
1432
@itemize @bullet
1433
@item
1434
tdo - HDR2_6
1435
@item
1436
tdi - HDR2_8
1437
@item
1438
tms - HDR2_10
1439
@item
1440
tck - HDR2_12
1441
@end itemize
1442
 
1443
This corresponds to right-most column of pins on the J4 header, starting on the third row going down.
1444
 
1445
Supply and ground pins must also be hooked up for the USB debugger.
1446
 
1447
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.
1448
 
1449 650 julius
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 @uref{http://opencores.org/openrisc,debugging_physical} for more information.
1450 415 julius
 
1451
@node ML501 UART
1452 468 julius
@subsection UART
1453 415 julius
 
1454
There are 2 ways of connecting to the UART in the design.
1455
 
1456
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.
1457
 
1458
There is also a connection available via the USB debugger mentioned in the previous subsection.
1459
 
1460
The following pins are used for RX/TX to/from the design on header J4.
1461
 
1462
@itemize @bullet
1463
@item
1464
UART RX - HDR2_2
1465
@item
1466
UART TX - HDR2_4
1467
@end itemize
1468
 
1469
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.
1470
 
1471 530 julius
If both UART and debug interface are connected via the ORSoC USB debugger, this ultimately ends up with the 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.
1472 415 julius
 
1473 650 julius
See the ML501 schematic (@uref{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.
1474 415 julius
 
1475 485 julius
 
1476 568 julius
 
1477 468 julius
@c ****************************************************************************
1478 568 julius
@c S3ADSP1800 board build chapter
1479
@c ****************************************************************************
1480
 
1481
@node S3ADSP1800
1482
@chapter S3ADSP1800
1483
@cindex S3ADSP1800 board build information
1484
 
1485
@menu
1486
* Overview::
1487
* Structure::
1488
* Tools::
1489
* Simulating::
1490
* Synthesis and Backend::
1491
* Programming File Generation::
1492
* Customising::
1493
* Running And Debugging Software::
1494
@end menu
1495
 
1496
@node S3ADSP1800 Overview
1497
@section Overview
1498
 
1499
The Xilinx XtremeDSP Starter Platform - Spartan-3A DSP 1800A Edition is known as the s3adsp1800 board in ORPSoC.
1500
 
1501
All information and resources relating to the board were sourced from Xilinx's board portal page:
1502
 
1503 650 julius
@uref{http://www.xilinx.com/products/boards-and-kits/HW-SD1800A-DSP-SB-UNI-G.htm}
1504 568 julius
 
1505
The build currently contains the bare essentials to get the board up and running some software on the OpenRISC processor.
1506
 
1507
The system, at present contains the OpenRISC SoC system running at 25MHz with OR1200, Wishbone B3 arbiters, a Xilinx DDR2 memory controller (125MHz) with Wishbone wrapper and the OpenCores 10/100 Ethernet MAC. Debug capabilities are available via a ORSoC USB debug cable connected to pins on header J8.
1508
 
1509
The S3ADSP1800 build's scripts are capable of generating a programming bitstream, @code{.bit}, file for direct programming of the FPGA via JTAG.
1510
 
1511
@node S3ADSP1800 Structure
1512
@section Structure
1513
 
1514
Note that in this chapter the term @emph{board path} refers to the path in the project for this board port; @code{boards/xilinx/s3adsp1800}.
1515
 
1516
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.
1517
 
1518
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.
1519
 
1520
Backend files, mainly binary NGC files for mapping, are found in the board's @code{backend/bin} path.
1521
 
1522 650 julius
@node S3ADSP1800 Xilinx Environment Setup
1523
@subsection S3ADSP1800 Xilinx Environment Setup
1524 568 julius
 
1525 650 julius
Ensure the Xilinx environment has been setup before running all scripts for this board build. @xref{Xilinx Environment Setup}.
1526 568 julius
 
1527
@node S3ADSP1800 Tools
1528
@section Tools
1529
 
1530
@menu
1531
* Host Tools::
1532
* Target System Tools::
1533
* EDA Tools::
1534
* Debug Tools::
1535
@end menu
1536
 
1537
@node S3ADSP1800 Host Tools
1538
@subsection Host Tools
1539
@cindex host tools required S3ADSP1800
1540
 
1541
Standard development suite of tools: gcc, make, etc.
1542
 
1543
@node S3ADSP1800 Target System Tools
1544
@subsection Target System Tools
1545
@cindex target system tools required S3ADSP1800
1546
 
1547
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
1548
 
1549
@node S3ADSP1800 EDA Tools
1550
@subsection EDA Tools
1551
@cindex EDA tools required S3ADSP1800
1552
 
1553
RTL, gatelevel simulation: Mentor Graphics' Modelsim
1554
Synthesis: XST (from Xilinx ISE)
1555
Backend: ngdbuild/map/par/bitgen/promgen, etc. (from Xilinx ISE)
1556
Programming: iMPACT (from Xilinx ISE)
1557
 
1558
This has been tested with Xilinx ISE 13.1 under Ubuntu 11.04.
1559
 
1560
 
1561
@node S3ADSP1800 Debug Tools
1562
@subsection Debug Tools
1563
@cindex Debug tools required S3ADSP1800
1564
 
1565
or_debug_proxy
1566
 
1567
@node S3ADSP1800 Simulating
1568
@section Simulating
1569
@cindex simulating S3ADSP1800
1570
 
1571
Note that if this path is not set, simulations will not compile.
1572
 
1573
@subheading Run RTL Regression Test
1574
 
1575
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
1576
 
1577
@example
1578
@kbd{make rtl-tests}
1579
@end example
1580
 
1581
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}.
1582
 
1583
Note that no OpenCores 10/100 Ethernet MAC (``ethmac'') tests will function correctly for the time being.
1584
 
1585
Options specific to the S3ADSP1800 build.
1586
 
1587
@table @code
1588
 
1589
@item PRELOAD_RAM
1590
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
1591
 
1592
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.
1593
 
1594
 
1595
@end table
1596
 
1597
 
1598
 
1599
@node S3ADSP1800 Synthesis
1600
@section Synthesis
1601
 
1602
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.
1603
 
1604
@example
1605
@kbd{make all}
1606
@end example
1607
 
1608
This will create an NGC file in @code{syn/xst/run} named @code{orpsoc.ngc}.
1609
 
1610
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.
1611
 
1612
@node S3ADSP1800 Synthesis Options
1613
@subsection Options
1614
 
1615
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}.
1616
 
1617
@example
1618
@kbd{make print-config}
1619
@end example
1620
 
1621
 
1622
@node S3ADSP1800 Synthesis Warnings
1623
@subsection Checks
1624
 
1625
The following is a list of some considerations before synthesis.
1626
 
1627
@itemize @bullet
1628
@item bootrom.v
1629
 
1630
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.
1631
 
1632
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.
1633
 
1634
 
1635
@item Clean away old leftovers
1636
 
1637
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.
1638
 
1639
 
1640
 
1641
@end itemize
1642
 
1643
@node S3ADSP1800 Synthesised Netlist
1644
@subsection Netlist generation
1645
 
1646
To create a Verilog HDL netlist of the post-synthesis design, run the following in the board's @code{syn/xst/run} path.
1647
 
1648
@example
1649
@kbd{make orpsoc.v}
1650
@end example
1651
 
1652
@node S3ADSP1800 Place and Route
1653
@section Place and Route
1654
 
1655
Place and route of the design can be run from the board's @code{backend/par/run} path with the following command.
1656
 
1657
@example
1658
@kbd{make orpsoc.ncd}
1659
@end example
1660
 
1661
@node S3ADSP1800 Timing Report
1662
@section Post-PAR STA Report
1663
 
1664
The @code{trce} tool can be used to generate a timing report of the post-place and route design.
1665
 
1666
@example
1667
@kbd{make timingreport}
1668
@end example
1669
 
1670
@node S3ADSP1800 Back-annotated Netlist
1671
@section Back-annotated Netlist
1672
 
1673
A post-PAR back-annotated netlist can be generated with the following command.
1674
 
1675
@example
1676
@kbd{make netlist}
1677
@end example
1678
 
1679
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.
1680
 
1681
 
1682
@node S3ADSP1800 Place and route options
1683
@subsection Options
1684
 
1685
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.
1686
 
1687
@example
1688
@kbd{make print-config}
1689
@end example
1690
 
1691
@node S3ADSP1800 Constraints
1692
@subsection Constraints
1693
 
1694
A Xilinx User Constraints File (UCF) file is in the board's @code{backend/par/bin} path. It is named @code{s3adsp1800.ucf}. It should be edited if any extra I/O or constraints are required.
1695
 
1696
Note that if modules are enabled or disabled via their @code{`define} line in @code{orpsoc-defines.v} and they have I/O declared, then this I/O will need to be manually commented out of the UCF to avoid errors during mapping.
1697
 
1698
@node S3ADSP1800 Programming File Generation
1699
@section Programming File Generation
1700
 
1701
Programming file generation is run from the board's @code{backend/par/run} path with the following command.
1702
 
1703
@example
1704
@kbd{make orpsoc.bit}
1705
@end example
1706
 
1707
This file can then be loaded into the Xilinx iMPACT program and programmed onto the Spartan-3A part on the S3ADSP1800.
1708
 
1709
 
1710
@node S3ADSP1800 SPI flash programming
1711
@subsection SPI flash programming
1712
 
1713
Unfortunately, it is particularly inconvient to program the flash memory that the FPGA can configure itself with at power-on.
1714
 
1715
The iMPACT tool does not contain the appropriate facility to enable this, and a Windows-only tool provided from Avnet.
1716
 
1717 650 julius
See Avnet's page on this board. @uref{http://www.em.avnet.com/spartan3a-dsp} and follow the links to ``Support Files & Downloads'' and the file named ``Programming the Intel S33 Flash'' is the guide. The following link may directly work to download the files: @uref{http://tinyurl.com/63k8r5c}
1718 568 julius
 
1719
Another way is to load on a Microblaze design and somehow program the flash via the Xilinx GUI tool. This method will not be covered here. The XAPP number of the user guide to do this escapes me right now, but I'm pretty sure you don't want to have to do that.
1720
 
1721
Potentially this flash could be programmed via the SPI core in this board build. This would result in having to flash the FPGA with the s3adsp18000 build image via JTAG first, before downloading SPI programming software with the FPGA configuration embedded in it, to be programmed into the SPI flash. This would probably be easy enough to do but the author did not have enough time to experiment it at the time of writing. Patches to this file's texinfo source describing how this could be done would be greatly appreciated.
1722
 
1723
@node S3ADSP1800 Customising
1724
@section Customising
1725
 
1726
The large amount of peripherals on the S3ADSP1800 means that things will want to be added or removed to suit the design.
1727
 
1728
The following sections have information on how to configure the design.
1729
 
1730
@node S3ADSP1800 Customising Enabling Existing Modules
1731
@subsection Enabling Existing RTL Modules
1732
 
1733
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.
1734
 
1735
These @code{`defines} will correspond to defines in the board's top level RTL file @code{boardpath/rtl/verilog/orpsoc_top/orpsoc_top.v}.
1736
 
1737
There are only a few modules included by default.
1738
 
1739
@itemize @bullet
1740
@item Processor - @emph{or1200}
1741
@item Clock and reset generation - @emph{clkgen}
1742
@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}
1743
@end itemize
1744
 
1745
The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.
1746
 
1747
@node S3ADSP1800 Customising Adding Modules
1748
@subsection Adding RTL Modules
1749
 
1750
There are a number of steps to take when adding a new module to the design.
1751
 
1752
@itemize @bullet
1753
@item RTL Files
1754
 
1755
@itemize @bullet
1756
@item Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.
1757
 
1758
@emph{or}
1759
 
1760
Create a directory under the board's @code{modules} directory, containing a @code{rtl/verilog} directory, and name it the same as the top level of the module
1761
 
1762
@item Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.
1763
 
1764
@item Place any include files into the board's @code{rtl/verilog/include} path.
1765
@end itemize
1766
@item Instantiate in ORPSoC Top Level File
1767
 
1768
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.
1769
@itemize @bullet
1770
@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.
1771
@item Add required I/Os (surrounded by appropriate @emph{`ifdef })
1772
@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.
1773
@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.
1774
@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.
1775
@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.
1776
@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.
1777
@end itemize
1778
 
1779
@item Update ORPSoC Testbench
1780
 
1781
Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)
1782
 
1783
Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.
1784
 
1785
@item Add Software Drivers and Tests
1786
 
1787
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.)
1788
 
1789
@item Update Backend Scripts
1790
 
1791
If any I/O is added, or special timing specified, the board's UCF file will need updating - see @code{backend/par/bin/s3adsp1800.ucf}.
1792
 
1793
@end itemize
1794
 
1795
@node S3ADSP1800 Running And Debugging Software
1796
@section Running And Debugging Software
1797
 
1798 650 julius
This section indicates how to connect a USB JTAG debugger to the board to control the system. At present this setup has only been tested with the ft2232-based ORSoC USB debugger  (@uref{http://opencores.com/shop,item,3}).
1799 568 julius
 
1800
 
1801 650 julius
See the USB debugger documentation and schematics on orsoc.se: @uref{http://orsoc.se/usb-jtag-debugger/}
1802 568 julius
 
1803 650 julius
Find more information about the Spartan 3 board (schematics, user guide, etc.) on the Xilinx site: @uref{http://www.xilinx.com/support/documentation/spartan-3a_dsp_board_and_kit_documentation.htm}
1804 568 julius
 
1805
@node S3ADSP1800 Debug Interface
1806
@subsection Debug Interface
1807
 
1808
The debug interface uses a separate JTAG tap and some fly-leads must be connected from an @emph{ORSoC USB debugger} to J8 on the S3ADSP1800.
1809
 
1810
From the USB debugger, a fly lead must take the following signals to the following pins on header J8 on the S3ADSP1800.
1811
 
1812
@itemize @bullet
1813
@item
1814
tdo - D0
1815
@item
1816
tdi - D1
1817
@item
1818
tms - D2
1819
@item
1820
tck - D3
1821
@end itemize
1822
 
1823
Supply and ground pins must also be hooked up for the USB debugger. They can also be found on the J8 header (either V2.5 or V3.3 should work for VCC.)
1824
 
1825 650 julius
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 @uref{http://opencores.org/openrisc,debugging_physical} for more information.
1826 568 julius
 
1827
@node S3ADSP1800 UART
1828
@subsection UART
1829
 
1830
There are 2 ways of connecting to the UART in the design.
1831
 
1832
One is via the DB89 connector, P2. This will obviously require a PC with a serial input and appropriate terminal application.
1833
 
1834
There is also a connection available via the USB debugger mentioned in the previous subsection.
1835
 
1836
The following pins on the J8 are connected to the same UART core as goes to the P2 connector. The two UART RX lines are logically ``AND''ed internally.
1837
 
1838
@itemize @bullet
1839
@item
1840
UART RX - D4
1841
@item
1842
UART TX - D5
1843
@end itemize
1844
 
1845
Again, supply and ground leads for the UART drivers on the USB debugger can be sourced from J8.
1846
 
1847 650 julius
@c ****************************************************************************
1848
@c Atlys board build chapter
1849
@c ****************************************************************************
1850 568 julius
 
1851 650 julius
@node Atlys
1852
@chapter Atlys
1853
@cindex Atlys board build information
1854
 
1855
@menu
1856
* Overview::
1857
* Structure::
1858
* Tools::
1859
* Simulating::
1860
* Synthesis and Backend::
1861
* Programming File Generation::
1862
@end menu
1863
 
1864
@node Atlys Overview
1865
@section Overview
1866
 
1867
The Atlys board is from Digilent and contains a Spartan 6 device.
1868
 
1869
More informatino can be found on the manufacturer's website: @uref{http://www.digilentinc.com/atlys/}
1870
 
1871
Note that this board port is based on the ML501 and structure and use are very similar.
1872
 
1873
@node Atlys Structure
1874
@section Structure
1875
 
1876
Note that in this chapter the term @emph{board path} refers to the path in the project for this board port; @code{boards/xilinx/atlys}.
1877
 
1878
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.
1879
 
1880
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.
1881
 
1882
Backend files, mainly binary NGC files for mapping, are found in the board's @code{backend/bin} path.
1883
 
1884
@node Atlys Xilinx Environment Setup
1885
@subsection Atlys Xilinx Environment Setup
1886
 
1887
Ensure the Xilinx environment has been setup before running all scripts for this board build. @xref{Xilinx Environment Setup}.
1888
 
1889
 
1890
@node Atlys Tools
1891
@section Tools
1892
 
1893
@menu
1894
* Host Tools::
1895
* Target System Tools::
1896
* EDA Tools::
1897
* Debug Tools::
1898
@end menu
1899
 
1900
@node Atlys Host Tools
1901
@subsection Host Tools
1902
@cindex host tools required Atlys
1903
 
1904
Standard development suite of tools: gcc, make, etc.
1905
 
1906
@node Atlys Target System Tools
1907
@subsection Target System Tools
1908
@cindex target system tools required Atlys
1909
 
1910
OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.
1911
 
1912
@node Atlys EDA Tools
1913
@subsection EDA Tools
1914
@cindex EDA tools required Atlys
1915
 
1916
RTL, gatelevel simulation: Mentor Graphics' Modelsim
1917
Synthesis: XST (from Xilinx ISE)
1918
Backend: ngdbuild/map/par/bitgen/promgen, etc. (from Xilinx ISE)
1919
Programming: iMPACT (from Xilinx ISE)
1920
 
1921
This has been tested with Xilinx ISE 11.1 under Ubuntu Linux.
1922
 
1923
 
1924
@node Atlys Debug Tools
1925
@subsection Debug Tools
1926
@cindex Debug tools required Atlys
1927
 
1928
or_debug_proxy, ORPmon/u-boot
1929
 
1930
@node Atlys Simulating
1931
@section Simulating
1932
@cindex simulating Atlys
1933
 
1934
Ensure the Xilinx environment has been setup before running all simulations for this board build. @xref{Xilinx Environment Setup}.
1935
 
1936
 
1937
@subheading Run RTL Regression Test
1938
 
1939
To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.
1940
 
1941
@example
1942
@kbd{make rtl-tests}
1943
@end example
1944
 
1945
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}.
1946
 
1947
Options specific to the Atlys build.
1948
 
1949
@table @code
1950
 
1951
@item PRELOAD_RAM
1952
Set to '1' to enable loading of the software image into RAM at the beginning of simulation.
1953
 
1954
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.
1955
 
1956
 
1957
@end table
1958
 
1959
 
1960
 
1961
@node Atlys Synthesis
1962
@section Synthesis
1963
 
1964
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.
1965
 
1966
@example
1967
@kbd{make all}
1968
@end example
1969
 
1970
This will create an NGC file in @code{syn/xst/run} named @code{orpsoc.ngc}.
1971
 
1972
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.
1973
 
1974
@node Atlys Synthesis Options
1975
@subsection Options
1976
 
1977
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}.
1978
 
1979
@example
1980
@kbd{make print-config}
1981
@end example
1982
 
1983
 
1984
@node Atlys Synthesis Warnings
1985
@subsection Checks
1986
 
1987
The following is a list of some considerations before synthesis.
1988
 
1989
@itemize @bullet
1990
@item bootrom.v
1991
 
1992
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.
1993
 
1994
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.
1995
 
1996
 
1997
@item Clean away old leftovers
1998
 
1999
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.
2000
 
2001
 
2002
 
2003
@end itemize
2004
 
2005
@node Atlys Synthesised Netlist
2006
@subsection Netlist generation
2007
 
2008
To create a Verilog HDL netlist of the post-synthesis design, run the following in the board's @code{syn/xst/run} path.
2009
 
2010
@example
2011
@kbd{make orpsoc.v}
2012
@end example
2013
 
2014
@node Atlys Place and Route
2015
@section Place and Route
2016
 
2017
Place and route of the design can be run from the board's @code{backend/par/run} path with the following command.
2018
 
2019
@example
2020
@kbd{make orpsoc.ncd}
2021
@end example
2022
 
2023
@node Atlys Timing Report
2024
@section Post-PAR STA Report
2025
 
2026
The @code{trce} tool can be used to generate a timing report of the post-place and route design.
2027
 
2028
@example
2029
@kbd{make timingreport}
2030
@end example
2031
 
2032
@node Atlys Back-annotated Netlist
2033
@section Back-annotated Netlist
2034
 
2035
A post-PAR back-annotated netlist can be generated with the following command.
2036
 
2037
@example
2038
@kbd{make netlist}
2039
@end example
2040
 
2041
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.
2042
 
2043
 
2044
@node Atlys Place and route options
2045
@subsection Options
2046
 
2047
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.
2048
 
2049
@example
2050
@kbd{make print-config}
2051
@end example
2052
 
2053
@node Atlys Constraints
2054
@subsection Constraints
2055
 
2056
A Xilinx User Constraints File (UCF) file is in the board's @code{backend/par/bin} path. It is named @code{atlys.ucf}. It should be edited if any extra I/O or constraints are required.
2057
 
2058
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.
2059
 
2060
@node Atlys Programming File Generation
2061
@section Programming File Generation
2062
 
2063
Programming file generation is run from the board's @code{backend/par/run} path with the following command.
2064
 
2065
@example
2066
@kbd{make orpsoc.bit}
2067
@end example
2068
 
2069
This file can then be loaded into the Xilinx iMPACT program and programmed onto the Spartan 6 part on the Atlys.
2070
 
2071
 
2072
 
2073 568 julius
@c ****************************************************************************
2074 485 julius
@c Generic Design build chapter
2075
@c ****************************************************************************
2076
 
2077 492 julius
@node Generic Designs
2078
@chapter Generic Designs
2079 485 julius
@cindex Generic design information
2080
 
2081
@menu
2082
* Overview::
2083
@end menu
2084
 
2085
 
2086
@node Generic Build Overview
2087
@section Overview
2088
 
2089
The paths under @code{boards/generic} contain designs similar to the reference design, in that they are not technology specific, and used for development of certain features of the processor, or peripherals.
2090
 
2091 492 julius
These builds are a TODO, but should provide technology-independent builds, with any specialist modules required to debug, or assist in development or demonstration of a module.
2092 485 julius
 
2093
 
2094
@c ****************************************************************************
2095 468 julius
@c Software section
2096
@c ****************************************************************************
2097 415 julius
 
2098 468 julius
 
2099
@node Software
2100
@chapter Software
2101
 
2102
@cindex software use of @value{ORPSOC}
2103
 
2104
This section details the structure of the software library included in @value{ORPSOC}.
2105
 
2106
@node Software Overview
2107
@section Overview
2108
 
2109
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.
2110
 
2111
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.
2112
 
2113
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.
2114
 
2115 530 julius
@node Software Components
2116 468 julius
@section Components
2117
 
2118
This section outlines the different components of the software library in the @code{sw/} path in the root of @value{ORPSOC}.
2119
 
2120
 
2121
@node Software Components Applications
2122
@subsection Applications
2123
 
2124
There are some included applications, which are neither drivers or tests.
2125
 
2126
Typically these will contain a @code{README} file in their directories which contain information on the software and its use.
2127
 
2128 650 julius
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}.
2129 468 julius
 
2130
@node Software Components Drivers
2131
@subsection Drivers
2132
 
2133
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.
2134
 
2135
Each driver path should contain its source and an include path for driver headers.
2136
 
2137
@node Software Components CPU Drivers
2138
@subsection CPU Drivers
2139
 
2140
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}.
2141
 
2142
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.
2143
 
2144
@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.
2145
 
2146
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.
2147
 
2148
The environment variable @code{CPU_DRIVER} is used to specify which driver is the CPU driver to be used at liborpsoc compile time.
2149
 
2150
@node Software Components Tests
2151
@subsection Tests
2152
 
2153
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.
2154
 
2155
@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}.
2156
 
2157
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.
2158
 
2159 530 julius
@emph{Note:} There is no automated testing mechanism 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.
2160 468 julius
 
2161
@node Software Components Library
2162
@subsection Library
2163
 
2164
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.
2165
 
2166
@node Software Components Board
2167
@subsection Board
2168
 
2169
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.
2170
 
2171
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.
2172
 
2173
@node Software Components Utilities
2174
@subsection Utilities
2175
 
2176
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.
2177
 
2178
 
2179
@node Software For Board Ports
2180
@section Software For Board Ports
2181
 
2182
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.
2183
 
2184
It may also contain drivers and tests specific to peripherals for that board.
2185
 
2186
@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.
2187
 
2188 530 julius
@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 indicate which board's configuration (@code{board.h} file, and any board-specific drivers) to use. For example:
2189 468 julius
 
2190
@example
2191
@kbd{orpsoc/sw/apps/app1$ make app1.elf BOARD=xilinx/ml501}
2192
@end example
2193
 
2194
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.)
2195
 
2196
 
2197 650 julius
@c ****************************************************************************
2198
@c EDA tool setup section
2199
@c ****************************************************************************
2200 468 julius
 
2201 650 julius
@node EDA tool notes
2202
@chapter EDA tool notes
2203
@cindex eda tool setup notes
2204
 
2205
EDA tool installation, setup and use notes.
2206
 
2207
@node Xilinx Environment Setup
2208
@section Xilinx Environment Setup
2209
 
2210
Be sure to execute the Xilinx setup scripts prior to running the ORPSoC scripts of boards using that technology.
2211
 
2212
Find the script in your Xilinx tool suite install path (the installer tells you where this is at the end of installation) but it should be under the ISE_DS path in recent Xilinx ISE releases.
2213
 
2214
@example
2215
@kbd{source /opt/Xilinx/13.2/ISE_DS/settings32.sh}
2216
@end example
2217
 
2218
Note that this affects the @kbd{LD_LIBRARY_PATH} environment variable and other programs may have issues caused by running this script.
2219
 
2220
 
2221 397 julius
@c ****************************************************************************
2222
@c End bits
2223
@c ****************************************************************************
2224
 
2225
@node  GNU Free Documentation License
2226
@chapter GNU Free Documentation License
2227
@cindex license for @value{ORPSOC}
2228
 
2229
@include fdl-1.2.texi
2230
 
2231
@node Index
2232
 
2233
@unnumbered Index
2234
 
2235
@printindex cp
2236
 
2237
@bye
2238
 

powered by: WebSVN 2.1.0

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