Skip to content

[Docs] Document freestanding requirements #132232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AaronBallman merged 8 commits into from
Mar 27, 2025
Merged

[Docs] Document freestanding requirements #132232

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5008e3c
[Docs] Document freestanding requirements
AaronBallman Mar 20, 2025
e6bcd39
Update based on review feedback
AaronBallman Mar 21, 2025
537dc66
Added a few more updates
AaronBallman Mar 21, 2025
d593347
Remove a mention about memcmp
AaronBallman Mar 21, 2025
6576792
Update based on review feedback
AaronBallman Mar 24, 2025
b88b4a0
Disabled -> diabled by default
AaronBallman Mar 25, 2025
74bbff4
Reword based on review feedback
AaronBallman Mar 26, 2025
bcd5db3
Slight rewording based on review feedback
AaronBallman Mar 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions clang/docs/CommandGuide/clang.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
21 changes: 21 additions & 0 deletions clang/docs/UsersManual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1073,6 +1073,27 @@ 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 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.
Copy link
Member

@jyknight jyknight Mar 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we distinguish standard conforming freestanding implementation vs what Clang expects of you when you use -ffreestanding? Or, do we intend to unify the two concepts?

Unification would imply (to me) that codegen in -ffreestanding is allowed to generate new calls to anything that the standards-conforming freestanding implementation is required to provide. And that we ought to treat calls to the freestanding-required functions as builtins for optimization purposes.

Also, I think we wouldn't need the callout for memcpy/memmove/memset, since all of those are in string.h which is already required of a freestanding implementation.

Copy link
Collaborator

@efriedma-quic efriedma-quic Mar 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the optimizations/warnings disabled by -fno-builtin turn out to be an issue, we can consider adding some additional flag which considers some functions builtin, or something like that. But we'll have to be careful how we expose it: people don't want to be on the treadmill of messing with their environment every time the C committee decides to expand the list of required functions for freestanding implementations.

I think it makes sense to specifically call out memcpy/memmove/memset because calls to them can show up even if you don't explicitly write them.

Copy link
Collaborator Author

@AaronBallman AaronBallman Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was aiming to let users know what Clang does & expects of you when -ffreestanding is passed. The primary thing is: freestanding does not mean "I don't need any C standard library", it means "I need a freestanding-compatible C standard library that includes a few functions that are expected to be available even in older language modes where they weren't in freestanding before."

Copy link
Member

@jyknight jyknight Mar 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I find the wording now a bit unclear because the new paragraph discusses standards conformance, in the middle of discussing Clang's expectations.

I think those two concepts need to clearly distinguished.

How about rewording something like:

An implementation of the following runtime library functions must always be provided with the usual semantics, as Clang will generate calls to them:

  • memcpy,
  • memmove, and
  • memset.

Clang does not, by itself, provide a full "conforming freestanding implementation". If you wish to have a conforming freestanding implementation, you must provide a freestanding C library. While Clang provides some of the required header files, it does not provide all of them, nor any library implementations.

Conversely, when -ffreestanding is specified, Clang does not require you to provide a conforming freestanding implementation library. Clang will not make any assumptions as to the availability or semantics of standard-library, functions other than those mentioned above.

Copy link
Contributor

@jhuber6 jhuber6 Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm guessing there's a full list of functions that we need to provide. Wonder how difficult it would be to just stash those in compiler-rt or something.

Copy link
Collaborator Author

@AaronBallman AaronBallman Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the wording along the lines of what @jyknight proposed.

Copy link
Collaborator Author

@AaronBallman AaronBallman Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I think that list will need to be expanded (in a future patch?). For example, we support _Complex in freestanding mode and that will emit a call to __divsc3 on complex division, that sort of thing.

Copy link
Member

@jyknight jyknight Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I summarized the functionality required from a conforming freestanding implementation in a previous comment on this PR.

I think we should also assume that future C standards may further increase the set of freestanding functions, towards inclusion of any function which doesn't require a runtime environment (e.g. memory allocator, system calls, or other global state).

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`, and
* `memset`.

Controlling Errors and Warnings
-------------------------------

Expand Down
5 changes: 0 additions & 5 deletions clang/www/c_status.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Comment on lines -537 to -541
Copy link
Contributor

@frederick-vs-ja frederick-vs-ja Mar 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although the PR description said:

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.

It seem to me that the status will become less clear due to removal of the entry.

Copy link
Collaborator Author

@AaronBallman AaronBallman Mar 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't typically document anything which the compiler isn't required to provide (for example, we don't really list other things from the C standard library). We could add an N/A status like we have for DRs, but I think that would start to drown out the relevant information due to talking about editorial changes as well as library changes.

WDYT?

Copy link
Contributor

@philnik777 philnik777 Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW we list all the LWG papers and issues in the libc++ docs, and IMO it's useful. That makes it clear whether we've considered the paper/issue and what our conclusion was. Since most papers by far require changes, it's also really not cluttering the list too much.

Copy link
Collaborator Author

@AaronBallman AaronBallman Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit different though -- libc++ lists library issues and papers, not Core issues and papers, because it's an implementation of the library. In this case, Clang doesn't provide any libc functionality, so we typically do not list any C Standard Library papers (just the core wording papers). But freestanding can either be "the compiler provides this" or "the library provides this". In this case, the library provides this, so I don't think it makes sense to list it as a feature the compiler needs to provide.

Copy link
Contributor

@frederick-vs-ja frederick-vs-ja Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found that c_status.html is currently listing some library-only changes (e.g. N2359 and possibly N2951). Perhaps a thorough cleanup (in a later PR) is desired?

Copy link
Collaborator Author

@AaronBallman AaronBallman Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

N2359 applies to the compiler because it introduces new potentially reserved identifiers we may want to diagnose and it changes behavior of limits.h which Clang provides.

N2951 applies to the compiler because it imposes some requirements on freestanding regarding FENV_ACCESS. It's questionable whether this one belongs on the list or not. It's marked as "Unknown" currently because I've not spent the time trying to figure out whether we have anything to do here or not.

But yes, cleaning these up in a later PR is a good idea. FWIW, I've been removing ones as I realize they don't impact the compiler.

Copy link
Contributor

@philnik777 philnik777 Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, yeah. I guess the call what is compiler and library is a bit less explicit in C, since there isn't a CWG/LWG distinction. I guess we also only list CWG papers that affect the library in some way and not all of them.

<tr>
<td>Digit separators</td>
<td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2626.pdf">N2626</a></td>
Expand Down
Loading