diff --git a/src/doc/rustc/src/platform-support/loongarch-linux.md b/src/doc/rustc/src/platform-support/loongarch-linux.md index e8f55b8bfce10..45eb0a81216d8 100644 --- a/src/doc/rustc/src/platform-support/loongarch-linux.md +++ b/src/doc/rustc/src/platform-support/loongarch-linux.md @@ -1,30 +1,24 @@ -# loongarch\*-unknown-linux-\* +# `loongarch*-unknown-linux-*` -**Tier: 2** +**Tier: 2 (with Host Tools)** -[LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited. +[LoongArch][la-docs] Linux targets. +LoongArch is a RISC ISA developed by Loongson Technology Corporation Limited. -[LoongArch]: https://loongson.github.io/LoongArch-Documentation/README-EN.html +| Target | Description | +|--------|-------------| +| `loongarch64-unknown-linux-gnu` | LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36) | +| `loongarch64-unknown-linux-musl` | LoongArch64 Linux, LP64D ABI (kernel 5.19, musl 1.2.5) | -The target name follow this format: `--`, where `` specifies the CPU family/model, `` specifies the vendor and `` the operating system name. -While the integer base ABI is implied by the machine field, the floating point base ABI type is encoded into the os field of the specifier using the string suffix ``. +These support both native and cross builds, and have full support for `std`. -| `` | `Description` | -|------------------------|--------------------------------------------------------------------| -| f64 | The base ABI use 64-bits FPRs for parameter passing. (lp64d)| -| f32 | The base ABI uses 32-bit FPRs for parameter passing. (lp64f)| -| sf | The base ABI uses no FPR for parameter passing. (lp64s) | +Reference material: -
+* [LoongArch ISA manuals][la-docs] +* [Application Binary Interface for the LoongArch™ Architecture][la-abi-specs] -|`ABI type(Base ABI/ABI extension)`| `C library` | `kernel` | `target tuple` | -|----------------------------------|-------------|----------|----------------------------------| -| lp64d/base | glibc | linux | loongarch64-unknown-linux-gnu | -| lp64f/base | glibc | linux | loongarch64-unknown-linux-gnuf32 | -| lp64s/base | glibc | linux | loongarch64-unknown-linux-gnusf | -| lp64d/base | musl libc | linux | loongarch64-unknown-linux-musl| -| lp64f/base | musl libc | linux | loongarch64-unknown-linux-muslf32| -| lp64s/base | musl libc | linux | loongarch64-unknown-linux-muslsf | +[la-abi-specs]: https://github.com/loongson/la-abi-specs +[la-docs]: https://loongson.github.io/LoongArch-Documentation/README-EN.html ## Target maintainers @@ -35,23 +29,57 @@ While the integer base ABI is implied by the machine field, the floating po ## Requirements -This target is cross-compiled. -A GNU toolchain for LoongArch target is required. It can be downloaded from https://github.com/loongson/build-tools/releases, or built from the source code of GCC (12.1.0 or later) and Binutils (2.40 or later). +### OS Version -## Building the target +The minimum supported Linux version is 5.19. -The target can be built by enabling it for a `rustc` build. +Some Linux distributions, mostly commercial ones, may provide forked Linux +kernels that has a version number less than 5.19 for their LoongArch ports. +Such kernels may still get patched to be compatible with the upstream Linux +5.19 UAPI, therefore supporting the targets described in this document, but +this is not always the case. The `rustup` installer contains a check for this, +and will abort if incompatibility is detected. + +### Host toolchain + +The targets require a reasonably up-to-date LoongArch toolchain on the host. +Currently the following components are used by the Rust CI to build the target, +and the versions can be seen as the minimum requirement: + +* GNU Binutils 2.40 +* GCC 13.x +* glibc 2.36 +* linux-headers 5.19 + +Of these, glibc and linux-headers are at their respective earliest versions with +mainline LoongArch support, so it is impossible to use older versions of these. +Older versions of Binutils and GCC will not work either, due to lack of support +for newer LoongArch ELF relocation types, among other features. + +Recent LLVM/Clang toolchains may be able to build the targets, but are not +currently being actively tested. + +## Building + +These targets are distributed through `rustup`, and otherwise require no +special configuration. + +If you need to build your own Rust for some reason though, the targets can be +simply enabled in `config.toml`. For example: ```toml [build] target = ["loongarch64-unknown-linux-gnu"] ``` -Make sure `loongarch64-unknown-linux-gnu-gcc` can be searched from the directories specified in`$PATH`. Alternatively, you can use GNU LoongArch Toolchain by adding the following to `config.toml`: +Make sure the LoongArch toolchain binaries are reachable from `$PATH`. +Alternatively, you can explicitly configure the paths in `config.toml`: ```toml [target.loongarch64-unknown-linux-gnu] -# ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN +# Adjust the paths to point at your toolchain +# Suppose the toolchain is placed at /TOOLCHAIN_PATH, and the cross prefix is +# "loongarch64-unknown-linux-gnu-": cc = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc" cxx = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++" ar = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ar" @@ -59,36 +87,51 @@ ranlib = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ranlib" linker = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc" ``` -## Cross-compilation +### Cross-compilation -This target can be cross-compiled on a `x86_64-unknown-linux-gnu` host. Cross-compilation on other hosts may work but is not tested. +This target can be cross-compiled on a `x86_64-unknown-linux-gnu` host. +Other hosts are also likely to work, but not actively tested. + +You can test the cross build directly on the host, thanks to QEMU linux-user emulation. +An example is given below: + +```sh +# Suppose the cross toolchain is placed at $TOOLCHAIN_PATH, with a cross prefix +# of "loongarch64-unknown-linux-gnu-". +export CC_loongarch64_unknown_linux_gnu="$TOOLCHAIN_PATH"/bin/loongarch64-unknown-linux-gnu-gcc +export CXX_loongarch64_unknown_linux_gnu="$TOOLCHAIN_PATH"/bin/loongarch64-unknown-linux-gnu-g++ +export AR_loongarch64_unknown_linux_gnu="$TOOLCHAIN_PATH"/bin/loongarch64-unknown-linux-gnu-gcc-ar +export CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNU_LINKER="$TOOLCHAIN_PATH"/bin/loongarch64-unknown-linux-gnu-gcc + +# Point qemu-loongarch64 to the LoongArch sysroot. +# Suppose the sysroot is located at "sysroot" below the toolchain root: +export CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNU_RUNNER="qemu-loongarch64 -L $TOOLCHAIN_PATH/sysroot" +# Or alternatively, if binfmt_misc is set up for running LoongArch binaries +# transparently: +export QEMU_LD_PREFIX="$TOOLCHAIN_PATH"/sysroot -## Testing -To test a cross-compiled binary on your build system, install the qemu binary that supports the LoongArch architecture and execute the following commands. -```text -CC_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \ -CXX_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++ \ -AR_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc-ar \ -CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_LINKER=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \ -# SET TARGET SYSTEM LIBRARY PATH -CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_RUNNER="qemu-loongarch64 -L /TOOLCHAIN_PATH/TARGET_LIBRARY_PATH" \ cargo run --target loongarch64-unknown-linux-gnu --release ``` -Tested on x86 architecture, other architectures not tested. -## Building Rust programs +## Testing + +There are no special requirements for testing and running the targets. +For testing cross builds on the host, please refer to the "Cross-compilation" +section above. -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 `std` by using `build-std` or similar. +## Building Rust programs -If `rustc` has support for that target and the library artifacts are available, then Rust static libraries can be built for that target: +As the targets are available through `rustup`, it is very easy to build Rust +programs for these targets: same as with other architectures. +Note that you will need a LoongArch C/C++ toolchain for linking, or if you want +to compile C code along with Rust (such as for Rust crates with C dependencies). -```shell -$ rustc --target loongarch64-unknown-linux-gnu your-code.rs --crate-type staticlib -$ ls libyour_code.a +```sh +rustup target add loongarch64-unknown-linux-gnu +cargo build --target loongarch64-unknown-linux-gnu ``` -On Rust Nightly it's possible to build without the target artifacts available: +Availability of pre-built artifacts through `rustup` are as follows: -```text -cargo build -Z build-std --target loongarch64-unknown-linux-gnu -``` +* `loongarch64-unknown-linux-gnu`: since Rust 1.71; +* `loongarch64-unknown-linux-musl`: since Rust 1.81. diff --git a/src/doc/rustc/src/platform-support/loongarch-none.md b/src/doc/rustc/src/platform-support/loongarch-none.md index 68d7c9d85e444..110a7cc3424d4 100644 --- a/src/doc/rustc/src/platform-support/loongarch-none.md +++ b/src/doc/rustc/src/platform-support/loongarch-none.md @@ -4,10 +4,10 @@ Freestanding/bare-metal LoongArch64 binaries in ELF format: firmware, kernels, etc. -| Target | Descriptions | -|------------------------------------|-------------------------------------------------------| -| loongarch64-unknown-none | LoongArch 64-bit, LP64D ABI (freestanding, hardfloat) | -| loongarch64-unknown-none-softfloat | LoongArch 64-bit, LP64S ABI (freestanding, softfloat) | +| Target | Description | +|--------|-------------| +| `loongarch64-unknown-none` | LoongArch 64-bit, LP64D ABI (freestanding, hard-float) | +| `loongarch64-unknown-none-softfloat` | LoongArch 64-bit, LP64S ABI (freestanding, soft-float) | ## Target maintainers @@ -19,6 +19,8 @@ Freestanding/bare-metal LoongArch64 binaries in ELF format: firmware, kernels, e 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. +The `*-softfloat` target does not assume existence of FPU or any other LoongArch +ISA extension, and does not make use of any non-GPR register. 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 @@ -26,54 +28,64 @@ 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 `loongarch` -hardware; enabling additional target features may raise this baseline. +By default, code generated with the soft-float target should run on any +LoongArch64 hardware, with the hard-float target additionally requiring an FPU; +enabling additional target features may raise this baseline. -Code generated with this target will use the `small` code model by default. +Code generated with the targets will use the `small` code model by default. You can change this using the `-C code-model=` option to rustc. -On `loongarch64-unknown-none*`, `extern "C"` uses the [standard calling -convention](https://loongson.github.io/LoongArch-Documentation/LoongArch-ELF-ABI-EN.html). +On `loongarch64-unknown-none*`, `extern "C"` uses the [architecture's standard calling convention][lapcs]. -This target generates binaries in the ELF format. Any alternate formats or +[lapcs]: https://github.com/loongson/la-abi-specs/blob/release/lapcs.adoc + +The targets generate binaries in the ELF format. Any alternate formats or special considerations for binary layout will require linker options or linker scripts. ## Building the target -You can build Rust with support for the target by adding it to the `target` +You can build Rust with support for the targets by adding them to the `target` list in `config.toml`: ```toml [build] build-stage = 1 -target = ["loongarch64-unknown-none"] +target = [ + "loongarch64-unknown-none", + "loongarch64-unknown-none-softfloat", +] ``` +## Testing + +As the targets support a variety of different environments and do not support +`std`, they do not support running the Rust test suite. + ## Building Rust programs -```text +Starting with Rust 1.74, precompiled artifacts are provided via `rustup`: + +```sh +# install cross-compile toolchain +rustup target add loongarch64-unknown-none # target flag may be used with any cargo or rustc command cargo build --target loongarch64-unknown-none ``` -## Testing - -As `loongarch64-unknown-none*` supports a variety of different environments and does -not support `std`, this target does not support running the Rust test suite. - ## Cross-compilation toolchains and C code -If you want to compile C code along with Rust (such as for Rust crates with C -dependencies), you will need an appropriate `loongarch` toolchain. +For cross builds, you will need an appropriate LoongArch C/C++ toolchain for +linking, or if you want to compile C code along with Rust (such as for Rust +crates with C dependencies). Rust *may* be able to use an `loongarch64-unknown-linux-gnu-` toolchain with appropriate standalone flags to build for this toolchain (depending on the assumptions of that toolchain, see below), or you may wish to use a separate `loongarch64-unknown-none` toolchain. -On some `loongarch` hosts that use ELF binaries, you *may* be able to use the host +On some LoongArch hosts that use ELF binaries, you *may* be able to use the host C toolchain, if it does not introduce assumptions about the host environment that don't match the expectations of a standalone environment. Otherwise, you may need a separate toolchain for standalone/freestanding development, just as -when cross-compiling from a non-`loongarch` platform. +when cross-compiling from a non-LoongArch platform.