79 lines
3.9 KiB
Plaintext
79 lines
3.9 KiB
Plaintext
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).
|