[libc-commits] [libc] a2b3e6b - [libc] Add documentation about how to add a math function to LLVM-libc.

[Tue Ly via libc-commits]

Author: Tue Ly
Date: 2021-12-16T12:12:21-05:00
New Revision: a2b3e6bed86d25b3eeb09c96c73948edb48cda64

URL: https://github.com/llvm/llvm-project/commit/a2b3e6bed86d25b3eeb09c96c73948edb48cda64
DIFF: https://github.com/llvm/llvm-project/commit/a2b3e6bed86d25b3eeb09c96c73948edb48cda64.diff

LOG: [libc] Add documentation about how to add a math function to LLVM-libc.

Add documentation about how to add a math function to LLVM-libc.

Differential Revision: https://reviews.llvm.org/D115608

Added: 
    libc/src/math/docs/add_math_function.md

Modified: 
    

Removed: 
    


################################################################################
diff  --git a/libc/src/math/docs/add_math_function.md b/libc/src/math/docs/add_math_function.md
new file mode 100644
index 0000000000000..a3325a533e433
--- /dev/null
+++ b/libc/src/math/docs/add_math_function.md
@@ -0,0 +1,181 @@
+# How to add a new math function to LLVM-libc
+
+This document is to serve as a cookbook for adding a new math function
+implementation to LLVM libc.  To add a new function, apart from the actual
+implementation, one has to follow a few other steps to setup proper registration
+and shipping of the new function.  Each of these steps will be described in
+detail below.
+
+## Registration
+
+To register the function's entry points for supported OSes and architectures,
+together with its specifications:
+
+- Add entry points `libc.src.math.func` to the following files:
+```
+  libc/config/linux/<arch>/entrypoints.txt
+  libc/config/windows/entrypoints.txt
+```
+- Add function specs to the file:
+```
+  libc/spec/stdc.td
+```
+
+## Implementation
+
+The function's actual implementation and its corresponding header should be
+added to the following locations:
+
+- Add `add_math_entrypoint_object(<func>)` to:
+```
+  libc/src/math/CMakeLists.txt
+```
+- Add function declaration (under `__llvm_libc` namespace) to:
+```
+  libc/src/math/<func>.h
+```
+- Add function definition to:
+```
+  libc/src/math/generic/<func>.cpp
+```
+- Add the corresponding `add_entrypoint_object` to:
+```
+  libc/src/math/generic/CMakeLists.txt
+```
+- Add architectural specific implementations to:
+```
+  libc/src/math/<arch>/<func>.cpp
+```
+
+### Floating point utility
+
+- Floating point utilities and math functions that are also used internally are
+located at:
+```
+  libc/src/__support/FPUtils
+```
+- These are preferred to be included as header-only.
+- To manipulate bits of floating point numbers, use the template class
+`__llvm_libc::fputil::FPBits<>` in the header file:
+```
+  libc/src/__support/FPUtils/FPBits.h
+```
+
+## Testing
+
+### MPFR utility
+
+In addition to the normal testing macros such as `EXPECT_EQ, ASSERT_THAT, ...`
+there are two special macros `ASSERT_MPFR_MATCH` and `EXPECT_MPFR_MATCH` to
+compare your outputs with the corresponding MPFR function.  In
+order for your new function to be supported by these two macros,
+the following files will need to be updated:
+
+- Add the function enum to `__llvm_libc::testing::mpfr::Operation` in the
+header file:
+```
+  libc/utils/MPFRWrapper/MPFRUtils.h
+```
+- Add support for `func` in the `MPFRNumber` class and the corresponding link
+between the enum and its call to the file:
+```
+  libc/utils/MPFRWrapper/MPFRUtils.cpp
+```
+
+### Unit tests
+
+Besides the usual testing macros like `EXPECT_EQ, ASSERT_TRUE, ...` there are
+testing macros specifically used for floating point values, such as
+`EXPECT_FP_EQ, ASSERT_FP_LE, ...`
+
+- Add unit test to:
+```
+  libc/test/src/math/func_test.cpp
+```
+- Add the corresponding entry point to:
+```
+  libc/test/src/math/CMakeLists.txt
+```
+
+### Exhaustive tests
+
+Exhaustive tests are long-running tests that are not included when you run
+`ninja check-libc`.  These exhaustive tests are added and manually run in
+order to find exceptional cases for your function's implementation.
+
+- Add an exhaustive test to:
+```
+  libc/test/src/math/exhaustive/func_test.cpp
+```
+- Add the corresponding entry point to:
+```
+  libc/test/src/math/exhaustive/CMakeLists.txt
+```
+
+### Performance tests
+
+Performance tests compare your function's implementation with the system libc
+implementation (which is very often glibc).
+
+- Add a performance test to:
+```
+  libc/test/src/math/
diff erential_testing/<func>_perf.cpp
+```
+- Add the corresponding entry point to:
+```
+  libc/test/src/math/
diff erential_testing/CMakeLists.txt
+```
+
+## Build and Run
+
+- Check out the LLVM source tree:
+```
+  $ git clone https://github.com/llvm/llvm-project.git
+```
+
+- Setup projects with CMake:
+```
+  $ cd llvm-project
+  $ mkdir build
+  $ cd build
+  $ cmake ../llvm -G Ninja \
+  -DLLVM_ENABLE_PROJECTS="llvm;libc" \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_C_COMPILER=clang \
+  -DCMAKE_CXX_COMPILER=clang++
+```
+
+- Build the whole `libc`:
+```
+  $ ninja llvmlibc
+```
+
+- Run all unit tests:
+```
+  $ ninja check-libc
+```
+
+- Build and Run a specific unit test:
+```
+  $ ninja libc.test.src.math.func_test
+  $ projects/libc/test/src/math/libc.test.src.math.<func>_test
+```
+
+- Build and Run exhaustive test (might take hours to run):
+```
+  $ ninja libc.test.src.math.exhaustive.<func>_test
+```
+
+- Build and Run performance test:
+```
+  $ ninja libc.test.src.math.
diff erential_testing.<func>_perf
+  $ projects/libc/test/src/math/
diff erential_testing/libc.test.src.math.
diff erential_testing.<func>_perf
+  $ cat <func>_perf.log
+```
+
+## Code reviews
+
+We follow the code review process of LLVM with Phabricator:
+```
+  https://llvm.org/docs/Phabricator.html
+```