PL-4051, An Introduction to SPIR for OpenCL Application Developers and Compiler Developers, by Yaxun Liu

Introduction to SPIR for
Application and Compiler
Developers

Yaxun Sam Liu

OUTLINE
y What is SPIR and why it is useful
‒ Why do we need SPIR since we already have LLVM IR

y SPIR for Application Developers
‒ How to generate SPIR
‒ How to load SPIR
‒ Portability considerations using SPIR

y SPIR for Compiler Developers
‒ Introduction to SPIR spec
‒ How to implement a SPIR loader

y References

2 | INTRODUCTION TO SPIR FOR APPLICATION DEVELOPERS AND COMPILER DEVELOPERS | November 5, 2013

WHAT IS SPIR
y A Binary Format
‒ SPIR means Standard Portable Intermediate Representation
‒ A portable binary format for OpenCLTM programs
‒ Defined by SPIR spec
‒ Based on LLVM IR
‒ Supports most of OpenCLTM core features
‒ Current version is 1.2, corresponding to OpenCLTM 1.2
‒ Developed by Khronos Group, OpenCLTM working group, SPIR subgroup
‒ A SPIR binary is bitness aware, means
‒ The pointer size in a SPIR binary is either 32 bit or 64 bit depending on target devices
‒ Two sets of SPIR binaries are needed for shipping products in SPIR to both 32 and 64 bit devices

y An extension for OpenCLTM
‒ Defined by SPIR host API
‒ Denoted by cl_khr_spir
‒ OpenCLTM devices supporting cl_khr_spir is able to load SPIR binary and run it

WHY IS SPIR USEFUL
y Why is SPIR useful
‒ For Game/Application Developers
‒ Can ship OpenCLTM program in binary instead of source code
‒ Can ship just a few binaries for one OpenCLTM program instead of tons of binaries for different platforms/devices

‒ For Compiler Developers
‒ Can compile other programming languages to SPIR which can be run on OpenCLTM devices


HOW TO GENERATE SPIR
y SPIR generation is optional for devices supporting cl_khr_spir
‒ A device supporting cl_khr_spir is only required to be able to consume SPIR
‒ Whether to support SPIR generation is vendors’ choice

y Generating SPIR in host program
‒ SPIR spec and host API does not define how to generate SPIR
‒ If SPIR generation is supported, it is likely to be done as
‒
‒
‒
‒

Load OpenCLTM source code by clCreateProgramWithSource
Compile OpenCLTM source code by clCompileProgram with a vendor specific option for generating SPIR
Get the SPIR binary by clGetProgramInfo with CL_PROGRAM_BINARIES
Save the SPIR binary to a file

y Generating SPIR by offline compiler
‒ Clang 3.3/3.4 can compile OpenCLTM source code to SPIR-like LLVM bitcode
‒ A patch for Clang 3.2 is available to Khronos members which can compile OpenCLTM source code to SPIR 1.2
‒ Clang options for generating SPIR: -cl-std=CL1.2 -emit-llvm -triple spir[32|64]-unknown-unknown

HOW TO LOAD SPIR
LOAD A SINGLE SPIR BINARY
SPIR Binary
clCreateProgramWithBinary
cl_program
clBuildProgram
cl_program
clCreateKernel
cl_kernel


HOW TO LOAD SPIR
MULTIPLE SPIR BINARIES, OPENCLTM SOURCE CODES AND VENDOR-SPECIFIC BINARIES
OpenCLTM Source

SPIR Binary

Vendor-specific Binary

clCreateProgramWithSource



cl_program

cl_program

cl_program

clCompileProgram

clCompileProgram

cl_program

cl_program
clLinkProgram
cl_program
clCreateKernel
cl_kernel


PORTABILITY CONSIDERATIONS USING SPIR
y Check whether a device supports SPIR
‒ Get all supported extensions by clGetDeviceInfo with CL_DEVICE_EXTENSIONS
‒ Check whether cl_khr_spir is included

y Supporting both 32 and 64 bit devices
‒ Two sets of SPIR binaries are needed, one for 32 bit devices, the other for 64 bit devices
‒ Check bitness of a device by clGetDeviceInfo with CL_DEVICE_ADDRESS_BITS
‒ Load 32 or 64 bit SPIR binaries accordingly

y Supporting optional extensions
‒ Get all supported extensions by clGetDeviceInfo with CL_DEVICE_EXTENSIONS
‒ Check if the required extension is supported
‒ If yes, load the SPIR binary
‒ If no, either fallback to a SPIR binary or OpenCLTM source using only core extensions, or fail gracefully


PORTABILITY CONSIDERATIONS USING SPIR
y SPIR binaries generated from non-portable OpenCLTM source is not portable
‒ Not following restrictions specified by OpenCLTM spec 1.2 section 6.9
‒ Casting a pointer from one address space to a different address space
‒ Casting an OpenCLTM opaque structure to a different type
‒ Performing arithmetic operations or comparison on a sampler
‒ Performing sizeof on OpenCLTM opaque structures
‒ etc.


SPIR FOR COMPILER DEVELOPERS
y Introduction to SPIR spec
‒ Relation between SPIR 1.2 and LLVM 3.2
‒ Mapping of OpenCLTM to SPIR
‒
‒
‒
‒
‒
‒
‒

Data types
Enumeration values
Calling conventions
Address spaces
Name mangling
Used extensions
Kernel argument info

y How to implement a SPIR loader
‒ Overall structure
‒ Transforming data types
‒ Transforming meta data
‒ Demangling and mapping builtin function names

RELATION BETWEEN SPIR AND LLVM BITCODE
y SPIR binary is subset of LLVM bitcode
‒ A valid SPIR 1.2 binary is valid LLVM 3.2 bitcode
‒ SPIR is defined by mapping OpenCLTM C entities to LLVM and also imposing restrictions on LLVM 3.2 bitcode format
‒
‒
‒
‒

Specific target triple and data layout for 32 and 64 bit devices
Specific ABI
Specific calling conventions
Restrictions on allowed instructions, intrinsic functions, linkage types, parameter attributes, visibility styles, function
attributes, etc.

y The ideas behind SPIR
‒ To be expressive enough to represent OpenCLTM C programs
‒ To carry enough information for OpenCLTM runtime to execute and query the kernels
‒ Do not introduce unnecessary entities
‒ This may limit SPIR’s expressiveness for other languages, but facilitates development of SPIR loader
‒ Balance the burden between SPIR producer and loader


MAPPING OF OPENCLTM TO SPIR
DATA TYPES

y OpenCLTM builtin scalar types are mapped to LLVM primitive types
‒ bool -> i1
‒ char -> i8
‒ unsigned char, uchar -> i8
‒ short -> i16
‒ unsigned short, ushort -> i16
‒ int -> i32
‒ unsigned int, uint -> i32
‒ long -> i64
‒ unsigned long, ulong -> i64
‒ float -> float
‒ double -> double
‒ half -> half
‒ void -> void

y OpenCLTM builtin vector types are mapped to LLVM vector types
‒ charn < n x i8 >


DATA TYPES

y Image and event types are mapped to LLVM opaque structure
‒ image1d_t -> %opencl.image1d_t
‒ image1d_array_t -> %opencl.image1d_array_t
‒ image1d_buer_t -> %opencl.image1d_buer_t
‒ image2d_array_t -> %opencl.image2d_array_t
‒ image2d_msaa_t -> %opencl.image2d_msaa_t
‒ image2d_array_msaa_t -> %opencl.image2d_array_msaa_t
‒ image2d_msaa_depth_t -> %opencl.image2d_msaa_depth_t
‒ image2d_array_msaa_depth_t -> %opencl.image2d_array_msaa_depth_t
‒ image2d_depth_t -> %opencl.image2d_depth_t
‒ image2d_array_depth_t -> %opencl.image2d_array_depth_t
‒ event_t -> %opencl.event_t


DATA TYPES

y Sampler type is mapped to LLVM i32 type
‒ Although sampler is represented by integer in SPIR, arithmetic operations and comparison with other values are not
allowed.

y size_t, diffptr_t, intptr_t, uintptr_t is mapped to LLVM i32 or i64 depending on the bitness of SPIR
y Signed/unsignedness of integer types
‒ LLVM does not have unsigned integer types
‒ OpenCLTM unsigned and signed integer types of the same bit width are mapped to the same type in SPIR
‒ If signed/unsignedness of an integer type is needed, usually the information can be obtained through
‒ Mangled function names
‒ Sign extension of function arguments and return type
‒ Kernel argument metadata


CALLING CONVENTIONS

y SPIR uses calling convention to indicate whether a function is a kernel function
‒ Kernel functions use spir_kernel calling convention
‒ Non-kernel functions use spir_func calling convention
‒ No other calling conventions are allowed in SPIR


ADDRESS SPACES

y OpenCLTM C address spaces are mapped to LLVM address spaces
‒ Private -> 0
‒ Global -> 1
‒ Constant -> 2
‒ Local -> 3

y Casting a pointer to a different address space is not allowed
y OpenCLTM C function-level local variables are mapped to LLVM module scope global variables
‒ The variable name is mapped as <function name>.<variable name>


ENUMERATION VALUES

y SPIR defines enumeration values used by OpenCLTM C programs
‒ Image channel order -> same as cl.h
‒ Image data type -> same as cl.h
‒ Sampler enumeration values (based on cl.h but not exactly the same)
‒ Addressing mode
‒ CLK_ADDRESS_NONE=0x0000
‒ CLK_ADDRESS_CLAMP_TO_EDGE=0x0002
‒ CLK_ADDRESS_CLAMP=0x0004
‒ CLK_ADDRESS_REPEAT=0x0006
‒ CLK_ADDRESS_MIRRORED_REPEAT=0x0008

‒ Normalized coords
‒ CLK_NORMALIZED_COORDS_FALSE=0x0000
‒ CLK_NORMALIZED_COORDS_TRUE=0x0001

‒ Filter mode
‒ CLK_FILTER_NEAREST=0x0010
‒ CLK_FILTER_LINEAR=_0x0020


NAME MANGLING

y OpenCLTM C builtin functions are mangled
y OpenCLTM C kernel functions and non-kernel user functions are not mangled
y Other languages may choose to mangle non-kernel user functions
y SPIR adopts name mangling scheme of Itanium C++ ABI section 5.1 with extended rules for OpenCLTM C
data types, address spaces, access qualifiers
‒ Unsigned/signed integer types of the same bit widths are mangled to different names
‒ Pointers of non-private address space N -> PU3ASN<mangled element type>
‒ Vector type of N elements -> DvN_<mangled element type>
‒ OpenCLTM C opaque types (image, sampler, event) -> <string length>ocl_<type name> e.g.
‒ sampler_t -> 11ocl_sampler

‒ Access qualifiers: read only -> U1R, write only -> U1W, read write -> U1B
‒ size_t and uintptr_t are treated as uint or ulong
‒ Ptrdiff_t and intptr_t are treated as int or long


USE OF OPTIONAL CORE FEATURES AND EXTENSIONS

y SPIR contains information about used optional features and extensions
‒ Runtime can reject SPIR binaries using unsupported optional features
‒ Application can select SPIR binaries based on used optional features and extensions

y Metadata for used core features
‒ openclTM.used.optional.core.features
‒ Two core features are allowed:
‒ cl_image: indicates images are used
‒ cl_double: indicates doubles are used

y Metadata for used extensions
‒ openclTM.used.extensions
‒
‒
‒
‒
‒
‒

cl_khr_int64_base_atomics
cl_khr_int64_extended_atomics
cl_khr_fp16
cl_khr_gl_sharing
cl_khr_gl_event
etc


KERNEL ATTRIBUTES

y SPIR contains information about optional kernel attributes
‒ Reqd_work_group_size
‒ Work_group_size_hint
‒ Vec_type_hint

y For each kernel, there is a metadata for optional kernel attributes
‒ !opencl.kernels = {!0, !1, ..., !N}
‒
‒
‒
‒

!0 = metadata { < function signature >, !01, !02, ..., , !0i }
!1 = metadata { < function signature >, !11, !12, ..., , !1j }
...
!N = metadata { < function signature >, !N1, !N2, ..., , !Nk }


KERNEL ARGUMENT INFO

y SPIR contains kernel argument information required by OpenCLTM runtime for executing kernels
y For each kernel argument, there is metadata
‒ kernel_arg_addr_space
‒ kernel_arg_access_qual
‒ kernel_arg_type
‒ kernel_arg_base_type
‒ kernel_arg_type_qual
‒ kernel_arg_name : optional, only exists if -cl-kernel-arg-info is used when producing SPIR


SPIR ABI
y SPIR uses the default ABI of Clang 3.2
‒ Any aggregate type is passed as a pointer. Memory allocation (if needed) is the responsibility of the caller function.
‒ Enumeration types are handled as the underlying integer type.
‒ If the argument type is a promotable integer type, it will be extended according to the C99 integer promotion rules.
‒ Any other type, including floating point types, vectors, etc.. will be passed directly as the corresponding LLVM type.


HOW TO IMPLEMENT SPIR LOADER
OVERALL STRUCTURE – IDEAL CASE
User’s OpenCLTM Source

User’s SPIR Binary

Builtin Library Source

compile

compile

SPIR Binary

SPIR Binary

Optimize, link
Linked SPIR Binary
Optimize, codegen
Executable Kernels

y Backend consumes SPIR directly without transforming to vendor’s LLVM format

OVERALL STRUCTURE – ACTUAL CASE
User’s OpenCLTM Source

User’s SPIR Binary

Builtin Library Source

compile

SPIR loader

compile

Vendor’s LLVM Binary



Optimize, link
Vendor’s Linked Binary
Optimize, codegen
Executable Kernels

y Backend transforms SPIR to vendor’s LLVM format

WHY IS SPIR LOADER NEEDED
y Vendor uses different LLVM entities or format to convey information required by OpenCLTM runtime for
querying and executing kernels
y Vendor’s frontend does special transformations which are not done by SPIR producer
y Vendor’s backend is shared by different frontends, some of which do not generate SPIR
y Vendor’s builtin library uses different name mangling scheme


y Verify SPIR target triple and data layout is compatible with target device
y Set target triple for target device
y Demangle builtin functions and re-mangle them using vendor’s name mangling scheme
y Transform data types
y Transform metadata
y Transform calling conventions
y Perform special transformations done by frontend
‒ If possible, consider moving the transformations from frontend to backend


SPIR CONFORMANCE TEST
y SPIR is a Khronos extension
y To claim supporting SPIR, vendor’s OpenCLTM implementation needs to pass SPIR conformance test
y SPIR 1.2 conformance test is going to be part of OpenCLTM 1.2 conformance test


REFERENCES
y Khronos OpenCLTM Working Group SPIR subgroup, SPIR provisional spec http://www.khronos.org/files/
opencl-spir-12-provisional.pdf, version 1.2.
y LLVM Team. LLVM Bitcode File Format. http://www.llvm.org/releases/3.2/docs/BitCodeFormat.html,
2012. Version 3.2.
y CodeSourcery, Compaq, EDG, HP, IBM, Intel, Red Hat, SGI, and others. Itanium C++ ABI. http://
mentorembedded.github.com/cxx-abi/abi.html .
y Khronos OpenCLTM Working Group. The OpenCLTM Specication, version 1.2. http://www.khronos.org/
registry/cl/specs/opencl-1.2.pdf, November 2012.
y LLVM Team. LLVM Language Reference Manual. http://www.llvm.org/releases/3.2/docs/LangRef.html ,
2012. Version 3.2.


DISCLAIMER & ATTRIBUTION
The information presented in this document is for informational purposes only and may contain technical inaccuracies, omissions and typographical errors.
The information contained herein is subject to change and may be rendered inaccurate for many reasons, including but not limited to product and roadmap
changes, component and motherboard version changes, new model and/or product releases, product differences between differing manufacturers,
software changes, BIOS flashes, firmware upgrades, or the like. AMD assumes no obligation to update or otherwise correct or revise this information.
However, AMD reserves the right to revise this information and to make changes from time to time to the content hereof without obligation of AMD to
notify any person of such revisions or changes.
AMD MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND ASSUMES NO RESPONSIBILITY FOR ANY
INACCURACIES, ERRORS OR OMISSIONS THAT MAY APPEAR IN THIS INFORMATION.
AMD SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT WILL AMD
BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL OR OTHER CONSEQUENTIAL DAMAGES ARISING FROM THE USE OF ANY INFORMATION
CONTAINED HEREIN, EVEN IF AMD IS EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

ATTRIBUTION
© 2013 Advanced Micro Devices, Inc. All rights reserved. AMD, the AMD Arrow logo and combinations thereof are trademarks of Advanced Micro Devices,
Inc. in the United States and/or other jurisdictions. OpenCLTM is a trademark of Apple Inc. Other names are for informational purposes only and may be
trademarks of their respective owners.

PL-4051, An Introduction to SPIR for OpenCL Application Developers and Compiler Developers, by Yaxun Liu

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (20)

Similar a PL-4051, An Introduction to SPIR for OpenCL Application Developers and Compiler Developers, by Yaxun Liu

Similar a PL-4051, An Introduction to SPIR for OpenCL Application Developers and Compiler Developers, by Yaxun Liu (20)

Más de AMD Developer Central

Más de AMD Developer Central (20)

Último

Último (20)

PL-4051, An Introduction to SPIR for OpenCL Application Developers and Compiler Developers, by Yaxun Liu