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

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

CLRadeonExtender: Update README and INSTALL: add info about needed tools to build documentation.

File size: 5.1 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
135### Installation
136
137Installation is easy. Just run command:
138
139```
140make install
141```
142
143or (for NMake):
144
145```
146nmake install
147```
148
149### Usage of libraries in binaries
150
151The default (without '-gcc5' in name) binary libraries for Linux are compiled
152for C++11 old ABI, hence you must add option -D_GLIBCXX_USE_CXX11_ABI=0 to
153compiler commands if you are using GCC 5.0 or higher or compiler that by default
154uses new C++11 ABI.
155
156### Usage
157
158Usage of the clrxasm is easy:
159
160```
161clrxasm [-o outputFile] [options] [file ...]
162```
163
164If no file specified clrxasm read source from standard input.
165
166Useful options:
167
168* -g DEVICETYPE - device type ('pitcairn', 'bonaire'...)
169* -A ARCH - architecture ('gcn1.0', 'gcn1.1', 'gcn1.2' or 'gcn1.4')
170* -b BINFMT - binary format ('amd', 'amdcl2', 'gallium', 'rocm', 'rawcode')
171* -t VERSION - driver version for which a binary will be generated
172* -w - suppress warnings
173
174Usage of the clrxdisasm:
175
176```
177clrxdisasm [options] [file ...]
178```
179
180and clrxdisasm will print a disassembled code to standard output.
181
182Useful options for clrxdisasm:
183
184* -a - print everything (not only code, but also kernels and their metadatas)
185* -f - print floating points
186* -h - print hexadecimal instruction codes
187* -C - print configuration dump instead metadatas, CALnotes and setup data
188* -g DEVICETYPE - device type ('pitcairn', 'bonaire'...)
189* -A ARCH - architecture ('gcn1.0', 'gcn1.1', 'gcn1.2' or 'gcn1.4')
190* -t VERSION - driver version for which a binary will be generated
191
192A CLRX assembler accepts source from disassembler.
Note: See TracBrowser for help on using the repository browser.