`bindgen` wanted features & bugfixes

[ojeda]

Note: see as well the "rust-for-linux" label in bindgen: https://github.com/rust-lang/rust-bindgen/labels/rust-for-linux.

Features that we would like to see

Required (we almost certainly want them)

• Support for a GCC-based backend.

  • Issue: Support for a GCC-based backend rust-lang/rust-bindgen#1949.
  • Related: How to avoid bindgen being out of sync with cc? rust-lang/rust-bindgen#2962.

• Support non-trivial object-like macros that evaluate to a numeric value when fully expanded.

  • For instance:
    • An expression, e.g. #define A ((int)1).
    • Macros using function-like macros, e.g. Linux ioctl #defines using _IO*.
  • Issue: Improve macro defined constants to recognize #define CONSTANT ((int) 1) rust-lang/rust-bindgen#316 (expressions).
  • Issue: Functional C macros are not expanded. rust-lang/rust-bindgen#753 (using other macros).
  • PR ("one pass per macro", i.e. option 1 below): Workaround for expansion of function-like macros rust-lang/rust-bindgen#2779 (0.70.0).
  • PR (follow up fixes): Switch to single precompiled header in macro fallback rust-lang/rust-bindgen#2823 (0.70.0?).
  • Lore (trying out --clang-macro-fallback, kernel patch with workarounds to test bindgen available): https://lore.kernel.org/rust-for-linux/CANiq72m20pom+B9EmWO+91E8fjbMEob3JmvHRQ6UaXe_JmatfA@mail.gmail.com/.
  • Issue: --clang-macro-fallback interaction with -include rust-lang/rust-bindgen#3069.
  • Issue: --clang-macro-fallback interaction with -Wp,-MMD,file.d rust-lang/rust-bindgen#3070.
  • Issue: --clang-macro-fallback duplicate definitions rust-lang/rust-bindgen#3071.
  • Issue (on --clang-macro-fallback's types): Fails to generate correct code when UINT64_C is used rust-lang/rust-bindgen#3200.
  • PR: Fix bugs in --clang-macro-fallback rust-lang/rust-bindgen#3072.
  • Related PR: Fix race condition in clang_macro_fallback rust-lang/rust-bindgen#3111.
  • Meta-issue: Preprocessing meta-issue rust-lang/rust-bindgen#2426.
  • Zulip: https://rust-for-linux.zulipchat.com/#narrow/stream/288089-General/topic/bindgen.20issue.20.23753.20-.20function.20like.20macros/near/420514477.
  • Cc: @jbaublitz who has been following/helping with this issue since the beginning and potentially interested in working on it.
  • Status:

    I met with @emilio a few days ago (early February 2024), and we discussed this for a bit, including the bindgen-side solution/workaround of emitting extra code so that we can fetch the value.

    The variations we discussed were "one pass per macro" (slow, but could work without user input), "one extra pass for all macros" (this would be fast, but would require the user to pass e.g. a regex of matching macros to evaluate that are "known to be constants" already); as well as the possibility of "appending the macros later on" (i.e. add them into a context or similar, which may be possible or not with the current API; we should also check e.g. what Clang-Repl/Cling does here).

    So, in summary, bindgen would be happy with a workaround. But solving it in LLVM is, of course, the best long-term, so that would be great too (ideally both, so that we can use the feature before projects like the kernel have a minimum LLVM version >= 19).

    For the LLVM side, @AaronBallman (the Clang maintainer) told me he would be happy to review our changes if we sent them, in order to help bindgen, so that is great if someone wants to work on it.

    • The first option, i.e. "one pass per macro" was prototyped by @jbaublitz.

• Support aligned members (including structs with bitfields) inside packed structs.

  • Workaround: mark the type as opaque, and if needed, access it in another way (e.g. from C).
  • See as well the Rust support for it: Rust wanted features #354.
  • i.e. avoid generating #[repr(C, align(...)] inside an #[repr(C, packed)].
  • Seen for struct alt_instr: https://lore.kernel.org/all/202212272003.rgQDX8DQ-lkp@intel.com/
  • Issue: packed type cannot transitively contain a #[repr(align)] type rust-lang/rust-bindgen#2179.
  • Issue: structure layout using __aligned__ attribute is incorrect rust-lang/rust-bindgen#867.
  • Issue: handle more cases of packed and aligned structs when it's safe/correct rust-lang/rust-bindgen#2725.
  • Related issue: E0587 error on packed and aligned structures from C rust-lang/rust-bindgen#1538.
  • PR: Consider alignment contribution from bitfields rust-lang/rust-bindgen#2388.
  • PR: try to avoid #[repr(packed)] when align is needed rust-lang/rust-bindgen#2734.
  • PR (RFC alternative 1): [RFC, V1] try to exclude packed attr for types that contain aligned types rust-lang/rust-bindgen#2769.
  • PR (RFC alternative 2): [RFC, V2] exclude packed attr for types that contain aligned types when possible rust-lang/rust-bindgen#2770.
  • RFC: RFC: Add an attribute for raising the alignment of various items rust-lang/rfcs#3806.

• Support a new "enum variant" kind, similar to rustified_enum, that provides a safe method to transform a C enum to Rust.

  • The goal is to ensure at compile-time that, if the C side enum adds a variant, the Rust side (i.e. the conversion method) will be updated properly too.
  • From: https://rust-for-linux.zulipchat.com/#narrow/stream/288089-General/topic/Enum.20handling/near/392620696.
  • Issue: Add enum option constified_enum + rustified_enum with conversions rust-lang/rust-bindgen#2646.
  • PR: Add option to generate safe and unsafe conversions for rustified enums rust-lang/rust-bindgen#2908.
  • Issue (revamping the CLI interface for enums, from Add option to generate safe and unsafe conversions for rustified enums rust-lang/rust-bindgen#2908 (comment)): [RFC] Revamp interface for enum representations rust-lang/rust-bindgen#3050.
  • Issue (modifying existing behavior?): Using rustified enums in function signatures is (almost?) always wrong rust-lang/rust-bindgen#3051.

• --with-derive-custom-struct doesn't apply to __BindgenBitfieldUnit.

  • Issue: --with-derive-custom-struct doesn't apply to __BindgenBitfieldUnit rust-lang/rust-bindgen#3196.
  • Zulip: https://rust-for-linux.zulipchat.com/#narrow/channel/291565/topic/Zeroable.20trait.20for.20C.20structs/near/509711564.
  • Rust for Linux branch with use case: https://github.com/y86-dev/linux/commits/bindgen-zeroable/.
  • Cc: @y86-dev.

Nice to have (not critical, we could workaround if needed, etc.)

• process_comments via CLI.

  • See as well "C javadoc comments" below.
  • Issue: CLI integration with doxygen-rs? rust-lang/rust-bindgen#2953.

• bindgen does not generate union + ManuallyDrop for some cases.

  • Even when manually_drop style is requested (e.g. via --default-non-copy-union-style manually_drop or --manually-drop-union '.*').
  • This happens in the kernel via unions with only DECLARE_FLEX_ARRAY such as in struct bpf_array.
  • Issue: C union containing only flexible array members does not generate Rust union rust-lang/rust-bindgen#3130.
  • Rust for Linux issue: Bindgen should be configured to use union + ManuallyDrop #1137.
  • Related: Source for union claim? Richardhongyu/rfl_empirical_tools#1.

• Translating inline assembly into Rust.

  • See "Querying GCC-style inline assembly so that bindgen can translate it into Rust inline assembly." in LLVM and Clang wanted features & bugfixes #1132.
  • Cc: @dingxiangfei2009.

Low priority (we will likely not use them in the end)

Done (stabilized, fixed, not needed anymore, etc.)

• Support unsafe_op_in_unsafe_fn.

  • Issue: Support unsafe_op_in_unsafe_fn rust-lang/rust-bindgen#2063.
  • PR: Wrap unsafe function's bodies in unsafe blocks rust-lang/rust-bindgen#2266.

• Support _Noreturn, [[noreturn]], __attribute__((noreturn))

  • Issue: Support _Noreturn, [[noreturn]], __attribute__((noreturn)) rust-lang/rust-bindgen#2094.
  • PR: Handle no return attributes rust-lang/rust-bindgen#2259.

• Support typedefs shadowing types e.g. typedef struct T *T;.

  • In other words, avoid conflating C name spaces.
  • Seen in the past e.g. for maple_*nodes (Build fail on linux-next (next-20220629 tag): the name maple_enode is defined multiple times #795).
  • Issue: Multiple definitions when a pointer gets typedef’d to the same name as a struct rust-lang/rust-bindgen#2227.
  • PR: Handle the const struct * and struct * patterns rust-lang/rust-bindgen#2304.

• Take advantage of feature(core_ffi_c) and feature(c_size_t).

  • This avoids having to manually specify --ctypes-prefix core::ffi.
  • Issue: Take advantage of feature(core_ffi_c) (and possibly feature(c_size_t)) rust-lang/rust-bindgen#2231.
  • PR: use #[feature(core_ffi_c)] when available rust-lang/rust-bindgen#2267.

• A way to query the Clang version being used.

  • Issue: Querying bindgen for LLVM version being used rust-lang/rust-bindgen#2138.
  • PR: options: Implement --version manually and print clang version on --version --verbose rust-lang/rust-bindgen#2140.

• Compile-time layout tests.

  • We are planning to run the layout tests as e.g. KUnit tests, but if they were compile-time ones, it would be simpler.
  • Issue: Feature request: compile-time layout tests rust-lang/rust-bindgen#2786.
  • PR: Compile time layout tests rust-lang/rust-bindgen#2787 (0.xx.x).

• Support static inline functions in headers (by generating a wrapper).

  • Currently we do it manually. bindgen currently (0.64.0) has experimental support via --wrap-static-fns --experimental.
  • Netdev would like it, e.g. skbuff.h has 300+ static inlines: https://lore.kernel.org/rust-for-linux/f28d6403-d042-4ffb-9872-044388d0f9d9@lunn.ch/
  • Tracking (?) Issue: Allow wrap-static-fns to be used without experimental feature rust-lang/rust-bindgen#2900.
  • Issue: Generate C code to export static inline functions rust-lang/rust-bindgen#1090.
  • PR: Generate extern wrappers for inlined functions rust-lang/rust-bindgen#2335.
  • Issue: Interaction between wrapped statics and redefined function rust-lang/rust-bindgen#2420.
  • Stabilization PR: Stabilize --wrap-static-fns rust-lang/rust-bindgen#2928.

• Raw pointer bitfield accessors.

  • Issue: bitfields raw pointer accessors rust-lang/rust-bindgen#2674.
  • PR: Add additional helpers to bitfield data structure rust-lang/rust-bindgen#2876.

• Rust for Linux in the bindgen CI.

  • PR: ci: Add Rust for Linux rust-lang/rust-bindgen#2851.

• CI: update to v6.12-rc5.

  • PR: ci: Move forward Rust for Linux version rust-lang/rust-bindgen#2970.
  • Reported in the CI of PR: fix very small typo rust-lang/rust-bindgen#2969.

• A way to specify a MSRV, instead of --rust-target (which only supports a subset of versions).

  • For instance, when we started using --rust-target, the kernel supported Rust 1.78.0+ and bindgen 0.65.1+, thus we picked --rust-target 1.68, since it is the maximum stable version supported by the --rust-target flag in bindgen 0.65.1 (and it is lower than our MSRV).
  • Lore: https://lore.kernel.org/rust-for-linux/20241123180323.255997-1-ojeda@kernel.org/.
  • Rust Zulip: https://rust-lang.zulipchat.com/#narrow/channel/425075-rust-for-linux/topic/rust.20version.20on.20generated.20bindings/near/484087179.
  • PR: Refactor RustTarget rust-lang/rust-bindgen#2993.
  • PR: Make nightly target compatible with every other target rust-lang/rust-bindgen#3006.

• A way to specify an output Edition, e.g. --rust-edition.

  • PR: Introduce --rust-edition rust-lang/rust-bindgen#3002.
  • PR: Add rust language editions support rust-lang/rust-bindgen#3000.

• CI: update to v6.13-rc1.

  • PR: ci: Move forward Rust for Linux version to v6.13-rc1 rust-lang/rust-bindgen#3030.

• Support for Edition 2024.

  • Not important, since we can keep compiling the bindings in an older edition like 2021, but it would be nice to migrate everything to Edition 2024 eventually if it becomes available in Debian Trixie.
  • Edition 2021: Supporting 2021-edition features rust-lang/rust-bindgen#2998.
  • unsafe extern issue: Generate unsafe extern blocks (Edition 2024) rust-lang/rust-bindgen#2901.
  • unsafe extern PR: Add support for unsafe extern blocks rust-lang/rust-bindgen#3015.
  • Issue: Make RustEdition public rust-lang/rust-bindgen#3012.
  • PR: Make RustEdition public rust-lang/rust-bindgen#3013.

• CI: update to v6.14 (which also fixes the soft-float issue since bindgen uses stable).

  • Issue: Rust for linux CI breaks with rust 1.86 rust-lang/rust-bindgen#3188.
  • PR: ci: use stable again moving forward Rust for Linux job rust-lang/rust-bindgen#3189.

• CI: update to v6.15-rc4.

  • PR: ci: Move forward Rust for Linux version to v6.15-rc4 rust-lang/rust-bindgen#3201.

• CI: update to v6.16-rc1.

  • PR: ci: Move forward Rust for Linux version to v6.16-rc1 rust-lang/rust-bindgen#3225.

• CI: update to v6.17-rc2.

  • PR: ci: Move forward Rust for Linux version to v6.17-rc2 rust-lang/rust-bindgen#3271.

---

Bugs that we would like to see fixed

Required (we almost certainly want them)

• BindgenUnion can get incorrect alignment on i686.

  • Issue: BindgenUnion can get incorrect alignment on i686 rust-lang/rust-bindgen#2773.

• Forward references to enum types end up generating the wrong type.

  • Issue: Forward references to enum types end up generating the wrong type rust-lang/rust-bindgen#3179.
  • Issue (duplicate): emitted enum type changes type depending on usage rust-lang/rust-bindgen#3205.
  • Workaround patch: https://lore.kernel.org/rust-for-linux/20250325184309.97170-1-ojeda@kernel.org/.
  • Lore: https://lore.kernel.org/rust-for-linux/87tt7md1s6.fsf@kernel.org/.

Nice to have (probably not critical, we could workaround if needed, etc.)

Low priority (we will likely not use them in the end)

Done (stabilized, fixed, or not needed anymore, etc.)

• Fix the called `Result::unwrap()` on an `Err` value: FromBytesWithNulError { kind: InteriorNul(4) } issue (affects 0.66.0 and 0.66.1, fixed in 0.68.0, note that 0.67.x does not exist, patched in e.g. Debian).

  • Commit: 981ad93 ("rust: warn about bindgen versions 0.66.0 and 0.66.1").
  • Issue: Thread 'main' panicked at 'called Result::unwrap() on an Err value: FromBytesWithNulError { kind: InteriorNul(29) } rust-lang/rust-bindgen#2566.
  • PR: codegen: Generate CStr only if possible. rust-lang/rust-bindgen#2567.

• Support --version without header (affects 0.69.0, fixed in 0.69.1, regressed in 0.71.0, fixed again in 0.71.1).

  • We currently workaround it with a dummy parameter.
  • Commit: 9e98db1 ("rust: work around bindgen 0.69.0 issue").
  • Issue (0.69.0): --version no longer works without <HEADER> argument rust-lang/rust-bindgen#2677.
  • Issue (0.71.0): bindgen --version does not work (0.71.0 regression) rust-lang/rust-bindgen#3039.
  • Issue (probably related, 0.71.0): generate shell completion is changed in v0.71.0 rust-lang/rust-bindgen#3037.
  • PR: fix(args): make header argument optional rust-lang/rust-bindgen#2678 (0.69.1).
  • PR: Unbreak shell completion and --version without header rust-lang/rust-bindgen#3040 (0.71.1).

• C javadoc comments are not Markdown-escaped, triggering rustdoc warnings.

  • Issue: C javadoc comments are not Markdown-escaped, triggering rustdoc warnings rust-lang/rust-bindgen#2057.

• Attribute btf_type_tag makes constness of pointers disappear.

  • It will allow to undo the f6bb7cb workaround.
  • Should be fixed in 0.61.
  • Issue: Attribute btf_type_tag makes constness of pointers disappear  rust-lang/rust-bindgen#2244.
  • PR: ty: Use canonical type to access pointee. rust-lang/rust-bindgen#2245.

• "Unable to find libclang" problems (rust compiler not found #934), possibly related to Clang 15.

  • Issue: Unable to find libclang: "the libclang shared library rust-lang/rust-bindgen#2360.
  • PR (may or may not solve our issue): Bump clang-sys version rust-lang/rust-bindgen#2368.

• --wrap-static-fns generates code that returns a call to a void function.

  • Issue: --wrap-static-fns generates code that returns a call to a void function rust-lang/rust-bindgen#2485.
  • PR: Do not return when calling void functions  rust-lang/rust-bindgen#2497.

• --wrap-static-fns generates () for empty parameter lists.

  • Issue: --wrap-static-fns generates () for empty parameter lists rust-lang/rust-bindgen#2484.
  • Should be fixed in 0.65.1.

• Fix the support for linking libclang statically.

  • Zulip: https://rust-for-linux.zulipchat.com/#narrow/stream/291565-Help/topic/Build.20errors/near/391197677.
  • PR: Fix bindgen-cli support link static libclang rust-lang/rust-bindgen#2644.

Not a bug (the report was not considered a bug)

• "Duplicated" variable (due to struct_group).
  • Issue: Incorrect bindings generation with sk_buff C structure from Linux kernel rust-lang/rust-bindgen#3089.

[pvdrz]

Hi everyone!

I have opened some PRs on bindgen adding some features you needed:

• Handle no return attributes rust-lang/rust-bindgen#2259
• Wrap unsafe function's bodies in unsafe blocks rust-lang/rust-bindgen#2266
• use #[feature(core_ffi_c)] when available rust-lang/rust-bindgen#2267

I'd be happy to hear if the PRs here actually provide what you need.

[alex]

These look spot on to me. Thanks for your efforts!

[ojeda]

Added links above, thanks a lot @pvdrz! :)

[dwlsalmeida]

@ojeda Hey Miguel, is there a workaround in place for this?

Support function-like macros that use other macros and that evaluate to a numeric value when fully expanded (e.g. for Linux ioctl #defines using _IO*).

I am trying to write a v4l2 driver and one of the issues I found was that the pixel formats bindings are not generated by bindgen because the V4L2_PIX_FMT_* stuff is defined using the v4l2_fourcc macro

[ojeda]

For something like pixel formats that are stable (given they are in uapi, right?), I guess the easiest is re-implementing them on the Rust side, especially if you want to give them a proper type etc. anyway. Probably using a small temporary script to perform the bulk of the conversion.

Otherwise, if performance is not too much of a concern (even if cross-language LTO could reduce the cost at some point), one alternative is "executing" the macro at runtime by providing a C function that does it for the Rust side. In your case this one is likely not interesting because the important bits are the parameters to the macro, rather than the macro itself.

[bjorn3]

For the drm fourcc pixel format codes, the drm-fourcc crate has some code which fetches all #define from the header, generates a constant for each #define in a new header and then runs bindgen on the generated header: https://github.com/danielzfranklin/drm-fourcc-rs/blob/main/build.rs

[dwlsalmeida]

One question though, suppose I use the approach suggested by @bjorn3

Do I commit the bindings I generate? Asking because apparently bindings_generated.rs is not part of the kernel per-se and is only generated during build time.

[bjorn3]

I think the bindings should be generated on the fly to ensure they stay up to date, just like bindings_generated.rs.

[dwlsalmeida]

well, in which case I suppose that the code to generate them (i.e. something similar to the code in the drm-fourcc crate) would have to be integrated into the kernel build system somehow?

[bjorn3]

Indeed. There is already infrastructure to run code written in rust. See for example scripts/generate_rust_target.rs.

[dwlsalmeida]

Makes sense, thanks for the pointers!