Skip to content

Commit e31ebae

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #113535 - jonathanpallant:sparc-bare-metal, r=jackh726
Add a sparc-unknown-none-elf target. # `sparc-unknown-none-elf` **Tier: 3** Rust for bare-metal 32-bit SPARC V7 and V8 systems, e.g. the Gaisler LEON3. ## Target maintainers - Jonathan Pallant, `[email protected]`, https://ferrous-systems.com ## Requirements > Does the target support host tools, or only cross-compilation? Only cross-compilation. > Does the target support std, or alloc (either with a default allocator, or if the user supplies an allocator)? Only tested with `libcore` but I see no reason why you couldn't also support `liballoc`. > Document the expectations of binaries built for the target. Do they assume specific minimum features beyond the baseline of the CPU/environment/etc? What version of the OS or environment do they expect? Tested by linking with a standard SPARC bare-metal toolchain - specifically I used the [BCC2] toolchain from Gaisler (both GCC and clang variants, both pre-compiled for x64 Linux and compiling my own SPARC GCC from source to run on `aarch64-apple-darwin`). The target is set to use the lowest-common-denominator `SPARC V7` architecture (yes, they started at V7 - see [Wikipedia](https://en.wikipedia.org/wiki/SPARC#History)). [BCC2]: https://www.gaisler.com/index.php/downloads/compilers > Are there notable `#[target_feature(...)]` or `-C target-feature=` values that programs may wish to use? `-Ctarget-cpu=v8` adds the instructions added in V8. `-Ctarget-cpu=leon3` adds the V8 instructions and sets up scheduling to suit the Gaisler LEON3. > What calling convention does `extern "C"` use on the target? I believe this is defined by the SPARC architecture reference manuals and V7, V8 and V9 are all compatible. > What format do binaries use by default? ELF, PE, something else? ELF ## Building the target > If Rust doesn't build the target by default, how can users build it? Can users just add it to the `target` list in `config.toml`? Yes. I did: ```toml target = ["aarch64-apple-darwin", "sparc-unknown-none-elf"] ``` ## Building Rust programs > Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of `core` by using `build-std` or similar. Correct. ## Testing > Does the target support running binaries, or do binaries have varying expectations that prevent having a standard way to run them? No - it's a bare metal platform. > If users can run binaries, can they do so in some common emulator, or do they need native hardware? But if you use [BCC2] as the linker, you get default memory map suitable for the LEON3, and a default BSP for the LEON3, and so you can run the binaries in the `tsim-leon3` simulator from Gaisler. ```console $ cat .cargo/config.toml | grep runner runner = "tsim-leon3 -c sim-commands.txt" $ cat sim-commands.txt run quit $ cargo +sparcrust run --targe=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 -c sim-commands.txt 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 [email protected] 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: 104400 bytes section: .rodata, addr: 0x400197d0, size: 15616 bytes section: .data, addr: 0x4001d4d0, size: 1176 bytes read 1006 symbols Initializing and starting from 0x40000000 Hello, this is Rust! PANIC: PanicInfo { payload: Any { .. }, message: Some(I am a panic), location: Location { file: "src/main.rs", line: 33, col: 5 }, can_unwind: true } Program exited normally on CPU 0. ``` > Does the target support running the Rust testsuite? I don't think so, the testsuite requires `libstd` IIRC. ## Cross-compilation toolchains and C code > Does the target support C code? Yes. > If so, what toolchain target should users use to build compatible C code? (This may match the target triple, or it may be a toolchain for a different target triple, potentially with specific options or caveats.) I suggest [BCC2] from Gaisler. It comes in both GCC and Clang variants.
2 parents cfeeab5 + 4bccf83 commit e31ebae

File tree

6 files changed

+196
-0
lines changed

6 files changed

+196
-0
lines changed

‎compiler/rustc_target/src/spec/mod.rs

+2
Original file line numberDiff line numberDiff line change
@@ -1433,6 +1433,8 @@ supported_targets! {
14331433
("riscv64gc-unknown-linux-gnu", riscv64gc_unknown_linux_gnu),
14341434
("riscv64gc-unknown-linux-musl", riscv64gc_unknown_linux_musl),
14351435

1436+
("sparc-unknown-none-elf", sparc_unknown_none_elf),
1437+
14361438
("loongarch64-unknown-none", loongarch64_unknown_none),
14371439
("loongarch64-unknown-none-softfloat", loongarch64_unknown_none_softfloat),
14381440

‎compiler/rustc_target/src/spec/sparc_unknown_none_elf.rs

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
use crate::abi::Endian;
2+
use crate::spec::{Cc, LinkerFlavor, Lld, PanicStrategy, RelocModel, Target, TargetOptions};
3+
4+
pub fn target() -> Target {
5+
let options = TargetOptions {
6+
linker_flavor: LinkerFlavor::Gnu(Cc::Yes, Lld::No),
7+
linker: Some("sparc-elf-gcc".into()),
8+
endian: Endian::Big,
9+
cpu: "v7".into(),
10+
abi: "elf".into(),
11+
max_atomic_width: Some(32),
12+
atomic_cas: true,
13+
panic_strategy: PanicStrategy::Abort,
14+
relocation_model: RelocModel::Static,
15+
no_default_libraries: false,
16+
emit_debug_gdb_scripts: false,
17+
eh_frame_header: false,
18+
..Default::default()
19+
};
20+
Target {
21+
data_layout: "E-m:e-p:32:32-i64:64-f128:64-n32-S64".into(),
22+
llvm_target: "sparc-unknown-none-elf".into(),
23+
pointer_width: 32,
24+
arch: "sparc".into(),
25+
options,
26+
}
27+
}

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

+1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
- [mipsisa\*r6\*-unknown-linux-gnu\*](platform-support/mips-release-6.md)
4040
- [nvptx64-nvidia-cuda](platform-support/nvptx64-nvidia-cuda.md)
4141
- [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md)
42+
- [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md)
4243
- [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)
4344
- [\*-nto-qnx-\*](platform-support/nto-qnx.md)
4445
- [\*-unknown-netbsd\*](platform-support/netbsd.md)

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

+1
Original file line numberDiff line numberDiff line change
@@ -176,6 +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`](./platform-support/sparc-unknown-none-elf.md) | * | Bare 32-bit SPARC V7+
179180
`wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten
180181
`wasm32-unknown-unknown` | ✓ | WebAssembly
181182
`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+
```

‎src/tools/build-manifest/src/main.rs

+1
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@ static TARGETS: &[&str] = &[
127127
"s390x-unknown-linux-gnu",
128128
"sparc64-unknown-linux-gnu",
129129
"sparcv9-sun-solaris",
130+
"sparc-unknown-none-elf",
130131
"thumbv6m-none-eabi",
131132
"thumbv7em-none-eabi",
132133
"thumbv7em-none-eabihf",

0 commit comments

Comments
 (0)