diff --git a/libc/src/math/docs/add_math_function.md b/libc/src/math/docs/add_math_function.md new file mode 100644 --- /dev/null +++ b/libc/src/math/docs/add_math_function.md @@ -0,0 +1,150 @@ +# How to add a new math function to LLVM-libc + +A new math function (let call it `func`) to the LLVM-libc can be added as follow: + +## Registration + +- Add entry points `libc.src.math.func` to the following files: +``` + libc/config/linux//entrypoints.txt + libc/config/windows/entrypoints.txt +``` +- Add function specs to the file: +``` + libc/spec/stdc.td +``` + +## Implementation + +- 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//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 preferable to be implemented 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 +- 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 between the enum and its call to the file: +``` + libc/utils/MPFRWrapper/MPFRUtils.cpp +``` + +### Unit tests +- 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 +- Add 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 +- Add a performance test to: +``` + libc/test/src/math/differential_testing/func_perf.cpp +``` +- Add the corresponding entry point to: +``` + libc/test/src/math/differential_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="clang;clang-tools-extra;llvm;libc" \ + -DCMAKE_BUILD_TYPE=Debug \ + -DCMAKE_C_COMPILER=clang \ + -DCMAKE_CXX_COMPILER=clang++ +``` + +- Build the whole `libc`: +``` + $ ninja llvmlibc +``` + +- Build only `libm`: +``` + $ ninja llvmlibm +``` + +- 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.differential_testing.func_perf + $ projects/libc/test/src/math/differential_testing/libc.test.src.math.differential_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 +``` \ No newline at end of file