Rollup merge of #114006 - jonathanpallant:update-sparc-unknown-readme, r=Amanieu

Update sparc-unknown-none-elf platform README

Cherry picked a couple of commits that didn't quite make it in #113535

1 files changed, 42 insertions, 18 deletions

diff --git a/src/doc/rustc/src/platform-support/sparc-unknown-none-elf.md b/src/doc/rustc/src/platform-support/sparc-unknown-none-elf.md
index efd58e8302f..f579b1fb8d4 100644
--- a/src/doc/rustc/src/platform-support/sparc-unknown-none-elf.md
+++ b/src/doc/rustc/src/platform-support/sparc-unknown-none-elf.md
@@ -17,13 +17,6 @@ Rust for bare-metal 32-bit SPARC V7 and V8 systems, e.g. the Gaisler LEON3.
 This target is cross-compiled. There is no support for `std`. There is no
 default allocator, but it's possible to use `alloc` by supplying an allocator.
 
-This allows the generated code to run in environments, such as kernels, which
-may need to avoid the use of such registers or which may have special
-considerations about the use of such registers (e.g. saving and restoring them
-to avoid breaking userspace code using the same registers). You can change code
-generation to use additional CPU features via the `-C target-feature=` codegen
-options to rustc, or via the `#[target_feature]` mechanism within Rust code.
-
 By default, code generated with this target should run on any `SPARC` hardware;
 enabling additional target features may raise this baseline.
 
@@ -46,20 +39,31 @@ list in `config.toml`:
 ```toml
 [build]
 build-stage = 1
-target = ["sparc-unknown-none-elf"]
+host = ["<target for your host>"]
+target = ["<target for your host>", "sparc-unknown-none-elf"]
 ```
 
+Replace `<target for your host>` with `x86_64-unknown-linux-gnu` or whatever
+else is appropriate for your host machine.
+
 ## Building Rust programs
 
-```text
+To build with this target, pass it to the `--target` argument, like:
+
+```console
 cargo build --target sparc-unknown-none-elf
 ```
 
 This target uses GCC as a linker, and so you will need an appropriate GCC
-compatible `sparc-unknown-none` toolchain.
+compatible `sparc-unknown-none` toolchain. The default linker binary is
+`sparc-elf-gcc`, but you can override this in your project configuration, as
+follows:
 
-The default linker name is `sparc-elf-gcc`, but you can override this in your
-project configuration.
+`.cargo/config.toml`:
+```toml
+[target.sparc-unknown-none-elf]
+linker = "sparc-custom-elf-gcc"
+```
 
 ## Testing
 
@@ -84,21 +88,41 @@ runner = "tsim-leon3"
 [build]
 target = ["sparc-unknown-none-elf"]
 rustflags = "-Ctarget-cpu=leon3"
+```
+
+With this configuration, running `cargo run` will compile your code for the
+SPARC V8 compatible Gaisler Leon3 processor and then start the `tsim-leon3`
+simulator. The `libcore` was pre-compiled as part of the `rustc` compilation
+process using the SPARC V7 baseline, but if you are using a nightly toolchain
+you can use the
+[`-Z build-std=core`](https://doc.rust-lang.org/cargo/reference/unstable.html#build-std)
+option to rebuild `libcore` from source. This may be useful if you want to
+compile it for SPARC V8 and take advantage of the extra instructions.
+
+`.cargo/config.toml`:
+```toml
+[target.sparc-unknown-none-elf]
+linker = "sparc-gaisler-elf-gcc"
+runner = "tsim-leon3"
+
+[build]
+target = ["sparc-unknown-none-elf"]
+rustflags = "-Ctarget-cpu=leon3"
 
 [unstable]
 build-std = ["core"]
 ```
 
-With this configuration, running `cargo run` will compile your code for the
-SPARC V8 compatible Gaisler Leon3 processor and then start the `tsim-leon3`
-simulator. Once the simulator is running, simply enter the command
-`run` to start the code executing in the simulator.
+Either way, once the simulator is running, simply enter the command `run` to
+start the code executing in the simulator.
 
 The default C toolchain libraries are linked in, so with the Gaisler [BCC2]
 toolchain, and using its default Leon3 BSP, you can use call the C `putchar`
-function and friends to output to the simulator console.
+function and friends to output to the simulator console. The default linker
+script is also appropriate for the Leon3 simulator, so no linker script is
+required.
 
-Here's a complete example:
+Here's a complete example using the above config file:
 
 ```rust,ignore (cannot-test-this-because-it-assumes-special-libc-functions)
 #![no_std]