ORPSoCv3.mw

'''Most of the information on this page is now out of date. The latest details on ORPSoCv3 can be found on the main [[ORPSoC]] page. This page will get a clean up at some point.'''

= Introduction =

ORPSoC is the '''O'''penRISC '''R'''eference '''P'''latform '''S'''ystem-'''o'''n-'''C'''hip. It is intended to be a development and verification environment for IP cores and SoC designs. It is a collaboratively developed project. 

As a development platform it should provide a modular, easy to use environment to perform RTL development with push-button simulation and synthesis flows. A basic software build environment is also present to support OpenRISC development in simulation and on target. The project should be easy enough for users, both new and experienced, to get started with OpenRISC designs and develop quickly and collaborate easily.

=Rationale=
The following problems with current ORPSoC have been identified. The next version will try to rectify these issues

* Current version of ORPSoC require local copies of all cores which duplicates a lot of code and creates undocumented deviations from the upstream versions.

* Each board port contain files that could be centralized for easier maintenance.

* ORPSoC contain some basic C library functions that are also available in newlib. This also creates additional problems with incompatibility between software built with liborpsoc and newlib.

* The reference build, which is really a non-technology-specific board build, is treated as a special board build which complicates the hierarchy

* It's easy to get lost in the tree and there is no way to go from setup to simulation to implementation without moving around in the ORPSoC tree

* It's hard to know what is expected to provide when a new board port is added

* ORPSoC is hidden in the or1k tree, which makes it harder to find.

=Implementation=

See the documentation which comes with the project. [https://github.com/openrisc/orpsoc See the project's page on github.]

=Workflow=

==Quick start. Build a ready-made FPGA image==
From the project root
<code><br>make config_<board_name>
<br>make loadmodule</code>
The above code will select the configuration file for the selected board and save it in config/board.conf. It will then use the default synthesis and PAR tools to build a FPGA image

==Quick start. Simulation==
From the project root
<code><br>make config_<board_name>
<br>make rtl-tests</code>
The above code will select the configuration file for the selected board and save it in config/board.conf. It will then use the default simulation tool to run through all the RTL tests

==Adding a new core to a board build==
TBD

==Building a bare-metal program with ORPSoC drivers==
TBD
==Overriding a central core with a local version==
TBD
==Adding support for a new core in ORPSoC==
TBD
==Creating and updating patches==
Quilt is needed for patching of the cores. This describes how to add an ORPSoC-specific patch to a core
Go to <code><core root></code>
If there are any previous patches, make sure they are all applied before you start
<code><br>quilt push -a<br></code>
Decide a name for the patch and a number that follows the naming scheme. In ORPSoC this is <nnnn>-<name-of-patch>.diff, where nnnn is a four-digit number that follows the latest available patch. Create the patch with:
<code><br>quilt new <nnnn>-<name-of-patch>.diff (e.g. quilt new 0003-remove-defines.diff)<br></code>

The state of all files that are to be changed must be recorded by quilt before-hand so that the original state is known.
There are two ways to make changes to files

1. Use quilt edit <filename> This will make quilt automatically record the original state, and add the changes to the patch

2. Use quilt add <filename> before the file is added. This will make quilt record the original state, and any editor can now be used

When the editing is done, the patch can be reviewed with <code>quilt diff</code>

To actually create the patch, <code>quilt refresh</code>. A new patch can now be created with <code>quilt new <nnnn+1>-<name-of-next-patch>.diff</code>

==Porting an ORPSoCv2 board port to ORPSoCv3==
TBD

==Other==

* ORPSoC will be living in a separate repository. This will increase visibility and also make it easier to use other CPU implementations.

=Status=
==Currently supported==

===Simulation===
{| border="1" cellspacing="0" cellpadding="2"
! Tool
! Supported
|-
|Icarus    || In progress
|-
|Isim      || In progress
|-
|Modelsim  || No
|-
|Verilator || No
|}

===Synthesis===
{| border="1" cellspacing="0" cellpadding="2"
! Tool
! Supported
|-
|CoreGen  || Yes
|-
|Quartus  || No
|-
|Synplify || No
|-
|XST      || Yes
|}

===Place and route===
{| border="1" cellspacing="0" cellpadding="2"
! Tool
! Supported
|-
|ISE            || Yes
|-
|Quartus        || No
|-
|Actel Designer || No
|}

===Boards===
{| border="1" cellspacing="0" cellpadding="2"
! Board
! Simulation
! Synthesis
! Place and route
|-
|Digilent Atlys    || In progress || XST || ISE
|-
|generic  || Icarus      || No  || No
|-
|ORSoC ordb2a   || No          || No  || No
|}

==Work items==
===Software support===
* Set up software structure
* Move drivers to core roots
* Adapt simulation scripts from ORPSoCv2
* Merge board and sim tests and add #ifdefs where needed
===Test bench===
* Clean up define files
===Infrastructure===
* Add isim scripts to simulate Xilinx builds
* Adapt Altera and Actel build scripts from ORPSoCv2

=Open issues=
* Investigate if quilt or git be used for managing patches
* Rename loadmodule target to something more sensible. (programmingfile, fpgaimage..?)
* What can be done to ease additions or removals of cores in the top-level? IP-Xact is under consideration for generation of arbiters and top-level file
* boards is not a good name, as there can be several configurations for a physical board, or a design may be purely for verification purposes only and thus not intended to end up on a board. systems, designs or configurations have been proposed

=Discussion=

The original discussion can be found here [[ORPSoCv3InitialDiscussion]]