Skip to content

Commit

Permalink
Update the LoongArch target documentation
Browse files Browse the repository at this point in the history 
The docs for the LoongArch targets are a bit dated since their
introduction, and the prose has some room for improvement as well.
Streamline a bit, referring to the neighboring targets' docs, and
provide up-to-date information as much as I can come up with.
  • Loading branch information
@xen0n
xen0n committed Jun 27, 2024
1 parent 2495953 commit 64be3a3
Show file tree
Hide file tree
Showing 2 changed files with 125 additions and 70 deletions.
139 changes: 91 additions & 48 deletions src/doc/rustc/src/platform-support/loongarch-linux.md
View file
Original file line number Diff line number Diff line change
@@ -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: `<machine>-<vendor>-<os><fabi_suffix>`, where `<machine>` specifies the CPU family/model, `<vendor>` specifies the vendor and `<os>` 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 `<fabi-suffix>`.
These support both native and cross builds, and have full support for `std`.

| `<fabi-suffix>` | `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:

<br>
* [LoongArch ISA manuals][la-docs]
* [Application Binary Interface for the LoongArch&trade; 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

Expand All @@ -35,60 +29,109 @@ 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"
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.
56 changes: 34 additions & 22 deletions src/doc/rustc/src/platform-support/loongarch-none.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -19,61 +19,73 @@ 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
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.

0 comments on commit 64be3a3

Please sign in to comment.