hexagon-unknown-qurt

Tier: 3

Rust for Hexagon QuRT (Qualcomm Real-Time OS).

Target maintainers

@androm3da

Requirements

This target is cross-compiled. There is support for std. The target uses QuRT's standard library and runtime.

By default, code generated with this target should run on Hexagon DSP hardware running the QuRT real-time operating system.

• -Ctarget-cpu=hexagonv69 targets Hexagon V69 architecture (default)
• -Ctarget-cpu=hexagonv73 adds support for instructions defined up to Hexagon V73

Functions marked extern "C" use the Hexagon architecture calling convention.

This target generates position-independent ELF binaries by default, making it suitable for both static images and dynamic shared objects.

The Hexagon SDK is required for building programs for this target.

Linking

This target uses hexagon-clang from the Hexagon SDK as the default linker. The linker is available at paths like /opt/Hexagon_SDK/6.4.0.2/tools/HEXAGON_Tools/19.0.04/Tools/bin/hexagon-clang.

Alternative linkers include:

• eld, which is provided with both the opensource hexagon toolchain and the Hexagon SDK
• rust-lld can be used by specifying -C linker=rust-lld

Building the target

You can build Rust with support for the target by adding it to the target list in bootstrap.toml:

[build]
build-stage = 1
host = ["<target for your host>"]
target = ["<target for your host>", "hexagon-unknown-qurt"]

[target.hexagon-unknown-qurt]
cc = "hexagon-clang"
cxx = "hexagon-clang++"
ranlib = "llvm-ranlib"
ar = "llvm-ar"
llvm-libunwind = 'in-tree'

Replace <target for your host> with x86_64-unknown-linux-gnu or whatever else is appropriate for your host machine.

Building Rust programs

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 core by using build-std or similar.

Static Image Targeting

For static executables that run directly on QuRT, use the default target configuration with additional linker flags:

# Build a static executable for QuRT
cargo rustc --target hexagon-unknown-qurt -- \
    -C link-args="-static -nostdlib" \
    -C link-args="-L/opt/Hexagon_SDK/6.3.0.0/rtos/qurt/computev69/lib" \
    -C link-args="-lqurt -lc"

This approach is suitable for:

• Standalone QuRT applications
• System-level services
• Boot-time initialization code
• Applications that need deterministic memory layout

User-Loadable Shared Object Targeting

For shared libraries that can be dynamically loaded by QuRT applications:

# Build a shared object for QuRT
cargo rustc --target hexagon-unknown-qurt \
    --crate-type=cdylib -- \
    -C link-args="-shared -fPIC" \
    -C link-args="-L/opt/Hexagon_SDK/6.3.0.0/rtos/qurt/computev69/lib"

This approach is suitable for:

• Plugin architectures
• Runtime-loadable modules
• Libraries shared between multiple applications
• Code that needs to be updated without system restart

Configuration Options

The target can be customized for different use cases:

For Static Images

# In .cargo/config.toml
[target.hexagon-unknown-qurt]
rustflags = [
    "-C", "link-args=-static",
    "-C", "link-args=-nostdlib",
    "-C", "target-feature=-small-data"
]

For Shared Objects

# In .cargo/config.toml
[target.hexagon-unknown-qurt]
rustflags = [
    "-C", "link-args=-shared",
    "-C", "link-args=-fPIC",
    "-C", "relocation-model=pic"
]

Testing

Since hexagon-unknown-qurt requires the QuRT runtime environment, testing requires either:

• Hexagon hardware with QuRT
• hexagon-sim
• QEMU (qemu-system-hexagon)

Cross-compilation toolchains and C code

This target requires the proprietary Hexagon SDK toolchain for C interoperability:

• Sample SDK Path: /opt/Hexagon_SDK/6.3.0.0/
• Toolchain: Use hexagon-clang from the Hexagon SDK
• Libraries: Link against QuRT system libraries as needed

C Interoperability Example

// lib.rs
#![no_std]
extern crate std;

#[unsafe(no_mangle)]
pub extern "C" fn rust_function() -> i32 {
    // Your Rust code here
    42
}

fn main() {
    // Example usage
    let result = rust_function();
    assert_eq!(result, 42);
}

// wrapper.c
extern int rust_function(void);

int main() {
    return rust_function();
}

The target supports both static linking for standalone applications and dynamic linking for modular architectures, making it flexible for various QuRT deployment scenarios.