libc/docs/headers/stdfix.rst

========
stdfix.h
========

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\*        |                |             | |check|       | |check|    | |check|        | |check|     |                |             | |check|       | |check|    | |check|        | |check|     |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| idiv\*        |                |             | |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.