Skip to content

Commit bcdc528

Browse files
simollsimoll
authored
Merge pull request #31 from sx-aurora-dev/clean-readme
[VE][NFC] Clane README.md to merge upstream
2 parents cf8c8a0 + 4559a6a commit bcdc528

File tree

2 files changed

+176
-66
lines changed

2 files changed

+176
-66
lines changed

‎README-ve.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# LLVM for NEC SX-Aurora VE (llvm-ve-rv 1.8-dev)
2+
3+
[![Build Status](https://travis-ci.com/sx-aurora-dev/llvm-project.svg?branch=hpce%2Fdevelop)](https://travis-ci.com/sx-aurora-dev/llvm-project)
4+
5+
This is a fork of the LLVM repositoy with support for the NEC
6+
SX-Aurora TSUBASA Vector Engine (VE).
7+
8+
### Features
9+
10+
- C, C++ support.
11+
- VE Intrinsics for low-level vector programming.
12+
- Packed-mode vector code generation by default.
13+
- Automatic vectorization through LLVM's loop and SLP vectorizers.
14+
- When combined with RV for SX-Aurora, provides user-guided (and some automatic)
15+
outer-loop vectorization through the Region Vectorizer.
16+
- Two OpenMP offloading modes: VE to VH and VH to VE.
17+
18+
19+
### Build instructions
20+
21+
To build llvm-ve from source refer to
22+
[llvm-dev](https://github.com/sx-aurora-dev/llvm-dev) and
23+
[Compile.rst](llvm/docs/VE/Compile.rst).
24+
25+
26+
### General Usage
27+
28+
To compile C/C++ code for the VE run Clang/Clang++ with the following command
29+
line:
30+
31+
$ clang -target ve-linux -O3 ...
32+
33+
34+
### OpenMP offloading for/from SX-Aurora
35+
36+
To compile with OpenMP offloading from VE to VH (VHCall) use:
37+
38+
$ clang -target ve-linux -fopenmp -fopenmp-targets=x86_64-pc-linux -O3 ...
39+
40+
To compile with OpenMP offloading from VH to VE (VEO) use:
41+
42+
$ clang -march=native -fopenmp -fopenmp-targets=ve-linux -O3 ...
43+
44+
45+
### Outer-loop Vectorization
46+
47+
LLVM for SX-Aurora provides outer-loop vectorization, provided it is build with
48+
the Region Vectorizer. The following usage examples require an RV-enabled
49+
build.
50+
51+
To use user-guided outer-loop vectorization with RV annotate the loops to
52+
vectorize with `#pragma omp simd` and use:
53+
54+
$ clang -fopenmp-simd -mllvm -rv -O3 ...
55+
56+
This release comes with a preview feature for automatic outer-loop vectorization
57+
with RV. This will work for some loops that use `int64_t` for their iteration
58+
variables (loop counters). To enable automatic outer-loop vectorization with RV
59+
use:
60+
61+
$ clang -mllvm -rv -mllvm -rv-autovec -O3 ...
62+
63+
64+
### VE Intrinsics for direct vector programming
65+
66+
See [the manual](https://sx-aurora-dev.github.io/velintrin.html).
67+
There is also [a tutorial](https://sx-aurora-dev.github.io/ve-intrinsics-tutorial/).
68+
69+
### Clang Options
70+
71+
Refer to the [Clang Command Line Reference](Ghttps://clang.llvm.org/docs/ClangCommandLineReference.html) for general compiler flags
72+
There are VE-specific flags to control vector code generation:
73+
Note that packed mode code generation and vectorization is enabled by default.
74+
75+
- `clang -mno-vepacked` disables packed mode support.
76+
LLVM and the vectorizers will not use packed instructions.
77+
This option is incompatible with VE Intrinsics.
78+
- `clang -mno-vevpu` disables all vector code support.
79+
Disable vector code generation entirely.
80+
Vectorizers (of LLVM or RV) will keep all code scalar - no vector instructions will be generated.
81+
Incompatible with VE Intrinsics.
82+
- `clang -mvesimd` switches to the fixed SIMD legacy code generation path (deprecated).
83+
84+
85+
### LLVM Advanced Options
86+
87+
Clang and llc accept these flags directly, prefix them with `-mllvm ` to use them with Clang.
88+
89+
##### Code Generation
90+
91+
- `-ve-regalloc=0` disable the experimental improvements to the vector register allocator.
92+
- `-ve-fast-mem=0` use `VGT` (gather op) for masked loads instead of ignoring the mask.
93+
- `-ve-ignore-masks=0` do not ignore masks on arithmetic even if it's safe.
94+
- `-ve-optimize-split-avl=0` use the same VL setting for both non-packed operations when a packed operation is split.
95+
96+
97+
##### Cost Modelling
98+
99+
- `-ve-unroll-vector=0` discourage vector loop unrolling.
100+
- `-ve-expensive-vector=1` penalize vector ops to surpress all automatic vectorization.
101+
May help with VE Intrinsics to rule out spurious auto-vectorization.

‎README.md

Lines changed: 75 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,110 @@
1-
# LLVM for NEC SX-Aurora VE (llvm-ve-rv 1.8-dev)
1+
# The LLVM Compiler Infrastructure
22

3-
[![Build Status](https://travis-ci.com/sx-aurora-dev/llvm-project.svg?branch=hpce%2Fdevelop)](https://travis-ci.com/sx-aurora-dev/llvm-project)
3+
This directory and its sub-directories contain source code for LLVM,
4+
a toolkit for the construction of highly optimized compilers,
5+
optimizers, and run-time environments.
46

5-
This is a fork of the LLVM repositoy with support for the NEC
6-
SX-Aurora TSUBASA Vector Engine (VE).
7+
The README briefly describes how to get started with building LLVM.
8+
For more information on how to contribute to the LLVM project, please
9+
take a look at the
10+
[Contributing to LLVM](https://llvm.org/docs/Contributing.html) guide.
711

8-
### Features
12+
## Getting Started with the LLVM System
913

10-
- C, C++ support.
11-
- VE Intrinsics for low-level vector programming.
12-
- Packed-mode vector code generation by default.
13-
- Automatic vectorization through LLVM's loop and SLP vectorizers.
14-
- When combined with RV for SX-Aurora, provides user-guided (and some automatic)
15-
outer-loop vectorization through the Region Vectorizer.
16-
- Two OpenMP offloading modes: VE to VH and VH to VE.
14+
Taken from https://llvm.org/docs/GettingStarted.html.
1715

16+
### Overview
1817

19-
### Build instructions
18+
Welcome to the LLVM project!
2019

21-
To build llvm-ve from source refer to
22-
[llvm-dev](https://github.com/sx-aurora-dev/llvm-dev) and
23-
[Compile.rst](llvm/docs/VE/Compile.rst).
20+
The LLVM project has multiple components. The core of the project is
21+
itself called "LLVM". This contains all of the tools, libraries, and header
22+
files needed to process intermediate representations and converts it into
23+
object files. Tools include an assembler, disassembler, bitcode analyzer, and
24+
bitcode optimizer. It also contains basic regression tests.
2425

26+
C-like languages use the [Clang](http://clang.llvm.org/) front end. This
27+
component compiles C, C++, Objective-C, and Objective-C++ code into LLVM bitcode
28+
-- and from there into object files, using LLVM.
2529

26-
### General Usage
30+
Other components include:
31+
the [libc++ C++ standard library](https://libcxx.llvm.org),
32+
the [LLD linker](https://lld.llvm.org), and more.
2733

28-
To compile C/C++ code for the VE run Clang/Clang++ with the following command
29-
line:
34+
### Getting the Source Code and Building LLVM
3035

31-
$ clang -target ve-linux -O3 ...
36+
The LLVM Getting Started documentation may be out of date. The [Clang
37+
Getting Started](http://clang.llvm.org/get_started.html) page might have more
38+
accurate information.
3239

40+
This is an example work-flow and configuration to get and build the LLVM source:
3341

34-
### OpenMP offloading for/from SX-Aurora
42+
1. Checkout LLVM (including related sub-projects like Clang):
3543

36-
To compile with OpenMP offloading from VE to VH (VHCall) use:
44+
* ``git clone https://github.com/llvm/llvm-project.git``
3745

38-
$ clang -target ve-linux -fopenmp -fopenmp-targets=x86_64-pc-linux -O3 ...
46+
* Or, on windows, ``git clone --config core.autocrlf=false
47+
https://github.com/llvm/llvm-project.git``
3948

40-
To compile with OpenMP offloading from VH to VE (VEO) use:
49+
2. Configure and build LLVM and Clang:
4150

42-
$ clang -march=native -fopenmp -fopenmp-targets=ve-linux -O3 ...
51+
* ``cd llvm-project``
4352

53+
* ``mkdir build``
4454

45-
### Outer-loop Vectorization
55+
* ``cd build``
4656

47-
LLVM for SX-Aurora provides outer-loop vectorization, provided it is build with
48-
the Region Vectorizer. The following usage examples require an RV-enabled
49-
build.
57+
* ``cmake -G <generator> [options] ../llvm``
5058

51-
To use user-guided outer-loop vectorization with RV annotate the loops to
52-
vectorize with `#pragma omp simd` and use:
59+
Some common build system generators are:
5360

54-
$ clang -fopenmp-simd -mllvm -rv -O3 ...
61+
* ``Ninja`` --- for generating [Ninja](https://ninja-build.org)
62+
build files. Most llvm developers use Ninja.
63+
* ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
64+
* ``Visual Studio`` --- for generating Visual Studio projects and
65+
solutions.
66+
* ``Xcode`` --- for generating Xcode projects.
5567

56-
This release comes with a preview feature for automatic outer-loop vectorization
57-
with RV. This will work for some loops that use `int64_t` for their iteration
58-
variables (loop counters). To enable automatic outer-loop vectorization with RV
59-
use:
68+
Some Common options:
6069

61-
$ clang -mllvm -rv -mllvm -rv-autovec -O3 ...
70+
* ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
71+
sub-projects you'd like to additionally build. Can include any of: clang,
72+
clang-tools-extra, libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld,
73+
polly, or debuginfo-tests.
6274

75+
For example, to build LLVM, Clang, libcxx, and libcxxabi, use
76+
``-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"``.
6377

64-
### VE Intrinsics for direct vector programming
78+
* ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
79+
path name of where you want the LLVM tools and libraries to be installed
80+
(default ``/usr/local``).
6581

66-
See [the manual](https://sx-aurora-dev.github.io/velintrin.html).
67-
There is also [a tutorial](https://sx-aurora-dev.github.io/ve-intrinsics-tutorial/).
82+
* ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
83+
Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
6884

69-
### Clang Options
85+
* ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
86+
(default is Yes for Debug builds, No for all other build types).
7087

71-
Refer to the [Clang Command Line Reference](Ghttps://clang.llvm.org/docs/ClangCommandLineReference.html) for general compiler flags
72-
There are VE-specific flags to control vector code generation:
73-
Note that packed mode code generation and vectorization is enabled by default.
88+
* ``cmake --build . [-- [options] <target>]`` or your build system specified above
89+
directly.
7490

75-
- `clang -mno-vepacked` disables packed mode support.
76-
LLVM and the vectorizers will not use packed instructions.
77-
This option is incompatible with VE Intrinsics.
78-
- `clang -mno-vevpu` disables all vector code support.
79-
Disable vector code generation entirely.
80-
Vectorizers (of LLVM or RV) will keep all code scalar - no vector instructions will be generated.
81-
Incompatible with VE Intrinsics.
82-
- `clang -mvesimd` switches to the fixed SIMD legacy code generation path (deprecated).
91+
* The default target (i.e. ``ninja`` or ``make``) will build all of LLVM.
8392

93+
* The ``check-all`` target (i.e. ``ninja check-all``) will run the
94+
regression tests to ensure everything is in working order.
8495

85-
### LLVM Advanced Options
96+
* CMake will generate targets for each tool and library, and most
97+
LLVM sub-projects generate their own ``check-<project>`` target.
8698

87-
Clang and llc accept these flags directly, prefix them with `-mllvm ` to use them with Clang.
99+
* Running a serial build will be **slow**. To improve speed, try running a
100+
parallel build. That's done by default in Ninja; for ``make``, use the option
101+
``-j NNN``, where ``NNN`` is the number of parallel jobs, e.g. the number of
102+
CPUs you have.
88103

89-
##### Code Generation
104+
* For more information see [CMake](https://llvm.org/docs/CMake.html)
90105

91-
- `-ve-regalloc=0` disable the experimental improvements to the vector register allocator.
92-
- `-ve-fast-mem=0` use `VGT` (gather op) for masked loads instead of ignoring the mask.
93-
- `-ve-ignore-masks=0` do not ignore masks on arithmetic even if it's safe.
94-
- `-ve-optimize-split-avl=0` use the same VL setting for both non-packed operations when a packed operation is split.
95-
96-
97-
##### Cost Modelling
98-
99-
- `-ve-unroll-vector=0` discourage vector loop unrolling.
100-
- `-ve-expensive-vector=1` penalize vector ops to surpress all automatic vectorization.
101-
May help with VE Intrinsics to rule out spurious auto-vectorization.
106+
Consult the
107+
[Getting Started with LLVM](https://llvm.org/docs/GettingStarted.html#getting-started-with-llvm)
108+
page for detailed information on configuring and compiling LLVM. You can visit
109+
[Directory Layout](https://llvm.org/docs/GettingStarted.html#directory-layout)
110+
to learn about the layout of the source code tree.

0 commit comments

Comments
 (0)