106 lines · plain
1.. _porting:2 3=======================================4Bringup on a New OS or Architecture5=======================================6 7.. contents:: Table of Contents8 :depth: 49 :local:10 11CI builders12===========13 14If you are contributing a port for an operating system or architecture which15is not covered by existing CI builders, you will also have to present a plan16for testing and contribute a CI builder. See17`this guide <https://llvm.org/docs/HowToAddABuilder.html>`_ for information18on how to add new builders to the19`LLVM buildbot <https://lab.llvm.org/buildbot>`_.20You will either have to extend the existing21`Linux script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-linux.py>`_22and/or23`Windows script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-windows.py>`_24or add a new script for your operating system.25 26An OS specific config directory27===============================28 29If you are starting to bring up LLVM's libc on a new operating system, the first30step is to add a directory for that OS in the ``libc/config`` directory. Both31`Linux <https://github.com/llvm/llvm-project/tree/main/libc/config/linux>`_ and32`Windows <https://github.com/llvm/llvm-project/tree/main/libc/config/windows>`_,33the two operating systems on which LLVM's libc is being actively developed,34have their own config directory.35 36.. note:: Windows development is not as active as the development on Linux.37 There is a38 `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 the42 `Fuchsia <https://fuchsia.dev/>`_ operating system also. However, there is no43 config directory for Fuchsia as the bring up is being done in the Fuchsia44 source tree.45 46Architecture Subdirectory47=========================48 49There are parts of the libc which are implemented differently for different50architectures. The simplest example of this is the ``syscall`` function and51its internal implementation - its Linux implementation differs for different52architectures. Since a large part of the libc makes use of syscalls (or an53equivalent on non-Linux like platforms), it might be simpler and convenient to54bring up the libc for one architecture at a time. In such cases, wherein the55support surface of LLVM's libc differs for each target architecture, one will56have to add a subdirectory (within the config directory of the operating57system) for each target architecture, and list the relevant config information58separately in those subdirectories. For example, for Linux, the x86_64 and59aarch64 configs are in separate directories, named60`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_61and `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_.62The libc CMake machinery looks for subdirectories named after the target63architecture.64 65The entrypoints.txt file66========================67 68One of the important pieces of config information is listed in a file named69``entrypoints.txt``. This file lists the targets for the entrypoints (see70:ref:`entrypoints`) you want to include in the static archive of the libc (for71the :ref:`overlay_mode` and/or the :ref:`full_host_build`.) If you are doing an72architecture specific bring up, then an ``entrypoints.txt`` file should be73created in the architecture subdirectory for each architecture. Else, having a74single ``entrypoints.txt`` in the operating system directory is sufficient.75 76The Linux config has an ``entrypoint.txt`` for each individual target77architecture 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>`_ and79`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_. On the80other 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 83A typical bring up procedure will normally bring up a small group of entrypoints84at a time. The usual practice is to progressively add the targets for those85entrypoints to the ``entrypoints.txt`` file as they are being brought up. The86same is the case if one is implementing a new entrypoint - the target for the87new entrypoint should be added to the relevant ``entrypoints.txt`` file. If88the implementation of the new entrypoint supports multiple operating systems and89target architectures, then multiple ``entrypoints.txt`` files will have to be90updated.91 92The headers.txt file93====================94 95Another important piece of config information is listed in a file named96``headers.txt``. It lists the targets for the set of public headers that are97provided by the libc. This is relevant only if the libc is to be used in the98:ref:`full_host_build` on the target operating system and architecture. As with99the ``entrypoints.txt`` file, one ``headers.txt`` file should be listed for100each individual target architecture if you are doing an architecture specific101bring up. The Linux config has ``headers.txt`` file listed separately for the102`aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_103config and the104`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_105config.106