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

Subversion Repositories openrisc

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

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

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

powered by: WebSVN 2.1.0

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