OuessantQuickStart » Historique » Version 18

Pierre-Henri HORREIN, 16/11/2016 20:07

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 5 Pierre-Henri HORREIN
This page is still a Work in Progress. Feel free to signal any mistake/lack in the description.
7 1 Pierre-Henri HORREIN
8 5 Pierre-Henri HORREIN
h2. First simulation
9 1 Pierre-Henri HORREIN
10 1 Pierre-Henri HORREIN
Here are the required steps to set a Ouessant based system up. For now, only Leon based platforms are possible
11 1 Pierre-Henri HORREIN
12 1 Pierre-Henri HORREIN
h3. Requirements
13 1 Pierre-Henri HORREIN
14 1 Pierre-Henri HORREIN
In order to use Ouessant, a few tools are needed.
15 1 Pierre-Henri HORREIN
16 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:
17 1 Pierre-Henri HORREIN
18 8 Pierre-Henri HORREIN
    @sudo apt-get install build-essential gcc make git bison flex @
19 2 Pierre-Henri HORREIN
20 1 Pierre-Henri HORREIN
Ouessant is a hardware design, thus CAD tools are needed according to your needs:
21 1 Pierre-Henri HORREIN
22 5 Pierre-Henri HORREIN
 * if you want to work in simulation, ModelSim is required. 
23 16 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).
24 16 Pierre-Henri HORREIN
 * for Zynq based device, we use Vivado toolsuite
25 16 Pierre-Henri HORREIN
 
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 1 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 16 Pierre-Henri HORREIN
For Zynq (ARM based) SoC, this means:
33 16 Pierre-Henri HORREIN
 * the compiler(s) for the ARM processor (we use the compiler suite from Xilinx)
34 16 Pierre-Henri HORREIN
35 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].
36 1 Pierre-Henri HORREIN
37 5 Pierre-Henri HORREIN
h3. Getting started: setting up Ouessant environment
38 1 Pierre-Henri HORREIN
39 7 Pierre-Henri HORREIN
 # Download the project repository:
40 7 Pierre-Henri HORREIN
   <pre>git clone https://redmine.telecom-bretagne.eu/git/ouessant/ </pre>
41 1 Pierre-Henri HORREIN
42 1 Pierre-Henri HORREIN
 # Go to the project's root (ie. the folder you have just created by cloning the repository). If you put it in your home directory, you can do this by typing :
43 1 Pierre-Henri HORREIN
   <pre>cd ~/ouessant</pre>
44 1 Pierre-Henri HORREIN
 # Set up the Ouessant environment:
45 17 Pierre-Henri HORREIN
   <pre>make env-complete</pre>
46 16 Pierre-Henri HORREIN
   This will generate the complete environment for Zynq and Leon based systems. 
47 16 Pierre-Henri HORREIN
   You can use 
48 16 Pierre-Henri HORREIN
   <pre>make env-zynq</pre> or <pre>make env-leon</pre> if you only want a single system.
49 1 Pierre-Henri HORREIN
   *Warning* : make sure that you have all the required permissions on the ouessant folder.
50 5 Pierre-Henri HORREIN
51 5 Pierre-Henri HORREIN
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. 
52 1 Pierre-Henri HORREIN
53 16 Pierre-Henri HORREIN
The code is divided in 6 main directories (other directories will be described later):
54 5 Pierre-Henri HORREIN
55 12 Pierre-Henri HORREIN
* @ocp@ contains the main VHDL code for Ouessant,
56 16 Pierre-Henri HORREIN
* @data@ contains various data for Ouessant. In particular, it contains Coprocessor descriptions
57 5 Pierre-Henri HORREIN
* @drivers@ has all the example codes in it, for Linux and baremetal
58 5 Pierre-Henri HORREIN
* @socs@ is the main directory for complete example System on Chips
59 5 Pierre-Henri HORREIN
* @scripts@ contains tools for automation
60 5 Pierre-Henri HORREIN
* @tools@ is created to store tools for Ouessant, mainly the assembler 
61 5 Pierre-Henri HORREIN
62 5 Pierre-Henri HORREIN
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. 
63 5 Pierre-Henri HORREIN
64 5 Pierre-Henri HORREIN
h3. Simulate a first Leon design
65 11 Pierre-Henri HORREIN
66 9 Pierre-Henri HORREIN
We are now going to simulate a Spiral FFT design using Ouessant. 
67 12 Pierre-Henri HORREIN
68 9 Pierre-Henri HORREIN
 # Go to the leon3-ouessant-mst-minimal folder by typing:
69 3 Pierre-Henri HORREIN
   <pre>cd socs/leon3-ouessant-mst-minimal/</pre>
70 1 Pierre-Henri HORREIN
   and compile the project by running
71 1 Pierre-Henri HORREIN
   <pre>make vsim</pre>
72 9 Pierre-Henri HORREIN
   By default, this will compile a Leon processor with required peripherals, and a Ouessant with a Spiral DFT (256 points) accelerator. Further information on how to change this design are given in the "Going further" section. 
73 9 Pierre-Henri HORREIN
 # The design is now compiled, we can compile the associated code. This is done by running 
74 9 Pierre-Henri HORREIN
   <pre> make install </pre>
75 9 Pierre-Henri HORREIN
   which will compile the code and create the RAM image for the design. 
76 1 Pierre-Henri HORREIN
 # Finally, type
77 1 Pierre-Henri HORREIN
   <pre>make vsim-launch</pre>
78 1 Pierre-Henri HORREIN
   to launch the simulation. This will launch ModelSim with the compiled design. 
79 1 Pierre-Henri HORREIN
   You can then launch the simulation. We provide a complete wave configuration to show what is going on inside Ouessant. Type 
80 12 Pierre-Henri HORREIN
   <pre> 
81 12 Pierre-Henri HORREIN
 do wave.do
82 12 Pierre-Henri HORREIN
 run 30 ms
83 9 Pierre-Henri HORREIN
   </pre>
84 10 Pierre-Henri HORREIN
   to start the simulation. The device starts to do things around 1.6 ms. You should see the first result output around 2 ms, and the first values around 4.7 ms. This takes a few minutes to reach depending on your machine. While simulation is useful to debug the coprocessor, complete simulation of a Leon-based device can be long. If you see a result in the transcript, functional verification is faster (as long as it is working!) on the FPGA. 
85 1 Pierre-Henri HORREIN
86 6 Pierre-Henri HORREIN
h2. Going further
87 6 Pierre-Henri HORREIN
88 1 Pierre-Henri HORREIN
h3. Going further: modifying the project
89 1 Pierre-Henri HORREIN
90 1 Pierre-Henri HORREIN
Congratulations, you launched your first Ouessant project!
91 1 Pierre-Henri HORREIN
92 10 Pierre-Henri HORREIN
You can now modify it if you want to suit your need. Here, we provide a description of what can be found where. 
93 1 Pierre-Henri HORREIN
94 1 Pierre-Henri HORREIN
The SoC you are working on is based on the minimal Leon example from Gaisler. Nearly all the automation comes from Aeroflex. If you need to change things, two files can be useful: 
95 12 Pierre-Henri HORREIN
96 10 Pierre-Henri HORREIN
   * @leon3mp.vhd@ is the top-level file. You can find a @ouessant0@ instantiation. The @orac@ generic of this instantiation defines which available accelerator you want to use. This is very basic, but will be improved in the next release of Ouessant. You can find valid values in @data/grlib-interface/devices.vhd" . Only a few are available for now, but you can add your own if you like. 
97 1 Pierre-Henri HORREIN
   * @Makefile@ is used to build the design. One specific variable is important here: @PROGDIR@. It is the path of the required program. You can change it as you like. 
98 1 Pierre-Henri HORREIN
99 12 Pierre-Henri HORREIN
The code which is executed is typically stored in @drivers/racs_examples/@. In our case, we use the @fft_float_test@ app, which runs a simple FFT test. The @fft.S@ file is the Ouessant microcode. It is compiled and available in the @fft_ouessant.[ch]@ files. You can change this in the Makefile. The @main.c@ is the main code. It allocates data, initializes Ouessant, and runs infinitely the tests. You can comment in or out the 4 configuration macros: 
100 10 Pierre-Henri HORREIN
101 10 Pierre-Henri HORREIN
   * SOFTWARE_VERSION allows usage of FFTW to compare the results
102 10 Pierre-Henri HORREIN
   * RANDOM_INPUT will randomly change inputs at each iteration
103 1 Pierre-Henri HORREIN
   * PRINT_RESULT will provide some info on the standard output
104 10 Pierre-Henri HORREIN
   * SIMULATE is defined to provide a ligher test code when simulating the design.
105 1 Pierre-Henri HORREIN
106 10 Pierre-Henri HORREIN
If you want to run a FPGA test, we advise you to define the first three macros. 
107 10 Pierre-Henri HORREIN
108 16 Pierre-Henri HORREIN
h3. Getting started: run Ouessant on a FPGA with Leon
109 1 Pierre-Henri HORREIN
110 10 Pierre-Henri HORREIN
For now, Ouessant is available on Atlys and Nexys4 boards, only with a Leon project. We describe how to run a test on Nexys 4 in the following steps. Atlys works the same, except that you do not use the same base designs. 
111 1 Pierre-Henri HORREIN
112 15 Pierre-Henri HORREIN
*_Please note that due to a temporary bug, ethernet is currently not optional. This will be corrected in the next days_*
113 15 Pierre-Henri HORREIN
114 10 Pierre-Henri HORREIN
# First, we are going to generate the programming file for the FPGA. Change to the directory for the SoC you want to use, in our case: 
115 10 Pierre-Henri HORREIN
<pre> cd socs/leon3-ouessant-digilent-nexys4 </pre>
116 10 Pierre-Henri HORREIN
# If you need to change the project, do it now. Ouessant ships with a functional FFT design for Nexys 4. 
117 10 Pierre-Henri HORREIN
# Build the design for FPGA: 
118 10 Pierre-Henri HORREIN
<pre> make ise </pre>
119 1 Pierre-Henri HORREIN
This will take around 30 minutes, once again depending on your machine (tests have been performed on an Intel Core i5 running at 2.8 Ghz, with 8 GB of RAM, and a SSD disk).
120 10 Pierre-Henri HORREIN
# Connect the FPGA board to your computer and turn it on. You need to connect: 
121 12 Pierre-Henri HORREIN
122 10 Pierre-Henri HORREIN
   * the serial port and programming port (they are the same for Nexys4, so only one cable is required)
123 10 Pierre-Henri HORREIN
   * (optional) the ethernet port to an ethernet port of your host computer. This is not necessary, but recommended, since sending the example code can be very long otherwise. For baremetal testing, serial port is sufficient, loading will take a few seconds. 
124 10 Pierre-Henri HORREIN
# Program the FPGA: 
125 10 Pierre-Henri HORREIN
<pre> make ise-prog-fpga</pre>
126 10 Pierre-Henri HORREIN
# Modify the code as explained in the previous part, and compile the software code:
127 10 Pierre-Henri HORREIN
<pre> make install </pre>
128 1 Pierre-Henri HORREIN
# (optional) If you use Ethernet, please ensure that the IP address is set on the network interface. It should be in the 192.168.0.0/24 subnet. 
129 10 Pierre-Henri HORREIN
# Connect to the loaded Leon design using one of the following: 
130 12 Pierre-Henri HORREIN
131 14 Pierre-Henri HORREIN
   * if you want to use the serial port. Note that @/dev/ttyUSB1@ must be change to match the actual port
132 14 Pierre-Henri HORREIN
     <pre>grmon -uart /dev/ttyUSB1 -baud 38400 -u </pre>
133 14 Pierre-Henri HORREIN
   * (optional) if you want to use Ethernet
134 14 Pierre-Henri HORREIN
     <pre>grmon -eth</pre> 
135 14 Pierre-Henri HORREIN
     
136 1 Pierre-Henri HORREIN
# Load the compiled code in the Leon RAM by typing in the grmon command line interface:
137 1 Pierre-Henri HORREIN
<pre>load systest.exe</pre>
138 1 Pierre-Henri HORREIN
# (optional) If you use Ethernet, connect a serial monitor to the board (Putty is a wonderful tool for this) using the correct parameters (baudrate is 38400). 
139 1 Pierre-Henri HORREIN
# Run the test and check the results! 
140 1 Pierre-Henri HORREIN
<pre> run </pre>
141 16 Pierre-Henri HORREIN
142 16 Pierre-Henri HORREIN
h3. Getting started: run Ouessant on a FPGA with Zynq on ZedBoard
143 16 Pierre-Henri HORREIN
144 16 Pierre-Henri HORREIN
Working with Zynq is much more straightforward, since it doesn't require as much Third Party tools. 
145 16 Pierre-Henri HORREIN
# Change into the correct directory
146 16 Pierre-Henri HORREIN
<pre>cd socs/zynq-ouessant-zedboard</pre>
147 16 Pierre-Henri HORREIN
# Clean any previously generated files
148 16 Pierre-Henri HORREIN
<pre>make clean</pre>
149 16 Pierre-Henri HORREIN
# Build for a given configuration
150 16 Pierre-Henri HORREIN
<pre>make build</pre>
151 16 Pierre-Henri HORREIN
# Connect the ZedBoard and program the FPGA
152 16 Pierre-Henri HORREIN
<pre>make prog-fpga</pre>
153 16 Pierre-Henri HORREIN
154 18 Pierre-Henri HORREIN
Once the hardware part is ready, we can proceed with the software part. We describe here how to run the Zynq examples.
155 18 Pierre-Henri HORREIN
# Change into the sofware Board Support Package directory
156 18 Pierre-Henri HORREIN
<pre>cd drivers/zynq_examples/bsp</pre>
157 18 Pierre-Henri HORREIN
# Build the bsp library
158 18 Pierre-Henri HORREIN
<pre>make</pre>
159 18 Pierre-Henri HORREIN
# Change to the example code for your Ouessant CoProcessor. Here, we run the fft example. 
160 18 Pierre-Henri HORREIN
<pre>cd ../units/fft </pre>
161 18 Pierre-Henri HORREIN
# Build the code
162 18 Pierre-Henri HORREIN
<pre>make</pre>
163 18 Pierre-Henri HORREIN
# Connect your ZedBoard to your computer and configure the serial port (on Linux, /dev/ttyACM0 with speed 115200)
164 18 Pierre-Henri HORREIN
# Launch xmd
165 18 Pierre-Henri HORREIN
<pre>xmd</pre>
166 18 Pierre-Henri HORREIN
# In XMD, configure the processor: 
167 18 Pierre-Henri HORREIN
<pre>source launch.tcl</pre>
168 18 Pierre-Henri HORREIN
# Run the app!
169 18 Pierre-Henri HORREIN
<pre>run</pre>
170 1 Pierre-Henri HORREIN
171 1 Pierre-Henri HORREIN
Have fun !