Skip to contentSkip to conversation

docs: module: start adding some docs for MODULE_ macros.

PATCH In review Dave Airlie 4 participants 6 messages Apr 26, 2023 – Jun 30, 2023

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/2 docs: module: start adding some docs for MODULE_ macros.

From: Dave Airlie <[email protected]>

In order to add a new macro, Luis suggested converting some docs for the new ones.

This tries to keep exisiting module_init, module_exit where they are, and adds the new docs to the module section.

---
 Documentation/core-api/kernel-api.rst |  3 ++
 Documentation/driver-api/basics.rst   |  2 +-
 include/linux/module.h                | 76 ++++++++++++++++++---------
 3 files changed, 54 insertions(+), 27 deletions(-)
Documentation/core-api/kernel-api.rst +3 -0
index 62f961610773..0b78b1a3e8a2 100644
@@ -226,6 +226,9 @@ Module Loading
 .. kernel-doc:: kernel/kmod.c
    :export:
 
+.. kernel-doc:: include/linux/module.h
+   :no-identifiers: module_init module_exit klp_modinfo
+
 Inter Module support
 --------------------
 
Documentation/driver-api/basics.rst +1 -1
index 4b4d8e28d3be..fea42d6cad80 100644
@@ -5,7 +5,7 @@ Driver Entry and Exit points
 ----------------------------
 
 .. kernel-doc:: include/linux/module.h
-   :internal:
+   :identifiers: module_init module_exit
 
 Driver device table
 -------------------
include/linux/module.h +50 -26

123 lines not on this page · raw message

Signature · 1 line
2.39.2
#1 lore raw

PATCH 2/2 modules/firmware: add a new option to denote a firmware group to choose one.

From: Dave Airlie <[email protected]>

This adds a tag that will go into the module info, only one firmware from the group given needs to be available for this driver to work. This allows dracut to avoid adding in firmware that aren't needed.

This just brackets a module list in the modinfo, the modules in the list will get entries in reversed order so the last module in the list is the preferred one.

The corresponding dracut code it at:
https://github.com/dracutdevs/dracut/pull/2309

---
 include/linux/module.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
include/linux/module.h +22 -0
index f9d072a7e198..d3e7085cedd0 100644
@@ -306,6 +306,28 @@ extern typeof(name) __mod_##type##__##name##_device_table		\
  */
 #define MODULE_FIRMWARE(_firmware) MODULE_INFO(firmware, _firmware)
 
+/**
+ * MODULE_FIRMWARE_GROUP_ONLY_ONE - Create a need only one firmware group
+ * @_grpname: group name
+ *
+ * This creates a group of which the driver only needs one firmware installed.
+ * This is to allow dracut to limit the number of firmwares in the initramfs.
+ * This just creates a new entry in the modinfo section, there should be one
+ * of these entries bracketing the group of MODULE_INFO lines.
+ * Due to how modinfo is constructed the ordering of the modinfo means the
+ * last module info in the group will end up being the first one dracut will
+ * search for, so place the newest firmware last.
+ *
+ * ``MODULE_FIRMWARE_GROUP_ONLY_ONE("mygroup")``
+ *
+ * ``MODULE_FIRMWARE("firmwarev1")``
+ *
+ * ``MODULE_FIRMWARE("firmwarev2")``
+ *
+ * ``MODULE_FIRMWARE_GROUP_ONLY_ONE("mygroup")``
+ */
+#define MODULE_FIRMWARE_GROUP_ONLY_ONE(_grpname) MODULE_INFO(firmware_group_only_one, _grpname)
+
 /**
  * MODULE_IMPORT_NS - Set the symbol namespace for the module.
  * @ns: symbol namespace to import the module into.
Signature · 1 line
2.39.2
Reviewed-by on v1 2/2
#2 lore raw

Re: [PATCH 2/2] modules/firmware: add a new option to denote a firmware group to choose one.

Quoted 11 lines · Dave Airlie

From: Dave Airlie <[email protected]>

This adds a tag that will go into the module info, only one firmware from the group given needs to be available for this driver to work. This allows dracut to avoid adding in firmware that aren't needed.

This just brackets a module list in the modinfo, the modules in the list will get entries in reversed order so the last module in the list is the preferred one.

Quoted 7 lines

The corresponding dracut code it at:
https://github.com/dracutdevs/dracut/pull/2309

I think this is a very useful feature,

Quoted 40 lines
---
 include/linux/module.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
include/linux/module.h +22 -1
index f9d072a7e198..d3e7085cedd0 100644
@@ -306,6 +306,28 @@ extern typeof(name) __mod_##type##__##name##_device_table          \
  */
 #define MODULE_FIRMWARE(_firmware) MODULE_INFO(firmware, _firmware)
 
+/**
+ * MODULE_FIRMWARE_GROUP_ONLY_ONE - Create a need only one firmware group
+ * @_grpname: group name
+ *
+ * This creates a group of which the driver only needs one firmware installed.
+ * This is to allow dracut to limit the number of firmwares in the initramfs.
+ * This just creates a new entry in the modinfo section, there should be one
+ * of these entries bracketing the group of MODULE_INFO lines.
+ * Due to how modinfo is constructed the ordering of the modinfo means the
+ * last module info in the group will end up being the first one dracut will
+ * search for, so place the newest firmware last.
+ *
+ * ``MODULE_FIRMWARE_GROUP_ONLY_ONE("mygroup")``
+ *
+ * ``MODULE_FIRMWARE("firmwarev1")``
+ *
+ * ``MODULE_FIRMWARE("firmwarev2")``
+ *
+ * ``MODULE_FIRMWARE_GROUP_ONLY_ONE("mygroup")``
+ */
+#define MODULE_FIRMWARE_GROUP_ONLY_ONE(_grpname) MODULE_INFO(firmware_group_only_one, _grpname)
+
 /**
  * MODULE_IMPORT_NS - Set the symbol namespace for the module.
  * @ns: symbol namespace to import the module into.
--

2.39.2

reviewer Tested-by on v1 2/2
#3 lore raw

Re: [PATCH 2/2] modules/firmware: add a new option to denote a firmware group to choose one.

In reply to Dave Airlie
Quoted 26 lines · Dave Airlie

From: Dave Airlie <[email protected]>

This adds a tag that will go into the module info, only one firmware from the group given needs to be available for this driver to work. This allows dracut to avoid adding in firmware that aren't needed.

This just brackets a module list in the modinfo, the modules in the list will get entries in reversed order so the last module in the list is the preferred one.

The corresponding dracut code it at:
https://github.com/dracutdevs/dracut/pull/2309

---
 include/linux/module.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
include/linux/module.h +0 -0
index f9d072a7e198..d3e7085cedd0 100644

include/linux/module.h extern typeof(name) __mod_##type##__##name##_device_table \ · line 310

Quoted 5 lines
include/linux/module.h +2 -0
@@ -306,6 +306,28 @@ extern typeof(name) __mod_##type##__##name##_device_table		\
  */
 #define MODULE_FIRMWARE(_firmware) MODULE_INFO(firmware, _firmware)
 
+/**
+ * MODULE_FIRMWARE_GROUP_ONLY_ONE - Create a need only one firmware group

need-only-one

include/linux/module.h extern typeof(name) __mod_##type##__##name##_device_table \ · line 315

Quoted 5 lines
include/linux/module.h +5 -0
+ * @_grpname: group name
+ *
+ * This creates a group of which the driver only needs one firmware installed.
+ * This is to allow dracut to limit the number of firmwares in the initramfs.
+ * This just creates a new entry in the modinfo section, there should be one
                                                   section;
Quoted 8 lines
include/linux/module.h +8 -0
+ * of these entries bracketing the group of MODULE_INFO lines.
+ * Due to how modinfo is constructed the ordering of the modinfo means the
+ * last module info in the group will end up being the first one dracut will
+ * search for, so place the newest firmware last.
+ *
+ * ``MODULE_FIRMWARE_GROUP_ONLY_ONE("mygroup")``
+ *
+ * ``MODULE_FIRMWARE("firmwarev1")``

include/linux/module.h extern typeof(name) __mod_##type##__##name##_device_table \ · line 333

Quoted 10 lines
include/linux/module.h +7 -0
+ *
+ * ``MODULE_FIRMWARE("firmwarev2")``
+ *
+ * ``MODULE_FIRMWARE_GROUP_ONLY_ONE("mygroup")``
+ */
+#define MODULE_FIRMWARE_GROUP_ONLY_ONE(_grpname) MODULE_INFO(firmware_group_only_one, _grpname)
+
 /**
  * MODULE_IMPORT_NS - Set the symbol namespace for the module.
  * @ns: symbol namespace to import the module into.

Is this going anywhere? It was posted about 2 months ago.

thanks.

Signature · 1 line
~Randy
maintainer
#4 lore raw

Re: [PATCH 2/2] modules/firmware: add a new option to denote a firmware group to choose one.

Quoted 1 line · Randy Dunlap

Is this going anywhere? It was posted about 2 months ago.

Last I heard Dave was still working with Lucas on this?

Luis

reviewer Tested-by on v1 1/2
#5 lore raw
In reply to Dave Airlie
Quoted 5 lines · Dave Airlie

From: Dave Airlie <[email protected]>

In order to add a new macro, Luis suggested converting some docs for the new ones.

Quoted 8 lines

This tries to keep exisiting module_init, module_exit where they are, and adds the new docs to the module section.

Thanks.

Quoted 164 lines
---
 Documentation/core-api/kernel-api.rst |  3 ++
 Documentation/driver-api/basics.rst   |  2 +-
 include/linux/module.h                | 76 ++++++++++++++++++---------
 3 files changed, 54 insertions(+), 27 deletions(-)
Documentation/core-api/kernel-api.rst +3 -0
index 62f961610773..0b78b1a3e8a2 100644
@@ -226,6 +226,9 @@ Module Loading
 .. kernel-doc:: kernel/kmod.c
    :export:
 
+.. kernel-doc:: include/linux/module.h
+   :no-identifiers: module_init module_exit klp_modinfo
+
 Inter Module support
 --------------------
 
Documentation/driver-api/basics.rst +1 -1
index 4b4d8e28d3be..fea42d6cad80 100644
@@ -5,7 +5,7 @@ Driver Entry and Exit points
 ----------------------------
 
 .. kernel-doc:: include/linux/module.h
-   :internal:
+   :identifiers: module_init module_exit
 
 Driver device table
 -------------------
include/linux/module.h +50 -26
index 4435ad9439ab..f9d072a7e198 100644
@@ -182,23 +182,27 @@ extern void cleanup_module(void);
 #define MODULE_FILE	MODULE_INFO(file, KBUILD_MODFILE);
 #endif
 
-/*
+/**
+ * MODULE_LICENSE - module license
+ * @_license: license covering this module.
+ *
  * The following license idents are currently accepted as indicating free
  * software modules
  *
- *	"GPL"				[GNU Public License v2]
- *	"GPL v2"			[GNU Public License v2]
- *	"GPL and additional rights"	[GNU Public License v2 rights and more]
- *	"Dual BSD/GPL"			[GNU Public License v2
- *					 or BSD license choice]
- *	"Dual MIT/GPL"			[GNU Public License v2
- *					 or MIT license choice]
- *	"Dual MPL/GPL"			[GNU Public License v2
- *					 or Mozilla license choice]
+ *    "GPL"                        [GNU Public License v2]
  *
- * The following other idents are available
+ *    "GPL v2"                     [GNU Public License v2]
  *
- *	"Proprietary"			[Non free products]
+ *    "GPL and additional rights"  [GNU Public License v2 rights and more]
+ *
+ *    "Dual BSD/GPL"               [GNU Public License v2 or BSD license choice]
+ *
+ *    "Dual MIT/GPL"               [GNU Public License v2 or MIT license choice]
+ *
+ *    "Dual MPL/GPL"               [GNU Public License v2 or Mozilla license choice]
+ *
+ * The following other idents are available
+ *    "Proprietary"                [Non free products]
  *
  * Both "GPL v2" and "GPL" (the latter also in dual licensed strings) are
  * merely stating that the module is licensed under the GPL v2, but are not
@@ -221,20 +225,26 @@ extern void cleanup_module(void);
  * is a GPL combined work.
  *
  * This exists for several reasons
- * 1.	So modinfo can show license info for users wanting to vet their setup
- *	is free
+ *
+ * 1.	So modinfo can show license info for users wanting to vet their setup is free
+ *
  * 2.	So the community can ignore bug reports including proprietary modules
+ *
  * 3.	So vendors can do likewise based on their own policies
  */
 #define MODULE_LICENSE(_license) MODULE_FILE MODULE_INFO(license, _license)
 
-/*
- * Author(s), use "Name <email>" or just "Name", for multiple
- * authors use multiple MODULE_AUTHOR() statements/lines.
+/**
+ * MODULE_AUTHOR - Module author
+ * @_author: Author(s), use "Name <email>" or just "Name", for multiple
+ *           authors use multiple MODULE_AUTHOR() statements/lines.
  */
 #define MODULE_AUTHOR(_author) MODULE_INFO(author, _author)
 
-/* What your module does. */
+/**
+ * MODULE_DESCRIPTION - Module description
+ * @_description: What your module does.
+ */
 #define MODULE_DESCRIPTION(_description) MODULE_INFO(description, _description)
 
 #ifdef MODULE
@@ -246,19 +256,23 @@ extern typeof(name) __mod_##type##__##name##_device_table		\
 #define MODULE_DEVICE_TABLE(type, name)
 #endif
 
-/* Version of form [<epoch>:]<version>[-<extra-version>].
+/**
+ * MODULE_VERSION: version of module
+ * @_version: version in the form below
+ *
+ * Version of form [<epoch>:]<version>[-<extra-version>].
  * Or for CVS/RCS ID version, everything but the number is stripped.
  * <epoch>: A (small) unsigned integer which allows you to start versions
  * anew. If not mentioned, it's zero.  eg. "2:1.0" is after
  * "1:2.0".
-
+ *
  * <version>: The <version> may contain only alphanumerics and the
- * character `.'.  Ordered by numeric sort for numeric parts,
+ * character '.'.  Ordered by numeric sort for numeric parts,
  * ascii sort for ascii parts (as per RPM or DEB algorithm).
-
+ *
  * <extraversion>: Like <version>, but inserted for local
  * customizations, eg "rh3" or "rusty1".
-
+ *
  * Using this automatically adds a checksum of the .c files and the
  * local headers in "srcversion".
  */
@@ -284,11 +298,21 @@ extern typeof(name) __mod_##type##__##name##_device_table		\
 		}
 #endif
 
-/* Optional firmware file (or files) needed by the module
- * format is simply firmware file name.  Multiple firmware
- * files require multiple MODULE_FIRMWARE() specifiers */
+/**
+ * MODULE_FIRMWARE - Optional firmware files needed by the module
+ * @_firmware: firmware file name
+ *
+ * Multiple firmware files require multiple MODULE_FIRMWARE() specifiers.
+ */
 #define MODULE_FIRMWARE(_firmware) MODULE_INFO(firmware, _firmware)
 
+/**
+ * MODULE_IMPORT_NS - Set the symbol namespace for the module.
+ * @ns: symbol namespace to import the module into.
+ *
+ * This adds a modinfo tag 'import_ns' to the module. This is observed
+ * by userspace at module loading time.
+ */
 #define MODULE_IMPORT_NS(ns)	MODULE_INFO(import_ns, __stringify(ns))
 
 struct notifier_block;
Signature · 1 line
~Randy