[libc][docs][NFC] Expand entrypoints technical reference (#4) (llvm#188255)

Expanded entrypoints.rst with details about definitions, registration
rules, and the lifecycle of an entrypoint.

Updated multiple documents to remove redundant technical details and
link to the centralized entrypoints reference:

- libc/docs/dev/cmake_build_rules.rst
- libc/docs/dev/implementation_standard.rst
- libc/docs/porting.rst
- libc/docs/dev/source_tree_layout.rst

Author: kaladron

libc/docs/dev/cmake_build_rules.rst

@@ -12,20 +12,17 @@ task.
 Targets for entrypoints
 -----------------------
 
-Every entrypoint in LLVM-libc has its own build target. This target is listed
-using the ``add_entrypoint_object`` rule. This rule generates a single object
-file containing the implementation of the entrypoint.
+Every entrypoint in LLVM-libc has its own build target, listed using the
+``add_entrypoint_object`` rule. This rule generates a single object file
+containing the implementation.
 
-Targets for redirecting entrypoints are also listed using the
-``add_entrypoint_object`` rule. However, one will have to additionally specify
-the ``REDIRECTED`` option with the rule.
+For more technical details on how to register entrypoints, see the
+:ref:`entrypoints` documentation.
 
 Targets for entrypoint libraries
 --------------------------------
 
 Standards like POSIX require that a libc provide certain library files like
 ``libc.a``, ``libm.a``, etc. The targets for such library files are listed in
-the ``lib`` directory as ``add_entrypoint_library`` targets. An
-``add_entrypoint_library`` target  takes a list of ``add_entrypoint_object``
-targets and produces a static library containing the object files corresponding
-to the ``add_entrypoint_targets``.
+the ``lib`` directory as ``add_entrypoint_library`` targets.
+

libc/docs/dev/entrypoints.rst

@@ -1,8 +1,116 @@
 .. _entrypoints:
 
+========================
 Entrypoints in LLVM libc
-------------------------
+========================
 
 A public function or a global variable provided by LLVM-libc is called an
-entrypoint. The notion of entrypoints is ingrained in LLVM-libc's
-source layout, build system and source code.
+*entrypoint*. The notion of entrypoints is central to LLVM-libc's source layout,
+build system, and configuration management. This document provides a technical
+reference for how entrypoints are defined, implemented, and integrated into
+the final library.
+
+What is an Entrypoint?
+----------------------
+
+In a typical C library, all functions are part of a monolithic archive. In
+LLVM-libc, each function (e.g., ``malloc``, ``printf``, ``isalpha``) is treated
+as a discrete "entrypoint" unit. This allows for:
+
+- **Granular build targets**: You can build just the objects you need.
+- **Configuration-driven selection**: Different operating systems and
+  architectures can pick specific implementations for the same function.
+- **Support for multiple build modes**: Selectively replacing parts of a host's
+  libc in :ref:`overlay_mode` or building a complete library in :ref:`full_host_build`.
+
+The Lifecycle of an Entrypoint
+------------------------------
+
+1. **Implementation**: The function is implemented in a ``.cpp`` file using
+   LLVM-libc's coding and implementation standards.
+2. **Registration**: The entrypoint is defined as a CMake target using the
+   ``add_entrypoint_object`` rule.
+3. **Configuration**: The target name is added to an ``entrypoints.txt`` file
+   to include it in a specific OS/Architecture configuration.
+
+Implementation Standards
+------------------------
+
+Implementations live in the ``src/`` directory, organized by the public header
+they belong to (e.g., ``src/ctype/isalpha.cpp`` for ``ctype.h``).
+
+Header File Structure
+^^^^^^^^^^^^^^^^^^^^^
+
+Every entrypoint has an internal implementation header file (e.g.,
+``src/ctype/isalpha.h``). This header declares the function within the
+``LIBC_NAMESPACE_DECL`` namespace::
+
+   namespace LIBC_NAMESPACE_DECL {
+   int isalpha(int c);
+   } // namespace LIBC_NAMESPACE_DECL
+
+Source File Structure
+^^^^^^^^^^^^^^^^^^^^^
+
+The implementation file (e.g., ``src/ctype/isalpha.cpp``) defines the function
+using the ``LLVM_LIBC_FUNCTION`` macro. This macro handles C-linkage and
+aliasing::
+
+   namespace LIBC_NAMESPACE_DECL {
+   LLVM_LIBC_FUNCTION(int, isalpha, (int c)) {
+     // ... implementation ...
+   }
+   } // namespace LIBC_NAMESPACE_DECL
+
+For more details on implementation conventions, see the
+:ref:`implementation_standard` page.
+
+Registration: CMake Rules
+-------------------------
+
+Entrypoints are registered as CMake targets to make them available to the
+build system. These rules are usually defined in the ``CMakeLists.txt`` file
+within the function's source directory.
+
+``add_entrypoint_object``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This rule generates a single object file containing the implementation of the
+entrypoint.
+
+.. code-block:: cmake
+
+   add_entrypoint_object(
+     isalpha
+     SRCS isalpha.cpp
+     HDRS isalpha.h
+     DEPENDS
+       .some_internal_dependency
+   )
+
+For redirecting entrypoints (e.g., when one function is a simple alias for
+another), the ``REDIRECTED`` option can be specified to the rule.
+
+``add_entrypoint_library``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Standard library files like ``libc.a`` and ``libm.a`` are produced by
+aggregating multiple entrypoint objects. The ``add_entrypoint_library`` target
+takes a list of ``add_entrypoint_object`` targets and produces a static library.
+
+Configuration: ``entrypoints.txt``
+----------------------------------
+
+The final selection of which entrypoints are included in a specific build is
+determined by ``entrypoints.txt`` files located in the ``libc/config`` tree.
+
+- **Location**: Typically found in ``libc/config/<os>/entrypoints.txt`` or
+  ``libc/config/<os>/<arch>/entrypoints.txt``.
+- **Role**: This file acts as the "source of truth" for what is supported on a
+  given platform. A typical bring-up procedure involves progressively adding
+  targets to this file as they are implemented and tested.
+
+If you are implementing a new entrypoint, you must add its target name to the
+relevant ``entrypoints.txt`` files for it to be included in the library build.
+For more details on platform configuration, see the :ref:`porting` guide.

libc/docs/dev/fuzzing.rst

@@ -1,3 +1,5 @@
+.. _fuzzing:
+
 Fuzzing for LLVM-libc functions
 ===============================
 

libc/docs/dev/implementation_standard.rst

@@ -1,13 +1,16 @@
+.. _implementation_standard:
+
 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``).
+The implementations of LLVM-libc entrypoints live in the ``src/`` directory,
+organized by the public 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``).
+
+For a complete overview of what an entrypoint is and how it is managed in the
+build system, see the :ref:`entrypoints` documentation.
+
 
 Implementation of entrypoints can span multiple ``.cpp`` and ``.h`` files, but
 there will be at least one header file with name of the form

libc/docs/dev/source_tree_layout.rst

@@ -90,8 +90,9 @@ public libraries ``libc.a``, ``libm.a`` etc.
 The ``src`` directory
 ---------------------
 
-This directory contains the implementations of the llvm-libc entrypoints. It is
-further organized as follows:
+This directory contains the implementations of the llvm-libc entrypoints. For
+more details on what an entrypoint is and how it is implemented, see the
+:ref:`entrypoints` documentation. It is further organized as follows:
 
 1. There is a top-level CMakeLists.txt file.
 2. For every public header file provided by llvm-libc, there exists a

libc/docs/dev/undefined_behavior.rst

@@ -1,3 +1,5 @@
+.. _undefined_behavior:
+
 ===========================
 Defining Undefined Behavior
 ===========================

libc/docs/porting.rst

@@ -49,29 +49,19 @@ architecture.
 The entrypoints.txt file
 ------------------------
 
-One of the important pieces of config information is listed in a file named
-``entrypoints.txt``. This file lists the targets for the entrypoints (see
-:ref:`entrypoints`) you want to include in the static archive of the libc (for
-the :ref:`overlay_mode` and/or the :ref:`full_host_build`.) If you are doing an
-architecture specific bring up, then an ``entrypoints.txt`` file should be
-created in the architecture subdirectory for each architecture. Else, having a
-single ``entrypoints.txt`` in the operating system directory is sufficient.
-
-The Linux config has an ``entrypoint.txt`` for each individual target
-architecture separately: `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_,
-`arm32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm>`_ and
-`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_. On the
-other hand, the Windows config has a single ``entrypoints.txt``
-`file <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_.
-
-A typical bring up procedure will normally bring up a small group of entrypoints
-at a time. The usual practice is to progressively add the targets for those
-entrypoints to the ``entrypoints.txt`` file as they are being brought up. The
-same is the case if one is implementing a new entrypoint - the target for the
-new entrypoint should be added to the relevant ``entrypoints.txt`` file. If
-the implementation of the new entrypoint supports multiple operating systems and
-target architectures, then multiple ``entrypoints.txt`` files will have to be
-updated.
+The ``entrypoints.txt`` file lists the targets for the entrypoints to be
+included in the build for a specific platform. For more technical details on
+what entrypoints are and how they are registered as targets, see the
+:ref:`entrypoints` documentation.
+
+If you are doing an architecture specific bring-up, then an ``entrypoints.txt``
+file should be created in the architecture subdirectory for each architecture.
+Else, having a single ``entrypoints.txt`` in the operating system directory is
+sufficient.
+
+A typical bring-up procedure will normally involve progressively adding targets
+to this file as they are implemented and tested.
+
 
 The headers.txt file
 --------------------