diff --git a/libc/docs/index.rst b/libc/docs/index.rst --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -80,7 +80,6 @@ api_test layering mechanics_of_public_api - redirectors source_layout strings runtimes_build diff --git a/libc/docs/layering.rst b/libc/docs/layering.rst --- a/libc/docs/layering.rst +++ b/libc/docs/layering.rst @@ -2,22 +2,20 @@ Layering Over Another libc ========================== -When meaningful and practically possible on a platform, llvm-libc will be -developed in a fashion that it will be possible to layer it over the system -libc. This does not mean that one can mix llvm-libc with the system-libc. Also, -it does not mean that layering is the only way to use llvm-libc. What it -means is that, llvm-libc can optionally be packaged in a way that it can -delegate parts of the functionality to the system-libc. The delegation happens -internal to llvm-libc and is invisible to the users. From the user's point of -view, they only call into llvm-libc. +LLVM libc can be built in two different modes controlled by the CMake +flag ``LLVM_LIBC_FULL_BUILD``. By default, this flag is ``OFF``. The LLVM libc +binary, the file ``libllvmlibc.a`` which gets built by the build target +``llvmlibc``, contains only those pieces of the libc which are not ABI +sensitive. For example, functions from the ``math.h`` and ``string.h`` are of +this kind. The LLVM libc binary can then be used with headers from another libc. +A binary built with headers from a different libc but linking to +``libllvmlibc.a`` will then pull implementations from LLVM libc when available +and get the rest of the implementations from the system libc. -There are a few problems one needs to be mindful of when implementing such a -delegation scheme in llvm-libc. Examples of such problems are: - -1. One cannot mix data structures from llvm-libc with those from the -system-libc. A translation from one set of data structures to the other should -happen internal to llvm-libc. -2. The delegation mechanism has to be implemented over a related set of -functions. For example, one cannot delegate just the `fopen` function to the -system-libc. One will have to delegate all `FILE` related functions to the -system-libc. +This ability of using LLVM libc implementations when available, and getting the +rest from the system libc, allows adopters of LLVM libc to gradually switch over +to LLVM libc instead of doing an all or nothing switch. One has to keep in mind +that such a scheme cannot be used with the ABI sensitive parts of the libc. A +related set of functions, and the corresponding of public header files, will +have to be switched over together. For example, all functions dealing with the +``FILE`` data structure have to be switched over in together. diff --git a/libc/docs/redirectors.rst b/libc/docs/redirectors.rst deleted file mode 100644 --- a/libc/docs/redirectors.rst +++ /dev/null @@ -1,68 +0,0 @@ -Redirectors -=========== - -When implementing a new C standard library (referred to as *libc* henceforth in -this document) starting from scratch, it is unrealistic to expect that we will -have the entire library available from day one. In such a scenario, a practical -approach is to redirect calls to the unimplemented functions to the same -functions from another fully functional libc implementation. Such a scheme can -also serve users who would like to mix and match implementations from LLVM libc -and another libc implementation. On most platforms, this other libc can be the -system libc itself. In this document, we present a strategy one can employ to -build redirectors to redirect from LLVM libc to the system libc. For now, the -scheme presented is limited to ELF platforms. - -Highlevel Mechanism -------------------- - -The highlevel scheme is as below: - - - -As shown in the diagram, the mechanism involves a redirector dynamic library -which goes in between the llvm-libc static library and the system libc dynamic -library. Essentially, LLVM libc provides implementations for all public -functions. However, some of the implementations do not actually implement the -expected functionality. Instead, they just call the corresponding function in -the redirector library, which in turn calls the same function from the system -libc. - -Implementation of redirecting entrypoints ------------------------------------------ - -Let us take the ``round`` function from ``math.h`` as an example to see what -it's implementation looks like when it just redirects to the ``round`` function -from the system libc:: - - namespace llvm_libc { - - double __redirected_round(double); - - double LLVM_LIBC_ENTRYPOINT(round)(double x) { - return __redirected_round(x); - } - - } // namespace llvm_libc - -As can be seen, the ``round`` function from LLVM libc does not call the -``round`` function from the system libc directly. It calls a function -``__redirected_round`` from the redirector library. The rest of the -code follows the conventions described in the *implementation standard* -document. - -Implementation of the redirector function ------------------------------------------ - -The function ``__redirected_round`` calls the ``round`` function from the system -libc. Its implementation is as follows:: - - #include // Header file from the system libc - - namespace llvm_libc { - - double __redirected_round(double x) { - return ::round(x); // Call to round from the system libc - } - - } // namespace llvm_libc - diff --git a/libc/docs/redirectors_schematic.svg b/libc/docs/redirectors_schematic.svg deleted file mode 100644 --- a/libc/docs/redirectors_schematic.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file