doc: update ffi design

2026-08-17 22:04:56 +08:00
parent b9e9039c83
commit da56800265
2 changed files with 212 additions and 22 deletions
@@ -5,7 +5,7 @@
 When writing FFI, we require you to develop with two projects using the Rust workspace mechanism. For example:

 - An ordinary Rust library project named `foobar`. In this project you write your library logic in a pure Rust way.
- An FFI-specific library project named `foobar-ffi` (the name is not mandatory). This project references `foobar` within the workspace, writes the relevant code according to this design, wraps `foobar` into a form suitable for FFI export, and finally exports it in FFI form.
+- An FFI-specific library project named `foobar-ffi` (the name does not have to be exactly this; you may choose any name that fits your need). This project references `foobar` within the workspace, writes the relevant code according to this design, wraps `foobar` into a form suitable for FFI export, and finally exports it in FFI form.

 ## Panic Policy

@@ -28,3 +28,26 @@ The build artifact of the FFI project should meet the requirements of the C lang
 [lib]
 crate-type = ["cdylib"]
 ```
+
+## Module Organization
+
+In the FFI project, do not try to pile everything into `lib.rs`. You need to make reasonable use of the Rust module mechanism. For example:
+
+- When combining multiple Rust types to create an opaque struct dedicated to FFI, you can write it in a module named like `wrapper` (the name does not have to be exactly this; you may choose any name that fits your need).
+- When re-wrapping Rust types, you can write it in a module named like `ffi_types` (the name does not have to be exactly this; you may choose any name that fits your need).
+
+`lib.rs` should contain only the following:
+
+- User-defined error types, `Result` types, `CError` constants and so on.
+- The constants and types to export, including those defined directly with `pub type` and `pub const`, and those defined indirectly with `pub use` from other modules.
+- All the FFI functions to export.
+
+The re-wrapped contents can be written in a separate module `wrapper.rs`. `lib.rs` only contains the error definitions, the types to export, the constants and the functions.
+
+## Dependency Specification
+
+When adding `sarasacw-omrf` to the dependencies of the FFI project, we require specifying it as a git repository, supplemented with a tag and the `version` field, to ensure the version is correct. As shown below:
+
+```toml
+sarasacw-omrf = { version="1.0.0", git = "https://github.com/SarasasChipWorkshop/sarasacw-omrf.git", tag = "omrf/1.0.0" }
+```