Subversion Repositories openrisc

\input texinfo   @c -*-texinfo-*-

\input texinfo   @c -*-texinfo-*-

@c %**start of header

@c %**start of header

@setfilename orpsoc.info

@setfilename orpsoc.info

@settitle ORPSoC manual 0.1

@settitle ORPSoC manual 0.1

@include config.texi

@include config.texi

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

Copyright @copyright{} 2010 OpenCores

Copyright @copyright{} 2010 OpenCores

@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

Invariant Sections, with no Front-Cover Texts, and with no Back-Cover

Invariant Sections, with no Front-Cover Texts, and with no Back-Cover

Texts.  A copy of the license is included in the section entitled ``GNU

Texts.  A copy of the license is included in the section entitled ``GNU

Free Documentation License''.

Free Documentation License''.

@end quotation

@end quotation

@end copying

@end copying

@setchapternewpage on

@setchapternewpage on

@settitle @value{ORPSOC} User Guide

@settitle @value{ORPSOC} User Guide

@syncodeindex fn cp

@syncodeindex fn cp

@syncodeindex vr cp

@syncodeindex vr cp

@titlepage

@titlepage

@title @value{ORPSOC} User Guide

@title @value{ORPSOC} User Guide

@c @subtitle subtitle-if-any

@c @subtitle subtitle-if-any

@c @subtitle second-subtitle

@c @subtitle second-subtitle

@author Julius Baxter

@author Julius Baxter

@author OpenCores

@author OpenCores

@author Issue 1 for @value{ORPSOC}

@author Issue 1 for @value{ORPSOC}

@c  The following two commands

@c  The following two commands

@c  start the copyright page.

@c  start the copyright page.

@page

@page

@vskip 0pt plus 1filll

@vskip 0pt plus 1filll

@insertcopying

@insertcopying

Published by OpenCores

Published by OpenCores

@end titlepage

@end titlepage

@c So the toc is printed at the start.

@c So the toc is printed at the start.

@contents

@contents

@ifnottex

@ifnottex

@node Top

@node Top

@top Scope of this Document

@top Scope of this Document

This document is the user guide for @value{ORPSOC}, the OpenRISC Reference Platform System on Chip project.

This document is the user guide for @value{ORPSOC}, the OpenRISC Reference Platform System on Chip project.

@end ifnottex

@end ifnottex

@menu

@menu

* Introduction::

* Introduction::

* Project Organisation::

* Project Organisation::

* Getting Started::

* Getting Started::

* Reference Design::

* Reference Design::

* Board Designs::

* Board Designs::

* ORDB1A3PE1500::

* ORDB1A3PE1500::

* 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

@chapter Introduction

@chapter Introduction

@cindex introduction to this @value{ORPSOC}

@cindex introduction to this @value{ORPSOC}

@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, and systems intended to be synthesized and run on physical hardware (boards.) The simple refernce system contains just enough to test the processor's functionality, whereas the board targeted builds will include many additional peripherals.

@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, and systems intended to be synthesized and run on physical hardware (boards.) The simple refernce system contains just enough to test the processor's functionality, whereas the board targeted builds will include many additional peripherals.

The reference design will contain a minimal set of resources to create an OpenRISC-based SoC. It is expected the board builds will contain their own set of peripheral modules and software, and still draw upon the resources available in the reference implementation. It is hoped that, with this structure, the project can serve dual roles; to be a development platform for OpenRISC family processors, and to provide a platform for development of complex OpenRISC-based systems on chip.

The reference design will contain a minimal set of resources to create an OpenRISC-based SoC. It is expected the board builds will contain their own set of peripheral modules and software, and still draw upon the resources available in the reference implementation. It is hoped that, with this structure, the project can serve dual roles; to be a development platform for OpenRISC family processors, and to provide a platform for development of complex OpenRISC-based systems on chip.

This document, the user guide, focuses on getting the various designs in @value{ORPSOC} up and running. For matters relating to development of a board port, see the development guide included with this documentation.

This document, the user guide, focuses on getting the various designs in @value{ORPSOC} up and running. For matters relating to development of a board port, see the development guide included with this documentation.

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

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

@c Project Organisation

@c Project Organisation

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

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

@node Project Organisation

@node Project Organisation

@chapter Project Organisation

@chapter Project Organisation

@cindex organisation of @value{ORPSOC} project

@cindex organisation of @value{ORPSOC} project

@menu

@menu

* Overview::

* Overview::

* Software::

* Software::

* RTL::

* RTL::

* Testbenches::

* Testbenches::

* Reference And Board Designs::

* Reference And Board Designs::

@end menu

@end menu

@node Organisation Overview

@node Organisation Overview

@section Organisation Overview

@section Organisation Overview

The @value{ORPSOC} project is intended for dual uses. One is to act as a development platform for OpenRISC processors, as well as development of complex OpenRISC-based SoCs. Organising a single project to satisfy these requirements can lead to some confusion. This section is intended to make the organisation of the project clear.

The @value{ORPSOC} project is intended for dual uses. One is to act as a development platform for OpenRISC processors, as well as development of complex OpenRISC-based SoCs. Organising a single project to satisfy these requirements can lead to some confusion. This section is intended to make the organisation of the project clear.

In essense, the reference implementation based in the root of the project contains enough to get a simple OpenRISC-based SoC together, the board builds are intended to implement fully-featured systems. The project is organised in such a way that the board builds can use both the reference implementation's RTL and software, as well as its own set of RTL and software. The reference implementation, however, cannot use any board's modules, software or scripts.

In essense, the reference implementation based in the root of the project contains enough to get a simple OpenRISC-based SoC together, the board builds are intended to implement fully-featured systems. The project is organised in such a way that the board builds can use both the reference implementation's RTL and software, as well as its own set of RTL and software. The reference implementation, however, cannot use any board's modules, software or scripts.

The following sections outline the organisation of the software, RTL, and board designs.

The following sections outline the organisation of the software, RTL, and board designs.

@node Software Organisation

@node Software Organisation

@section Software

@section Software

The @code{sw} path contains primarily target software (code intended for cross-compilation and execution on an OpenRISC processor) and a few custom tools for manipulation of binary software images.

The @code{sw} path contains primarily target software (code intended for cross-compilation and execution on an OpenRISC processor) and a few custom tools for manipulation of binary software images.

Driver software, implementing access functions for hardware modules, are found under @code{sw/drivers}. There is the concept of a CPU library, providing CPU-specific functions, which can be changed to support different versions of OpenRISC processors. There is also 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}.

Driver software, implementing access functions for hardware modules, are found under @code{sw/drivers}. There is the concept of a CPU library, providing CPU-specific functions, which can be changed to support different versions of OpenRISC processors. There is also 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}.

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.

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.

Under each test directory are two directories, @code{board} and @code{sim}, containing the test software targeted at each. Code for simulation will produce less printfs and perhaps not run as long as tests intended to run at full speed on target.

Under each test directory are two directories, @code{board} and @code{sim}, containing the test software targeted at each. Code for simulation will produce less printfs and perhaps not run as long as tests intended to run at full speed on target.

There are for naming software tests, 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}.

There are for naming software tests, 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

Beyond that, there are some rules for the naming in modules. 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 (...}.

Beyond that, there are some rules for the naming in modules. 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 (...}.

@node Testbench Organisation

@node Testbench Organisation

@section Testbench

@section Testbench

For each design in @value{ORPSOC} there will be a testbench instantiating the top level, and any peripherals (at least, as many as there are models for.)

For each design in @value{ORPSOC} there will be a testbench instantiating the top level, and any peripherals (at least, as many as there are models for.)

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. However, this is not intended as a platform for peripheral development (although, it very well could be) the board designs are not expected to have thorough peripheral tests. They are expected to have just enough to prove that basic functionality.

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. However, this is not intended as a platform for peripheral development (although, it very well could be) the board designs are not expected to have thorough peripheral tests. They are expected to have just enough to prove that basic functionality.

@node Organisation of Reference And Board Designs

@node Organisation of Reference And Board Designs

@section Reference And Board Designs

@section Reference And Board Designs

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.

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.

Typically, a board-targeted design will wish to reuse common components (processor, debug interface, Wishbone arbiters, UART etc.) The project has been configured to allow a board build to use either modules available in the ``common'' RTL path (@code{rtl/verilog/}) as well as those in their ``local'' RTL path (something like @code{boards/vendor/boardname/rtl/verilog}). In the event that some particular modification to a module in the common RTL set is desired for a particular board build, that module can simply be copied into the board's ``local'' RTL path and the scripts will that version instead of the common one.

Typically, a board-targeted design will wish to reuse common components (processor, debug interface, Wishbone arbiters, UART etc.) The project has been configured to allow a board build to use either modules available in the ``common'' RTL path (@code{rtl/verilog/}) as well as those in their ``local'' RTL path (something like @code{boards/vendor/boardname/rtl/verilog}). In the event that some particular modification to a module in the common RTL set is desired for a particular board build, that module can simply be copied into the board's ``local'' RTL path and the scripts will that version instead of the common one.

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

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

@c Getting started

@c Getting started

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

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

@node Getting Started

@node Getting Started

@chapter Getting Started

@chapter Getting Started

@cindex source files for @value{ORPSOC}, downloading

@cindex source files for @value{ORPSOC}, downloading

@menu

@menu

* Supported Platforms::

* Supported Platforms::

* Obtaining Project Source::

* Obtaining Project Source::

* Required Tools::

* Required Tools::

@end menu

@end menu

@node Getting Started Supported Platforms

@node Getting Started Supported Platforms

@section Supported Platforms

@section Supported Platforms

@cindex platforms supported by the @value{ORPSOC} project

@cindex platforms supported by the @value{ORPSOC} project

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.

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.

Unless indicated otherwise, support for the project under Cygwin on Microsoft Windows platforms is not a given.

Unless indicated otherwise, support for the project under Cygwin on Microsoft Windows platforms is not a given.

@node Getting Started Obtaining Project Source

@node Getting Started Obtaining Project Source

@section Obtaining Project Source

@section Obtaining Project Source

@cindex getting a copy of the @value{ORPSOC} project

@cindex getting a copy of the @value{ORPSOC} project

The source for @value{ORPSOC} can be obtained from the OpenCores subversion (SVN) server.

The source for @value{ORPSOC} can be obtained from the OpenCores subversion (SVN) server.

@example

@example

@kbd{svn export http://opencores.org/ocsvn/openrisc/openrisc/trunk/orpsocv2}

@kbd{svn export http://opencores.org/ocsvn/openrisc/openrisc/trunk/orpsocv2}

@end example

@end example

@node Getting Started Required Tools

@node Getting Started Required Tools

@section Required Tools

@section Required Tools

@cindex tools and utilities required for @value{ORPSOC}

@cindex tools and utilities required for @value{ORPSOC}

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.

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.

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 grealty improved productivity.

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 grealty improved productivity.

The required tools can be divided into four groups.

The required tools can be divided into four groups.

@itemize @bullet

@itemize @bullet

@item

@item

Host system tools - things like gcc, make, texinfo.

Host system tools - things like gcc, make, texinfo.

@item

@item

Target system toolchain and software - the OpenRISC GNU toolchain, with gcc crosscompiler, support libraries, the GNU debugger (gdb), OpenRISC port of various OSes and RTOS, etc.

Target system toolchain and software - the OpenRISC GNU toolchain, with gcc crosscompiler, support libraries, the GNU debugger (gdb), OpenRISC port of various OSes and RTOS, etc.

@item

@item

Electronic design automation (EDA) tools - preprocessors, simulators, FPGA tool suites, etc.

Electronic design automation (EDA) tools - preprocessors, simulators, FPGA tool suites, etc.

@item

@item

Debug tools - tools providing control over the system on target

Debug tools - tools providing control over the system on target

@end itemize

@end itemize

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.

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.

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.

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.

Anyone implementing their own board port is encouraged to document, as best they can, any problematic tool installations and contribute them to this document.

Anyone implementing their own board port is encouraged to document, as best they can, any problematic tool installations and contribute them to this document.

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

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

@c Reference Design chapter

@c Reference Design chapter

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

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

@node Reference Design

@node Reference Design

@chapter Reference Design

@chapter Reference Design

@cindex reference design

@cindex reference design

@menu

@menu

* Overview::

* Overview::

* Structure::

* Structure::

* Tools::

* Tools::

* Simulation::

* Simulation::

* Synthesis::

* Synthesis::

@end menu

@end menu

@node Reference Design Overview

@node Reference Design Overview

@subsection Overview

@subsection 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. In this regard, 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. In this regard, 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 instaniated 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 instaniated 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 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.

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.

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

@subsection Structure

@subsection Structure

@menu

@menu

* Overview::

* Overview::

* RTL::

* RTL::

* Software::

* Software::

* Simulation::

* Simulation::

@end menu

@end menu

@node Reference Design Overview

@node Reference Design Overview

@subsubsection Overview

@subsubsection 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

@subsubsection RTL

@subsubsection 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

@subsubsection Software

@subsubsection 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

@subsubsection Simulation

@subsubsection 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

@subsection Tools

@subsection 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

@subsubsection Host Tools

@subsubsection 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

@subsubsection Target System Tools

@subsubsection 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

@subsubsection EDA Tools

@subsubsection 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

@subsubsection Debug Tools

@subsubsection 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

@subsection Simulation

@subsection Simulation

@menu

@menu

* RTL::

* RTL::

* Cycle Accurate::

* Cycle Accurate::

* Results::

* Results::

@end menu

@end menu

@node Reference Design RTL

@node Reference Design RTL

@subsubsection RTL

@subsubsection 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.

@subsubheading Running RTL Regression Test

@subsubheading Running RTL Regression Test

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.

@subsubheading Running An Individual Test

@subsubheading Running An Individual Test

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

@subsubheading Running A Set Of Specific Tests

@subsubheading Running A Set Of Specific 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

@subsubheading Options For RTL Tests

@subsubheading Options For 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

@item VCD

@item VCD

Set to '1' to enable @emph{value change dump} (VCD) creation in @code{sim/out/@emph{testname}.vcd}

Set to '1' to enable @emph{value change dump} (VCD) creation in @code{sim/out/@emph{testname}.vcd}

@item VCD_DELAY

@item VCD_DELAY

Delay VCD creation start time by this number of timesteps (used as a Verilog @code{#delay} in the testbench.)

Delay VCD creation start time by this number of timesteps (used as a Verilog @code{#delay} in the testbench.)

@item VCD_DELAY_INSNS

@item VCD_DELAY_INSNS

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

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

@item END_TIME

@item END_TIME

Force simulation end (@code{$finish}) at this time.

Force simulation end (@code{$finish}) at this time.

@item DISABLE_PROCESSOR_LOGS

@item DISABLE_PROCESSOR_LOGS

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.

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.

@item SIMULATOR

@item SIMULATOR

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.

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.

@end table

@end table

@node Reference Design Cycle Accurate

@node Reference Design Cycle Accurate

@subsubsection Cycle Accurate

@subsubsection Cycle Accurate

@cindex cycle accurate simulation of reference design

@cindex cycle accurate simulation of reference design

@subsubheading Running Cycle Accurate Regression Test

@subsubheading Running Cycle Accurate Regression Test

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.

@subsubheading Running An Individual Test

@subsubheading Running An Individual Test

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

@subsubheading Generating Cycle Accurate Simulator Executable

@subsubheading Generating Cycle Accurate Simulator Executable

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.

@subsubheading Generating Automatically Profiled Cycle Accurate Simulator Executable

@subsubheading Generating Automatically Profiled Cycle Accurate Simulator Executable

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

@subsubheading Cycle Accurate Model Executable Usage

@subsubheading Cycle Accurate Model Executable Usage

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}

@end example

@end example

A short list of options is given here.

A short list of options is given here.

@table @code

@table @code

@item -f @var{file}

@item -f @var{file}

@itemx --program @var{file}

@itemx --program @var{file}

@cindex @code{-f}

@cindex @code{-f}

@cindex @code{--program}

@cindex @code{--program}

Load software from OR32 ELF image @var{file}

Load software from OR32 ELF image @var{file}

If unspecified, model attempts to load VMEM file @code{sram.vmem}

If unspecified, model attempts to load VMEM file @code{sram.vmem}

@item -v

@item -v

@itemx --vcd

@itemx --vcd

@cindex @code{-v}

@cindex @code{-v}

@cindex @code{--vcd}

@cindex @code{--vcd}

Dump VCD file

Dump VCD file

@item -e @var{value}

@item -e @var{value}

@itemx --endtime @var{value}

@itemx --endtime @var{value}

@cindex @code{-e}

@cindex @code{-e}

@cindex @code{--endtime}

@cindex @code{--endtime}

End simulation after @var{value} simulated ns

End simulation after @var{value} simulated ns

@item -l @var{file}

@item -l @var{file}

@itemx --log @var{file}

@itemx --log @var{file}

@cindex @code{-l}

@cindex @code{-l}

@cindex @code{--log}

@cindex @code{--log}

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

@subsubsection Results

@subsubsection Results

@cindex output from simulation of reference design

@cindex output from simulation of reference design

The following files are generted 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 generted from the event driven simulation. For output options of the cycle accurate model, see the section on Cycle Accurate Model Executable Usage.

@subsubheading Processor Execution Trace

@subsubheading Processor Execution Trace

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

@subsubheading Processor SPR Access Log

@subsubheading Processor SPR Access 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}.

@subsubheading Processor Instruction Excecution Time Log

@subsubheading Processor Instruction Excecution Time 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}.

@subsubheading Processor Report Mechanism Log

@subsubheading Processor Report Mechanism 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.

@subsubheading Value Change Dump (VCD)

@subsubheading Value Change Dump (VCD)

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

@subsection Synthesis

@subsection 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 ****************************************************************************

@c ORDB1A3PE1500 board build chapter

@c ORDB1A3PE1500 board build chapter

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

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

@node ORDB1A3PE1500

@node ORDB1A3PE1500

@chapter ORDB1A3PE1500

@chapter ORDB1A3PE1500

@cindex ORDB1A3PE1500 board build information

@cindex ORDB1A3PE1500 board build information

@menu

@menu

* Overview::

* Overview::

* Structure::

* Structure::

* Tools::

* Tools::

* Simulating::

* Simulating::

* Synthesis and Backend::

* Synthesis and Backend::

* Programming File Generation::

* Programming File Generation::

* Customising::

* Customising::

@end menu

@end menu

@node ORDB1A3PE1500 Overview

@node ORDB1A3PE1500 Overview

@subsection Overview

@subsection 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.

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.

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.

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

@subsection Structure

@subsection 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

@subsection Tools

@subsection 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

@subsubsection Host Tools

@subsubsection 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

@subsubsection Target System Tools

@subsubsection 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

@subsubsection EDA Tools

@subsubsection 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 developed with Libero v8.6 for Linux.

This has been developed with Libero v8.6 for Linux.

@node ORDB1A3PE1500 Debug Tools

@node ORDB1A3PE1500 Debug Tools

@subsubsection Debug Tools

@subsubsection 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

@subsection Simulating

@subsection Simulating

@cindex simulating ORDB1A3PE1500

@cindex simulating ORDB1A3PE1500

@subsubheading Run RTL Regression Test

@subsubheading Run RTL Regression Test

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 example

@end example

The same set of options for RTL tests available in the reference design should available in this build. @xref{Running A Set Of Specific Reference Design RTL Tests}.

The same set of options for RTL tests available in the reference design should available in this build. @xref{Running A Set Of Specific Reference Design RTL Tests}.

Options specific to the ORDB1A3PE1500 build.

Options specific to the ORDB1A3PE1500 build.

@table @code

@table @code

@item PRELOAD_RAM

@item PRELOAD_RAM

Set to '1' to enable loading of the software image into RAM at the beginning of simulation.

Set to '1' to enable loading of the software image into RAM at the beginning of simulation.

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.

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.

@end table

@end table

@node ORDB1A3PE1500 Synthesis

@node ORDB1A3PE1500 Synthesis

@subsection Synthesis

@subsection 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}

@end example

@end example

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

@subsubsection Options

@subsubsection 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

@item RTL_TOP

@item RTL_TOP

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.

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.

@item FPGA_PART

@item FPGA_PART

Defaults to A3PE1500 but if targeting any other set it with this.

Defaults to A3PE1500 but if targeting any other set it with this.

@item FPGA_FAMILY

@item FPGA_FAMILY

Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.

Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.

@item FPGA_PACKAGE

@item FPGA_PACKAGE

Defaults to PQFP208 but if targeting any other set it with this.

Defaults to PQFP208 but if targeting any other set it with this.

@item FPGA_SPEED_GRADE

@item FPGA_SPEED_GRADE

Defaults to Std but if targeting any other set it with this.

Defaults to Std but if targeting any other set it with this.

@item FREQ

@item FREQ

Target frequency for synthesis.

Target frequency for synthesis.

@item MAXFAN

@item MAXFAN

Maximum net fanout.

Maximum net fanout.

@item MAXFAN_HARD

@item MAXFAN_HARD

Hard limit on maximum net fanout.

Hard limit on maximum net fanout.

@item GLOBALTHRESH

@item GLOBALTHRESH

Threshold of fanout before promoting signal to a global routing net.

Threshold of fanout before promoting signal to a global routing net.

@item RETIMING

@item RETIMING

Defaults to '1' (on) but set to '0' to disable.

Defaults to '1' (on) but set to '0' to disable.

@item RESOURCE_SHARING

@item RESOURCE_SHARING

Defaults to '1' (on) but set to '0' to disable.

Defaults to '1' (on) but set to '0' to disable.

@item DISABLE_IO_INSERTION

@item DISABLE_IO_INSERTION

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

@subsubsection Checks

@subsubsection Checks

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

If the bootROM module is being used to provide the processor with a progrm at startup, check that board software include file, in the board's @code{sw/board/include} path, is selecting the correct bootROM program.

If the bootROM module is being used to provide the processor with a progrm at startup, check that board software include file, in the board's @code{sw/board/include} path, is selecting the correct bootROM program.

Do a @kbd{make clean-all} from the synthesis run directory to be sure that the previous bootROM file is cleared away and regenerated when synthesis is run.

Do a @kbd{make clean-all} from the synthesis run directory to be sure that the previous bootROM file is cleared away and regenerated when synthesis is run.

@item Clean away old leftovers

@item Clean away old leftovers

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.

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.

@item Check Command Line Options

@item Check Command Line Options

If using any command line settings, they can be checked by passing them to the following make target: @kbd{make print-config}

If using any command line settings, they can be checked by passing them to the following make target: @kbd{make print-config}

@end itemize

@end itemize

@node ORDB1A3PE1500 Place and Route

@node ORDB1A3PE1500 Place and Route

@subsection Place and Route

@subsection 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}

@end example

@end example

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 programming file generation are done here. This is mainly a licensing thing (free liceneses for Libero under Linux @emph{do not} allow programming file generation - they do, however, under Windows.)

All steps, up to programming file generation are done here. This is mainly a licensing thing (free liceneses for Libero under Linux @emph{do not} allow programming file generation - they do, however, under Windows.)

@node ORDB1A3PE1500 Place and route options

@node ORDB1A3PE1500 Place and route options

@subsubsection Options

@subsubsection Options

Most of the design's parameters are deteremined by processing the @code{orpsoc-defines.v} file and determining, for example, the frequency of the clocks entering the design.

Most of the design's parameters are deteremined by processing the @code{orpsoc-defines.v} file and determining, 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}.

@table @code

@table @code

@item FPGA_PART

@item FPGA_PART

Defaults to A3PE1500 but if targeting any other set it with this.

Defaults to A3PE1500 but if targeting any other set it with this.

@item FPGA_FAMILY

@item FPGA_FAMILY

Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.

Defaults to the A3PE1500's @emph{ProASIC3E} but if targeting any other set it with this.

@item FPGA_PACKAGE

@item FPGA_PACKAGE

Defaults to ``208 PQFP'' but if targeting any other set it with this.

Defaults to ``208 PQFP'' but if targeting any other set it with this.

@item FPGA_SPEED_GRADE

@item FPGA_SPEED_GRADE

Defaults to Std but if targeting any other set it with this.

Defaults to Std but if targeting any other set it with this.

@item FPGA_VOLTAGE

@item FPGA_VOLTAGE

Defaults to 1.5 but if targeting any other set it with this.

Defaults to 1.5 but if targeting any other set it with this.

@item FPGA_TEMP_RANGE

@item FPGA_TEMP_RANGE

Defaults to COM but if targeting any other set it with this.

Defaults to COM but if targeting any other set it with this.

@item FPGA_VOLT_RANGE

@item FPGA_VOLT_RANGE

Defaults to COM but if targeting any other set it with this.

Defaults to COM but if targeting any other set it with this.

@item PLACE_INCREMENTAL

@item PLACE_INCREMENTAL

Defaults to off.

Defaults to off.

@item ROUTE_INCREMENTAL

@item ROUTE_INCREMENTAL

Defaults to off.

Defaults to off.

@item PLACER_HIGH_EFFORT

@item PLACER_HIGH_EFFORT

Defaults to off.

Defaults to off.

@item BOARD_CONFIG

@item BOARD_CONFIG

Defaults to @code{orsoccpuexpio.mkpinassigns}

Defaults to @code{orsoccpuexpio.mkpinassigns}

@end table

@end table

@node ORDB1A3PE1500 Constraints

@node ORDB1A3PE1500 Constraints

@subsubsection Constraints

@subsubsection 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.

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

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

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.

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.

@example

@example

@kbd{make pdc-file sdc-file}

@kbd{make pdc-file sdc-file}

@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

@subsection Programming File Generation

@subsection 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

@subsection Customising

@subsection 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

@subsubsection Enabling Existing RTL Modules

@subsubsection Enabling Existing RTL 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 deafult.

There are only a few modules included by deafult.

@itemize @bullet

@itemize @bullet

@item Processor - @emph{or1200}

@item Processor - @emph{or1200}

@item Clock and reset generation - @emph{clkgen}

@item Clock and reset generation - @emph{clkgen}

@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}

@item Bus arbiters - @emph{arbiter_ibus}, @emph{arbiter_dbus}, @emph{arbiter_bytebus}

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

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 (uncommont in the @code{orspco-defines.v} file.)

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

@node ORDB1A3PE1500 Customising Adding Modules

@node ORDB1A3PE1500 Customising Adding Modules

@subsubsection Adding RTL Modules

@subsubsection Adding RTL 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

Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.

Create a directory under the board's @code{rtl/verilog} directory, and name it the same as the top level of the module.

Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.

Ensure the module's top level file and actual name of the module when it will be instantiated are @emph{all the same}.

Place any include files into the board's @code{rtl/verilog/include} path.

Place any include files into the board's @code{rtl/verilog/include} path.

@item Instantiate in ORPSoC Top Level File

@item Instantiate in ORPSoC Top Level File

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.

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.

@itemize @bullet

@itemize @bullet

@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.

@item Create appropriate @emph{`define} in @code{orpsoc-defines.v} and surround module instantiation with it.

@item Add required I/Os (surrounded by appropriate @emph{`ifdef })

@item Add required I/Os (surrounded by appropriate @emph{`ifdef })

@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.

@item Attach to appropriate bus arbiter, declaring any signals required. Be sure to tie them off if modules is not included.

@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.

@item Update appropriate bus arbiter (in board's @code{rtl/verilog/arbiters} path) adding (uncommenting) additional ports as needed.

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

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

@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.

@item Attach appropriate clocks and resets, modify the board's @code{rtl/verilog/clkgen/clkgen.v} file generating appropriate clocks if required.

@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.

@item Attach any interrupts to the processor's PIC vector in, assigned as the last thing in the file.

@end itemize

@end itemize

@item Update ORPSoC Testbench

@item Update ORPSoC Testbench

Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)

Update the board's @code{bench/verilog/orpsoc_testbench.v} file with appropriate ports (surrounded by appropriate @emph{`ifdef}.)

Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.

Add any desired models to help test the module to the board's @code{bench/verilog} path and instantiate it correctly in the testbench.

@item Add Software Drivers and Tests

@item Add Software Drivers and Tests

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

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

@item Update Backend Scripts

@item Update Backend Scripts

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} wll need to be updated.

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} wll need to be updated.

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.

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.

Continuing the format already there should be easy enough. Rememeber that the @code{orspoc-defines.v} file is parsed and it's possible to tell if the module is included by testing if the variable is defined.

Continuing the format already there should be easy enough. Rememeber that the @code{orspoc-defines.v} file is parsed and it's possible to tell if the module is included by testing if the variable is defined.

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.

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.

@example

@example

@kbd{   $(Q)if [ ! -z $$FOO1 ]; then \

@kbd{   $(Q)if [ ! -z $$FOO1 ]; then \

        echo "set_io foo1_srx_i " $(FOO_SRX_BUS_SETTINGS) " \

        echo "set_io foo1_srx_i " $(FOO_SRX_BUS_SETTINGS) " \

        echo "set_io foo1_tx_o\\[0\\] " $(FOO_TX_BUS_SETTINGS) " \

        echo "set_io foo1_tx_o\\[0\\] " $(FOO_TX_BUS_SETTINGS) " \

        echo "set_io foo1_tx_o\\[1\\] " $(FOO_TX_BUS_SETTINGS) "  \

        echo "set_io foo1_tx_o\\[1\\] " $(FOO_TX_BUS_SETTINGS) "  \

        echo "set_io foo1_tx_o\\[2\\] " $(FOO_TX_BUS_SETTINGS) "  \

        echo "set_io foo1_tx_o\\[2\\] " $(FOO_TX_BUS_SETTINGS) "  \

        echo "set_io foo1_tx_o\\[3\\] " $(FOO_TX_BUS_SETTINGS) "  \

        echo "set_io foo1_tx_o\\[3\\] " $(FOO_TX_BUS_SETTINGS) "  \

        fi

        fi

       }

       }

@end example

@end example

@emph{(ensure there is no whitespace after the trailing backslashes.)}

@emph{(ensure there is no whitespace after the trailing backslashes.)}

It's a little hard to follow, but it's essentially one @code{set_io} line for each I/O line.

It's a little hard to follow, but it's essentially one @code{set_io} line for each I/O line.

First the line checks if the module's define was exported (which happens automatically if it's defined in @code{orpsoc-defines.v}.

First the line checks if the module's define was exported (which happens automatically if it's defined in @code{orpsoc-defines.v}.

Note that what is defined can be checked by running @kbd{make print-defines} in the board's @code{backend/par/run} path.

Note that what is defined can be checked by running @kbd{make print-defines} in the board's @code{backend/par/run} path.

The values of the bus settings variables depend on the desired I/O standards and other examples in the Makefile can be referenced.

The values of the bus settings variables depend on the desired I/O standards and other examples in the Makefile can be referenced.

The pin numbers need to be set in the @code{.mkpinassigns} which is included intot he Makefile (according to the @code{BOARD_CONFIG} variable set when running the @code{make} command.)

The pin numbers need to be set in the @code{.mkpinassigns} which is included intot he Makefile (according to the @code{BOARD_CONFIG} variable set when running the @code{make} command.)

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.

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.

The physical constraints file can be generated manually with the @kbd{make pdc-file} command.

The physical constraints file can be generated manually with the @kbd{make pdc-file} command.

@end itemize

@end itemize

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

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

@c End bits

@c End bits

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

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

@node  GNU Free Documentation License

@node  GNU Free Documentation License

@chapter GNU Free Documentation License

@chapter GNU Free Documentation License

@cindex license for @value{ORPSOC}

@cindex license for @value{ORPSOC}

@include fdl-1.2.texi

@include fdl-1.2.texi

@node Index

@node Index

@unnumbered Index

@unnumbered Index

@printindex cp

@printindex cp

@bye

@bye