Skip to content

Commit 9f8ca0e

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #113042 - Cyanoxygen:add-mipsr6-target-docs, r=JohnTitor
Add Platform Support documentation for MIPS Release 6 targets This is a follow-up to our to-announce MCP, rust-lang/compiler-team#638, where we proposed to assign several maintainers for MIPS R6 targets and was told to explain that this set of targets are experimental in nature. This documentation describes Rust support for `mipsisa*r6*-unknown-linux-gnu*` targets (mainly `mipsisa64r6el-unknown-linux-gnuabi64`), including toolchain setup, building, and testing procedures.
2 parents c4083fa + 9262c33 commit 9f8ca0e

File tree

3 files changed

+186
-4
lines changed

3 files changed

+186
-4
lines changed

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

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
- [m68k-unknown-linux-gnu](platform-support/m68k-unknown-linux-gnu.md)
3737
- [mips64-openwrt-linux-musl](platform-support/mips64-openwrt-linux-musl.md)
3838
- [mipsel-sony-psx](platform-support/mipsel-sony-psx.md)
39+
- [mipsisa\*r6\*-unknown-linux-gnu\*](platform-support/mips-release-6.md)
3940
- [nvptx64-nvidia-cuda](platform-support/nvptx64-nvidia-cuda.md)
4041
- [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md)
4142
- [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)

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

+4-4
Original file line numberDiff line numberDiff line change
@@ -277,10 +277,10 @@ target | std | host | notes
277277
[`mipsel-sony-psx`](platform-support/mipsel-sony-psx.md) | * | | MIPS (LE) Sony PlayStation 1 (PSX)
278278
`mipsel-unknown-linux-uclibc` | ✓ | | MIPS (LE) Linux with uClibc
279279
`mipsel-unknown-none` | * | | Bare MIPS (LE) softfloat
280-
`mipsisa32r6-unknown-linux-gnu` | ? | |
281-
`mipsisa32r6el-unknown-linux-gnu` | ? | |
282-
`mipsisa64r6-unknown-linux-gnuabi64` | ? | |
283-
`mipsisa64r6el-unknown-linux-gnuabi64` | ? | |
280+
[`mipsisa32r6-unknown-linux-gnu`](platform-support/mips-release-6.md) | ? | | 32-bit MIPS Release 6 Big Endian
281+
[`mipsisa32r6el-unknown-linux-gnu`](platform-support/mips-release-6.md) | ? | | 32-bit MIPS Release 6 Little Endian
282+
[`mipsisa64r6-unknown-linux-gnuabi64`](platform-support/mips-release-6.md) | ? | | 64-bit MIPS Release 6 Big Endian
283+
[`mipsisa64r6el-unknown-linux-gnuabi64`](platform-support/mips-release-6.md) | ✓ | ✓ | 64-bit MIPS Release 6 Little Endian
284284
`msp430-none-elf` | * | | 16-bit MSP430 microcontrollers
285285
`powerpc-unknown-linux-gnuspe` | ✓ | | PowerPC SPE Linux
286286
`powerpc-unknown-linux-musl` | ? | |

‎src/doc/rustc/src/platform-support/mips-release-6.md

+181
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# mipsisa\*r6\*-unknown-linux-gnu\*
2+
3+
**Tier: 3**
4+
5+
[MIPS Release 6](https://s3-eu-west-1.amazonaws.com/downloads-mips/documents/MD00083-2B-MIPS64INT-AFP-06.01.pdf), or simply MIPS R6, is the latest iteration of the MIPS instruction set architecture (ISA).
6+
7+
MIPS R6 is experimental in nature, as there is not yet real hardware. However, Qemu emulation is available and we have two Linux distros maintained for development and evaluation purposes. This documentation describes the Rust support for MIPS R6 targets under `mipsisa*r6*-unknown-linux-gnu*`.
8+
9+
The target name follow this format: `<machine>-<vendor>-<os><abi_suffix>`, where `<machine>` specifies the CPU family/model, `<vendor>` specifies the vendor and `<os>` the operating system name. The `<abi_suffix>` denotes the base ABI (32/n32/64/o64).
10+
11+
| ABI suffix | Description |
12+
|------------|------------------------------------|
13+
| abi64 | Uses the 64-bit (64) ABI |
14+
| abin32 | Uses the n32 ABI |
15+
| N/A | Uses the (assumed) 32-bit (32) ABI |
16+
17+
## Target Maintainers
18+
19+
- [Xuan Chen](https://github.com/chenx97) <[email protected]>
20+
- [Walter Ji](https://github.com/709924470) <[email protected]>
21+
- [Xinhui Yang](https://github.com/Cyanoxygen) <[email protected]>
22+
- [Lain Yang](https://github.com/Fearyncess) <[email protected]>
23+
24+
## Requirements
25+
26+
### C/C++ Toolchain
27+
28+
A GNU toolchain for one of the MIPS R6 target is required. [AOSC OS](https://aosc.io/) provides working native and cross-compiling build environments. You may also supply your own a toolchain consisting of recent versions of GCC and Binutils.
29+
30+
### Target libraries
31+
32+
A minimum set of libraries is required to perform dynamic linking:
33+
34+
- GNU glibc
35+
- OpenSSL
36+
- Zlib
37+
- Linux API Headers
38+
39+
This set of libraries should be installed to make up minimal target sysroot.
40+
41+
For AOSC OS, You may install such a sysroot with the following commands:
42+
43+
```sh
44+
cd /tmp
45+
46+
# linux+api, glibc, and file system structure are included in the toolchain.
47+
sudo apt install gcc+cross-mips64r6el binutils+cross-mips64r6el
48+
49+
# Download and extract required libraries.
50+
wget https://repo.aosc.io/debs/pool/stable/main/z/zlib_1.2.13-0_mips64r6el.deb -O zlib.deb
51+
wget https://repo.aosc.io/debs/pool/stable/main/o/openssl_1.1.1q-1_mips64r6el.deb -O openssl.deb
52+
53+
# Extract them to your desired location.
54+
for i in zlib openssl ; do
55+
sudo dpkg-deb -vx $i.deb /var/ab/cross-root/mips64r6el
56+
done
57+
58+
# Workaround a possible ld bug when using -Wl,-Bdynamic.
59+
sudo sed -i 's|/usr|=/usr|g' /var/ab/cross-root/mips64r6el/usr/lib/libc.so
60+
```
61+
62+
For other distros, you may build them manually.
63+
64+
## Building
65+
66+
The following procedure outlines the build process for the MIPS64 R6 target with 64-bit (64) ABI (`mipsisa64r6el-unknown-linux-gnuabi64`).
67+
68+
### Prerequisite: Disable debuginfo
69+
70+
A LLVM bug makes rustc crash if debug or debug info generation is enabled. You need to edit `config.toml` to disable this:
71+
72+
```toml
73+
[rust]
74+
debug = false
75+
debug-info-level = 0
76+
```
77+
78+
### Prerequisite: Enable rustix's libc backend
79+
80+
The crate `rustix` may try to link itself against MIPS R2 assembly, resulting in linkage error. To avoid this, you may force `rustix` to use its fallback `libc` backend by setting relevant `RUSTFLAGS`:
81+
82+
```sh
83+
export RUSTFLAGS="--cfg rustix_use_libc"
84+
```
85+
86+
This will trigger warnings during build, as `-D warnings` is enabled by default. Disable `-D warnings` by editing `config.toml` to append the following:
87+
88+
```toml
89+
[rust]
90+
deny-warnings = false
91+
```
92+
93+
### Prerequisite: Supplying OpenSSL
94+
95+
As a Tier 3 target, `openssl_sys` lacks the vendored OpenSSL library for this target. You will need to provide a prebuilt OpenSSL library to link `cargo`. Since we have a pre-configured sysroot, we can point to it directly:
96+
97+
```sh
98+
export MIPSISA64R6EL_UNKNOWN_LINUX_GNUABI64_OPENSSL_NO_VENDOR=y
99+
export MIPSISA64R6EL_UNKNOWN_LINUX_GNUABI64_OPENSSL_DIR="/var/ab/cross-root/mips64r6el/usr"
100+
```
101+
102+
On Debian, you may need to provide library path and include path separately:
103+
104+
```sh
105+
export MIPSISA64R6EL_UNKNOWN_LINUX_GNUABI64_OPENSSL_NO_VENDOR=y
106+
export MIPSISA64R6EL_UNKNOWN_LINUX_GNUABI64_OPENSSL_LIB_DIR="/usr/lib/mipsisa64r6el-linux-gnuabi64/"
107+
export MIPSISA64R6EL_UNKNOWN_LINUX_GNUABI64_OPENSSL_INCLUDE_DIR="/usr/include"
108+
```
109+
110+
### Launching `x.py`
111+
112+
```toml
113+
[build]
114+
target = ["mipsisa64r6el-unknown-linux-gnuabi64"]
115+
```
116+
117+
Make sure that `mipsisa64r6el-unknown-linux-gnuabi64-gcc` is available from your executable search path (`$PATH`).
118+
119+
Alternatively, you can specify the directories to all necessary toolchain executables in `config.toml`:
120+
121+
```toml
122+
[target.mipsisa64r6el-unknown-linux-gnuabi64]
123+
# Adjust the paths below to point to your toolchain installation prefix.
124+
cc = "/toolchain_prefix/bin/mipsisa64r6el-unknown-linux-gnuabi64-gcc"
125+
cxx = "/toolchain_prefix/bin/mipsisa64r6el-unknown-linux-gnuabi64-g++"
126+
ar = "/toolchain_prefix/bin/mipsisa64r6el-unknown-linux-gnuabi64-gcc-ar"
127+
ranlib = "/toolchain_prefix/bin/mipsisa64r6el-unknown-linux-gnuabi64-ranlib"
128+
linker = "/toolchain_prefix/bin/mipsisa64r6el-unknown-linux-gnuabi64-gcc"
129+
```
130+
131+
Or, you can specify your cross compiler toolchain with an environment variable:
132+
133+
```sh
134+
export CROSS_COMPILE="/opt/abcross/mips64r6el/bin/mipsisa64r6el-aosc-linux-gnuabi64-"
135+
```
136+
137+
Finally, launch the build script:
138+
139+
```sh
140+
./x.py build
141+
```
142+
143+
### Tips
144+
145+
- Avoid setting `cargo-native-static` to `false`, as this will result in a redundant artifact error while building clippy:
146+
```text
147+
duplicate artifacts found when compiling a tool, this typically means that something was recompiled because a transitive dependency has different features activated than in a previous build:
148+
149+
the following dependencies have different features:
150+
syn 2.0.8 (registry+https://github.com/rust-lang/crates.io-index)
151+
`clippy-driver` additionally enabled features {"full"} at ...
152+
`cargo` additionally enabled features {} at ...
153+
154+
to fix this you will probably want to edit the local src/tools/rustc-workspace-hack/Cargo.toml crate, as that will update the dependency graph to ensure that these crates all share the same feature set
155+
thread 'main' panicked at 'tools should not compile multiple copies of the same crate', tool.rs:250:13
156+
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
157+
```
158+
159+
## Building Rust programs
160+
161+
To build Rust programs for MIPS R6 targets, for instance, the `mipsisa64r6el-unknown-linux-gnuabi64` target:
162+
163+
```bash
164+
cargo build --target mipsisa64r6el-unknown-linux-gnuabi64
165+
```
166+
167+
## Testing
168+
169+
To test a cross-compiled binary on your build system, install the Qemu user emulator that support the MIPS R6 architecture (`qemu-user-mipsel` or `qemu-user-mips64el`). GCC runtime libraries (`libgcc_s`) for the target architecture should be present in target sysroot to run the program.
170+
171+
```sh
172+
env \
173+
CARGO_TARGET_MIPSISA64R6EL_UNKNOWN_LINUX_GNUABI64_LINKER="/opt/abcross/mips64r6el/bin/mipsisa64r6el-aosc-linux-gnuabi64-gcc" \
174+
CARGO_TARGET_MIPSISA64R6EL_UNKNOWN_LINUX_GNUABI64_RUNNER="qemu-mips64el-static -L /var/ab/cross-root/mips64r6el" \
175+
cargo run --release \
176+
--target mipsisa64r6el-unknown-linux-gnuabi64
177+
```
178+
179+
## Tips for building Rust programs for MIPS R6
180+
181+
- Until we finalize a fix, please make sure the aforementioned workarounds for `rustix` crate and LLVM are always applied. This can be achieved by setting the relevant environment variables, and editing `Cargo.toml` before building.

0 commit comments

Comments
 (0)