From ae81146538cea205c1463c0035f13cd67d3ee44d Mon Sep 17 00:00:00 2001 From: Brian Sumner Date: Thu, 21 Mar 2019 16:04:11 -0700 Subject: [PATCH] Update readme Change-Id: I43f6662545e75c18c8312f1c4e69eacb334f6589 --- README.md | 58 ++++++++++++++++++++++++++----------------------------- 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 16c55c77..dbb50bd5 100644 --- a/README.md +++ b/README.md @@ -2,26 +2,25 @@ ROCm Device libraries. -This repository contains the following libraries: +This repository contains the sources and CMake build system for a +set of AMD specific device-side language runtime libraries. Specifically: | **Name** | **Comments** | **Dependencies** | | --- | --- | --- | -| irif | Internal interface to LLVM IR | | -| ocml | Open Compute Math library ([documentation](doc/OCML.md)) | irif | -| oclc | Open Compute library controls ([documentation](doc/OCML.md#controls)) | | -| ockl | Open Compute Kernel library. | irif | -| opencl | OpenCL built-in library | ocml, ockl | -| hc | Heterogeneous Compute built-in library | ocml, ockl | - -All libraries are compiled to LLVM Bitcode which can be linked. Note that libraries use specific AMDGPU intrinsics. +| oclc* | Open Compute library controls ([documentation](doc/OCML.md#controls)) | | +| ocml | Open Compute Math library ([documentation](doc/OCML.md)) | oclc* | +| ockl | Open Compute Kernel library ([documentation](doc/OCKL.md)) | oclc* | +| opencl | OpenCL built-in library | ocml, ockl, oclc* | +| hip | HIP built-in library | ocml, ockl, oclc* | +| hc | Heterogeneous Compute built-in library | ocml, ockl, oclc* | Refer to [LICENSE.TXT](LICENSE.TXT) for license information. ## BUILDING -To build it, use RadeonOpenCompute LLVM/LLD/Clang. Default branch on these -repositories is "amd-common", which may contain AMD-specific codes yet -upstreamed. +The library sources should be compiled using a clang compiler built from +sources in the amd-common branch of AMD modified clang, llvm, and lld repositories +using the following commands: git clone git@github.com:RadeonOpenCompute/llvm.git llvm_amd-common cd llvm_amd-common/tools @@ -36,20 +35,18 @@ upstreamed. -DLLVM_TARGETS_TO_BUILD="AMDGPU;X86" \ .. -Testing also requires amdhsacod utility from ROCm Runtime. - -Use out-of-source CMake build and create separate directory to run CMake. -The following build steps are performed: +To build the library bitcodes, from the top level of this repository +run the following commands: mkdir -p build cd build - export LLVM_BUILD=... (path to LLVM build) + export LLVM_BUILD=... (path to LLVM build directory created above) CC=$LLVM_BUILD/bin/clang cmake -DLLVM_DIR=$LLVM_BUILD .. make -It is also possible to use compiler that only has AMDGPU target enabled if you build prepare-builtins separately -with host compiler and pass explicit target option to CMake: +It is also possible to use a compiler that only has AMDGPU target enabled if you build prepare-builtins separately +with the regular host compiler and pass explicit target option to CMake: export LLVM_BUILD=... (path to LLVM build) # Build prepare-builtins @@ -62,7 +59,9 @@ with host compiler and pass explicit target option to CMake: cd ../.. mkdir build cd build - CC=$LLVM_BUILD/bin/clang cmake -DLLVM_DIR=$LLVM_BUILD -DCMAKE_C_FLAGS="-target amdgcn--amdhsa" -DCMAKE_CXX_FLAGS="-target amdgcn--amdhsa" -DPREPARE_BUILTINS=`cd ../utils/build/prepare-builtins/; pwd`/prepare-builtins .. + CC=$LLVM_BUILD/bin/clang cmake -DLLVM_DIR=$LLVM_BUILD -DPREPARE_BUILTINS=`cd ../utils/build/prepare-builtins/; pwd`/prepare-builtins .. + +Testing requires the amdhsacod utility from ROCm Runtime. To install artifacts: make install @@ -74,17 +73,14 @@ To create packages for the library: make package ## USING BITCODE LIBRARIES - -The bitcode libraries should be linked to user bitcode (obtained from source) *before* final code generation -with llvm-link or -mlink-builtin-bitcode, or -mlink-bitcode-file options of clang. - -For OpenCL, the list of bitcode libraries includes opencl, its dependencies (ocml, ockl) -and oclc control libraries selected according to OpenCL compilation mode. Assuming that the build -of this repository was done in /srv/git/ROCm-Device-Libs/build, the following command line -shows how to compile simple OpenCL source test.cl into code object test.so: - - clang -x cl -Xclang -finclude-default-header \ - -target amdgcn--amdhsa -mcpu=fiji \ + +The ROCm language runtimes automatically add the required bitcode files during the +LLVM linking stage invoked during the process of creating a code object. There are options +to display the exact commands executed, but an approximation of the command the OpenCL +runtime might use is as follows: + + $LLVM_BUILD/bin/clang -x cl -Xclang -finclude-default-header \ + -target amdgcn-amd-amdhsa -mcpu=gfx803 \ -Xclang -mlink-bitcode-file -Xclang /srv/git/ROCm-Device-Libs/build/opencl/opencl.amdgcn.bc \ -Xclang -mlink-bitcode-file -Xclang /srv/git/ROCm-Device-Libs/build/ocml/ocml.amdgcn.bc \ -Xclang -mlink-bitcode-file -Xclang /srv/git/ROCm-Device-Libs/build/ockl/ockl.amdgcn.bc \