diff --git a/libc/docs/getting_started.rst b/libc/docs/getting_started.rst index 51c295f384a06..9d846e6d22acf 100644 --- a/libc/docs/getting_started.rst +++ b/libc/docs/getting_started.rst @@ -54,5 +54,5 @@ We can then compile and run hello world via: This was what we call a "full build" of llvm-libc. From here, you can visit :ref:`full_host_build` for more info, :ref:`full_cross_build` for cross -compiling, :ref:`overlay_mode` for mixing llvm-libc with another libc, or -:ref:`libc_gpu` for targeting GPUs. +compiling, :ref:`overlay_mode` for mixing llvm-libc with another libc, +:ref:`libc_gpu` for targeting GPUs, or :ref:`libc_uefi` for targeting UEFI. diff --git a/libc/docs/index.rst b/libc/docs/index.rst index f0e5c9db79b40..bf982cc456349 100644 --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -63,6 +63,7 @@ LLVM-libc aspires to a unique place in the software ecosystem. The goals are: full_cross_build overlay_mode gpu/index.rst + uefi/index.rst configure .. toctree:: diff --git a/libc/docs/uefi/building.rst b/libc/docs/uefi/building.rst new file mode 100644 index 0000000000000..39f0c47bf2ff2 --- /dev/null +++ b/libc/docs/uefi/building.rst @@ -0,0 +1,53 @@ +.. _libc_uefi_building: + +====================== +Building libc for UEFI +====================== + +.. contents:: Table of Contents + :depth: 4 + :local: + +Building LLVM libc for UEFI +=========================== + +This document will present recipes to build the LLVM C library for UEFI. +UEFI builds use the same :ref:`cross build` support as +the other targets. However, the UEFI target has the restriction that it *must* +be built with an up-to-date ``clang`` compiler. This is because UEFI support +in ``clang`` is still an experimental feature. + +Currently, it is only possible to build LLVM libc for UEFI for ``x86_64`` +CPUs. This is due to the target not being enabled for ``aarch64`` and +``riscv64``. + +Once you have finished building, refer to :ref:`libc_uefi_usage` to get started +with the newly built C library. + +Standard runtimes build +----------------------- + +The simplest way to build for UEFI is to use the existing LLVM runtimes +support. This will automatically handle bootstrapping an up-to-date ``clang`` +compiler and use it to build the C library. The following CMake invocation +will instruct it to build the ``libc`` runtime targeting ``x86_64`` CPUs. + +.. code-block:: sh + + $> cd llvm-project # The llvm-project checkout + $> mkdir build + $> cd build + $> cmake ../llvm -G Ninja \ + -DLLVM_ENABLE_PROJECTS="clang;lld" \ + -DCMAKE_BUILD_TYPE= \ # Select build type + -DCMAKE_INSTALL_PREFIX= \ # Where the libraries will live + -DLLVM_DEFAULT_TARGET_TRIPLE=x86_64-unknown-uefi-llvm \ + -DLLVM_RUNTIME_TARGETS=x86_64-unknown-uefi-llvm \ + -DRUNTIMES_x86_64-unknown-uefi-llvm_LLVM_ENABLE_RUNTIMES=libc \ + -DRUNTIMES_x86_64-unknown-uefi-llvm_LLVM_LIBC_FULL_BUILD=true \ + $> ninja install + +We need ``clang`` to build the UEFI C library and ``lld`` to link UEFI PE +executables, so we enable them in ``LLVM_ENABLE_PROJECTS``. We then set +``RUNTIMES__LLVM_ENABLE_RUNTIMES`` to enable ``libc`` for the UEFI +targets. diff --git a/libc/docs/uefi/index.rst b/libc/docs/uefi/index.rst new file mode 100644 index 0000000000000..db86507f63f2c --- /dev/null +++ b/libc/docs/uefi/index.rst @@ -0,0 +1,19 @@ +.. _libc_uefi: + +============= +libc for UEFI +============= + +.. note:: This feature is very experimental and may change in the future. + +The *UEFI* support for LLVM's libc project aims to provide a standard libc +frontend to the UEFI protocols. This allows for many existing +applications to be easily ported to UEFI. Nagivate using the links below to +learn more about this project. + +.. toctree:: + + building + using + support + testing diff --git a/libc/docs/uefi/support.rst b/libc/docs/uefi/support.rst new file mode 100644 index 0000000000000..335990566c66c --- /dev/null +++ b/libc/docs/uefi/support.rst @@ -0,0 +1,86 @@ +.. _libc_uefi_support: + +=================== +Supported Functions +=================== + +.. include:: ../check.rst + +.. contents:: Table of Contents + :depth: 4 + :local: + +The follow functions and headers are supported at least partially in +UEFI. Some functions are implemented fully for UEFI. + +ctype.h +------- + +============= ========= +Function Name Available +============= ========= +============= ========= + +string.h +-------- + +============= ========= +Function Name Available +============= ========= +============= ========= + +strings.h +--------- + +============= ========= +Function Name Available +============= ========= +============= ========= + +stdbit.h +-------- + +============= ========= +Function Name Available +============= ========= +============= ========= + +stdlib.h +-------- + +============= ========= +Function Name Available +============= ========= +============= ========= + +inttypes.h +---------- + +============= ========= +Function Name Available +============= ========= +============= ========= + +stdio.h +-------- + +============= ========= +Function Name Available +============= ========= +============= ========= + +time.h +------ + +============= ========= +Function Name Available +============= ========= +============= ========= + +assert.h +-------- + +============= ========= +Function Name Available +============= ========= +============= ========= diff --git a/libc/docs/uefi/testing.rst b/libc/docs/uefi/testing.rst new file mode 100644 index 0000000000000..0c484f093d6b6 --- /dev/null +++ b/libc/docs/uefi/testing.rst @@ -0,0 +1,29 @@ +.. _libc_uefi_testing: + +========================== +Testing the UEFI C library +========================== + +.. contents:: Table of Contents + :depth: 4 + :local: + +Testing infrastructure +====================== + +The LLVM C library supports different kinds of :ref:`tests ` +depending on the build configuration. The UEFI target is considered a full build +and therefore provides all of its own utilities to build and run the generated +tests. Currently UEFI supports two kinds of tests. + +#. **Hermetic tests** - These are unit tests built with a test suite similar to + Google's ``gtest`` infrastructure. These use the same infrastructure as unit + tests except that the entire environment is self-hosted. + +#. **Integration tests** - These are lightweight tests that simply call a + ``main`` function and checks if it returns non-zero. + +The UEFI target uses the same testing infrastructure as the other supported +``libc`` targets. We do this by treating UEFI as a standard hosted environment +capable of launching a ``main`` function. This only requires us to run the +tests in a UEFI environment. diff --git a/libc/docs/uefi/using.rst b/libc/docs/uefi/using.rst new file mode 100644 index 0000000000000..718ebd0fc432a --- /dev/null +++ b/libc/docs/uefi/using.rst @@ -0,0 +1,17 @@ +.. _libc_uefi_usage: + +=================== +Using libc for UEFI +=================== + +.. contents:: Table of Contents + :depth: 4 + :local: + +Using the UEFI C library +======================== + +Once you have finished :ref:`building` the UEFI C library +it can be used to run libc or libm functions inside of UEFI Images. Currently, +not all C standard functions are supported in UEFI. Consult the :ref:`list of +supported functions` for a comprehensive list.