Toolchain

From NaplesPU Documentation
Revision as of 14:55, 29 March 2019 by Francesco (talk | contribs) (The nu+ LLVM Structure)
Jump to: navigation, search

The nu+ toolchain is a collection of tools required to compile a nu+ executable application. It is based on the LLVM project leveraging on a custom version of the Clang Frontend and on a from-scratch implementation of the Backend. The toolchain comes with a modified version of LLD, an elf2hex tool to generate nu+ compatible memory images and lastly a custom version of the objdump tool for debug purposes. A custom implementation of the libc libraries is provided.

The toolchain supports the compilation of C-based and OpenCL C kernels.

Building Toolchain on Ubuntu Linux environment

This section shows how to build the nu+ toolchain in an Ubuntu Linux environment. The following steps are still valid in any other Unix-based system despite of package manager related differences.

Required Software

The nu+ toolchain installation relies on the following dependencies:

  • Git
  • GCC
  • CMake
  • Python 2.7
  • libxml
  • Zlib
  • Bison
  • Flex
  • Libedit
  • Swig
  • ncurses libraries
  • Ninja

The following terminal command may be used to install all required software:

$ sudo apt install libxml2-dev git cmake gcc g++ python bison flex zlib1g-dev swig python-dev libedit-dev libncurses5-dev ninja

Building Process

First, you have to obtain the source code from the official repository by typing the following command:

$ git clone https://gitlab.com/catecio/NuPlusLLVM.git <clone_directory>

The repository contains a helper script, setup.sh to make easier the installation process. To build a new implementation of the nu+ toolchain just type:

$ ./setup.sh -n

This command starts the compilation process, installing the toolchain in Release Mode in /usr/local/llvm-nuplus. If a debug version is required, add the -d flag to setup.sh. You can also choose the number of threads for the compilation process, by using the -t=<number_of_threads> parameter.

At the end of the compilation process, libraries are required to be linked to the installation folder:

$ ./setup.sh -l

Now, you can use the toolchain to build your own application.

The nu+ LLVM Structure

The nu+ toolchain relies on the LLVM project, version 7.0, providing customized implementation of its libraries to make possible generating nu+ executable kernels.

Clang is the compiler frontend for nu+, extended to handle the token-recognition of custom intrinsic functions.

LLVM core libraries are used to implement a custom backend for nu+, to manage the code lowering on the target-device.

LLD is adapted to match nu+ architecture requirements for linking.

objdump is provided to disassemble and analyze the generated code.

elf2hex is a tool required for memory image generation.


Check the following links for detailed informations on how the toolchain is implemented.

Testing

To test the code generation process, the LLVM testing infrastructure has been used.

The script "run_tests" can be used to run the nu+ testing suite. The main purpose is to perform regression tests, so that it is possible to determine if a change in the back-end has any negative consequence.

The tool used is the "llvm-lit", a python script that parses the test files and executes the testing commands.

The code generation tests are contained in "compiler/test/CodeGen/NuPlus" and cover the main LLVM IR operations. A code generation test file is a collection of functions written in LLVM IR with commands directed to the llvm-lit and FileCheck tools. These commands are written as comments. The main commands used are RUN, CHECK, and CHECK-LABEL.

The RUN line tells lit how to run the test. If there are no RUN lines, lit will issue an error while running a test. The line syntax is similar to a shell’s syntax for pipelines. To examine the output and check if the test has been passed, the FileCheck tool must be used.

The RUN line used for all the tests is:

; RUN: llc -march=nuplus < %s | FileCheck %s

This tells lit to run llc with nu+ architecture as target, to give the output file to the FileCheck tool.

The CHECK_LABEL and the CHECK lines are interpreted by the FileCheck tool. It compares the llc output file with the CHECK_LABEL and CHECK lines. The comparison is done in sequence, although there are directives that let the checking not be performed in sequential order, see [1] for further details.

Libraries

nu+ is provided with different kind of libraries that are contained in the libs/ folder. For more information, check The nu+ libraries.

Makefiles and linker scripts

TODO: completare

Debug and typical errors

For more information about the debug support and some typical errors, check How to debug LLVM.

Compiler Extensions