Categorize and explain target features support

[mattico]

There are 3 different uses of the -C target-feature args passed to rustc:

1. All of the features are passed to LLVM, which uses them to configure code-generation. This is sort-of stabilized since 1.0 though LLVM does change/add/remove target features regularly.
2. Target features which are in the compiler's allowlist can be used in cfg!(target_feature) etc. These may have different names than in LLVM and are renamed before passing them to LLVM.
3. Target features which are in the allowlist and which are stabilized or feature-gate-enabled can be used in #[target_feature].

It can be confusing that rustc --print target-features just prints out the LLVM features without separating out the rustc features or even mentioning that the dichotomy exists.

This improves the situation by separating out the rustc and LLVM target features and adding a brief explanation about the difference.

Abbreviated Example Output:

$ rustc --print target-features
Features supported by rustc for this target:
    adx                         - Support ADX instructions.
    aes                         - Enable AES instructions.
...
    xsaves                      - Support xsaves instructions.
    crt-static                  - Enables libraries with C Run-time Libraries(CRT) to be statically linked.

Code-generation features supported by LLVM for this target:
    16bit-mode                  - 16-bit mode (i8086).
    32bit-mode                  - 32-bit mode (80386).
...
    x87                         - Enable X87 float instructions.
    xop                         - Enable XOP instructions.

Use +feature to enable a feature, or -feature to disable it.
For example, rustc -C target-cpu=mycpu -C target-feature=+feature1,-feature2

Code-generation features cannot be used in cfg or #[target_feature],
and may be renamed or removed in a future version of LLVM or rustc.

Motivated by #83975.
CC #49653

[rust-highfive]

r? @petrochenkov

(rust-highfive has picked a reviewer for you, use r? to override)

[petrochenkov]

or even mentioning that the dichotomy exists

It's quite possible that such "dichotomy" is an unintentional result of different features being implemented at different time by different people not having a vision of the larger picture, then it's not surprising that's not documented.

[petrochenkov]

The main thing here is to avoid documenting more guarantees than it was previously documented.
The wording looks ok in this sense (and is otherwise an improvement).

[petrochenkov]

r=me with commits squashed.

[petrochenkov]

@bors r+

[bors]

📌 Commit e258a5b has been approved by petrochenkov

[bors]

⌛ Testing commit e258a5b with merge dae9d6a...

[bors]

☀️ Test successful - checks-actions
Approved by: petrochenkov
Pushing dae9d6a to master...