Getting Started

Follow this guide to:

  • Setup a command line development environment on Ubuntu

  • Get the source code

  • Build and run a helloworld

Within this doc, you can find all the api descriptions, how to use our tools (like nntool, gvsoc, profiler, etc), and some useful application notes.

Get the GAP SDK

Note

Depending on your system, you might need to install git. With Ubuntu 22.04, use: sudo apt install git.

Clone the actual sdk repository

  • gitlab: you can find the url on the top, blue button which written “Clone”

  • github: you can find the url on the top, green button which written “Code”

git clone <the url of this repository>

If you are using ssh to clone, don’t forget to put your ssh-key in your account.

Install dependencies

The SDK installation instructions were developed using a fresh Ubuntu 22.04 (Jammy Jellyfish) 64-Bit virtual machine from [OS-Boxes](https://www.osboxes.org/ubuntu/#ubuntu-2204-info).

Some packages need to be installed. Please run the following command to install them.

# Update your system
sudo apt udpate
sudo apt upgrade

# install all system dependencies
cat requirements_apt_ubuntu_22_04.md | xargs sudo apt install -y

Python Package Management

SDK and some tools are all based on Python3 (version > 3.8), you can use following command to set your default python to python3.

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10

This will setup a “python” binary pointing at python3.

Download and install the toolchain

Now clone the GAP/RISC-V toolchain:

git clone https://github.com/GreenWaves-Technologies/gap_riscv_toolchain_ubuntu.git
cd gap_riscv_toolchain_ubuntu
# Depending on where you want to install it, you may need to run this command with sudo
./install.sh

Note

Please note that the toolchain receives updates on a different basis than the SDK, therefore this step must be re-done regularly.

Configure the SDK

You can either source sourceme.sh in the root sdk folder and then select the right board from the list, or directly source the board config.

source sourceme.sh

or

source config/<the target you want to use>.sh

Once the proper config file is sourced, you can proceed with the SDK build.

Note that after the SDK has been built, you can source another board config file to change the board configuration, in case you want to use a different board. In this case the SDK will have to be built again. As soon as the SDK has been built once for a board configuration, it does not need to be built again for this configuration, unless the SDK is cleaned.

Python requirements

Our modules (Gapy/NNTool between others) require a few additional Python packages to function. We recommend that you create a python venv for the gap sdk. You can do so as follows:

cd PATH/TO/YOUR/SDK
# create the venv
python -m venv .venv
# source the venv (choose the right extension for your shell, sh is default for bash)
source .venv/bin/active.YOUR_SHELL_EXTENSION

Note

Please source the venv environment every time before sourcing the SDK’s sourceme.

Now that the venv is setup, you can install python dependencies with this command from GAP SDK root folder:

./install_python_deps.sh

SDK installation

First, use the following command to configure the shell environment correctly for the GAP SDK. It must be done for each terminal session:

cd path/to/gap_sdk

Choose which board

source sourceme.sh

Tip: You can add an “alias” command as follows in your .bashrc file:

# without venv
alias GAP_SDK='cd path/to/gap_sdk && source sourceme.sh'
# with venv:
alias GAP_SDK='cd PATH/TO/YOUR/SDK && .venv/bin/activate.YOUR_SHELL_EXTENSION && source sourceme.sh'

Typing GAP_SDK will now change to the gap_sdk directory and execute the source command.

Once in the SDK, run make help to get commands and get SDK ready to use.

$ make help
=================== GAP SDK ===================

Main targets:
 - clean       : clean the SDK
 - all         : build the whole SDK with all tools
 - openocd.all : build OpenOCD tools to run simulation on boards

Then, depends on what you need, build the SDK accordingly:

# Build with GUI (QT) tools
make <target> WITH_GUI_TOOLS=1
# Or without gui tools
make <target>

Install OpenOCD Rules

  • Copy openocd udev rules and reload udev rules:

sudo cp <your openocd path>/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload-rules && sudo udevadm trigger

  • Now, add your user to dialout group.

sudo usermod -a -G dialout <username>

This will require a logout / login to take effect

Build SDK Doc

For those that are reading this getting started from a PDF documentation, it is recomended to build the HTML documentation as it is more practical to use. SDK HTML documentation is built and generated based on SPHINX [https://www.sphinx-doc.org/en/master/], the SDK will have installed all the necessary packages for you. You just need to run:

cd doc
make html

This will generate the doc in HTML in

doc/_build/html/

and open the file index.html with your browser. With Firefox, you can do as follow:

firefox doc/_build/html/index.html

Build and run a HelloWorld

First connect your board to your PC’s USB port. Now, you should be able to run your first helloworld on the board.

cd examples/<target name>/basic/helloworld
# Init cmake build directory, named "build"
cmake -B build
# Configure the application, using build directory "build"
# --> here you may choose the plaform (board or gvsoc)
cmake --build build --target menuconfig
# Run the target
cmake --build build --target run

After the build you should see an output resembling:

*** PMSIS HelloWorld ***

Entering main controller
[32 0] Hello World!
Cluster master core entry
[0 7] Hello World!
[0 0] Hello World!
[0 4] Hello World!
[0 5] Hello World!
[0 3] Hello World!
[0 1] Hello World!
[0 2] Hello World!
[0 6] Hello World!
Cluster master core exit
Bye !

If this fails, ensure that you followed previous steps correctly (openocd install, udev rules). If libusb fails with a permission error, you might need to reboot to apply all changes.

If you need GAP tools for neural networks (nntool) or the Autotiler, please follow the next section.

Console IO via uart

If you choose to boot your application from Flash, and/or you want to view the output of printf’s in your code then you can first compile your application with the printf redirected on the UART with this command:

cmake --build build --target menuconfig

In the menuconfig, printf output interface may be configured in: GAP_SDK/Utils/IO with option Type. Interface may be specified there too. 0 will output on CN6 connector on the EVK. 1 will output on the ftdi.

You can also use a terminal program, like “cutecom”:

sudo apt-get install -y cutecom
cutecom&

Then please configure your terminal program to use /dev/ttyUSB<x> with a 115200 baud rate, 8 data bits and 1 stop bit.

Upgrading/Downgrading the SDK

To upgrade/downgrade your SDK to a new/old version:

cd gap_sdk
git checkout master && git pull
git checkout <release tag name>
# install python dependencies, in case those got updated
./install_python_deps.sh
# install all system dependencies, in case those got updated
cat requirements_apt_ubuntu_22_04.md | xargs sudo apt install -y
make clean all

A list of releases can be found in this repository.

Next Steps

Here are some next steps for exploring the GAP SDK: