越过边界：FFI 调 C 与 no_std

1
/* pebble_shim.h - hand-written C99 shims linked into the Pebble runtime.
2
 *
3
 * Everything in this header has a safe Rust wrapper in `pebble-sys`'s lib.rs.
4
 * The ABI is plain C: integers by value, pointers by address.
5
 */
6
#ifndef PEBBLE_SHIM_H
7
#define PEBBLE_SHIM_H
8

9
#include <stddef.h>
10
#include <stdint.h>
11

12
#ifdef __cplusplus
13
extern "C" {
14
#endif
15

16
/* FNV-1a, 64-bit variant (offset basis 0xcbf29ce484222325, prime 0x100000001b3).
17
 *
18
 * Reads `len` bytes through `data` and returns the resulting digest. `data` may
19
 * be NULL when `len` is 0. The function keeps no reference to `data`.
20
 */
21
uint64_t pebble_fnv1a(const uint8_t *data, size_t len);
22

23
/* A bump (arena) allocator over a single upfront allocation.
24
 *
25
 * The struct is opaque: callers only ever hold a `PebbleArena *`. Every
26
 * function tolerates a NULL arena. Arenas are not thread-safe.
27
 */
28
typedef struct PebbleArena PebbleArena;
29

30
/* Creates an arena with room for `capacity` bytes.
31
 *
32
 * Returns NULL if memory cannot be obtained. A capacity of 0 is allowed: the
33
 * arena exists, `pebble_arena_used` stays 0 and every `pebble_arena_alloc`
34
 * fails. Release the result with `pebble_arena_destroy`.
35
 */
36
PebbleArena *pebble_arena_create(size_t capacity);
37

38
/* Bump-allocates `len` uninitialised bytes.
39
 *
40
 * The returned region is aligned to the widest scalar alignment the platform
41
 * requires (16 bytes on x86-64) and
42
 * never overlaps a region handed out by a previous call that has not been
43
 * invalidated by `pebble_arena_reset`. Contents are unspecified.
44
 *
45
 * Returns NULL when the arena is NULL, when the arena has no backing storage
46
 * (capacity 0) or when `len` bytes plus alignment padding do not fit in the
47
 * remaining capacity.
48
 */
49
void *pebble_arena_alloc(PebbleArena *arena, size_t len);
50

51
/* Bytes handed out so far, including alignment padding between allocations.
52
 * Returns 0 for a NULL arena. */
53
size_t pebble_arena_used(const PebbleArena *arena);
54

55
/* Total number of bytes the arena can hand out. Returns 0 for a NULL arena. */
56
size_t pebble_arena_capacity(const PebbleArena *arena);
57

58
/* Rewinds the arena so all of its capacity becomes available again.
59
 *
60
 * Every pointer previously returned by `pebble_arena_alloc` is invalidated by
61
 * this call: using one afterwards is undefined behaviour. No-op for NULL.
62
 */
63
void pebble_arena_reset(PebbleArena *arena);
64

65
/* Releases the arena and its backing storage. No-op for NULL. Afterwards the
66
 * arena pointer and every pointer it handed out are dangling. */
67
void pebble_arena_destroy(PebbleArena *arena);
68

69
/* Callback signature used by `pebble_fold`. `ctx` is the opaque pointer the
70
 * caller passed to `pebble_fold`; it may be NULL. */
71
typedef int64_t (*pebble_fold_fn)(int64_t acc, int64_t value, void *ctx);
72

73
/* Folds the integers in the inclusive range [lo, hi].
74
 *
75
 * Calls `cb(acc, value, ctx)` once per integer, in ascending order, threading
76
 * `init` as the initial accumulator and the callback's result as the next
77
 * accumulator. Returns the final accumulator, or `init` when `lo > hi`.
78
 *
79
 * `cb` must not be NULL. `pebble_fold` does not catch anything: how a callback
80
 * failure is handled is up to the callback.
81
 */
82
int64_t pebble_fold(int64_t init, int64_t lo, int64_t hi, pebble_fold_fn cb, void *ctx);
83

84
#ifdef __cplusplus
85
}
86
#endif
87

88
#endif /* PEBBLE_SHIM_H */

1
/* pebble_shim.c - implementation of the C half of `pebble-sys`. Portable C99. */
2

3
#include "pebble_shim.h"
4

5
#include <stdlib.h>
6

7
/* --- FNV-1a ----------------------------------------------------------------- */
8

9
#define PEBBLE_FNV_OFFSET_BASIS UINT64_C(0xcbf29ce484222325)
10
#define PEBBLE_FNV_PRIME UINT64_C(0x100000001b3)
11

12
uint64_t pebble_fnv1a(const uint8_t *data, size_t len) {
13
    uint64_t hash = PEBBLE_FNV_OFFSET_BASIS;
14
    size_t i;
15

16
    for (i = 0; i < len; i++) {
17
        hash ^= (uint64_t)data[i];
18
        hash *= PEBBLE_FNV_PRIME;
19
    }
20
    return hash;
21
}
22

23
/* --- Arena ------------------------------------------------------------------ */
24

25
/* C99 has no max_align_t, so probe the platform's widest scalar alignment with
26
 * a union instead. Its size is a multiple of that alignment (16 on x86-64). */
27
typedef union pebble_align_probe {
28
    long double ld;
29
    void *ptr;
30
    int64_t i64;
31
    size_t sz;
32
} pebble_align_probe;
33

34
#define PEBBLE_ALIGNMENT ((size_t)sizeof(pebble_align_probe))
35

36
struct PebbleArena {
37
    unsigned char *base;
38
    size_t capacity;
39
    size_t used;
40
};
41

42
/* Rounds `n` up to the next multiple of PEBBLE_ALIGNMENT. Overflow is handled
43
 * by the capacity check in pebble_arena_alloc. */
44
static size_t pebble_align_up(size_t n) {
45
    size_t rem = n % PEBBLE_ALIGNMENT;
46
    return rem == 0 ? n : n + (PEBBLE_ALIGNMENT - rem);
47
}
48

49
PebbleArena *pebble_arena_create(size_t capacity) {
50
    PebbleArena *arena = (PebbleArena *)malloc(sizeof(PebbleArena));
51

52
    if (arena == NULL) {
53
        return NULL;
54
    }
55
    arena->base = NULL;
56
    arena->capacity = capacity;
57
    arena->used = 0;
58

59
    if (capacity > 0) {
60
        arena->base = (unsigned char *)malloc(capacity);
61
        if (arena->base == NULL) {
62
            free(arena);
63
            return NULL;
64
        }
65
    }
66
    return arena;
67
}
68

69
void *pebble_arena_alloc(PebbleArena *arena, size_t len) {
70
    size_t start;
71

72
    if (arena == NULL || arena->base == NULL) {
73
        return NULL;
74
    }
75
    start = pebble_align_up(arena->used);
76
    /* Both comparisons are overflow-safe: `start <= capacity` is established
77
     * before `capacity - start` is computed. */
78
    if (start > arena->capacity || len > arena->capacity - start) {
79
        return NULL;
80
    }
81
    arena->used = start + len;
82
    return arena->base + start;
83
}
84

85
size_t pebble_arena_used(const PebbleArena *arena) {
86
    return arena == NULL ? 0 : arena->used;
87
}
88

89
size_t pebble_arena_capacity(const PebbleArena *arena) {
90
    return arena == NULL ? 0 : arena->capacity;
91
}
92

93
void pebble_arena_reset(PebbleArena *arena) {
94
    if (arena != NULL) {
95
        arena->used = 0;
96
    }
97
}
98

99
void pebble_arena_destroy(PebbleArena *arena) {
100
    if (arena != NULL) {
101
        free(arena->base);
102
        free(arena);
103
    }
104
}
105

106
/* --- Fold ------------------------------------------------------------------- */
107

108
int64_t pebble_fold(int64_t init, int64_t lo, int64_t hi, pebble_fold_fn cb, void *ctx) {
109
    int64_t acc = init;
110
    int64_t value;
111

112
    /* Walking hi upwards would be pointless: the range is inclusive and `lo >
113
     * hi` means "empty". */
114
    if (lo > hi) {
115
        return acc;
116
    }
117
    /* Structured so that the loop variable never overflows, even for hi ==
118
     * INT64_MAX: the increment is skipped on the final iteration. */
119
    for (value = lo;; value++) {
120
        acc = cb(acc, value, ctx);
121
        if (value == hi) {
122
            break;
123
        }
124
    }
125
    return acc;
126
}

1
//! Compiles the C shim in `csrc/` into a static library linked into this crate.
2

3
/// Source files that make up the C shim, relative to this crate's root.
4
const C_SOURCES: &[&str] = &["csrc/pebble_shim.c", "csrc/include/pebble_shim.h"];
5

6
fn main() {
7
    for source in C_SOURCES {
8
        println!("cargo:rerun-if-changed={source}");
9
    }
10

11
    cc::Build::new()
12
        .file("csrc/pebble_shim.c")
13
        .include("csrc/include")
14
        .flag_if_supported("-std=c99")
15
        .warnings(true)
16
        .compile("pebble_shim");
17
}

1
[package]
2
name = "pebble-sys"
3
description = "FFI shims: a small C library linked into the Pebble runtime."
4
version.workspace = true
5
edition.workspace = true
6
rust-version.workspace = true
7
authors.workspace = true
8
license.workspace = true
9
repository.workspace = true
10

11
[build-dependencies]
12
cc.workspace = true
13

14
[lints]
15
workspace = true

1
#[cfg(test)]
2
mod tests {
3
    use super::*;
4

5
    #[test]
6
    fn fnv1a_empty_is_offset_basis() {
7
        assert_eq!(fnv1a(b""), 0xcbf2_9ce4_8422_2325);
8
    }
9

10
    #[test]
11
    fn fnv1a_hello_matches_reference() {
12
        assert_eq!(fnv1a(b"hello"), 0xa430_d846_80aa_bd0b);
13
    }
14

15
    #[test]
16
    fn fnv1a_foobar_matches_reference() {
17
        assert_eq!(fnv1a(b"foobar"), 0x8594_4171_f739_67e8);
18
    }
19

20
    #[test]
21
    fn fnv1a_long_input_matches_rust_reference() {
22
        fn reference(data: &[u8]) -> u64 {
23
            data.iter().fold(0xcbf2_9ce4_8422_2325u64, |hash, byte| {
24
                (hash ^ u64::from(*byte)).wrapping_mul(0x0000_0100_0000_01b3)
25
            })
26
        }
27

28
        let data: Vec<u8> = (0..=255u8).cycle().take(1000).collect();
29
        assert_eq!(fnv1a(&data), reference(&data));
30
    }
31
}

1
/// Opaque handle for the C arena type.
2
///
3
/// The layout is deliberately unknown: Rust only ever names this type inside a
4
/// pointer, and the C side of the header is the single source of truth for what
5
/// it actually contains.
6
///
7
/// The marker follows the Rustonomicon's pattern for opaque FFI types: the raw
8
/// pointer makes the type `!Send` and `!Sync`, and `PhantomPinned` makes it
9
/// `!Unpin`, so safe code can never move or share it by accident.
10
#[repr(C)]
11
struct PebbleArena {
12
    /// Makes the type impossible to construct in Rust.
13
    _data: [u8; 0],
14
    _marker: PhantomData<(*mut u8, PhantomPinned)>,
15
}

1
unsafe extern "C" {
2
    /// Reads `len` bytes at `data`; `data` may be null when `len` is 0.
3
    fn pebble_fnv1a(data: *const u8, len: usize) -> u64;
4

5
    /// Returns null on allocation failure.
6
    fn pebble_arena_create(capacity: usize) -> *mut PebbleArena;
7
    /// Returns null when the request does not fit.
8
    fn pebble_arena_alloc(arena: *mut PebbleArena, len: usize) -> *mut c_void;
9
    fn pebble_arena_used(arena: *const PebbleArena) -> usize;
10
    fn pebble_arena_capacity(arena: *const PebbleArena) -> usize;
11
    /// Invalidates every pointer the arena has handed out.
12
    fn pebble_arena_reset(arena: *mut PebbleArena);
13
    /// Frees the arena and its backing storage.
14
    fn pebble_arena_destroy(arena: *mut PebbleArena);
15
}

1
error[E0308]: mismatched types
2
 --> src/bin/closure_cb.rs:5:59
3
  |
4
5 |     let cb: extern "C" fn(i64, i64, *mut c_void) -> i64 = |acc, value, _ctx| acc + value * scale;
5
  |             -------------------------------------------   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected fn pointer, found closure
6
  |             |
7
  |             expected due to this
8
  |
9
  = note: expected fn pointer `extern "C" fn(i64, i64, *mut c_void) -> i64`
10
                found closure `{closure@src/bin/closure_cb.rs:5:59: 5:77}`
11
note: closures can only be coerced to `fn` types if they do not capture any variables
12
 --> src/bin/closure_cb.rs:5:92
13
  |
14
5 |     let cb: extern "C" fn(i64, i64, *mut c_void) -> i64 = |acc, value, _ctx| acc + value * scale;
15
  |                                                                                            ^^^^^ `scale` captured here
16

17
For more information about this error, try `rustc --explain E0308`.
18
error: could not compile `lab-ch13-sys` (bin "closure_cb") due to 1 previous error

1
/// The Rust function C calls once per value, cast to `pebble_fold_fn`.
2
///
3
/// A panic must not unwind into C, so the closure runs inside
4
/// [`catch_unwind`]; the payload is stashed in the context and the panic is
5
/// resumed in [`fold`] after C has returned.
6
extern "C" fn fold_trampoline(acc: i64, value: i64, ctx: *mut c_void) -> i64 {
7
    // SAFETY: `fold` passes a pointer to a `FoldCtx` that outlives the whole
8
    // `pebble_fold` call, passes the same pointer to every invocation, and the
9
    // trampoline is the only callback C is given for that call.
10
    let ctx: &mut FoldCtx<'_> = unsafe { &mut *ctx.cast() };
11
    if ctx.panic.is_some() {
12
        // The closure already panicked; do not call into possibly-broken state
13
        // again while C keeps walking the range.
14
        return acc;
15
    }
16
    match catch_unwind(AssertUnwindSafe(|| (ctx.f)(acc, value))) {
17
        Ok(next) => next,
18
        Err(payload) => {
19
            ctx.panic = Some(payload);
20
            acc
21
        }
22
    }
23
}