| Message ID | 20200629140442.1043957-21-lee.jones@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Fix a bunch more W=1 warnings in Misc | expand |
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>
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. */
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(-)