diff options
| -rw-r--r-- | src/doc/rustc/src/SUMMARY.md | 1 | ||||
| -rw-r--r-- | src/doc/rustc/src/platform-support.md | 4 | ||||
| -rw-r--r-- | src/doc/rustc/src/platform-support/hexagon-unknown-linux-musl.md | 102 | ||||
| -rw-r--r-- | src/doc/rustc/src/platform-support/hexagon-unknown-none-elf.md | 19 |
4 files changed, 121 insertions, 5 deletions
diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index d4ca91977a6..90ac97f35f6 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -39,6 +39,7 @@ - [\*-unknown-fuchsia](platform-support/fuchsia.md) - [\*-kmc-solid_\*](platform-support/kmc-solid.md) - [csky-unknown-linux-gnuabiv2\*](platform-support/csky-unknown-linux-gnuabiv2.md) + - [hexagon-unknown-linux-musl](platform-support/hexagon-unknown-linux-musl.md) - [hexagon-unknown-none-elf](platform-support/hexagon-unknown-none-elf.md) - [loongarch\*-unknown-linux-\*](platform-support/loongarch-linux.md) - [loongarch\*-unknown-none\*](platform-support/loongarch-none.md) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 984cb13f790..f1e3ad81b85 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -286,8 +286,8 @@ target | std | host | notes `bpfel-unknown-none` | * | | BPF (little endian) `csky-unknown-linux-gnuabiv2` | ✓ | | C-SKY abiv2 Linux (little endian) `csky-unknown-linux-gnuabiv2hf` | ✓ | | C-SKY abiv2 Linux, hardfloat (little endian) -[`hexagon-unknown-none-elf`](platform-support/hexagon-unknown-none-elf.md)| * | Bare Hexagon (v60+, HVX) -`hexagon-unknown-linux-musl` | ? | | +[`hexagon-unknown-none-elf`](platform-support/hexagon-unknown-none-elf.md)| * | | Bare Hexagon (v60+, HVX) +[`hexagon-unknown-linux-musl`](platform-support/hexagon-unknown-linux-musl.md) | ✓ | | Hexagon Linux `i386-apple-ios` | ✓ | | 32-bit x86 iOS [^x86_32-floats-return-ABI] [`i586-pc-nto-qnx700`](platform-support/nto-qnx.md) | * | | 32-bit x86 QNX Neutrino 7.0 RTOS [^x86_32-floats-return-ABI] [`i586-unknown-netbsd`](platform-support/netbsd.md) | ✓ | | 32-bit x86, restricted to Pentium diff --git a/src/doc/rustc/src/platform-support/hexagon-unknown-linux-musl.md b/src/doc/rustc/src/platform-support/hexagon-unknown-linux-musl.md new file mode 100644 index 00000000000..c1372726a35 --- /dev/null +++ b/src/doc/rustc/src/platform-support/hexagon-unknown-linux-musl.md @@ -0,0 +1,102 @@ +# `hexagon-unknown-linux-musl` + +**Tier: 3** + +Target for cross-compiling Linux user-mode applications targeting the Hexagon +DSP architecture. + +| Target | Descriptions | +| ------------------------ | ----------------------------------------- | +| hexagon-unknown-linux-musl | Hexagon 32-bit Linux | + +## Target maintainers + +- [Brian Cain](https://github.com/androm3da), `bcain@quicinc.com` + +## Requirements +The target is cross-compiled. This target supports `std`. By default, code +generated with this target should run on Hexagon DSP hardware. + +- `-Ctarget-cpu=hexagonv73` adds support for instructions defined up to Hexagon V73. + +Binaries can be run using QEMU user emulation. On Debian-based systems, it should be +sufficient to install the package `qemu-user-static` to be able to run simple static +binaries: + +```text +# apt install qemu-user-static +# qemu-hexagon-static ./hello +``` + +In order to build linux programs with Rust, you will require a linker capable +of targeting hexagon. You can use `clang`/`lld` from the [hexagon toolchain +using exclusively public open source repos](https://github.com/quic/toolchain_for_hexagon/releases). + +Also included in that toolchain is the C library that can be used when creating +dynamically linked executables. + +```text +# /opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/bin/qemu-hexagon -L /opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr/ ./hello +``` + +## Building the target +Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this +target. + +Therefore, you can build Rust with support for the target by adding it to the +target list in `config.toml`, a sample configuration is shown below. + +```toml +[build] +target = [ "hexagon-unknown-linux-musl"] + +[target.hexagon-unknown-linux-musl] + +cc = "hexagon-unknown-linux-musl-clang" +cxx = "hexagon-unknown-linux-musl-clang++" +linker = "hexagon-unknown-linux-musl-clang" +ar = "hexagon-unknown-linux-musl-ar" +ranlib = "hexagon-unknown-linux-musl-ranlib" +musl-root = "/opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr" +llvm-libunwind = 'in-tree' +qemu-rootfs = "/opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr" +``` + + +## Testing + +Currently there is no support to run the rustc test suite for this target. + + +## Building Rust programs + +Download and install the hexagon open source toolchain from https://github.com/quic/toolchain_for_hexagon/releases + +The following `.cargo/config` is needed inside any project directory to build +for the Hexagon Linux target: + +```toml +[build] +target = "hexagon-unknown-linux-musl" + +[target.hexagon-unknown-linux-musl] +linker = "hexagon-unknown-linux-musl-clang" +ar = "hexagon-unknown-linux-musl-ar" +runner = "qemu-hexagon -L /opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr" +``` + +Edit the "runner" in `.cargo/config` to point to the path to your toolchain's +C library. + +```text +... +runner = "qemu-hexagon -L /path/to/my/inst/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr" +... +``` + +Build/run your rust program with `qemu-hexagon` in your `PATH`: + +```text +export PATH=/path/to/my/inst/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/bin/:$PATH +cargo run -Zbuild-std -Zbuild-std-features=llvm-libunwind +``` diff --git a/src/doc/rustc/src/platform-support/hexagon-unknown-none-elf.md b/src/doc/rustc/src/platform-support/hexagon-unknown-none-elf.md index 3ac1d2c2460..a0e26b798ac 100644 --- a/src/doc/rustc/src/platform-support/hexagon-unknown-none-elf.md +++ b/src/doc/rustc/src/platform-support/hexagon-unknown-none-elf.md @@ -41,6 +41,8 @@ target = ["<target for your host>", "hexagon-unknown-none-elf"] cc = "hexagon-unknown-none-elf-clang" cxx = "hexagon-unknown-none-elf-clang++" linker = "hexagon-unknown-none-elf-clang" +ranlib = "hexagon-unknown-none-elf-ranlib" +ar = "hexagon-unknown-none-elf-ar" llvm-libunwind = 'in-tree' ``` @@ -142,7 +144,7 @@ ${cc} --target=hexagon-unknown-none-elf -o testit \ ${g0_lib_path}/init.o \ -L${sdk_libs}/${q6_arch}/ \ -L${sdk_libs}/ \ - testit.c \ + wrap.c \ target/hexagon-unknown-none-elf/${build_cfg}/libdemo1_hexagon.rlib \ target/hexagon-unknown-none-elf/${build_cfg}/deps/libcore-*.rlib \ target/hexagon-unknown-none-elf/${build_cfg}/deps/libcompiler_builtins-*.rlib \ @@ -217,7 +219,18 @@ fn rust_eh_personality() {} ``` -Next, save the script below as `build.sh` and edit it to suit your +Next, create a C program as an entry point, save the content below as +`wrap.c`: + +```C +int hello(); + +int main() { + hello(); +} +``` + +Then, save the script below as `build.sh` and edit it to suit your environment. The script below will build a shared object against the QuRT RTOS which is suitable for emulation or on-device testing when loaded via the fastrpc-shell. @@ -248,7 +261,7 @@ ${cc} --target=hexagon-unknown-none-elf -o testit.so \ -Wl,--wrap=realloc \ -Wl,--wrap=memalign \ -m${q6_arch} \ - testit.c \ + wrap.c \ target/hexagon-unknown-none-elf/${build_cfg}/libdemo2_hexagon.rlib \ target/hexagon-unknown-none-elf/${build_cfg}/deps/libcore-*.rlib \ target/hexagon-unknown-none-elf/${build_cfg}/deps/libcompiler_builtins-*.rlib \ |