Subversion Repositories openrisc_me

@c %**end of header

@c %**end of header

@copying

@copying

This file documents the OpenRISC Reference Platform SoC, @value{ORPSOC}.

This file documents the OpenRISC Reference Platform SoC, @value{ORPSOC}.

@quotation

@quotation

Permission is granted to copy, distribute and/or modify this document

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.2 or

under the terms of the GNU Free Documentation License, Version 1.2 or

any later version published by the Free Software Foundation; with no

any later version published by the Free Software Foundation; with no

* Getting Started::

* Getting Started::

* Reference Design::

* Reference Design::

* Board Designs::

* Board Designs::

* ORDB1A3PE1500::

* ORDB1A3PE1500::

* ML501::

* ML501::

* GNU Free Documentation License::  The license for this documentation

* GNU Free Documentation License::  The license for this documentation

* Index::

* Index::

@end menu

@end menu

@node Document Introduction

@node Document Introduction

@node Software Test Naming

@node Software Test Naming

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}.

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}.

@node RTL Organisation

@node RTL Organisation

@section RTL

@section RTL

The HDL code layout conforms to those outlined in the OpenCores.org coding guidelines. http://cdn.opencores.org/downloads/opencores_coding_guidelines.pdf

The HDL code layout conforms to those outlined in the OpenCores.org coding guidelines. http://cdn.opencores.org/downloads/opencores_coding_guidelines.pdf

* Simulation::

* Simulation::

* Synthesis::

* Synthesis::

@end menu

@end menu

@node Reference Design Overview

@node Reference Design Overview

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.

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.

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.

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.

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.

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.

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.

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.

@node Reference Design Structure

@node Reference Design Structure

@menu

@menu

* Overview::

* Overview::

* RTL::

* RTL::

* Software::

* Software::

* Simulation::

* Simulation::

@end menu

@end menu

@node Reference Design Overview

@node Reference Design Overview

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.

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.

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}.

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}.

@node Reference Design RTL

@node Reference Design RTL

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.

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.

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.

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.

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.

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.

@node Reference Design Software

@node Reference Design Software

The software run on the reference design is found in the @value{ORPSOC} root directory, under the @code{sw} path.

The software run on the reference design is found in the @value{ORPSOC} root directory, under the @code{sw} path.

The test software for the or1200 processor is found under @code{sw/tests/or1200/sim}.

The test software for the or1200 processor is found under @code{sw/tests/or1200/sim}.

A minimal set of drivers is built into @code{liborpsoc}, and they are found under @code{sw/tests/drivers}.

A minimal set of drivers is built into @code{liborpsoc}, and they are found under @code{sw/tests/drivers}.

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.

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.

@node Reference Design Simulation

@node Reference Design Simulation

The simulation of the reference design is run from the @code{sim/run} path.

The simulation of the reference design is run from the @code{sim/run} path.

The script controlling simulation is the file @code{sim/bin/Makefile}.

The script controlling simulation is the file @code{sim/bin/Makefile}.

The generated output is kept in the @code{sim/out} path, and is cleared away when @kbd{make clean} is run.

The generated output is kept in the @code{sim/out} path, and is cleared away when @kbd{make clean} is run.

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.

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.

@node Reference Design Tools

@node Reference Design Tools

@menu

@menu

* Host Tools::

* Host Tools::

* Target System Tools::

* Target System Tools::

* EDA Tools::

* EDA Tools::

* Debug Tools::

* Debug Tools::

@end menu

@end menu

@node Reference Design Host Tools

@node Reference Design Host Tools

@cindex host tools required

@cindex host tools required

Standard development suite of tools: gcc, make, etc.

Standard development suite of tools: gcc, make, etc.

@node Reference Design Target System Tools

@node Reference Design Target System Tools

@cindex target system tools required

@cindex target system tools required

OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.

OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.

@node Reference Design EDA Tools

@node Reference Design EDA Tools

@cindex EDA tools required

@cindex EDA tools required

RTL simulation: Icarus Verilog (also compatible with Mentor Graphics' Modelsim)

RTL simulation: Icarus Verilog (also compatible with Mentor Graphics' Modelsim)

Cycle Accurate Simulation: Verilator, Verilog-Perl, System-Perl, SystemC

Cycle Accurate Simulation: Verilator, Verilog-Perl, System-Perl, SystemC

@node Reference Design Debug Tools

@node Reference Design Debug Tools

@cindex Debug tools required

@cindex Debug tools required

None. The target is purely simulation, no extra utilities are required to debug.

None. The target is purely simulation, no extra utilities are required to debug.

@node Reference Design Simulation

@node Reference Design Simulation

@menu

@menu

* RTL::

* RTL::

* Cycle Accurate::

* Cycle Accurate::

* Results::

* Results::

@end menu

@end menu

@node Reference Design RTL

@node Reference Design RTL

@cindex rtl simulation of reference design

@cindex rtl simulation of reference design

All simulations of the reference design are run from the @code{sim/run} path.

All simulations of the reference design are run from the @code{sim/run} path.

The simplest way of starting a run through the regression test, using the default RTL simulator, Icarus Verilog, can be done with:

The simplest way of starting a run through the regression test, using the default RTL simulator, Icarus Verilog, can be done with:

@example

@example

@kbd{make rtl-tests}

@kbd{make rtl-tests}

@end example

@end example

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.

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.

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.

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.

@example

@example

@kbd{make rtl-test TEST=or1200-basic}

@kbd{make rtl-test TEST=or1200-basic}

@end example

@end example

@node Running A Set Of Specific Reference Design RTL Tests

@node Running A Set Of Specific Reference Design RTL Tests

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.

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.

@example

@example

@kbd{make rtl-tests TESTS="sdram-rows uart-simple or1200-mmu or1200-fp"}

@kbd{make rtl-tests TESTS="sdram-rows uart-simple or1200-mmu or1200-fp"}

@end example

@end example

@node Options For Reference Design RTL Tests

@node Options For Reference Design RTL Tests

There are some options, which can be specified through shell environment variables when running the test.

There are some options, which can be specified through shell environment variables when running the test.

@table @code

@table @code

@end table

@end table

@node Reference Design Cycle Accurate

@node Reference Design Cycle Accurate

@cindex cycle accurate simulation of reference design

@cindex cycle accurate simulation of reference design

The simplest way of starting a run through the regression test using the cycle accurate model can be done with:

The simplest way of starting a run through the regression test using the cycle accurate model can be done with:

@example

@example

@kbd{make vlt-tests}

@kbd{make vlt-tests}

@end example

@end example

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.

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.

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.

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.

@example

@example

@kbd{make vlt-test TEST=or1200-basic}

@kbd{make vlt-test TEST=or1200-basic}

@end example

@end example

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.

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.

@example

@example

@kbd{make prepare-vlt}

@kbd{make prepare-vlt}

@end example

@end example

The resulting executable will be @emph{Vorpsoc_top} in the @code{sim/vlt} path. Run it with the @emph{-h} option for usage instructions.

The resulting executable will be @emph{Vorpsoc_top} in the @code{sim/vlt} path. Run it with the @emph{-h} option for usage instructions.

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.

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.

@example

@example

@kbd{make prepare-vlt-profiled}

@kbd{make prepare-vlt-profiled}

@end example

@end example

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.

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.

@example

@example

@kbd{Vorpsoc_top --help}

@kbd{Vorpsoc_top --help}

Log processor execution trace to @var{file}

Log processor execution trace to @var{file}

@end table

@end table

@node Reference Design Results

@node Reference Design Results

@cindex output from simulation of reference design

@cindex output from simulation of reference design

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.

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.

A trace of the processor after each executed instruction is generated by both the event and cycle accurate models.

A trace of the processor after each executed instruction is generated by both the event and cycle accurate models.

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}.

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}.

A list of processor special purpose registers (SPR) accesses is created when processor logging is enabled.

A list of processor special purpose registers (SPR) accesses is created when processor logging is enabled.

These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-sprs.log}.

These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-sprs.log}.

A list of when each instruction was executed is generated when processor execution logging is enabled.

A list of when each instruction was executed is generated when processor execution logging is enabled.

This is useful when debugging with VCD, and detecting at what time the problematic instructions were executed.

This is useful when debugging with VCD, and detecting at what time the problematic instructions were executed.

These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-lookup.log}.

These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-lookup.log}.

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.

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.

These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-general.log}. This is not optional.

These values are logged to a file in @code{sim/out} named @code{@emph{test-name}-general.log}. This is not optional.

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}.

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}.

@node Reference Design Synthesis

@node Reference Design Synthesis

The reference design is not intended to be synthesised, and thus no backend scripts are provided. See the sections on the board-specific builds.

The reference design is not intended to be synthesised, and thus no backend scripts are provided. See the sections on the board-specific builds.

@c ****************************************************************************

@c ****************************************************************************

* Programming File Generation::

* Programming File Generation::

* Customising::

* Customising::

@end menu

@end menu

@node ORDB1A3PE1500 Overview

@node ORDB1A3PE1500 Overview

The ORDB1 (ORSoC development board 1) with Actel A3PE1500 FPGA is supported by this build.

The ORDB1 (ORSoC development board 1) with Actel A3PE1500 FPGA is supported by this build.

As the ORDB1 is intended to be a daughter board for a variety of I/O boards its options for configuration are extensive.

As the ORDB1 is intended to be a daughter board for a variety of I/O boards its options for configuration are extensive.

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.

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.

This guide will overview how to simulation, synthesize and customise the system.

This guide will overview how to simulation, synthesize and customise the system.

@node ORDB1A3PE1500 Structure

@node ORDB1A3PE1500 Structure

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}.

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}.

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.

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.

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.

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.

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.

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.

@node ORDB1A3PE1500 Tools

@node ORDB1A3PE1500 Tools

@menu

@menu

* Host Tools::

* Host Tools::

* Target System Tools::

* Target System Tools::

* EDA Tools::

* EDA Tools::

* Debug Tools::

* Debug Tools::

@end menu

@end menu

@node ORDB1A3PE1500 Host Tools

@node ORDB1A3PE1500 Host Tools

@cindex host tools required ORDB1A3PE1500

@cindex host tools required ORDB1A3PE1500

Standard development suite of tools: gcc, make, etc.

Standard development suite of tools: gcc, make, etc.

@node ORDB1A3PE1500 Target System Tools

@node ORDB1A3PE1500 Target System Tools

@cindex target system tools required ORDB1A3PE1500

@cindex target system tools required ORDB1A3PE1500

OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.

OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.

@node ORDB1A3PE1500 EDA Tools

@node ORDB1A3PE1500 EDA Tools

@cindex EDA tools required ORDB1A3PE1500

@cindex EDA tools required ORDB1A3PE1500

RTL, gatelevel simulation: Mentor Graphics' Modelsim

RTL, gatelevel simulation: Mentor Graphics' Modelsim

Synthesis: Synopsys Synplify (included in Actel Libero Suite)

Synthesis: Synopsys Synplify (included in Actel Libero Suite)

Backend: Actel Designer (included in Actel Libero Suite)

Backend: Actel Designer (included in Actel Libero Suite)

Programming: Actel FlashPRO (included in Actel Libero Suite)

Programming: Actel FlashPRO (included in Actel Libero Suite)

This has been tested with with Libero v8.6 and v9.0sp1 under Ubuntu Linux.

This has been tested with with Libero v8.6 and v9.0sp1 under Ubuntu Linux.

@node ORDB1A3PE1500 Debug Tools

@node ORDB1A3PE1500 Debug Tools

@cindex Debug tools required ORDB1A3PE1500

@cindex Debug tools required ORDB1A3PE1500

or_debug_proxy, ORPmon

or_debug_proxy, ORPmon

@node ORDB1A3PE1500 Simulating

@node ORDB1A3PE1500 Simulating

@cindex simulating ORDB1A3PE1500

@cindex simulating ORDB1A3PE1500

To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.

To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.

@example

@example

@kbd{make rtl-tests}

@kbd{make rtl-tests}

@end table

@end table

@node ORDB1A3PE1500 Synthesis

@node ORDB1A3PE1500 Synthesis

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.

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.

@example

@example

@kbd{make all}

@kbd{make all}

This will create a EDIF netlist in @code{syn/synplify/out}.

This will create a EDIF netlist in @code{syn/synplify/out}.

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.

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.

@node ORDB1A3PE1500 Synthesis Options

@node ORDB1A3PE1500 Synthesis Options

The following can be passed as environment variables when running @kbd{make all}.

The following can be passed as environment variables when running @kbd{make all}.

@table @code

@table @code

Defaults to '0' (off) but set to '1' to enable. Useful when synthesizing individual modules not intended as a top level.

Defaults to '0' (off) but set to '1' to enable. Useful when synthesizing individual modules not intended as a top level.

@end table

@end table

@node ORDB1A3PE1500 Synthesis Warnings

@node ORDB1A3PE1500 Synthesis Warnings

The following is a list of some considerations before synthesis.

The following is a list of some considerations before synthesis.

@itemize @bullet

@itemize @bullet

@item bootrom.v

@item bootrom.v

@end itemize

@end itemize

@node ORDB1A3PE1500 Place and Route

@node ORDB1A3PE1500 Place and Route

Place and route is run from the board's @code{backend/par/run} path with the following command.

Place and route is run from the board's @code{backend/par/run} path with the following command.

@example

@example

@kbd{make all}

@kbd{make all}

This will create a @code{.adb} file in the same path.

This will create a @code{.adb} file in the same path.

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.

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.

@node ORDB1A3PE1500 Place and route options

@node ORDB1A3PE1500 Place and route options

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.

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.

The following can be passed as environment variables when running @kbd{make all}.

The following can be passed as environment variables when running @kbd{make all}.

Defaults to @code{orsoccpuexpio.mkpinassigns}

Defaults to @code{orsoccpuexpio.mkpinassigns}

@end table

@end table

@node ORDB1A3PE1500 Constraints

@node ORDB1A3PE1500 Constraints

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.

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.

@end example

@end example

These can be generated and edited and then used when running place and route, they will not get replaced.

These can be generated and edited and then used when running place and route, they will not get replaced.

@node ORDB1A3PE1500 Programming File Generation

@node ORDB1A3PE1500 Programming File Generation

The @code{.adb} file resulting from place and route can be opened in the Actel @emph{Designer} tool and a programming file generated there.

The @code{.adb} file resulting from place and route can be opened in the Actel @emph{Designer} tool and a programming file generated there.

Once this programming file is created, Actel's @emph{FlashPro} can used to program the ORDB1A3PE1500 board.

Once this programming file is created, Actel's @emph{FlashPro} can used to program the ORDB1A3PE1500 board.

@node ORDB1A3PE1500 Customising

@node ORDB1A3PE1500 Customising

The versatile nature of the ORDB1A3PE1500 means the design that goes on it must be equally versatile, if not more so.

The versatile nature of the ORDB1A3PE1500 means the design that goes on it must be equally versatile, if not more so.

The following sections have information on how to configure the design.

The following sections have information on how to configure the design.

@node ORDB1A3PE1500 Customising Enabling Existing Modules

@node ORDB1A3PE1500 Customising Enabling Existing Modules

The design relies on the Verilog HDL @emph{define} function to indicate which modules are included.

The design relies on the Verilog HDL @emph{define} function to indicate which modules are included.

There are only a few modules included by default.

There are only a few modules included by default.

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.

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.

These cores should be supported and ready to go by just defining them (uncomment in the @code{orspco-defines.v} file.)

These cores should be supported and ready to go by just defining them (uncomment in the @code{orspco-defines.v} file.)

@node ORDB1A3PE1500 Customising Adding Modules

@node ORDB1A3PE1500 Customising Adding Modules

There are a number of steps to take when adding a new module to the design.

There are a number of steps to take when adding a new module to the design.

@itemize @bullet

@itemize @bullet

@item RTL Files

@item RTL Files

* Customising::

* Customising::

* Running And Debugging Software::

* Running And Debugging Software::

@end menu

@end menu

@node ML501 Overview

@node ML501 Overview

The Xilinx ML501 board contains a Virtex LX50 part, varied memories and peripherals. See Xilinx's site for specific details:

The Xilinx ML501 board contains a Virtex LX50 part, varied memories and peripherals. See Xilinx's site for specific details:

http://www.xilinx.com/products/devkits/HW-V5-ML501-UNI-G.htm

http://www.xilinx.com/products/devkits/HW-V5-ML501-UNI-G.htm

The project is configured to generate either a @code{.bit} file for direct programming via JTAG, or a @code{.mcs} file with inbuilt bootloader software for the processor, meaning the board can be powered up and an application like ORPmon loaded without having to reprogram it from iMPACT between power cycles.

The project is configured to generate either a @code{.bit} file for direct programming via JTAG, or a @code{.mcs} file with inbuilt bootloader software for the processor, meaning the board can be powered up and an application like ORPmon loaded without having to reprogram it from iMPACT between power cycles.

This guide is far from complete, but provides the basics on running simulations, and building the design.

This guide is far from complete, but provides the basics on running simulations, and building the design.

@node ML501 Structure

@node ML501 Structure

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}.

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}.

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.

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.

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.

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.

Backend files, mainly binary NGC files for mapping, are found in the board's @code{backend/bin} path.

Backend files, mainly binary NGC files for mapping, are found in the board's @code{backend/bin} path.

@node ML501 XILINX_PATH

@node ML501 XILINX_PATH

Be sure to set the environment variable @code{XILINX_PATH} to the path of the ISE path on the host machine. This can be done with something like @kbd{export XILINX_PATH=/software/xilinx_11.1/ISE} and additionally a symbolic link to the Verilog simulation library sources will be required - see the simulation section on this. Note that it helps to add the @code{XILINX_PATH} variable to the user's @code{.bashrc} script or similar to save setting it each time a new shell is opened.

Be sure to set the environment variable @code{XILINX_PATH} to the path of the ISE path on the host machine. This can be done with something like @kbd{export XILINX_PATH=/software/xilinx_11.1/ISE} and additionally a symbolic link to the Verilog simulation library sources will be required - see the simulation section on this. Note that it helps to add the @code{XILINX_PATH} variable to the user's @code{.bashrc} script or similar to save setting it each time a new shell is opened.

If the @code{XILINX_PATH} variable is not set correctly, the makefiles will not run.

If the @code{XILINX_PATH} variable is not set correctly, the makefiles will not run.

@node ML501 Tools

@node ML501 Tools

@menu

@menu

* Host Tools::

* Host Tools::

* Target System Tools::

* Target System Tools::

* EDA Tools::

* EDA Tools::

* Debug Tools::

* Debug Tools::

@end menu

@end menu

@node ML501 Host Tools

@node ML501 Host Tools

@cindex host tools required ML501

@cindex host tools required ML501

Standard development suite of tools: gcc, make, etc.

Standard development suite of tools: gcc, make, etc.

@node ML501 Target System Tools

@node ML501 Target System Tools

@cindex target system tools required ML501

@cindex target system tools required ML501

OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.

OpenRISC GNU toolchain. For installation, see OpenRISC GNU toolchain page on OpenCores.org.

@node ML501 EDA Tools

@node ML501 EDA Tools

@cindex EDA tools required ML501

@cindex EDA tools required ML501

RTL, gatelevel simulation: Mentor Graphics' Modelsim

RTL, gatelevel simulation: Mentor Graphics' Modelsim

Synthesis: XST (from Xilinx ISE)

Synthesis: XST (from Xilinx ISE)

Backend: ngdbuild/map/par/bitgen/promgen, etc. (from Xilinx ISE)

Backend: ngdbuild/map/par/bitgen/promgen, etc. (from Xilinx ISE)

This has been tested with Xilinx ISE 11.1 under Ubuntu Linux.

This has been tested with Xilinx ISE 11.1 under Ubuntu Linux.

@node ML501 Debug Tools

@node ML501 Debug Tools

@cindex Debug tools required ML501

@cindex Debug tools required ML501

or_debug_proxy, ORPmon

or_debug_proxy, ORPmon

@node ML501 Simulating

@node ML501 Simulating

@cindex simulating ML501

@cindex simulating ML501

Ensure the @code{XILINX_PATH} environment variable is set correcetly. @xref{ML501 XILINX_PATH} for information.

Ensure the @code{XILINX_PATH} environment variable is set correcetly. @xref{ML501 XILINX_PATH} for information.

Note that if this path is not set, simulations will not compile.

Note that if this path is not set, simulations will not compile.

To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.

To run the default set of regression tests for the build, run the following command in the board's @code{sw/run} path.

@example

@example

@kbd{make rtl-tests}

@kbd{make rtl-tests}

@end table

@end table

@node ML501 Synthesis

@node ML501 Synthesis

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.

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.

@example

@example

@kbd{make all}

@kbd{make all}

This will create an NGC file in @code{syn/xst/run} named @code{orpsoc.ngc}.

This will create an NGC file in @code{syn/xst/run} named @code{orpsoc.ngc}.

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.

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.

@node ML501 Synthesis Options

@node ML501 Synthesis Options

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}.

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}.

@example

@example

@kbd{make print-config}

@kbd{make print-config}

@end example

@end example

@node ML501 Synthesis Warnings

@node ML501 Synthesis Warnings

The following is a list of some considerations before synthesis.

The following is a list of some considerations before synthesis.

@itemize @bullet

@itemize @bullet

@item bootrom.v

@item bootrom.v

@end itemize

@end itemize

@node ML501 Synthesised Netlist

@node ML501 Synthesised Netlist

To create a Verilog HDL netlist of the post-synthesis design, run the following in the board's @code{syn/xst/run} path.

To create a Verilog HDL netlist of the post-synthesis design, run the following in the board's @code{syn/xst/run} path.

@example

@example

@kbd{make orpsoc.v}

@kbd{make orpsoc.v}

@end example

@end example

@node ML501 Place and Route

@node ML501 Place and Route

Place and route of the design can be run from the board's @code{backend/par/run} path with the following command.

Place and route of the design can be run from the board's @code{backend/par/run} path with the following command.

@example

@example

@kbd{make orpsoc.ncd}

@kbd{make orpsoc.ncd}

@end example

@end example

@node ML501 Timing Report

@node ML501 Timing Report

The @code{trce} tool can be used to generate a timing report of the post-place and route design.

The @code{trce} tool can be used to generate a timing report of the post-place and route design.

@example

@example

@kbd{make timingreport}

@kbd{make timingreport}

@end example

@end example

@node ML501 Back-annotated Netlist

@node ML501 Back-annotated Netlist

A post-PAR back-annotated netlist can be generated with the following command.

A post-PAR back-annotated netlist can be generated with the following command.

@example

@example

@kbd{make netlist}

@kbd{make netlist}

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.

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.

@node ML501 Place and route options

@node ML501 Place and route options

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.

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.

@example

@example

@kbd{make print-config}

@kbd{make print-config}

@end example

@end example

@node ML501 Constraints

@node ML501 Constraints

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.

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.

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.

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.

@node ML501 Programming File Generation

@node ML501 Programming File Generation

Programming file generation is run from the board's @code{backend/par/run} path with the following command.

Programming file generation is run from the board's @code{backend/par/run} path with the following command.

@example

@example

@kbd{make orpsoc.bit}

@kbd{make orpsoc.bit}

@end example

@end example

This file can then be loaded into the Xilinx iMPACT program and programmed onto the Virtex 5 part on the ML501.

This file can then be loaded into the Xilinx iMPACT program and programmed onto the Virtex 5 part on the ML501.

@node ML501 SPI programming file

@node ML501 SPI programming file

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.

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.

@example

@example

@kbd{make orpsoc.mcs}

@kbd{make orpsoc.mcs}

@end example

@end example

@node ML501 SPI programming file with software

@node ML501 SPI programming file with software

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.

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.

@example

@example

@kbd{make orpsoc.mcs BOOTLOADER_BIN=/path/to/bootloader-binary-file.bin}

@kbd{make orpsoc.mcs BOOTLOADER_BIN=/path/to/bootloader-binary-file.bin}

This @code{orpmon-sizeword.bin} file should then be passed via the BOOTLOADER_BIN option when creating the @code{.mcs} file to embed it.

This @code{orpmon-sizeword.bin} file should then be passed via the BOOTLOADER_BIN option when creating the @code{.mcs} file to embed it.

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.

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.

@node ML501 SPI flash programming

@node ML501 SPI flash programming

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.

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.

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.

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.

Booting from the SPI flash to ORPmon prompt is about 3 to 4 seconds.

Booting from the SPI flash to ORPmon prompt is about 3 to 4 seconds.

@node ML501 Customising

@node ML501 Customising

The large amount of peripherals on the ML501 means that things will want to be added or removed to suit the design.

The large amount of peripherals on the ML501 means that things will want to be added or removed to suit the design.

The following sections have information on how to configure the design.

The following sections have information on how to configure the design.

@node ML501 Customising Enabling Existing Modules

@node ML501 Customising Enabling Existing Modules

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.

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.

These @code{`defines} will correspond to defines in the board's top level RTL file @code{boardpath/rtl/verilog/orpsoc_top/orpsoc_top.v}.

These @code{`defines} will correspond to defines in the board's top level RTL file @code{boardpath/rtl/verilog/orpsoc_top/orpsoc_top.v}.

@end itemize

@end itemize

The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.

The rest are optional, depending on what is defined in the board's @code{rtl/verilog/include/orpsoc-defines.v} file.

@node ML501 Customising Adding Modules

@node ML501 Customising Adding Modules

There are a number of steps to take when adding a new module to the design.

There are a number of steps to take when adding a new module to the design.

@itemize @bullet

@itemize @bullet

@item RTL Files

@item RTL Files

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}.

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}.

@end itemize

@end itemize

@node ML501 Running And Debugging Software

@node ML501 Running And Debugging Software

@node ML501 Debug Interface

@node ML501 Debug Interface

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.

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.

From the USB debugger, a fly lead must take the following signals to the following pins on header J4 on the ML501.

From the USB debugger, a fly lead must take the following signals to the following pins on header J4 on the ML501.

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.

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.

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.

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.

@node ML501 UART

@node ML501 UART

There are 2 ways of connecting to the UART in the design.

There are 2 ways of connecting to the UART in the design.

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.

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.

If both UART and debug interface are connected via the ORSoC USB debugger, this ultimately ends up witht he first 2 pins on the right column of J4 as RX/TX for the UART then the JTAG TDO, TDI, TMS and TCK in succession down the right column of J4.

If both UART and debug interface are connected via the ORSoC USB debugger, this ultimately ends up witht he first 2 pins on the right column of J4 as RX/TX for the UART then the JTAG TDO, TDI, TMS and TCK in succession down the right column of J4.

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.

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.

@c ****************************************************************************

@c ****************************************************************************

@c End bits

@c End bits

@c ****************************************************************************

@c ****************************************************************************