diff options
Diffstat (limited to 'libc/docs/math')
| -rw-r--r-- | libc/docs/math/index.rst | 459 | ||||
| -rw-r--r-- | libc/docs/math/log.rst | 557 | ||||
| -rw-r--r-- | libc/docs/math/stdfix.rst | 149 |
3 files changed, 0 insertions, 1165 deletions
diff --git a/libc/docs/math/index.rst b/libc/docs/math/index.rst deleted file mode 100644 index 4934e93ccb16..000000000000 --- a/libc/docs/math/index.rst +++ /dev/null @@ -1,459 +0,0 @@ -.. _math: - -============== -Math Functions -============== - -.. include:: ../check.rst - -.. raw:: html - - <style> .green {color:green} </style> - -.. role:: green - -.. toctree:: - :hidden: - - log.rst - stdfix.rst - - -.. contents:: Table of Contents - :depth: 4 - :local: - -Source Locations -================ - -- The main source is located at: `libc/src/math <https://github.com/llvm/llvm-project/tree/main/libc/src/math>`_. -- The tests are located at: `libc/test/src/math <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math>`_. -- The floating point utilities are located at: `libc/src/__support/FPUtil <https://github.com/llvm/llvm-project/tree/main/libc/src/__support/FPUtil>`_. - -Implementation Requirements / Goals -=================================== - -* The highest priority is to be as accurate as possible, according to the C and - IEEE 754 standards. By default, we will aim to be correctly rounded for `all rounding modes <https://en.cppreference.com/w/c/numeric/fenv/FE_round>`_. - The current rounding mode of the floating point environment is used to perform - computations and produce the final results. - - - To test for correctness, we compare the outputs with other correctly rounded - multiple-precision math libraries such as the `GNU MPFR library <https://www.mpfr.org/>`_ - or the `CORE-MATH library <https://core-math.gitlabpages.inria.fr/>`_. - -* Our next requirement is that the outputs are consistent across all platforms. - Notice that the consistency requirement will be satisfied automatically if the - implementation is correctly rounded. - -* Our last requirement for the implementations is to have good and predicable - performance: - - - The average performance should be comparable to other ``libc`` - implementations. - - The worst case performance should be within 10X-20X of the average. - - Platform-specific implementations or instructions could be added whenever it - makes sense and provides significant performance boost. - -* For other use cases that have strict requirements on the code size, memory - footprint, or latency, such as embedded systems, we will aim to be as accurate - as possible within the memory or latency budgets, and consistent across all - platforms. - - -Add a new math function to LLVM libc -==================================== - -* To add a new math function, follow the steps at: `libc/src/math/docs/add_math_function.md <https://github.com/llvm/llvm-project/tree/main/libc/src/math/docs/add_math_function.md>`_. - -Implementation Status -===================== - -* To check math functions enabled for Linux: - - - `linux-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64/entrypoints.txt>`_ - - - `linux-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64/entrypoints.txt>`_ - - - `linux-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm/entrypoints.txt>`_ - - - `linux-riscv and linux-riscv32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/riscv/entrypoints.txt>`_ - -* To check math functions enabled for Windows: - - - `windows-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_ - - - windows-aarch64 - to be added - -* To check math functions enabled for macOS: - - - `darwin-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/x86_64/entrypoints.txt>`_ - - - `darwin-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/arm/entrypoints.txt>`_ - -* To check math functions enabled for GPU: - - - `gpu-entrypoints <https://github.com/llvm/llvm-project/tree/main/libc/config/gpu/entrypoints.txt>`_ - -* To check math functions enabled for embedded system: - - - `baremetal-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/baremetal/arm/entrypoints.txt>`_ - - - baremetal-riscv32 - to be added - - -Basic Operations -================ - -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| <Func> | <Func_f> (float) | <Func> (double) | <Func_l> (long double) | <Func_f16> (float16) | <Func_f128> (float128) | C23 Definition Section | C23 Error Handling Section | -+==================+==================+=================+========================+======================+========================+========================+============================+ -| ceil | |check| | |check| | |check| | |check| | |check| | 7.12.9.1 | F.10.6.1 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| canonicalize | |check| | |check| | |check| | |check| | |check| | 7.12.11.7 | F.10.8.7 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| copysign | |check| | |check| | |check| | |check| | |check| | 7.12.11.1 | F.10.8.1 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| dadd | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.1 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| ddiv | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.4 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| dfma | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.5 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| dmul | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.3 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| dsub | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.2 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| f16add | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.1 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| f16div | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.4 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| f16fma | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.5 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| f16mul | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.5 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| f16sub | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.2 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fabs | |check| | |check| | |check| | |check| | |check| | 7.12.7.3 | F.10.4.3 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fadd | N/A | |check| | |check| | N/A | |check| | 7.12.14.1 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fdim | |check| | |check| | |check| | |check| | |check| | 7.12.12.1 | F.10.9.1 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fdiv | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.4 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| ffma | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.5 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| floor | |check| | |check| | |check| | |check| | |check| | 7.12.9.2 | F.10.6.2 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmax | |check| | |check| | |check| | |check| | |check| | 7.12.12.2 | F.10.9.2 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmaximum | |check| | |check| | |check| | |check| | |check| | 7.12.12.4 | F.10.9.4 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmaximum_mag | |check| | |check| | |check| | |check| | |check| | 7.12.12.6 | F.10.9.4 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmaximum_mag_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.10 | F.10.9.5 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmaximum_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.8 | F.10.9.5 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmin | |check| | |check| | |check| | |check| | |check| | 7.12.12.3 | F.10.9.3 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fminimum | |check| | |check| | |check| | |check| | |check| | 7.12.12.5 | F.10.9.4 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fminimum_mag | |check| | |check| | |check| | |check| | |check| | 7.12.12.7 | F.10.9.4 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fminimum_mag_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.11 | F.10.9.5 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fminimum_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.9 | F.10.9.5 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmod | |check| | |check| | |check| | |check| | |check| | 7.12.10.1 | F.10.7.1 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fmul | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.3 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| frexp | |check| | |check| | |check| | |check| | |check| | 7.12.6.7 | F.10.3.7 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fromfp | |check| | |check| | |check| | |check| | |check| | 7.12.9.10 | F.10.6.10 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fromfpx | |check| | |check| | |check| | |check| | |check| | 7.12.9.11 | F.10.6.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fsub | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.2 | F.10.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| getpayload | |check| | |check| | |check| | |check| | |check| | F.10.13.1 | N/A | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| ilogb | |check| | |check| | |check| | |check| | |check| | 7.12.6.8 | F.10.3.8 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| iscanonical | |check| | |check| | |check| | |check| | |check| | 7.12.3.2 | N/A | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| issignaling | |check| | |check| | |check| | |check| | |check| | 7.12.3.8 | N/A | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| ldexp | |check| | |check| | |check| | |check| | |check| | 7.12.6.9 | F.10.3.9 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| llogb | |check| | |check| | |check| | |check| | |check| | 7.12.6.10 | F.10.3.10 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| llrint | |check| | |check| | |check| | |check| | |check| | 7.12.9.5 | F.10.6.5 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| llround | |check| | |check| | |check| | |check| | |check| | 7.12.9.7 | F.10.6.7 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| logb | |check| | |check| | |check| | |check| | |check| | 7.12.6.17 | F.10.3.17 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| lrint | |check| | |check| | |check| | |check| | |check| | 7.12.9.5 | F.10.6.5 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| lround | |check| | |check| | |check| | |check| | |check| | 7.12.9.7 | F.10.6.7 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| modf | |check| | |check| | |check| | |check| | |check| | 7.12.6.18 | F.10.3.18 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| nan | |check| | |check| | |check| | |check| | |check| | 7.12.11.2 | F.10.8.2 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| nearbyint | |check| | |check| | |check| | |check| | |check| | 7.12.9.3 | F.10.6.3 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| nextafter | |check| | |check| | |check| | |check| | |check| | 7.12.11.3 | F.10.8.3 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| nextdown | |check| | |check| | |check| | |check| | |check| | 7.12.11.6 | F.10.8.6 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| nexttoward | |check| | |check| | |check| | |check| | N/A | 7.12.11.4 | F.10.8.4 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| nextup | |check| | |check| | |check| | |check| | |check| | 7.12.11.5 | F.10.8.5 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| remainder | |check| | |check| | |check| | |check| | |check| | 7.12.10.2 | F.10.7.2 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| remquo | |check| | |check| | |check| | |check| | |check| | 7.12.10.3 | F.10.7.3 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| rint | |check| | |check| | |check| | |check| | |check| | 7.12.9.4 | F.10.6.4 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| round | |check| | |check| | |check| | |check| | |check| | 7.12.9.6 | F.10.6.6 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| roundeven | |check| | |check| | |check| | |check| | |check| | 7.12.9.8 | F.10.6.8 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| scalbln | |check| | |check| | |check| | |check| | |check| | 7.12.6.19 | F.10.3.19 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| scalbn | |check| | |check| | |check| | |check| | |check| | 7.12.6.19 | F.10.3.19 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| setpayload | |check| | |check| | |check| | |check| | |check| | F.10.13.2 | N/A | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| setpayloadsig | |check| | |check| | |check| | |check| | |check| | F.10.13.3 | N/A | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| totalorder | |check| | |check| | |check| | |check| | |check| | F.10.12.1 | N/A | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| totalordermag | |check| | |check| | |check| | |check| | |check| | F.10.12.2 | N/A | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| trunc | |check| | |check| | |check| | |check| | |check| | 7.12.9.9 | F.10.6.9 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| ufromfp | |check| | |check| | |check| | |check| | |check| | 7.12.9.10 | F.10.6.10 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| ufromfpx | |check| | |check| | |check| | |check| | |check| | 7.12.9.11 | F.10.6.11 | -+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ - - -Higher Math Functions -===================== - -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| <Func> | <Func_f> (float) | <Func> (double) | <Func_l> (long double) | <Func_f16> (float16) | <Func_f128> (float128) | C23 Definition Section | C23 Error Handling Section | -+===========+==================+=================+========================+======================+========================+========================+============================+ -| acos | |check| | | | | | 7.12.4.1 | F.10.1.1 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| acosh | |check| | | | | | 7.12.5.1 | F.10.2.1 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| acospi | | | | | | 7.12.4.8 | F.10.1.8 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| asin | |check| | | | | | 7.12.4.2 | F.10.1.2 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| asinh | |check| | | | | | 7.12.5.2 | F.10.2.2 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| asinpi | | | | | | 7.12.4.9 | F.10.1.9 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| atan | |check| | | | | | 7.12.4.3 | F.10.1.3 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| atan2 | |check| | 1 ULP | | | | 7.12.4.4 | F.10.1.4 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| atan2pi | | | | | | 7.12.4.11 | F.10.1.11 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| atanh | |check| | | | | | 7.12.5.3 | F.10.2.3 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| atanpi | | | | | | 7.12.4.10 | F.10.1.10 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| cbrt | |check| | |check| | | | | 7.12.7.1 | F.10.4.1 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| compoundn | | | | | | 7.12.7.2 | F.10.4.2 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| cos | |check| | |check| | | | | 7.12.4.5 | F.10.1.5 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| cosh | |check| | | | |check| | | 7.12.5.4 | F.10.2.4 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| cospi | |check| | | | |check| | | 7.12.4.12 | F.10.1.12 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| dsqrt | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.6 | F.10.11 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| erf | |check| | | | | | 7.12.8.1 | F.10.5.1 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| erfc | | | | | | 7.12.8.2 | F.10.5.2 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| exp | |check| | |check| | | |check| | | 7.12.6.1 | F.10.3.1 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| exp10 | |check| | |check| | | |check| | | 7.12.6.2 | F.10.3.2 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| exp10m1 | |check| | | | |check| | | 7.12.6.3 | F.10.3.3 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| exp2 | |check| | |check| | | |check| | | 7.12.6.4 | F.10.3.4 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| exp2m1 | |check| | | | |check| | | 7.12.6.5 | F.10.3.5 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| expm1 | |check| | |check| | | |check| | | 7.12.6.6 | F.10.3.6 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fma | |check| | |check| | | | | 7.12.13.1 | F.10.10.1 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| f16sqrt | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.6 | F.10.11 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| fsqrt | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.6 | F.10.11 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| hypot | |check| | |check| | | | | 7.12.7.4 | F.10.4.4 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| lgamma | | | | | | 7.12.8.3 | F.10.5.3 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| log | |check| | |check| | | |check| | | 7.12.6.11 | F.10.3.11 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| log10 | |check| | |check| | | |check| | | 7.12.6.12 | F.10.3.12 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| log10p1 | | | | | | 7.12.6.13 | F.10.3.13 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| log1p | |check| | |check| | | | | 7.12.6.14 | F.10.3.14 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| log2 | |check| | |check| | | |check| | | 7.12.6.15 | F.10.3.15 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| log2p1 | | | | | | 7.12.6.16 | F.10.3.16 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| logp1 | | | | | | 7.12.6.14 | F.10.3.14 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| pow | |check| | 1 ULP | | | | 7.12.7.5 | F.10.4.5 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| powi\* | | | | | | | | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| pown | | | | | | 7.12.7.6 | F.10.4.6 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| powr | | | | | | 7.12.7.7 | F.10.4.7 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| rootn | | | | | | 7.12.7.8 | F.10.4.8 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| rsqrt | | | | | | 7.12.7.9 | F.10.4.9 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| sin | |check| | |check| | | |check| | | 7.12.4.6 | F.10.1.6 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| sincos | |check| | |check| | | | | | | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| sinh | |check| | | | |check| | | 7.12.5.5 | F.10.2.5 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| sinpi | |check| | | | |check| | | 7.12.4.13 | F.10.1.13 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| sqrt | |check| | |check| | |check| | |check| | |check| | 7.12.7.10 | F.10.4.10 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| tan | |check| | |check| | | | | 7.12.4.7 | F.10.1.7 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| tanh | |check| | | | |check| | | 7.12.5.6 | F.10.2.6 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| tanpi | | | | |check| | | 7.12.4.14 | F.10.1.14 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ -| tgamma | | | | | | 7.12.8.4 | F.10.5.4 | -+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ - -Legends: - -* |check| : correctly rounded for all 4 rounding modes. -* CR: correctly rounded for the default rounding mode (round-to-the-nearest, - tie-to-even). -* x ULPs: largest errors recorded. -* N/A: Not defined in the standard or will not be added. -* \*: LLVM libc extension. - -.. - TODO(lntue): Add a new page to discuss about the algorithms used in the - implementations and include the link here. - - -Performance -=========== - -* Simple performance testings are located at: `libc/test/src/math/performance_testing <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math/performance_testing>`_. - -* We also use the *perf* tool from the `CORE-MATH <https://core-math.gitlabpages.inria.fr/>`_ - project: `link <https://gitlab.inria.fr/core-math/core-math/-/tree/master>`_. - The performance results from the CORE-MATH's perf tool are reported in the - table below, using the system library as reference (such as the `GNU C library <https://www.gnu.org/software/libc/>`_ - on Linux). Fmod performance results obtained with "performance_testing". - -+--------------+-------------------------------+-------------------------------+-------------------------------------+----------------------------------------------------------------------+ -| <Func> | Reciprocal throughput (clk) | Latency (clk) | Testing ranges | Testing configuration | -| +-----------+-------------------+-----------+-------------------+ +-------------+-------------------------+--------------+---------------+ -| | LLVM libc | Reference (glibc) | LLVM libc | Reference (glibc) | | CPU | OS | Compiler | Special flags | -+==============+===========+===================+===========+===================+=====================================+=============+=========================+==============+===============+ -| acosf | 24 | 29 | 62 | 77 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| acoshf | 18 | 26 | 73 | 74 | :math:`[1, 21]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| asinf | 23 | 27 | 62 | 62 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| asinhf | 21 | 39 | 77 | 91 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| atanf | 27 | 29 | 79 | 68 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| atanhf | 18 | 66 | 68 | 133 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| cosf | 13 | 32 | 53 | 59 | :math:`[0, 2\pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| coshf | 14 | 20 | 50 | 48 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| expf | 9 | 7 | 44 | 38 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| exp10f | 10 | 8 | 40 | 38 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| exp2f | 9 | 6 | 35 | 31 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| expm1f | 9 | 44 | 42 | 121 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| fmodf | 73 | 263 | - | - | [MIN_NORMAL, MAX_NORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | -| +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| | 9 | 11 | - | - | [0, MAX_SUBNORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| fmod | 595 | 3297 | - | - | [MIN_NORMAL, MAX_NORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | -| +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| | 14 | 13 | - | - | [0, MAX_SUBNORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| hypotf | 25 | 15 | 64 | 49 | :math:`[-10, 10] \times [-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| logf | 12 | 10 | 56 | 46 | :math:`[e^{-1}, e]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| log10f | 9 | 17 | 35 | 48 | :math:`[e^{-1}, e]` | Ryzen 5900X | Ubuntu 22.04 LTS x86_64 | Clang 15.0.6 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| log1pf | 16 | 33 | 61 | 97 | :math:`[e^{-0.5} - 1, e^{0.5} - 1]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| log2f | 13 | 10 | 57 | 46 | :math:`[e^{-1}, e]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| sinf | 12 | 25 | 51 | 57 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| sincosf | 19 | 30 | 57 | 68 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| sinhf | 13 | 63 | 48 | 137 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| tanf | 16 | 50 | 61 | 107 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ -| tanhf | 13 | 55 | 57 | 123 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | -+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ - -Algorithms + Implementation Details -=================================== - -* :doc:`log` - -Fixed-point Arithmetics -======================= - -* :doc:`stdfix` - -References -========== - -* `CRLIBM <https://hal-ens-lyon.archives-ouvertes.fr/ensl-01529804/file/crlibm.pdf>`_. -* `RLIBM <https://people.cs.rutgers.edu/~sn349/rlibm/>`_. -* `Sollya <https://www.sollya.org/>`_. -* `The CORE-MATH Project <https://core-math.gitlabpages.inria.fr/>`_. -* `The GNU C Library (glibc) <https://www.gnu.org/software/libc/>`_. -* `The GNU MPFR Library <https://www.mpfr.org/>`_. diff --git a/libc/docs/math/log.rst b/libc/docs/math/log.rst deleted file mode 100644 index 82d2e2be6fb5..000000000000 --- a/libc/docs/math/log.rst +++ /dev/null @@ -1,557 +0,0 @@ -.. _log_algorithm: - -======================== -Log/Log10/Log2 Algorithm -======================== - -.. default-role:: math - -In this short note, we will discuss in detail about the computation of -:math:`\log(x)` function, with double precision inputs, in particular, the range -reduction steps and error analysis. The algorithm is broken down into 2 main -phases as follow: - -1. Fast phase: - - a. Range reduction - b. Polynomial approximation - c. Ziv's test - -2. Accurate phase (if Ziv's test failed): - - a. Further range reduction - b. Polynomial approximation - - -Fast phase -========== - -Range reduction ---------------- - -Let `x = 2^{e_x} (1 + m_x)` be a normalized double precision number, in which -`-1074 \leq e_x \leq 1022` and `0 \leq m_x < 1` such that -`2^{52} m_x \in \mathbb{Z}`. - -Then from the properties of logarithm: - -.. math:: - \log(x) &= \log\left( 2^{e_x} (1 + m_x) \right) \\ - &= \log\left( 2^{e_x} \right) + \log(1 + m_x) \\ - &= e_x \log(2) + \log(1 + m_x) - -the computation of `\log(x)` can be reduced to: - -1. compute the product of `e_x` and `\log(2)`, -2. compute `\log(1 + m_x)` for `0 \leq m_x < 1`, -3. add step 1 and 2. - -To compute `\log(1 + m_x)` in step 2, we can reduce the range further by finding -`r > 0` such that: - -.. math:: - | r(1 + m_x) - 1 | < C \quad \quad \text{(R1)} - -for small `0 < C < 1`. Then if we let `u = r(1 + m_x) - 1`, `|u| < C`: - -.. math:: - \log(1 + m_x) &= \log \left( \frac{r (1 + m_x)}{r} \right) \\ - &= \log(r (1 + m_x) ) - \log(r) \\ - &= \log(1 + u) - \log(r) - -and step 2 can be computed with: - -a. extract `r` and `-\log(r)` from look-up tables, -b. compute the reduced argument `u = r(1 + m_x) - 1`, -c. compute `\log(1 + u)` by polynomial approximation or further range reduction, -d. add step a and step c results. - - -How to derive `r` ------------------ - -For an efficient implementation, we would like to use the first `M` significant -bits of `m_x` to look up for `r`. In particular, we would like to find a value -of `r` that works for all `m_x` satisfying: - -.. math:: - k 2^{-M} \leq m_x < (k + 1) 2^{-M} \quad \text{for some} \quad - k = 0..2^{M} - 1. \quad\quad \text{(M1)} - -Let `r = 1 + s`, then `u` can be expressed in terms of `s` as: - -.. math:: - u &= r(1 + m_x) - 1 \\ - &= (1 + s)(1 + m_x) - 1 \\ - &= s m_x + s + m_x &\quad\quad \text{(U1)} \\ - &= s (1 + m_x) + m_x \\ - &= m_x (1 + s) + s. - -From the condition `\text{(R1)}`, `s` is bounded by: - -.. math:: - \frac{-C - m_x}{1 + m_x} < s < \frac{C - m_x}{1 + m_x} \quad\quad \text{(S1)}. - -Since our reduction constant `s` must work for all `m_x` in the interval -`I = \{ v: k 2^{-M} \leq v < (k + 1) 2^{-M} \}`, `s` is bounded by: - -.. math:: - \sup_{v \in I} \frac{-C - v}{1 + v} < s < \inf_{v \in I} \frac{C - v}{1 + v} - -For a fixed constant `|c| < 1`, let `f(v) = \frac{c - v}{1 + v}`, then its -derivative is: - -.. math:: - f'(v) = \frac{(-1)(1 + v) - (1)(c - v)}{(1 + v)^2} = \frac{-1 - c}{(1 + v)^2}. - -Since `|c| < 1`, `f'(v) < 0` for all `v \neq -1`, so: - -.. math:: - \sup_{v \in I} f(v) &= f \left( \inf\{ v: v \in I \} \right) - = f \left( k 2^{-M} \right) \\ - \inf_{v \in I} f(v) &= f \left( \sup\{ v: v \in I \} \right) - = f \left( (k + 1) 2^{-M} \right) - -Hence we have the following bound on `s`: - -.. math:: - \frac{-C - k 2^{-M}}{1 + k 2^{-M}} < s \leq - \frac{C - (k + 1) 2^{-M}}{1 + (k + 1) 2^{-M}}. \quad\quad \text{(S2)} - -In order for `s` to exist, we need that: - -.. math:: - \frac{C - (k + 1) 2^{-M}}{1 + (k + 1) 2^{-M}} > - \frac{-C - k 2^{-M}}{1 + k 2^{-M}} - -which is equivalent to: - -.. math:: - \quad\quad 2C - 2^{-M} + (2k + 1) 2^{-M} C > 0 - \iff C > \frac{2^{-M - 1}}{1 + (2k + 1) 2^{-M - 1}} \quad\quad \text{(C1)}. - -Consider the case `C = 2^{-N}`. Since `0 \leq k \leq 2^M - 1,` the right hand -side of `\text{(C1)}` is bounded by: - -.. math:: - 2^{-M - 1} > \frac{2^{-M - 1}}{1 + (2k + 1) 2^{-M - 1}} \geq - \frac{2^{-M - 1}}{1 + (2^{M + 1} - 1) 2^{-M - 1}} > 2^{-M - 2}. - -Hence, from `\text{(C1)}`, being an exact power of 2, `C = 2^{-N}` is bounded below -by: - -.. math:: - C = 2^{-N} \geq 2^{-M - 1}. - -To make the range reduction efficient, we will want to minimize `C` (maximize -`N`) while keeping the required precision of `s`(`r`) as low as possible. And -for that, we will consider the following two cases: `N = M + 1` and `N = M`. - -Case 1 - `N = M + 1` -~~~~~~~~~~~~~~~~~~~~ - -When `N = M + 1`, `\text{(S2)}` becomes: - -.. math:: - \frac{-2^{-M - 1} - k 2^{-M}}{1 + k 2^{-M}} < s < - \frac{2^{-M - 1} - (k + 1) 2^{-M}}{1 + (k + 1) 2^{-M}}. - \quad\quad \text{(S2')} - -This is an interval of length: - -.. math:: - l &= \frac{2^{-M - 1} - (k + 1) 2^{-M}}{1 + (k + 1) 2^{-M}} - - \frac{-2^{-M - 1} - k 2^{-M}}{1 + k 2^{-M}} \\ - &= \frac{(2k + 1)2^{-2M - 1}}{(1 + k 2^{-M})(1 + (k + 1)2^{-M})} - \quad\quad \text{(L1)} - -As a function of `k`, the length `l` has its derivative with respect to `k`: - -.. math:: - \frac{dl}{dk} = - \frac{2^{2M + 1} - 2k(k + 1) - 1} - {2^{4M}(1 + k 2^{-M})^2 (1 + (k + 1) 2^{-M})^2} - -which is always positive for `0 \leq k \leq 2^M - 1`. So for all -`0 < k < 2^{-M}` (`k = 0` will be treated differently in edge cases), and for -`M > 2`, `l` is bounded below by: - -.. math:: - l > 2^{-2M}. - -It implies that we can always find `s` with `\operatorname{ulp}(s) = 2^{-2M}`. -And from `\text{(U1)}`, `u = s(1 + m_x) + m_x`, its `ulp` is: - -.. math:: - \operatorname{ulp}(u) &= \operatorname{ulp}(s) \cdot \operatorname{ulp}(m_x) \\ - &= 2^{-2M} \operatorname{ulp}(m_x). - -Since: - -.. math:: - |u| < C = 2^{-N} = 2^{-M - 1}, - -Its required precision is: - -.. math:: - \operatorname{prec}(u) &= \log_2(2^{-M-1} / \operatorname{ulp}(u)) \\ - &= \log_2(2^{M - 1} / \operatorname{ulp}(m_x)) \\ - &= M - 1 - \log_2(\operatorname{ulp}(m_x)). - -This means that in this case, we cannot restrict `u` to be exactly representable -in double precision for double precision input `x` with `M > 2`. Nonetheless, -for a reasonable value of `M`, we can have `u` exactly representable in double -precision for single precision input `x` (`\operatorname{ulp}(m_x) = 2^{-23}`) -such that `|u| < 2^{-M - 1}` using a look-up table of size `2^M`. - -A particular formula for `s` can be derived from `\text{(S2')}` by the midpoint -formula: - -.. math:: - s &= 2^{-2M} \operatorname{round}\left( 2^{2M} \cdot \operatorname{midpoint} - \left(-\frac{-2^{-M - 1} - k2^{-M}}{1 + k 2^{-M}}, - \frac{2^{-M-1} - (k + 1)2^{-M}}{1 + (k + 1) 2^{-M}}\right) \right) \\ - &= 2^{-2M} \operatorname{round}\left( 2^{2M} \cdot \frac{1}{2} \left( - \frac{-2^{-M - 1} - k2^{-M}}{1 + k 2^{-M}} + - \frac{2^{-M - 1} + (k + 1)2^{-M}}{1 + (k + 1) 2^{-M}} - \right) \right) \\ - &= 2^{-2M} \operatorname{round}\left( \frac{ - - \left(k + \frac{1}{2} \right) \left(2^M - k - \frac{1}{2} \right) } - {(1 + k 2^{-N})(1 + (k + 1) 2^{-N})} \right) \\ - &= - 2^{-2M} \operatorname{round}\left( \frac{ - \left(k + \frac{1}{2} \right) \left(2^M - k - \frac{1}{2} \right) } - {(1 + k 2^{-N})(1 + (k + 1) 2^{-N})} \right) \quad\quad \text{(S3)} - -The corresponding range and formula for `r = 1 + s` are: - -.. math:: - \frac{1 - 2^{-M - 1}}{1 + k 2^{-M}} < r \leq - \frac{1 + 2^{-M - 1}}{1 + (k + 1) 2^{-M}} - -.. math:: - r &= 2^{-2M} \operatorname{round}\left( 2^{2M} \cdot - \operatorname{midpoint}\left( \frac{1 - 2^{-M - 1}}{1 + k 2^{-M}}, - \frac{1 + 2^{-M - 1}}{1 + (k + 1) 2^{-M}}\right) \right) \\ - &= 2^{-2M} \operatorname{round}\left( 2^{2M} \cdot \frac{1}{2} \left( - \frac{1 + 2^{-M-1}}{1 + (k + 1) 2^{-M}} + \frac{1 - 2^{-M-1}}{1 + k 2^{-M}} - \right) \right) \\ - &= 2^{-2M} \operatorname{round}\left( 2^{2M} \cdot \frac{ - 1 + \left(k + \frac{1}{2} \right) 2^{-M} - 2^{-2M-2} }{(1 + k 2^{-M}) - (1 + (k + 1) 2^{-M})} \right) - -Case 1 - `N = M` -~~~~~~~~~~~~~~~~ - -When `N = M`, `\text{(S2)}` becomes: - -.. math:: - \frac{-(k + 1)2^{-M}}{1 + k 2^{-M}} < s < \frac{-k 2^{-M}}{1 + (k + 1) 2^{-M}} - \quad\quad \text{(S2")} - -This is an interval of length: - -.. math:: - l &= \frac{- k 2^{-M}}{1 + (k + 1) 2^{-M}} - - \frac{- (k + 1) 2^{-M}}{1 + k 2^{-M}} \\ - &= \frac{2^{-M} (1 + (2k + 1) 2^{-M})}{(1 + k 2^{-M})(1 + (k + 1)2^{-M})} - \quad\quad \text{(L1')} - -As a function of `k`, its derivative with respect to `k`: - -.. math:: - \frac{dl}{dk} = - -\frac{2^{-2M}(k(k + 1)2^{-M + 1} + 2^{-M} + 2k + 1)} - {(1 + k 2^{-M})^2 (1 + (k + 1) 2^{-M})^2} - -which is always negative for `0 \leq k \leq 2^M - 1`. So for `M > 1`, `l` is -bounded below by: - -.. math:: - l > \frac{2^{-M - 1} (3 - 2^{-M})}{2 - 2^{-M}} > 2^{-M - 1}. - -It implies that we can always find `s` with `\operatorname{ulp}(s) = 2^{-M-1}`. -And from `\text{(U1)}`, `u = s(1 + m_x) + m_x`, its `ulp` is: - -.. math:: - \operatorname{ulp}(u) &= \operatorname{ulp}(s) \cdot \operatorname{ulp}(m_x) \\ - &= 2^{-M - 1} \operatorname{ulp}(m_x). - -Since: - -.. math:: - |u| < C = 2^{-N} = 2^{-M}, - -Its required precision is: - -.. math:: - \operatorname{prec}(u) &= \log_2(2^{-M} / \operatorname{ulp}(u)) \\ - &= \log_2(2 / \operatorname{ulp}(m_x)) \\ - &= 1 - \log_2(\operatorname{ulp}(m_x)). - -Hence, for double precision `x`, `\operatorname{ulp}(m_x) = 2^{-52}`, and the -precision needed for `u` is `\operatorname{prec}(u) = 53`, i.e., `u` can be -exactly representable in double precision. And in this case, `s` can be -derived from `\text{(S2")}` by the midpoint formula: - -.. math:: - s &= 2^{-M - 1} \operatorname{round}\left( 2^{M + 1} \cdot - \operatorname{midpoint} \left(-\frac{-(k + 1)2^{-M}}{1 + k 2^{-M}}, - \frac{-k2^{-M}}{1 + (k + 1) 2^{-M}}\right) \right) \\ - &= 2^{-M - 1} \operatorname{round}\left( 2^{M + 1} \cdot \frac{1}{2} \left( - \frac{-(k + 1)2^{-M}}{1 + k 2^{-M}} + \frac{-k2^{-M}}{1 + (k + 1) 2^{-M}} - \right) \right) \\ - &= -2^{-M - 1} \operatorname{round}\left( \frac{ - (2k + 1) + (2k^2 + 2k + 1) 2^{-M} } - {(1 + k 2^{-N})(1 + (k + 1) 2^{-N})} \right) \quad\quad \text{(S3')} - -The corresponding range and formula for `r = 1 + s` are: - -.. math:: - \frac{1 - 2^{-M}}{1 + k 2^{-M}} < r \leq \frac{1 + 2^{-M}}{1 + (k + 1) 2^{-M}} - -.. math:: - r &= 2^{-M-1} \operatorname{round}\left( 2^{M + 1} \cdot - \operatorname{midpoint}\left( \frac{1 - 2^{-M}}{1 + k 2^{-M}}, - \frac{1 + 2^{-M}}{1 + (k + 1) 2^{-M}}\right) \right) \\ - &= 2^{-M-1} \operatorname{round}\left( 2^{M + 1} \cdot \frac{1}{2} \left( - \frac{1 + 2^{-M}}{1 + (k + 1) 2^{-M}} + \frac{1 - 2^{-M}}{1 + k 2^{-M}} - \right) \right) \\ - &= 2^{-M - 1} \operatorname{round}\left( 2^{M + 1} \cdot \frac{ - 1 + \left(k + \frac{1}{2} \right) 2^{-M} - 2^{-2M-1} }{(1 + k 2^{-M}) - (1 + (k + 1) 2^{-M})} \right) - -Edge cases ----------- - -1. When `k = 0`, notice that: - -.. math:: - 0 = k 2^{-N} \leq m_x < (k + 1) 2^{-N} = 2^{-N} = C, - -so we can simply choose `r = 1` so that `\log(r) = 0` is exact, then `u = m_x`. -This will help reduce the accumulated errors when `m_x` is close to 0 while -maintaining the range reduction output's requirements. - -2. When `k = 2^{N} - 1`, `\text{(S2)}` becomes: - -.. math:: - -\frac{1}{2} - \frac{C - 2^{-M-1}}{2 - 2^{-M}} <> s \leq - -\frac{1}{2} + \frac{C}{2}. - -so when `C > 2^{-M - 1}` is a power of 2, we can always choose: - -.. math:: - s = -\frac{1}{2}, \quad \text{i.e.} \quad r = \frac{1}{2}. - -This reduction works well to avoid catastrophic cancellation happening when -`e_x = -1`. - -This also works when `C = 2^{-M - 1}` if we relax the condition on `u` to -`|u| \leq C = 2^{-M-1}`. - -Intermediate precision, and Ziv's test --------------------------------------- - -In the fast phase, we want extra precision while performant, so we use -double-double precision for most intermediate computation steps, and employ Ziv -test to see if the result is accurate or not. In our case, the Ziv's test can -be described as follow: - -1. Let `re = re.hi + re.lo` be the double-double output of the fast phase - computation. -2. Let `err` be an estimated upper bound of the errors of `re`. -3. If `\circ(re.hi + (re.lo - err)) == \circ(re.hi + (r.lo + err))` then the - result is correctly rounded to double precision for the current rounding mode - `\circ`. Otherwise, the accurate phase with extra precision is needed. - -For an easy and cheap estimation of the error bound `err`, since the range -reduction step described above is accurate, the errors of the result: - -.. math:: - \log(x) &= e_x \log(2) - \log(r) + \log(1 + u) \\ - &\approx e_x \log(2) - \log(r) + u P(u) - -come from 2 parts: - -1. the look-up part: `e_x \log(2) - \log(r)` -2. the polynomial approximation part: `u P(u)` - -The errors of the first part can be computed with a single `\operatorname{fma}` -operation: - -.. math:: - err_1 = \operatorname{fma}(e_x, err(\log(2)), err(\log(r))), - -and then combining with the errors of the second part for another -`\operatorname{fma}` operation: - -.. math:: - err = \operatorname{fma}(u, err(P), err_1) - - -Accurate phase -============== - -Extending range reduction -------------------------- - -Since the output `u = r(1 + m_x) - 1` of the fast phase's range reduction -is computed exactly, we can apply further range reduction steps by -using the following formula: - -.. math:: - u_{i + 1} = r_i(1 + u_i) - 1 = u_i \cdot r_i + (r_i - 1), - -where `|u_i| < 2^{-N_i}` and `u_0 = u` is representable in double precision. - -Let `s_i = r_i - 1`, then we can rewrite it as: - -.. math:: - u_{i + 1} &= (1 + s_i)(1 + u_i) - 1 \\ - &= s_i u_i + u_i + s_i \\ - &= u_i (1 + s_i) + s_i - &= s_i (1 + u_i) + u_i. - -Then the bound on `u_{i + 1}` is translated to `s_i` as: - -.. math:: - \frac{-2^{-N_{i + 1}} - u_i}{1 + u_i} < s_i < \frac{2^{-N_{i + 1}} - u_i}{1 + u_i}. - -Let say we divide the interval `[0, 2^-{N_i})` into `2^{M_i}` subintervals -evenly and use the index `k` such that: - -.. math:: - k 2^{-N_i - M_i} \leq u_i < (k + 1) 2^{-N_i - M_i}, - -to look-up for the reduction constant `s_{i, k}`. In other word, `k` is given -by the formula: - -.. math:: - k = \left\lfloor 2^{N_i + M_i} u_i \right\rfloor - -Notice that our reduction constant `s_{i, k}` must work for all `u_i` in the -interval `I = \{ v: k 2^{-N_i - M_i} \leq v < (k + 1) 2^{-N_i - M_i} \}`, -so it is bounded by: - -.. math:: - \sup_{v \in I} \frac{-2^{-N_{i + 1}} - v}{1 + v} < s_{i, k} < \inf_{v \in I} \frac{2^{-N_{i + 1}} - v}{1 + v} - -For a fixed constant `|C| < 1`, let `f(v) = \frac{C - v}{1 + v}`, then its derivative -is: - -.. math:: - f'(v) = \frac{(-1)(1 + v) - (1)(C - v)}{(1 + v)^2} = \frac{-1 - C}{(1 + v)^2}. - -Since `|C| < 1`, `f'(v) < 0` for all `v \neq -1`, so: - -.. math:: - \sup_{v \in I} f(v) &= f \left( \inf\{ v: v \in I \} \right) - = f \left( k 2^{-N_i - M_i} \right) \\ - \inf_{v \in I} f(v) &= f \left( \sup\{ v: v \in I \} \right) - = f \left( (k + 1) 2^{-N_i - M_i} \right) - -Hence we have the following bound on `s_{i, k}`: - -.. math:: - \frac{-2^{-N_{i + 1}} - k 2^{-N_i - M_i}}{1 + k 2^{-N_i - M_i}} < s_{i, k} - \leq \frac{2^{-N_{i + 1}} - (k + 1) 2^{-N_i - M_i}}{1 + (k + 1) 2^{-N_i - M_i}} - -This interval is of length: - -.. math:: - l &= \frac{2^{-N_{i + 1}} - (k + 1) 2^{-N_i - M_i}}{1 + (k + 1) 2^{-N_i - M_i}} - - \frac{-2^{-N_{i + 1}} - k 2^{-N_i - M_i}}{1 + k 2^{-N_i - M_i}} \\ - &= \frac{2^{-N_{i + 1} + 1} - 2^{-N_i - M_i} + (2k + 1) 2^{-N_{i + 1} - N_i - M_i}} - {(1 + k 2^{-N_i - M_i})(1 + (k + 1) 2^{-N_i -M_i})} - -So in order to be able to find `s_{i, k}`, we need that: - -.. math:: - 2^{-N_{i + 1} + 1} - 2^{-N_i - M_i} + (2k + 1) 2^{-N_{i + 1} - N_i - M_i} > 0 - -This give us the following bound on `N_{i + 1}`: - -.. math:: - N_{i + 1} \leq N_i + M_i + 1. - -To make the range reduction effective, we will want to maximize `N_{i + 1}`, so -let consider the two cases: `N_{i + 1} = N_i + M_i + 1` and -`N_{i + 1} = N_i + M_i`. - - - -The optimal choice to balance between maximizing `N_{i + 1}` and minimizing the -precision needed for `s_{i, k}` is: - -.. math:: - N_{i + 1} = N_i + M_i, - -and in this case, the optimal `\operatorname{ulp}(s_{i, k})` is: - -.. math:: - \operatorname{ulp}(s_{i, k}) = 2^{-N_i - M_i} - -and the corresponding `\operatorname{ulp}(u_{i + 1})` is: - -.. math:: - \operatorname{ulp}(u_{i + 1}) &= \operatorname{ulp}(u_i) \operatorname{ulp}(s_{i, k}) \\ - &= \operatorname{ulp}(u_i) \cdot 2^{-N_i - M_i} \\ - &= \operatorname{ulp}(u_0) \cdot 2^{-N_0 - M_0} \cdot 2^{-N_0 - M_0 - M_1} \cdots 2^{-N_0 - M_0 - M_1 - \cdots - M_i} \\ - &= 2^{-N_0 - 53} \cdot 2^{-N_0 - M_0} \cdot 2^{-N_0 - M_0 - M_1} \cdots 2^{-N_0 - M_0 - M_1 - \cdots - M_i} - -Since `|u_{i + 1}| < 2^{-N_{i + 1}} = 2^{-N_0 - M_1 - ... -M_i}`, the precision -of `u_{i + 1}` is: - -.. math:: - \operatorname{prec}(u_{i + 1}) &= (N_0 + 53) + (N_0 + M_0) + \cdots + - (N_0 + M_0 + \cdots + M_i) - (N_0 + M_0 + \cdots + M_i) \\ - &= (i + 1) N_0 + i M_0 + (i - 1) M_1 + \cdots + M_{i - 1} + 53 - -If we choose to have the same `M_0 = M_1 = \cdots = M_i = M`, this can be -simplified to: - -.. math:: - \operatorname{prec}(u_{i + 1}) = (i + 1) N_0 + \frac{i(i + 1)}{2} \cdot M + 53. - -We summarize the precision analysis for extending the range reduction in the -table below: - -+-------+-----+-----------+------------+--------------+-----------------+-------------------+ -| `N_0` | `M` | No. steps | Table size | Output bound | ulp(`s_{i, k}`) | prec(`u_{i + 1}`) | -+-------+-----+-----------+------------+--------------+-----------------+-------------------+ -| 7 | 4 | 1 | 32 | `2^{-11}` | `2^{-12}` | 60 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 2 | 64 | `2^{-15}` | `2^{-16}` | 71 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 3 | 96 | `2^{-19}` | `2^{-20}` | 86 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 4 | 128 | `2^{-23}` | `2^{-24}` | 105 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 5 | 160 | `2^{-27}` | `2^{-28}` | 128 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 6 | 192 | `2^{-31}` | `2^{-32}` | 155 | -| +-----+-----------+------------+--------------+-----------------+-------------------+ -| | 5 | 3 | 192 | `2^{-22}` | `2^{-23}` | 89 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 4 | 256 | `2^{-27}` | `2^{-28}` | 111 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 5 | 320 | `2^{-32}` | `2^{-33}` | 138 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 6 | 384 | `2^{-37}` | `2^{-38}` | 170 | -| +-----+-----------+------------+--------------+-----------------+-------------------+ -| | 6 | 3 | 384 | `2^{-25}` | `2^{-26}` | 92 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 4 | 512 | `2^{-31}` | `2^{-32}` | 117 | -| +-----+-----------+------------+--------------+-----------------+-------------------+ -| | 7 | 1 | 256 | `2^{-24}` | `2^{-15}` | 60 | -| | +-----------+------------+--------------+-----------------+-------------------+ -| | | 2 | 512 | `2^{-21}` | `2^{-22}` | 74 | -+-------+-----+-----------+------------+--------------+-----------------+-------------------+ - -where: - -- Number of steps = `i + 1` -- Table size = `(i + 1) 2^{M + 1}` -- Output bound = `2^{-N_{i + 1}} = 2^{-N_0 - (i + 1) M}` -- `\operatorname{ulp}(s_{i, k}) = 2^{-N_{i + 1} - 1}` -- `\operatorname{prec}(u_{i + 1}) = (i + 1) N_0 + \frac{i(i + 1)}{2} \cdot M + 53` diff --git a/libc/docs/math/stdfix.rst b/libc/docs/math/stdfix.rst deleted file mode 100644 index d8dcb0cfa4c5..000000000000 --- a/libc/docs/math/stdfix.rst +++ /dev/null @@ -1,149 +0,0 @@ -================ -StdFix Functions -================ - -.. include:: ../check.rst - -Standards and Goals -------------------- - -- stdfix.h is specified in the `ISO/IEC TR 18037:2008 <https://www.iso.org/standard/51126.html>`_, - C extensions to support embedded processors . - -- Its `specifications <https://standards.iso.org/ittf/PubliclyAvailableStandards/c051126_ISO_IEC_TR_18037_2008.zip>`_. - -- Our goal is to implement a complete set of math functions for fixed point - types, most of them are currently not included in the ISO/IEC TR - 18037:2008 standard. Our math functions for fixed point types are modeled - after the C99/C23 math functions for floating point types. - ---------------- -Source location ---------------- - -- The main source for fixed-point functions is located at: - ``libc/src/stdfix`` with subdirectories for internal implementations. - ---------------------- -Implementation Status ---------------------- - -Requirements -============ - -- In order to build LLVM libc to support fixed-point arithmetics, we need the - compiler to support the basic fixed-point types `_Fract` and `_Accum` in - C++. - -- For the users to be able to use the generated headers, their compiler needs - to support `_Fract` and `_Accum` types in C or C++. - -- This compiler support is checked at the beginning of - `libc/include/llvm-libc-macros/stdfix-macros.h <https://github.com/llvm/llvm-project/tree/main/libc/include/llvm-libc-macros/stdfix-macros.h>`_. - - - -Predefined Macros -================= - -- We use the macro `LIBC_COMPILER_HAS_FIXED_POINT` to specify whether the - compiler support the fixed-point types. - -- Other predefined precision macros specified in section 7.18a.3 are defined - in `libc/include/llvm-libc-macros/stdfix-macros.h <https://github.com/llvm/llvm-project/tree/main/libc/include/llvm-libc-macros/stdfix-macros.h>`_ - using the default configuration of `typical desktop processor` in section - A.3. - - -Fixed-point Arithmetics -======================= - -The following functions are included in the ISO/IEC TR 18037:2008 standard. - -+---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+ -| Function Name | _Fract (r) | _Accum (k) | -| +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+ -| | short (hr) | _ (r) | long (lr) | short (hk) | _ (k) | long (lk) | -| +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) | -+===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+ -| abs | | |check| | | |check| | | |check| | | |check| | | |check| | | |check| | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| bits\* | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| \*bits | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| countls | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| divi | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| idivi | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| muli | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| rdivi | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| round | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ - -================== ========= -Type Generic Macro Available -================== ========= -absfx -countlsfx -roundfx -================== ========= - - -Higher math functions -===================== - -The following math functions are modeled after C99/C23 math functions for -floating point types, but are not part of the ISO/IEC TR 18037:2008 spec. - -+---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+ -| Function Name | _Fract (r) | _Accum (k) | -| +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+ -| | short (hr) | _ (r) | long (lr) | short (hk) | _ (k) | long (lk) | -| +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) | -+===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+ -| cos | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| exp | | | | | | | | |check| | | |check| | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| log | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| sin | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| sqrt | |check| | | |check| | | |check| | | |check| | | |check| | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| tan | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ - - -Conversion Functions -==================== - -The following conversion functions are included in the ISO/IEC TR 18037:2008 -standard. - -+---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+ -| Function Name | _Fract (r) | _Accum (k) | -| +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+ -| | short (hr) | _ (r) | long (lr) | short (hk) | _ (k) | long (lk) | -| +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) | -+===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+ -| fprintf | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| fscanf | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ -| strtofx | | | | | | | | | | | | | -+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ - - -Warnings -======== - -This is currently a work-in-progress, its headers, macros, and ABI are still unstable, and might be modified. |