[libc-commits] [libc] [libc] add uefi docs (PR #131426)
Tristan Ross via libc-commits
libc-commits at lists.llvm.org
Fri Mar 14 21:29:43 PDT 2025
https://github.com/RossComputerGuy updated https://github.com/llvm/llvm-project/pull/131426
>From 84568773cb3ae3d7603db41ed1e86612ff5331a6 Mon Sep 17 00:00:00 2001
From: Tristan Ross <tristan.ross at midstall.com>
Date: Fri, 14 Mar 2025 21:12:58 -0700
Subject: [PATCH] [libc] add uefi docs
---
libc/docs/getting_started.rst | 4 +-
libc/docs/index.rst | 1 +
libc/docs/uefi/building.rst | 53 +++++++++++++++++++++
libc/docs/uefi/index.rst | 19 ++++++++
libc/docs/uefi/support.rst | 86 +++++++++++++++++++++++++++++++++++
libc/docs/uefi/testing.rst | 29 ++++++++++++
libc/docs/uefi/using.rst | 17 +++++++
7 files changed, 207 insertions(+), 2 deletions(-)
create mode 100644 libc/docs/uefi/building.rst
create mode 100644 libc/docs/uefi/index.rst
create mode 100644 libc/docs/uefi/support.rst
create mode 100644 libc/docs/uefi/testing.rst
create mode 100644 libc/docs/uefi/using.rst
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..fa4c611556f8a
--- /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..986e71866e443
--- /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.
More information about the libc-commits
mailing list