Readme.md
1<!---======================= begin_copyright_notice ============================
2
3Copyright (C) 2020-2021 Intel Corporation
4
5SPDX-License-Identifier: MIT
6
7============================= end_copyright_notice ==========================-->
8
9# VC Intrinsics
10
11## Introduction
12
13VC Intrinsics project contains a set of new intrinsics on top of core
14LLVM IR instructions that represent SIMD semantics of a program
15targeting GPU. This set is now used by
16
17* CMC - https://github.com/intel/cm-compiler
18* DPC++ - https://github.com/intel/llvm
19* ISPC - https://github.com/ispc/ispc
20
21frontend compilers and
22
23* IGC VC backend - https://github.com/intel/intel-graphics-compiler
24
25## License
26
27VC Intrinsics are distributed under the MIT license.
28
29You may obtain a copy of the License at:
30
31https://opensource.org/licenses/MIT
32
33## Dependencies
34
35### Source code
36
37* LLVM Project - https://github.com/llvm/llvm-project
38
39### Tools
40
41To build libraries:
42
43* CMake - https://cmake.org/ - 3.13.4 or later
44* Python - https://www.python.org/ - 2.7 or later
45* C++ compiler - anything that can compile LLVM
46
47To build documentation:
48
49* Sphinx - https://www.sphinx-doc.org - 1.5 or later
50* GNU Make - https://www.gnu.org/software/make/ - 3.79 or later
51* Standard Unix utilities (mkdir, rm, sed)
52
53## Building
54
55VC Intrinsics can be built in two major modes: in-tree and
56external. All major LLVM versions starting from LLVM 8 are supported.
57
58LLVM ToT can be used too, but there is no guarantee that it will
59always work (because of sudden breaking changes in LLVM C++
60API). However, maintainers are trying to fix such issues as fast as
61possible.
62
63### In-tree build
64
65For in-tree build VC Intrinsics can be considered as an external LLVM
66project. Put VC Intrinsics source directory inside `llvm/projects`
67directory or add `-DLLVM_EXTERNAL_PROJECTS="vc-intrinsics"
68-DLLVM_EXTERNAL_VC_INTRINSICS_SOURCE_DIR=<vc-intrinsics>` to cmake
69command arguments when configuring LLVM.
70
71### External build
72
73To configure VC Intrinsics with prebuilt LLVM run cmake as follows:
74
75```shell
76$ cmake -DLLVM_DIR=<llvm install>/lib/cmake/llvm <vc-intrinsics>
77```
78
79### Documentation
80
81VC Intrinsics documentation is inside `docs` subdirectory and can be
82built using Sphinx. To build html version do the following:
83
84```shell
85$ cd docs
86$ make -f Makefile.sphinx html
87```
88
89This will extract comments from main intrinsics description and
90generate readable html output in `_build/html` subdirectory.
91
92## Testing
93
94VC Intrinsics repository contains lit tests that are enabled when
95`-DVC_INTR_ENABLE_LIT_TESTS=ON` is passed to cmake command. Lit tests
96use LLVM plugins and currently are supported only with dynamic LLVM
97(when LLVM is configured with `-DLLVM_LINK_LLVM_DYLIB=ON`). In
98external build path to `lit` utility should be specified as follows:
99`-DLLVM_EXTERNAL_LIT=<lit>`. Full example with external build:
100
101```shell
102$ cmake -DLLVM_DIR=<llvm install>/lib/cmake/llvm -DVC_INTR_ENABLE_LIT_TESTS=ON -DLLVM_EXTERNAL_LIT=<lit> <vc-intrinsics>
103```
104
105Target `check-vc-intrinsics` will run lit tests.
106
107## How to provide feedback
108
109Please submit an issue using native github.com interface:
110https://github.com/intel/vc-intrinsics/issues.
111
112## How to contribute
113
114Create a pull request on github.com with your patch. A maintainer
115will contact you if there are questions or concerns.
116