Skip to content

Commit 4bccf83

Browse files
jonathanpallantjonathanpallant
committed
Add platform support information.
1 parent d30294e commit 4bccf83

File tree

3 files changed

+166
-1
lines changed

3 files changed

+166
-1
lines changed

‎src/doc/rustc/src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
- [mipsel-sony-psx](platform-support/mipsel-sony-psx.md)
3939
- [nvptx64-nvidia-cuda](platform-support/nvptx64-nvidia-cuda.md)
4040
- [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md)
41+
- [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md)
4142
- [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)
4243
- [\*-nto-qnx-\*](platform-support/nto-qnx.md)
4344
- [\*-unknown-netbsd\*](platform-support/netbsd.md)

‎src/doc/rustc/src/platform-support.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ target | std | notes
176176
`thumbv8m.base-none-eabi` | * | Bare ARMv8-M Baseline
177177
`thumbv8m.main-none-eabi` | * | Bare ARMv8-M Mainline
178178
`thumbv8m.main-none-eabihf` | * | Bare ARMv8-M Mainline, hardfloat
179-
`sparc-unknown-none-elf` | * | Bare 32-bit SPARC V7+
179+
[`sparc-unknown-none-elf`](./platform-support/sparc-unknown-none-elf.md) | * | Bare 32-bit SPARC V7+
180180
`wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten
181181
`wasm32-unknown-unknown` | ✓ | WebAssembly
182182
`wasm32-wasi` | ✓ | WebAssembly with WASI

‎src/doc/rustc/src/platform-support/sparc-unknown-none-elf.md

+164
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# `sparc-unknown-none-elf`
2+
3+
**Tier: 3**
4+
5+
Rust for bare-metal 32-bit SPARC V7 and V8 systems, e.g. the Gaisler LEON3.
6+
7+
| Target | Descriptions |
8+
| ---------------------- | ----------------------------------------- |
9+
| sparc-unknown-none-elf | SPARC V7 32-bit (freestanding, hardfloat) |
10+
11+
## Target maintainers
12+
13+
- Jonathan Pallant, <[email protected]>, https://ferrous-systems.com
14+
15+
## Requirements
16+
17+
This target is cross-compiled. There is no support for `std`. There is no
18+
default allocator, but it's possible to use `alloc` by supplying an allocator.
19+
20+
This allows the generated code to run in environments, such as kernels, which
21+
may need to avoid the use of such registers or which may have special
22+
considerations about the use of such registers (e.g. saving and restoring them
23+
to avoid breaking userspace code using the same registers). You can change code
24+
generation to use additional CPU features via the `-C target-feature=` codegen
25+
options to rustc, or via the `#[target_feature]` mechanism within Rust code.
26+
27+
By default, code generated with this target should run on any `SPARC` hardware;
28+
enabling additional target features may raise this baseline.
29+
30+
- `-Ctarget-cpu=v8` adds the extra SPARC V8 instructions.
31+
32+
- `-Ctarget-cpu=leon3` adds the SPARC V8 instructions and sets up scheduling to
33+
suit the Gaisler Leon3.
34+
35+
Functions marked `extern "C"` use the [standard SPARC architecture calling
36+
convention](https://sparc.org/technical-documents/).
37+
38+
This target generates ELF binaries. Any alternate formats or special
39+
considerations for binary layout will require linker options or linker scripts.
40+
41+
## Building the target
42+
43+
You can build Rust with support for the target by adding it to the `target`
44+
list in `config.toml`:
45+
46+
```toml
47+
[build]
48+
build-stage = 1
49+
target = ["sparc-unknown-none-elf"]
50+
```
51+
52+
## Building Rust programs
53+
54+
```text
55+
cargo build --target sparc-unknown-none-elf
56+
```
57+
58+
This target uses GCC as a linker, and so you will need an appropriate GCC
59+
compatible `sparc-unknown-none` toolchain.
60+
61+
The default linker name is `sparc-elf-gcc`, but you can override this in your
62+
project configuration.
63+
64+
## Testing
65+
66+
As `sparc-unknown-none-elf` supports a variety of different environments and does
67+
not support `std`, this target does not support running the Rust test suite.
68+
69+
## Cross-compilation toolchains and C code
70+
71+
This target was initially tested using [BCC2] from Gaisler, along with the TSIM
72+
Leon3 processor simulator. Both [BCC2] GCC and [BCC2] Clang have been shown to
73+
work. To work with these tools, your project configuration should contain
74+
something like:
75+
76+
[BCC2]: https://www.gaisler.com/index.php/downloads/compilers
77+
78+
`.cargo/config.toml`:
79+
```toml
80+
[target.sparc-unknown-none-elf]
81+
linker = "sparc-gaisler-elf-gcc"
82+
runner = "tsim-leon3"
83+
84+
[build]
85+
target = ["sparc-unknown-none-elf"]
86+
rustflags = "-Ctarget-cpu=leon3"
87+
88+
[unstable]
89+
build-std = ["core"]
90+
```
91+
92+
With this configuration, running `cargo run` will compile your code for the
93+
SPARC V8 compatible Gaisler Leon3 processor and then start the `tsim-leon3`
94+
simulator. Once the simulator is running, simply enter the command
95+
`run` to start the code executing in the simulator.
96+
97+
The default C toolchain libraries are linked in, so with the Gaisler [BCC2]
98+
toolchain, and using its default Leon3 BSP, you can use call the C `putchar`
99+
function and friends to output to the simulator console.
100+
101+
Here's a complete example:
102+
103+
```rust,ignore (cannot-test-this-because-it-assumes-special-libc-functions)
104+
#![no_std]
105+
#![no_main]
106+
107+
extern "C" {
108+
fn putchar(ch: i32);
109+
fn _exit(code: i32) -> !;
110+
}
111+
112+
#[no_mangle]
113+
extern "C" fn main() -> i32 {
114+
let message = "Hello, this is Rust!";
115+
for b in message.bytes() {
116+
unsafe {
117+
putchar(b as i32);
118+
}
119+
}
120+
0
121+
}
122+
123+
#[panic_handler]
124+
fn panic(_panic: &core::panic::PanicInfo) -> ! {
125+
unsafe {
126+
_exit(1);
127+
}
128+
}
129+
```
130+
131+
```console
132+
$ cargo run --target=sparc-unknown-none-elf
133+
Compiling sparc-demo-rust v0.1.0 (/work/sparc-demo-rust)
134+
Finished dev [unoptimized + debuginfo] target(s) in 3.44s
135+
Running `tsim-leon3 target/sparc-unknown-none-elf/debug/sparc-demo-rust`
136+
137+
TSIM3 LEON3 SPARC simulator, version 3.1.9 (evaluation version)
138+
139+
Copyright (C) 2023, Frontgrade Gaisler - all rights reserved.
140+
This software may only be used with a valid license.
141+
For latest updates, go to https://www.gaisler.com/
142+
Comments or bug-reports to [email protected]
143+
144+
This TSIM evaluation version will expire 2023-11-28
145+
146+
Number of CPUs: 2
147+
system frequency: 50.000 MHz
148+
icache: 1 * 4 KiB, 16 bytes/line (4 KiB total)
149+
dcache: 1 * 4 KiB, 16 bytes/line (4 KiB total)
150+
Allocated 8192 KiB SRAM memory, in 1 bank at 0x40000000
151+
Allocated 32 MiB SDRAM memory, in 1 bank at 0x60000000
152+
Allocated 8192 KiB ROM memory at 0x00000000
153+
section: .text, addr: 0x40000000, size: 20528 bytes
154+
section: .rodata, addr: 0x40005030, size: 128 bytes
155+
section: .data, addr: 0x400050b0, size: 1176 bytes
156+
read 347 symbols
157+
158+
tsim> run
159+
Initializing and starting from 0x40000000
160+
Hello, this is Rust!
161+
162+
Program exited normally on CPU 0.
163+
tsim>
164+
```

0 commit comments

Comments
 (0)