implementation_standard.rst

Convention for implementing entrypoints

LLVM-libc entrypoints are defined in the entrypoints document. In this document, we explain how the entrypoints are implemented. The source layout document explains that, within the high level src directory, there exists one directory for every public header file provided by LLVM-libc. The implementations of related group of entrypoints will also live in a directory of their own. This directory will have a name indicative of the related group of entrypoints, and will be under the directory corresponding to the header file of the entrypoints. For example, functions like fopen and fclose cannot be tested independent of each other and hence will live in a directory named src/stdio/file_operations. On the other hand, the implementation of the round function from math.h can be tested by itself, so it will live in the directory of its own named src/math/round/.

Implementation of entrypoints can span multiple .cpp and .h files, but there will be atleast one header file with name of the form <entrypoint name>.h for every entrypoint. This header file is called as the implementation header file. For the round function, the path to the implementation header file will be src/math/round/round.h. The rest of this document explains the structure of implementation header files and .cpp files.

Implementation Header File Structure

We will use the round function from the public math.h header file as an example. The round function will be declared in an internal header file src/math/round/round.h as follows:

// --- round.h --- //
#ifndef LLVM_LIBC_SRC_MATH_ROUND_ROUND_H
#define LLVM_LIBC_SRC_MATH_ROUND_ROUND_H

namespace __llvm_libc {

double round(double);

} // namespace __llvm_libc

#endif LLVM_LIBC_SRC_MATH_ROUND_ROUND_H

Notice that the round function declaration is nested inside the namespace __llvm_libc. All implementation constructs in LLVM-libc are declared within the namespace __llvm_libc.

.cpp File Structure

The implementation can span multiple .cpp files. However, the signature of the entrypoint function should make use of a special macro. For example, the round function from math.h should be defined as follows, say in the file src/math/math/round.cpp:

// --- round.cpp --- //

namespace __llvm_libc {

double LLVM_LIBC_ENTRYPOINT(round)(double d) {
  // ... implementation goes here.
}

} // namespace __llvm_libc

Notice the use of the macro LLVM_LIBC_ENTRYPOINT. This macro helps us define an C alias symbol for the C++ implementation. The C alias need not be added by the macro by itself. For example, for ELF targets, the macro is defined as follows:

#define ENTRYPOINT_SECTION_ATTRIBUTE(name) \
    __attribute__((section(".llvm.libc.entrypoint."#name)))
#define LLVM_LIBC_ENTRYPOINT(name) ENTRYPOINT_SECTION_ATTRIBUTE(name) name

The macro places the C++ function in a unique section with name .llvm.libc.entrypoint.<function name>. This allows us to add a C alias using a post build step. For example, for the round function, one can use objcopy to add an alias symbol as follows:

objcopy --add-symbol round=.llvm.libc.entrypoint.round:0,function round.o

NOTE: We use a post build objcopy step to add an alias instead of using the __attribute__((alias)). For C++, this alias attribute requires mangled names of the referees. Using the post build objcopy step helps us avoid putting mangled names with alias attributes.