NOELLE Offers Empowering LLVM Extensions

Table of Contents

• Description
• Version
• Prerequisites
• Building NOELLE
• Testing NOELLE
• Repository structure
• Examples of using NOELLE
• Contributions
• License

Description

NOELLE provides abstractions to help build advanced code analyses and transformations.

NOELLE is in active development so more tools, tests, and abstractions will be added.

We release NOELLE's source code in the hope of benefiting others. You are kindly asked to acknowledge usage of the tool by citing the following paper:

@inproceedings{NOELLE,
    title={{NOELLE} {O}ffers {E}mpowering {LL}VM {E}xtensions},
    author={Angelo Matni and Enrico Armenio Deiana and Yian Su and Lukas Gross and Souradip Ghosh and Sotiris Apostolakis and Ziyang Xu and Zujun Tan and Ishita Chaturvedi and David I. August and Simone Campanoni},
    booktitle={International Symposium on Code Generation and Optimization, 2022. CGO 2022.},
    year={2022}
}

The only documentation available for NOELLE is:

• a video introducing NOELLE
• the paper
• the comments within the code
• the slides we use in the class Advanced Topics in Compilers
• the wiki of the project

Version

The latest stable version is 9.9.1 (tag = v9.9.1).

Version Numbering Scheme

The version number is in the form of [v Major.Minor.Revision ]

• Major: Each major version matches a specific LLVM version (e.g., version 9 matches LLVM 9, version 11 matches LLVM 11)
• Minor: Starts from 0, each minor version represents either one or more API replacements/removals that might impact the users OR a forced update every six months (the minimum minor update frequency)
• Revision: Starts from 0; each revision version may include bug fixes or incremental improvements

Update Frequency

• Major: Matches the LLVM releases on a best-effort basis
• Minor: At least once per six months, at most once per month (1/month ~ 2/year)
• Revision: At least once per month, at most twice per week (2/week ~ 1/month)

Prerequisites

LLVM 9.0.0

Northwestern

Next is the information for those that have access to the Zythos cluster at Northwestern.

To enable the correct LLVM, run the following command from any node of the Zythos cluster:

source /project/extra/llvm/9.0.0/enable

The guide about the Zythos cluster can be downloaded here.

Building NOELLE

To build and install NOELLE: run make from the repository root directory.

Run make clean from the root directory to clean the repository.

Run make uninstall from the root directory to uninstall the NOELLE installation.

Testing NOELLE

To run all tests in parallel using Condor, invoke the following commands:

make clean ; 
cd tests ;
make condor ;

To monitor how tests are doing: cd tests ; make condor_watch

To find out if all tests passed: cd tests ; make condor_check

To test NOELLE using condor to run all tests in parallel, go to "tests" and run "make condor". This creates one regression_X sub-directory per configuration where X is going to be a number (e.g., regression_42). Each single test within a given regression_X sub-directory will contain a run_me.sh script, which is automatically generated by make condor. To re-produce the compilation for a specific test for a specific configuration (e.g., the one associated with the current regression_X sub-directory), then do the following:

cd tests/regression_42 ;
cd THE_TEST_YOU_ARE_INTERESTED ;
./run_me.sh ;

where regression_42 is the sub-directory of the configuration you are interested and THE_TEST_YOU_ARE_INTERESTED is the test you care.

To run only the autotuned performance tests using Condor, invoke the following commands:

make clean ;
cd tests ;
make condor_autotuner ;

The speedup results will be collected in the tests/performance/speedups_autotuner.txt file.

Repository structure

The directory src includes sources of the noelle framework. Within this directory, src/core includes the abstractions provided by NOELLE. Also, src/tools includes code transformations that rely on the NOELLE's abstractions to modify the code.

The directory external includes libraries that are external to noelle that are used by noelle. Some of these libraries are patched and/or extended for noelle.

The directory tests includes unit tests, integration tests, and performance tests. Furthermore, this directory includes the scripts to run all these tests in parallel via condor.

The directory examples includes examples of LLVM passes (and their tests) that rely on the noelle framework.

Finally, the directory doc includes the documentation of noelle.

Examples of using NOELLE

LLVM passes in the directory examples/passes shows use cases of NOELLE.

If you have any trouble using this framework feel free to reach out to us for help (contact [email protected]).

Contributing to NOELLE

NOELLE uses clang-format to ensure uniform styling across the project's source code. clang-format is run automatically as a pre-commit git hook, meaning that when you commit a file clang-format is automatically run on the file in-place.

Since git doesn't allow for git hooks to be installed when you clone the repository we manage this with our top-level Makefile. To install the NOELLE git hooks, run make hooks at the root of the directory. This make rule is run at the start of the make all rule as well for ease of use.

Contributions

We welcome contributions from the community to improve this framework and evolve it to cater for more users.

License

NOELLE is licensed under the MIT License.