Skip to contentSkip to conversation

Add __require_explicit_initialization and its first user

PATCH In review Kees Cook 7 participants 14 messages Oct 14 – Oct 15

Subsystems (4)
lore
Share & tools
lore

Kees Cook

author
#0 lore raw

cover Add __require_explicit_initialization and its first user

Hi!

As discussed in Ian's kobj_type::release series[1], this takes its first patch (to add __require_explicit_initialization), with Miguel's requested comment tweak (the attribute needs Clang 20 or later), along with a first user that needs no fix-ups first: seq_file's seq_operations callbacks, which are called without a NULL check. This will make the attribute available in v7.4-rc1, while the kobj_type fixes continue separately.

The annotation adds no warnings anywhere in the tree today that I could find across allmodconfig builds:

Clang 24.0.0git: x86_64, arm64, i386, arm, riscv, s390, loongarch, powerpc. GCC 16.2.0: x86_64, arm64, i386, arm, riscv, s390, m68k, mips, parisc,
sparc, loongarch, xtensa, arc, and openrisc.

Thanks!

-Kees

[1] https://lore.kernel.org/all/[email protected]/

Ian Rogers (1):
Compiler Attributes: Add __require_explicit_initialization macro

Kees Cook (1):
seq_file: Require explicit initialization of struct seq_operations

 scripts/checkpatch.pl                 |  1 +
 Documentation/conf.py                 |  1 +
 include/linux/compiler_attributes.h   | 12 ++++++++++++
 include/linux/seq_file.h              | 13 +++++++++----
 tools/lib/python/kdoc/xforms_lists.py |  1 +
 5 files changed, 24 insertions(+), 4 deletions(-)
Signature · 1 line
2.55.0
author
#1 lore raw

PATCH 1/2 Compiler Attributes: Add __require_explicit_initialization macro

From: Ian Rogers <[email protected]>

Clang supports the 'require_explicit_initialization' attribute on struct fields to indicate that a field must be initialized explicitly by the user when the object is constructed. When an aggregate initializer or uninitialized variable omits an annotated field, Clang emits a -Wuninitialized-explicit-init warning (enabled by default).

Add the __require_explicit_initialization macro to include/linux/compiler_attributes.h (which is included by include/linux/compiler_types.h and include/linux/compiler.h) so kernel structs with error-prone initialization (such as mandatory callbacks or cleanup handlers) can enforce explicit initialization at compile time, as discussed at the Linux Plumbers Conference.

Also teach Sphinx (Documentation/conf.py), kernel-doc (tools/lib/python/kdoc/xforms_lists.py), and checkpatch.pl about the new attribute macro.

---
 scripts/checkpatch.pl                 |  1 +
 Documentation/conf.py                 |  1 +
 include/linux/compiler_attributes.h   | 12 ++++++++++++
 tools/lib/python/kdoc/xforms_lists.py |  1 +
 4 files changed, 15 insertions(+)
scripts/checkpatch.pl +1 -0
index 8a7787d228a6..4a3ae6b0100a 100755
@@ -6871,6 +6871,7 @@ sub process {
 				"noreturn"			=> "__noreturn",
 				"packed"			=> "__packed",
 				"pure"				=> "__pure",
+				"require_explicit_initialization" => "__require_explicit_initialization",
 				"section"			=> "__section",
 				"used"				=> "__used",
 				"weak"				=> "__weak"
Documentation/conf.py +1 -0
index 5ab26ce89daf..3e5cb9ca0970 100644
@@ -203,6 +203,7 @@ c_id_attributes = [
     "__noreturn",
     "__packed",
     "__pure",
+    "__require_explicit_initialization",
     "__section",
     "__always_unused",
     "__maybe_unused",
include/linux/compiler_attributes.h +12 -0
index 476c4c560d17..625e95e684c7 100644
@@ -322,6 +322,18 @@
  */
 #define __pure                          __attribute__((__pure__))
 
+/*
+ * Optional: not supported by gcc
+ * Optional: only supported since clang >= 20.0
+ *
+ * clang: https://clang.llvm.org/docs/AttributeReference.html#require-explicit-initialization
+ */
+#if __has_attribute(__require_explicit_initialization__)
+# define __require_explicit_initialization __attribute__((__require_explicit_initialization__))
+#else
+# define __require_explicit_initialization
+#endif
+
 /*
  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-section-function-attribute
  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-section-variable-attribute
tools/lib/python/kdoc/xforms_lists.py +1 -0
index e3dda2fe8a53..32066fbbe763 100644
@@ -36,6 +36,7 @@ class CTransforms:
         (CMatch("CRYPTO_MINALIGN_ATTR"), ""),
         (CMatch("__private"), ""),
         (CMatch("__rcu"), ""),
+        (CMatch("__require_explicit_initialization"), ""),
         (CMatch("____cacheline_aligned_in_smp"), ""),
         (CMatch("____cacheline_aligned"), ""),
         (CMatch("__cacheline_group_(?:begin|end)"), ""),
Signature · 1 line
2.55.0
author
#4 lore raw

PATCH 2/2 seq_file: Require explicit initialization of struct seq_operations

In reply to Kees Cook

In the very unlikely chance that a seq_operations didn't get initialized, we wouldn't want them calling some random location. As a first example user of __require_explicit_initialization, annotate them so a missing initializer is a compile-time warning.

Every seq_operations in the tree already sets all four, so no new warnings are added.

---
 include/linux/seq_file.h | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)
include/linux/seq_file.h +9 -4
index dc0e8c62d9e0..f0e7e52a0905 100644
@@ -28,11 +28,16 @@ struct seq_file {
 	void *private;
 };
 
+/* All four are called without checking for NULL. */
 struct seq_operations {
-	void * (*start) (struct seq_file *m, loff_t *pos);
-	void (*stop) (struct seq_file *m, void *v);
-	void * (*next) (struct seq_file *m, void *v, loff_t *pos);
-	int (*show) (struct seq_file *m, void *v);
+	void *(*start)(struct seq_file *m, loff_t *pos)
+		__require_explicit_initialization;
+	void (*stop)(struct seq_file *m, void *v)
+		__require_explicit_initialization;
+	void *(*next)(struct seq_file *m, void *v, loff_t *pos)
+		__require_explicit_initialization;
+	int (*show)(struct seq_file *m, void *v)
+		__require_explicit_initialization;
 };
 
 #define SEQ_SKIP 1
Signature · 1 line
2.55.0
Reviewed-by on v1 1/2
#2 lore raw

Re: [PATCH 1/2] Compiler Attributes: Add __require_explicit_initialization macro

In reply to Kees Cook
Quoted 19 lines · Kees Cook

From: Ian Rogers <[email protected]>

Clang supports the 'require_explicit_initialization' attribute on struct fields to indicate that a field must be initialized explicitly by the user when the object is constructed. When an aggregate initializer or uninitialized variable omits an annotated field, Clang emits a -Wuninitialized-explicit-init warning (enabled by default).

Add the __require_explicit_initialization macro to include/linux/compiler_attributes.h (which is included by include/linux/compiler_types.h and include/linux/compiler.h) so kernel structs with error-prone initialization (such as mandatory callbacks or cleanup handlers) can enforce explicit initialization at compile time, as discussed at the Linux Plumbers Conference.

Also teach Sphinx (Documentation/conf.py), kernel-doc (tools/lib/python/kdoc/xforms_lists.py), and checkpatch.pl about the new attribute macro.

Quoted 6 lines
Signature · 2 lines
Cheers,
Nathan
Acked-by on v1 1/2
#3 lore raw

Re: [PATCH 1/2] Compiler Attributes: Add __require_explicit_initialization macro

In reply to Kees Cook
Quoted 19 lines · Kees Cook

From: Ian Rogers <[email protected]>

Clang supports the 'require_explicit_initialization' attribute on struct fields to indicate that a field must be initialized explicitly by the user when the object is constructed. When an aggregate initializer or uninitialized variable omits an annotated field, Clang emits a -Wuninitialized-explicit-init warning (enabled by default).

Add the __require_explicit_initialization macro to include/linux/compiler_attributes.h (which is included by include/linux/compiler_types.h and include/linux/compiler.h) so kernel structs with error-prone initialization (such as mandatory callbacks or cleanup handlers) can enforce explicit initialization at compile time, as discussed at the Linux Plumbers Conference.

Also teach Sphinx (Documentation/conf.py), kernel-doc (tools/lib/python/kdoc/xforms_lists.py), and checkpatch.pl about the new attribute macro.

Quoted 7 lines

---

#5 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

In reply to Kees Cook
Quoted 26 lines · Kees Cook

In the very unlikely chance that a seq_operations didn't get initialized, we wouldn't want them calling some random location. As a first example user of __require_explicit_initialization, annotate them so a missing initializer is a compile-time warning.

Every seq_operations in the tree already sets all four, so no new warnings are added.

---
 include/linux/seq_file.h | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)
include/linux/seq_file.h +1 -3
index dc0e8c62d9e0..f0e7e52a0905 100644
@@ -28,11 +28,16 @@ struct seq_file {
 	void *private;
 };
 
+/* All four are called without checking for NULL. */
 struct seq_operations {
-	void * (*start) (struct seq_file *m, loff_t *pos);
-	void (*stop) (struct seq_file *m, void *v);
-	void * (*next) (struct seq_file *m, void *v, loff_t *pos);

include/linux/seq_file.h struct seq_file { · line 41

Quoted 10 lines
include/linux/seq_file.h +8 -1
-	int (*show) (struct seq_file *m, void *v);
+	void *(*start)(struct seq_file *m, loff_t *pos)
+		__require_explicit_initialization;
+	void (*stop)(struct seq_file *m, void *v)
+		__require_explicit_initialization;
+	void *(*next)(struct seq_file *m, void *v, loff_t *pos)
+		__require_explicit_initialization;
+	int (*show)(struct seq_file *m, void *v)
+		__require_explicit_initialization;
 };

Hm, I acked the first patch, but seeing this "in the wild" is interesting. Feels kind of ackward, but I don't really know what to suggest instead? What about just making the lines longer:

	void *(*start)(struct seq_file *m, loff_t *pos)		__require_explicit_initialization;
	void (*stop)(struct seq_file *m, void *v)		__require_explicit_initialization;
	void *(*next)(struct seq_file *m, void *v, loff_t *pos) __require_explicit_initialization;
	int (*show)(struct seq_file *m, void *v)		__require_explicit_initialization;

?

Anyway, I don't know. I like this feature, and maybe it's going to be used so infrequently it's not a big deal, but feels clunky.

thanks,

greg k-h

#6 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

Quoted 3 lines · Greg KH

Anyway, I don't know. I like this feature, and maybe it's going to be used so infrequently it's not a big deal, but feels clunky.

Perhaps we could call it something shorter, like __explicit_init or similar -- I don't see that substring (even without the double underscores) used anywhere.

Cheers,
Miguel

author
#7 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

Quoted 8 lines · Miguel Ojeda
Quoted 3 lines · Greg KH

Anyway, I don't know. I like this feature, and maybe it's going to be used so infrequently it's not a big deal, but feels clunky.

Perhaps we could call it something shorter, like __explicit_init or similar -- I don't see that substring (even without the double underscores) used anywhere.

That's nice, yeah. And it's not the first time we've changed the "spelling" of an attribute.

Does anyone object to that? I can replace it with that in my tree...

-Kees

Signature · 1 line
Kees Cook
#8 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

Quoted 11 lines · Kees Cook
Quoted 8 lines · Miguel Ojeda
Quoted 3 lines · Greg KH

Anyway, I don't know. I like this feature, and maybe it's going to be used so infrequently it's not a big deal, but feels clunky.

Perhaps we could call it something shorter, like __explicit_init or similar -- I don't see that substring (even without the double underscores) used anywhere.

__must_init might be smaller?

Naming is hard :)

Quoted 3 lines

That's nice, yeah. And it's not the first time we've changed the "spelling" of an attribute.

Does anyone object to that? I can replace it with that in my tree...

No objection from me to make it shorter, and yes, we can always change it going forward if someone comes up with a better term.

thanks,

greg k-h

#9 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

Quoted 2 lines · Greg KH

__must_init might be smaller?

That sounds fine too. I like that it says that something *has* to be done (like the original name did). Hmm... On the other hand, I guess "must" could sound like one has to initialize the field "somehow", i.e. writing:

  struct S s = {};

definitely initializes it, yet the compiler would warn. Would "explicit" hint a bit more at the fact that one has to actually "write" the field, even if it may have been initialized anyway?

(Of course, if one knows that the attribute only applies to fields, then it doesn't make much of a difference)

Cheers,
Miguel

#10 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

Quoted 9 lines · Miguel Ojeda
Quoted 2 lines · Greg KH

__must_init might be smaller?

That sounds fine too. I like that it says that something *has* to be done (like the original name did). Hmm... On the other hand, I guess "must" could sound like one has to initialize the field "somehow", i.e. writing:

Quoted 5 lines
  struct S s = {};

definitely initializes it, yet the compiler would warn. Would "explicit" hint a bit more at the fact that one has to actually "write" the field, even if it may have been initialized anyway?

"explicit" is a description, "must" is an action that tells the reader what they have to do, so maybe "must" is better?

Anyway, I don't care, naming is hard, either is fine with me, I'll let the authors of the patch here pick what they want :)

thanks,

greg k-h

author
#12 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

In reply to Miguel Ojeda
Quoted 9 lines · Miguel Ojeda
Quoted 2 lines · Greg KH

__must_init might be smaller?

That sounds fine too. I like that it says that something *has* to be done (like the original name did). Hmm... On the other hand, I guess "must" could sound like one has to initialize the field "somehow", i.e. writing:

Quoted 8 lines
  struct S s = {};

definitely initializes it, yet the compiler would warn. Would "explicit" hint a bit more at the fact that one has to actually "write" the field, even if it may have been initialized anyway?

(Of course, if one knows that the attribute only applies to fields, then it doesn't make much of a difference)

Hmm, I just noticed Clang isn't diagnosing for file-scoped definitions. I've opened: https://github.com/llvm/llvm-project/issues/232483

Do we want to wait on this attribute until Clang has full coverage for all initializer cases, or land the attribute so we can continue to add coverage for function-level coverage? I'm worried about a compiler bump (once the bug is fixed) suddenly exposing a bunch of missed initializers, but then again we also have no users yet...

-Kees

Signature · 1 line
Kees Cook
#13 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

Quoted 20 lines · Kees Cook
Quoted 9 lines · Miguel Ojeda
Quoted 2 lines · Greg KH

__must_init might be smaller?

That sounds fine too. I like that it says that something *has* to be done (like the original name did). Hmm... On the other hand, I guess "must" could sound like one has to initialize the field "somehow", i.e. writing:

Quoted 8 lines
  struct S s = {};

definitely initializes it, yet the compiler would warn. Would "explicit" hint a bit more at the fact that one has to actually "write" the field, even if it may have been initialized anyway?

(Of course, if one knows that the attribute only applies to fields, then it doesn't make much of a difference)

Quoted 8 lines

Hmm, I just noticed Clang isn't diagnosing for file-scoped definitions. I've opened: https://github.com/llvm/llvm-project/issues/232483

Do we want to wait on this attribute until Clang has full coverage for all initializer cases, or land the attribute so we can continue to add coverage for function-level coverage? I'm worried about a compiler bump (once the bug is fixed) suddenly exposing a bunch of missed initializers, but then again we also have no users yet...

This is a false negative, right? When it gets fixed in clang, the existing uses in globals start getting checked. Nothing that would require compiler version checks, IMO.

Quoted 5 lines

-Kees

--
Kees Cook

Signature · 2 lines
Thanks,
~Nick Desaulniers
#11 lore raw

Re: [PATCH 2/2] seq_file: Require explicit initialization of struct seq_operations

In reply to Greg KH
Quoted 17 lines · Greg KH
Quoted 9 lines · Miguel Ojeda
Quoted 2 lines · Greg KH

__must_init might be smaller?

That sounds fine too. I like that it says that something *has* to be done (like the original name did). Hmm... On the other hand, I guess "must" could sound like one has to initialize the field "somehow", i.e. writing:

Quoted 5 lines
  struct S s = {};

definitely initializes it, yet the compiler would warn. Would "explicit" hint a bit more at the fact that one has to actually "write" the field, even if it may have been initialized anyway?

Quoted 5 lines

"explicit" is a description, "must" is an action that tells the reader what they have to do, so maybe "must" is better?

Anyway, I don't care, naming is hard, either is fine with me, I'll let the authors of the patch here pick what they want :)

Fwiw, I like __must_init for being both short and intention revealing. I'll hold off sending my v2 for kobject::release to avoid renaming the attribute.

Thanks,
Ian