= sycl_ext_oneapi_native_math

:source-highlighter: coderay
:coderay-linenums-mode: table

// This section needs to be after the document title.
:doctype: book
:toc2:
:toc: left
:encoding: utf-8
:lang: en
:dpcpp: pass:[DPC++]

// Set the default source code type in this document to C++,
// for syntax highlighting purposes.  This is needed because
// docbook uses c++ and html5 uses cpp.
:language: {basebackend@docbook:c++:cpp}


== Notice

[%hardbreaks]
Copyright (C) 2022 Intel Corporation.  All rights reserved.

Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks
of The Khronos Group Inc.  OpenCL(TM) is a trademark of Apple Inc. used by
permission by Khronos.


== Contact

To report problems with this extension, please open a new issue at:

https://github.com/intel/llvm/issues


== Dependencies

This extension is written against the SYCL 2020 revision 4 specification.  All
references below to the "core SYCL specification" or to section numbers in the
SYCL specification refer to that revision.

== Status

This is an experimental extension specification, intended to provide early
access to features and gather community feedback.  Interfaces defined in this
specification are implemented in {dpcpp}, but they are not finalized and may
change incompatibly in future versions of {dpcpp} without prior notice.
*Shipping software products should not rely on APIs defined in this
specification.*

== Overview

The CUDA backend has introduced fast math "approx" versions of the `exp2` and
`tanh` functions for `half` and `float` types. It is considered likely that
other backends will eventually introduce similar functionality, motivated
particularly by deep learning use cases of these functions. We propose that the
appropriate place to call such functionality in SYCL applications would be from
the newly proposed native functions.

== Specification

=== Feature test macro

This extension provides a feature-test macro as described in the core SYCL
specification.  An implementation supporting this extension must predefine the
macro `SYCL_EXT_ONEAPI_NATIVE_MATH` to one of the values defined in the table
below.  Applications can test for the existence of this macro to determine if
the implementation supports this feature, or applications can test the macro's
value to determine which of the extension's features the implementation
supports.

[%header,cols="1,5"]
|===
|Value
|Description

|1
|The APIs of this experimental extension are not versioned, so the
 feature-test macro always has this value.
|===

=== New functions

This extension allows the `sycl::native::exp2` function (that originally
supports `genfloatf` types) to support `genfloath` types in the
`sycl::ext::oneapi::experimental::native` namespace. It also introduces a new
native `tanh` function supporting `genfloath` and `genfloatf` types in the
`sycl::ext::oneapi::experimental::native` namespace.

NOTE: This document does not propose `genfloatd` support for either
`sycl::ext::oneapi::experimental::native::exp2` or
`sycl::ext::oneapi::experimental::native::tanh`. 


> This extension adds the following new native builtin functions to SYCL:
>
> ```
> namespace sycl::ext::oneapi::experimental::native {
> 
> // Available only when "T" is one of the genfloath types.
> template <typename T>
> T exp2(T x);
> 
> // Available only when "T" is one of the genfloatf or genfloath types.
> template <typename T>
> T tanh(T x);
> 
> } // namespace sycl::ext::oneapi::experimental::native
> ```