libc/docs/math/stdfix.rst

   1 ================
   2 StdFix Functions
   3 ================
   4
   5 .. include:: ../check.rst
   6
   7 Standards and Goals
   8 -------------------
   9
  10 -   stdfix.h is specified in the `ISO/IEC TR 18037:2008 <https://www.iso.org/standard/51126.html>`_,
  11     C extensions to support embedded processors .
  12
  13 -   Its `specifications <https://standards.iso.org/ittf/PubliclyAvailableStandards/c051126_ISO_IEC_TR_18037_2008.zip>`_.
  14
  15 -   Our goal is to implement a complete set of math functions for fixed point
  16     types, most of them are currently not included in the ISO/IEC TR
  17     18037:2008 standard.  Our math functions for fixed point types are modeled
  18     after the C99/C23 math functions for floating point types.
  19
  20 ---------------
  21 Source location
  22 ---------------
  23
  24 -   The main source for fixed-point functions is located at:
  25     ``libc/src/stdfix`` with subdirectories for internal implementations.
  26
  27 ---------------------
  28 Implementation Status
  29 ---------------------
  30
  31 Requirements
  32 ============
  33
  34 -   In order to build LLVM libc to support fixed-point arithmetics, we need the
  35     compiler to support the basic fixed-point types `_Fract` and `_Accum` in
  36     C++.
  37
  38 -   For the users to be able to use the generated headers, their compiler needs
  39     to support `_Fract` and `_Accum` types in C or C++.
  40
  41 -   This compiler support is checked at the beginning of
  42     `libc/include/llvm-libc-macros/stdfix-macros.h <https://github.com/llvm/llvm-project/tree/main/libc/include/llvm-libc-macros/stdfix-macros.h>`_.
  43
  44
  45
  46 Predefined Macros
  47 =================
  48
  49 -   We use the macro `LIBC_COMPILER_HAS_FIXED_POINT` to specify whether the
  50     compiler support the fixed-point types.
  51
  52 -   Other predefined precision macros specified in section 7.18a.3 are defined
  53     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>`_
  54     using the default configuration of `typical desktop processor` in section
  55     A.3.
  56
  57
  58 Fixed-point Arithmetics
  59 =======================
  60
  61 The following functions are included in the ISO/IEC TR 18037:2008 standard.
  62
  63 +---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+
  64 | Function Name | _Fract (r)                                                                               | _Accum (k)                                                                               |
  65 |               +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+
  66 |               | short (hr)                   | _ (r)                      | long (lr)                    | short (hk)                   | _ (k)                      | long (lk)                    |
  67 |               +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  68 |               | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) |
  69 +===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+
  70 | abs           |                | |check|     |               | |check|    |                | |check|     |                | |check|     |               | |check|    |                | |check|     |
  71 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  72 | bits\*        |                |             |               |            |                |             |                |             |               |            |                |             |
  73 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  74 | \*bits        |                |             |               |            |                |             |                |             |               |            |                |             |
  75 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  76 | countls       |                |             |               |            |                |             |                |             |               |            |                |             |
  77 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  78 | divi          |                |             |               |            |                |             |                |             |               |            |                |             |
  79 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  80 | idivi         |                |             |               |            |                |             |                |             |               |            |                |             |
  81 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  82 | muli          |                |             |               |            |                |             |                |             |               |            |                |             |
  83 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  84 | rdivi         |                |             |               |            |                |             |                |             |               |            |                |             |
  85 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  86 | round         | |check|        | |check|     | |check|       | |check|    | |check|        | |check|     | |check|        | |check|     | |check|       | |check|    | |check|        | |check|     |
  87 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
  88
  89 ================== =========
  90 Type Generic Macro Available
  91 ================== =========
  92 absfx
  93 countlsfx
  94 roundfx
  95 ================== =========
  96
  97
  98 Higher math functions
  99 =====================
 100
 101 The following math functions are modeled after C99/C23 math functions for
 102 floating point types, but are not part of the ISO/IEC TR 18037:2008 spec.
 103
 104 +---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+
 105 | Function Name | _Fract (r)                                                                               | _Accum (k)                                                                               |
 106 |               +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+
 107 |               | short (hr)                   | _ (r)                      | long (lr)                    | short (hk)                   | _ (k)                      | long (lk)                    |
 108 |               +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 109 |               | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) |
 110 +===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+
 111 | cos           |                |             |               |            |                |             |                |             |               |            |                |             |
 112 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 113 | exp           |                |             |               |            |                |             |                | |check|     |               | |check|    |                |             |
 114 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 115 | log           |                |             |               |            |                |             |                |             |               |            |                |             |
 116 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 117 | sin           |                |             |               |            |                |             |                |             |               |            |                |             |
 118 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 119 | sqrt          | |check|        |             | |check|       |            | |check|        |             | |check|        |             | |check|       |            |                |             |
 120 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 121 | tan           |                |             |               |            |                |             |                |             |               |            |                |             |
 122 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 123
 124
 125 Conversion Functions
 126 ====================
 127
 128 The following conversion functions are included in the ISO/IEC TR 18037:2008
 129 standard.
 130
 131 +---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+
 132 | Function Name | _Fract (r)                                                                               | _Accum (k)                                                                               |
 133 |               +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+
 134 |               | short (hr)                   | _ (r)                      | long (lr)                    | short (hk)                   | _ (k)                      | long (lk)                    |
 135 |               +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 136 |               | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) |
 137 +===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+
 138 | fprintf       |                |             |               |            |                |             |                |             |               |            |                |             |
 139 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 140 | fscanf        |                |             |               |            |                |             |                |             |               |            |                |             |
 141 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 142 | strtofx       |                |             |               |            |                |             |                |             |               |            |                |             |
 143 +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
 144
 145
 146 Warnings
 147 ========
 148
 149 This is currently a work-in-progress, its headers, macros, and ABI are still unstable, and might be modified.