https://github.com/AaronBallman updated
https://github.com/llvm/llvm-project/pull/132232
>From 5008e3cff11bb019e22148926f0088fbb8fc530f Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aa...@aaronballman.com>
Date: Thu, 20 Mar 2025 11:00:05 -0400
Subject: [PATCH 1/5] [Docs] Document freestanding requirements
This adds some initial documentation about freestanding requirements
for Clang. The most critical part of the documentation is spelling out
that a conforming freestanding C Standard Library is required; Clang
will not be providing the headers for <string.h> in C23 which expose a
number of symbols in freestanding mode.
The docs also make it clear that in addition to a conforming
freestanding C standard library, the library must provide some
additional symbols which LLVM requires.
These docs are not comprehensive, this is just getting the bare bones
in place so that they can be expanded later.
This also updates the C status page to make it clear that we don't have
anything to do for WG14 N2524 which adds string interfaces to
freestanding mode.
---
clang/docs/CommandGuide/clang.rst | 7 ++++---
clang/docs/UsersManual.rst | 24 ++++++++++++++++++++++++
clang/www/c_status.html | 5 -----
3 files changed, 28 insertions(+), 8 deletions(-)
diff --git a/clang/docs/CommandGuide/clang.rst
b/clang/docs/CommandGuide/clang.rst
index f0d94a4e628b0..dfe28fc5d2bcb 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -262,9 +262,10 @@ Language Selection and Mode Options
.. option:: -ffreestanding
Indicate that the file should be compiled for a freestanding, not a hosted,
- environment. Note that it is assumed that a freestanding environment will
- additionally provide `memcpy`, `memmove`, `memset` and `memcmp`
- implementations, as these are needed for efficient codegen for many programs.
+ environment. Note that a freestanding build still requires linking against a C
+ Standard Library which supports the freestanding interfaces for the specified
+ language mode and target environment. This includes functions like `memcpy`,
+ `memmove`, `memset` and `memcmp`.
.. option:: -fno-builtin
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 2ea4b9d90ad34..d73e8eb78dbf6 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1073,6 +1073,30 @@ inputs. Here is some example of ``$``-prefixed options:
Language and Target-Independent Features
========================================
+Freestanding Builds
+-------------------
+Passing the ``-ffreestanding`` flag causes Clang to build for a freestanding
+(rather than a hosted) environment. The ``__STDC_HOSTED__`` predefined macro
+will expand to ``0`` in a freestanding environment. In such an environment,
+execution of the program may happen without an operating system and so a
+startup function (e.g., ``main``) may not be automatically called, though file
+scope objects which need to run startup code (constructors in C++,
+``__attribute__((constructor))``, etc) are executed via implementation-defined
+means such as ``__cxx_global_var_init``.
+
+A freestanding environment is not one which has no C standard library support.
+A conforming freestanding C standard library implementation is required. Clang
+supplies some of the header files needed for a freestanding execution, such as
+``<stdarg.h>``, ``<limits.h>``, ``<stdint.h>``, etc. However, Clang still
+requires the runtime freestanding library to provide the interfaces required by
+Clause 4 (Conformance) of the C standard. Additionally, Clang requires the
+following runtime interfaces to be provided:
+
+ * `memcpy`,
+ * `memmove`,
+ * `memset`, and
+ * `memcmp`.
+
Controlling Errors and Warnings
-------------------------------
diff --git a/clang/www/c_status.html b/clang/www/c_status.html
index c9e2eda4304f3..ee0cd057916ba 100644
--- a/clang/www/c_status.html
+++ b/clang/www/c_status.html
@@ -534,11 +534,6 @@ <h2 id="c2x">C23 implementation status</h2>
<td class="full" align="center">Clang 16</td>
</tr>
<!-- Apr 2021 Papers -->
- <tr>
- <td>String functions for freestanding implementations</td>
- <td><a
href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2524.htm";>N2524</a></td>
- <td class="none" align="center">No</td>
- </tr>
<tr>
<td>Digit separators</td>
<td><a
href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2626.pdf";>N2626</a></td>
>From e6bcd391ecbbad5125e472dc16ff2883aaa85eb7 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aa...@aaronballman.com>
Date: Fri, 21 Mar 2025 13:18:50 -0400
Subject: [PATCH 2/5] Update based on review feedback
---
clang/docs/UsersManual.rst | 17 +++++++----------
1 file changed, 7 insertions(+), 10 deletions(-)
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index d73e8eb78dbf6..30cfad1b1d68d 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1076,13 +1076,11 @@ Language and Target-Independent Features
Freestanding Builds
-------------------
Passing the ``-ffreestanding`` flag causes Clang to build for a freestanding
-(rather than a hosted) environment. The ``__STDC_HOSTED__`` predefined macro
-will expand to ``0`` in a freestanding environment. In such an environment,
-execution of the program may happen without an operating system and so a
-startup function (e.g., ``main``) may not be automatically called, though file
-scope objects which need to run startup code (constructors in C++,
-``__attribute__((constructor))``, etc) are executed via implementation-defined
-means such as ``__cxx_global_var_init``.
+(rather than a hosted) environment. The flag has the following effects:
+
+* the ``__STDC_HOSTED__`` predefined macro will expand to ``0``,
+* builtin functions are disabled (``-fno-builtins``), and
+* unwind tables are disabled (``fno-asynchronous-unwind-tables
-fno-unwind-tables``)
A freestanding environment is not one which has no C standard library support.
A conforming freestanding C standard library implementation is required. Clang
@@ -1093,9 +1091,8 @@ Clause 4 (Conformance) of the C standard. Additionally,
Clang requires the
following runtime interfaces to be provided:
* `memcpy`,
- * `memmove`,
- * `memset`, and
- * `memcmp`.
+ * `memmove`, and
+ * `memset`.
Controlling Errors and Warnings
-------------------------------
>From 537dc66942fa55b971afc141882cf3a8808be602 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aa...@aaronballman.com>
Date: Fri, 21 Mar 2025 13:20:38 -0400
Subject: [PATCH 3/5] Added a few more updates
---
clang/docs/UsersManual.rst | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 30cfad1b1d68d..e68ac902acf92 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1079,8 +1079,10 @@ Passing the ``-ffreestanding`` flag causes Clang to
build for a freestanding
(rather than a hosted) environment. The flag has the following effects:
* the ``__STDC_HOSTED__`` predefined macro will expand to ``0``,
-* builtin functions are disabled (``-fno-builtins``), and
-* unwind tables are disabled (``fno-asynchronous-unwind-tables
-fno-unwind-tables``)
+* builtin functions are disabled (``-fno-builtins``),
+* unwind tables are disabled (``fno-asynchronous-unwind-tables
-fno-unwind-tables``),
+* allows ``main`` to be used as a regular function, and
+* removes implicit system header search paths and link libraries.
A freestanding environment is not one which has no C standard library support.
A conforming freestanding C standard library implementation is required. Clang
>From d5933473da23dcf9e57d54a05f35d62fe5276898 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aa...@aaronballman.com>
Date: Fri, 21 Mar 2025 13:21:35 -0400
Subject: [PATCH 4/5] Remove a mention about memcmp
---
clang/docs/CommandGuide/clang.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/docs/CommandGuide/clang.rst
b/clang/docs/CommandGuide/clang.rst
index dfe28fc5d2bcb..42aac7b25d93c 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -265,7 +265,7 @@ Language Selection and Mode Options
environment. Note that a freestanding build still requires linking against a C
Standard Library which supports the freestanding interfaces for the specified
language mode and target environment. This includes functions like `memcpy`,
- `memmove`, `memset` and `memcmp`.
+ `memmove`, and `memset`.
.. option:: -fno-builtin
>From 6576792c44d1de5df1a4c3de239cc6bb6c12ae3b Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aa...@aaronballman.com>
Date: Mon, 24 Mar 2025 07:48:03 -0400
Subject: [PATCH 5/5] Update based on review feedback
---
clang/docs/UsersManual.rst | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index e68ac902acf92..e67c854941ab4 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1080,9 +1080,8 @@ Passing the ``-ffreestanding`` flag causes Clang to build
for a freestanding
* the ``__STDC_HOSTED__`` predefined macro will expand to ``0``,
* builtin functions are disabled (``-fno-builtins``),
-* unwind tables are disabled (``fno-asynchronous-unwind-tables
-fno-unwind-tables``),
-* allows ``main`` to be used as a regular function, and
-* removes implicit system header search paths and link libraries.
+* unwind tables are disabled (``fno-asynchronous-unwind-tables
-fno-unwind-tables``), and
+* allows ``main`` to be used as a regular symbol.
A freestanding environment is not one which has no C standard library support.
A conforming freestanding C standard library implementation is required. Clang
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
