[libc] add uefi docs

[RossComputerGuy]

Adds documentation for the UEFI target since #131246 was merged.

[llvmbot]

@llvm/pr-subscribers-libc

Author: Tristan Ross (RossComputerGuy)

Changes

Adds documentation for the UEFI target since #131246 was merged.

---

Full diff: https://github.com/llvm/llvm-project/pull/131426.diff

7 Files Affected:

• (modified) libc/docs/getting_started.rst (+2-2)
• (modified) libc/docs/index.rst (+1)
• (added) libc/docs/uefi/building.rst (+53)
• (added) libc/docs/uefi/index.rst (+19)
• (added) libc/docs/uefi/support.rst (+86)
• (added) libc/docs/uefi/testing.rst (+29)
• (added) libc/docs/uefi/using.rst (+17)

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<full_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=<Debug|Release>  \ # Select build type
+      -DCMAKE_INSTALL_PREFIX=<PATH>       \ # 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_<triple>_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..41a30527f4e43
--- /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* suppport 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
+   suppport
+   testing
diff --git a/libc/docs/uefi/support.rst b/libc/docs/uefi/support.rst
new file mode 100644
index 0000000000000..e32896aa45021
--- /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 <build_and_test>`
+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..8449a91abcbc2
--- /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<libc_uefi_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<libc_uefi_support>` for a comprehensive list.