Rewrite much of the index page for libc

The prior page was the proposal doc, this one is now
more about what the project intends to do, written in the
present tense.

Reviewed By: sivachandra

Differential Revision: https://reviews.llvm.org/D119379

2 files changed, 60 insertions, 75 deletions

diff --git a/libc/docs/index.rst b/libc/docs/index.rst
index dce5315f3409..d51a1a6bdbb0 100644
--- 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 @@ Other Interesting Documentation
     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
index 000000000000..f6a14a9d9bde
--- /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.