* [PATCH 1/2] docs: module: start adding some docs for MODULE_ macros.
@ 2023-04-26 4:29 Dave Airlie
2023-06-22 21:14 ` Randy Dunlap
0 siblings, 1 reply; 3+ messages in thread
From: Dave Airlie @ 2023-04-26 4:29 UTC (permalink / raw)
To: dri-devel
Cc: Dave Airlie, linux-doc, Jonathan Corbet, Luis Chamberlain,
linux-modules
From: Dave Airlie <airlied@redhat.com>
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.
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Luis Chamberlain <mcgrof@kernel.org>
Cc: linux-modules@vger.kernel.org
Signed-off-by: Dave Airlie <airlied@redhat.com>
---
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(-)
diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 62f961610773..0b78b1a3e8a2 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -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
--------------------
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 4b4d8e28d3be..fea42d6cad80 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -5,7 +5,7 @@ Driver Entry and Exit points
----------------------------
.. kernel-doc:: include/linux/module.h
- :internal:
+ :identifiers: module_init module_exit
Driver device table
-------------------
diff --git a/include/linux/module.h b/include/linux/module.h
index 4435ad9439ab..f9d072a7e198 100644
--- a/include/linux/module.h
+++ b/include/linux/module.h
@@ -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;
--
2.39.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH 1/2] docs: module: start adding some docs for MODULE_ macros.
2023-04-26 4:29 Dave Airlie
@ 2023-06-22 21:14 ` Randy Dunlap
0 siblings, 0 replies; 3+ messages in thread
From: Randy Dunlap @ 2023-06-22 21:14 UTC (permalink / raw)
To: Dave Airlie, dri-devel
Cc: Dave Airlie, linux-doc, Jonathan Corbet, Luis Chamberlain,
linux-modules
On 4/25/23 21:29, Dave Airlie wrote:
> From: Dave Airlie <airlied@redhat.com>
>
> 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.
>
> Cc: linux-doc@vger.kernel.org
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Luis Chamberlain <mcgrof@kernel.org>
> Cc: linux-modules@vger.kernel.org
> Signed-off-by: Dave Airlie <airlied@redhat.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org> # for the kernel-doc
Thanks.
> ---
> 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(-)
>
> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
> index 62f961610773..0b78b1a3e8a2 100644
> --- a/Documentation/core-api/kernel-api.rst
> +++ b/Documentation/core-api/kernel-api.rst
> @@ -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
> --------------------
>
> diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
> index 4b4d8e28d3be..fea42d6cad80 100644
> --- a/Documentation/driver-api/basics.rst
> +++ b/Documentation/driver-api/basics.rst
> @@ -5,7 +5,7 @@ Driver Entry and Exit points
> ----------------------------
>
> .. kernel-doc:: include/linux/module.h
> - :internal:
> + :identifiers: module_init module_exit
>
> Driver device table
> -------------------
> diff --git a/include/linux/module.h b/include/linux/module.h
> index 4435ad9439ab..f9d072a7e198 100644
> --- a/include/linux/module.h
> +++ b/include/linux/module.h
> @@ -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;
--
~Randy
^ permalink raw reply [flat|nested] 3+ messages in thread
* [PATCH 1/2] docs: module: start adding some docs for MODULE_ macros.
[not found] <20230704025322.2623556-1-airlied@gmail.com>
@ 2023-07-04 2:50 ` Dave Airlie
0 siblings, 0 replies; 3+ messages in thread
From: Dave Airlie @ 2023-07-04 2:50 UTC (permalink / raw)
To: dri-devel, linux-modules
Cc: Dave Airlie, linux-doc, Jonathan Corbet, Luis Chamberlain
From: Dave Airlie <airlied@redhat.com>
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.
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Luis Chamberlain <mcgrof@kernel.org>
Cc: linux-modules@vger.kernel.org
Signed-off-by: Dave Airlie <airlied@redhat.com>
---
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(-)
diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 9b3f3e5f5a95..5079e48dd58c 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -226,6 +226,9 @@ Kernel module auto-loading
.. kernel-doc:: kernel/module/kmod.c
:export:
+.. kernel-doc:: include/linux/module.h
+ :no-identifiers: module_init module_exit klp_modinfo
+
Module debugging
----------------
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 4b4d8e28d3be..fea42d6cad80 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -5,7 +5,7 @@ Driver Entry and Exit points
----------------------------
.. kernel-doc:: include/linux/module.h
- :internal:
+ :identifiers: module_init module_exit
Driver device table
-------------------
diff --git a/include/linux/module.h b/include/linux/module.h
index 9e56763dff81..b255db33b40f 100644
--- a/include/linux/module.h
+++ b/include/linux/module.h
@@ -183,23 +183,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
@@ -222,20 +226,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
@@ -247,19 +257,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".
*/
@@ -285,11 +299,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;
--
2.41.0
^ permalink raw reply related [flat|nested] 3+ messages in thread
end of thread, other threads:[~2023-07-04 2:55 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <20230704025322.2623556-1-airlied@gmail.com>
2023-07-04 2:50 ` [PATCH 1/2] docs: module: start adding some docs for MODULE_ macros Dave Airlie
2023-04-26 4:29 Dave Airlie
2023-06-22 21:14 ` Randy Dunlap
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).