Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions ffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,6 @@
- In `exclude` and `rename`, a path that a field shares with a method or constant of its
type, such as `Backoff::initial`, names only the method, as in rustdoc. Name the field
`field@Backoff::initial`: an `exclude` that left out both now needs both entries.
- Every export defines `<prefix>_contract` and `<PREFIX>_CONTRACT`, so an exported item
that the naming rule names either, such as a crate root's `pub fn contract` or
`pub const CONTRACT`, clashes with them: give it another name with a `rename`.
4 changes: 4 additions & 0 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,10 @@ refused, and the census counts why.
- **Callbacks** are a struct of a table and its data. Rust calls `free` once it drops the
implementation, and may call the others from any thread. A callback takes scalars and
buffers lent for the call, and returns a scalar.
- **The contract** is a hash of the header's declarations, its docs included: the header
defines it as `<PREFIX>_CONTRACT`, and `<prefix>_contract()` returns it from the library
built with the header. A binding checks the two match before any other call, so a header
and a library from different builds refuse to mix.
- **Panics** abort, as an `extern "C"` function's do.
- **Names** are the prefix, then the item's path from its crate's root, each segment in
snake case, joined by `_`: `track::Producer::append_group` is
Expand Down
1 change: 1 addition & 0 deletions ffi/moq/moq.c
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ static void wake(void *data) {
int main(void) {
moq_waker waker = {.wake = wake};
moq_error *err = NULL;
CHECK(moq_contract() == MOQ_CONTRACT);

moq_broadcast_info *info = moq_broadcast_info_new();
moq_broadcast_producer *broadcast = moq_broadcast_info_produce(info);
Expand Down
4 changes: 2 additions & 2 deletions ffi/src/abi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -401,10 +401,10 @@ impl<'a> Abi<'a> {
.map(|r| r.span)
.or_else(|| api.objects.first().map(|o| o.span))
.unwrap_or(rustc_span::DUMMY_SP);
for runtime in ["buf", "buf_free", "duration", "waker", "poll"] {
for runtime in ["contract", "buf", "buf_free", "duration", "waker", "poll"] {
self.claim(self.rt(runtime), "the runtime".to_string(), crate_span);
}
for constant in ["POLL_PENDING", "POLL_READY", "POLL_ERROR"] {
for constant in ["CONTRACT", "POLL_PENDING", "POLL_READY", "POLL_ERROR"] {
Comment thread
kixelated marked this conversation as resolved.
Resolved
let name = format!("{}_{constant}", self.prefix.to_uppercase());
self.claim(name, "the runtime".to_string(), crate_span);
}
Expand Down
44 changes: 30 additions & 14 deletions ffi/src/c.rs
Original file line number Diff line number Diff line change
@@ -1,19 +1,43 @@
//! The C header: the declarations of everything [`crate::glue`] defines.

use std::collections::BTreeSet;
use std::hash::Hasher;

use rustc_data_structures::stable_hash::StableHasher;

use crate::abi::{self, Abi, Sig, Ty};
use crate::ir::{Function, Int, Literal, Receiver, Traits, Type};

/// The header for `abi`, as `<prefix>.h`.
pub fn header(abi: &Abi<'_>, packages: &str) -> String {
/// The header for `abi`, as `<prefix>.h`, and its contract: a hash of what it declares,
/// which the library returns from `<prefix>_contract`.
pub fn header(abi: &Abi<'_>, packages: &str) -> (String, u64) {
let mut h = Header {
abi,
out: String::new(),
defined: BTreeSet::new(),
};
h.write(packages);
h.out
h.write();
// Platform independent, so a header names the same contract wherever it is generated.
let mut hasher = StableHasher::new();
hasher.write(h.out.as_bytes());
let contract = Hasher::finish(&hasher);
let p = &abi.prefix;
let upper = p.to_uppercase();
let guard = format!("{upper}_H");
let header = format!(
"/* Generated by rust2-ffi: the C ABI of the pub API of {packages}. Do not edit. */\n\n\
#ifndef {guard}\n#define {guard}\n\n\
#include <stdbool.h>\n#include <stddef.h>\n#include <stdint.h>\n\n\
#ifdef __cplusplus\nextern \"C\" {{\n#endif\n\n\
/* A hash of everything below, which {p}_contract returns from a library built with\n * this header. Check it before any other call: a header and a library that declare\n * different APIs must not mix. */\n\
#define {upper}_CONTRACT ((uint64_t)0x{contract:016x}ULL)\n\
uint64_t {p}_contract(void);\n\n\
{body}\n\
#ifdef __cplusplus\n}}\n#endif\n\n\
#endif /* {guard} */\n",
body = h.out,
);
(header, contract)
}

struct Header<'a> {
Expand Down Expand Up @@ -66,18 +90,12 @@ impl Header<'_> {
format!("{};", self.decl(&sig.ret, &format!("{}({params})", sig.name)))
}

fn write(&mut self, packages: &str) {
/// Everything the header declares but its contract.
fn write(&mut self) {
let abi = self.abi;
let api = abi.api;
let p = abi.prefix.clone();
let guard = format!("{}_H", p.to_uppercase());
let upper = p.to_uppercase();
self.line(format!(
"/* Generated by rust2-ffi: the C ABI of the pub API of {packages}. Do not edit. */\n"
));
self.line(format!("#ifndef {guard}\n#define {guard}\n"));
self.line("#include <stdbool.h>\n#include <stddef.h>\n#include <stdint.h>\n");
self.line("#ifdef __cplusplus\nextern \"C\" {\n#endif\n");
self.line(format!(
"/* Bytes. Passed in, a view Rust reads during the call and never frees. Returned,\n * an owned buffer to free once with {p}_buf_free. A null ptr is None. */\ntypedef struct {p}_buf {{\n\tconst uint8_t *ptr;\n\tsize_t len;\n\tvoid *owner;\n}} {p}_buf;\n\nvoid {p}_buf_free({p}_buf buf);\n"
));
Expand Down Expand Up @@ -237,8 +255,6 @@ impl Header<'_> {
for function in &api.functions {
self.function(function, None);
}
self.line("\n#ifdef __cplusplus\n}\n#endif\n");
self.line(format!("#endif /* {guard} */"));
}

/// A value struct, after the structs its fields hold.
Expand Down
9 changes: 8 additions & 1 deletion ffi/src/glue.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,11 @@ impl Crate<'_> {
packages = self.packages(),
lib = self.abi.prefix,
);
let header = crate::c::header(self.abi, &self.packages());
let (header, contract) = crate::c::header(self.abi, &self.packages());
let mut generator = Gen {
abi: self.abi,
packages: self.packages(),
contract,
dependencies: self.exports.iter().map(|export| dependency(&export.root())).collect(),
out: String::new(),
};
Expand All @@ -96,6 +97,8 @@ struct Gen<'a> {
abi: &'a Abi<'a>,
/// The exported packages, for the docs.
packages: String,
/// The header's contract, which `<prefix>_contract` returns.
contract: u64,
/// The name the crate depends on each export by.
dependencies: Vec<String>,
out: String,
Expand Down Expand Up @@ -330,6 +333,10 @@ impl Gen<'_> {
self.line(format!(
"#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {p}_buf_free(buf: rt::Buf) {{\n\tunsafe {{ buf.free() }}\n}}\n"
));
self.line(format!(
"#[unsafe(no_mangle)]\npub extern \"C\" fn {p}_contract() -> u64 {{\n\t0x{:016x}\n}}\n",
self.contract
));

for (name, ty) in &self.abi.ranges {
let (kind, int) = match ty {
Expand Down
4 changes: 4 additions & 0 deletions ffi/tests/api.c
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,10 @@ static int broken(const char *which) {
}

int main(int argc, char **argv) {
if (api_contract() != API_CONTRACT) {
fprintf(stderr, "api.h and the library are from different builds\n");
return 1;
}
if (argc > 1) {
return broken(argv[1]);
}
Expand Down
3 changes: 2 additions & 1 deletion quest/m1/ffi-export/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ package's place.

Every generator on the C ABI:

- checks `<prefix>_contract()` against the header's contract when it loads, before any
other call, and fails loud on a mismatch;
- is measured on the [binding benchmark](/bench/ffi/README.md);
- keeps the C ABI's bulk and zero-copy payloads, with no per-byte loop on either side;
- reports its generated size, raw and gzipped, against the fork's (Python 653 KiB, Kotlin
Expand Down Expand Up @@ -51,6 +53,5 @@ Every generator on the C ABI:
- [moq-clock's C names once it moves into kio](/quest/m1/ffi-export/crates.md) - `moq_now` and `moq_origin` become the clock's, after moq moves it into `kio::clock`
- [Sessions on moq-tokio](/quest/m1/ffi-export/session-tokio.md) - bindings connect and accept with one call, the library running moq-tokio inside
- [Sessions on sans-IO QUIC](/quest/m1/ffi-export/session-quic.md) - bindings move UDP datagrams and drive the session's poll themselves
- [A contract symbol](/quest/m1/ffi-export/contract.md) - a header and a library from different builds refuse to mix
- [C++ bindings](/quest/m1/ffi-export/cpp.md) - C++17, 20, and 23 over the C ABI, with native futures
- [Kotlin bindings](/quest/m1/ffi-export/kotlin.md) - JNI or Panama over the C ABI, with native futures
13 changes: 0 additions & 13 deletions quest/m1/ffi-export/contract.md

This file was deleted.