Crate mu_lib

Expand description

§mu_lib

✅ mu_lib version 0.1.6 and mu_macro version 0.1.2 or higher are considered stable.
Please use these versions or above to ensure compatibility.

A library providing essential functionality for the XCENA system. This library is designed to work with both C++ and Rust, providing a safe and efficient interface for system operations.

§Features

Safe Rust bindings for all system operations
Thread-safe atomic operations
Comprehensive logging system
Task management utilities
System clock access
Message passing capabilities

§Modules

assert: Provides condition checking and program termination functions
atomic: Provides thread-safe atomic operations
clock: Provides system clock functionality
logger: Provides logging functionality with various log levels
message: Provides synchronous and asynchronous message handling functions
print: Provides output functionality for UART, host, and general printing
task: Provides task management functionality

§Example: Creating and Building a `myMuKernel` Project

This guide walks you through creating a minimal kernel crate using mu_macro and mu_lib.

§1. Project Initialization

Create a new Rust binary project:

cargo new myMuKernel

This generates:

myMuKernel/
├── Cargo.toml
└── src/
    └── main.rs

§2. Build Environment Setup

⚠️ Make sure to adjust all paths (rustc, linker, library paths, etc.) to match your own environment. Using incorrect paths will cause the build to fail.

§2.1 Using `.cargo/config.toml`

Create the .cargo/config.toml file:

myMuKernel/
├── Cargo.toml
├── .cargo/
│   └── config.toml
└── src/
    └── main.rs

Example config.toml:

[build]
target = "riscv64imfdxmetis-unknown-none-elf"
rustc = "/mnt/media/mu_compiler/rust_build/x86_64-unknown-linux-gnu/stage1/bin/rustc"

[target.riscv64imfdxmetis-unknown-none-elf]
linker = "/mnt/media/mu_compiler/llvm-18.1/bin/ld.lld"
rustflags = [
    "-C", "link-args=-L/mnt/media/mu_compiler/llvm-18.1/picolibc-rv/newlib",
    "-C", "link-args=-L/mnt/media/mu_compiler/llvm-18.1/builtins-rv -lclang_rt.builtins-riscv64",
    "-C", "link-args=-T/usr/local/mu_library/mu/script/mu_linker.ld",
    "-C", "link-args=-lmu_std -L../../../../mu_lib/mu/lib",
    "-C", "target-feature=+xmetis",
    # "--extern", "mu_macro=../../../../mu_lib/mu/lib/libmu_macro.so",
    # "--extern", "mu_lib=../../../../mu_lib/mu/lib/libmu_lib.rlib",
]

Optionally, if you want to use locally built versions of mu_macro and mu_lib, add the following to your rustflags:

“–extern”, “mu_macro=/path/to/libmu_macro.so”, “–extern”, “mu_lib=/path/to/libmu_lib.rlib”,

⚠️ Use --extern only if using locally built mu_macro or mu_lib directly. If using crates from crates.io, add them to Cargo.toml instead:

[dependencies]
mu_macro = ">=0.1.2" // specify the version you want
mu_lib = ">=0.1.6" // specify the version you want

§2.2 Using Direct Build Command or CMake Integration

Instead of using .cargo/config.toml, you can directly set all necessary environment variables in the build command:

§Direct shell command:

RUSTC=${rustc_path} \
RUSTFLAGS="-C link-args=-L${mu_llvm_path}/picolibc-rv/newlib \
           -C link-args=-L${mu_llvm_path}/builtins-rv -lclang_rt.builtins-riscv64 \
           -C link-args=-T${mu_lib_path}/script/mu_linker.ld \
           -C link-args=-lmu_std -L${mu_lib_path}/lib \
           -C target-feature=+xmetis \
           # --extern mu_macro=${mu_lib_path}/lib/libmu_macro.so \ # this is also an option
           # --extern mu_lib=${mu_lib_path}/lib/libmu_lib.rlib" \ # this is also an option
CARGO_TARGET_RISCV64IMFDXMETIS_UNKNOWN_NONE_ELF_LINKER=${mu_llvm_path}/bin/ld.lld \
cargo build --release --target=riscv64imfdxmetis-unknown-none-elf

Make sure to update all paths (rustc, linker, libraries, etc.) according to your environment.

Note: The --extern flags for mu_macro and mu_lib are optional.
Use them only if you are linking to locally built versions.
If you are using published crates from crates.io, declare them in Cargo.toml instead.

§CMake integration:

cmake_minimum_required(VERSION 3.11)
project(sort_kernel_rs)

set(rust_flags "-C link-args=-L${MU_LLVM_PATH}/picolibc-rv/newlib \
                -C link-args=-L${MU_LLVM_PATH}/builtins-rv -lclang_rt.builtins-riscv64 \
                -C link-args=-T${MU_LIB_PATH}/script/mu_linker.ld \
                -C link-args=-lmu_std -L${MU_LIB_PATH}/lib \
                -C target-feature=+xmetis \
                --extern mu_macro=${MU_LIB_PATH}/lib/libmu_macro.so \
                --extern mu_lib=${MU_LIB_PATH}/lib/libmu_lib.rlib")

add_custom_target(${PROJECT_NAME} ALL
    COMMAND ${CMAKE_COMMAND} -E env /bin/bash -l -c "cargo clean"
    COMMAND ${CMAKE_COMMAND} -E env
        RUSTC=${RUSTC_PATH}
        RUSTFLAGS=${rust_flags}
        CARGO_TARGET_RISCV64IMFDXMETIS_UNKNOWN_NONE_ELF_LINKER=${MU_LLVM_PATH}/bin/ld.lld
        /bin/bash -l -c "cargo build --release --target=riscv64imfdxmetis-unknown-none-elf"
    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
)

§3. Kernel Code Example

#![no_main]

extern crate mu_macro;
use mu_macro::mu_kernel;

extern crate mu_lib;
use mu_lib::{host_println, uart_println};

#[mu_kernel]
pub fn print_test_kernel(i: i32) {
    uart_println!("uart_println i = {}, i + 1 = {}, i + 2 = {}", i, i + 1, i + 2);
    host_println!("host_println i = {}, i + 1 = {}, i + 2 = {}", i, i + 1, i + 2);
}

§4. Building the Kernel

cargo build --release
# or
cargo build

The resulting binary will be located at:

target/riscv64imfdxmetis-unknown-none-elf/release/myMuKernel

Rename it to myMuKernel.mubin and provide it to your host-side loader or simulator.

§Safety

This library contains unsafe code that interfaces with the system. While the Rust interface provides safe abstractions, users should be aware of the underlying system requirements and constraints.

Modules§

assert: Assertion module providing condition checking functionality
atomic: Atomic operations module providing thread-safe operations
clock: Clock module providing system clock functionality
logger: Logger module providing logging functionality
message: Message handling module providing synchronous and asynchronous message operations
print: Print module providing output functionality
task: Task module providing task management functionality

Macros§

host_print: Macro for printing a single string to the host
host_println: Macro for printing a single string to the host followed by a newline
log_print: Macro for logging output
log_print_with_level: Macro for logging output with a specified level
uart_print: Macro for printing a single string to UART
uart_println: Macro for printing a single string to UART followed by a newline

Crate mu_libCopy item path