libc/docs/math/index.rst

   1 .. _math:
   2
   3 ==============
   4 Math Functions
   5 ==============
   6
   7 .. include:: ../check.rst
   8
   9 .. raw:: html
  10
  11     <style> .green {color:green} </style>
  12
  13 .. role:: green
  14
  15 .. toctree::
  16   :hidden:
  17
  18   log.rst
  19   stdfix.rst
  20
  21
  22 .. contents:: Table of Contents
  23   :depth: 4
  24   :local:
  25
  26 Source Locations
  27 ================
  28
  29 - The main source is located at: `libc/src/math <https://github.com/llvm/llvm-project/tree/main/libc/src/math>`_.
  30 - The tests are located at: `libc/test/src/math <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math>`_.
  31 - The floating point utilities are located at: `libc/src/__support/FPUtil <https://github.com/llvm/llvm-project/tree/main/libc/src/__support/FPUtil>`_.
  32
  33 Implementation Requirements / Goals
  34 ===================================
  35
  36 * The highest priority is to be as accurate as possible, according to the C and
  37   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>`_.
  38   The current rounding mode of the floating point environment is used to perform
  39   computations and produce the final results.
  40
  41   - To test for correctness, we compare the outputs with other correctly rounded
  42     multiple-precision math libraries such as the `GNU MPFR library <https://www.mpfr.org/>`_
  43     or the `CORE-MATH library <https://core-math.gitlabpages.inria.fr/>`_.
  44
  45 * Our next requirement is that the outputs are consistent across all platforms.
  46   Notice that the consistency requirement will be satisfied automatically if the
  47   implementation is correctly rounded.
  48
  49 * Our last requirement for the implementations is to have good and predicable
  50   performance:
  51
  52   - The average performance should be comparable to other ``libc``
  53     implementations.
  54   - The worst case performance should be within 10X-20X of the average.
  55   - Platform-specific implementations or instructions could be added whenever it
  56     makes sense and provides significant performance boost.
  57
  58 * For other use cases that have strict requirements on the code size, memory
  59   footprint, or latency, such as embedded systems, we will aim to be as accurate
  60   as possible within the memory or latency budgets, and consistent across all
  61   platforms.
  62
  63
  64 Add a new math function to LLVM libc
  65 ====================================
  66
  67 * 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>`_.
  68
  69 Implementation Status
  70 =====================
  71
  72 * To check math functions enabled for Linux:
  73
  74   - `linux-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64/entrypoints.txt>`_
  75
  76   - `linux-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64/entrypoints.txt>`_
  77
  78   - `linux-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm/entrypoints.txt>`_
  79
  80   - `linux-riscv and linux-riscv32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/riscv/entrypoints.txt>`_
  81
  82 * To check math functions enabled for Windows:
  83
  84   - `windows-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_
  85
  86   - windows-aarch64 - to be added
  87
  88 * To check math functions enabled for macOS:
  89
  90   - `darwin-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/x86_64/entrypoints.txt>`_
  91
  92   - `darwin-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/arm/entrypoints.txt>`_
  93
  94 * To check math functions enabled for GPU:
  95
  96   - `gpu-entrypoints <https://github.com/llvm/llvm-project/tree/main/libc/config/gpu/entrypoints.txt>`_
  97
  98 * To check math functions enabled for embedded system:
  99
 100   - `baremetal-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/baremetal/arm/entrypoints.txt>`_
 101
 102   - baremetal-riscv32 - to be added
 103
 104
 105 Basic Operations
 106 ================
 107
 108 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 109 | <Func>           | <Func_f> (float) | <Func> (double) | <Func_l> (long double) | <Func_f16> (float16) | <Func_f128> (float128) | C23 Definition Section | C23 Error Handling Section |
 110 +==================+==================+=================+========================+======================+========================+========================+============================+
 111 | ceil             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.1               | F.10.6.1                   |
 112 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 113 | canonicalize     | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.11.7              | F.10.8.7                   |
 114 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 115 | copysign         | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.11.1              | F.10.8.1                   |
 116 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 117 | dadd             | N/A              | N/A             | |check|                | N/A                  | |check|\*              | 7.12.14.1              | F.10.11                    |
 118 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 119 | ddiv             | N/A              | N/A             | |check|                | N/A                  | |check|\*              | 7.12.14.4              | F.10.11                    |
 120 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 121 | dfma             | N/A              | N/A             | |check|                | N/A                  | |check|\*              | 7.12.14.5              | F.10.11                    |
 122 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 123 | dmul             | N/A              | N/A             | |check|                | N/A                  | |check|\*              | 7.12.14.3              | F.10.11                    |
 124 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 125 | dsub             | N/A              | N/A             | |check|                | N/A                  | |check|\*              | 7.12.14.2              | F.10.11                    |
 126 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 127 | f16add           | |check|\*        | |check|\*       | |check|\*              | N/A                  | |check|                | 7.12.14.1              | F.10.11                    |
 128 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 129 | f16div           | |check|\*        | |check|\*       | |check|\*              | N/A                  | |check|                | 7.12.14.4              | F.10.11                    |
 130 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 131 | f16fma           | |check|\*        | |check|\*       | |check|\*              | N/A                  | |check|                | 7.12.14.5              | F.10.11                    |
 132 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 133 | f16mul           | |check|\*        | |check|\*       | |check|\*              | N/A                  | |check|                | 7.12.14.5              | F.10.11                    |
 134 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 135 | f16sub           | |check|\*        | |check|\*       | |check|\*              | N/A                  | |check|                | 7.12.14.2              | F.10.11                    |
 136 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 137 | fabs             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.7.3               | F.10.4.3                   |
 138 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 139 | fadd             | N/A              | |check|         | |check|                | N/A                  | |check|                | 7.12.14.1              | F.10.11                    |
 140 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 141 | fdim             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.1              | F.10.9.1                   |
 142 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 143 | fdiv             | N/A              | |check|         | |check|                | N/A                  | |check|\*              | 7.12.14.4              | F.10.11                    |
 144 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 145 | ffma             | N/A              | |check|         | |check|                | N/A                  | |check|\*              | 7.12.14.5              | F.10.11                    |
 146 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 147 | floor            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.2               | F.10.6.2                   |
 148 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 149 | fmax             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.2              | F.10.9.2                   |
 150 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 151 | fmaximum         | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.4              | F.10.9.4                   |
 152 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 153 | fmaximum_mag     | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.6              | F.10.9.4                   |
 154 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 155 | fmaximum_mag_num | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.10             | F.10.9.5                   |
 156 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 157 | fmaximum_num     | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.8              | F.10.9.5                   |
 158 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 159 | fmin             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.3              | F.10.9.3                   |
 160 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 161 | fminimum         | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.5              | F.10.9.4                   |
 162 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 163 | fminimum_mag     | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.7              | F.10.9.4                   |
 164 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 165 | fminimum_mag_num | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.11             | F.10.9.5                   |
 166 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 167 | fminimum_num     | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.12.9              | F.10.9.5                   |
 168 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 169 | fmod             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.10.1              | F.10.7.1                   |
 170 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 171 | fmul             | N/A              | |check|         | |check|                | N/A                  | |check|\*              | 7.12.14.3              | F.10.11                    |
 172 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 173 | frexp            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.7               | F.10.3.7                   |
 174 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 175 | fromfp           | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.10              | F.10.6.10                  |
 176 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 177 | fromfpx          | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.11              | F.10.6.11                  |
 178 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 179 | fsub             | N/A              | |check|         | |check|                | N/A                  | |check|\*              | 7.12.14.2              | F.10.11                    |
 180 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 181 | getpayload       | |check|          | |check|         | |check|                | |check|              | |check|                | F.10.13.1              | N/A                        |
 182 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 183 | ilogb            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.8               | F.10.3.8                   |
 184 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 185 | iscanonical      | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.3.2               | N/A                        |
 186 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 187 | issignaling      | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.3.8               | N/A                        |
 188 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 189 | ldexp            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.9               | F.10.3.9                   |
 190 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 191 | llogb            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.10              | F.10.3.10                  |
 192 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 193 | llrint           | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.5               | F.10.6.5                   |
 194 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 195 | llround          | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.7               | F.10.6.7                   |
 196 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 197 | logb             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.17              | F.10.3.17                  |
 198 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 199 | lrint            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.5               | F.10.6.5                   |
 200 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 201 | lround           | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.7               | F.10.6.7                   |
 202 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 203 | modf             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.18              | F.10.3.18                  |
 204 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 205 | nan              | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.11.2              | F.10.8.2                   |
 206 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 207 | nearbyint        | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.3               | F.10.6.3                   |
 208 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 209 | nextafter        | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.11.3              | F.10.8.3                   |
 210 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 211 | nextdown         | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.11.6              | F.10.8.6                   |
 212 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 213 | nexttoward       | |check|          | |check|         | |check|                | |check|              | N/A                    | 7.12.11.4              | F.10.8.4                   |
 214 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 215 | nextup           | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.11.5              | F.10.8.5                   |
 216 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 217 | remainder        | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.10.2              | F.10.7.2                   |
 218 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 219 | remquo           | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.10.3              | F.10.7.3                   |
 220 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 221 | rint             | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.4               | F.10.6.4                   |
 222 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 223 | round            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.6               | F.10.6.6                   |
 224 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 225 | roundeven        | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.8               | F.10.6.8                   |
 226 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 227 | scalbln          | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.19              | F.10.3.19                  |
 228 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 229 | scalbn           | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.6.19              | F.10.3.19                  |
 230 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 231 | setpayload       | |check|          | |check|         | |check|                | |check|              | |check|                | F.10.13.2              | N/A                        |
 232 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 233 | setpayloadsig    | |check|          | |check|         | |check|                | |check|              | |check|                | F.10.13.3              | N/A                        |
 234 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 235 | totalorder       | |check|          | |check|         | |check|                | |check|              | |check|                | F.10.12.1              | N/A                        |
 236 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 237 | totalordermag    | |check|          | |check|         | |check|                | |check|              | |check|                | F.10.12.2              | N/A                        |
 238 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 239 | trunc            | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.9               | F.10.6.9                   |
 240 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 241 | ufromfp          | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.10              | F.10.6.10                  |
 242 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 243 | ufromfpx         | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.9.11              | F.10.6.11                  |
 244 +------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 245
 246
 247 Higher Math Functions
 248 =====================
 249
 250 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 251 | <Func>    | <Func_f> (float) | <Func> (double) | <Func_l> (long double) | <Func_f16> (float16) | <Func_f128> (float128) | C23 Definition Section | C23 Error Handling Section |
 252 +===========+==================+=================+========================+======================+========================+========================+============================+
 253 | acos      | |check|          |                 |                        |                      |                        | 7.12.4.1               | F.10.1.1                   |
 254 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 255 | acosh     | |check|          |                 |                        |                      |                        | 7.12.5.1               | F.10.2.1                   |
 256 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 257 | acospi    |                  |                 |                        |                      |                        | 7.12.4.8               | F.10.1.8                   |
 258 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 259 | asin      | |check|          |                 |                        |                      |                        | 7.12.4.2               | F.10.1.2                   |
 260 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 261 | asinh     | |check|          |                 |                        |                      |                        | 7.12.5.2               | F.10.2.2                   |
 262 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 263 | asinpi    |                  |                 |                        |                      |                        | 7.12.4.9               | F.10.1.9                   |
 264 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 265 | atan      | |check|          |                 |                        |                      |                        | 7.12.4.3               | F.10.1.3                   |
 266 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 267 | atan2     | |check|          | 1 ULP           |                        |                      |                        | 7.12.4.4               | F.10.1.4                   |
 268 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 269 | atan2pi   |                  |                 |                        |                      |                        | 7.12.4.11              | F.10.1.11                  |
 270 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 271 | atanh     | |check|          |                 |                        |                      |                        | 7.12.5.3               | F.10.2.3                   |
 272 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 273 | atanpi    |                  |                 |                        |                      |                        | 7.12.4.10              | F.10.1.10                  |
 274 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 275 | cbrt      | |check|          | |check|         |                        |                      |                        | 7.12.7.1               | F.10.4.1                   |
 276 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 277 | compoundn |                  |                 |                        |                      |                        | 7.12.7.2               | F.10.4.2                   |
 278 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 279 | cos       | |check|          | |check|         |                        |                      |                        | 7.12.4.5               | F.10.1.5                   |
 280 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 281 | cosh      | |check|          |                 |                        | |check|              |                        | 7.12.5.4               | F.10.2.4                   |
 282 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 283 | cospi     | |check|          |                 |                        | |check|              |                        | 7.12.4.12              | F.10.1.12                  |
 284 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 285 | dsqrt     | N/A              | N/A             |   |check|              | N/A                  |       |check|\*        | 7.12.14.6              | F.10.11                    |
 286 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 287 | erf       | |check|          |                 |                        |                      |                        | 7.12.8.1               | F.10.5.1                   |
 288 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 289 | erfc      |                  |                 |                        |                      |                        | 7.12.8.2               | F.10.5.2                   |
 290 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 291 | exp       | |check|          | |check|         |                        | |check|              |                        | 7.12.6.1               | F.10.3.1                   |
 292 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 293 | exp10     | |check|          | |check|         |                        | |check|              |                        | 7.12.6.2               | F.10.3.2                   |
 294 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 295 | exp10m1   | |check|          |                 |                        | |check|              |                        | 7.12.6.3               | F.10.3.3                   |
 296 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 297 | exp2      | |check|          | |check|         |                        | |check|              |                        | 7.12.6.4               | F.10.3.4                   |
 298 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 299 | exp2m1    | |check|          |                 |                        | |check|              |                        | 7.12.6.5               | F.10.3.5                   |
 300 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 301 | expm1     | |check|          | |check|         |                        | |check|              |                        | 7.12.6.6               | F.10.3.6                   |
 302 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 303 | fma       | |check|          | |check|         |                        |                      |                        | 7.12.13.1              | F.10.10.1                  |
 304 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 305 | f16sqrt   | |check|\*        | |check|\*       | |check|\*              | N/A                  | |check|                | 7.12.14.6              | F.10.11                    |
 306 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 307 | fsqrt     | N/A              | |check|         |  |check|               | N/A                  | |check|\*              | 7.12.14.6              | F.10.11                    |
 308 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 309 | hypot     | |check|          | |check|         |                        |                      |                        | 7.12.7.4               | F.10.4.4                   |
 310 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 311 | lgamma    |                  |                 |                        |                      |                        | 7.12.8.3               | F.10.5.3                   |
 312 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 313 | log       | |check|          | |check|         |                        | |check|              |                        | 7.12.6.11              | F.10.3.11                  |
 314 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 315 | log10     | |check|          | |check|         |                        | |check|              |                        | 7.12.6.12              | F.10.3.12                  |
 316 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 317 | log10p1   |                  |                 |                        |                      |                        | 7.12.6.13              | F.10.3.13                  |
 318 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 319 | log1p     | |check|          | |check|         |                        |                      |                        | 7.12.6.14              | F.10.3.14                  |
 320 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 321 | log2      | |check|          | |check|         |                        | |check|              |                        | 7.12.6.15              | F.10.3.15                  |
 322 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 323 | log2p1    |                  |                 |                        |                      |                        | 7.12.6.16              | F.10.3.16                  |
 324 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 325 | logp1     |                  |                 |                        |                      |                        | 7.12.6.14              | F.10.3.14                  |
 326 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 327 | pow       | |check|          | 1 ULP           |                        |                      |                        | 7.12.7.5               | F.10.4.5                   |
 328 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 329 | powi\*    |                  |                 |                        |                      |                        |                        |                            |
 330 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 331 | pown      |                  |                 |                        |                      |                        | 7.12.7.6               | F.10.4.6                   |
 332 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 333 | powr      |                  |                 |                        |                      |                        | 7.12.7.7               | F.10.4.7                   |
 334 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 335 | rootn     |                  |                 |                        |                      |                        | 7.12.7.8               | F.10.4.8                   |
 336 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 337 | rsqrt     |                  |                 |                        |                      |                        | 7.12.7.9               | F.10.4.9                   |
 338 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 339 | sin       | |check|          | |check|         |                        |                      |                        | 7.12.4.6               | F.10.1.6                   |
 340 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 341 | sincos    | |check|          | |check|         |                        |                      |                        |                        |                            |
 342 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 343 | sinh      | |check|          |                 |                        | |check|              |                        | 7.12.5.5               | F.10.2.5                   |
 344 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 345 | sinpi     | |check|          |                 |                        |  |check|             |                        | 7.12.4.13              | F.10.1.13                  |
 346 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 347 | sqrt      | |check|          | |check|         | |check|                | |check|              | |check|                | 7.12.7.10              | F.10.4.10                  |
 348 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 349 | tan       | |check|          | |check|         |                        |                      |                        | 7.12.4.7               | F.10.1.7                   |
 350 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 351 | tanh      | |check|          |                 |                        | |check|              |                        | 7.12.5.6               | F.10.2.6                   |
 352 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 353 | tanpi     |                  |                 |                        | |check|              |                        | 7.12.4.14              | F.10.1.14                  |
 354 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 355 | tgamma    |                  |                 |                        |                      |                        | 7.12.8.4               | F.10.5.4                   |
 356 +-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+
 357
 358 Legends:
 359
 360 * |check| : correctly rounded for all 4 rounding modes.
 361 * CR: correctly rounded for the default rounding mode (round-to-the-nearest,
 362   tie-to-even).
 363 * x ULPs: largest errors recorded.
 364 * N/A: Not defined in the standard or will not be added.
 365 * \*: LLVM libc extension.
 366
 367 ..
 368   TODO(lntue): Add a new page to discuss about the algorithms used in the
 369   implementations and include the link here.
 370
 371
 372 Performance
 373 ===========
 374
 375 * 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>`_.
 376
 377 * We also use the *perf* tool from the `CORE-MATH <https://core-math.gitlabpages.inria.fr/>`_
 378   project: `link <https://gitlab.inria.fr/core-math/core-math/-/tree/master>`_.
 379   The performance results from the CORE-MATH's perf tool are reported in the
 380   table below, using the system library as reference (such as the `GNU C library <https://www.gnu.org/software/libc/>`_
 381   on Linux). Fmod performance results obtained with "performance_testing".
 382
 383 +--------------+-------------------------------+-------------------------------+-------------------------------------+----------------------------------------------------------------------+
 384 | <Func>       | Reciprocal throughput (clk)   | Latency (clk)                 | Testing ranges                      | Testing configuration                                                |
 385 |              +-----------+-------------------+-----------+-------------------+                                     +-------------+-------------------------+--------------+---------------+
 386 |              | LLVM libc | Reference (glibc) | LLVM libc | Reference (glibc) |                                     | CPU         | OS                      | Compiler     | Special flags |
 387 +==============+===========+===================+===========+===================+=====================================+=============+=========================+==============+===============+
 388 | acosf        |        24 |                29 |        62 |                77 | :math:`[-1, 1]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 389 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 390 | acoshf       |        18 |                26 |        73 |                74 | :math:`[1, 21]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 391 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 392 | asinf        |        23 |                27 |        62 |                62 | :math:`[-1, 1]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 393 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 394 | asinhf       |        21 |                39 |        77 |                91 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 395 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 396 | atanf        |        27 |                29 |        79 |                68 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 397 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 398 | atanhf       |        18 |                66 |        68 |               133 | :math:`[-1, 1]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 399 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 400 | cosf         |        13 |                32 |        53 |                59 | :math:`[0, 2\pi]`                   | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 401 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 402 | coshf        |        14 |                20 |        50 |                48 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 403 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 404 | expf         |         9 |                 7 |        44 |                38 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 405 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 406 | exp10f       |        10 |                 8 |        40 |                38 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 407 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 408 | exp2f        |         9 |                 6 |        35 |                31 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 409 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 410 | expm1f       |         9 |                44 |        42 |               121 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 411 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 412 | fmodf        |        73 |               263 |        -  |                 - | [MIN_NORMAL, MAX_NORMAL]            | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 413 |              +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 414 |              |         9 |                11 |        -  |                 - | [0, MAX_SUBNORMAL]                  | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 415 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 416 | fmod         |       595 |              3297 |        -  |                 - | [MIN_NORMAL, MAX_NORMAL]            | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 417 |              +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 418 |              |        14 |                13 |        -  |                 - | [0, MAX_SUBNORMAL]                  | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 419 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 420 | hypotf       |        25 |                15 |        64 |                49 | :math:`[-10, 10] \times [-10, 10]`  | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 421 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 422 | logf         |        12 |                10 |        56 |                46 | :math:`[e^{-1}, e]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 423 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 424 | log10f       |         9 |                17 |        35 |                48 | :math:`[e^{-1}, e]`                 | Ryzen 5900X | Ubuntu 22.04 LTS x86_64 | Clang 15.0.6 | FMA           |
 425 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 426 | 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           |
 427 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 428 | log2f        |        13 |                10 |        57 |                46 | :math:`[e^{-1}, e]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 429 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 430 | sinf         |        12 |                25 |        51 |                57 | :math:`[-\pi, \pi]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 431 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 432 | sincosf      |        19 |                30 |        57 |                68 | :math:`[-\pi, \pi]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 433 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 434 | sinhf        |        13 |                63 |        48 |               137 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 435 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 436 | tanf         |        16 |                50 |        61 |               107 | :math:`[-\pi, \pi]`                 | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 437 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 438 | tanhf        |        13 |                55 |        57 |               123 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 439 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 440
 441 Algorithms + Implementation Details
 442 ===================================
 443
 444 * :doc:`log`
 445
 446 Fixed-point Arithmetics
 447 =======================
 448
 449 * :doc:`stdfix`
 450
 451 References
 452 ==========
 453
 454 * `CRLIBM <https://hal-ens-lyon.archives-ouvertes.fr/ensl-01529804/file/crlibm.pdf>`_.
 455 * `RLIBM <https://people.cs.rutgers.edu/~sn349/rlibm/>`_.
 456 * `Sollya <https://www.sollya.org/>`_.
 457 * `The CORE-MATH Project <https://core-math.gitlabpages.inria.fr/>`_.
 458 * `The GNU C Library (glibc) <https://www.gnu.org/software/libc/>`_.
 459 * `The GNU MPFR Library <https://www.mpfr.org/>`_.