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/newhdrgen/yaml/math.yaml

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 LIBC_NAMESPACE 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 LIBC_NAMESPACE::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 LIBC_NAMESPACE::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 smoke tests (simple cases and zeros / inf / nan inputs or outputs) to:

  libc/test/src/math/smoke/<func>_test.cpp

• Add unit test that might require MPFR to:

  libc/test/src/math/<func>_test.cpp

• Add the corresponding entry points to:

  libc/test/src/math/smoke/CMakeLists.txt
  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

• The template class LlvmLibcExhaustiveMathTest located at:

  libc/test/src/math/exhaustive/exhaustive_test.h

can be used for conveniently parallelizing the exhaustive tests.

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/performance_testing/<func>_perf.cpp

• Add the corresponding entry point to:

  libc/test/src/math/performance_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 libc

• Run all unit tests:

  $ ninja check-libc

• Run math smoke tests only:

  $ ninja libc-math-smoke-tests

• Run math smoke and unit tests:

  $ ninja libc-math-unittests

• Build and Run a specific unit test:

  $ ninja libc.test.src.math.<func>_test.__unit__
  $ 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
  $ projects/libc/test/src/math/exhaustive/libc.test.src.math.exhaustive.<func>_test

• Build and Run performance test:

  $ ninja libc.test.src.math.performance_testing.<func>_perf
  $ projects/libc/test/src/math/performance_testing/libc.test.src.math.performance_testing.<func>_perf
  $ cat <func>_perf.log

Code reviews

We use GitHub's inbuilt pull request system for code review:

  https://docs.github.com/articles/about-collaborative-development-models
  https://docs.github.com/articles/about-pull-requests