Re: [PATCH 20/20] misc: genwqe: card_utils: Whole a plethora of documentation issues

[haver <haver@linux.vnet.ibm.com>]

On 2020-06-29 16:04, Lee Jones wrote:
> Including; demoting file header from kerneldoc to standard comment/
> header, adding a variety of missing function argument documentation,
> repairing formatting (kerneldoc does not like blank lines) and the
> demotion of a kerneldoc header which shows no interest in providing
> documentation for any of its arguments.
> 
> Fixes this the following W=1 issues:
> 
>  drivers/misc/genwqe/card_utils.c:37: warning: Incorrect use of
> kernel-doc format:  * __genwqe_writeq() - Write 64-bit register
>  drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or
> member 'cd' not described in '__genwqe_writeq'
>  drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or
> member 'byte_offs' not described in '__genwqe_writeq'
>  drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or
> member 'val' not described in '__genwqe_writeq'
>  drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or
> member 'cd' not described in 'genwqe_read_app_id'
>  drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or
> member 'app_name' not described in 'genwqe_read_app_id'
>  drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or
> member 'len' not described in 'genwqe_read_app_id'
>  drivers/misc/genwqe/card_utils.c:186: warning: bad line:
>  drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
> member 'cd' not described in 'genwqe_alloc_sync_sgl'
>  drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
> member 'sgl' not described in 'genwqe_alloc_sync_sgl'
>  drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
> member 'user_addr' not described in 'genwqe_alloc_sync_sgl'
>  drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
> member 'user_size' not described in 'genwqe_alloc_sync_sgl'
>  drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
> member 'write' not described in 'genwqe_alloc_sync_sgl'
>  drivers/misc/genwqe/card_utils.c:469: warning: Function parameter or
> member 'cd' not described in 'genwqe_free_sync_sgl'
>  drivers/misc/genwqe/card_utils.c:469: warning: Function parameter or
> member 'sgl' not described in 'genwqe_free_sync_sgl'
>  drivers/misc/genwqe/card_utils.c:716: warning: Function parameter or
> member 'count' not described in 'genwqe_set_interrupt_capability'
>  drivers/misc/genwqe/card_utils.c:747: warning: Function parameter or
> member 'idx' not described in 'set_reg_idx'
>  drivers/misc/genwqe/card_utils.c:747: warning: Excess function
> parameter 'index' description in 'set_reg_idx'
>  drivers/misc/genwqe/card_utils.c:823: warning: Function parameter or
> member 'cd' not described in 'genwqe_ffdc_buff_size'
>  drivers/misc/genwqe/card_utils.c:823: warning: Function parameter or
> member 'uid' not described in 'genwqe_ffdc_buff_size'
>  drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
> member 'cd' not described in 'genwqe_ffdc_buff_read'
>  drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
> member 'uid' not described in 'genwqe_ffdc_buff_read'
>  drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
> member 'regs' not described in 'genwqe_ffdc_buff_read'
>  drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
> member 'max_regs' not described in 'genwqe_ffdc_buff_read'
>  drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
> member 'cd' not described in 'genwqe_write_vreg'
>  drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
> member 'reg' not described in 'genwqe_write_vreg'
>  drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
> member 'val' not described in 'genwqe_write_vreg'
>  drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
> member 'func' not described in 'genwqe_write_vreg'
>  drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or
> member 'cd' not described in 'genwqe_read_vreg'
>  drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or
> member 'reg' not described in 'genwqe_read_vreg'
>  drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or
> member 'func' not described in 'genwqe_read_vreg'
>  drivers/misc/genwqe/card_utils.c:995: warning: Function parameter or
> member 'cd' not described in 'genwqe_base_clock_frequency'
>  drivers/misc/genwqe/card_utils.c:1012: warning: Function parameter or
> member 'cd' not described in 'genwqe_stop_traps'
>  drivers/misc/genwqe/card_utils.c:1022: warning: Function parameter or
> member 'cd' not described in 'genwqe_start_traps'
> 
> Cc: Michael Jung <mijung@gmx.net>
> Cc: Michael Ruettger <michael@ibmra.de>
> Cc: Frank Haverkamp <haver@linux.ibm.com>
> Cc: Joerg-Stephan Vogt <jsvogt@de.ibm.com>
> Signed-off-by: Lee Jones <lee.jones@linaro.org>
> 
>  # Please enter the commit message for your changes. Lines starting
>  # with '#' will be ignored, and an empty message aborts the commit.
>  #
>  # Date:      Mon Jun 29 10:30:56 2020 +0100
>  #
>  # On branch tb-mfd-fix-warnings
>  # Changes to be committed:
>  #	modified:   drivers/misc/genwqe/card_utils.c
>  #
>  # Untracked files:
>  #	qemu-i2c-devs.txt
>  #
> ---
>  drivers/misc/genwqe/card_utils.c | 30 ++++++++++++++++++++++++++----
>  1 file changed, 26 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/misc/genwqe/card_utils.c 
> b/drivers/misc/genwqe/card_utils.c
> index 77c21caf2acd1..039b923d1d60a 100644
> --- a/drivers/misc/genwqe/card_utils.c
> +++ b/drivers/misc/genwqe/card_utils.c
> @@ -1,5 +1,5 @@
>  // SPDX-License-Identifier: GPL-2.0-only
> -/**
> +/*
>   * IBM Accelerator Family 'GenWQE'
>   *
>   * (C) Copyright IBM Corp. 2013
> @@ -129,6 +129,9 @@ u32 __genwqe_readl(struct genwqe_dev *cd, u64 
> byte_offs)
> 
>  /**
>   * genwqe_read_app_id() - Extract app_id
> + * @cd:	        genwqe device descriptor
> + * @app_name:   carrier used to pass-back name
> + * @len:        length of data for name
>   *
>   * app_unitcfg need to be filled with valid data first
>   */
> @@ -183,7 +186,7 @@ void genwqe_init_crc32(void)
>   * @init:       initial crc (0xffffffff at start)
>   *
>   * polynomial = x^32 * + x^29 + x^18 + x^14 + x^3 + 1 (0x20044009)
> -
> + *
>   * Example: 4 bytes 0x01 0x02 0x03 0x04 with init=0xffffffff should
>   * result in a crc32 of 0xf33cb7d3.
>   *
> @@ -277,7 +280,7 @@ static int genwqe_sgl_size(int num_pages)
>  	return roundup(len, PAGE_SIZE);
>  }
> 
> -/**
> +/*
>   * genwqe_alloc_sync_sgl() - Allocate memory for sgl and overlapping 
> pages
>   *
>   * Allocates memory for sgl and overlapping pages. Pages which might
> @@ -460,6 +463,8 @@ int genwqe_setup_sgl(struct genwqe_dev *cd, struct
> genwqe_sgl *sgl,
> 
>  /**
>   * genwqe_free_sync_sgl() - Free memory for sgl and overlapping pages
> + * @cd:	        genwqe device descriptor
> + * @sgl:        scatter gather list describing user-space memory
>   *
>   * After the DMA transfer has been completed we free the memory for
>   * the sgl and the cached pages. Data is being transferred from cached
> @@ -710,6 +715,7 @@ int genwqe_read_softreset(struct genwqe_dev *cd)
>  /**
>   * genwqe_set_interrupt_capability() - Configure MSI capability 
> structure
>   * @cd:         pointer to the device
> + * @count:      number of vectors to allocate
>   * Return: 0 if no error
>   */
>  int genwqe_set_interrupt_capability(struct genwqe_dev *cd, int count)
> @@ -738,7 +744,7 @@ void genwqe_reset_interrupt_capability(struct
> genwqe_dev *cd)
>   * @i:          index to desired entry
>   * @m:          maximum possible entries
>   * @addr:       addr which is read
> - * @index:      index in debug array
> + * @idx:        index in debug array
>   * @val:        read value
>   */
>  static int set_reg_idx(struct genwqe_dev *cd, struct genwqe_reg *r,
> @@ -818,6 +824,8 @@ int genwqe_read_ffdc_regs(struct genwqe_dev *cd,
> struct genwqe_reg *regs,
> 
>  /**
>   * genwqe_ffdc_buff_size() - Calculates the number of dump registers
> + * @cd:	        genwqe device descriptor
> + * @uid:	unit ID
>   */
>  int genwqe_ffdc_buff_size(struct genwqe_dev *cd, int uid)
>  {
> @@ -871,6 +879,10 @@ int genwqe_ffdc_buff_size(struct genwqe_dev *cd, 
> int uid)
> 
>  /**
>   * genwqe_ffdc_buff_read() - Implements LogoutExtendedErrorRegisters 
> procedure
> + * @cd:	        genwqe device descriptor
> + * @uid:	unit ID
> + * @regs:       register information
> + * @max_regs:   number of register entries
>   */
>  int genwqe_ffdc_buff_read(struct genwqe_dev *cd, int uid,
>  			  struct genwqe_reg *regs, unsigned int max_regs)
> @@ -956,6 +968,10 @@ int genwqe_ffdc_buff_read(struct genwqe_dev *cd, 
> int uid,
> 
>  /**
>   * genwqe_write_vreg() - Write register in virtual window
> + * @cd:	        genwqe device descriptor
> + * @reg:	register (byte) offset within BAR
> + * @val:	value to write
> + * @func:	PCI virtual function
>   *
>   * Note, these registers are only accessible to the PF through the
>   * VF-window. It is not intended for the VF to access.
> @@ -969,6 +985,9 @@ int genwqe_write_vreg(struct genwqe_dev *cd, u32
> reg, u64 val, int func)
> 
>  /**
>   * genwqe_read_vreg() - Read register in virtual window
> + * @cd:	        genwqe device descriptor
> + * @reg:	register (byte) offset within BAR
> + * @func:	PCI virtual function
>   *
>   * Note, these registers are only accessible to the PF through the
>   * VF-window. It is not intended for the VF to access.
> @@ -981,6 +1000,7 @@ u64 genwqe_read_vreg(struct genwqe_dev *cd, u32
> reg, int func)
> 
>  /**
>   * genwqe_base_clock_frequency() - Deteremine base clock frequency of 
> the card
> + * @cd:	        genwqe device descriptor
>   *
>   * Note: From a design perspective it turned out to be a bad idea to
>   * use codes here to specifiy the frequency/speed values. An old
> @@ -1005,6 +1025,7 @@ int genwqe_base_clock_frequency(struct genwqe_dev 
> *cd)
> 
>  /**
>   * genwqe_stop_traps() - Stop traps
> + * @cd:	        genwqe device descriptor
>   *
>   * Before reading out the analysis data, we need to stop the traps.
>   */
> @@ -1015,6 +1036,7 @@ void genwqe_stop_traps(struct genwqe_dev *cd)
> 
>  /**
>   * genwqe_start_traps() - Start traps
> + * @cd:	        genwqe device descriptor
>   *
>   * After having read the data, we can/must enable the traps again.
>   */

Thanks for adding proper documentation to our driver.

Signed-off-by: Frank Haverkamp <haver@linux.ibm.com>

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel