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

Changes from 1 commit
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
17 changes: 7 additions & 10 deletions clang/docs/UsersManual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
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
Expand All @@ -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
-------------------------------
Expand Down
Loading