From 229c16a0dc661a47df03315c6aeed373a9705bb8 Mon Sep 17 00:00:00 2001 From: Ian Chamberlain Date: Wed, 16 Mar 2022 23:26:22 -0400 Subject: [PATCH 1/4] Add platform-support page for armv6k-nintendo-3ds --- .../platform-support/armv6k-nintendo-3ds.md | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md diff --git a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md new file mode 100644 index 0000000000000..568b3c7d7e159 --- /dev/null +++ b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md @@ -0,0 +1,104 @@ +# `armv6k-nintendo-3ds` + +**Tier: 3** + +The Nintendo 3DS platform, which has an ARMv6K processor, and its associated +operating system (`horizon`). + +## Target maintainers + +- [@Meziu](https://github.com/Meziu) +- [@AzureMarker](https://github.com/AzureMarker) +- [@ian-h-chamberlain](https://github.com/ian-h-chamberlain) + +## Requirements + +This target is cross-compiled. `#![no_std]` crates should work without much +additional effort. + +`std` is partially supported, but mostly works. Some APIs are unimplemented +and will simply return an error, such as `std::process`. An allocator is provided +by default. + +In order to support `std` APIs, binaries must be linked against the open-source +[devkitARM toolchain](https://devkitpro.org/wiki/Getting_Started), notably +using its `arm-none-eabi-gcc` as the linker. + +Additionally, some helper crates provide implementations of some `libc` functions +use by `std`. These, or an alternate implementation of the relevant functions, +are required to use `std`: + +- [`pthread-3ds`](https://github.com/Meziu/pthread-3ds) provides pthread APIs for `std::thread`. +- [`linker-fix-3ds`](https://github.com/Meziu/rust-linker-fix-3ds) fulfills some other missing libc APIs. + +Binaries built for this target should be compatible with most variants of the +3DS (and 2DS) hardware and firmware, but testing is limited and some versions may +not work correctly. + +This target generates binaries in the ELF format. + +## Building the target + +You can build Rust with support for the target by adding it to the `target` +list in `config.toml` and providing paths to the devkitARM toolchain, e.g.: + +```toml +[build] +build-stage = 1 +target = ["armv6k-nintendo-3ds"] + +[target.armv6k-nintendo-3ds] +cc = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc" +cxx = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-g++" +ar = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-ar" +ranlib = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-ranlib" +linker = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc" +``` + +## Building Rust programs + +Rust does not yet ship pre-compiled artifacts for this target. + +The recommended way to build binaries is by using the +[cargo-3ds](https://github.com/Meziu/cargo-3ds) tool, which uses `build-std` +and provides commands that work like the usual `cargo run`, `cargo build`, etc. + +You can also build Rust with the target enabled (see "Building the target" above). + +As mentioned in in "Requirements", programs that use `std` must link against +both the devkitARM toolchain and libraries providing the `libc` APIs used in `std`. +There is a general-purpose utility crate for working with nonstandard +APIs provided by the OS: [`ctru-rs`](https://github.com/Meziu/ctru-rs). +Add it to Cargo.toml to use it in your program: + +```toml +[dependencies] +ctru-rs = { git = "https://github.com/Meziu/ctru-rs.git" } +``` + +Using this library's `init()` function ensures the symbols needed to link +against `std` are present (as mentioned in "Requirements" above), as well as +providing a runtime suitable for `std`: + +```rust +fn main() { + ctru::init(); +} +``` + +## Testing + +Binaries built for this target can be run in an emulator (most commonly +[Citra](https://citra-emu.org/)), or sent to a device through +the use of a tool like devkitARM's `3dslink`. + +The `cargo-3ds` tool mentioned in "Building Rust programs" supports the use of +`3dslink` with `cargo 3ds run`. The default Rust test runner is not supported, but +[custom test frameworks](https://doc.rust-lang.org/beta/unstable-book/language-features/custom-test-frameworks.html) +can be used with `cargo 3ds test` to run unit tests on a device. + +The Rust `library/std` test suite is not yet supported. + +## Cross-compilation toolchains and C code + +C code can be built for this target using the aforementioned devkitARM toolchain. From 4f8820034ca21def04cfabfca1dfd97fabf28f25 Mon Sep 17 00:00:00 2001 From: Ian Chamberlain Date: Fri, 18 Mar 2022 00:03:09 -0400 Subject: [PATCH 2/4] Address comments for platform support doc --- .../platform-support/armv6k-nintendo-3ds.md | 55 ++++++++++++------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md index 568b3c7d7e159..5ce4076dd8534 100644 --- a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md +++ b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md @@ -5,6 +5,9 @@ The Nintendo 3DS platform, which has an ARMv6K processor, and its associated operating system (`horizon`). +Rust support for this target is not affiliated with Nintendo, and is not derived +from nor used with any official Nintendo SDK. + ## Target maintainers - [@Meziu](https://github.com/Meziu) @@ -13,25 +16,29 @@ operating system (`horizon`). ## Requirements -This target is cross-compiled. `#![no_std]` crates should work without much -additional effort. +This target is cross-compiled. Dynamic linking is not supported. + +`#![no_std]` crates can be built using `build-std` to build `core` and optionally +`alloc`, and either `panic_abort` or `panic_unwind`. `std` is partially supported, but mostly works. Some APIs are unimplemented and will simply return an error, such as `std::process`. An allocator is provided by default. -In order to support `std` APIs, binaries must be linked against the open-source -[devkitARM toolchain](https://devkitpro.org/wiki/Getting_Started), notably -using its `arm-none-eabi-gcc` as the linker. +In order to support some APIs, binaries must be linked against `libc` written +for the target, using a linker for the target. These are provided by the +devkitARM toolchain. See +[Cross-compilation toolchains and C code](#cross-compilation-toolchains-and-c-code) +for more details. Additionally, some helper crates provide implementations of some `libc` functions -use by `std`. These, or an alternate implementation of the relevant functions, -are required to use `std`: +use by `std` that may otherwise be missing. These, or an alternate implementation +of the relevant functions, are required to use `std`: - [`pthread-3ds`](https://github.com/Meziu/pthread-3ds) provides pthread APIs for `std::thread`. - [`linker-fix-3ds`](https://github.com/Meziu/rust-linker-fix-3ds) fulfills some other missing libc APIs. -Binaries built for this target should be compatible with most variants of the +Binaries built for this target should be compatible with all variants of the 3DS (and 2DS) hardware and firmware, but testing is limited and some versions may not work correctly. @@ -63,11 +70,12 @@ The recommended way to build binaries is by using the [cargo-3ds](https://github.com/Meziu/cargo-3ds) tool, which uses `build-std` and provides commands that work like the usual `cargo run`, `cargo build`, etc. -You can also build Rust with the target enabled (see "Building the target" above). +You can also build Rust with the target enabled (see +[Building the target](#building-the-target) above). -As mentioned in in "Requirements", programs that use `std` must link against -both the devkitARM toolchain and libraries providing the `libc` APIs used in `std`. -There is a general-purpose utility crate for working with nonstandard +As mentioned in [Requirements](#requirements), programs that use `std` must link +against both the devkitARM toolchain and libraries providing the `libc` APIs used +in `std`. There is a general-purpose utility crate for working with nonstandard APIs provided by the OS: [`ctru-rs`](https://github.com/Meziu/ctru-rs). Add it to Cargo.toml to use it in your program: @@ -77,8 +85,8 @@ ctru-rs = { git = "https://github.com/Meziu/ctru-rs.git" } ``` Using this library's `init()` function ensures the symbols needed to link -against `std` are present (as mentioned in "Requirements" above), as well as -providing a runtime suitable for `std`: +against `std` are present (as mentioned in [Requirements](#requirements) +above), as well as providing a runtime suitable for `std`: ```rust fn main() { @@ -90,15 +98,24 @@ fn main() { Binaries built for this target can be run in an emulator (most commonly [Citra](https://citra-emu.org/)), or sent to a device through -the use of a tool like devkitARM's `3dslink`. +the use of a tool like devkitARM's `3dslink`. They may also simply be copied +to an SD card to be inserted in the device. -The `cargo-3ds` tool mentioned in "Building Rust programs" supports the use of -`3dslink` with `cargo 3ds run`. The default Rust test runner is not supported, but +The `cargo-3ds` tool mentioned in [Building Rust programs](#building-rust-programs) +supports the use of `3dslink` with `cargo 3ds run`. The default Rust test runner +is not supported, but [custom test frameworks](https://doc.rust-lang.org/beta/unstable-book/language-features/custom-test-frameworks.html) can be used with `cargo 3ds test` to run unit tests on a device. -The Rust `library/std` test suite is not yet supported. +The Rust test suite for `library/std` is not yet supported. ## Cross-compilation toolchains and C code -C code can be built for this target using the aforementioned devkitARM toolchain. +C code can be built for this target using the +[devkitARM toolchain](https://devkitpro.org/wiki/Getting_Started). +This toolchain provides `arm-none-eabi-gcc` as the linker used to link Rust +programs as well. + +The toolchain also provides a `libc` implementation, which is required by `std` +for many of its APIs, and a helper library `libctru` which is used by several +of the helper crates listed in [Requirements](#requirements). From 2d4f1cdfe7a5abb176576d676d1de09dc7cf6a09 Mon Sep 17 00:00:00 2001 From: Ian Chamberlain Date: Wed, 23 Mar 2022 20:42:13 -0400 Subject: [PATCH 3/4] Include note about CFLAGS for building the target --- .../rustc/src/platform-support/armv6k-nintendo-3ds.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md index 5ce4076dd8534..60c122da403a7 100644 --- a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md +++ b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md @@ -47,7 +47,7 @@ This target generates binaries in the ELF format. ## Building the target You can build Rust with support for the target by adding it to the `target` -list in `config.toml` and providing paths to the devkitARM toolchain, e.g.: +list in `config.toml` and providing paths to the devkitARM toolchain. ```toml [build] @@ -62,6 +62,13 @@ ranlib = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-ranlib" linker = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc" ``` +Also, to build `compiler_builtins` for the target, export these flags before +building the Rust toolchain: + +```sh +export CFLAGS_armv6k_nintendo_3ds="-mfloat-abi=hard -mtune=mpcore -mtp=soft -march=armv6k" +``` + ## Building Rust programs Rust does not yet ship pre-compiled artifacts for this target. From 749f93505a598294a1156b27bd4fd99732d6e7b3 Mon Sep 17 00:00:00 2001 From: Ian Chamberlain Date: Wed, 23 Mar 2022 20:45:46 -0400 Subject: [PATCH 4/4] Include note about libc APIs fulfilled by helper crates. --- src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md index 60c122da403a7..1309491734728 100644 --- a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md +++ b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md @@ -126,3 +126,5 @@ programs as well. The toolchain also provides a `libc` implementation, which is required by `std` for many of its APIs, and a helper library `libctru` which is used by several of the helper crates listed in [Requirements](#requirements). +This toolchain does not, however, include all of the APIs expected by `std`, +and the remaining APIs are implemented by `pthread-3ds` and `linker-fix-3ds`.