Merge pull request raspberrypi#713 from ojeda/c-comment-style

rust: C files improvements & cleanups

Author: ojeda

rust/exports.c

@@ -1,14 +1,15 @@
 // SPDX-License-Identifier: GPL-2.0
-//
-// A hack to export Rust symbols for loadable modules without having to redo
-// the entire `include/linux/export.h` logic in Rust.
-//
-// This requires the Rust's new/future `v0` mangling scheme because the default
-// one ("legacy") uses invalid characters for C identifiers (thus we cannot use
-// the `EXPORT_SYMBOL_*` macros).
-//
-// All symbols are exported as GPL-only to guarantee no GPL-only feature is
-// accidentally exposed.
+/*
+ * A hack to export Rust symbols for loadable modules without having to redo
+ * the entire `include/linux/export.h` logic in Rust.
+ *
+ * This requires the Rust's new/future `v0` mangling scheme because the default
+ * one ("legacy") uses invalid characters for C identifiers (thus we cannot use
+ * the `EXPORT_SYMBOL_*` macros).
+ *
+ * All symbols are exported as GPL-only to guarantee no GPL-only feature is
+ * accidentally exposed.
+ */
 
 #include <linux/module.h>
 

rust/helpers.c

@@ -1,21 +1,22 @@
 // SPDX-License-Identifier: GPL-2.0
-//
-// Non-trivial C macros cannot be used in Rust. Similarly, inlined C functions
-// cannot be called either. This file explicitly creates functions ("helpers")
-// that wrap those so that they can be called from Rust.
-//
-// Even though Rust kernel modules should never use directly the bindings, some
-// of these helpers need to be exported because Rust generics and inlined
-// functions may not get their code generated in the crate where they are
-// defined. Other helpers, called from non-inline functions, may not be
-// exported, in principle. However, in general, the Rust compiler does not
-// guarantee codegen will be performed for a non-inline function either.
-// Therefore, this file exports all the helpers. In the future, this may be
-// revisited to reduce the number of exports after the compiler is informed
-// about the places codegen is required.
-//
-// All symbols are exported as GPL-only to guarantee no GPL-only feature is
-// accidentally exposed.
+/*
+ * Non-trivial C macros cannot be used in Rust. Similarly, inlined C functions
+ * cannot be called either. This file explicitly creates functions ("helpers")
+ * that wrap those so that they can be called from Rust.
+ *
+ * Even though Rust kernel modules should never use directly the bindings, some
+ * of these helpers need to be exported because Rust generics and inlined
+ * functions may not get their code generated in the crate where they are
+ * defined. Other helpers, called from non-inline functions, may not be
+ * exported, in principle. However, in general, the Rust compiler does not
+ * guarantee codegen will be performed for a non-inline function either.
+ * Therefore, this file exports all the helpers. In the future, this may be
+ * revisited to reduce the number of exports after the compiler is informed
+ * about the places codegen is required.
+ *
+ * All symbols are exported as GPL-only to guarantee no GPL-only feature is
+ * accidentally exposed.
+ */
 
 #include <linux/bug.h>
 #include <linux/build_bug.h>
@@ -506,24 +507,25 @@ const struct of_device_id *rust_helper_of_match_device(
 }
 EXPORT_SYMBOL_GPL(rust_helper_of_match_device);
 
-/* We use bindgen's --size_t-is-usize option to bind the C size_t type
- * as the Rust usize type, so we can use it in contexts where Rust
- * expects a usize like slice (array) indices. usize is defined to be
- * the same as C's uintptr_t type (can hold any pointer) but not
- * necessarily the same as size_t (can hold the size of any single
+/*
+ * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type
+ * as the Rust `usize` type, so we can use it in contexts where Rust
+ * expects a `usize` like slice (array) indices. `usize` is defined to be
+ * the same as C's `uintptr_t` type (can hold any pointer) but not
+ * necessarily the same as `size_t` (can hold the size of any single
  * object). Most modern platforms use the same concrete integer type for
  * both of them, but in case we find ourselves on a platform where
  * that's not true, fail early instead of risking ABI or
  * integer-overflow issues.
  *
  * If your platform fails this assertion, it means that you are in
  * danger of integer-overflow bugs (even if you attempt to remove
- * --size_t-is-usize). It may be easiest to change the kernel ABI on
- * your platform such that size_t matches uintptr_t (i.e., to increase
- * size_t, because uintptr_t has to be at least as big as size_t).
-*/
+ * `--size_t-is-usize`). It may be easiest to change the kernel ABI on
+ * your platform such that `size_t` matches `uintptr_t` (i.e., to increase
+ * `size_t`, because `uintptr_t` has to be at least as big as `size_t`).
+ */
 static_assert(
 	sizeof(size_t) == sizeof(uintptr_t) &&
 	__alignof__(size_t) == __alignof__(uintptr_t),
-	"Rust code expects C size_t to match Rust usize"
+	"Rust code expects C `size_t` to match Rust `usize`"
 );

rust/kernel/bindings_helper.h

@@ -1,31 +1,37 @@
 /* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * Header that contains the code (mostly headers) for which Rust bindings
+ * will be automatically generated by `bindgen`.
+ *
+ * Sorted alphabetically.
+ */
 
+#include <asm/io.h>
+#include <linux/amba/bus.h>
 #include <linux/cdev.h>
 #include <linux/clk.h>
 #include <linux/errname.h>
+#include <linux/file.h>
 #include <linux/fs.h>
+#include <linux/gpio/driver.h>
 #include <linux/hw_random.h>
+#include <linux/interrupt.h>
+#include <linux/irqdomain.h>
+#include <linux/irq.h>
+#include <linux/miscdevice.h>
+#include <linux/mm.h>
 #include <linux/module.h>
+#include <linux/of_platform.h>
+#include <linux/platform_device.h>
+#include <linux/poll.h>
 #include <linux/random.h>
+#include <linux/security.h>
 #include <linux/slab.h>
 #include <linux/sysctl.h>
 #include <linux/uaccess.h>
 #include <linux/uio.h>
-#include <linux/miscdevice.h>
-#include <linux/poll.h>
-#include <linux/mm.h>
-#include <linux/file.h>
 #include <uapi/linux/android/binder.h>
-#include <linux/platform_device.h>
-#include <linux/of_platform.h>
-#include <linux/security.h>
-#include <asm/io.h>
-#include <linux/irq.h>
-#include <linux/interrupt.h>
-#include <linux/irqdomain.h>
-#include <linux/amba/bus.h>
-#include <linux/gpio/driver.h>
 
-// `bindgen` gets confused at certain things
+/* `bindgen` gets confused at certain things. */
 const gfp_t BINDINGS_GFP_KERNEL = GFP_KERNEL;
 const gfp_t BINDINGS___GFP_ZERO = __GFP_ZERO;