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

Last change on this file since 3573 was 3573, checked in by matszpk, 3 years ago

CLRadeonExtender: Revert last changes in other docs.

File size: 4.4 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)
32* GNU make tool
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
45### Compilation
46
47To build system you should create a build directory in source code package:
48
49```
50mkdir build
51```
52
53and run:
54
55```
56cmake .. [cmake options]
57```
58
59Optional CMake configuration options for build:
60
61* CMAKE_BUILD_TYPE - type of build (Release, Debug, GCCSan, GCCSSP).
62* CMAKE_INSTALL_PREFIX - prefix for installation (for example '/usr/local')
63* BUILD_32BIT - build also 32-bit binaries
64* BUILD_TESTS - build all tests
65* BUILD_SAMPLES - build OpenCL samples
66* BUILD_DOCUMENTATION - build project documentation (doxygen, unix manuals, user doc)
67* BUILD_DOXYGEN - build doxygen documentation
68* BUILD_MANUAL - build Unix manual pages
69* BUILD_CLRXDOC - build CLRX user documentation
70* BUILD_STATIC_EXE - build with statically linked executables
71* GCC5CXX11NEWABI - build with new GCC5 C++11 ABI
72* NO_STATIC - no static libraries
73* NO_CLWRAPPER - do not build CLRXWrapper
74* CPU_ARCH - target CPU architecture (in GCC parameter to -march, for MSVC
75  parameter to /arch:)
76* OPENCL_DIST_DIR - an OpenCL directory distribution installation (optional)
77
78You can just add one or many of these options to cmake command:
79
80```
81cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
82```
83
84After creating Makefiles scripts you can compile project:
85
86`make` or `make -jX` - where X is number of processors.
87
88After building you can check whether project is working (if you will build tests):
89
90```
91ctest
92```
93
94Creating documentation will be done by this command
95(if you will enable a building documentation, required for version 0.1):
96
97```
98make Docs
99```
100
101### Installation
102
103Installation is easy. Just run command:
104
105```
106make install
107```
108
109### Usage of libraries in binaries
110
111The default (without '-gcc5' in name) binary libraries for Linux are compiled
112for C++11 old ABI, hence you must add option -D_GLIBCXX_USE_CXX11_ABI=0 to
113compiler commands if you are using GCC 5.0 or higher or compiler that by default
114uses new C++11 ABI.
115
116### Usage
117
118Usage of the clrxasm is easy:
119
120```
121clrxasm [-o outputFile] [options] [file ...]
122```
123
124If no file specified clrxasm read source from standard input.
125
126Useful options:
127
128* -g DEVICETYPE - device type ('pitcairn', 'bonaire'...)
129* -A ARCH - architecture ('gcn1.0', 'gcn1.1', 'gcn1.2' or 'gcn1.4')
130* -b BINFMT - binary format ('amd', 'amdcl2', 'gallium', 'rocm', 'rawcode')
131* -t VERSION - driver version for which a binary will be generated
132* -w - suppress warnings
133
134Usage of the clrxdisasm:
135
136```
137clrxdisasm [options] [file ...]
138```
139
140and clrxdisasm will print a disassembled code to standard output.
141
142Useful options for clrxdisasm:
143
144* -a - print everything (not only code, but also kernels and their metadatas)
145* -f - print floating points
146* -h - print hexadecimal instruction codes
147* -C - print configuration dump instead metadatas, CALnotes and setup data
148* -g DEVICETYPE - device type ('pitcairn', 'bonaire'...)
149* -A ARCH - architecture ('gcn1.0', 'gcn1.1', 'gcn1.2' or 'gcn1.4')
150* -t VERSION - driver version for which a binary will be generated
151
152A CLRX assembler accepts source from disassembler.
Note: See TracBrowser for help on using the repository browser.