OuessantQuickStart » Historique » Version 4

Pierre-Henri HORREIN, 10/11/2015 00:43

1 4 Pierre-Henri HORREIN
2 4 Pierre-Henri HORREIN
{{>toc}}
3 4 Pierre-Henri HORREIN
4 1 Pierre-Henri HORREIN
h1. Ouessant HowTos: Quickstart
5 1 Pierre-Henri HORREIN
 
6 1 Pierre-Henri HORREIN
This page is still a Work in Progress, since it will evolve as long as the development process has not been formalized
7 1 Pierre-Henri HORREIN
8 1 Pierre-Henri HORREIN
h2. Introduction
9 1 Pierre-Henri HORREIN
10 1 Pierre-Henri HORREIN
h2. I want my Ouessant now!
11 1 Pierre-Henri HORREIN
12 1 Pierre-Henri HORREIN
Here are the required steps to set a Ouessant based system up. For now, only Leon based platforms are possible
13 1 Pierre-Henri HORREIN
14 1 Pierre-Henri HORREIN
h3. Requirements
15 1 Pierre-Henri HORREIN
16 1 Pierre-Henri HORREIN
In order to use Ouessant, a few tools are needed.
17 1 Pierre-Henri HORREIN
18 1 Pierre-Henri HORREIN
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:
19 1 Pierre-Henri HORREIN
20 2 Pierre-Henri HORREIN
    @sudo apt-get install build-essential gcc make git @
21 1 Pierre-Henri HORREIN
22 1 Pierre-Henri HORREIN
Ouessant is a hardware design, thus CAD tools are needed according to your needs:
23 1 Pierre-Henri HORREIN
24 2 Pierre-Henri HORREIN
 * if you want to work in simulation, ModelSim? is required. ISim automation is currently under way but (really) not functional
25 2 Pierre-Henri HORREIN
 * 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). 
26 1 Pierre-Henri HORREIN
27 1 Pierre-Henri HORREIN
Furthermore, you will need the tools for the processor you are working with. For LEON based SoC, this means :
28 1 Pierre-Henri HORREIN
29 2 Pierre-Henri HORREIN
 * 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)
30 2 Pierre-Henri HORREIN
 * the GRMON debugger (​http://www.gaisler.com/index.php/downloads/debug-tools?task=view&id=190) 
31 1 Pierre-Henri HORREIN
32 1 Pierre-Henri HORREIN
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].
33 1 Pierre-Henri HORREIN
34 1 Pierre-Henri HORREIN
h3. Getting started : simulate a first Leon design
35 1 Pierre-Henri HORREIN
36 2 Pierre-Henri HORREIN
 # 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.
37 2 Pierre-Henri HORREIN
 # 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 :
38 3 Pierre-Henri HORREIN
   <pre>cd ~/ouessant</pre>
39 1 Pierre-Henri HORREIN
 # Set up the Ouessant environment:
40 3 Pierre-Henri HORREIN
   <pre>make env</pre>
41 1 Pierre-Henri HORREIN
   This will clone all necessary files from the git.
42 2 Pierre-Henri HORREIN
   *Warning* : make sure that you have all the required permissions on the ouessant folder.
43 1 Pierre-Henri HORREIN
 # Now go to the leon3-ouessant-mst-minimal folder by typing:
44 3 Pierre-Henri HORREIN
   <pre>cd socs/leon3-ouessant-mst-minimal/</pre>
45 2 Pierre-Henri HORREIN
   and compile the project by running
46 3 Pierre-Henri HORREIN
   <pre>make vsim</pre>
47 1 Pierre-Henri HORREIN
   By default, this will compile a Leon processor with required peripherals, and a Ouessant with a Spiral DFT (256 points) accelerator.
48 2 Pierre-Henri HORREIN
 # Finally, type
49 3 Pierre-Henri HORREIN
   <pre>make vsim-launch</pre>
50 2 Pierre-Henri HORREIN
   to launch the simulation. This will only launch ModelSim?, you can then launch the simulation. This example takes a simulated 30 ms to complete. 
51 1 Pierre-Henri HORREIN
52 1 Pierre-Henri HORREIN
h3. Going further: modifying the project
53 1 Pierre-Henri HORREIN
54 1 Pierre-Henri HORREIN
Congratulations, you launched your first Ouessant project!
55 1 Pierre-Henri HORREIN
56 1 Pierre-Henri HORREIN
You can now modify it if you want to suit your need.
57 1 Pierre-Henri HORREIN
58 1 Pierre-Henri HORREIN
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.
59 1 Pierre-Henri HORREIN
60 1 Pierre-Henri HORREIN
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.
61 1 Pierre-Henri HORREIN
62 1 Pierre-Henri HORREIN
h3. Getting started: run Ouessant on a FPGA
63 1 Pierre-Henri HORREIN
64 1 Pierre-Henri HORREIN
For now, Ouessant is available on Atlys and Nexys4 boards, only with a Leon project.
65 1 Pierre-Henri HORREIN
66 2 Pierre-Henri HORREIN
# If you want to load your project on FPGA, you first have to connect it to your computer and to turn it on.
67 2 Pierre-Henri HORREIN
# 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.
68 2 Pierre-Henri HORREIN
# 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.
69 2 Pierre-Henri HORREIN
# 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.
70 2 Pierre-Henri HORREIN
# Connect your FPGA to your computer using its IP address via Network Manager for instance.
71 2 Pierre-Henri HORREIN
# 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.
72 2 Pierre-Henri HORREIN
# Open PuTTY by typing "putty" in your terminal. Please note that you should have PuTTY already installed.
73 2 Pierre-Henri HORREIN
# Fill the Host Name field with "/dev/ttyACM0" and the port name with "38 400".
74 2 Pierre-Henri HORREIN
# 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.
75 2 Pierre-Henri HORREIN
# Now you can load your program by typing the following command line in the GRMON terminal load systest.exe.
76 2 Pierre-Henri HORREIN
# Finally, you can run your program simply by typing "run" in the GRMON terminal.
77 2 Pierre-Henri HORREIN
# When you're done, you can exit the GRMON terminal by typing "quit". 
78 1 Pierre-Henri HORREIN
79 1 Pierre-Henri HORREIN
Have fun !
80 1 Pierre-Henri HORREIN
81 1 Pierre-Henri HORREIN
h2. Testing
82 1 Pierre-Henri HORREIN
83 1 Pierre-Henri HORREIN
In Ouessant, we try to keep everything functional from version to version. This is done through automated testing.
84 1 Pierre-Henri HORREIN
85 1 Pierre-Henri HORREIN
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.
86 1 Pierre-Henri HORREIN
Which simulator?
87 1 Pierre-Henri HORREIN
88 1 Pierre-Henri HORREIN
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.
89 1 Pierre-Henri HORREIN
90 2 Pierre-Henri HORREIN
 * 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.
91 2 Pierre-Henri HORREIN
 * 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.
92 2 Pierre-Henri HORREIN
 * 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. 
93 1 Pierre-Henri HORREIN
94 1 Pierre-Henri HORREIN
h3. Test architecture overview
95 1 Pierre-Henri HORREIN
96 1 Pierre-Henri HORREIN
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.
97 1 Pierre-Henri HORREIN
98 1 Pierre-Henri HORREIN
# Create your testbench in @$(OUESSANT)/ocp/testbench@. This must respect a few criterions:
99 2 Pierre-Henri HORREIN
    
100 1 Pierre-Henri HORREIN
  *  it must have a generic @debug_level@ of type @severity_level@.
101 1 Pierre-Henri HORREIN
  *  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.
102 1 Pierre-Henri HORREIN
  *  it should be automated, with an automated checker. Errors should be detected with an assert, with severity @debug_level@.
103 2 Pierre-Henri HORREIN
  *  you can use and improve the tb_global_pkg package, which provides some useful procedure to display data and generate random inputs. 
104 2 Pierre-Henri HORREIN
# 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.
105 2 Pierre-Henri HORREIN
  There are some little points to take into account when writing tests:
106 2 Pierre-Henri HORREIN
   
107 2 Pierre-Henri HORREIN
  *    the test (ie. the directory) must have the same name than the entity of the top testbench it is linked to.
108 2 Pierre-Henri HORREIN
  *    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.
109 2 Pierre-Henri HORREIN
  *    a short human-readable description of the test is provided in short_description, and a detailed one in long_description.
110 1 Pierre-Henri HORREIN
  *    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.
111 2 Pierre-Henri HORREIN
  *    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. 
112 3 Pierre-Henri HORREIN
# You can now run your test. Run: 
113 2 Pierre-Henri HORREIN
114 3 Pierre-Henri HORREIN
<pre>make help_tests</pre>
115 2 Pierre-Henri HORREIN
116 3 Pierre-Henri HORREIN
to get a list of tests related command. 
117 2 Pierre-Henri HORREIN
118 1 Pierre-Henri HORREIN
h3. Using GHDL to perform non-regression tests
119 1 Pierre-Henri HORREIN
120 1 Pierre-Henri HORREIN
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.
121 1 Pierre-Henri HORREIN
122 1 Pierre-Henri HORREIN
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.
123 1 Pierre-Henri HORREIN
Installing GHDL
124 1 Pierre-Henri HORREIN
125 1 Pierre-Henri HORREIN
To install GHDL in the Ouessant project, you first need to install llvm, clang, libz and libedit. In a Debian/Ubuntu distribution, run :
126 1 Pierre-Henri HORREIN
127 3 Pierre-Henri HORREIN
<pre>sudo apt-get install gnat-5 llvm-dev clang libedit-dev libz-dev mercurial</pre>
128 1 Pierre-Henri HORREIN
129 1 Pierre-Henri HORREIN
Once this is done, you can run the install script:
130 1 Pierre-Henri HORREIN
131 2 Pierre-Henri HORREIN
    @$OUESSANT/scripts/install_ghdl.sh <path_to_ouessant>@
132 1 Pierre-Henri HORREIN
133 1 Pierre-Henri HORREIN
The script will install a local version in $OUESSANT/tools/ghdl-local. Once it successfully finishes, you can run
134 1 Pierre-Henri HORREIN
135 2 Pierre-Henri HORREIN
    @make tests_ghdl@
136 1 Pierre-Henri HORREIN
137 1 Pierre-Henri HORREIN
to run the complete set of tests, or
138 1 Pierre-Henri HORREIN
139 2 Pierre-Henri HORREIN
    @make <unit_test>_batch_ghdl@
140 1 Pierre-Henri HORREIN
141 1 Pierre-Henri HORREIN
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!).
142 1 Pierre-Henri HORREIN
Current limitations of the test architecture
143 1 Pierre-Henri HORREIN
144 1 Pierre-Henri HORREIN
There are some limitations which will be addressed later:
145 1 Pierre-Henri HORREIN
146 2 Pierre-Henri HORREIN
 * a test can only be described to succeed. For now, you cannot create a failing configuration. This will be addressed later.