source: CLRX/CLRadeonExtender/trunk/README.md @ 4652

Last change on this file since 4652 was 4650, checked in by matszpk, 9 months ago

CLRadeonExtender: Update README.md.

File size: 5.6 KB
Line 
1## CLRadeonExtender
2
3This is mirror of the CLRadeonExtender project.
4
5Original site is here [https://clrx.nativeboinc.org](https://clrx.nativeboinc.org) or
6[http://clrx.nativeboinc.org](http://clrx.nativeboinc.org)
7if SSL certificate doesn't work.
8
9CLRadeonExtender provides tools to develop software in low-level for the Radeon GPU's
10compatible with GCN 1.0/1.1/1.2/1.4 (AMD VEGA) architecture. Since version 0.1.8 also AMD VEGA
11Deep Learning extensions has been supported.
12Currently, this project have two tools to develop that software:
13
14* clrxasm - the GCN assembler
15* clrxdisasm - the GCN disassembler
16
17Both tools can operate on four binary formats:
18
19* the AMD Catalyst OpenCL program binaries
20* the GalliumCompute (Mesa) program binaries
21* the AMD Catalyst OpenCL 2.0 (new AMD format) program binaries
22* the ROCm (RadeonOpenCompute) program binaries
23
24CLRadeonExtender not only provides basic tools to low-level development, but also
25allow to embed own assembler with AMD Catalyst driver through CLwrapper.
26An embedded assembler can be called from `clBuildProgram` OpenCL call
27with specified option `-xasm`. Refer to README and INSTALL to learn about CLRXWrapper.
28
29### System requirements
30
31CLRadeonExtender requires:
32
33* C++11 compliant compiler (Clang++ or GCC 4.7 or later, MSVC 2015 or later)
34* any build system supported by CMake (GNU make, NMake, Visual Studio, ...)
35* CMake system (2.8 or later)
36* Threads support (for Linux, recommended NPTL)
37* Unix-like (Linux or BSD) system or Windows system
38
39Optionally, CLRXWrapper requires:
40
41* libOpenCL.so or OpenCL.dll
42* OpenCL headers
43* OpenGL headers (to 0.1.5 version)
44* OpenCL ICD (for example from AMD Catalyst driver)
45* AMD Catalyst driver or AMDGPU-PRO driver.
46
47and documentation requires:
48
49* pod2man utility for Unix manuals
50* markdown_py utility for CLRX Documentation
51* Doxygen for CLRX API Documentation
52
53### Compilation
54
55To build system you should create a build directory in source code package:
56
57```
58mkdir build
59```
60
61and run:
62
63```
64cmake .. [cmake options]
65```
66
67Optional CMake configuration options for build:
68
69* CMAKE_BUILD_TYPE - type of build (Release, Debug, GCCSan, GCCSSP).
70* CMAKE_INSTALL_PREFIX - prefix for installation (for example '/usr/local')
71* BUILD_32BIT - build 32-bit binaries (works only in the Unix/Linux 64-bit environment)
72* BUILD_TESTS - build all tests
73* BUILD_SAMPLES - build OpenCL samples
74* BUILD_DOCUMENTATION - build project documentation (doxygen, unix manuals, user doc)
75* BUILD_DOXYGEN - build doxygen documentation
76* BUILD_MANUAL - build Unix manual pages
77* BUILD_CLRXDOC - build CLRX user documentation
78* BUILD_STATIC_EXE - build with statically linked executables
79* GCC5CXX11NEWABI - build with new GCC5 C++11 ABI (required if GCC uses old ABI by default)
80* NO_STATIC - no static libraries
81* NO_CLWRAPPER - do not build CLRXWrapper
82* CPU_ARCH - target CPU architecture (in GCC parameter to -march, for MSVC
83  parameter to /arch:)
84* OPENCL_DIST_DIR - an OpenCL directory distribution installation (optional)
85
86You can just add one or many of these options to cmake command:
87
88```
89cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
90```
91
92or for Microsoft Visual C++ (for NMake):
93
94```
95cmake .. -G "NMake Makefiles" [cmake configuration options]
96```
97
98or for Microsoft Visual C++ (for same Visual Studio)
99
100```
101cmake .. -G "Visual Studio XXXXXX [arch]" [cmake configuration options]
102```
103
104where XXXX - version of Visual Studio (7, 14 2015, ...).
105arch - architecture (Win64, ARM)  (optional).
106
107After creating Makefiles scripts you can compile project:
108
109`make` or `make -jX` - where X is number of processors.
110
111or (for NMake)
112
113`nmake`
114
115or just execute build option in Visual Studio.
116
117After building you can check whether project is working (if you will build tests):
118
119```
120ctest
121```
122
123Creating documentation will be done by this command
124(if you will enable a building documentation, required for version 0.1):
125
126```
127make Docs
128```
129
130or (for NMake)
131
132```
133nmake Docs
134```
135
136#### FreeBSD
137
138Due to unknown reasons, the compilation under clang++ will be failed. We recommend to use
139gcc compiler to build the CLRadeonExtender. You should prepend cmake command by `CXX=g++`:
140`CXX=g++ cmake .. ....`.
141
142
143### Installation
144
145Installation is easy. Just run command:
146
147```
148make install
149```
150
151or (for NMake):
152
153```
154nmake install
155```
156
157### Usage of libraries in binaries
158
159The default (without '-gcc5' in name) binary libraries for Linux are compiled
160for C++11 old ABI, hence you must add option -D_GLIBCXX_USE_CXX11_ABI=0 to
161compiler commands if you are using GCC 5.0 or higher or compiler that by default
162uses new C++11 ABI.
163
164### Usage
165
166Usage of the clrxasm is easy:
167
168```
169clrxasm [-o outputFile] [options] [file ...]
170```
171
172If no file specified clrxasm read source from standard input.
173
174Useful options:
175
176* -g DEVICETYPE - device type ('pitcairn', 'bonaire'...)
177* -A ARCH - architecture ('gcn1.0', 'gcn1.1', 'gcn1.2' or 'gcn1.4')
178* -b BINFMT - binary format ('amd', 'amdcl2', 'gallium', 'rocm', 'rawcode')
179* -t VERSION - driver version for which a binary will be generated
180* -w - suppress warnings
181
182Usage of the clrxdisasm:
183
184```
185clrxdisasm [options] [file ...]
186```
187
188and clrxdisasm will print a disassembled code to standard output.
189
190Useful options for clrxdisasm:
191
192* -a - print everything (not only code, but also kernels and their metadatas)
193* -f - print floating points
194* -h - print hexadecimal instruction codes
195* -C - print configuration dump instead metadatas, CALnotes and setup data
196* -g DEVICETYPE - device type ('pitcairn', 'bonaire'...)
197* -A ARCH - architecture ('gcn1.0', 'gcn1.1', 'gcn1.2' or 'gcn1.4')
198* -t VERSION - driver version for which a binary will be generated
199
200A CLRX assembler accepts source from disassembler.
Note: See TracBrowser for help on using the repository browser.