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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




On 4/25/23 21:29, Dave Airlie wrote:
> From: Dave Airlie <airlied@xxxxxxxxxx>
> 
> 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@xxxxxxxxxxxxxxx
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: Luis Chamberlain <mcgrof@xxxxxxxxxx>
> Cc: linux-modules@xxxxxxxxxxxxxxx
> Signed-off-by: Dave Airlie <airlied@xxxxxxxxxx>

Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> # 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



[Index of Archives]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [Big List of Linux Books]

  Powered by Linux