[clang] [Docs] Document freestanding requirements (PR #132232)

[James Y Knight via cfe-commits]

================
@@ -1073,6 +1073,28 @@ 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``),
+* 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.
----------------
jyknight wrote:

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.
```

https://github.com/llvm/llvm-project/pull/132232