diff --git a/libc/docs/index.rst b/libc/docs/index.rst --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -1,6 +1,9 @@ -========================= -"libc" C Standard Library -========================= +======================================================== +llvm-libc: An ISO C-conformant Standard Library for LLVM +======================================================== + +**llvm-libc library is not complete. If you need a fully functioning libc right +now, you should continue to use your standard system libc.** .. contents:: Table of Contents :depth: 4 @@ -9,100 +12,58 @@ Goals ===== -llvm-libc will be developed to have a certain minimum set of features: - - C17 and upwards conformant. - A modular libc with individual pieces implemented in the "as a library" philosophy of the LLVM project. - Ability to layer this libc over the system libc if possible and desired for a platform. -- Provide C symbols as specified by the standards, but take advantage - and use C++ language facilities for the core implementation. -- Provides POSIX extensions on POSIX compliant platforms. -- Provides system-specific extensions as appropriate. For example, - provides the Linux API on Linux. -- Vendor extensions if and only if necessary. -- Designed and developed from the start to work with LLVM tooling and - testing like fuzz testing and sanitizer-supported testing. -- ABI independent implementation as far as possible. +- Provide POSIX extensions on POSIX compliant platforms. +- Provide system-specific extensions as appropriate. For example, + provide the Linux API on Linux. +- Designed and developed from the start to work with LLVM tooling, fuzz testing + and sanitizer-supported testing. - Use source based implementations as far possible rather than assembly. Will try to *fix* the compiler rather than use assembly language workarounds. -- Extensive unit testing and standards conformance testing. If relevant - and possible, differential testing: We want to be able - to test llvm-libc against another battle-tested libc. This is - essentially to understand how we differ from other libcs. Also if - relevant and possible, test against the testsuite of an another - battle-tested libc implementation. +- Extensive unit testing and standards conformance testing. Why a new C Standard Library? ============================= Implementing a libc is no small task and is not be taken lightly. A natural question to ask is, "why a new implementation of the C -standard library?" There is no single answer to this question, but -some of the major reasons are as follows: - -- Most libc implementations are monolithic. It is a non-trivial - porting task to pick and choose only the pieces relevant to one's - platform. The llvm-libc will be developed with sufficient modularity to - make picking and choosing a straightforward task. -- Most libc implementations break when built with sanitizer specific - compiler options. The llvm-libc will be developed from the start to - work with those specialized compiler options. -- The llvm-libc will be developed to support and employ fuzz testing - from the start. -- Most libc implementations use a good amount of assembly language, - and assume specific ABIs (may be platform dependent). With the llvm-libc - implementation, we want to use normal source code as much as possible so - that compiler-based changes to the ABI are easy. Moreover, as part of the - LLVM project, we want to use this opportunity to fix performance related - compiler bugs rather than using assembly workarounds. -- A large hole in the LLVM toolchain will be plugged with llvm-libc. - With the broad platform expertise in the LLVM community, and the - strong license and project structure, we think that llvm-libc will - be more tunable and robust, without sacrificing the simplicity and - accessibility typical of the LLVM project. +standard library?" Some of the major reasons are as follows: + +- Rather than being built as a single monolithic codebase, llvm-libc is designed + from the beginning to enable picking and choosing pieces. This allows using + it as a minimum overlay for e.g. faster math functions than might be + available on the system library. This is useful where an application may + need to access improved CPU support over what's available on the system, + or may need guarantees in performance across different installs. +- Explicit support for building llvm-libc and code with sanitizer compiler + options. +- `Fuzzing`__ +- Be useful for research and review. By avoiding assembly language, using C++ + iterators, RAII and templates, llvm-libc aims to have clearly + readable code and to improve the compiler as needed to ensure that optimal + assembly is emitted. +- Enable fully static compiles. + +.. __: https://github.com/llvm/llvm-project/tree/main/libc/fuzzing Platform Support ================ -We envision that llvm-libc will support a variety of platforms in the coming -years. Interested parties are encouraged to participate in the design and -implementation, and add support for their favorite platforms. +Most development is currently targeting x86_64 and aarch64 on Linux. Several +functions in llvm-libc have been tested on Windows. The Fuchsia platform is +slowly replacing functions from its bundled libc with functions from llvm-libc. ABI Compatibility ================= -As llvm-libc is new, it will not offer ABI stability in the initial stages. -However, as we've heard from other LLVM contributors that they are interested -in having ABI stability, llvm-libc code will be written in a manner which is -amenable to ABI stability. We are looking for contributors interested in -driving the design in this space to help us define what exactly does ABI -stability mean for llvm-libc. - -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. - -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. +llvm-libc is written to be ABI independent. Interfaces are generated using +LLVM's tablegen, so supporting arbitrary ABIs is possible. In it's initial +stages llvm-libc is not offering ABI stability in any form. Other Interesting Documentation =============================== @@ -117,6 +78,7 @@ header_generation implementation_standard integration_test + layering mechanics_of_public_api redirectors source_layout diff --git a/libc/docs/layering.rst b/libc/docs/layering.rst new file mode 100644 --- /dev/null +++ b/libc/docs/layering.rst @@ -0,0 +1,23 @@ +========================== +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. + +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.