libc/docs/dev/implementation_standard.rst

   1 Convention for implementing entrypoints
   2 =======================================
   3
   4 LLVM-libc entrypoints are defined in the entrypoints document. In this document,
   5 we explain how the entrypoints are implemented. The source layout document
   6 explains that, within the high level ``src`` directory, there exists one
   7 directory for every public header file provided by LLVM-libc. The
   8 implementations of entrypoints live in the directory for the header they belong
   9 to. Some entrypoints are platform specific, and so their implementations are in
  10 a subdirectory with the name of the platform (e.g. ``stdio/linux/remove.cpp``).
  11
  12 Implementation of entrypoints can span multiple ``.cpp`` and ``.h`` files, but
  13 there will be at least one header file with name of the form
  14 ``<entrypoint name>.h`` for every entrypoint. This header file is called the
  15 implementation header file. For the ``isalpha`` function, the path to the
  16 implementation header file is ``src/ctype/isalpha.h``.
  17
  18 Implementation Header File Structure
  19 ------------------------------------
  20
  21 We will use the ``isalpha`` function from the public ``ctype.h`` header file as an
  22 example. The ``isalpha`` function will be declared in an internal header file
  23 ``src/ctype/isalpha.h`` as follows::
  24
  25     // --- isalpha.h --- //
  26     #ifndef LLVM_LIBC_SRC_CTYPE_ISALPHA_H
  27     #define LLVM_LIBC_SRC_CTYPE_ISALPHA_H
  28
  29     namespace LIBC_NAMESPACE_DECL {
  30
  31     int isalpha(int c);
  32
  33     } // namespace LIBC_NAMESPACE_DECL
  34
  35     #endif LLVM_LIBC_SRC_CTYPE_ISALPHA_H
  36
  37 Notice that the ``isalpha`` function declaration is nested inside the namespace
  38 ``LIBC_NAMESPACE_DECL``. All implementation constructs in LLVM-libc are declared
  39 within the namespace ``LIBC_NAMESPACE_DECL``.
  40
  41 ``.cpp`` File Structure
  42 -----------------------
  43
  44 The main ``.cpp`` file is named ``<entrypoint name>.cpp`` and is usually in the
  45 same folder as the header. It contains the signature of the entrypoint function,
  46 which must be defined with the ``LLVM_LIBC_FUNCTION`` macro. For example, the
  47 ``isalpha`` function from ``ctype.h`` is defined as follows, in the file
  48 ``src/ctype/isalpha.cpp``::
  49
  50     // --- isalpha.cpp --- //
  51
  52     namespace LIBC_NAMESPACE_DECL {
  53
  54     LLVM_LIBC_FUNCTION(int, isalpha, (int c)) {
  55       // ... implementation goes here.
  56     }
  57
  58     } // namespace LIBC_NAMESPACE_DECL
  59
  60 Notice the use of the macro ``LLVM_LIBC_FUNCTION``. This macro helps us define
  61 a C alias symbol for the C++ implementation. For example, for a library build,
  62 the macro is defined as follows::
  63
  64     #define LLVM_LIBC_FUNCTION(type, name, arglist)
  65         LLVM_LIBC_FUNCTION_IMPL(type, name, arglist)
  66     #define LLVM_LIBC_FUNCTION_IMPL(type, name, arglist)
  67         LLVM_LIBC_FUNCTION_ATTR decltype(LIBC_NAMESPACE::name)
  68             __##name##_impl__ __asm__(#name);
  69         decltype(LIBC_NAMESPACE::name) name [[gnu::alias(#name)]];
  70         type __##name##_impl__ arglist
  71
  72 The LLVM_LIBC_FUNCTION_ATTR macro is normally defined to nothing, but can be
  73 defined by vendors who want to set their own attributes.