|
| 1 | +# Compat Shims |
| 2 | + |
| 3 | +Rule matching needs a resolvable callee. The preprocessor keys every expression |
| 4 | +rule on the function, method, constructor, constant, or global that the |
| 5 | +pattern's `return` expression resolves to, and the only macros it can record are |
| 6 | +those that |
| 7 | +[expand to an integer literal](./writing-rules.md#enum-values-constants-and-macros), |
| 8 | +which match by macro name. Any other macro is invisible to the rule system: by |
| 9 | +the time clang has built the AST, the macro is gone and only its expansion |
| 10 | +remains. |
| 11 | + |
| 12 | +That is a problem for a small set of libc APIs that are specified as macros over |
| 13 | +platform internals: |
| 14 | + |
| 15 | +- `errno` is an object-like macro; glibc expands it to `(*__errno_location())`, |
| 16 | + macOS to `(*__error())`. |
| 17 | +- `assert` expands to a conditional that stringifies the condition and calls a |
| 18 | + platform-specific failure handler with file and line arguments. |
| 19 | +- `FD_SET`, `FD_CLR`, `FD_ISSET`, and `FD_ZERO` expand to bit manipulation on |
| 20 | + the `fd_set` representation, through helpers that differ per platform. |
| 21 | +- `ntohl`, `ntohs`, `htonl`, and `htons` expand to byte-swap builtins or to |
| 22 | + nothing at all, depending on endianness. |
| 23 | + |
| 24 | +There is no stable, platform-independent callee here to key a rule on. The |
| 25 | +_compat headers_ in `cpp2rust/compat/` fix this by rewriting each such macro |
| 26 | +into a call to a synthetic, well-known function before matching happens. |
| 27 | + |
| 28 | +## How the shims work |
| 29 | + |
| 30 | +`cpp2rust/compat` is injected as a system include directory ahead of the |
| 31 | +platform headers in every clang invocation the project makes: both when |
| 32 | +`cpp2rust` parses the input program and when `cpp-rule-preprocessor` compiles |
| 33 | +rule sources. The shared flag list lives in `cpp2rust/compat/platform_flags.h` |
| 34 | +(`getPlatformClangBeginFlags`), and the directory path is baked in at build time |
| 35 | +via the `COMPAT_INCLUDE_DIR` definition. |
| 36 | + |
| 37 | +A shim header sits at the same relative path as the real header it shadows |
| 38 | +(`errno.h`, `sys/select.h`, `arpa/inet.h`, ...), so an ordinary |
| 39 | +`#include <errno.h>` finds the shim first. The header then: |
| 40 | + |
| 41 | +1. pulls in the real platform header with `#include_next` (a GNU extension; the |
| 42 | + shared flags pass `-Wno-gnu-include-next` for it), |
| 43 | +2. `#undef`s the macro, |
| 44 | +3. declares a `cpp2rust_*` shim function, |
| 45 | +4. redefines the macro to call the shim. |
| 46 | + |
| 47 | +`cpp2rust/compat/errno.h` in full: |
| 48 | + |
| 49 | +```c |
| 50 | +#include_next <errno.h> |
| 51 | + |
| 52 | +#undef errno |
| 53 | + |
| 54 | +int *cpp2rust_errno(void); |
| 55 | + |
| 56 | +#define errno (*cpp2rust_errno()) |
| 57 | +``` |
| 58 | +
|
| 59 | +The redefinition keeps `errno` an lvalue by dereferencing the returned pointer, |
| 60 | +so both reads and assignments like `errno = 0` still parse; what the matcher |
| 61 | +sees in either case is a call to `int *cpp2rust_errno()`. |
| 62 | +
|
| 63 | +Because the input program and the rule sources are compiled with the same shim |
| 64 | +headers, both sides canonicalize to the same signature, and an ordinary |
| 65 | +[expression rule](./writing-rules.md) matches it: |
| 66 | +
|
| 67 | +```c |
| 68 | +// rules/errno/src.c |
| 69 | +#include <errno.h> |
| 70 | +
|
| 71 | +int *f1(void) { return cpp2rust_errno(); } |
| 72 | +``` |
| 73 | + |
| 74 | +The shim functions are declared but never defined on the C side. They only exist |
| 75 | +so that the callee resolves; translation replaces the call with the rule body, |
| 76 | +so no C implementation is ever linked. Whatever the shim is supposed to _do_ is |
| 77 | +supplied by the Rust targets: |
| 78 | + |
| 79 | +```rust |
| 80 | +// rules/errno/tgt_unsafe.rs |
| 81 | +unsafe fn f1() -> *mut i32 { |
| 82 | + libcc2rs::cpp2rust_errno_unsafe() |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +```rust |
| 87 | +// rules/errno/tgt_refcount.rs |
| 88 | +fn f1() -> Ptr<i32> { |
| 89 | + libcc2rs::cpp2rust_errno() |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +In the unsafe model `libcc2rs::cpp2rust_errno_unsafe` wraps the real platform |
| 94 | +errno location (`__errno_location` on Linux, `__error` on macOS). The refcount |
| 95 | +model instead _virtualizes_ errno as a thread-local `Value<i32>` inside |
| 96 | +`libcc2rs`; this is the same cell that other refcount rules write when they |
| 97 | +translate a failing libc call into |
| 98 | +`libcc2rs::cpp2rust_errno().write(__e as i32)`. |
| 99 | + |
| 100 | +A rule pattern may spell either the macro or the shim directly; the two are |
| 101 | +identical after expansion. `rules/errno` and `rules/assert` call the shim by |
| 102 | +name, while `rules/arpa_inet` and `rules/select` write the macro form: |
| 103 | + |
| 104 | +```c |
| 105 | +// rules/select/src.cpp |
| 106 | +void f2(int fd, fd_set *set) { return FD_SET(fd, set); } |
| 107 | +``` |
| 108 | +
|
| 109 | +## The current shims |
| 110 | +
|
| 111 | +| Header | Macros | Shim functions | Rules | |
| 112 | +| -------------- | ----------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------- | |
| 113 | +| `assert.h` | `assert` | `cpp2rust_assert_fail(bool)` | `rules/assert` maps it to `assert!(a0)` | |
| 114 | +| `errno.h` | `errno` | `cpp2rust_errno()` | `rules/errno`, see above | |
| 115 | +| `arpa/inet.h` | `ntohl`, `ntohs`, `htonl`, `htons` | `cpp2rust_ntohl(x)`, ... | `rules/arpa_inet` maps them to `u32::from_be`, `u16::to_be`, ... | |
| 116 | +| `sys/select.h` | `FD_SET`, `FD_CLR`, `FD_ISSET`, `FD_ZERO` | `cpp2rust_fd_set(fd, set)`, ... | `rules/select` maps them to `libc::FD_SET(...)` (unsafe) or `CFdSet` methods (refcount) | |
| 117 | +
|
| 118 | +Note how the shim also normalizes the _shape_ of the API. C's `assert` is a |
| 119 | +macro precisely so it can stringify its condition and capture file and line; the |
| 120 | +shim reduces it to a plain `void(bool)` function, and the Rust side regains the |
| 121 | +diagnostics by mapping it to the `assert!` macro. |
| 122 | +
|
| 123 | +## Adding a new shim |
| 124 | +
|
| 125 | +To make another macro-based API matchable: |
| 126 | +
|
| 127 | +1. Create the header in `cpp2rust/compat/` at the same relative path as the |
| 128 | + platform header that defines the macro. |
| 129 | +2. Follow the pattern above: `#include_next` the real header, `#undef` the |
| 130 | + macro, declare a `cpp2rust_<name>` function with the macro's effective |
| 131 | + signature, and redefine the macro to call it. |
| 132 | +3. Write rules for the shim in a `rules/` module as for any other function, |
| 133 | + including the corresponding header in `src.c`/`src.cpp`. |
| 134 | +4. If a model needs runtime support (as refcount errno does), implement it in |
| 135 | + `libcc2rs` and call it from the rule target. |
| 136 | +
|
| 137 | +Keep the shim's signature platform-independent; the whole point is that both |
| 138 | +sides of every rule see one canonical declaration on every platform. |
| 139 | +
|
| 140 | +## Related normalization |
| 141 | +
|
| 142 | +The same shared flag list also passes `-D_FORTIFY_SOURCE=0`, which keeps glibc |
| 143 | +from substituting fortified variants (`__printf_chk` and friends) for standard |
| 144 | +calls. Like the shims, this ensures that calls in the input program resolve to |
| 145 | +the standard declarations the rules are written against. |
0 commit comments