OuessantQuickStart » Historique » Révision 10
Révision 9 (Pierre-Henri HORREIN, 15/03/2016 15:13) → Révision 10/19 (Pierre-Henri HORREIN, 15/03/2016 16:08)
{{>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 bison flex @
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 project repository:
<pre>git clone https://redmine.telecom-bretagne.eu/git/ouessant/ </pre>
# 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 :
<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
We are now going to simulate a Spiral FFT design using Ouessant.
# 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. Further information on how to change this design are given in the "Going further" section.
# The design is now compiled, we can compile the associated code. This is done by running
<pre> make install </pre>
which will compile the code and create the RAM image for the design.
# Finally, type
<pre>make vsim-launch</pre>
to launch the simulation. This will launch ModelSim with the compiled design.
You can then launch the simulation. We provide a complete wave configuration to show what is going on inside Ouessant. Type
<pre> do wave.do
run 30 ms
</pre>
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.
h2. Going further
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. Here, we provide a description of what can be found where.
The SoC
If you are working on is based on open the minimal Leon example from Gaisler. Nearly all the automation comes from Aeroflex. If you need to change things, two files can be useful:
* @leon3mp.vhd@ is the top-level file. You can find a @ouessant0@ instantiation. The @orac@ generic of this instantiation defines which available accelerator file, you want to use. This is very basic, but will be improved in see the next release of Ouessant. You can find valid values in @data/grlib-interface/devices.vhd" . Only a few are available top for now, but you can add your own if you like.
* @Makefile@ is used to build the this design. One specific variable is important here: @PROGDIR@. It is the path of the required program. You can change it as you like.
The code which is executed is typically stored in @drivers/racs_examples/@. In our case, we use modify the @fft_float_test@ app, which runs a simple FFT test. The @fft.S@ file is the Ouessant microcode. It is compiled and available instantiation in the @fft_ouessant.[ch]@ files. You it (called @ouessant0@). For example, you can change this in the Makefile. The @main.c@ is the main code. It allocates data, initializes Ouessant, and runs infinitely the tests. @orac@ generic parameter to suit your need.
You can comment in or out also modify the 4 configuration macros:
* SOFTWARE_VERSION allows usage of FFTW to compare the results
* RANDOM_INPUT will randomly change inputs at each iteration
* PRINT_RESULT will provide some info on the standard output
* SIMULATE is defined to provide a ligher test source code when simulating by editing the design. @systest.c@ file. For the moment, no Ouessant compiler exists, and the microcode must be written directly in binary.
If you want to run a FPGA test, we advise you to define the first three macros.
h3. Getting started: run Ouessant on a FPGA
For now, Ouessant is available on Atlys and Nexys4 boards, only with a Leon project. We describe how
# If you want to run a test load your project on Nexys 4 in the following steps. Atlys works the same, except that FPGA, you do not use the same base designs.
# First, we are going first have to generate the programming file for the FPGA. Change connect it to your computer and to turn it on.
# Go into the directory for the SoC you want design corresponding to use, in our case:
<pre> cd socs/leon3-ouessant-digilent-nexys4 </pre> your FPGA~/ouessant/design/leon3-ouessant-digilent-atlys/ and make sure there is the right version of leon3mp.vhd and systest.c.
# If you need to change Type the project, do it now. Ouessant ships with a functional FFT design following command line "make ise-prog-fpga". This will compile all vhd files for Nexys 4.
your Digilent Atlys FPGA. Please note that you should have Adept already installed.
# Build Type the design for FPGA:
<pre> make ise </pre>
following command line "sparc-elf-gcc systest.c -o systest". This will take around 30 minutes, once again depending on cross compile your machine (tests have been performed on an Intel Core i5 running at 2.8 Ghz, with 8 GB of RAM, and C file into a SSD disk). binary stream for your FPGA.
# Connect the your FPGA board to your computer and turn it on. You need to connect:
* using its IP address via Network Manager for instance.
# Type the serial port and programming port (they are the same for Nexys4, so only one cable following command line "grmon -eth XXX.XXX.X.XX" where XXX.XXX.X.XX is required)
* (optional) your FPGA's IP address. The LED at the ethernet port to an ethernet port right of your host computer. This is not necessary, but recommended, since sending the example code can FPGA should be very long otherwise. For baremetal testing, serial port is sufficient, loading will take a few seconds.
on.
# Program the FPGA:
<pre> make ise-prog-fpga</pre> Open PuTTY by typing "putty" in your terminal. Please note that you should have PuTTY already installed.
# Modify Fill the code as explained in the previous part, Host Name field with "/dev/ttyACM0" and compile the software code: port name with "38 400".
<pre> # To make install </pre>
# (optional) If you use Ethernet, please ensure sure that you're correctly connected, click on the IP address is set reset button on the network interface. It your FPGA. A short message should be in pop on the 192.168.0.0/24 subnet.
PuTTY terminal.
# Connect to the loaded Leon design using one of the following:
* @grmon -uart /dev/ttyUSB1 -baud 38400 -u @ if Now you want to use can load your program by typing the serial port. Note that @/dev/ttyUSB1@ must be change to match following command line in the actual port.
* @grmon -eth@ if GRMON terminal load systest.exe.
# Finally, you want to use Ethernet.
# Load the compiled code in the Leon RAM can run your program simply by typing "run" in the grmon command line interface: GRMON terminal.
<pre>load systest.exe</pre>
# (optional) If When you're done, you use Ethernet, connect a serial monitor to can exit the board (Putty is a wonderful tool for this) using the correct parameters (baudrate is 38400).
# Run the test and check the results!
<pre> run </pre>
GRMON terminal by typing "quit".
Have fun !