stdfix.h

Standards and Goals

• stdfix.h is specified in the ISO/IEC TR 18037:2008, C extensions to support embedded processors .
• Its specifications.
• 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.

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 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           |                | ✅          |               | ✅         |                | ✅          |                | ✅          |               | ✅         |                | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| bits\*        | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| \*bits        | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| countls       | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| divi\*        |                |             | ✅            | ✅         | ✅             | ✅          |                |             | ✅            | ✅         | ✅             | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| idiv\*        |                |             | ✅            | ✅         | ✅             | ✅          |                |             | ✅            | ✅         | ✅             | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| muli          |                |             |               |            |                |             |                |             |               |            |                |             |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| \*divi        |                |             | ✅            | ✅         | ✅             | ✅          |                |             | ✅            | ✅         | ✅             | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| round         | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          | ✅             | ✅          | ✅            | ✅         | ✅             | ✅          |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+

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           |                |             |               |            |                |             |                | ✅          |               | ✅         |                |             |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| log           |                |             |               |            |                |             |                |             |               |            |                |             |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| sin           |                |             |               |            |                |             |                |             |               |            |                |             |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| sqrt          | ✅             |             | ✅            |            | ✅             |             | ✅             |             | ✅            |            |                |             |
+---------------+----------------+-------------+---------------+------------+----------------+-------------+----------------+-------------+---------------+------------+----------------+-------------+
| 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.