From 0f31d8e5e933b57a4ec5aaf02a6d14d301da2129 Mon Sep 17 00:00:00 2001 From: felix91gr <11747623+felix91gr@users.noreply.github.com> Date: Wed, 19 Nov 2025 16:49:02 +0000 Subject: [PATCH 1/2] Add guideline for issue #137 Co-authored-by: darkwisebear --- src/coding-guidelines/ffi.rst | 84 +++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/src/coding-guidelines/ffi.rst b/src/coding-guidelines/ffi.rst index fc48d03b..8091197e 100644 --- a/src/coding-guidelines/ffi.rst +++ b/src/coding-guidelines/ffi.rst @@ -6,3 +6,87 @@ FFI === + +.. guideline:: Use matching type declarations at the language boundary + :id: gui_QmEmKMYSuQSl + :category: required + :status: draft + :release: 1.0.0-latest + :fls: fls_v24ino4hix3m + :decidability: decidable + :scope: crate + :tags: undefined-behavior,reduce-human-error + + If it is required or advisable (e.g. to provide a "rusty" interface) to use different types on the Rust side than on the foreign function side, the respective type changes shall not be done on the FFI boundary but on an additional layer above the FFI level. + + .. rationale:: + :id: rat_LnIHMWRaC19F + :status: draft + + If the languages on the FFI boundary to not agree on the type or its layout, size and alignment properties, undefined behavior might be invoked. It is therefore critical to reduce the possibility of such misalignment to an absolute minimum. Developers and/or tools shall therefore follow a set of strict rules that govern how a foreign type definition shall be translated to Rust. + + Since the only ubiquitously supported foreign calling ABI is the calling ABI of the C programming language, this rule will state how C types are to be translated. For any other language or ABI, it is required to document the respective translation rules. + + It is recommended that tooling is used to automate the generation of matching declarations where possible. If this is not possible (e.g. due to the pre-existence of code), it is recommended to set up tooling that is able to check the consistency of the type declarations. + + .. non_compliant_example:: + :id: non_compl_ex_9uNGhTr1I20O + :status: draft + + The example shows the import of a single function from C which populates a given out parameter with data about a file. Looking at both type definitions of the second parameter, we can see that types are used which might or might not match, depending on the used platform triple and the definition of size_t. While the resulting program might run perfectly well on your favorite 64 bit host platform, other platforms like a 16 bit embedded platform will most likely fail. + + .. code-block:: rust + + /* C side */ + typedef struct __file_info { + size_t size; + int epoch_time; + } file_info; + + int get_name_size(const char* path, file_info* info_out) { ... } + ``` + + ```rust + // Rust side + use std::ffi; + + #[repr(C)] + struct FileInfo { + size: i64, + epoch_time: i32, + } + + unsafe extern "C" { + fn get_name_size(path: *const ffi::c_char, file_info: *mut FileInfo) -> std::ffi::c_int; + } + + .. compliant_example:: + :id: compl_ex_TPV54bWJEmft + :status: draft + + By picking matching types for the Rust ``extern`` declaration, we ensure the usage of a type that is understood in the same way on both the Rust and the C side. The type to choose is unambiguous - for each type on C side, it is exactly specified which basic type or compound type to use on Rust side. + + .. code-block:: rust + + /* C side */ + typedef struct __file_info { + size_t size; + int epoch_time; + } file_info; + + int get_name_size(const char* path, file_info* info_out) { ... } + ``` + + ```rust + // Rust side + use std::ffi; + + #[repr(C)] + struct FileInfo { + size: libc::size_t, + epoch_time: std::ffi::c_int, + } + + unsafe extern "C" { + fn get_name_size(path: *const ffi::c_char, file_info: *mut FileInfo) -> std::ffi::c_int; + } From dc5442e47153059c50bab98baf8e2fe85c601e26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Eris=20Celeste=20n=C3=A9e=20Gilding?= Date: Wed, 3 Dec 2025 01:01:18 +0000 Subject: [PATCH 2/2] typo fix --- src/coding-guidelines/ffi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/coding-guidelines/ffi.rst b/src/coding-guidelines/ffi.rst index 8091197e..38540fab 100644 --- a/src/coding-guidelines/ffi.rst +++ b/src/coding-guidelines/ffi.rst @@ -23,7 +23,7 @@ FFI :id: rat_LnIHMWRaC19F :status: draft - If the languages on the FFI boundary to not agree on the type or its layout, size and alignment properties, undefined behavior might be invoked. It is therefore critical to reduce the possibility of such misalignment to an absolute minimum. Developers and/or tools shall therefore follow a set of strict rules that govern how a foreign type definition shall be translated to Rust. + If the languages on the FFI boundary do not agree on the type or its layout, size and alignment properties, undefined behavior might be invoked. It is therefore critical to reduce the possibility of such misalignment to an absolute minimum. Developers and/or tools shall therefore follow a set of strict rules that govern how a foreign type definition shall be translated to Rust. Since the only ubiquitously supported foreign calling ABI is the calling ABI of the C programming language, this rule will state how C types are to be translated. For any other language or ABI, it is required to document the respective translation rules.