150 lines · plain
1========2stdfix.h3========4 5.. include:: ../check.rst6 7Standards and Goals8-------------------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 point16 types, most of them are currently not included in the ISO/IEC TR17 18037:2008 standard. Our math functions for fixed point types are modeled18 after the C99/C23 math functions for floating point types.19 20---------------21Source location22---------------23 24- The main source for fixed-point functions is located at:25 ``libc/src/stdfix`` with subdirectories for internal implementations.26 27---------------------28Implementation Status29---------------------30 31Requirements32============33 34- In order to build LLVM libc to support fixed-point arithmetics, we need the35 compiler to support the basic fixed-point types `_Fract` and `_Accum` in36 C++.37 38- For the users to be able to use the generated headers, their compiler needs39 to support `_Fract` and `_Accum` types in C or C++.40 41- This compiler support is checked at the beginning of42 `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 Macros47=================48 49- We use the macro `LIBC_COMPILER_HAS_FIXED_POINT` to specify whether the50 compiler support the fixed-point types.51 52- Other predefined precision macros specified in section 7.18a.3 are defined53 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 section55 A.3.56 57 58Fixed-point Arithmetics59=======================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\* | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| |73+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+74| \*bits | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| |75+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+76| countls | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| |77+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+78| divi\* | | | | | | | | | | | | |79+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+80| idiv\* | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| |81+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+82| muli | | | | | | | | | | | | |83+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+84| \*divi | | | | |check| | | | | | | | | |85+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+86| round | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| |87+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+88 89================== =========90Type Generic Macro Available91================== =========92absfx |check|93countlsfx |check|94roundfx |check|95================== =========96 97 98Higher math functions99=====================100 101The following math functions are modeled after C99/C23 math functions for102floating 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 Functions126====================127 128The following conversion functions are included in the ISO/IEC TR 18037:2008129standard.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 146Warnings147========148 149This is currently a work-in-progress, its headers, macros, and ABI are still unstable, and might be modified.150