1================ 2StdFix Functions 3================ 4 5.. include:: ../../check.rst 6 7Standards 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--------------- 21Source 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--------------------- 28Implementation Status 29--------------------- 30 31Requirements 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 46Predefined 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 58Fixed-point Arithmetics 59======================= 60 61The 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================== ========= 90Type Generic Macro Available 91================== ========= 92absfx 93countlsfx 94roundfx 95================== ========= 96 97 98Higher math functions 99===================== 100 101The following math functions are modeled after C99/C23 math functions for 102floating 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 125Conversion Functions 126==================== 127 128The following conversion functions are included in the ISO/IEC TR 18037:2008 129standard. 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 146Warnings 147======== 148 149This is currently a work-in-progress, its headers, macros, and ABI are still unstable, and might be modified. 150