| Message ID | 20230426042906.724352-1-airlied@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/2] docs: module: start adding some docs for MODULE_ macros. | expand |
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;
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;