Add few docs and implementation of strcpy and strcat.
Summary:
This patch illustrates some of the features like modularity we want
in the new libc. Few other ideas like different kinds of testing, redirectors
etc are not yet present.
Reviewers: dlj, hfinkel, theraven, jfb, alexshap, jdoerfert
Subscribers: mgorny, dexonsmith, llvm-commits
Tags: #llvm
Differential Revision: https://reviews.llvm.org/D67867
llvm-svn: 373764
diff --git a/libc/docs/build_system.rst b/libc/docs/build_system.rst
new file mode 100644
index 0000000..f34ffe0
--- /dev/null
+++ b/libc/docs/build_system.rst
@@ -0,0 +1,24 @@
+LLVM libc build rules
+=====================
+
+At the cost of verbosity, we want to keep the build system of LLVM libc
+as simple as possible. We also want to be highly modular with our build
+targets. This makes picking and choosing desired pieces a straighforward
+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.
+
+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``.
diff --git a/libc/docs/entrypoints.rst b/libc/docs/entrypoints.rst
new file mode 100644
index 0000000..dfc0aec
--- /dev/null
+++ b/libc/docs/entrypoints.rst
@@ -0,0 +1,6 @@
+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.
diff --git a/libc/docs/header_generation.rst b/libc/docs/header_generation.rst
new file mode 100644
index 0000000..99b1177
--- /dev/null
+++ b/libc/docs/header_generation.rst
@@ -0,0 +1,98 @@
+Generating Public and Internal headers
+======================================
+
+Other libc implementations make use of preprocessor macro tricks to make header
+files platform agnostic. When macros aren't suitable, they rely on build
+system tricks to pick the right set of files to compile and export. While these
+approaches have served them well, parts of their systems have become extremely
+complicated making it hard to modify, extend or maintain. To avoid these
+problems in llvm-libc, we use a header generation mechanism. The mechanism is
+driven by a *header configuration language*.
+
+Header Configuration Language
+-----------------------------
+
+Header configuration language consists of few special *commands*. The header
+generation mechanism takes a an input file, which has an extension of
+``.h.def``, and produces a header file with ``.h`` extension. The header
+configuration language commands are listed in the input ``.h.def`` file. While
+reading a ``.h.def`` file, the header generation tool does two things:
+
+1. Copy the lines not containing commands as is into the output ``.h`` file.
+2. Replace the line on which a command occurs with some other text as directed
+ by the command. The replacment text can span multiple lines.
+
+Command syntax
+~~~~~~~~~~~~~~
+
+A command should be listed on a line by itself, and should not span more than
+one line. The first token to appear on the line is the command name prefixed
+with ``%%``. For example, a line with the ``include_file`` command should start
+with ``%%include_file``. There can be indentation spaces before the ``%%``
+prefix.
+
+Most commands typically take arguments. They are listed as a comma separated
+list of named identifiers within parenthesis, similar to the C function call
+syntax. Before performing the action corresponding to the command, the header
+generator replaces the arguments with concrete values.
+
+Argument Syntax
+~~~~~~~~~~~~~~~
+
+Arguments are named indentifiers but prefixed with ``$`` and enclosed in ``{``
+and ``}``. For example, ``${path_to_constants}``.
+
+Comments
+~~~~~~~~
+
+There can be cases wherein one wants to add comments in the .h.def file but
+does not want them to be copied into the generated header file. Such comments
+can be added by beginning the comment lines with the ``<!>`` prefix. Currently,
+comments have to be on lines of their own. That is, they cannot be suffixes like
+this:
+
+```
+%%include_file(a/b/c) <!> Path to c in b of a. !!! WRONG SYNTAX
+```
+
+Available Commands
+------------------
+
+Sub-sections below describe the commands currently available. Under each command
+is the discription of the arugments to the command, and the action taken by the
+header generation tool when processing a command.
+
+``include_file``
+~~~~~~~~~~~~~~~~
+
+This is a replacement command which should be listed in an input ``.h.def``
+file.
+
+Arguments
+
+ * **path argument** - An argument representing a path to a file. The file
+ should have an extension of ``.h.inc``.
+
+Action
+
+ This command instructs that the line on which the command appears should be
+ replaced by the contents of the file whose path is passed as argument to the
+ command.
+
+``begin``
+~~~~~~~~~
+
+This is not a replacement command. It is an error to list it in the input
+``.h.def`` file. It is normally listed in the files included by the
+``include_file`` command (the ``.h.inc`` files). A common use of this command it
+mark the beginning of what is to be included. This prevents copying items like
+license headers into the generated header file.
+
+Arguments
+
+ None.
+
+Action
+
+ The header generator will only include content starting from the line after the
+ line on which this command is listed.
diff --git a/libc/docs/implementation_standard.rst b/libc/docs/implementation_standard.rst
new file mode 100644
index 0000000..bba4fe6
--- /dev/null
+++ b/libc/docs/implementation_standard.rst
@@ -0,0 +1,85 @@
+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 related group of entrypoints will also live in a directory of
+their own. This directory will have a name indicative of the related group of
+entrypoints, and will be under the directory corresponding to the header file of
+the entrypoints. For example, functions like ``fopen`` and ``fclose`` cannot be
+tested independent of each other and hence will live in a directory named
+``src/stdio/file_operations``. On the other hand, the implementation of the
+``round`` function from ``math.h`` can be tested by itself, so it will live in
+the directory of its own named ``src/math/round/``.
+
+Implementation of entrypoints can span multiple ``.cpp`` and ``.h`` files, but
+there will be atleast one header file with name of the form
+``<entrypoint name>.h`` for every entrypoint. This header file is called as the
+implementation header file. For the ``round`` function, the path to the
+implementation header file will be ``src/math/round/round.h``. The rest of this
+document explains the structure of implementation header files and ``.cpp``
+files.
+
+Implementaion Header File Structure
+-----------------------------------
+
+We will use the ``round`` function from the public ``math.h`` header file as an
+example. The ``round`` function will be declared in an internal header file
+``src/math/round/round.h`` as follows::
+
+ // --- round.h --- //
+ #ifndef LLVM_LIBC_SRC_MATH_ROUND_ROUND_H
+ #define LLVM_LIBC_SRC_MATH_ROUND_ROUND_H
+
+ namespace __llvm_libc {
+
+ double round(double);
+
+ } // namespace __llvm_libc
+
+ #endif LLVM_LIBC_SRC_MATH_ROUND_ROUND_H
+
+Notice that the ``round`` function declaration is nested inside the namespace
+``__llvm_libc``. All implementation constructs in LLVM-libc are declared within
+the namespace ``__llvm_libc``.
+
+``.cpp`` File Structure
+-----------------------
+
+The implementation can span multiple ``.cpp`` files. However, the signature of
+the entrypoint function should make use of a special macro. For example, the
+``round`` function from ``math.h`` should be defined as follows, say in the file
+``src/math/math/round.cpp``::
+
+ // --- round.cpp --- //
+
+ namespace __llvm_libc {
+
+ double LLVM_LIBC_ENTRYPOINT(round)(double d) {
+ // ... implementation goes here.
+ }
+
+ } // namespace __llvm_libc
+
+Notice the use of the macro ``LLVM_LIBC_ENTRYPOINT``. This macro helps us define
+an C alias symbol for the C++ implementation. The C alias need not be added by
+the macro by itself. For example, for ELF targets, the macro is defined as
+follows::
+
+ #define ENTRYPOINT_SECTION_ATTRIBUTE(name) \
+ __attribute__((section(".llvm.libc.entrypoint."#name)))
+ #define LLVM_LIBC_ENTRYPOINT(name) ENTRYPOINT_SECTION_ATTRIBUTE(name) name
+
+The macro places the C++ function in a unique section with name
+``.llvm.libc.entrypoint.<function name>``. This allows us to add a C alias using
+a post build step. For example, for the ``round`` function, one can use
+``objcopy`` to add an alias symbol as follows::
+
+ objcopy --add-symbol round=.llvm.libc.entrypoint.round:0,function round.o
+
+NOTE: We use a post build ``objcopy`` step to add an alias instead of using
+the ``__attribute__((alias))``. For C++, this ``alias`` attribute requires
+mangled names of the referees. Using the post build ``objcopy`` step helps
+us avoid putting mangled names with ``alias`` atttributes.
diff --git a/libc/docs/source_layout.rst b/libc/docs/source_layout.rst
new file mode 100644
index 0000000..b06ad96
--- /dev/null
+++ b/libc/docs/source_layout.rst
@@ -0,0 +1,85 @@
+LLVM-libc Source Tree Layout
+============================
+
+At the top-level, LLVM-libc source tree is organized in to the following
+directories::
+
+ + libc
+ - cmake
+ - docs
+ - include
+ - lib
+ - loader
+ - src
+ + utils
+ - build_scripts
+ - testing
+ - www
+
+Each of these directories is explained in detail below.
+
+The ``cmake`` directory
+-----------------------
+
+The ``cmake`` directory contains the implementations of LLVM-libc's CMake build
+rules.
+
+The ``docs`` directory
+----------------------
+
+The ``docs`` directory contains design docs and also informative documents like
+this document on source layout.
+
+The ``include`` directory
+-------------------------
+
+The ``include`` directory contains:
+
+1. Self contained public header files - These are header files which are
+ already in the form that get installed when LLVM-libc is installed on a user's
+ computer.
+2. ``*.h.def`` and ``*.h.in`` files - These files are used to construct the
+ generated public header files.
+3. A ``CMakeLists.txt`` file - This file lists the targets for the self
+ contained and generated public header files.
+
+The ``lib`` directory
+---------------------
+
+This directory contains a ``CMakeLists.txt`` file listing the targets for the
+public libraries ``libc.a``, ``libm.a`` etc.
+
+The ``loader`` directory
+------------------------
+
+This directory contains the implementations of the application loaders like
+``crt1.o`` etc.
+
+The ``src`` directory
+---------------------
+
+This directory contains the implementations of the llvm-libc entrypoints. It is
+further organized as follows:
+
+1. There is a toplevel CMakeLists.txt file.
+2. For every public header file provided by llvm-libc, there exists a
+ corresponding directory in the ``src`` directory. The name of the directory
+ is same as the base name of the header file. For example, the directory
+ corresponding to the public ``math.h`` header file is named ``math``. The
+ implementation standard document explains more about the *header*
+ directories.
+
+The ``www`` directory
+---------------------
+
+The ``www`` directory contains the HTML content of libc.llvm.org
+
+The ``utils/build_scripts`` directory
+-------------------------------------
+
+This directory contains scripts which support the build system, tooling etc.
+
+The ``utils/testing`` directory
+-------------------------------
+
+This directory contains testing infrastructure.