doc: update ffi design

2026-08-11 23:08:24 +08:00
parent d7e564d666
commit 38b64a1092
2 changed files with 22 additions and 0 deletions
@@ -1 +1,17 @@
 # C/C++ Side
+
+This chapter introduces some things you need to know before writing the C/C++ side files of a C-friendly FFI.
+
+## Header File Structure
+
+Writing the C/C++ side of a C-friendly FFI requires two kinds of header files: the C headers and the C++ headers. Each kind may contain any number of individual header files.
+
+The C headers are a simple wrapper around the FFI surface. They must be loadable correctly in both C and C++ translation units.
+
+It is important that the C++ headers are wrappers around the C headers, not rewrites of them from scratch. The C++ headers build on top of the declarations already provided by the C headers and only add the C++ conveniences.
+
+## Language Standards
+
+The C headers target the C11 language standard.
+
+The C++ headers target the C++17 language standard.
@@ -1,4 +1,10 @@
 # Rust Side

+This chapter introduces some things you need to know before designing the Rust side of a C-friendly FFI.

+## Preliminary
+
+The design described in this document is intended to be used together with the `sarasacw-omrf` crate that is bundled with this repository. It is possible to write FFI code following this design without that crate, but you will lose most of the benefit, so we strongly recommend adding `sarasacw-omrf` as a dependency of your Rust project for the best experience.
+
+Throughout this document we may reference macros, functions and structs that belong to the `sarasacw-omrf` crate, such as `cffi_wrapper!` and `ObjectPool`. We do not explain how to use these items here. Please consult their docstrings for the exact usage, signatures and semantics; that information is kept in the crate itself so that it stays accurate as the crate evolves.