KhronosGroup / KhronosGroup/OpenCL-Docs

Improve documentation for correctly rounded divide and square root

Open
#1,537 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
420
Forks
131
Avg merge
5d 13h
Merged PRs (30d)
11

Description

We should improve our documentation for the "correctly rounded divide and square root" built option - `-cl-fp32-correctly-rounded-divide-sqrt`.

Spec reference: https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#math-intrinsics-options

Some things we should do specifically:

1. Confirm: This build option only applies to single precision divides and square roots, and not to half precision (fp16) divides and square roots?
* Note that double precision (fp64) divides and square roots are correctly rounded by default.
2. Check: What is the expected behavior if the `-cl-fp32-correctly-rounded-divide-sqrt` build option is passed to `clBuildProgram` and the device does not support correctly rounded divides and square roots ([CL_DEVICE_SINGLE_FP_CONFIG](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#CL_DEVICE_SINGLE_FP_CONFIG) does not include [CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT))?
* Should this generate [CL_INVALID_BUILD_OPTIONS](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#CL_INVALID_BUILD_OPTIONS)?
* What if some devices support correctly rounded divides and square roots, but some devices do not?
3. Update the math function accuracy tables in the [OpenCL C spec](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_C.html#relative-error-as-ulps) and the [OpenCL SPIR-V environment spec](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Env.html#relative-error-as-ulps) to clearly document when divides and square roots must be correctly rounded.
* Low priority: Do we need to define the behavior when both the `-cl-fp32-correctly-rounded-divide-sqrt` and `-cl-unsafe-math-optimizations` build options are present?

See also https://github.com/KhronosGroup/OpenCL-Docs/issues/1499.

Contributor guide

Open the contributing guide

Research direction

Start with the OpenCL API math-intrinsics-options section and the referenced OpenCL C and OpenCL SPIR-V environment accuracy tables. Verify the option's precision scope and unsupported-device behavior against the cited specification sections, including interactions with unsafe math optimizations. Done means the documentation clearly states these rules in all relevant tables and text.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.