docs/Proposals/LLVMLibC.rst

   1 ==============================
   2 "llvm-libc" C Standard Library
   3 ==============================
   4
   5 .. contents:: Table of Contents
   6   :depth: 4
   7   :local:
   8
   9 Introduction
  10 ============
  11
  12 This is a proposal to start *llvm-libc*, an implementation of the
  13 C standard library targeting C17 and above, as part of the LLVM project.
  14 llvm-libc will also provide platform specific extensions as relevant.
  15 For example, on Linux it also provides pthreads, librt and other POSIX
  16 extension libraries.
  17
  18 Features
  19 ========
  20
  21 llvm-libc will be developed to have a certain minimum set of features:
  22
  23 - C17 and upwards conformant.
  24 - A modular libc with individual pieces implemented in the "as a
  25   library" philosophy of the LLVM project.
  26 - Ability to layer this libc over the system libc if possible and desired
  27   for a platform.
  28 - Provide C symbols as specified by the standards, but take advantage
  29   and use C++ language facilities for the core implementation.
  30 - Provides POSIX extensions on POSIX compliant platforms.
  31 - Provides system-specific extensions as appropriate. For example,
  32   provides the Linux API on Linux.
  33 - Vendor extensions if and only if necessary.
  34 - Designed and developed from the start to work with LLVM tooling and
  35   testing like fuzz testing and sanitizer-supported testing.
  36 - ABI independent implementation as far as possible.
  37 - Use source based implementations as far possible rather than
  38   assembly. Will try to *fix* the compiler rather than use assembly
  39   language workarounds.
  40 - Extensive unit testing and standards conformance testing. If relevant
  41   and possible, differential testing: We want to be able
  42   to test llvm-libc against another battle-tested libc. This is
  43   essentially to understand how we differ from other libcs. Also if
  44   relevant and possible, test against the testsuite of an another
  45   battle-tested libc implementation.
  46
  47 Why a new C Standard Library?
  48 =============================
  49
  50 Implementing a libc is no small task and is not be taken lightly. A
  51 natural question to ask is, "why a new implementation of the C
  52 standard library?" There is no single answer to this question, but
  53 some of the major reasons are as follows:
  54
  55 - Most libc implementations are monolithic. It is a non-trivial
  56   porting task to pick and choose only the pieces relevant to one's
  57   platform. The llvm-libc will be developed with sufficient modularity to
  58   make picking and choosing a straightforward task.
  59 - Most libc implementations break when built with sanitizer specific
  60   compiler options. The llvm-libc will be developed from the start to
  61   work with those specialized compiler options.
  62 - The llvm-libc will be developed to support and employ fuzz testing
  63   from the start.
  64 - Most libc implementations use a good amount of assembly language,
  65   and assume specific ABIs (may be platform dependent). With the llvm-libc
  66   implementation, we want to use normal source code as much as possible so
  67   that compiler-based changes to the ABI are easy. Moreover, as part of the
  68   LLVM project, we want to use this opportunity to fix performance related
  69   compiler bugs rather than using assembly workarounds.
  70 - A large hole in the LLVM toolchain will be plugged with llvm-libc.
  71   With the broad platform expertise in the LLVM community, and the
  72   strong license and project structure, we think that llvm-libc will
  73   be more tunable and robust, without sacrificing the simplicity and
  74   accessibility typical of the LLVM project.
  75
  76 Platform Support
  77 ================
  78
  79 We envision that llvm-libc will support a variety of platforms in the coming
  80 years. Interested parties are encouraged to participate in the design and
  81 implementation, and add support for their favorite platforms.
  82
  83 ABI Compatibility
  84 =================
  85
  86 As llvm-libc is new, it will not offer ABI stability in the initial stages.
  87 However, as we've heard from other LLVM contributors that they are interested
  88 in having ABI stability, llvm-libc code will be written in a manner which is
  89 amenable to ABI stability. We are looking for contributors interested in
  90 driving the design in this space to help us define what exactly does ABI
  91 stability mean for llvm-libc.
  92
  93 Layering Over Another libc
  94 ==========================
  95
  96 When meaningful and practically possible on a platform, llvm-libc will be
  97 developed in a fashion that it will be possible to layer it over the system
  98 libc. This does not mean that one can mix llvm-libc with the system-libc. Also,
  99 it does not mean that layering is the only way to use llvm-libc. What it
 100 means is that, llvm-libc can optionally be packaged in a way that it can
 101 delegate parts of the functionality to the system-libc. The delegation happens
 102 internal to llvm-libc and is invisible to the users. From the user's point of
 103 view, they only call into llvm-libc.
 104
 105 There are a few problems one needs to be mindful of when implementing such a
 106 delegation scheme in llvm-libc. Examples of such problems are:
 107
 108 1. One cannot mix data structures from llvm-libc with those from the
 109 system-libc. A translation from one set of data structures to the other should
 110 happen internal to llvm-libc.
 111 2. The delegation mechanism has to be implemented over a related set of
 112 functions. For example, one cannot delegate just the `fopen` function to the
 113 system-libc. One will have to delegate all `FILE` related functions to the
 114 system-libc.
 115
 116 Current Status
 117 ==============
 118
 119 llvm-libc development is still in the planning phase.
 120
 121 Build Bots
 122 ==========
 123
 124 Once the development starts, there will be llvm-libc focused builders added to
 125 the LLVM BuildBot.