ext/cl_khr_spir.asciidoc

// Copyright 2017-2024 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[cl_khr_spir]]
== Standard Portable Intermediate Representation Binaries

This extension adds the ability to create an OpenCL program object from a
Standard Portable Intermediate Representation (SPIR) instance.
A SPIR instance is a vendor-neutral non-source representation for OpenCL C
programs.

The extension name is *cl_khr_spir*.
This extension has been superseded by the SPIR-V intermediate
representation, which is supported by the *cl_khr_il_program* extension,
and is a core feature in OpenCL 2.1.

=== General Information

==== Version History

[cols="1,1,3",options="header",]
|====
| *Date*     | *Version* | *Description*
| 2020-04-21 | 1.0.0     | First assigned version.
|====

[[cl_khr_spir-additions-to-chapter-4]]
=== Additions to Chapter 4 of the OpenCL 2.2 Specification

*Add a new device property to _table 4.3_ in _section 4.2_:*

.List of supported param_names by {clGetDeviceInfo}
[cols="2,1,4",options="header",]
|====
| Device Info
| Return Type
| Description

| {CL_DEVICE_SPIR_VERSIONS}
| {char_TYPE}[]
| A space separated list of SPIR versions supported by the device.

  For example, returning `"1.2"` in this query implies that SPIR version 1.2
  is supported by the implementation.

|====

[[cl_khr_spir-additions-to-chapter-5]]
=== Additions to Chapter 5 of the OpenCL 2.2 Specification

*Additions to _section 5.8.1_ -- Creating Program Objects:*

"{clCreateProgramWithBinary} can be used to load a SPIR binary.
Once a program object has been created from a SPIR binary, {clBuildProgram}
can be called to build a program executable or {clCompileProgram} can be
called to compile the SPIR binary."

Modify the {CL_PROGRAM_BINARY_TYPE} entry in _table 5.14_
for {clGetProgramBuildInfo} to add a potential value
{CL_PROGRAM_BINARY_TYPE_INTERMEDIATE}:

.List of supported param_names by {clGetProgramBuildInfo}
[cols="2,1,4",options="header",]
|====
| Program Build Info
| Return Type
| Description

| {CL_PROGRAM_BINARY_TYPE}
| {cl_program_binary_type_TYPE}
| {CL_PROGRAM_BINARY_TYPE_INTERMEDIATE} -- An intermediate (non-source)
  representation for the program is loaded as a binary.
  The program must be further processed with {clCompileProgram} or
  {clBuildProgram}.

  If processed with {clCompileProgram}, the result will be a binary of type
  {CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT} or {CL_PROGRAM_BINARY_TYPE_LIBRARY}.
  If processed with {clBuildProgram}, the result will be a binary of type
  {CL_PROGRAM_BINARY_TYPE_EXECUTABLE}.

|====

*Additions to _section 5.8.4_ -- Compiler Options:*

"The compile option `-x spir` must be specified to indicate that the binary
is in SPIR format, and the compile option `-spir-std` must be used to
specify the version of the SPIR specification that describes the format and
meaning of the binary.
For example, if the binary is as described in SPIR version 1.2, then
`-spir-std=1.2` must be specified.
Failing to specify these compile options may result in implementation-defined
behavior."

*Additions to _section 5.8.5_ -- Separate Compilation and Linking of Programs:*

Replace this error for {clCompileProgram}:

  * {CL_INVALID_OPERATION} if _program_ has no source or IL available, i.e. it
    has not been created with {clCreateProgramWithSource} or
    {clCreateProgramWithIL}.

with:

  * {CL_INVALID_OPERATION} if _program_ has no source or IL available, i.e. it
    has not been created with {clCreateProgramWithSource} or
    {clCreateProgramWithIL} or {clCreateProgramWithBinary} where `-x spir` is present in _options_.

*Additions to _section 5.9.3_ -- Kernel Object Queries:*

Modify following text in {clGetKernelArgInfo} from:

"Kernel argument information is only available if the program object
associated with _kernel_ is created with {clCreateProgramWithSource} and the
program executable is built with the -cl-kernel-arg-info option specified in
_options_ argument to {clBuildProgram} or {clCompileProgram}."

to:

"Kernel argument information is only available if the program object
associated with _kernel_ is created with {clCreateProgramWithSource} and the
program executable is built with the `-cl-kernel-arg-info option` specified in
_options_ argument to {clBuildProgram} or {clCompileProgram}, or if the
program object associated with _kernel_ is created with
{clCreateProgramWithBinary} and the program executable is built with the
`-cl-kernel-arg-info` and `-x spir` options specified in _options_ argument to
{clBuildProgram} or {clCompileProgram}."