SLD Toolchain

2. SLD Toolchain#

../_images/richie_sld_toolchain.png

Fig. 2.1 SLD toolchain architecture.#

2.1. Introduction#

The Richie SLD toolchain is a System-Level Design (SLD) toolchain that automates and simplifies the hardware-software assembling and specialization of accelerator-rich HeSoCs. The toolchain comprises a set of Python-based tools, which enables the seamless and rapid composition of accelerators into full-fledged accelerator-rich HeSoCs, from a high-level description. Indeed, the toolchain supports various accelerator design flows, e.g., based on High-Level Synthesis (HLS). Generated HeSoCs are based on the Parallel Ultra Low Power (PULP) Platform, an open-source research and development platform targeting highly parallel architectures for ultra-low-power processing based on the RISC-V ISA. The Richie SLD toolchain was formerly named GenOv.

2.2. How to install#

2.2.1. Clone the Repository#

Clone the repository with its Git submodules using git clone --recursive <url> or fetch the submodules afterwards with git submodule update --init --recursive.

2.2.2. Integration within the Richie framework#

This toolchain is employed as part of the Richie framework, which includes the hardware and software components to design, build and deploy a full-fledged accelerator-rich HeSoC. The Richie SLD toolchain is leveraged to generate the HeSoC sources to drive the exploration of implementation variants, thus optimize the HeSoC on top of the application requirements. To safely let the framework parts interact, the root of the Richie hardware subsystem (RICHIE_HW) must be defined accordingly:

export RICHIE_HW=<global-path-to-richie>/richie/hardware

2.2.3. Python Virtual Environment#

The toolchain leverages a Python virtual environment to manage the tool dependencies. The toolchain has been tested with Python 3.8.10, so we recommend sticking with this version. To create the environment and install the required packages (listed inside requirements.txt), simply run:

make py_env_init

Then, the environment can be activated by source richie-py-env/bin/activate. If new packages are added, the environment can be updated with the following command:

make py_env_update_reqs

Note that the py_env_init command should be run again to install newly added packages and/or update old ones.

2.2.4. Third-Party Git Submodules#

Third-party submodules can be pulled with the following command:

make richie_gen_init

2.2.5. Third-Party Tools#

More information under tools.

2.3. System-Level Design#

The toolchain facilitates three SLD phases concerning the assembling of accelerator-rich HeSoCs:

  1. Accelerator design;

  2. System integration;

  3. System optimization.

2.3.1. Accelerator Design#

This phase produces the accelerator datapaths. The toolchain supports various design flows to accommodate a wide range of users and application needs, including:

The IP interface is expected to attain the following requirements:

  • Adopt a streaming-based interface for data communication, e.g. the AMBA® 4 AXI4-Stream Protocol.

  • Adopt simple data ports or wires for control parameters, thus with no associated I/O protocol and handshaking signal.

2.3.2. System Integration#

This phase generates the accelerator interfaces which facilitate the integration inside the accelerator-rich HeSoC. These include HW interfaces for data communication and control, as well as SW drivers (API, runtime, HAL). The user is asked to provide an accelerator specification file describing the characteristics of the accelerator interface, as shown in the example below:

class accelerator_specs:

            def engine(self):
                    self.name = Accelerator datapath
                    self.flow = HLS, RTL
                    self.protocol = HWPE
                    return self

            def streamer(self):
                    self.inputs = [[Name, DataType], ...]
                    self.outputs = [[Name, DataType], ...]
                    return self

            def controller(self):
                    self.regs = [[Name, DataType], ...]
                    return self

Specifications are collected in the accelerator library (src/accelerators/), including the following sections:

  • specs/: This location contains the accelerator specification file accelerator_specs.py, which embodies the required information to specialize the HW/SW interface between the application-specific accelerators and the outer platform.

2.3.3. System Optimization#

This phase performs the specialization of the platform parts to meet the requirements of the integrated workload. The outcome consists of a specialized and optimized accelerator-rich HeSoC. Similarly, this phase mandates a platform specification file with the HeSoC characteristics,

class platform_specs:

        def hesoc(self):
            self.name = Accelerator-Rich HeSoC
            self.target = FPGA fabric
            self.l2_mem = [Number of ports, Size]
            return self

        def cluster_0(self):
            self.acc = [Accelerator name, ...]
            self.proxy = [IP, Number of cores, ...]
            self.dma = [IP, Job queue size, ...]
            self.l1_mem = [Number of ports, Size]
            return self

        ...

        def cluster_N(self)
            ...

Specifications are collected in the platform library (src/platforms/), including the following sections:

  • specs/: This location contains the platform specification file platform_specs.py, which drives the specialization of the HeSoC platform.

2.4. Generation Flow#

The generation flow is the toolchain automation core and enables the seamless and rapid composition of accelerator-rich platforms.

2.4.1. Defintion of Template#

Templates consist of markup text which is parsed and rendered given an input set of parameters. This process allows to automate the customization of various types of components, which range from hardware IPs to software drivers, libraries and tooling scripts. Richie leverages Python and the Mako Template Library to implement this template-based approach.

Examples of other frameworks leveraging a similar method to generate modular and composable platforms and components include OpenPiton and OpenTitan.

The extension of the template files is composed of: * The generated file type, e.g., sv for SystemVerilog, tcl for TCL files, yml for YAML files, etc. * The employed template library (Mako).

For instance, a template component richie_module_top implemented in SystemVerilog will have the following name name: richie_module_top.sv.mako.

2.4.2. How Generation Works#

This SLD toolchain adopts a design automation approach, where:

  1. Platform and accelerator specification files are user-defined parameters, which are employed as the design knobs to specialize the HeSoC parts;

  2. Templates are rendered into various output formats, e.g., hardware-software components, scripts, documentation, etc;

  3. The generation flow provides parameters to a Mako-based rendering engine, which parses and renders the toolchain templates;

  4. The generation output is a full-fledged accelerator-rich HeSoC, including a ready-to-go hardware-software stack, simulation testbenches and FPGA scripts.

2.4.3. How to Run#

The generation flow is triggered with the following command:

make clean all TARGET_PLATFORM=<TARGET_PLATFORM>

Additionally, add the following arguments:

  • TARGET_PLATFORM: This is to specify the target platform, where the device-under-test (DUT) is integrated. This should match the name declared in the corresponding platform specification file. For example, make clean all TARGET_PLATFORM=richie_example is run to generate the target platform richie_example, which specification is kept under src/platforms/richie_example/specs.

The generated components will then be available under output.

2.5. Verification#

2.5.1. HWPE Accelerator (Standalone)#

This toolchain supports the standalone verification of its generated HWPE accelerators. Additional information concerning the adopted test suite is available in the repository of the HWPE TestBench (TB).

2.5.1.1. Clone the Repository#

The HWPE TB is cloned as a Git submodule running git submodule update --init --recursive.

2.5.1.2. Prepare the Verification Environment#

Once the generation of the target platform completes, the verification environment can be set by importing the generated TB components. From the root of the Richie SLD toolchain, run the following command:

make acc_verif TARGET_PLATFORM=<TARGET_PLATFORM> TARGET_ACC_VERIF=<TARGET_ACC_VERIF>

Additionally, add the following arguments:

  • TARGET_PLATFORM: This is to specify the target platform, where the device-under-test (DUT) is integrated. This should match the name declared in the corresponding platform specification file.

  • TARGET_ACC_VERIF: The target DUT, which is assumed to be integrated into the <TARGET_PLATFORM>. This should match the name declared in the corresponding accelerator specification file.

2.5.1.3. Hardware Build#

Move now to the root of the HWPE TB (richie-sld-toolchain/verif/hwpe-tb) and run the following command to update the external IP sources:

make update-ips

At this point, the RTL source management tool (Bender) should have compiled a hw/compile.tcl including the necessary build dependencies for the RTL simulator. Then, set the QuestaSim environment variable to the simulation directory and finally build the HW:

export VSIM_PATH=<global-path-to-richie-sld-toolchain>/richie-sld-toolchain/verif/hwpe-tb/hw/sim
make build-hw

2.5.1.4. Prepare the PULP SDK#

There are several possibilities regarding the installation of the PULP SDK.

2.5.1.4.1. SDK Dependencies#

Start by installing the SDK dependencies of the pulp-builder.

2.5.1.4.2. Install by the pulp-sdk-release#

We recommend installing the SDK using the pulp-sdk-release.

Once installed, open pulp-sdk-release/env/env-sdk-2020.01.01.sh and modify the script with the information concerning the user environment. Then, the build environment can be set up as follows:

cd pulp-sdk-release
source env/env-sdk-2020.01.01.sh
source pkg/sdk/2020.01.01/configs/pulpissimo.sh
source pkg/sdk/2020.01.01/configs/platform-rtl.sh
cd ..

Note

Our tests have been conducted with the SDK environment version 2020.01.01.

2.5.1.4.3. Install by the pulp-builder#

Otherwise, the following commands are to install it through the pulp-builder:

git clone https://github.com/pulp-platform/pulp-builder.git
cd pulp-builder
git submodule update --init
source configs/pulpissimo.sh
./scripts/clean
./scripts/build-runtime
source sdk-setup.sh
source configs/rtl.sh
cd ..

2.5.1.5. Prepare the RISC-V Toolchain#

The RISCV toolchain has to be installed, as well. Then, after installation, add its install path to the TB path:

export PULP_RISCV_GCC_TOOLCHAIN_CI=<riscv-toolchain-path>

2.5.1.6. Golden Model#

The final verification goal is to assess the functionality of the generated HW components, thus a golden model is necessary. To this end, a C-based golden model is leveraged to generate input stimuli and output golden results, thus validating the DUT. This is inserted under hwpe-tb/sw/ref_sw.

Among the source files are:

  • main.c - Generation application.

  • ref_app.c - Reference SW-mapped application. It is assumed this has the same behavior as the accelerator datapath.

  • ref_app.h - Header file to support reference SW-mapped application.

  • gen_stim.c - Stimuli generator.

  • gen_Hfile.c - Script to generate header file values of a target array.

To generate input stimuli and golden results, run:

make ref_sw

Note

Refer to our accelerator examples to learn how to integrate a golden model in this test suite.

2.5.1.7. Software Build#

In hwpe-tb/sw you can find the SW components to build an application running bare-metal on the RISC-V core of the TB. The goal of the application is basically to program and feed the accelerator in a similar way to what would happen in a full-fledged system.

Return to the root of the HWPE TB and run:

make clean all

2.5.1.8. Run the RTL Simulation#

To run the simulation with no GUI:

make run

2.6. Tools#

2.6.1. Verible#

Verible is an open-source SystemVerilog style linter and formatting tool. The style linter is relatively mature and is used as part of our generation flow to analyze RTL components. Linting serves as a productivity tool for designers to quickly find typos and bugs at the time when the RTL is designed.

We leverage Verible to capture different aspects of the code and detect style elements that violate the lowRISC Verilog Coding Style Guide, thus reducing manual code alignment steps.

2.6.1.1. How to Install#

You can download and build Verible from scratch as explained on the Verible GitHub page. However, since this requires the Bazel build system we recommend consulting the Verible releases and download a pre-built binary for your machine.

The example below is for Ubuntu 20.04:

export VERIBLE_VERSION=v0.0-3644-g6882622d
wget https://github.com/google/verible/releases/download/${VERIBLE_VERSION}/verible-${VERIBLE_VERSION}-Ubuntu-20.04-focal-x86_64.tar.gz
tar -xf verible-${VERIBLE_VERSION}-Ubuntu-20.04-focal-x86_64.tar.gz

If you are using Ubuntu 18.04 then instead use:

export VERIBLE_VERSION=v0.0-3644-g6882622d
wget https://github.com/google/verible/releases/download/${VERIBLE_VERSION}/verible-${VERIBLE_VERSION}-Ubuntu-18.04-bionic-x86_64.tar.gz
tar -xf verible-${VERIBLE_VERSION}-Ubuntu-18.04-bionic-x86_64.tar.gz

Note that we currently use version v0.0-3644-g6882622d, but it is expected that this version is going to be updated frequently, since the tool is under active development.

2.6.1.2. How to Use#

Once the generation flow completes, Verible can be used to analyze the generated RTL. The tool arguments and invocations are managed in scripts/verible-format.py.

For example, the generated RTL of the target platform richie_example is analyzed by running the following command from the Toolchain root:

make check_systemverilog TARGET_PLATFORM=richie_example

2.6.2. Pylint#

Pylint is a static code analyser for Python 2 or 3.

We leverage Pylint to detect style elements that are in violation of the PEP8 Python Code Style Guide, thus reducing manual code alignment steps.

2.6.2.1. How to Install#

Pylint is automatically installed within the Python Virtual Environment of the Richie SLD toolchain.

2.6.2.2. How to Use#

Run the following command from the Toolchain root:

make check_python

2.6.3. ShellCheck#

ShellCheck is a shell script static analysis tool, which can detect style elements that are in violation of the Google Shell Style Guide.

2.6.3.1. How to Install#

Consult the ShellCheck repository and learn how to install the tool. We suggest downloading pre-compiled binaries for the latest release.

The example below is for Linux x86-64 (statically linked):

wget https://github.com/koalaman/shellcheck/releases/download/stable/shellcheck-stable.linux.x86_64.tar.xz
tar -xf shellcheck-stable.linux.x86_64.tar.xz

2.6.3.2. How to Use#

Run the following command from the Toolchain root:

make check_shell

2.6.4. Template support in VSCode#

Visual Studio Code (VSCode) allows to define language styles for custom file extensions.

2.6.4.1. How to Install#

Follow the following instructions:

  1. Open VSCode

  2. Press CTRL+SHIFT+p.

  3. Search for Preferences: Open User Settings (JSON) and add the following configuration:

"files.associations": {
        "*.sv.mako": "systemverilog",
        "*.v.mako": "verilog",
        "*.c.mako": "c",
        "*.py.mako": "python",
        "*.tcl.mako": "tcl",
        "*.yml.mako": "yml"
}

2.7. Useful Repositories#

2.7.1. AMD-Xilinx Open Hardware Competition 2023#

GenOv - the former name of the Richie SLD toolchain - was proposed in the 2023 edition of the AMD-Xilinx Open Hardware Competition.

Spoiler...
                                                                                                                                                                                ...We have not won! :-)

The contest outcome has been released as a tutorial to help you familiarize yourself with our work.

2.7.2. The HWPE Accelerator Interface#

The PULP platform repository includes the components of the HWPE accelerator interface that Richie leverages: Streamer and Controller. An example design of a HWPE-based MAC accelerator - as well as its testbench - are available as well. Both can be adopted as starting points to better understand the design principles and functionalities of the HWPE interface.

Contents