89657f726f
Summary: Integrated a series of quick documentation cleanups for LLVM-libc. This update focuses on de-duplicating core conventions (naming and namespaces) across multiple developer and contribution guides, and addresses empty platform stubs for UEFI. Changes: * libc/docs/contributing.rst: Removed duplicated code style rules and provided a link to dev/code_style.rst. * libc/docs/dev/clang_tidy_checks.rst: Removed redundant namespace explanations and linked to dev/code_style.rst. * libc/docs/dev/implementation_standard.rst: Removed repetitive notes about LIBC_NAMESPACE_DECL and linked to the authoritative reference. * libc/docs/uefi/support.rst & libc/docs/uefi/using.rst: Added early-stage bring-up warnings and pointed to the config directory for the source of truth.
74 lines
2.9 KiB
ReStructuredText
74 lines
2.9 KiB
ReStructuredText
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 entrypoints live in the directory for the header they belong
|
|
to. Some entrypoints are platform specific, and so their implementations are in
|
|
a subdirectory with the name of the platform (e.g. ``stdio/linux/remove.cpp``).
|
|
|
|
Implementation of entrypoints can span multiple ``.cpp`` and ``.h`` files, but
|
|
there will be at least one header file with name of the form
|
|
``<entrypoint name>.h`` for every entrypoint. This header file is called the
|
|
implementation header file. For the ``isalpha`` function, the path to the
|
|
implementation header file is ``src/ctype/isalpha.h``.
|
|
|
|
Implementation Header File Structure
|
|
------------------------------------
|
|
|
|
We will use the ``isalpha`` function from the public ``ctype.h`` header file as an
|
|
example. The ``isalpha`` function will be declared in an internal header file
|
|
``src/ctype/isalpha.h`` as follows::
|
|
|
|
// --- isalpha.h --- //
|
|
#ifndef LLVM_LIBC_SRC_CTYPE_ISALPHA_H
|
|
#define LLVM_LIBC_SRC_CTYPE_ISALPHA_H
|
|
|
|
namespace LIBC_NAMESPACE_DECL {
|
|
|
|
int isalpha(int c);
|
|
|
|
} // namespace LIBC_NAMESPACE_DECL
|
|
|
|
#endif LLVM_LIBC_SRC_CTYPE_ISALPHA_H
|
|
|
|
All LLVM-libc implementation constructs must be enclosed in the
|
|
``LIBC_NAMESPACE_DECL`` namespace. See :ref:`code_style` for the full technical
|
|
rationale and macro definitions.
|
|
|
|
``.cpp`` File Structure
|
|
-----------------------
|
|
|
|
The main ``.cpp`` file is named ``<entrypoint name>.cpp`` and is usually in the
|
|
same folder as the header. It contains the signature of the entrypoint function,
|
|
which must be defined with the ``LLVM_LIBC_FUNCTION`` macro. For example, the
|
|
``isalpha`` function from ``ctype.h`` is defined as follows, in the file
|
|
``src/ctype/isalpha.cpp``::
|
|
|
|
// --- isalpha.cpp --- //
|
|
|
|
namespace LIBC_NAMESPACE_DECL {
|
|
|
|
LLVM_LIBC_FUNCTION(int, isalpha, (int c)) {
|
|
// ... implementation goes here.
|
|
}
|
|
|
|
} // namespace LIBC_NAMESPACE_DECL
|
|
|
|
Notice the use of the macro ``LLVM_LIBC_FUNCTION``. This macro helps us define
|
|
a C alias symbol for the C++ implementation. For example, for a library build,
|
|
the macro is defined as follows::
|
|
|
|
#define LLVM_LIBC_FUNCTION(type, name, arglist)
|
|
LLVM_LIBC_FUNCTION_IMPL(type, name, arglist)
|
|
#define LLVM_LIBC_FUNCTION_IMPL(type, name, arglist)
|
|
LLVM_LIBC_FUNCTION_ATTR decltype(LIBC_NAMESPACE::name)
|
|
__##name##_impl__ __asm__(#name);
|
|
decltype(LIBC_NAMESPACE::name) name [[gnu::alias(#name)]];
|
|
type __##name##_impl__ arglist
|
|
|
|
The LLVM_LIBC_FUNCTION_ATTR macro is normally defined to nothing, but can be
|
|
defined by vendors who want to set their own attributes.
|