kernel-doc: add support for documenting vars

Specially on kAPI, sometimes it is desirable to be able to describe global variables that are part of kAPI.

Documenting vars with Sphinx is simple, as we don't need to parse a data struct. All we need is the variable declaration and use natice C domain ::c:var: to format it for us.

Add support for it.

Link https://lore.kernel.org/linux-doc/[email protected]/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 open here

Suggested-by Randy Dunlap <[email protected]>

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
 scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)

Hi,

Quoted 10 lines · Mauro Carvalho Chehab

Specially on kAPI, sometimes it is desirable to be able to describe global variables that are part of kAPI.

Documenting vars with Sphinx is simple, as we don't need to parse a data struct. All we need is the variable declaration and use natice C domain ::c:var: to format it for us.

Add support for it.

Quoted 7 lines

Link https://lore.kernel.org/linux-doc/[email protected]/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 open here

Suggested-by Randy Dunlap <[email protected]>

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
 scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)  

Thanks for the update. It's looking much better.

I have a few comments/questions, all about typedefs.

type vs typedef in output (html)

typedefs are usually output as "type":
Example 1:

type func_desc_t

although thp_order_fn_t is output as:
Example 2:

thp_order_fn_t
Typedef: Get the suggested THP orders from a BPF program for allocation
+ more syntax and description.

Is the difference in the 2 examples above just that the first one has no additional description or parameters?

3. typedef struct msi_alloc_info isn't output as a typedef at all, but instead as a struct. But the kernel-doc for this typedef is messed up (as taken from include/asm-generic/msi.h):

/**
* struct msi_alloc_info - Default structure for MSI interrupt allocation.
* @desc: Pointer to msi descriptor
* @hwirq: Associated hw interrupt number in the domain
* @scratchpad: Storage for implementation specific scratch data
*
* Architectures can provide their own implementation by not including
* asm-generic/msi.h into their arch specific header file.
*/

typedef struct msi_alloc_info {
	struct msi_desc			*desc;
	irq_hw_number_t			hwirq;
	unsigned long			flags;
	union {
		unsigned long		ul;
		void			*ptr;
	} scratchpad[NUM_MSI_ALLOC_SCRATCHPAD_REGS];
} msi_alloc_info_t;

a. It's a typedef, not a struct -- but we may want to print the struct (?).

b. The first line of the comment should be:
* typedef msi_alloc_info_t - Default structure for MSI interrupt allocation.

Hopefully a warning can be printed for this.

Em Mon, 17 Nov 2025 22:59:24 -0800
Randy Dunlap <[email protected]> escreveu:

Quoted 21 lines

Hi,

Quoted 10 lines · Mauro Carvalho Chehab

Specially on kAPI, sometimes it is desirable to be able to describe global variables that are part of kAPI.

Documenting vars with Sphinx is simple, as we don't need to parse a data struct. All we need is the variable declaration and use natice C domain ::c:var: to format it for us.

Add support for it.

Quoted 7 lines

Link https://lore.kernel.org/linux-doc/[email protected]/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 open here

Suggested-by Randy Dunlap <[email protected]>

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
 scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)  

Quoted 1 line

Thanks for the update. It's looking much better.

Great!

Quoted 1 line

I have a few comments/questions, all about typedefs.

The new version was made to be bug-compatible with the Perl version, so it just mimics whatever it was there. Both Jon and I verified to be sure that the output was identical (except for whitespaces).

If you look at dump_typedef(), typedefs can be mapped on different ways, depending on its actual meaning:

def dump_typedef(self, ln, proto):
...

# Parse function typedef prototypes
...
self.output_declaration('function', declaration_name,
typedef=True, functiontype=return_type, purpose=self.entry.declaration_purpose)
...

        #
        # Not a function, try to parse a simple typedef.
        #

...
self.output_declaration('typedef', declaration_name,
purpose=self.entry.declaration_purpose)

Also, the actual output is modified by the highlight logic at kdoc_output:

	# match expressions used to find embedded type information
	type_constant = KernRe(r"\b``([^\`]+)``\b", cache=False)
	type_constant2 = KernRe(r"\%([-_*\w]+)", cache=False)
	type_func = KernRe(r"(\w+)\(\)", cache=False)
	type_param_ref = KernRe(r"([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)

	# Special RST handling for func ptr params
	type_fp_param = KernRe(r"\@(\w+)\(\)", cache=False)

	# Special RST handling for structs with func ptr params
	type_fp_param2 = KernRe(r"\@(\w+->\S+)\(\)", cache=False)

	type_env = KernRe(r"(\$\w+)", cache=False)
	type_enum = KernRe(r"\&(enum\s*([_\w]+))", cache=False)
	type_struct = KernRe(r"\&(struct\s*([_\w]+))", cache=False)
	type_typedef = KernRe(r"\&(typedef\s*([_\w]+))", cache=False)
	type_union = KernRe(r"\&(union\s*([_\w]+))", cache=False)
	type_member = KernRe(r"\&([_\w]+)(\.|->)([_\w]+)", cache=False)
	type_fallback = KernRe(r"\&([_\w]+)", cache=False)
	type_member_func = type_member + KernRe(r"\(\)", cache=False)

	highlights = [
	    (type_constant, r"``\1``"),
	    (type_constant2, r"``\1``"),

	    # Note: need to escape () to avoid func matching later
	    (type_member_func, r":c:type:`\1\2\3\\(\\) <\1>`"),
	    (type_member, r":c:type:`\1\2\3 <\1>`"),
	    (type_fp_param, r"**\1\\(\\)**"),
	    (type_fp_param2, r"**\1\\(\\)**"),
	    (type_func, r"\1()"),
	    (type_enum, r":c:type:`\1 <\2>`"),
	    (type_struct, r":c:type:`\1 <\2>`"),
	    (type_typedef, r":c:type:`\1 <\2>`"),
	    (type_union, r":c:type:`\1 <\2>`"),

	    # in rst this can refer to any type
	    (type_fallback, r":c:type:`\1`"),
	    (type_param_ref, r"**\1\2**")
	]

On other words, "normal" typedefs use:

	type_typedef = KernRe(r"\&(typedef\s*([_\w]+))", cache=False)
	(type_typedef, r":c:type:`\1 <\2>`"),

but function typedefs have a different threatment (see out_function) at the RestFormat class.

Quoted 12 lines

type vs typedef in output (html)

typedefs are usually output as "type":
Example 1:

type func_desc_t

although thp_order_fn_t is output as:
Example 2:

Quoted 3 lines

thp_order_fn_t
Typedef: Get the suggested THP orders from a BPF program for allocation
+ more syntax and description.

I was unable to find kernel-doc markups for the above at linux-next or at docs-next.

Hard to tell without seeing the exact kernel-doc markups you're referring to, but see my comments above.

Quoted 27 lines

Is the difference in the 2 examples above just that the first one has no additional description or parameters?

3. typedef struct msi_alloc_info isn't output as a typedef at all, but instead as a struct. But the kernel-doc for this typedef is messed up (as taken from include/asm-generic/msi.h):

/**
* struct msi_alloc_info - Default structure for MSI interrupt allocation.
* @desc: Pointer to msi descriptor
* @hwirq: Associated hw interrupt number in the domain
* @scratchpad: Storage for implementation specific scratch data
*
* Architectures can provide their own implementation by not including
* asm-generic/msi.h into their arch specific header file.
*/

typedef struct msi_alloc_info {
	struct msi_desc			*desc;
	irq_hw_number_t			hwirq;
	unsigned long			flags;
	union {
		unsigned long		ul;
		void			*ptr;
	} scratchpad[NUM_MSI_ALLOC_SCRATCHPAD_REGS];
} msi_alloc_info_t;

Quoted 1 line

a. It's a typedef, not a struct -- but we may want to print the struct (?).

It is both:

struct msi_alloc_info
typedef msi_alloc_info_t

The kernel-doc declaration is for the struct, not for the typedef.

Ok, one could have two kernel-doc markups if this would be declared in separate:

	 /**
	  * struct msi_alloc_info - Default structure for MSI interrupt allocation.
...
	  */
	struct msi_alloc_info {
	 	struct msi_desc			*desc;
	 	irq_hw_number_t			hwirq;
	 	unsigned long			flags;
	 	union {
	 		unsigned long		ul;
	 		void			*ptr;

	 	} scratchpad[NUM_MSI_ALLOC_SCRATCHPAD_REGS];
	};

	 /**
	  * typedef msi_alloc_info_t - Default typedef for MSI interrupt allocation.
...
	  */
	typedef struct msi_alloc_info msi_alloc_info_t;

Quoted 2 lines

b. The first line of the comment should be:
* typedef msi_alloc_info_t - Default structure for MSI interrupt allocation.

Quoted 1 line

Hopefully a warning can be printed for this.

It won't be hard to add a warning, but the point is that, in this specific case, the intent seems to document only the struct to ensure that newer usages won't use typedef anymore.

Also, right now, we don't produce any warning if one does:

	 /**
	  * struct msi_alloc_info - Default structure for MSI interrupt allocation.
...
	  */
	struct msi_alloc_info {
	 	struct msi_desc			*desc;
	 	irq_hw_number_t			hwirq;
	 	unsigned long			flags;
	 	union {
	 		unsigned long		ul;
	 		void			*ptr;
	 	} scratchpad[NUM_MSI_ALLOC_SCRATCHPAD_REGS];
	};

	typedef struct msi_alloc_info msi_alloc_info_t;

So, what's the point of having a warning?

Em Mon, 17 Nov 2025 22:59:24 -0800
Randy Dunlap <[email protected]> escreveu:

Quoted 21 lines

Hi,

Quoted 17 lines · Mauro Carvalho Chehab

Specially on kAPI, sometimes it is desirable to be able to describe global variables that are part of kAPI.

Documenting vars with Sphinx is simple, as we don't need to parse a data struct. All we need is the variable declaration and use natice C domain ::c:var: to format it for us.

Add support for it.

Link https://lore.kernel.org/linux-doc/[email protected]/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 open here

Suggested-by Randy Dunlap <[email protected]>

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
 scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)  

Quoted 1 line

Thanks for the update. It's looking much better.

Great!

Quoted 1 line

I have a few comments/questions, all about typedefs.

Quoted 24 lines

Em Mon, 17 Nov 2025 22:59:24 -0800
Randy Dunlap <[email protected]> escreveu:

Quoted 21 lines

Hi,

Quoted 17 lines · Mauro Carvalho Chehab

Specially on kAPI, sometimes it is desirable to be able to describe global variables that are part of kAPI.

Documenting vars with Sphinx is simple, as we don't need to parse a data struct. All we need is the variable declaration and use natice C domain ::c:var: to format it for us.

Add support for it.

Link https://lore.kernel.org/linux-doc/[email protected]/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 open here

Suggested-by Randy Dunlap <[email protected]>

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
 scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)    

Quoted 6 lines

Quoted 1 line

Thanks for the update. It's looking much better.

Great!

Quoted 1 line

I have a few comments/questions, all about typedefs.

Hi Mauro,

I just noticed that in my sample init/kdoc-globals-test.c file (I have s/global/var/ in it), there is one global var that is missing or misparsed:

// from net/core/rtnetlink.c:
/**
* var rtnl_mutex - historical global lock for networking control operations. *
* @rtnl_mutex is used to serialize rtnetlink requests
* and protect all kernel internal data structures related to networking. *
* See Documentation/networking/netdevices.rst for details.
* Often known as the rtnl_lock, although rtnl_lock is a kernel function. */
static DEFINE_MUTEX(rtnl_mutex);

This var is completely missing in the html output.

In the man output,
it is rendered like this:

NAME
static DEFINE_MUTEX - historical global lock for networking control op‐ erations.

SYNOPSIS

       static DEFINE_MUTEX;

Description
rtnl_mutex is used to serialize rtnetlink requests and protect all ker‐
nel internal data structures related to networking. See Documenta‐
tion/networking/netdevices.rst for details. Often known as the
rtnl_lock, although rtnl_lock is a kernel function.

The media kAPI has two global variables at v4l2-ioctl.h. Document them.

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 include/media/v4l2-ioctl.h | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

include/media/v4l2-ioctl.h +15 -0

index 6f7a58350441..ed63841a100c 100644
@@ -663,7 +663,22 @@ void v4l_printk_ioctl(const char *prefix, unsigned int cmd);
 struct video_device;
 
 /* names for fancy debug output */
+
+/**
+ * var v4l2_field_names - Helper array mapping V4L2_FIELD_* to strings.
+ *
+ * Specially when printing debug messages, it is interesting to output
+ * the field order at the V4L2 buffers. This array associates all possible
+ * values of field pix format from V4L2 API into a string.
+ */
 extern const char *v4l2_field_names[];
+
+/**
+ * var v4l2_type_names - Helper array mapping V4L2_BUF_TYPE_* to strings.
+ *
+ * When printing debug messages, it is interesting to output the V4L2 buffer
+ * type number with a name that represents its content.
+ */
 extern const char *v4l2_type_names[];
 
 #ifdef CONFIG_COMPAT

Hi Jon,

As suggested and discussed with Randy, this small series add support for documenting variables using kernel-doc.

The first patch adds support for it.
The second one documents two variables from media.

While two documented variables are part of kAPI, I'm documenting them mostly aiming to test the new feature, as those are meant to be used for debugging messages, so we could live without having them documented.

I'm pretty sure we'll likely need to improve the parser regexes to catch everything. For instance, I had to add a logic on v3 due to the choice I did for the vars, which are pointers.

Mauro Carvalho Chehab (2):
kernel-doc: add support for handling global variables
docs: media: v4l2-ioctl.h: document two global variables

 include/media/v4l2-ioctl.h      | 15 +++++++++
 scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
 scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
 3 files changed, 115 insertions(+), 1 deletion(-)