Difference between revisions of "Toolchain"

Revision as of 22:48, 27 March 2019

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.

How to compile the the nu+ toolchain

To build the nu+ toolchain, you must launch ./setup_new.sh -n from a terminal in the compiler root folder. The script will create a new directory called build and will start building the compiler. By default the script tries to build the compiler using 4 threads. If you want to modify that, especially if your machine have less than 8GB of RAM, you can use the -t flag to specify the number of threads to use. Other information can be obtained by using the -h flag.

How to compile a kernel for the nu+ architecture

TODO: considerare rimuovere questo e spostarlo in nuova pagina (Writing nu+ applications)

Some kernels are provided with the standard release of the nu+ toolchain. We provide a makefile to compile these kernels for nu+. In case you want to add a new kernel, it is suggested to copy a kernel folder and replace C/C++ files with your own source code. Then, remember to modify the makefile updating the SRCS variable with the names of the C/C++ files you want to compile. When using these makefiles, different tools are called:

• Clang to emit the LLVM IR and the object files
• MCLINKER to handle the job of linking
• elf2hex to generate the HEX file from the ELF file
• llvm-objdump to generate the dump from the elf file

In order to change the optimization level of the compiler or any other flag, it is possible to modify the misc/NuPlus.mk (or misc/Makefile.nuplus if you are compiling a kernel for the MANGO project ) makefile.

How to compile the libraries for the nu+ architecture

To compile the libraries you only have to execute ./setup_new.sh -l from a terminal in the NuPlusLLVM root folder. The script will automatically build the libraries. Note that you must have compiled the nu+ compiler first.

The nu+ LLVM

The nu+ toolchain is based on the LLVM project and includes:

1. A custom version of the Clang frontend
2. A native nu+ backend
3. Some external tools that are used by llvm, i.e. linker, disassembler, etc..

In addition, in order add the nu+ architecture inside llvm, a registration phase was required.

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

• OpenCL extension for the nu+ architecture
• OpenMP extension for the nu+ architecture