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
This commit is contained in:
Matthias Krüger 2023-07-24 17:47:11 +02:00 committed by GitHub
commit 4ee3266da6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -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
@ -81,6 +85,26 @@ something like:
linker = "sparc-gaisler-elf-gcc"
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"
@ -89,16 +113,16 @@ rustflags = "-Ctarget-cpu=leon3"
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]