Auto merge of rust-lang#97571 - ehuss:symbol-mangling, r=michaelwoeri…

…ster

Add documentation on v0 symbol mangling.

This adds official documentation for the v0 symbol mangling format, migrating the documentation from [RFC 2603](https://rust-lang.github.io/rfcs/2603-rust-symbol-name-mangling-v0.html).
The format was originally stabilized as the `-C symbol-mangling-version` option, but the specifics were not stabilized (per rust-lang#90128 (comment)).
Per the discussion at rust-lang#93661 (comment) this adds those specifics as an official description of the format.

cc rust-lang#89917

src/doc/rustc/book.toml

@@ -6,3 +6,6 @@ title = "The rustc book"
 [output.html]
 git-repository-url = "https://github.com/rust-lang/rust/tree/master/src/doc/rustc"
 edit-url-template = "https://github.com/rust-lang/rust/edit/master/src/doc/rustc/{path}"
+
+[output.html.playground]
+runnable = false

src/doc/rustc/src/SUMMARY.md

@@ -59,4 +59,6 @@
 - [Instrumentation-based Code Coverage](instrument-coverage.md)
 - [Linker-plugin-based LTO](linker-plugin-lto.md)
 - [Exploit Mitigations](exploit-mitigations.md)
+- [Symbol Mangling](symbol-mangling/index.md)
+ - [v0 Symbol Format](symbol-mangling/v0.md)
 - [Contributing to `rustc`](contributing.md)

src/doc/rustc/src/codegen-options/index.md

@@ -569,13 +569,15 @@ for the purpose of generating object code and linking.
 
 Supported values for this option are:
 
-* `v0` — The "v0" mangling scheme. The specific format is not specified at
- this time.
+* `v0` — The "v0" mangling scheme.
 
 The default, if not specified, will use a compiler-chosen default which may
 change in the future.
 
+See the [Symbol Mangling] chapter for details on symbol mangling and the mangling format.
+
 [name mangling]: https://en.wikipedia.org/wiki/Name_mangling
+[Symbol Mangling]: ../symbol-mangling/index.md
 
 ## target-cpu
 

src/doc/rustc/src/symbol-mangling/index.md

@@ -0,0 +1,52 @@
+# Symbol Mangling
+
+[Symbol name mangling] is used by `rustc` to encode a unique name for symbols that are used during code generation.
+The encoded names are used by the linker to associate the name with the thing it refers to.
+
+The method for mangling the names can be controlled with the [`-C symbol-mangling-version`] option.
+
+[Symbol name mangling]: https://en.wikipedia.org/wiki/Name_mangling
+[`-C symbol-mangling-version`]: ../codegen-options/index.md#symbol-mangling-version
+
+## Per-item control
+
+The [`#[no_mangle]` attribute][reference-no_mangle] can be used on items to disable name mangling on that item.
+
+The [`#[export_name]`attribute][reference-export_name] can be used to specify the exact name that will be used for a function or static.
+
+Items listed in an [`extern` block][reference-extern-block] use the identifier of the item without mangling to refer to the item.
+The [`#[link_name]` attribute][reference-link_name] can be used to change that name.
+
+<!--
+FIXME: This is incomplete for wasm, per https://github.com/rust-lang/rust/blob/d4c364347ce65cf083d4419195b8232440928d4d/compiler/rustc_symbol_mangling/src/lib.rs#L191-L210
+-->
+
+[reference-no_mangle]: ../../reference/abi.html#the-no_mangle-attribute
+[reference-export_name]: ../../reference/abi.html#the-export_name-attribute
+[reference-link_name]: ../../reference/items/external-blocks.html#the-link_name-attribute
+[reference-extern-block]: ../../reference/items/external-blocks.html
+
+## Decoding
+
+The encoded names may need to be decoded in some situations.
+For example, debuggers and other tooling may need to demangle the name so that it is more readable to the user.
+Recent versions of `gdb` and `lldb` have built-in support for demangling Rust identifiers.
+In situations where you need to do your own demangling, the [`rustc-demangle`] crate can be used to programmatically demangle names.
+[`rustfilt`] is a CLI tool which can demangle names.
+
+An example of running rustfilt:
+
+```text
+$ rustfilt _RNvCskwGfYPst2Cb_3foo16example_function
+foo::example_function
+```
+
+[`rustc-demangle`]: https://crates.io/crates/rustc-demangle
+[`rustfilt`]: https://crates.io/crates/rustfilt
+
+## Mangling versions
+
+`rustc` supports different mangling versions which encode the names in different ways.
+The legacy version (which is currently the default) is not described here.
+The "v0" mangling scheme addresses several limitations of the legacy format,
+and is described in the [v0 Symbol Format](v0.md) chapter.