[PATCH 00/12] Rid W=1 warnings from Thunderbolt

[PATCH 00/12] Rid W=1 warnings from Thunderbolt

[Lee Jones]

This set is part of a larger effort attempting to clean-up W=1
kernel builds, which are currently overwhelmingly riddled with
niggly little warnings.

Only 1 small set required for Thunderbolt.  Pretty good!

Lee Jones (12):
  thunderbolt: dma_port: Remove unused variable 'ret'
  thunderbolt: cap: Fix kernel-doc formatting issue
  thunderbolt: ctl: Demote non-conformant kernel-doc headers
  thunderbolt: eeprom: Demote non-conformant kernel-doc headers to
    standard comment blocks
  thunderbolt: pa: Demote non-conformant kernel-doc headers
  thunderbolt: xdomain: Fix 'tb_unregister_service_driver()'s 'drv'
    param
  thunderbolt: nhi: Demote some non-conformant kernel-doc headers
  thunderbolt: tb: Kernel-doc function headers should document their
    parameters
  thunderbolt: swit: Demote a bunch of non-conformant kernel-doc headers
  thunderbolt: icm: Fix a couple of formatting issues
  thunderbolt: tunnel: Fix misspelling of 'receive_path'
  thunderbolt: swit: Fix function name in the header

 drivers/thunderbolt/cap.c      |  2 +-
 drivers/thunderbolt/ctl.c      | 22 +++++++++++-----------
 drivers/thunderbolt/dma_port.c |  5 ++---
 drivers/thunderbolt/eeprom.c   | 24 ++++++++++++------------
 drivers/thunderbolt/icm.c      |  4 ++--
 drivers/thunderbolt/nhi.c      | 14 +++++++-------
 drivers/thunderbolt/path.c     |  4 ++--
 drivers/thunderbolt/switch.c   | 14 +++++++-------
 drivers/thunderbolt/tb.c       | 12 ++++++------
 drivers/thunderbolt/tunnel.c   |  2 +-
 drivers/thunderbolt/xdomain.c  |  2 +-
 11 files changed, 52 insertions(+), 53 deletions(-)

Cc: Alexei Starovoitov <ast@kernel.org>
Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: bpf@vger.kernel.org
Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: Jesper Dangaard Brouer <hawk@kernel.org>
Cc: John Fastabend <john.fastabend@gmail.com>
Cc: linux-usb@vger.kernel.org
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: netdev@vger.kernel.org
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
-- 
2.25.1

[PATCH 01/12] thunderbolt: dma_port: Remove unused variable 'ret'

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/dma_port.c: In function ‘dma_port_flash_write_block’:
 drivers/thunderbolt/dma_port.c:331:6: warning: variable ‘ret’ set but not used [-Wunused-but-set-variable]

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/dma_port.c | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/drivers/thunderbolt/dma_port.c b/drivers/thunderbolt/dma_port.c
index 847dd07a7b172..5aced91e17dc4 100644
--- a/drivers/thunderbolt/dma_port.c
+++ b/drivers/thunderbolt/dma_port.c
@@ -328,13 +328,12 @@ static int dma_port_flash_write_block(struct tb_dma_port *dma, u32 address,
 {
 	struct tb_switch *sw = dma->sw;
 	u32 in, dwaddress, dwords;
-	int ret;
 
 	dwords = size / 4;
 
 	/* Write the block to MAIL_DATA registers */
-	ret = dma_port_write(sw->tb->ctl, buf, tb_route(sw), dma->port,
-			    dma->base + MAIL_DATA, dwords, DMA_PORT_TIMEOUT);
+	dma_port_write(sw->tb->ctl, buf, tb_route(sw), dma->port,
+		       dma->base + MAIL_DATA, dwords, DMA_PORT_TIMEOUT);
 
 	in = MAIL_IN_CMD_FLASH_WRITE << MAIL_IN_CMD_SHIFT;
 
-- 
2.25.1

Re: [PATCH 01/12] thunderbolt: dma_port: Remove unused variable 'ret'

[Lee Jones]

On Wed, 27 Jan 2021, Andy Shevchenko wrote:

> On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> 
> > Fixes the following W=1 kernel build warning(s):
> >
> >  drivers/thunderbolt/dma_port.c: In function ‘dma_port_flash_write_block’:
> >  drivers/thunderbolt/dma_port.c:331:6: warning: variable ‘ret’ set but
> > not used [-Wunused-but-set-variable]
> >
> >
> Is it scripted somehow?

A script opens up the file on the warning line.

The patch is hand-written.

> Because I am not sure we are okay to simply drop the assignment.

I've been careful not to change the semantics of the code.

The return value has never been checked since the driver's inception 4
years ago.

However, if this is an oversight and the intention was to check the
value and error-out during a failure condition, I can make that
happen.

I would need a nod from the author before I make such a change.

> > Cc: Andreas Noever <andreas.noever@gmail.com>
> > Cc: Michael Jamet <michael.jamet@intel.com>
> > Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
> > Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
> > Cc: linux-usb@vger.kernel.org
> > Signed-off-by: Lee Jones <lee.jones@linaro.org>
> > ---
> >  drivers/thunderbolt/dma_port.c | 5 ++---
> >  1 file changed, 2 insertions(+), 3 deletions(-)
> >
> > diff --git a/drivers/thunderbolt/dma_port.c b/drivers/thunderbolt/dma_
> > port.c
> > index 847dd07a7b172..5aced91e17dc4 100644
> > --- a/drivers/thunderbolt/dma_port.c
> > +++ b/drivers/thunderbolt/dma_port.c
> > @@ -328,13 +328,12 @@ static int dma_port_flash_write_block(struct
> > tb_dma_port *dma, u32 address,
> >  {
> >         struct tb_switch *sw = dma->sw;
> >         u32 in, dwaddress, dwords;
> > -       int ret;
> >
> >         dwords = size / 4;
> >
> >         /* Write the block to MAIL_DATA registers */
> > -       ret = dma_port_write(sw->tb->ctl, buf, tb_route(sw), dma->port,
> > -                           dma->base + MAIL_DATA, dwords,
> > DMA_PORT_TIMEOUT);
> > +       dma_port_write(sw->tb->ctl, buf, tb_route(sw), dma->port,
> > +                      dma->base + MAIL_DATA, dwords, DMA_PORT_TIMEOUT);
> >
> >         in = MAIL_IN_CMD_FLASH_WRITE << MAIL_IN_CMD_SHIFT;
> >
> >
> >
> 

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH 01/12] thunderbolt: dma_port: Remove unused variable 'ret'

[Mika Westerberg]

Hi,

On Wed, Jan 27, 2021 at 04:19:16PM +0000, Lee Jones wrote:
> On Wed, 27 Jan 2021, Andy Shevchenko wrote:
> 
> > On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> > 
> > > Fixes the following W=1 kernel build warning(s):
> > >
> > >  drivers/thunderbolt/dma_port.c: In function ‘dma_port_flash_write_block’:
> > >  drivers/thunderbolt/dma_port.c:331:6: warning: variable ‘ret’ set but
> > > not used [-Wunused-but-set-variable]
> > >
> > >
> > Is it scripted somehow?
> 
> A script opens up the file on the warning line.
> 
> The patch is hand-written.
> 
> > Because I am not sure we are okay to simply drop the assignment.
> 
> I've been careful not to change the semantics of the code.
> 
> The return value has never been checked since the driver's inception 4
> years ago.
> 
> However, if this is an oversight and the intention was to check the
> value and error-out during a failure condition, I can make that
> happen.
> 
> I would need a nod from the author before I make such a change.

It's actually an oversight from my side. It should do something like:

  if (ret)
  	return ret:

there. Feel free to fix it up :)

Thanks!

[PATCH V2 01/12] thunderbolt: dma_port: Check 'dma_port_flash_write_block()'s return value

[Lee Jones]

... and take the error path if it fails.

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/dma_port.c: In function ‘dma_port_flash_write_block’:
 drivers/thunderbolt/dma_port.c:331:6: warning: variable ‘ret’ set but not used [-Wunused-but-set-variable]

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---

v2: Different approach: actually handle the error.

 drivers/thunderbolt/dma_port.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/thunderbolt/dma_port.c b/drivers/thunderbolt/dma_port.c
index 847dd07a7b172..7288aaf01ae6a 100644
--- a/drivers/thunderbolt/dma_port.c
+++ b/drivers/thunderbolt/dma_port.c
@@ -335,6 +335,8 @@ static int dma_port_flash_write_block(struct tb_dma_port *dma, u32 address,
        /* Write the block to MAIL_DATA registers */
        ret = dma_port_write(sw->tb->ctl, buf, tb_route(sw), dma->port,
                            dma->base + MAIL_DATA, dwords, DMA_PORT_TIMEOUT);
+       if (ret)
+               return ret;
 
        in = MAIL_IN_CMD_FLASH_WRITE << MAIL_IN_CMD_SHIFT;

Re: [PATCH V2 01/12] thunderbolt: dma_port: Check 'dma_port_flash_write_block()'s return value

[Mika Westerberg]

On Thu, Jan 28, 2021 at 08:52:33AM +0000, Lee Jones wrote:
> ... and take the error path if it fails.
> 
> Fixes the following W=1 kernel build warning(s):
> 
>  drivers/thunderbolt/dma_port.c: In function ‘dma_port_flash_write_block’:
>  drivers/thunderbolt/dma_port.c:331:6: warning: variable ‘ret’ set but not used [-Wunused-but-set-variable]
> 
> Cc: Andreas Noever <andreas.noever@gmail.com>
> Cc: Michael Jamet <michael.jamet@intel.com>
> Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
> Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
> Cc: linux-usb@vger.kernel.org
> Signed-off-by: Lee Jones <lee.jones@linaro.org>

Applied, thanks!

[PATCH 02/12] thunderbolt: cap: Fix kernel-doc formatting issue

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/cap.c:189: warning: Function parameter or member 'sw' not described in 'tb_switch_find_cap'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/cap.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/thunderbolt/cap.c b/drivers/thunderbolt/cap.c
index 6f571e912cf21..8ecd610c62d50 100644
--- a/drivers/thunderbolt/cap.c
+++ b/drivers/thunderbolt/cap.c
@@ -178,7 +178,7 @@ int tb_switch_next_cap(struct tb_switch *sw, unsigned int offset)
 
 /**
  * tb_switch_find_cap() - Find switch capability
- * @sw Switch to find the capability for
+ * @sw: Switch to find the capability for
  * @cap: Capability to look
  *
  * Returns offset to start of capability or %-ENOENT if no such
-- 
2.25.1

[PATCH 03/12] thunderbolt: ctl: Demote non-conformant kernel-doc headers

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/ctl.c:38: warning: expecting prototype for struct tb_cfg. Prototype was for struct tb_ctl instead
 drivers/thunderbolt/ctl.c:350: warning: Function parameter or member 'ctl' not described in 'tb_ctl_tx'
 drivers/thunderbolt/ctl.c:350: warning: Function parameter or member 'data' not described in 'tb_ctl_tx'
 drivers/thunderbolt/ctl.c:350: warning: Function parameter or member 'len' not described in 'tb_ctl_tx'
 drivers/thunderbolt/ctl.c:350: warning: Function parameter or member 'type' not described in 'tb_ctl_tx'
 drivers/thunderbolt/ctl.c:350: warning: expecting prototype for tb_cfg_tx(). Prototype was for tb_ctl_tx() instead
 drivers/thunderbolt/ctl.c:383: warning: Function parameter or member 'ctl' not described in 'tb_ctl_handle_event'
 drivers/thunderbolt/ctl.c:383: warning: Function parameter or member 'type' not described in 'tb_ctl_handle_event'
 drivers/thunderbolt/ctl.c:383: warning: Function parameter or member 'pkg' not described in 'tb_ctl_handle_event'
 drivers/thunderbolt/ctl.c:383: warning: Function parameter or member 'size' not described in 'tb_ctl_handle_event'
 drivers/thunderbolt/ctl.c:611: warning: Function parameter or member 'nhi' not described in 'tb_ctl_alloc'
 drivers/thunderbolt/ctl.c:611: warning: Function parameter or member 'cb' not described in 'tb_ctl_alloc'
 drivers/thunderbolt/ctl.c:611: warning: Function parameter or member 'cb_data' not described in 'tb_ctl_alloc'
 drivers/thunderbolt/ctl.c:658: warning: Function parameter or member 'ctl' not described in 'tb_ctl_free'
 drivers/thunderbolt/ctl.c:682: warning: Function parameter or member 'ctl' not described in 'tb_ctl_start'
 drivers/thunderbolt/ctl.c:682: warning: expecting prototype for tb_cfg_start(). Prototype was for tb_ctl_start() instead
 drivers/thunderbolt/ctl.c:702: warning: Function parameter or member 'ctl' not described in 'tb_ctl_stop'
 drivers/thunderbolt/ctl.c:702: warning: expecting prototype for control(). Prototype was for tb_ctl_stop() instead
 drivers/thunderbolt/ctl.c:794: warning: Function parameter or member 'ctl' not described in 'tb_cfg_reset'
 drivers/thunderbolt/ctl.c:794: warning: Function parameter or member 'route' not described in 'tb_cfg_reset'
 drivers/thunderbolt/ctl.c:794: warning: Function parameter or member 'timeout_msec' not described in 'tb_cfg_reset'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'ctl' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'buffer' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'route' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'port' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'space' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'offset' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'length' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: Function parameter or member 'timeout_msec' not described in 'tb_cfg_read_raw'
 drivers/thunderbolt/ctl.c:830: warning: expecting prototype for tb_cfg_read(). Prototype was for tb_cfg_read_raw() instead
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'ctl' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'buffer' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'route' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'port' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'space' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'offset' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'length' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: Function parameter or member 'timeout_msec' not described in 'tb_cfg_write_raw'
 drivers/thunderbolt/ctl.c:893: warning: expecting prototype for tb_cfg_write(). Prototype was for tb_cfg_write_raw() instead
 drivers/thunderbolt/ctl.c:1033: warning: Function parameter or member 'ctl' not described in 'tb_cfg_get_upstream_port'
 drivers/thunderbolt/ctl.c:1033: warning: Function parameter or member 'route' not described in 'tb_cfg_get_upstream_port'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/ctl.c | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/drivers/thunderbolt/ctl.c b/drivers/thunderbolt/ctl.c
index bac08b820015d..e5d7ff6807721 100644
--- a/drivers/thunderbolt/ctl.c
+++ b/drivers/thunderbolt/ctl.c
@@ -19,7 +19,7 @@
 #define TB_CTL_RX_PKG_COUNT	10
 #define TB_CTL_RETRIES		4
 
-/**
+/*
  * struct tb_cfg - thunderbolt control channel
  */
 struct tb_ctl {
@@ -338,7 +338,7 @@ static void tb_ctl_tx_callback(struct tb_ring *ring, struct ring_frame *frame,
 	tb_ctl_pkg_free(pkg);
 }
 
-/**
+/*
  * tb_cfg_tx() - transmit a packet on the control channel
  *
  * len must be a multiple of four.
@@ -375,7 +375,7 @@ static int tb_ctl_tx(struct tb_ctl *ctl, const void *data, size_t len,
 	return res;
 }
 
-/**
+/*
  * tb_ctl_handle_event() - acknowledge a plug event, invoke ctl->callback
  */
 static bool tb_ctl_handle_event(struct tb_ctl *ctl, enum tb_cfg_pkg_type type,
@@ -600,7 +600,7 @@ struct tb_cfg_result tb_cfg_request_sync(struct tb_ctl *ctl,
 
 /* public interface, alloc/start/stop/free */
 
-/**
+/*
  * tb_ctl_alloc() - allocate a control channel
  *
  * cb will be invoked once for every hot plug event.
@@ -647,7 +647,7 @@ struct tb_ctl *tb_ctl_alloc(struct tb_nhi *nhi, event_cb cb, void *cb_data)
 	return NULL;
 }
 
-/**
+/*
  * tb_ctl_free() - free a control channel
  *
  * Must be called after tb_ctl_stop.
@@ -675,7 +675,7 @@ void tb_ctl_free(struct tb_ctl *ctl)
 	kfree(ctl);
 }
 
-/**
+/*
  * tb_cfg_start() - start/resume the control channel
  */
 void tb_ctl_start(struct tb_ctl *ctl)
@@ -690,7 +690,7 @@ void tb_ctl_start(struct tb_ctl *ctl)
 	ctl->running = true;
 }
 
-/**
+/*
  * control() - pause the control channel
  *
  * All invocations of ctl->callback will have finished after this method
@@ -782,7 +782,7 @@ static bool tb_cfg_copy(struct tb_cfg_request *req, const struct ctl_pkg *pkg)
 	return true;
 }
 
-/**
+/*
  * tb_cfg_reset() - send a reset packet and wait for a response
  *
  * If the switch at route is incorrectly configured then we will not receive a
@@ -819,7 +819,7 @@ struct tb_cfg_result tb_cfg_reset(struct tb_ctl *ctl, u64 route,
 	return res;
 }
 
-/**
+/*
  * tb_cfg_read() - read from config space into buffer
  *
  * Offset and length are in dwords.
@@ -882,7 +882,7 @@ struct tb_cfg_result tb_cfg_read_raw(struct tb_ctl *ctl, void *buffer,
 	return res;
 }
 
-/**
+/*
  * tb_cfg_write() - write from buffer into config space
  *
  * Offset and length are in dwords.
@@ -1020,7 +1020,7 @@ int tb_cfg_write(struct tb_ctl *ctl, const void *buffer, u64 route, u32 port,
 	return res.err;
 }
 
-/**
+/*
  * tb_cfg_get_upstream_port() - get upstream port number of switch at route
  *
  * Reads the first dword from the switches TB_CFG_SWITCH config area and
-- 
2.25.1

[PATCH 04/12] thunderbolt: eeprom: Demote non-conformant kernel-doc headers to standard comment blocks

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/eeprom.c:19: warning: Function parameter or member 'sw' not described in 'tb_eeprom_ctl_write'
 drivers/thunderbolt/eeprom.c:19: warning: Function parameter or member 'ctl' not described in 'tb_eeprom_ctl_write'
 drivers/thunderbolt/eeprom.c:27: warning: Function parameter or member 'sw' not described in 'tb_eeprom_ctl_read'
 drivers/thunderbolt/eeprom.c:27: warning: Function parameter or member 'ctl' not described in 'tb_eeprom_ctl_read'
 drivers/thunderbolt/eeprom.c:27: warning: expecting prototype for tb_eeprom_ctl_write(). Prototype was for tb_eeprom_ctl_read() instead
 drivers/thunderbolt/eeprom.c:43: warning: Function parameter or member 'sw' not described in 'tb_eeprom_active'
 drivers/thunderbolt/eeprom.c:43: warning: Function parameter or member 'enable' not described in 'tb_eeprom_active'
 drivers/thunderbolt/eeprom.c:73: warning: Function parameter or member 'sw' not described in 'tb_eeprom_transfer'
 drivers/thunderbolt/eeprom.c:73: warning: Function parameter or member 'ctl' not described in 'tb_eeprom_transfer'
 drivers/thunderbolt/eeprom.c:73: warning: Function parameter or member 'direction' not described in 'tb_eeprom_transfer'
 drivers/thunderbolt/eeprom.c:97: warning: Function parameter or member 'sw' not described in 'tb_eeprom_out'
 drivers/thunderbolt/eeprom.c:97: warning: Function parameter or member 'val' not described in 'tb_eeprom_out'
 drivers/thunderbolt/eeprom.c:117: warning: Function parameter or member 'sw' not described in 'tb_eeprom_in'
 drivers/thunderbolt/eeprom.c:117: warning: Function parameter or member 'val' not described in 'tb_eeprom_in'
 drivers/thunderbolt/eeprom.c:138: warning: Function parameter or member 'sw' not described in 'tb_eeprom_get_drom_offset'
 drivers/thunderbolt/eeprom.c:138: warning: Function parameter or member 'offset' not described in 'tb_eeprom_get_drom_offset'
 drivers/thunderbolt/eeprom.c:170: warning: Function parameter or member 'sw' not described in 'tb_eeprom_read_n'
 drivers/thunderbolt/eeprom.c:170: warning: Function parameter or member 'offset' not described in 'tb_eeprom_read_n'
 drivers/thunderbolt/eeprom.c:170: warning: Function parameter or member 'val' not described in 'tb_eeprom_read_n'
 drivers/thunderbolt/eeprom.c:170: warning: Function parameter or member 'count' not described in 'tb_eeprom_read_n'
 drivers/thunderbolt/eeprom.c:288: warning: Function parameter or member 'sw' not described in 'tb_drom_read_uid_only'
 drivers/thunderbolt/eeprom.c:288: warning: Function parameter or member 'uid' not described in 'tb_drom_read_uid_only'
 drivers/thunderbolt/eeprom.c:383: warning: Function parameter or member 'sw' not described in 'tb_drom_parse_entries'
 drivers/thunderbolt/eeprom.c:417: warning: Function parameter or member 'sw' not described in 'tb_drom_copy_efi'
 drivers/thunderbolt/eeprom.c:417: warning: Function parameter or member 'size' not described in 'tb_drom_copy_efi'
 drivers/thunderbolt/eeprom.c:526: warning: Function parameter or member 'sw' not described in 'tb_drom_read'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/eeprom.c | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/drivers/thunderbolt/eeprom.c b/drivers/thunderbolt/eeprom.c
index 0c8471be3e32f..e8cb8399069c9 100644
--- a/drivers/thunderbolt/eeprom.c
+++ b/drivers/thunderbolt/eeprom.c
@@ -12,7 +12,7 @@
 #include <linux/slab.h>
 #include "tb.h"
 
-/**
+/*
  * tb_eeprom_ctl_write() - write control word
  */
 static int tb_eeprom_ctl_write(struct tb_switch *sw, struct tb_eeprom_ctl *ctl)
@@ -20,7 +20,7 @@ static int tb_eeprom_ctl_write(struct tb_switch *sw, struct tb_eeprom_ctl *ctl)
 	return tb_sw_write(sw, ctl, TB_CFG_SWITCH, sw->cap_plug_events + 4, 1);
 }
 
-/**
+/*
  * tb_eeprom_ctl_write() - read control word
  */
 static int tb_eeprom_ctl_read(struct tb_switch *sw, struct tb_eeprom_ctl *ctl)
@@ -33,7 +33,7 @@ enum tb_eeprom_transfer {
 	TB_EEPROM_OUT,
 };
 
-/**
+/*
  * tb_eeprom_active - enable rom access
  *
  * WARNING: Always disable access after usage. Otherwise the controller will
@@ -62,7 +62,7 @@ static int tb_eeprom_active(struct tb_switch *sw, bool enable)
 	}
 }
 
-/**
+/*
  * tb_eeprom_transfer - transfer one bit
  *
  * If TB_EEPROM_IN is passed, then the bit can be retrieved from ctl->data_in.
@@ -90,7 +90,7 @@ static int tb_eeprom_transfer(struct tb_switch *sw, struct tb_eeprom_ctl *ctl,
 	return tb_eeprom_ctl_write(sw, ctl);
 }
 
-/**
+/*
  * tb_eeprom_out - write one byte to the bus
  */
 static int tb_eeprom_out(struct tb_switch *sw, u8 val)
@@ -110,7 +110,7 @@ static int tb_eeprom_out(struct tb_switch *sw, u8 val)
 	return 0;
 }
 
-/**
+/*
  * tb_eeprom_in - read one byte from the bus
  */
 static int tb_eeprom_in(struct tb_switch *sw, u8 *val)
@@ -131,7 +131,7 @@ static int tb_eeprom_in(struct tb_switch *sw, u8 *val)
 	return 0;
 }
 
-/**
+/*
  * tb_eeprom_get_drom_offset - get drom offset within eeprom
  */
 static int tb_eeprom_get_drom_offset(struct tb_switch *sw, u16 *offset)
@@ -162,7 +162,7 @@ static int tb_eeprom_get_drom_offset(struct tb_switch *sw, u16 *offset)
 	return 0;
 }
 
-/**
+/*
  * tb_eeprom_read_n - read count bytes from offset into val
  */
 static int tb_eeprom_read_n(struct tb_switch *sw, u16 offset, u8 *val,
@@ -278,7 +278,7 @@ struct tb_drom_entry_port {
 } __packed;
 
 
-/**
+/*
  * tb_drom_read_uid_only - read uid directly from drom
  *
  * Does not use the cached copy in sw->drom. Used during resume to check switch
@@ -374,7 +374,7 @@ static int tb_drom_parse_entry_port(struct tb_switch *sw,
 	return 0;
 }
 
-/**
+/*
  * tb_drom_parse_entries - parse the linked list of drom entries
  *
  * Drom must have been copied to sw->drom.
@@ -410,7 +410,7 @@ static int tb_drom_parse_entries(struct tb_switch *sw)
 	return 0;
 }
 
-/**
+/*
  * tb_drom_copy_efi - copy drom supplied by EFI to sw->drom if present
  */
 static int tb_drom_copy_efi(struct tb_switch *sw, u16 *size)
@@ -519,7 +519,7 @@ static int tb_drom_read_n(struct tb_switch *sw, u16 offset, u8 *val,
 	return tb_eeprom_read_n(sw, offset, val, count);
 }
 
-/**
+/*
  * tb_drom_read - copy drom to sw->drom and parse it
  */
 int tb_drom_read(struct tb_switch *sw)
-- 
2.25.1

[PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/path.c:476: warning: Function parameter or member 'path' not described in 'tb_path_activate'
 drivers/thunderbolt/path.c:568: warning: Function parameter or member 'path' not described in 'tb_path_is_invalid'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/path.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/thunderbolt/path.c b/drivers/thunderbolt/path.c
index ca7d738d66dea..758b5fa0060c6 100644
--- a/drivers/thunderbolt/path.c
+++ b/drivers/thunderbolt/path.c
@@ -464,7 +464,7 @@ void tb_path_deactivate(struct tb_path *path)
 	path->activated = false;
 }
 
-/**
+/*
  * tb_path_activate() - activate a path
  *
  * Activate a path starting with the last hop and iterating backwards. The
@@ -559,7 +559,7 @@ int tb_path_activate(struct tb_path *path)
 	return res;
 }
 
-/**
+/*
  * tb_path_is_invalid() - check whether any ports on the path are invalid
  *
  * Return: Returns true if the path is invalid, false otherwise.
-- 
2.25.1

Re: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers

[Lee Jones]

On Wed, 27 Jan 2021, Andy Shevchenko wrote:

> On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> 
> > Fixes the following W=1 kernel build warning(s):
> >
> >  drivers/thunderbolt/path.c:476: warning: Function parameter or member
> > 'path' not described in 'tb_path_activate'
> >  drivers/thunderbolt/path.c:568: warning: Function parameter or member
> > 'path' not described in 'tb_path_is_invalid'
> >
> >
> I think the intention was to describe them in kernel doc format, perhaps
> you need to add descriptions of the fields?

For changes like this, I've been working to the following rule:

 - I'll provide fix-ups; if and only if the author has had a
 reasonable attempt at providing a conformant kernel-doc header.

So if the headers are just suffering from a little doc-rot i.e. the
API has changed, but the doc update was omitted, or most of the
parameters/members are documented, but some were forgotten about etc,
or if there are formatting issues, I'll happily take up the slack and
polish those up a bit.

However, if no attempt was made, then they get demoted.

I don't want to get into a situation where authors delicately provide
weak documentation with the expectation that someone else will come
along and turn them into conformant docs.

If authors wish to come back, provide proper descriptions &
formatting and subsequently re-promote them again, then all power to
them.

> > Cc: Andreas Noever <andreas.noever@gmail.com>
> > Cc: Michael Jamet <michael.jamet@intel.com>
> > Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
> > Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
> > Cc: linux-usb@vger.kernel.org
> > Signed-off-by: Lee Jones <lee.jones@linaro.org>
> > ---
> >  drivers/thunderbolt/path.c | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git a/drivers/thunderbolt/path.c b/drivers/thunderbolt/path.c
> > index ca7d738d66dea..758b5fa0060c6 100644
> > --- a/drivers/thunderbolt/path.c
> > +++ b/drivers/thunderbolt/path.c
> > @@ -464,7 +464,7 @@ void tb_path_deactivate(struct tb_path *path)
> >         path->activated = false;
> >  }
> >
> > -/**
> > +/*
> >   * tb_path_activate() - activate a path
> >   *
> >   * Activate a path starting with the last hop and iterating backwards. Thee
> > @@ -559,7 +559,7 @@ int tb_path_activate(struct tb_path *path)
> >         return res;
> >  }
> >
> > -/**
> > +/*
> >   * tb_path_is_invalid() - check whether any ports on the path are invalid
> >   *
> >   * Return: Returns true if the path is invalid, false otherwise.
> >
> >
> 

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers

[Mika Westerberg]

On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:
> On Wed, 27 Jan 2021, Andy Shevchenko wrote:
> 
> > On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> > 
> > > Fixes the following W=1 kernel build warning(s):
> > >
> > >  drivers/thunderbolt/path.c:476: warning: Function parameter or member
> > > 'path' not described in 'tb_path_activate'
> > >  drivers/thunderbolt/path.c:568: warning: Function parameter or member
> > > 'path' not described in 'tb_path_is_invalid'
> > >
> > >
> > I think the intention was to describe them in kernel doc format, perhaps
> > you need to add descriptions of the fields?
> 
> For changes like this, I've been working to the following rule:
> 
>  - I'll provide fix-ups; if and only if the author has had a
>  reasonable attempt at providing a conformant kernel-doc header.
> 
> So if the headers are just suffering from a little doc-rot i.e. the
> API has changed, but the doc update was omitted, or most of the
> parameters/members are documented, but some were forgotten about etc,
> or if there are formatting issues, I'll happily take up the slack and
> polish those up a bit.
> 
> However, if no attempt was made, then they get demoted.
> 
> I don't want to get into a situation where authors delicately provide
> weak documentation with the expectation that someone else will come
> along and turn them into conformant docs.
> 
> If authors wish to come back, provide proper descriptions &
> formatting and subsequently re-promote them again, then all power to
> them.

Thanks for pointing these out. I prefer we fix the kernel-docs (add what
is missing) instead. I'll take care of that.

Re: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers

[Lee Jones]

On Wed, 27 Jan 2021, Mika Westerberg wrote:

> On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:
> > On Wed, 27 Jan 2021, Andy Shevchenko wrote:
> > 
> > > On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> > > 
> > > > Fixes the following W=1 kernel build warning(s):
> > > >
> > > >  drivers/thunderbolt/path.c:476: warning: Function parameter or member
> > > > 'path' not described in 'tb_path_activate'
> > > >  drivers/thunderbolt/path.c:568: warning: Function parameter or member
> > > > 'path' not described in 'tb_path_is_invalid'
> > > >
> > > >
> > > I think the intention was to describe them in kernel doc format, perhaps
> > > you need to add descriptions of the fields?
> > 
> > For changes like this, I've been working to the following rule:
> > 
> >  - I'll provide fix-ups; if and only if the author has had a
> >  reasonable attempt at providing a conformant kernel-doc header.
> > 
> > So if the headers are just suffering from a little doc-rot i.e. the
> > API has changed, but the doc update was omitted, or most of the
> > parameters/members are documented, but some were forgotten about etc,
> > or if there are formatting issues, I'll happily take up the slack and
> > polish those up a bit.
> > 
> > However, if no attempt was made, then they get demoted.
> > 
> > I don't want to get into a situation where authors delicately provide
> > weak documentation with the expectation that someone else will come
> > along and turn them into conformant docs.
> > 
> > If authors wish to come back, provide proper descriptions &
> > formatting and subsequently re-promote them again, then all power to
> > them.
> 
> Thanks for pointing these out. I prefer we fix the kernel-docs (add what
> is missing) instead. I'll take care of that.

Are you planning on actually using this?

I don't see a Doc link for these functions in Mainline:

  `git grep kernel-doc:: | grep thunderbolt`
  
-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers

[Mika Westerberg]

On Thu, Jan 28, 2021 at 08:23:30AM +0000, Lee Jones wrote:
> On Wed, 27 Jan 2021, Mika Westerberg wrote:
> 
> > On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:
> > > On Wed, 27 Jan 2021, Andy Shevchenko wrote:
> > > 
> > > > On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> > > > 
> > > > > Fixes the following W=1 kernel build warning(s):
> > > > >
> > > > >  drivers/thunderbolt/path.c:476: warning: Function parameter or member
> > > > > 'path' not described in 'tb_path_activate'
> > > > >  drivers/thunderbolt/path.c:568: warning: Function parameter or member
> > > > > 'path' not described in 'tb_path_is_invalid'
> > > > >
> > > > >
> > > > I think the intention was to describe them in kernel doc format, perhaps
> > > > you need to add descriptions of the fields?
> > > 
> > > For changes like this, I've been working to the following rule:
> > > 
> > >  - I'll provide fix-ups; if and only if the author has had a
> > >  reasonable attempt at providing a conformant kernel-doc header.
> > > 
> > > So if the headers are just suffering from a little doc-rot i.e. the
> > > API has changed, but the doc update was omitted, or most of the
> > > parameters/members are documented, but some were forgotten about etc,
> > > or if there are formatting issues, I'll happily take up the slack and
> > > polish those up a bit.
> > > 
> > > However, if no attempt was made, then they get demoted.
> > > 
> > > I don't want to get into a situation where authors delicately provide
> > > weak documentation with the expectation that someone else will come
> > > along and turn them into conformant docs.
> > > 
> > > If authors wish to come back, provide proper descriptions &
> > > formatting and subsequently re-promote them again, then all power to
> > > them.
> > 
> > Thanks for pointing these out. I prefer we fix the kernel-docs (add what
> > is missing) instead. I'll take care of that.
> 
> Are you planning on actually using this?

Yes, eventually :)

> I don't see a Doc link for these functions in Mainline:
> 
>   `git grep kernel-doc:: | grep thunderbolt`

There is not one now but I would like to have the kernel-docs at least
in correct format so we can add the link later.

Re: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> On Thu, Jan 28, 2021 at 08:23:30AM +0000, Lee Jones wrote:
> > On Wed, 27 Jan 2021, Mika Westerberg wrote:
> > 
> > > On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:
> > > > On Wed, 27 Jan 2021, Andy Shevchenko wrote:
> > > > 
> > > > > On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> > > > > 
> > > > > > Fixes the following W=1 kernel build warning(s):
> > > > > >
> > > > > >  drivers/thunderbolt/path.c:476: warning: Function parameter or member
> > > > > > 'path' not described in 'tb_path_activate'
> > > > > >  drivers/thunderbolt/path.c:568: warning: Function parameter or member
> > > > > > 'path' not described in 'tb_path_is_invalid'
> > > > > >
> > > > > >
> > > > > I think the intention was to describe them in kernel doc format, perhaps
> > > > > you need to add descriptions of the fields?
> > > > 
> > > > For changes like this, I've been working to the following rule:
> > > > 
> > > >  - I'll provide fix-ups; if and only if the author has had a
> > > >  reasonable attempt at providing a conformant kernel-doc header.
> > > > 
> > > > So if the headers are just suffering from a little doc-rot i.e. the
> > > > API has changed, but the doc update was omitted, or most of the
> > > > parameters/members are documented, but some were forgotten about etc,
> > > > or if there are formatting issues, I'll happily take up the slack and
> > > > polish those up a bit.
> > > > 
> > > > However, if no attempt was made, then they get demoted.
> > > > 
> > > > I don't want to get into a situation where authors delicately provide
> > > > weak documentation with the expectation that someone else will come
> > > > along and turn them into conformant docs.
> > > > 
> > > > If authors wish to come back, provide proper descriptions &
> > > > formatting and subsequently re-promote them again, then all power to
> > > > them.
> > > 
> > > Thanks for pointing these out. I prefer we fix the kernel-docs (add what
> > > is missing) instead. I'll take care of that.
> > 
> > Are you planning on actually using this?
> 
> Yes, eventually :)

:)

> > I don't see a Doc link for these functions in Mainline:
> > 
> >   `git grep kernel-doc:: | grep thunderbolt`
> 
> There is not one now but I would like to have the kernel-docs at least
> in correct format so we can add the link later.

Very well.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

[PATCH 06/12] thunderbolt: xdomain: Fix 'tb_unregister_service_driver()'s 'drv' param

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/xdomain.c:678: warning: Function parameter or member 'drv' not described in 'tb_unregister_service_driver'
 drivers/thunderbolt/xdomain.c:678: warning: Excess function parameter 'xdrv' description in 'tb_unregister_service_driver'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: Alexei Starovoitov <ast@kernel.org>
Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: Jesper Dangaard Brouer <hawk@kernel.org>
Cc: John Fastabend <john.fastabend@gmail.com>
Cc: linux-usb@vger.kernel.org
Cc: netdev@vger.kernel.org
Cc: bpf@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/xdomain.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/thunderbolt/xdomain.c b/drivers/thunderbolt/xdomain.c
index f2d4db1cd84d0..6e8bea6a7d392 100644
--- a/drivers/thunderbolt/xdomain.c
+++ b/drivers/thunderbolt/xdomain.c
@@ -670,7 +670,7 @@ EXPORT_SYMBOL_GPL(tb_register_service_driver);
 
 /**
  * tb_unregister_service_driver() - Unregister XDomain service driver
- * @xdrv: Driver to unregister
+ * @drv: Driver to unregister
  *
  * Unregisters XDomain service driver from the bus.
  */
-- 
2.25.1

[PATCH 07/12] thunderbolt: nhi: Demote some non-conformant kernel-doc headers

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/nhi.c:53: warning: Function parameter or member 'ring' not described in 'ring_interrupt_active'
 drivers/thunderbolt/nhi.c:53: warning: Function parameter or member 'active' not described in 'ring_interrupt_active'
 drivers/thunderbolt/nhi.c:114: warning: Function parameter or member 'nhi' not described in 'nhi_disable_interrupts'
 drivers/thunderbolt/nhi.c:191: warning: Function parameter or member 'ring' not described in 'ring_write_descriptors'
 drivers/thunderbolt/nhi.c:225: warning: Function parameter or member 'work' not described in 'ring_work'
 drivers/thunderbolt/nhi.c:599: warning: Function parameter or member 'ring' not described in 'tb_ring_start'
 drivers/thunderbolt/nhi.c:682: warning: Function parameter or member 'ring' not described in 'tb_ring_stop'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/nhi.c | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/drivers/thunderbolt/nhi.c b/drivers/thunderbolt/nhi.c
index cfc622da4f832..2ba33b53d4eb1 100644
--- a/drivers/thunderbolt/nhi.c
+++ b/drivers/thunderbolt/nhi.c
@@ -44,7 +44,7 @@ static int ring_interrupt_index(struct tb_ring *ring)
 	return bit;
 }
 
-/**
+/*
  * ring_interrupt_active() - activate/deactivate interrupts for a single ring
  *
  * ring->nhi->lock must be held.
@@ -105,7 +105,7 @@ static void ring_interrupt_active(struct tb_ring *ring, bool active)
 	iowrite32(new, ring->nhi->iobase + reg);
 }
 
-/**
+/*
  * nhi_disable_interrupts() - disable interrupts for all rings
  *
  * Use only during init and shutdown.
@@ -182,7 +182,7 @@ static bool ring_empty(struct tb_ring *ring)
 	return ring->head == ring->tail;
 }
 
-/**
+/*
  * ring_write_descriptors() - post frames from ring->queue to the controller
  *
  * ring->lock is held.
@@ -212,7 +212,7 @@ static void ring_write_descriptors(struct tb_ring *ring)
 	}
 }
 
-/**
+/*
  * ring_work() - progress completed frames
  *
  * If the ring is shutting down then all frames are marked as canceled and
@@ -590,7 +590,7 @@ struct tb_ring *tb_ring_alloc_rx(struct tb_nhi *nhi, int hop, int size,
 }
 EXPORT_SYMBOL_GPL(tb_ring_alloc_rx);
 
-/**
+/*
  * tb_ring_start() - enable a ring
  *
  * Must not be invoked in parallel with tb_ring_stop().
@@ -665,7 +665,7 @@ void tb_ring_start(struct tb_ring *ring)
 }
 EXPORT_SYMBOL_GPL(tb_ring_start);
 
-/**
+/*
  * tb_ring_stop() - shutdown a ring
  *
  * Must not be invoked from a callback.
@@ -754,7 +754,7 @@ void tb_ring_free(struct tb_ring *ring)
 	dev_dbg(&ring->nhi->pdev->dev, "freeing %s %d\n", RING_TYPE(ring),
 		ring->hop);
 
-	/**
+	/*
 	 * ring->work can no longer be scheduled (it is scheduled only
 	 * by nhi_interrupt_work, ring_stop and ring_msix). Wait for it
 	 * to finish before freeing the ring.
-- 
2.25.1

[PATCH 08/12] thunderbolt: tb: Kernel-doc function headers should document their parameters

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/tb.c:535: warning: Function parameter or member 'sw' not described in 'tb_scan_switch'
 drivers/thunderbolt/tb.c:551: warning: Function parameter or member 'port' not described in 'tb_scan_port'
 drivers/thunderbolt/tb.c:711: warning: Function parameter or member 'tb' not described in 'tb_free_invalid_tunnels'
 drivers/thunderbolt/tb.c:726: warning: Function parameter or member 'sw' not described in 'tb_free_unplugged_children'
 drivers/thunderbolt/tb.c:1129: warning: Function parameter or member 'work' not described in 'tb_handle_hotplug'
 drivers/thunderbolt/tb.c:1239: warning: Function parameter or member 'tb' not described in 'tb_handle_event'
 drivers/thunderbolt/tb.c:1239: warning: Function parameter or member 'type' not described in 'tb_handle_event'
 drivers/thunderbolt/tb.c:1239: warning: Function parameter or member 'buf' not described in 'tb_handle_event'
 drivers/thunderbolt/tb.c:1239: warning: Function parameter or member 'size' not described in 'tb_handle_event'
 drivers/thunderbolt/tb.c:1239: warning: expecting prototype for tb_schedule_hotplug_handler(). Prototype was for tb_handle_event() instead

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/tb.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/drivers/thunderbolt/tb.c b/drivers/thunderbolt/tb.c
index d08879849abed..413955aa6a949 100644
--- a/drivers/thunderbolt/tb.c
+++ b/drivers/thunderbolt/tb.c
@@ -528,7 +528,7 @@ static int tb_create_usb3_tunnels(struct tb_switch *sw)
 
 static void tb_scan_port(struct tb_port *port);
 
-/**
+/*
  * tb_scan_switch() - scan for and initialize downstream switches
  */
 static void tb_scan_switch(struct tb_switch *sw)
@@ -544,7 +544,7 @@ static void tb_scan_switch(struct tb_switch *sw)
 	pm_runtime_put_autosuspend(&sw->dev);
 }
 
-/**
+/*
  * tb_scan_port() - check for and initialize switches below port
  */
 static void tb_scan_port(struct tb_port *port)
@@ -704,7 +704,7 @@ static void tb_deactivate_and_free_tunnel(struct tb_tunnel *tunnel)
 	tb_tunnel_free(tunnel);
 }
 
-/**
+/*
  * tb_free_invalid_tunnels() - destroy tunnels of devices that have gone away
  */
 static void tb_free_invalid_tunnels(struct tb *tb)
@@ -719,7 +719,7 @@ static void tb_free_invalid_tunnels(struct tb *tb)
 	}
 }
 
-/**
+/*
  * tb_free_unplugged_children() - traverse hierarchy and free unplugged switches
  */
 static void tb_free_unplugged_children(struct tb_switch *sw)
@@ -1120,7 +1120,7 @@ static int tb_disconnect_xdomain_paths(struct tb *tb, struct tb_xdomain *xd)
 
 /* hotplug handling */
 
-/**
+/*
  * tb_handle_hotplug() - handle hotplug event
  *
  * Executes on tb->wq.
@@ -1229,7 +1229,7 @@ static void tb_handle_hotplug(struct work_struct *work)
 	kfree(ev);
 }
 
-/**
+/*
  * tb_schedule_hotplug_handler() - callback function for the control channel
  *
  * Delegates to tb_handle_hotplug.
-- 
2.25.1

[PATCH 09/12] thunderbolt: swit: Demote a bunch of non-conformant kernel-doc headers

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/switch.c:540: warning: Function parameter or member 'port' not described in 'tb_wait_for_port'
 drivers/thunderbolt/switch.c:540: warning: Function parameter or member 'wait_if_unplugged' not described in 'tb_wait_for_port'
 drivers/thunderbolt/switch.c:599: warning: Function parameter or member 'port' not described in 'tb_port_add_nfc_credits'
 drivers/thunderbolt/switch.c:599: warning: Function parameter or member 'credits' not described in 'tb_port_add_nfc_credits'
 drivers/thunderbolt/switch.c:653: warning: Function parameter or member 'port' not described in 'tb_port_clear_counter'
 drivers/thunderbolt/switch.c:653: warning: Function parameter or member 'counter' not described in 'tb_port_clear_counter'
 drivers/thunderbolt/switch.c:730: warning: Function parameter or member 'port' not described in 'tb_init_port'
 drivers/thunderbolt/switch.c:1348: warning: Function parameter or member 'sw' not described in 'tb_plug_events_active'
 drivers/thunderbolt/switch.c:1348: warning: Function parameter or member 'active' not described in 'tb_plug_events_active'
 drivers/thunderbolt/switch.c:2654: warning: Function parameter or member 'sw' not described in 'tb_sw_set_unplugged'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/switch.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/drivers/thunderbolt/switch.c b/drivers/thunderbolt/switch.c
index cdba05e72486b..ce1b120d1cd46 100644
--- a/drivers/thunderbolt/switch.c
+++ b/drivers/thunderbolt/switch.c
@@ -523,7 +523,7 @@ int tb_port_state(struct tb_port *port)
 	return phy.state;
 }
 
-/**
+/*
  * tb_wait_for_port() - wait for a port to become ready
  *
  * Wait up to 1 second for a port to reach state TB_PORT_UP. If
@@ -587,7 +587,7 @@ int tb_wait_for_port(struct tb_port *port, bool wait_if_unplugged)
 	return 0;
 }
 
-/**
+/*
  * tb_port_add_nfc_credits() - add/remove non flow controlled credits to port
  *
  * Change the number of NFC credits allocated to @port by @credits. To remove
@@ -644,7 +644,7 @@ int tb_port_set_initial_credits(struct tb_port *port, u32 credits)
 	return tb_port_write(port, &data, TB_CFG_PORT, ADP_CS_5, 1);
 }
 
-/**
+/*
  * tb_port_clear_counter() - clear a counter in TB_CFG_COUNTER
  *
  * Return: Returns 0 on success or an error code on failure.
@@ -718,7 +718,7 @@ int tb_port_disable(struct tb_port *port)
 	return __tb_port_enable(port, false);
 }
 
-/**
+/*
  * tb_init_port() - initialize a port
  *
  * This is a helper method for tb_switch_alloc. Does not check or initialize
@@ -1337,7 +1337,7 @@ int tb_switch_reset(struct tb_switch *sw)
 	return res.err;
 }
 
-/**
+/*
  * tb_plug_events_active() - enable/disable plug events on a switch
  *
  * Also configures a sane plug_events_delay of 255ms.
@@ -2647,7 +2647,7 @@ void tb_switch_remove(struct tb_switch *sw)
 	device_unregister(&sw->dev);
 }
 
-/**
+/*
  * tb_sw_set_unplugged() - set is_unplugged on switch and downstream switches
  */
 void tb_sw_set_unplugged(struct tb_switch *sw)
-- 
2.25.1

[PATCH 10/12] thunderbolt: icm: Fix a couple of formatting issues

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/icm.c:122: warning: Function parameter or member 'xdomain_connected' not described in 'icm'
 drivers/thunderbolt/icm.c:122: warning: Function parameter or member 'xdomain_disconnected' not described in 'icm'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/icm.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/thunderbolt/icm.c b/drivers/thunderbolt/icm.c
index b8c4159bc32d0..09c4a84413ec0 100644
--- a/drivers/thunderbolt/icm.c
+++ b/drivers/thunderbolt/icm.c
@@ -85,8 +85,8 @@ struct usb4_switch_nvm_auth {
  * @set_uuid: Set UUID for the root switch (optional)
  * @device_connected: Handle device connected ICM message
  * @device_disconnected: Handle device disconnected ICM message
- * @xdomain_connected - Handle XDomain connected ICM message
- * @xdomain_disconnected - Handle XDomain disconnected ICM message
+ * @xdomain_connected: Handle XDomain connected ICM message
+ * @xdomain_disconnected: Handle XDomain disconnected ICM message
  * @rtd3_veto: Handle RTD3 veto notification ICM message
  */
 struct icm {
-- 
2.25.1

[PATCH 11/12] thunderbolt: tunnel: Fix misspelling of 'receive_path'

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/tunnel.c:841: warning: Function parameter or member 'receive_path' not described in 'tb_tunnel_alloc_dma'
 drivers/thunderbolt/tunnel.c:841: warning: Excess function parameter 'reveive_path' description in 'tb_tunnel_alloc_dma'

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/tunnel.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/thunderbolt/tunnel.c b/drivers/thunderbolt/tunnel.c
index dcdf9c7a9caed..37943b0379abc 100644
--- a/drivers/thunderbolt/tunnel.c
+++ b/drivers/thunderbolt/tunnel.c
@@ -830,7 +830,7 @@ static void tb_dma_init_path(struct tb_path *path, unsigned int isb,
  * @transmit_path: HopID used for transmitting packets
  * @receive_ring: NHI ring number used to receive packets from the
  *		  other domain. Set to %0 if RX path is not needed.
- * @reveive_path: HopID used for receiving packets
+ * @receive_path: HopID used for receiving packets
  *
  * Return: Returns a tb_tunnel on success or NULL on failure.
  */
-- 
2.25.1

[PATCH 12/12] thunderbolt: swit: Fix function name in the header

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/thunderbolt/switch.c:1322: warning: expecting prototype for reset_switch(). Prototype was for tb_switch_reset() instead

Cc: Andreas Noever <andreas.noever@gmail.com>
Cc: Michael Jamet <michael.jamet@intel.com>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
Cc: linux-usb@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/switch.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/thunderbolt/switch.c b/drivers/thunderbolt/switch.c
index ce1b120d1cd46..6a3d5608431f6 100644
--- a/drivers/thunderbolt/switch.c
+++ b/drivers/thunderbolt/switch.c
@@ -1313,7 +1313,7 @@ static void tb_dump_switch(const struct tb *tb, const struct tb_switch *sw)
 }
 
 /**
- * reset_switch() - reconfigure route, enable and send TB_CFG_PKG_RESET
+ * tb_switch_reset() - reconfigure route, enable and send TB_CFG_PKG_RESET
  * @sw: Switch to reset
  *
  * Return: Returns 0 on success or an error code on failure.
-- 
2.25.1

Re: [PATCH 00/12] Rid W=1 warnings from Thunderbolt

[Mika Westerberg]

Hi Lee,

On Wed, Jan 27, 2021 at 11:25:42AM +0000, Lee Jones wrote:
> This set is part of a larger effort attempting to clean-up W=1
> kernel builds, which are currently overwhelmingly riddled with
> niggly little warnings.
> 
> Only 1 small set required for Thunderbolt.  Pretty good!
> 
> Lee Jones (12):
>   thunderbolt: dma_port: Remove unused variable 'ret'
>   thunderbolt: cap: Fix kernel-doc formatting issue
>   thunderbolt: ctl: Demote non-conformant kernel-doc headers
>   thunderbolt: eeprom: Demote non-conformant kernel-doc headers to
>     standard comment blocks
>   thunderbolt: pa: Demote non-conformant kernel-doc headers
>   thunderbolt: xdomain: Fix 'tb_unregister_service_driver()'s 'drv'
>     param
>   thunderbolt: nhi: Demote some non-conformant kernel-doc headers
>   thunderbolt: tb: Kernel-doc function headers should document their
>     parameters
>   thunderbolt: swit: Demote a bunch of non-conformant kernel-doc headers
>   thunderbolt: icm: Fix a couple of formatting issues
>   thunderbolt: tunnel: Fix misspelling of 'receive_path'
>   thunderbolt: swit: Fix function name in the header

I applied all of the changes that touch static functions. For non-static
functions I will send a patch set shortly that adds the missing bits for
the kernel-doc descriptions. I also fixed $subject lines of few patches
("switch:" instead of "swit:").

Please check that I got everything correct in

  git://git.kernel.org/pub/scm/linux/kernel/git/westeri/thunderbolt.git next

Thanks!

Re: [PATCH 00/12] Rid W=1 warnings from Thunderbolt

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> Hi Lee,
> 
> On Wed, Jan 27, 2021 at 11:25:42AM +0000, Lee Jones wrote:
> > This set is part of a larger effort attempting to clean-up W=1
> > kernel builds, which are currently overwhelmingly riddled with
> > niggly little warnings.
> > 
> > Only 1 small set required for Thunderbolt.  Pretty good!
> > 
> > Lee Jones (12):
> >   thunderbolt: dma_port: Remove unused variable 'ret'
> >   thunderbolt: cap: Fix kernel-doc formatting issue
> >   thunderbolt: ctl: Demote non-conformant kernel-doc headers
> >   thunderbolt: eeprom: Demote non-conformant kernel-doc headers to
> >     standard comment blocks
> >   thunderbolt: pa: Demote non-conformant kernel-doc headers
> >   thunderbolt: xdomain: Fix 'tb_unregister_service_driver()'s 'drv'
> >     param
> >   thunderbolt: nhi: Demote some non-conformant kernel-doc headers
> >   thunderbolt: tb: Kernel-doc function headers should document their
> >     parameters
> >   thunderbolt: swit: Demote a bunch of non-conformant kernel-doc headers
> >   thunderbolt: icm: Fix a couple of formatting issues
> >   thunderbolt: tunnel: Fix misspelling of 'receive_path'
> >   thunderbolt: swit: Fix function name in the header
> 
> I applied all of the changes that touch static functions. For non-static
> functions I will send a patch set shortly that adds the missing bits for
> the kernel-doc descriptions. I also fixed $subject lines of few patches
> ("switch:" instead of "swit:").

Oh, that's odd.  This must be a bug in my script.

As I strip [ch], as in *.c and *.h.

Thanks for noticing.

> Please check that I got everything correct in
> 
>   git://git.kernel.org/pub/scm/linux/kernel/git/westeri/thunderbolt.git next
> 
> Thanks!

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog