Add platform support information.

3 files changed, 166 insertions, 1 deletions

diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index f8af26326a7..4d4dc3f4996 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -38,6 +38,7 @@
     - [mipsel-sony-psx](platform-support/mipsel-sony-psx.md)
     - [nvptx64-nvidia-cuda](platform-support/nvptx64-nvidia-cuda.md)
     - [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md)
+    - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md)
     - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)
     - [\*-nto-qnx-\*](platform-support/nto-qnx.md)
     - [\*-unknown-netbsd\*](platform-support/netbsd.md)
diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index d287cf7a5fe..14fe7242ab9 100644
--- a/src/doc/rustc/src/platform-support.md
+++ b/src/doc/rustc/src/platform-support.md
@@ -176,7 +176,7 @@ target | std | notes
 `thumbv8m.base-none-eabi` | * | Bare ARMv8-M Baseline
 `thumbv8m.main-none-eabi` | * | Bare ARMv8-M Mainline
 `thumbv8m.main-none-eabihf` | * | Bare ARMv8-M Mainline, hardfloat
-`sparc-unknown-none-elf` | * | Bare 32-bit SPARC V7+
+[`sparc-unknown-none-elf`](./platform-support/sparc-unknown-none-elf.md) | * | Bare 32-bit SPARC V7+
 `wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten
 `wasm32-unknown-unknown` | ✓ | WebAssembly
 `wasm32-wasi` | ✓ | WebAssembly with WASI
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
new file mode 100644
index 00000000000..efd58e8302f
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/sparc-unknown-none-elf.md
@@ -0,0 +1,164 @@
+# `sparc-unknown-none-elf`
+
+**Tier: 3**
+
+Rust for bare-metal 32-bit SPARC V7 and V8 systems, e.g. the Gaisler LEON3.
+
+| Target                 | Descriptions                              |
+| ---------------------- | ----------------------------------------- |
+| sparc-unknown-none-elf | SPARC V7 32-bit (freestanding, hardfloat) |
+
+## Target maintainers
+
+- Jonathan Pallant, <jonathan.pallant@ferrous-systems.com>, https://ferrous-systems.com
+
+## Requirements
+
+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.
+
+- `-Ctarget-cpu=v8` adds the extra SPARC V8 instructions.
+
+- `-Ctarget-cpu=leon3` adds the SPARC V8 instructions and sets up scheduling to
+  suit the Gaisler Leon3.
+
+Functions marked `extern "C"` use the [standard SPARC architecture calling
+convention](https://sparc.org/technical-documents/).
+
+This target generates ELF binaries. Any alternate formats or special
+considerations for binary layout will require linker options or linker scripts.
+
+## Building the target
+
+You can build Rust with support for the target by adding it to the `target`
+list in `config.toml`:
+
+```toml
+[build]
+build-stage = 1
+target = ["sparc-unknown-none-elf"]
+```
+
+## Building Rust programs
+
+```text
+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.
+
+The default linker name is `sparc-elf-gcc`, but you can override this in your
+project configuration.
+
+## Testing
+
+As `sparc-unknown-none-elf` supports a variety of different environments and does
+not support `std`, this target does not support running the Rust test suite.
+
+## Cross-compilation toolchains and C code
+
+This target was initially tested using [BCC2] from Gaisler, along with the TSIM
+Leon3 processor simulator. Both [BCC2] GCC and [BCC2] Clang have been shown to
+work. To work with these tools, your project configuration should contain
+something like:
+
+[BCC2]: https://www.gaisler.com/index.php/downloads/compilers
+
+`.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.
+
+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.
+
+Here's a complete example:
+
+```rust,ignore (cannot-test-this-because-it-assumes-special-libc-functions)
+#![no_std]
+#![no_main]
+
+extern "C" {
+    fn putchar(ch: i32);
+    fn _exit(code: i32) -> !;
+}
+
+#[no_mangle]
+extern "C" fn main() -> i32 {
+    let message = "Hello, this is Rust!";
+    for b in message.bytes() {
+        unsafe {
+            putchar(b as i32);
+        }
+    }
+    0
+}
+
+#[panic_handler]
+fn panic(_panic: &core::panic::PanicInfo) -> ! {
+    unsafe {
+        _exit(1);
+    }
+}
+```
+
+```console
+$ cargo run --target=sparc-unknown-none-elf
+   Compiling sparc-demo-rust v0.1.0 (/work/sparc-demo-rust)
+    Finished dev [unoptimized + debuginfo] target(s) in 3.44s
+     Running `tsim-leon3 target/sparc-unknown-none-elf/debug/sparc-demo-rust`
+
+ TSIM3 LEON3 SPARC simulator, version 3.1.9 (evaluation version)
+
+ Copyright (C) 2023, Frontgrade Gaisler - all rights reserved.
+ This software may only be used with a valid license.
+ For latest updates, go to https://www.gaisler.com/
+ Comments or bug-reports to support@gaisler.com
+
+ This TSIM evaluation version will expire 2023-11-28
+
+Number of CPUs: 2
+system frequency: 50.000 MHz
+icache: 1 * 4 KiB, 16 bytes/line (4 KiB total)
+dcache: 1 * 4 KiB, 16 bytes/line (4 KiB total)
+Allocated 8192 KiB SRAM memory, in 1 bank at 0x40000000
+Allocated 32 MiB SDRAM memory, in 1 bank at 0x60000000
+Allocated 8192 KiB ROM memory at 0x00000000
+section: .text, addr: 0x40000000, size: 20528 bytes
+section: .rodata, addr: 0x40005030, size: 128 bytes
+section: .data, addr: 0x400050b0, size: 1176 bytes
+read 347 symbols
+
+tsim> run
+  Initializing and starting from 0x40000000
+Hello, this is Rust!
+
+  Program exited normally on CPU 0.
+tsim>
+```