From 66c222a02fadfd7cc62c754c12379d6bb08eaf77 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 29 Oct 2016 10:35:23 -0200 Subject: [PATCH] edac: fix kernel-doc tags at the drivers/edac_*.h Some kernel-doc tags don't provide good descriptions or use a different style. Adjust them. Signed-off-by: Mauro Carvalho Chehab --- Documentation/admin-guide/ras.rst | 2 +- drivers/edac/edac_mc.h | 55 ++++++++++++++++++++----------- 2 files changed, 36 insertions(+), 21 deletions(-) diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/ras.rst index 2f8706bae5a4..d71340e86c27 100644 --- a/Documentation/admin-guide/ras.rst +++ b/Documentation/admin-guide/ras.rst @@ -843,7 +843,7 @@ Module parameters EDAC device type ---------------- -In the header file, edac_core.h, there is a series of edac_device structures +In the header file, edac_pci.h, there is a series of edac_device structures and APIs for the EDAC_DEVICE. User space access to an edac_device is through the sysfs interface. diff --git a/drivers/edac/edac_mc.h b/drivers/edac/edac_mc.h index dcc2c7e3b8bc..50fc1dc9c0d8 100644 --- a/drivers/edac/edac_mc.h +++ b/drivers/edac/edac_mc.h @@ -15,6 +15,8 @@ * Refactored for multi-source files: * Doug Thompson * + * Please look at Documentation/driver-api/edac.rst for more info about + * EDAC core structs and functions. */ #ifndef _EDAC_MC_H_ @@ -94,7 +96,8 @@ do { \ #define to_mci(k) container_of(k, struct mem_ctl_info, dev) /** - * edac_mc_alloc: Allocate and partially fill a struct mem_ctl_info structure + * edac_mc_alloc() - Allocate and partially fill a struct &mem_ctl_info. + * * @mc_num: Memory controller number * @n_layers: Number of MC hierarchy layers * @layers: Describes each layer as seen by the Memory Controller @@ -116,8 +119,8 @@ do { \ * on such scenarios, as grouping the multiple ranks require drivers change. * * Returns: - * On failure: NULL - * On success: struct mem_ctl_info pointer + * On success, return a pointer to struct mem_ctl_info pointer; + * %NULL otherwise */ struct mem_ctl_info *edac_mc_alloc(unsigned mc_num, unsigned n_layers, @@ -125,28 +128,28 @@ struct mem_ctl_info *edac_mc_alloc(unsigned mc_num, unsigned sz_pvt); /** - * edac_mc_add_mc_with_groups: Insert the 'mci' structure into the mci - * global list and create sysfs entries associated with mci structure + * edac_mc_add_mc_with_groups() - Insert the @mci structure into the mci + * global list and create sysfs entries associated with @mci structure. + * * @mci: pointer to the mci structure to be added to the list * @groups: optional attribute groups for the driver-specific sysfs entries * - * Return: - * 0 Success - * !0 Failure + * Returns: + * 0 on Success, or an error code on failure */ extern int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci, const struct attribute_group **groups); #define edac_mc_add_mc(mci) edac_mc_add_mc_with_groups(mci, NULL) /** - * edac_mc_free - * 'Free' a previously allocated 'mci' structure + * edac_mc_free() - Frees a previously allocated @mci structure + * * @mci: pointer to a struct mem_ctl_info structure */ extern void edac_mc_free(struct mem_ctl_info *mci); /** - * edac_mc_find: Search for a mem_ctl_info structure whose index is @idx. + * edac_mc_find() - Search for a mem_ctl_info structure whose index is @idx. * * @idx: index to be seek * @@ -156,29 +159,41 @@ extern void edac_mc_free(struct mem_ctl_info *mci); extern struct mem_ctl_info *edac_mc_find(int idx); /** - * find_mci_by_dev + * find_mci_by_dev() - Scan list of controllers looking for the one that + * manages the @dev device. * - * scan list of controllers looking for the one that manages - * the 'dev' device * @dev: pointer to a struct device related with the MCI + * + * Returns: on success, returns a pointer to struct &mem_ctl_info; + * %NULL otherwise. */ extern struct mem_ctl_info *find_mci_by_dev(struct device *dev); /** - * edac_mc_del_mc: Remove sysfs entries for specified mci structure and - * remove mci structure from global list + * edac_mc_del_mc() - Remove sysfs entries for mci structure associated with + * @dev and remove mci structure from global list. * * @dev: Pointer to struct &device representing mci structure to remove. * - * Returns: pointer to removed mci structure, or NULL if device not found. + * Returns: pointer to removed mci structure, or %NULL if device not found. */ extern struct mem_ctl_info *edac_mc_del_mc(struct device *dev); + +/** + * edac_mc_find_csrow_by_page() - Ancillary routine to identify what csrow + * contains a memory page. + * + * @mci: pointer to a struct mem_ctl_info structure + * @page: memory page to find + * + * Returns: on success, returns the csrow. -1 if not found. + */ extern int edac_mc_find_csrow_by_page(struct mem_ctl_info *mci, unsigned long page); /** - * edac_raw_mc_handle_error - reports a memory event to userspace without doing - * anything to discover the error location + * edac_raw_mc_handle_error() - Reports a memory event to userspace without + * doing anything to discover the error location. * * @type: severity of the error (CE/UE/Fatal) * @mci: a struct mem_ctl_info pointer @@ -193,7 +208,7 @@ void edac_raw_mc_handle_error(const enum hw_event_mc_err_type type, struct edac_raw_error_desc *e); /** - * edac_mc_handle_error - reports a memory event to userspace + * edac_mc_handle_error() - Reports a memory event to userspace. * * @type: severity of the error (CE/UE/Fatal) * @mci: a struct mem_ctl_info pointer -- 2.20.1