======== stdfix.h

.. include:: ../check.rst

Standards and Goals

• stdfix.h is specified in the ISO/IEC TR 18037:2008 <https://www.iso.org/standard/51126.html>_, C extensions to support embedded processors .

• Its specifications <https://standards.iso.org/ittf/PubliclyAvailableStandards/c051126_ISO_IEC_TR_18037_2008.zip>_.

• Our goal is to implement a complete set of math functions for fixed point types, most of them are currently not included in the ISO/IEC TR 18037:2008 standard. Our math functions for fixed point types are modeled after the C99/C23 math functions for floating point types.

---

Source location

• The main source for fixed-point functions is located at: libc/src/stdfix with subdirectories for internal implementations.

---

Implementation Status

Requirements

• In order to build LLVM libc to support fixed-point arithmetics, we need the compiler to support the basic fixed-point types _Fract and _Accum in C++.

• For the users to be able to use the generated headers, their compiler needs to support _Fract and _Accum types in C or C++.

• This compiler support is checked at the beginning of libc/include/llvm-libc-macros/stdfix-macros.h <https://github.com/llvm/llvm-project/tree/main/libc/include/llvm-libc-macros/stdfix-macros.h>_.

Predefined Macros

• We use the macro LIBC_COMPILER_HAS_FIXED_POINT to specify whether the compiler support the fixed-point types.

• Other predefined precision macros specified in section 7.18a.3 are defined in libc/include/llvm-libc-macros/stdfix-macros.h <https://github.com/llvm/llvm-project/tree/main/libc/include/llvm-libc-macros/stdfix-macros.h>_ using the default configuration of typical desktop processor in section A.3.

Fixed-point Arithmetics

The following functions are included in the ISO/IEC TR 18037:2008 standard.

+---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+ | Function Name | _Fract (r) | _Accum (k) | | +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+ | | short (hr) | _ (r) | long (lr) | short (hk) | _ (k) | long (lk) | | +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) | +===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+ | abs | | |check| | | |check| | | |check| | | |check| | | |check| | | |check| | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | bits* | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | *bits | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | countls | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | divi* | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | idiv* | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | muli | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | *divi | | | | |check| | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | round | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+

================== ========= Type Generic Macro Available ================== ========= absfx |check| countlsfx |check| roundfx |check| ================== =========

Higher math functions

The following math functions are modeled after C99/C23 math functions for floating point types, but are not part of the ISO/IEC TR 18037:2008 spec.

+---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+ | Function Name | _Fract (r) | _Accum (k) | | +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+ | | short (hr) | _ (r) | long (lr) | short (hk) | _ (k) | long (lk) | | +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) | +===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+ | cos | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | exp | | | | | | | | |check| | | |check| | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | log | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | sin | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | sqrt | |check| | | |check| | | |check| | | |check| | | |check| | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | tan | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+

Conversion Functions

The following conversion functions are included in the ISO/IEC TR 18037:2008 standard.

+---------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------+ | Function Name | _Fract (r) | _Accum (k) | | +------------------------------+----------------------------+------------------------------+------------------------------+----------------------------+------------------------------+ | | short (hr) | _ (r) | long (lr) | short (hk) | _ (k) | long (lk) | | +----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | | unsigned (uhr) | signed (hr) | unsigned (ur) | signed (r) | unsigned (ulr) | signed (lr) | unsigned (uhk) | signed (hk) | unsigned (uk) | signed (k) | unsigned (ulk) | signed (lk) | +===============+================+=============+===============+============+================+=============+================+=============+===============+============+================+=============+ | fprintf | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | fscanf | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+ | strtofx | | | | | | | | | | | | | +---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+

Warnings

This is currently a work-in-progress, its headers, macros, and ABI are still unstable, and might be modified.