From 4005c5796ff396fe4f4b97a62f9d4d0c67bae7e3 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 30 Nov 2023 13:12:20 -0500 Subject: [PATCH] Builtin function precision is backend specific 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 #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 #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. --- adoc/chapters/opencl_backend.adoc | 12 ++++++ adoc/chapters/programming_interface.adoc | 55 +++++++++--------------- 2 files changed, 32 insertions(+), 35 deletions(-) diff --git a/adoc/chapters/opencl_backend.adoc b/adoc/chapters/opencl_backend.adoc index 70b829c3..f6ea1785 100644 --- a/adoc/chapters/opencl_backend.adoc +++ b/adoc/chapters/opencl_backend.adoc @@ -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 <>. + +== Precision of builtin math functions + +When the builtin SYCL functions defined in sections <> +through <> 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 %%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index ec929689..1ac0227a 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -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 <> 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 -<>. +<> 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: @@ -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 -<>. +<> 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. @@ -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 -<>. -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. +<> 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 <>. [[table.half.math.functions]] .Half precision math functions @@ -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 <>. -They are described here in <>. +<> 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: @@ -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 <>. -On the host the vector types use the [code]#vec# class and on an SYCL device use -the corresponding native <> vector types. -All of the geometric functions use round-to-nearest-even rounding mode. -<> contains the definitions of supported 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. @@ -25800,10 +25784,11 @@ corresponding [code]#vec#. |==== +[[sec:relational-functions]] === Relational functions -The functions in <> are defined in the [code]#sycl# -namespace and are available on both host and device. +<> 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.