Crate ralte32

A Rust Arithmetic Library Testing Environment for embedded RISC-V 32-bit. This libraries allows the testing of arithmetic Rust code made for RISC-V 32-bit using the QEMU simulator. This is especially useful when developing with the Rust riscv32 intrinsics.

This library is mostly just a minimal hack to implement a testing environment and port the riscv32 embedded targets to a Linux userspace target.

Usage

First, this project uses the QEMU userspace simulator to simulate the target code. This can be installed with the standard qemu-user package on most operating systems.

# Linux: Debian / Ubuntu
sudo apt-get install qemu-user

# Linux: ArchLinux
sudo pacman -S qemu-user

For more platforms, take a look here.

Then, add ralte32 as a development dependency.

cargo add --dev ralte32

Lastly, create and/or add a short section to your .cargo/config.toml.

# ...

[target.riscv32imac-unknown-none-elf]
rustflags = ['-Ctarget-feature=+crt-static']
runner = "qemu-riscv32 -cpu rv32"

# NOTE: If you want to enable additional target features, add them here.
#
# Example to enable the `zk` feature:
# rustflags = ['-Ctarget-feature=+crt-static,+zk']
# runner = "qemu-riscv32 -cpu rv32,zk=true"

Then, to implement some tests, you add an example in examples/.

// examples/test-rv32.rs
#![no_std]
#![no_main]

use ralte32::define_tests;

fn test_multiplication() {
    assert_eq!(6 * 7, 42);
}

fn test_remainder() {
    assert_eq!(7 % 6, 1);
}

define_tests!{
    test_multiplication,
    test_remainder,
}

This can then be ran with:

cargo run --example test-rv32 --target riscv32imac-unknown-none-elf

This will give:

Running tests...

Running "test_multiplication"... SUCCESSFUL
Running "test_remainder"... SUCCESSFUL

Limitations

There are several known limitations.

1. First test or assert to fail, stops the test environment.
2. This only tests user-level code. Access to supervisor, machine or hypervisor instructions and CSRs is not possible.
3. Very limited support for printing.

License

This project is dual licensed under MIT and APACHE-2.0 licenses.

Modules

• syscall
  Linux system calls used by this crate.

Macros

• assert
  Assert whether an condition is true similar to core::assert.
• assert_eq
  Assert whether two items are equal similar to core::assert_eq.
• assert_ne
  Assert whether two items are not equal similar to core::assert_ne.
• define_tests
  Define a set of test functions to run.
• eprint
  Print several items to the standard error.
• eprintln
  Print several items and a newline to the standard error.
• print
  Print several items to the standard output.
• println
  Print several items and a newline to the standard output.

Structs

• Binary
  Wrapper type to format a unsigned integer with binary
• Hex
  Wrapper type to format a unsigned integer with hexadecimal

Traits

• Rv32Write
  Trait to write data to a file descriptor