From 85a9579626ff3741c86cb977042e714480a46516 Mon Sep 17 00:00:00 2001 From: bunnie Date: Fri, 20 Feb 2026 23:52:42 +0800 Subject: [PATCH] update readme with toolflow and erratum --- libs/bio-lib/README.md | 44 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/libs/bio-lib/README.md b/libs/bio-lib/README.md index 2cef09560..4c19e2dee 100644 --- a/libs/bio-lib/README.md +++ b/libs/bio-lib/README.md @@ -71,6 +71,50 @@ level flags, configured by the host; writes to bits [31:24] are ignored. Core ID & debug: - x31 r/- [31:30] -> core ID; [29:0] -> cpu clocks since reset +### Building from C + +The BIO now supports a C-to-BIO code flow. It relies on the Zig C toolchain, +installable via Python. + +The intended flow is for developers to write their BIO modules in C, and translate +these into a Rust macro that is then incorporated into the `bio-lib` ecosystem. +Thus, we adopt the following policy assumptions: + +- The resulting Rust macro is checked into `xous-core` as the buildable artifact by most users +- Only developers looking to modify or create C code need to install the Zig toolchain +- It's assumed that you have Python 3.8 or later and a system that can support Zig's prerequisites + +#### Installing Zig + +To install Zig, on most systems you will need to run a command similar to: + +`python3 -m pip install ziglang` + +The scripts were tested against zig version 0.15.2. It's noted that the API has been changing rapidly +on Zig, so if the script isn't working for you try installing the specific version referenced here. +The build script was tested on Linux and Windows, but with the significant caveat that it does +not seem to work under WSL1 due to some filesystem APIs it relies upon that are not supported +by WSL1. + +#### Building Rust assembly from C + +- `cd libs/bio-lib/src/c` +- `zig build -Dmodule=` or `python3 -m ziglang build "-Dmodule="`, depending on your zig install method + +The above script will automatically scan for the C source, compile it into a clang assembly intermediate, +then translate it into a Rust assembly macro file, along with applying any erratum patches as needed. + +You can also run the clang-to-rust converter stand-alone with `python3 .\clang2rustasm.py ` + +#### Conventions + +- A collection of useful header files are kept in `include` +- Each BIO C-library is contained in a directory inside `src/c` +- The `mod.rs` file inside the `src/c/` contains all the Rust code to make the BIO program callable +- `main.c` contains the C code +- `.rs` is the Rust macro assembly - it is autogenerated +- Adding a new module requires adding the directory to the `mod.rs` inside `src/c` + ### ERRATUM BUG 1: ("phantom rs1"): For lui/auipc/jal (U&J type instructions),