libc/docs/porting.rst

   1 .. _porting:
   2
   3 =======================================
   4 Bringup on a New OS or Architecture
   5 =======================================
   6
   7 .. contents:: Table of Contents
   8   :depth: 4
   9   :local:
  10
  11 CI builders
  12 ===========
  13
  14 If you are contributing a port for an operating system or architecture which
  15 is not covered by existing CI builders, you will also have to present a plan
  16 for testing and contribute a CI builder. See
  17 `this guide <https://llvm.org/docs/HowToAddABuilder.html>`_ for information
  18 on how to add new builders to the
  19 `LLVM buildbot <https://lab.llvm.org/buildbot>`_.
  20 You will either have to extend the existing
  21 `Linux script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-linux.py>`_
  22 and/or
  23 `Windows script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-windows.py>`_
  24 or add a new script for your operating system.
  25
  26 An OS specific config directory
  27 ===============================
  28
  29 If you are starting to bring up LLVM's libc on a new operating system, the first
  30 step is to add a directory for that OS in the ``libc/config`` directory. Both
  31 `Linux <https://github.com/llvm/llvm-project/tree/main/libc/config/linux>`_ and
  32 `Windows <https://github.com/llvm/llvm-project/tree/main/libc/config/windows>`_,
  33 the two operating systems on which LLVM's libc is being actively developed,
  34 have their own config directory.
  35
  36 .. note:: Windows development is not as active as the development on Linux.
  37    There is a
  38    `Darwin <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin>`_
  39    config also which is in a similar state as Windows.
  40
  41 .. note:: LLVM's libc is being brought up on the
  42    `Fuchsia <https://fuchsia.dev/>`_ operating system also. However, there is no
  43    config directory for Fuchsia as the bring up is being done in the Fuchsia
  44    source tree.
  45
  46 The api.td file
  47 ---------------
  48
  49 If the :ref:`fullbuild_mode` is to be supported on the new operating system,
  50 then a file named ``api.td`` should be added in its config directory. It is
  51 written in the
  52 `LLVM tablegen language <https://llvm.org/docs/TableGen/ProgRef.html>`_.
  53 It lists all the relevant macros and type definitions we want in the
  54 public libc header files. See the existing Linux
  55 `api.td <https://github.com/llvm/llvm-project/blob/main/libc/config/linux/api.td>`_
  56 file as an example to prepare the ``api.td`` file for the new operating system.
  57
  58 .. note:: In future, LLVM tablegen will be replaced with a different DSL to list
  59    config information.
  60
  61 Architecture Subdirectory
  62 =========================
  63
  64 There are parts of the libc which are implemented differently for different
  65 architectures. The simplest example of this is the ``syscall`` function and
  66 its internal implementation - its Linux implementation differs for different
  67 architectures. Since a large part of the libc makes use of syscalls (or an
  68 equivalent on non-Linux like platforms), it might be simpler and convenient to
  69 bring up the libc for one architecture at a time. In such cases, wherein the
  70 support surface of LLVM's libc differs for each target architecture, one will
  71 have to add a subdirectory (within the config directory os the operating
  72 system) for each target architecture, and list the relevant config information
  73 separately in those subdirectories. For example, for Linux, the x86_64 and
  74 aarch64 configs are in separate directories, named
  75 `x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_
  76 and `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_.
  77 The libc CMake machinery looks for subdirectories named after the target
  78 architecture.
  79
  80 The entrypoints.txt file
  81 ========================
  82
  83 One of the important pieces of config information is listed in a file named
  84 ``entrypoints.txt``. This file lists the targets for the entrypoints (see
  85 :ref:`entrypoints`) you want to include in the static archive of the libc (for
  86 the :ref:`overlay_mode` and/or the :ref:`fullbuild_mode`.) If you are doing an
  87 architecture specific bring up, then an ``entrypoints.txt`` file should be
  88 created in the architecture subdirectory for each architecture. Else, having a
  89 single ``entrypoints.txt`` in the operating system directory is sufficient.
  90
  91 The Linux config has an ``entrypoint.txt`` for each individual target
  92 architecture separately: `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_,
  93 `arm32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm>`_ and
  94 `x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_. On the
  95 other hand, the Windows config has a single ``entrypoints.txt``
  96 `file <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_.
  97
  98 A typical bring up procedure will normally bring up a small group of entrypoints
  99 at a time. The usual practice is to progressively add the targets for those
 100 entrypoints to the ``entrypoints.txt`` file as they are being brought up. The
 101 same is the case if one is implementing a new entrypoint - the target for the
 102 new entrypoint should be added to the relevant ``entrypoints.txt`` file. If
 103 the implementation of the new entrypoint supports multiple operating systems and
 104 target architectures, then multiple ``entrypoints.txt`` files will have to be
 105 updated.
 106
 107 The headers.txt file
 108 ====================
 109
 110 Another important piece of config information is listed in a file named
 111 ``headers.txt``. It lists the targets for the set of public headers that are
 112 provided by the libc. This is relevant only if the libc is to be used in the
 113 :ref:`fullbuild_mode` on the target operating system and architecture. As with
 114 the ``entrypoints.txt`` file, one ``headers.txt`` file should be listed for
 115 each individual target architecture if you are doing an architecture specific
 116 bring up. The Linux config has ``headers.txt`` file listed separately for the
 117 `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_
 118 config and the
 119 `x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_
 120 config.