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 Architecture Subdirectory
  47 =========================
  48
  49 There are parts of the libc which are implemented differently for different
  50 architectures. The simplest example of this is the ``syscall`` function and
  51 its internal implementation - its Linux implementation differs for different
  52 architectures. Since a large part of the libc makes use of syscalls (or an
  53 equivalent on non-Linux like platforms), it might be simpler and convenient to
  54 bring up the libc for one architecture at a time. In such cases, wherein the
  55 support surface of LLVM's libc differs for each target architecture, one will
  56 have to add a subdirectory (within the config directory os the operating
  57 system) for each target architecture, and list the relevant config information
  58 separately in those subdirectories. For example, for Linux, the x86_64 and
  59 aarch64 configs are in separate directories, named
  60 `x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_
  61 and `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_.
  62 The libc CMake machinery looks for subdirectories named after the target
  63 architecture.
  64
  65 The entrypoints.txt file
  66 ========================
  67
  68 One of the important pieces of config information is listed in a file named
  69 ``entrypoints.txt``. This file lists the targets for the entrypoints (see
  70 :ref:`entrypoints`) you want to include in the static archive of the libc (for
  71 the :ref:`overlay_mode` and/or the :ref:`fullbuild_mode`.) If you are doing an
  72 architecture specific bring up, then an ``entrypoints.txt`` file should be
  73 created in the architecture subdirectory for each architecture. Else, having a
  74 single ``entrypoints.txt`` in the operating system directory is sufficient.
  75
  76 The Linux config has an ``entrypoint.txt`` for each individual target
  77 architecture separately: `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_,
  78 `arm32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm>`_ and
  79 `x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_. On the
  80 other hand, the Windows config has a single ``entrypoints.txt``
  81 `file <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_.
  82
  83 A typical bring up procedure will normally bring up a small group of entrypoints
  84 at a time. The usual practice is to progressively add the targets for those
  85 entrypoints to the ``entrypoints.txt`` file as they are being brought up. The
  86 same is the case if one is implementing a new entrypoint - the target for the
  87 new entrypoint should be added to the relevant ``entrypoints.txt`` file. If
  88 the implementation of the new entrypoint supports multiple operating systems and
  89 target architectures, then multiple ``entrypoints.txt`` files will have to be
  90 updated.
  91
  92 The headers.txt file
  93 ====================
  94
  95 Another important piece of config information is listed in a file named
  96 ``headers.txt``. It lists the targets for the set of public headers that are
  97 provided by the libc. This is relevant only if the libc is to be used in the
  98 :ref:`fullbuild_mode` on the target operating system and architecture. As with
  99 the ``entrypoints.txt`` file, one ``headers.txt`` file should be listed for
 100 each individual target architecture if you are doing an architecture specific
 101 bring up. The Linux config has ``headers.txt`` file listed separately for the
 102 `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_
 103 config and the
 104 `x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_
 105 config.