Ouessant

{{>toc}}

h1. Ouessant HowTos: Quickstart

This page is still a Work in Progress. Feel free to signal any mistake/lack in the description.

h2. First simulation

Here are the required steps to set a Ouessant based system up. For now, only Leon based platforms are possible

h3. Requirements

In order to use Ouessant, a few tools are needed.

The Ouessant code base and build architecture relies on GNU/Linux common building tools. We do not support Windows as a development platform. On a Debian/Ubuntu GNU/Linux distribution, you can get the required tools with the following command:

    @sudo apt-get install build-essential gcc make git @

Ouessant is a hardware design, thus CAD tools are needed according to your needs:

 * if you want to work in simulation, ModelSim is required. 

 * if you want to work with Xilinx FPGA, ISE toolsuite with a valid license for the board you are using is required. Please note that for Nexys4 and Atlys board, ISE WebPack is sufficient. You will also need tools to program the board (impact for Xilinx, Adept for Digilent boards). 

Furthermore, you will need the tools for the processor you are working with. For LEON based SoC, this means :

 * the compiler(s) for the SPARC processor (Linux or/and bare (​http://www.gaisler.com/index.php/downloads/compilers?task=view&id=161) according to your needs)

 * the GRMON debugger (​http://www.gaisler.com/index.php/downloads/debug-tools?task=view&id=190) 

We assume that all those tools are available, and correctly configured. Please refer to the corresponding manuals if you need more information. Boards specific instruction for supported devices are provided in [OuessantBoards|the Ouessant boards page].

h3. Getting started: setting up Ouessant environment

 # Download the folder and extract it with the help of an archive manager. You should put the “ouessant” folder where you can easily find it, for instance in your personal folder.

 # Now open a terminal and go to the project's root (ie. the folder you have just extracted). If you put it in your home directory, you can do this by typing :

   <pre>cd ~/ouessant</pre>

 # Set up the Ouessant environment:

   <pre>make env</pre>

   This will clone all necessary files from the git.

   *Warning* : make sure that you have all the required permissions on the ouessant folder.

We provide as much automation as possible to speed up the process of getting a Ouessant processor up and running. You can get all available commands and help by typing @make help@ in the command line. 

The code is divided in 5 main directories (other directories will be described later):

* @ocp@ contains the main VHDL code for Ouessant,

* @drivers@ has all the example codes in it, for Linux and baremetal

* @socs@ is the main directory for complete example System on Chips

* @scripts@ contains tools for automation

* @tools@ is created to store tools for Ouessant, mainly the assembler 

When you run the @make env@ command, you download all required tools (especially the Leon tools), generate the Ouessant configurations, and compile the tools. You are now ready to compile a complete SoC with associated software, and run your first test. 

h3. Simulate a first Leon design

 # Now go to the leon3-ouessant-mst-minimal folder by typing:

   <pre>cd socs/leon3-ouessant-mst-minimal/</pre>

   and compile the project by running

   <pre>make vsim</pre>

   By default, this will compile a Leon processor with required peripherals, and a Ouessant with a Spiral DFT (256 points) accelerator.

 # Finally, type

   <pre>make vsim-launch</pre>

   to launch the simulation. This will only launch ModelSim?, you can then launch the simulation. This example takes a simulated 30 ms to complete. 

h3. Going further: modifying the project

Congratulations, you launched your first Ouessant project!

You can now modify it if you want to suit your need.

If you open the @leon3mp.vhd@ file, you will see the top for this design. You can modify the Ouessant instantiation in it (called @ouessant0@). For example, you can change the @orac@ generic parameter to suit your need.

You can also modify the test source code by editing the @systest.c@ file. For the moment, no Ouessant compiler exists, and the microcode must be written directly in binary.

h3. Getting started: run Ouessant on a FPGA

For now, Ouessant is available on Atlys and Nexys4 boards, only with a Leon project.

# If you want to load your project on FPGA, you first have to connect it to your computer and to turn it on.

# Go into the SoC design corresponding to your FPGA~/ouessant/design/leon3-ouessant-digilent-atlys/ and make sure there is the right version of leon3mp.vhd and systest.c.

# Type the following command line "make ise-prog-fpga". This will compile all vhd files for your Digilent Atlys FPGA. Please note that you should have Adept already installed.

# Type the following command line "sparc-elf-gcc systest.c -o systest". This will cross compile your C file into a binary stream for your FPGA.

# Connect your FPGA to your computer using its IP address via Network Manager for instance.

# Type the following command line "grmon -eth XXX.XXX.X.XX" where XXX.XXX.X.XX is your FPGA's IP address. The LED at the right of your FPGA should be on.

# Open PuTTY by typing "putty" in your terminal. Please note that you should have PuTTY already installed.

# Fill the Host Name field with "/dev/ttyACM0" and the port name with "38 400".

# To make sure that you're correctly connected, click on the reset button on your FPGA. A short message should pop on the PuTTY terminal.

# Now you can load your program by typing the following command line in the GRMON terminal load systest.exe.

# Finally, you can run your program simply by typing "run" in the GRMON terminal.

# When you're done, you can exit the GRMON terminal by typing "quit". 

Have fun !

h2. Testing

In Ouessant, we try to keep everything functional from version to version. This is done through automated testing.

Automated testing is still under construction, and most modules are not yet tested. However, the architecture is available, and it is strongly recommended to provide tests if you want to add a module.

Which simulator?

Several simulation tools can be used in Ouessant. We currently support ModelSim, Xilins ISim, and GHDL for automated tests. GHDL will shortly be usable for local tests. Depending on the tools available for you, here are some advantages and disadvantages for each simulator.

 * ModelSim is efficient and interactive. It can easily be used and adapted for the project, allows simulation break and restart, and performs fast simulation. However, it is very expensive, and not available everywhere.

 * ISim is available for free with ISE WebPack. However, its performance are not good, and simulation time can be very high. Support is provided mainly for unit test, and for debug, but it should not be used for batch tests.

 * GHDL is efficient, open source, and easy to use. It performs better than ModelSim (faster). However, it is not interactive, and can not be scripted. It is our prefered choice for batch tests. 

h3. Test architecture overview

The automated test architecture is build so that it can be used either with ISim (Xilinx integrated simulator) or ModelSim. To add a test, two different parts must be added.

# Create your testbench in @$(OUESSANT)/ocp/testbench@. This must respect a few criterions:

  *  it must have a generic @debug_level@ of type @severity_level@.

  *  it can have any generic you want according to the module you are testing. These generics will then be configurable and different configurations will be tested.

  *  it should be automated, with an automated checker. Errors should be detected with an assert, with severity @debug_level@.

  *  you can use and improve the tb_global_pkg package, which provides some useful procedure to display data and generate random inputs. 

# Once the testbench is created, create your test configuration(s) in @$OUESSANT/tests/<test_name>@. This test configuration is used to provide information on the test unit to the automated test architecture. More specifically, it gives a list of involved files, configurations to be applied, and the scripts which can be used for interactive or batch testing. For now, you can use an existing test configuration as a basis. In the future, a script will be provided which will create these automatically.

  There are some little points to take into account when writing tests:

  *    the test (ie. the directory) must have the same name than the entity of the top testbench it is linked to.

  *    the list of VHDL (resp. Verilog) files is given in vhdlfiles (resp. vlogfiles). Please be careful: there should be no trailing blank characters at the end of line, or ISim compilation won't be performed correctly.

  *    a short human-readable description of the test is provided in short_description, and a detailed one in long_description.

  *    there are 4 TCL scripts, 2 for ISim and two for ModelSim. The "interactive" script is used when the test is launched in an interactive way (meaning with GUI). The other scripts are used when automated tests are used. You should not need to modify these scripts except if you want some specific features. They are placeholders, then calling generic scripts. They are only provided for very specific cases.

  *    the configs directory contains one INI file per required configuration. A configuration gives the values for the generic parameters of the testbench. This is done using a @generic_name=value@ list, one per line, in a [generics] section. It will then be used either for compiling with ISim, or to launch the simulations with ModelSim?. debug_level should not be handled in this configuration. 

# You can now run your test. Run: 

<pre>make help_tests</pre>

to get a list of tests related command. 

h3. Using GHDL to perform non-regression tests

In order to perform non-regression test, GHDL can be used with the automated test architecture. Please note that it is not fully integrated in the test architecture, and that it currently heavily relies on bash scripts and on the user, instead of Makefile automation.

In order to use GHDL, you need the latest not released GHDL version (see ​http://sourceforge.net/projects/ghdl-updates/ for more information). A script is provided in Ouessant to perform a local only install, which will then be used in the project. This is necessary because the latest release does not support top level generic value modification from the command line.

Installing GHDL

To install GHDL in the Ouessant project, you first need to install llvm, clang, libz and libedit. In a Debian/Ubuntu distribution, run :

<pre>sudo apt-get install gnat-5 llvm-dev clang libedit-dev libz-dev mercurial</pre>

Once this is done, you can run the install script:

    @$OUESSANT/scripts/install_ghdl.sh <path_to_ouessant>@

The script will install a local version in $OUESSANT/tools/ghdl-local. Once it successfully finishes, you can run

    @make tests_ghdl@

to run the complete set of tests, or

    @make <unit_test>_batch_ghdl@

to run only one. GHDL does not allow interactive launch for now. For now, no VCD file is created, even if it is on the TODO list of the project (but not of high priority!).

Current limitations of the test architecture

There are some limitations which will be addressed later:

 * a test can only be described to succeed. For now, you cannot create a failing configuration. This will be addressed later.