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

Last change on this file since 3891 was 3891, checked in by matszpk, 14 months ago

CLRadeonExtender: Add info about building under FreeBSD. Add extra rpath when FreeBSD and gcc used.

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