Skip to content

Commit

Permalink
Builtin function precision is backend specific
Browse files Browse the repository at this point in the history
Resolve conflicting wording about the precision requirements of the
builtin math functions.  The introductory paragraph of section 4.17
"SYCL built-in functions for SYCL host and device" says that the
precision is defined by the backend.  However, the descriptions in
section 4.17.4 "Math functions" and 4.17.6 "Half precision math
functions" specified a required precision for all backends.  Resolve
this by removing the the wording in 4.17.4 and 4.17.6.  (See issue KhronosGroup#507
for more on this.)

Also add a new section to the OpenCL backend specification stating that
the precision of these builtin math functions for the OpenCL backend
matches the precision of the corresponding functions in the OpenCL
specification.

There are a few other related changes in this PR:

* Clarify that the native precision and half precision functions are
  available in both host and device code (see issue KhronosGroup#509).

* Remove a statement that the geometric functions use round to nearest
  even rounding mode.  This also seems backend specific, and it doesn't
  even make sense for the OpenCL backend.  See OpenCL issue
  OpenCL-Docs#1024 for more details on this.

* Editorial changes to remove gratuitous references to OpenCL in the
  introductory paragraphs.

* Editorial changes to make the introductions of sections 4.17.4 -
  4.17.10 read consistently.
  • Loading branch information
gmlueck committed Nov 30, 2023
1 parent 8fa7715 commit 4005c57
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 35 deletions.
12 changes: 12 additions & 0 deletions adoc/chapters/opencl_backend.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -1185,6 +1185,18 @@ standard output all of the SYCL classes and primitives, and covers the
capabilities defined in the OpenCL 1.2 specification document <<opencl12, par.
6.12.13>>.


== Precision of builtin math functions

When the builtin SYCL functions defined in sections <<sec:math-functions>>
through <<sec:relational-functions>> are called from a kernel running on the
OpenCL backend, their precision is the same as the corresponding OpenCL
functions as specified for the OpenCL profile.
See ch. 6.12.2 through ch. 6.12.6 of the OpenCL 1.2 specification for the
definition of these corresponding OpenCL functions.



// %%%%%%%%%%%%%%%%%%%%%%%%%%%% end opencl_extensions %%%%%%%%%%%%%%%%%%%%%%%%%%%%

// %%%%%%%%%%%%%%%%%%%%%%%%%%%% end opencl_backend %%%%%%%%%%%%%%%%%%%%%%%%%%%%
55 changes: 20 additions & 35 deletions adoc/chapters/programming_interface.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -20583,17 +20583,11 @@ determined by their linear id.
--


[[sec:math-functions]]
=== Math functions

In SYCL the OpenCL math functions are available in the namespace [code]#sycl# on
host and device with the same precision guarantees as defined in the OpenCL 1.2
specification document <<opencl12, ch. 7>> for host and device.
For a SYCL platform the numerical requirements for host need to match the
numerical requirements of the OpenCL math built-in functions.

The built-in functions available for SYCL host and device, with the same
precision requirements for both host and device, are described in
<<table.math.functions>>.
<<table.math.functions>> describes the math functions that are available in the
[code]#sycl# namespace in both host and device code.

The function descriptions in this section use the term _writeable address space_
to represent the following address spaces:
Expand Down Expand Up @@ -23273,10 +23267,9 @@ corresponding [code]#vec#.

=== Native precision math functions

In SYCL the implementation-defined precision math functions are defined in the
namespace [code]#sycl::native#.
The functions that are available within this namespace are specified in
<<table.native.math.functions>>.
<<table.native.math.functions>> describes the native precision math functions
that are available in the [code]#sycl::native# namespace in both host and device
code.

The range of valid input values and the maximum error for these functions is
implementation defined.
Expand Down Expand Up @@ -23736,12 +23729,13 @@ corresponding [code]#vec#.

=== Half precision math functions

In SYCL the half precision math functions are defined in the namespace
[code]#sycl::half_precision#.
The functions that are available within this namespace are specified in
<<table.half.math.functions>>.
These functions are implemented with a minimum of 10-bits of accuracy i.e. the
maximum error is less than or equal to 8192 ulp.
<<table.half.math.functions>> describes the half precision math functions that
are available in the [code]#sycl::half_precision# namespace in both host and
device code.

The precision requirements for these functions are defined in the backend
specification, but the intent is that these functions have a lower precision
than their counterparts in <<sec:math-functions>>.

[[table.half.math.functions]]
.Half precision math functions
Expand Down Expand Up @@ -25065,11 +25059,8 @@ corresponding [code]#vec#.

=== Common functions

In SYCL the OpenCL [keyword]#common functions# are available in the namespace
[code]#sycl# on host and device as defined in the OpenCL 1.2 specification
document <<opencl12, par.
6.12.4>>.
They are described here in <<table.common.functions>>.
<<table.common.functions>> describes the common functions that are available in
the [code]#sycl# namespace in both host and device code.

The function descriptions in this section use the term _generic floating point
type_ to represent the following types:
Expand Down Expand Up @@ -25529,15 +25520,8 @@ corresponding [code]#vec#.
[[sec:geometric-functions]]
=== Geometric functions

In SYCL the OpenCL [keyword]#geometric functions# are available in the namespace
[code]#sycl# on host and device as defined in the OpenCL 1.2 specification
document <<opencl12, par.
6.12.5>>.
On the host the vector types use the [code]#vec# class and on an SYCL device use
the corresponding native <<backend>> vector types.
All of the geometric functions use round-to-nearest-even rounding mode.
<<table.geometric.functions>> contains the definitions of supported geometric
functions.
<<table.geometric.functions>> describes the geometric functions that are
available in the [code]#sycl# namespace in both host and device code.

The function descriptions in this section use two terms that refer to a specific
list of types.
Expand Down Expand Up @@ -25800,10 +25784,11 @@ corresponding [code]#vec#.
|====


[[sec:relational-functions]]
=== Relational functions

The functions in <<table.relational.functions>> are defined in the [code]#sycl#
namespace and are available on both host and device.
<<table.relational.functions>> describes the relational functions that are
available in the [code]#sycl# namespace in both host and device code.
These functions perform various relational comparisons on [code]#vec#,
[code]#marray#, and scalar types.

Expand Down

0 comments on commit 4005c57

Please sign in to comment.