From 9a6e750a1d53e0f69d3139c200961dbe2d0ff97f Mon Sep 17 00:00:00 2001 From: Cool Man Date: Tue, 19 Aug 2025 04:13:49 +0200 Subject: [PATCH 1/2] Update readme --- README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 118 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 667ff8c..0bfac25 100644 --- a/README.md +++ b/README.md @@ -4,24 +4,134 @@ Rust bindings for the [Rockchip RKNN API (rknpu2)](https://github.com/airockchip > These bindings do **not** require redistributing the C headers from the Rockchip rknpu2 SDK. The sys crate contains bindgen bindings, but bindgen is not part of the build process. +## Overview + +This crate provides safe, idiomatic Rust abstractions over the Rockchip RKNN runtime API, enabling efficient deployment and inference of deep learning models on Rockchip NPU hardware. It's designed for production use in embedded systems, IoT devices, and edge computing applications where Rockchip NPUs are deployed. + ## Requirements -- Rockchip NPU compatible with librknnrt or librknnmrt libraries. +- Rockchip NPU compatible with `librknnrt` or `librknnmrt` libraries +- Rust 1.70+ +- Linux environment (primary target) +- Supported NPU families: RK35xx, RK3576, and others compatible with RKNN API v2.3.2 ## Features -- Safe and idiomatic Rust abstractions over the `librknnrt.so` C API -- Support for loading models, setting inputs, running inference, and reading outputs -- There will be Zero-copy input/output buffer support -- Includes both low-level `-sys` bindings and higher-level wrappers -- Based on the **rknpu2 SDK v2.3.2** +- **Safe Rust Abstractions**: Memory-safe wrappers around the C API with proper error handling +- **Model Management**: Load, query, and manage RKNN models with type-safe interfaces +- **Inference Pipeline**: Set inputs, run inference, and retrieve outputs with zero-copy buffer support +- **Hardware Optimization**: Configure NPU core usage and batch processing for optimal performance +- **Flexible API Loading**: Choose between linked and runtime-loaded RKNN libraries +- **Comprehensive Querying**: Access model metadata, tensor attributes, and performance information +- **Multi-format Support**: Handle various tensor formats (NCHW, NHWC) and data types +- **Production Ready**: Based on the stable **rknpu2 SDK v2.3.2** + +## Installation + +Add to your `Cargo.toml`: + +```toml +[dependencies] +rknpu2 = { version = "0.1", features = ["rk35xx"] } + +# For runtime library loading (optional) +rknpu2 = { version = "0.1", features = ["rk35xx", "libloading"] } + +# For RK3576 specific features +rknpu2 = { version = "0.1", features = ["rk3576"] } +``` + +## API Overview + +### Core Types + +- **`RKNN`**: Main struct for model management and inference +- **`Input`**: Represents model input tensors with various data types and formats +- **`Output`**: Handles model output retrieval with flexible buffer management +- **`Query`**: Trait for querying model metadata and attributes + +### Key Methods + +- **`RKNN::new()`**: Create RKNN context from model data +- **`set_inputs()`**: Configure model inputs before inference +- **`run()`**: Execute model inference +- **`get_outputs()`**: Retrieve inference results +- **`query()`**: Get model information and attributes + +### Supported Data Types + +- **Input**: `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `f16`, `f32` +- **Output**: `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `f16`, `f32` +- **Tensor Formats**: NCHW, NHWC, NC1HWC2 + +## Examples + +The crate includes several examples demonstrating different use cases: + +- **MobileNet Classification**: Complete image classification pipeline +- **Model Querying**: How to inspect model properties and performance +- **Custom Input/Output**: Advanced buffer management techniques + +Run examples with: + +```bash +# Basic MobileNet example +cargo run --example mobilenet --features rk35xx + +# With runtime library loading +cargo run --example mobilenet --features "rk35xx,libloading" +``` + +## Performance Considerations + +- **Zero-copy Buffers**: Use preallocated buffers when possible for optimal performance +- **Core Selection**: Configure appropriate NPU cores based on your workload +- **Batch Processing**: Leverage batch inference for multiple inputs +- **Memory Management**: Reuse input/output buffers across inference calls + +## Troubleshooting + +### Common Issues + +1. **Library Not Found**: Ensure `librknnrt.so` is in your library path +2. **Feature Flags**: Verify you're using the correct feature flags for your NPU +3. **Model Format**: Ensure your model is in the correct RKNN format +4. **Memory Alignment**: Check that input/output buffers meet alignment requirements + +## Contributing + +Contributions are welcome! Please see our contributing guidelines for: + +- Code style and formatting +- Testing requirements +- Documentation standards +- Feature request process + +## License + +This project is licensed under either of: + +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) +- MIT License ([LICENSE-MIT](LICENSE-MIT)) + +at your option. ## Version Compatibility These bindings are aligned with the **2.3.2** release of the RKNN API. [rknn C API v2.3.2 PDF](https://github.com/airockchip/rknn-toolkit2/blob/42aa1d426c0a9e0869b6374edba009f7208a1926/doc/04_Rockchip_RKNPU_API_Reference_RKNNRT_V2.3.2_EN.pdf) +## Related Projects + +- [rknpu2-sys](crates/rknpu2-sys/): Low-level FFI bindings +- [rktensor](crates/rktensor/): Tensor operations and utilities +- [RKNN Toolkit2](https://github.com/airockchip/rknn-toolkit2): Official Python toolkit + +## Support -## Usage +For issues and questions: -Coming soon! +- Check the [examples](crates/rknpu2/examples/) directory +- Review the [API documentation](https://docs.rs/rknpu2) +- Open an issue on GitHub +- Consult the [RKNN API reference](https://github.com/airockchip/rknn-toolkit2) From bb814b0ef2e6193722dde62e284fd12c1cb0a439 Mon Sep 17 00:00:00 2001 From: Cool Man Date: Tue, 19 Aug 2025 05:04:33 +0200 Subject: [PATCH 2/2] Resolve conflict --- README.md | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 0bfac25..3bf6797 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# rknpu2-rs +# RKNN -Rust bindings for the [Rockchip RKNN API (rknpu2)](https://github.com/airockchip/rknn-toolkit2), targeting deployment of deep learning models on Rockchip NPUs. +Rust bindings for the Rockchip RKNN Runtime API (librknnrt.so), enabling deployment of deep learning models on Rockchip NPUs. This library is a key component of the rknpu2 SDK, providing efficient integration between Rust applications and Rockchip's neural processing unit for optimized AI model execution. > These bindings do **not** require redistributing the C headers from the Rockchip rknpu2 SDK. The sys crate contains bindgen bindings, but bindgen is not part of the build process. @@ -11,7 +11,7 @@ This crate provides safe, idiomatic Rust abstractions over the Rockchip RKNN run ## Requirements - Rockchip NPU compatible with `librknnrt` or `librknnmrt` libraries -- Rust 1.70+ +- Rust 1.70+ (edition 2021) - Linux environment (primary target) - Supported NPU families: RK35xx, RK3576, and others compatible with RKNN API v2.3.2 @@ -25,6 +25,17 @@ This crate provides safe, idiomatic Rust abstractions over the Rockchip RKNN run - **Comprehensive Querying**: Access model metadata, tensor attributes, and performance information - **Multi-format Support**: Handle various tensor formats (NCHW, NHWC) and data types - **Production Ready**: Based on the stable **rknpu2 SDK v2.3.2** +- **Comprehensive Error Handling**: Custom error types with detailed error information +- **Memory-safe Operations**: Safe tensor operations and buffer management + +## Project Structure + +``` +crates/ +├── rknpu2/ # High-level Rust API wrapper +├── rknpu2-sys/ # Low-level FFI bindings +└── rktensor/ # Tensor operations and utilities +``` ## Installation @@ -98,6 +109,10 @@ cargo run --example mobilenet --features "rk35xx,libloading" 3. **Model Format**: Ensure your model is in the correct RKNN format 4. **Memory Alignment**: Check that input/output buffers meet alignment requirements +## Development Status + +This project is actively maintained and follows Rust best practices. Contributions are welcome! + ## Contributing Contributions are welcome! Please see our contributing guidelines for: @@ -107,20 +122,6 @@ Contributions are welcome! Please see our contributing guidelines for: - Documentation standards - Feature request process -## License - -This project is licensed under either of: - -- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) -- MIT License ([LICENSE-MIT](LICENSE-MIT)) - -at your option. - -## Version Compatibility - -These bindings are aligned with the **2.3.2** release of the RKNN API. -[rknn C API v2.3.2 PDF](https://github.com/airockchip/rknn-toolkit2/blob/42aa1d426c0a9e0869b6374edba009f7208a1926/doc/04_Rockchip_RKNPU_API_Reference_RKNNRT_V2.3.2_EN.pdf) - ## Related Projects - [rknpu2-sys](crates/rknpu2-sys/): Low-level FFI bindings @@ -135,3 +136,12 @@ For issues and questions: - Review the [API documentation](https://docs.rs/rknpu2) - Open an issue on GitHub - Consult the [RKNN API reference](https://github.com/airockchip/rknn-toolkit2) + +## License + +This project is licensed under either of: + +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) +- MIT License ([LICENSE-MIT](LICENSE-MIT)) + +at your option.