Skip to content

Commit 4e841d7

Browse files
RossComputerGuyRossComputerGuy
authored
[libc] add uefi docs (#131426)
Adds documentation for the UEFI target since #131246 was merged.
1 parent 7c98cdd commit 4e841d7

File tree

7 files changed

+207
-2
lines changed

7 files changed

+207
-2
lines changed

‎libc/docs/getting_started.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,5 +54,5 @@ We can then compile and run hello world via:
5454
5555
This was what we call a "full build" of llvm-libc. From here, you can visit
5656
:ref:`full_host_build` for more info, :ref:`full_cross_build` for cross
57-
compiling, :ref:`overlay_mode` for mixing llvm-libc with another libc, or
58-
:ref:`libc_gpu` for targeting GPUs.
57+
compiling, :ref:`overlay_mode` for mixing llvm-libc with another libc,
58+
:ref:`libc_gpu` for targeting GPUs, or :ref:`libc_uefi` for targeting UEFI.

‎libc/docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ LLVM-libc aspires to a unique place in the software ecosystem. The goals are:
6363
full_cross_build
6464
overlay_mode
6565
gpu/index.rst
66+
uefi/index.rst
6667
configure
6768

6869
.. toctree::

‎libc/docs/uefi/building.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
.. _libc_uefi_building:
2+
3+
======================
4+
Building libc for UEFI
5+
======================
6+
7+
.. contents:: Table of Contents
8+
:depth: 4
9+
:local:
10+
11+
Building LLVM libc for UEFI
12+
===========================
13+
14+
This document will present recipes to build the LLVM C library for UEFI.
15+
UEFI builds use the same :ref:`cross build<full_cross_build>` support as
16+
the other targets. However, the UEFI target has the restriction that it *must*
17+
be built with an up-to-date ``clang`` compiler. This is because UEFI support
18+
in ``clang`` is still an experimental feature.
19+
20+
Currently, it is only possible to build LLVM libc for UEFI for ``x86_64``
21+
CPUs. This is due to the target not being enabled for ``aarch64`` and
22+
``riscv64``.
23+
24+
Once you have finished building, refer to :ref:`libc_uefi_usage` to get started
25+
with the newly built C library.
26+
27+
Standard runtimes build
28+
-----------------------
29+
30+
The simplest way to build for UEFI is to use the existing LLVM runtimes
31+
support. This will automatically handle bootstrapping an up-to-date ``clang``
32+
compiler and use it to build the C library. The following CMake invocation
33+
will instruct it to build the ``libc`` runtime targeting ``x86_64`` CPUs.
34+
35+
.. code-block:: sh
36+
37+
$> cd llvm-project # The llvm-project checkout
38+
$> mkdir build
39+
$> cd build
40+
$> cmake ../llvm -G Ninja \
41+
-DLLVM_ENABLE_PROJECTS="clang;lld" \
42+
-DCMAKE_BUILD_TYPE=<Debug|Release> \ # Select build type
43+
-DCMAKE_INSTALL_PREFIX=<PATH> \ # Where the libraries will live
44+
-DLLVM_DEFAULT_TARGET_TRIPLE=x86_64-unknown-uefi-llvm \
45+
-DLLVM_RUNTIME_TARGETS=x86_64-unknown-uefi-llvm \
46+
-DRUNTIMES_x86_64-unknown-uefi-llvm_LLVM_ENABLE_RUNTIMES=libc \
47+
-DRUNTIMES_x86_64-unknown-uefi-llvm_LLVM_LIBC_FULL_BUILD=true \
48+
$> ninja install
49+
50+
We need ``clang`` to build the UEFI C library and ``lld`` to link UEFI PE
51+
executables, so we enable them in ``LLVM_ENABLE_PROJECTS``. We then set
52+
``RUNTIMES_<triple>_LLVM_ENABLE_RUNTIMES`` to enable ``libc`` for the UEFI
53+
targets.

‎libc/docs/uefi/index.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. _libc_uefi:
2+
3+
=============
4+
libc for UEFI
5+
=============
6+
7+
.. note:: This feature is very experimental and may change in the future.
8+
9+
The *UEFI* support for LLVM's libc project aims to provide a standard libc
10+
frontend to the UEFI protocols. This allows for many existing
11+
applications to be easily ported to UEFI. Nagivate using the links below to
12+
learn more about this project.
13+
14+
.. toctree::
15+
16+
building
17+
using
18+
support
19+
testing

‎libc/docs/uefi/support.rst

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
.. _libc_uefi_support:
2+
3+
===================
4+
Supported Functions
5+
===================
6+
7+
.. include:: ../check.rst
8+
9+
.. contents:: Table of Contents
10+
:depth: 4
11+
:local:
12+
13+
The follow functions and headers are supported at least partially in
14+
UEFI. Some functions are implemented fully for UEFI.
15+
16+
ctype.h
17+
-------
18+
19+
============= =========
20+
Function Name Available
21+
============= =========
22+
============= =========
23+
24+
string.h
25+
--------
26+
27+
============= =========
28+
Function Name Available
29+
============= =========
30+
============= =========
31+
32+
strings.h
33+
---------
34+
35+
============= =========
36+
Function Name Available
37+
============= =========
38+
============= =========
39+
40+
stdbit.h
41+
--------
42+
43+
============= =========
44+
Function Name Available
45+
============= =========
46+
============= =========
47+
48+
stdlib.h
49+
--------
50+
51+
============= =========
52+
Function Name Available
53+
============= =========
54+
============= =========
55+
56+
inttypes.h
57+
----------
58+
59+
============= =========
60+
Function Name Available
61+
============= =========
62+
============= =========
63+
64+
stdio.h
65+
--------
66+
67+
============= =========
68+
Function Name Available
69+
============= =========
70+
============= =========
71+
72+
time.h
73+
------
74+
75+
============= =========
76+
Function Name Available
77+
============= =========
78+
============= =========
79+
80+
assert.h
81+
--------
82+
83+
============= =========
84+
Function Name Available
85+
============= =========
86+
============= =========

‎libc/docs/uefi/testing.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. _libc_uefi_testing:
2+
3+
==========================
4+
Testing the UEFI C library
5+
==========================
6+
7+
.. contents:: Table of Contents
8+
:depth: 4
9+
:local:
10+
11+
Testing infrastructure
12+
======================
13+
14+
The LLVM C library supports different kinds of :ref:`tests <build_and_test>`
15+
depending on the build configuration. The UEFI target is considered a full build
16+
and therefore provides all of its own utilities to build and run the generated
17+
tests. Currently UEFI supports two kinds of tests.
18+
19+
#. **Hermetic tests** - These are unit tests built with a test suite similar to
20+
Google's ``gtest`` infrastructure. These use the same infrastructure as unit
21+
tests except that the entire environment is self-hosted.
22+
23+
#. **Integration tests** - These are lightweight tests that simply call a
24+
``main`` function and checks if it returns non-zero.
25+
26+
The UEFI target uses the same testing infrastructure as the other supported
27+
``libc`` targets. We do this by treating UEFI as a standard hosted environment
28+
capable of launching a ``main`` function. This only requires us to run the
29+
tests in a UEFI environment.

‎libc/docs/uefi/using.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. _libc_uefi_usage:
2+
3+
===================
4+
Using libc for UEFI
5+
===================
6+
7+
.. contents:: Table of Contents
8+
:depth: 4
9+
:local:
10+
11+
Using the UEFI C library
12+
========================
13+
14+
Once you have finished :ref:`building<libc_uefi_building>` the UEFI C library
15+
it can be used to run libc or libm functions inside of UEFI Images. Currently,
16+
not all C standard functions are supported in UEFI. Consult the :ref:`list of
17+
supported functions<libc_uefi_support>` for a comprehensive list.

0 commit comments

Comments
 (0)