| STYLE REQUIREMENTS |
| ================== |
| |
| 1. Most code in this sub-directory is expected to be upstreamed into glibc so |
| the GNU Coding Standard and glibc specific conventions should be followed |
| to ease upstreaming. |
| |
| 2. ABI and symbols: the code should be written so it is suitable for inclusion |
| into a libc with minimal changes. This e.g. means that internal symbols |
| should be hidden and in the implementation reserved namespace according to |
| ISO C and POSIX rules. If possible the built shared libraries and static |
| library archives should be usable to override libc symbols at link time (or |
| at runtime via LD_PRELOAD). This requires the symbols to follow the glibc ABI |
| (other than symbol versioning), this cannot be done reliably for static |
| linking so this is a best effort requirement. |
| |
| 3. API: include headers should be suitable for benchmarking and testing code |
| and should not conflict with libc headers. |
| |
| |
| CONTRIBUTION GUIDELINES FOR math SUB-DIRECTORY |
| ============================================== |
| |
| 1. Math functions have quality and performance requirements. |
| |
| 2. Quality: |
| - Worst-case ULP error should be small in the entire input domain (for most |
| common double precision scalar functions the target is < 0.66 ULP error, |
| and < 1 ULP for single precision, even performance optimized function |
| variant should not have > 5 ULP error if the goal is to be a drop in |
| replacement for a standard math function), this should be tested |
| statistically (or on all inputs if possible in reasonable amount of time). |
| The ulp tool is for this and runulp.sh should be updated for new functions. |
| |
| - All standard rounding modes need to be supported but in non-default rounding |
| modes the quality requirement can be relaxed. (Non-nearest rounded |
| computation can be slow and inaccurate but has to be correct for conformance |
| reasons.) |
| |
| - Special cases and error handling need to follow ISO C Annex F requirements, |
| POSIX requirements, IEEE 754-2008 requirements and Glibc requiremnts: |
| https://www.gnu.org/software/libc/manual/html_mono/libc.html#Errors-in-Math-Functions |
| this should be tested by direct tests (glibc test system may be used for it). |
| |
| - Error handling code should be decoupled from the approximation code as much |
| as possible. (There are helper functions, these take care of errno as well |
| as exception raising.) |
| |
| - Vector math code does not need to work in non-nearest rounding mode and error |
| handling side effects need not happen (fenv exceptions and errno), but the |
| result should be correct (within quality requirements, which are lower for |
| vector code than for scalar code). |
| |
| - Error bounds of the approximation should be clearly documented. |
| |
| - The code should build and pass tests on arm, aarch64 and x86_64 GNU linux |
| systems. (Routines and features can be disabled on specific targets, but |
| the build must complete). On aarch64, both little- and big-endian targets |
| are supported as well as valid combinations of architecture extensions. |
| The configurations that should be tested depend on the contribution. |
| |
| 3. Performance: |
| - Common math code should be benchmarked on modern aarch64 microarchitectures |
| over typical inputs. |
| |
| - Performance improvements should be documented (relative numbers can be |
| published; it is enough to use the mathbench microbenchmark tool which should |
| be updated for new functions). |
| |
| - Attention should be paid to the compilation flags: for aarch64 fma |
| contraction should be on and math errno turned off so some builtins can be |
| inlined. |
| |
| - The code should be reasonably performant on x86_64 too, e.g. some rounding |
| instructions and fma may not be available on x86_64, such builtins turn into |
| libc calls with slow code. Such slowdown is not acceptable, a faster fallback |
| should be present: glibc and bionic use the same code on all targets. (This |
| does not apply to vector math code). |