update readme with toolflow and erratum

This commit is contained in:
bunnie 2026-02-20 23:52:42 +08:00
parent 9e34da0bf7
commit 85a9579626

View file

@ -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=<program>` or `python3 -m ziglang build "-Dmodule=<program>"`, 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 <program>`
#### 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/<program>` contains all the Rust code to make the BIO program callable
- `main.c` contains the C code
- `<program>.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),