Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lupyuen/bl602-rust-wrapper
Rust Wrapper for BL602 IoT SDK
https://github.com/lupyuen/bl602-rust-wrapper
bl602 bl604 macro riscv riscv32 rust
Last synced: 3 months ago
JSON representation
Rust Wrapper for BL602 IoT SDK
- Host: GitHub
- URL: https://github.com/lupyuen/bl602-rust-wrapper
- Owner: lupyuen
- License: apache-2.0
- Created: 2021-04-21T14:52:14.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2021-07-31T06:10:45.000Z (over 3 years ago)
- Last Synced: 2024-11-07T12:49:02.497Z (3 months ago)
- Topics: bl602, bl604, macro, riscv, riscv32, rust
- Language: Rust
- Homepage: https://lupyuen.github.io/articles/adc
- Size: 5.76 MB
- Stars: 16
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Rust Wrapper for BL602 IoT SDK
Read the article and docs...
- ["Rust on RISC-V BL602: Is It Sunny?"](https://lupyuen.github.io/articles/adc)
- ["Run Rust RISC-V Firmware with BL602 IoT SDK"](https://lupyuen.github.io/articles/rust)
- [Rust Docs](https://lupyuen.github.io/bl602-rust-wrapper/)
- [Rust Crate `bl602-sdk`](https://crates.io/crates/bl602-sdk)
- [Rust Crate `bl602-macros`](https://crates.io/crates/bl602-macros)
- [Check this Twitter Thread for updates](https://twitter.com/MisterTechBlog/status/1416608940876435462)
## Usage
Here's how we call the Rust Wrapper for BL602 GPIO HAL in our BL602 Rust Firmware...
```rust
use bl602_sdk::gpio;
...
// Configure the LED GPIO for output (instead of input)
gpio::enable_output(LED_GPIO, 0, 0) // No pullup, no pulldown
.expect("GPIO enable output failed"); // Halt on error
// Blink the LED 5 times
for i in 0..10 { // Iterates 10 times from 0 to 9 (`..` excludes 10)
// Toggle the LED GPIO between 0 (on) and 1 (off)
gpio::output_set( // Set the GPIO output (from BL602 GPIO HAL)
LED_GPIO, // GPIO pin number
i % 2 // 0 for low, 1 for high
).expect("GPIO output failed"); // Halt on error
```
[From `sdk_app_rust_gpio/rust/src/lib.rs`](https://github.com/lupyuen/bl_iot_sdk/blob/adc/customer_app/sdk_app_rust_gpio/rust/src/lib.rs)
Build the BL602 Firmware with the [`run.sh` script](https://github.com/lupyuen/bl_iot_sdk/blob/adc/customer_app/sdk_app_rust_gpio/run.sh)
## Generate Rust Wrapper
To generate the Rust Wrapper...
```bash
# Install bindgen and clang: https://rust-lang.github.io/rust-bindgen/requirements.html
cargo install bindgen
sudo apt install llvm-dev libclang-dev clang
# Download the source code
git clone --recursive https://github.com/lupyuen/bl602-rust-wrapper
git clone --recursive https://github.com/lupyuen/bl_iot_sdk
# Generate the Rust Bindings for BL602 IoT SDK
cd bl602-rust-wrapper
scripts/gen-bindings.sh
# Build the docs and the test project
scripts/build.sh
```
## How It Works
This script...
- [`scripts/gen-bindings.sh`](scripts/gen-bindings.sh)
Reads the BL602 IoT SDK Header Files...
```c
// Function Declarations from BL602 IoT SDK (GPIO HAL)
// https://github.com/lupyuen/bl_iot_sdk/blob/master/components/hal_drv/bl602_hal/bl_gpio.h
int bl_gpio_enable_output(uint8_t pin, uint8_t pullup, uint8_t pulldown);
int bl_gpio_output_set(uint8_t pin, uint8_t value);
```
And auto-generates the Rust Bindings...
- [`bl602-sdk/src/gpio.rs`](bl602-sdk/src/gpio.rs)
- [`bl602-sdk/src/i2c.rs`](bl602-sdk/src/i2c.rs)
- [`bl602-sdk/src/pwm.rs`](bl602-sdk/src/pwm.rs)
- [`bl602-sdk/src/spi.rs`](bl602-sdk/src/spi.rs)
- [More Bindings](bl602-sdk/src)
```rust
// Rust Bindings for BL602 GPIO generated by gen-bindings.sh
#[safe_wrap(_)] extern "C" {
pub fn bl_gpio_enable_output(pin: u8, pullup: u8, pulldown: u8) -> ::cty::c_int;
}
#[safe_wrap(_)] extern "C" {
pub fn bl_gpio_output_set(pin: u8, value: u8) -> ::cty::c_int;
}
```
Which call the `safe_wrap` Procedural Macro...
- [`bl602-macros/src/safe_wrap.rs`](bl602-macros/src/safe_wrap.rs)
To produce the Rust Wrapper for BL602 IoT SDK...
- [Expanded `safe_wrap` macros: `logs/sdk-expanded.rs`](logs/sdk-expanded.rs)
```rust
// Expanded version of `safe_wrap` macros for the GPIO Rust Bindings
#[doc = "Configure a GPIO Pin for Output Mode. See `bl_gpio_enable_output` in \"Enable GPIO\" "]
pub fn enable_output(pin: u8, pullup: u8, pulldown: u8)
-> BlResult<()> {
"----------Extern Decl----------";
extern "C" {
pub fn bl_gpio_enable_output(pin: u8, pullup: u8, pulldown: u8)
-> ::cty::c_int;
}
"----------Validation----------";
unsafe {
"----------Call----------";
let res =
bl_gpio_enable_output(pin as u8, pullup as u8,
pulldown as u8);
"----------Result----------";
match res { 0 => Ok(()), _ => Err(BlError::from(res)), }
}
}
#[doc = "Set output value of GPIO Pin. See `bl_gpio_output_set` in \"Read and Write GPIO\" "]
pub fn output_set(pin: u8, value: u8) -> BlResult<()> {
"----------Extern Decl----------";
extern "C" {
pub fn bl_gpio_output_set(pin: u8, value: u8)
-> ::cty::c_int;
}
"----------Validation----------";
unsafe {
"----------Call----------";
let res = bl_gpio_output_set(pin as u8, value as u8);
"----------Result----------";
match res { 0 => Ok(()), _ => Err(BlError::from(res)), }
}
}
```
Links to ["The RISC-V BL602 Book"](https://lupyuen.github.io/articles/book) are defined here...
- [`bl602-sdk/doclinks.md`](bl602-sdk/doclinks.md)
## Build Log
Build the docs and the test project with this script...
- [`scripts/build.sh`](scripts/build.sh)
```text
+ export RUST_BACKTRACE=1
+ RUST_BACKTRACE=1
+ rust_build_options=' --target riscv32imacf-unknown-none-elf.json -Z build-std=core '
+ pushd bl602-macros
/mnt/c/pinecone/bl602-rust-wrapper/bl602-macros /mnt/c/pinecone/bl602-rust-wrapper
+ cargo build
Compiling proc-macro2 v1.0.27
Compiling unicode-xid v0.2.2
Compiling memchr v2.4.0
Compiling syn v1.0.73
Compiling cty v0.2.1
Compiling rustc-serialize v0.3.24
Compiling lazy_static v1.4.0
Compiling cstr_core v0.2.4
Compiling quote v1.0.9
Compiling bl602-macros v0.0.2 (/mnt/c/pinecone/bl602-rust-wrapper/bl602-macros)
Finished dev [unoptimized + debuginfo] target(s) in 50.67s
+ popd
/mnt/c/pinecone/bl602-rust-wrapper
+ cp bl602-sdk/doclinks.md .
+ pushd bl602-sdk
/mnt/c/pinecone/bl602-rust-wrapper/bl602-sdk /mnt/c/pinecone/bl602-rust-wrapper
+ cargo rustc --target riscv32imacf-unknown-none-elf.json -Z build-std=core -- -Z unstable-options --pretty expanded
Compiling compiler_builtins v0.1.47
Compiling core v0.0.0 (/home/user/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core)
Compiling heapless v0.7.3
Compiling rustc-std-workspace-core v1.99.0 (/home/user/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/rustc-std-workspace-core)
Compiling byteorder v1.4.3
Compiling stable_deref_trait v1.2.0
Compiling cty v0.2.1
Compiling hash32 v0.2.1
Compiling bl602-sdk v0.0.6 (/mnt/c/pinecone/bl602-rust-wrapper/bl602-sdk)
Finished dev [unoptimized + debuginfo] target(s) in 33.50s
+ cargo build --target riscv32imacf-unknown-none-elf.json -Z build-std=core
Compiling bl602-sdk v0.0.6 (/mnt/c/pinecone/bl602-rust-wrapper/bl602-sdk)
Finished dev [unoptimized + debuginfo] target(s) in 7.85s
+ cargo doc --target riscv32imacf-unknown-none-elf.json -Z build-std=core
Checking unicode-xid v0.2.2
Documenting unicode-xid v0.2.2
Checking cty v0.2.1
Documenting cty v0.2.1
Checking lazy_static v1.4.0
Documenting rustc-serialize v0.3.24
Checking rustc-serialize v0.3.24
Documenting lazy_static v1.4.0
Checking memchr v2.4.0
Documenting memchr v2.4.0
Checking proc-macro2 v1.0.27
Checking byteorder v1.4.3
Documenting byteorder v1.4.3
Checking stable_deref_trait v1.2.0
Documenting stable_deref_trait v1.2.0
Checking cstr_core v0.2.4
Documenting proc-macro2 v1.0.27
Checking quote v1.0.9
Documenting cstr_core v0.2.4
Checking hash32 v0.2.1
Checking syn v1.0.73
Checking heapless v0.7.3
Documenting hash32 v0.2.1
Documenting quote v1.0.9
Documenting heapless v0.7.3
Documenting syn v1.0.73
Documenting bl602-macros v0.0.2 (/mnt/c/pinecone/bl602-rust-wrapper/bl602-macros)
Documenting bl602-sdk v0.0.6 (/mnt/c/pinecone/bl602-rust-wrapper/bl602-sdk)
Finished dev [unoptimized + debuginfo] target(s) in 48.79s
+ popd
/mnt/c/pinecone/bl602-rust-wrapper
+ echo 'Moved to [`bl602-sdk/doclinks.md`](bl602-sdk/doclinks.md)'
+ cp -r target/riscv32imacf-unknown-none-elf/doc/bl602_sdk docs
+ cp -r target/riscv32imacf-unknown-none-elf/doc/src docs
```