[PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions

[PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

Hi all,

This series was inspired by the patch series from Lee Jones that fixed a
bunch of warnings with W=1 build:

  https://lore.kernel.org/linux-usb/20210127112554.3770172-1-lee.jones@linaro.org/

For non-static functions we fix missing kernel-doc descriptions
accordingly. This fixes the rest of the warnings with W=1 build.

Applies on top of thunderbolt.git/next.

Mika Westerberg (5):
  thunderbolt: ctl: Fix kernel-doc descriptions of non-static functions
  thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
  thunderbolt: path: Fix kernel-doc descriptions of non-static functions
  thunderbolt: nhi: Fix kernel-doc descriptions of non-static functions
  thunderbolt: switch: Fix kernel-doc descriptions of non-static functions

 drivers/thunderbolt/ctl.c    | 47 ++++++++++++++++++++++++++++++++----
 drivers/thunderbolt/eeprom.c | 13 ++++++++--
 drivers/thunderbolt/nhi.c    |  2 ++
 drivers/thunderbolt/path.c   |  2 ++
 drivers/thunderbolt/switch.c |  7 ++++++
 5 files changed, 64 insertions(+), 7 deletions(-)

-- 
2.29.2

[PATCH 1/5] thunderbolt: ctl: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

Fix kernel-doc descriptions of all non-static functions and struct
tb_cfg. Gets rid of several warnings on W=1 builds too.

Reported-by: Lee Jones <lee.jones@linaro.org>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/ctl.c | 47 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/drivers/thunderbolt/ctl.c b/drivers/thunderbolt/ctl.c
index 2f9d4fc8aa23..f1aeaff9f368 100644
--- a/drivers/thunderbolt/ctl.c
+++ b/drivers/thunderbolt/ctl.c
@@ -20,7 +20,17 @@
 #define TB_CTL_RETRIES		4
 
 /**
- * struct tb_cfg - thunderbolt control channel
+ * struct tb_ctl - Thunderbolt control channel
+ * @nhi: Pointer to the NHI structure
+ * @tx: Transmit ring
+ * @rx: Receive ring
+ * @frame_pool: DMA pool for control messages
+ * @rx_packets: Received control messages
+ * @request_queue_lock: Lock protecting @request_queue
+ * @request_queue: List of outstanding requests
+ * @running: Is the control channel running at the moment
+ * @callback: Callback called when hotplug message is received
+ * @callback_data: Data passed to @callback
  */
 struct tb_ctl {
 	struct tb_nhi *nhi;
@@ -602,6 +612,9 @@ struct tb_cfg_result tb_cfg_request_sync(struct tb_ctl *ctl,
 
 /**
  * tb_ctl_alloc() - allocate a control channel
+ * @nhi: Pointer to NHI
+ * @cb: Callback called for plug events
+ * @cb_data: Data passed to @cb
  *
  * cb will be invoked once for every hot plug event.
  *
@@ -649,6 +662,7 @@ struct tb_ctl *tb_ctl_alloc(struct tb_nhi *nhi, event_cb cb, void *cb_data)
 
 /**
  * tb_ctl_free() - free a control channel
+ * @ctl: Control channel to free
  *
  * Must be called after tb_ctl_stop.
  *
@@ -677,6 +691,7 @@ void tb_ctl_free(struct tb_ctl *ctl)
 
 /**
  * tb_cfg_start() - start/resume the control channel
+ * @ctl: Control channel to start
  */
 void tb_ctl_start(struct tb_ctl *ctl)
 {
@@ -691,7 +706,8 @@ void tb_ctl_start(struct tb_ctl *ctl)
 }
 
 /**
- * control() - pause the control channel
+ * tb_ctrl_stop() - pause the control channel
+ * @ctl: Control channel to stop
  *
  * All invocations of ctl->callback will have finished after this method
  * returns.
@@ -784,6 +800,9 @@ static bool tb_cfg_copy(struct tb_cfg_request *req, const struct ctl_pkg *pkg)
 
 /**
  * tb_cfg_reset() - send a reset packet and wait for a response
+ * @ctl: Control channel pointer
+ * @route: Router string for the router to send reset
+ * @timeout_msec: Timeout in ms how long to wait for the response
  *
  * If the switch at route is incorrectly configured then we will not receive a
  * reply (even though the switch will reset). The caller should check for
@@ -820,9 +839,17 @@ struct tb_cfg_result tb_cfg_reset(struct tb_ctl *ctl, u64 route,
 }
 
 /**
- * tb_cfg_read() - read from config space into buffer
+ * tb_cfg_read_raw() - read from config space into buffer
+ * @ctl: Pointer to the control channel
+ * @buffer: Buffer where the data is read
+ * @route: Route string of the router
+ * @port: Port number when reading from %TB_CFG_PORT, %0 otherwise
+ * @space: Config space selector
+ * @offset: Dword word offset of the register to start reading
+ * @length: Number of dwords to read
+ * @timeout_msec: Timeout in ms how long to wait for the response
  *
- * Offset and length are in dwords.
+ * Reads from router config space without translating the possible error.
  */
 struct tb_cfg_result tb_cfg_read_raw(struct tb_ctl *ctl, void *buffer,
 		u64 route, u32 port, enum tb_cfg_space space,
@@ -884,8 +911,16 @@ struct tb_cfg_result tb_cfg_read_raw(struct tb_ctl *ctl, void *buffer,
 
 /**
  * tb_cfg_write() - write from buffer into config space
+ * @ctl: Pointer to the control channel
+ * @buffer: Data to write
+ * @route: Route string of the router
+ * @port: Port number when writing to %TB_CFG_PORT, %0 otherwise
+ * @space: Config space selector
+ * @offset: Dword word offset of the register to start writing
+ * @length: Number of dwords to write
+ * @timeout_msec: Timeout in ms how long to wait for the response
  *
- * Offset and length are in dwords.
+ * Writes to router config space without translating the possible error.
  */
 struct tb_cfg_result tb_cfg_write_raw(struct tb_ctl *ctl, const void *buffer,
 		u64 route, u32 port, enum tb_cfg_space space,
@@ -1022,6 +1057,8 @@ int tb_cfg_write(struct tb_ctl *ctl, const void *buffer, u64 route, u32 port,
 
 /**
  * tb_cfg_get_upstream_port() - get upstream port number of switch at route
+ * @ctl: Pointer to the control channel
+ * @route: Route string of the router
  *
  * Reads the first dword from the switches TB_CFG_SWITCH config area and
  * returns the port number from which the reply originated.
-- 
2.29.2

Re: [PATCH 1/5] thunderbolt: ctl: Fix kernel-doc descriptions of non-static functions

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> Fix kernel-doc descriptions of all non-static functions and struct
> tb_cfg. Gets rid of several warnings on W=1 builds too.
> 
> Reported-by: Lee Jones <lee.jones@linaro.org>
> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>  drivers/thunderbolt/ctl.c | 47 ++++++++++++++++++++++++++++++++++-----
>  1 file changed, 42 insertions(+), 5 deletions(-)

Reviewed-by: Lee Jones <lee.jones@linaro.org>

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

[PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

Fix kernel-doc descriptions of the two non-static functions. This also
gets rid of the rest of the warnings on W=1 build.

Reported-by: Lee Jones <lee.jones@linaro.org>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/eeprom.c | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/drivers/thunderbolt/eeprom.c b/drivers/thunderbolt/eeprom.c
index 63c64f503faa..dd03d3096653 100644
--- a/drivers/thunderbolt/eeprom.c
+++ b/drivers/thunderbolt/eeprom.c
@@ -279,7 +279,9 @@ struct tb_drom_entry_port {
 
 
 /**
- * tb_drom_read_uid_only - read uid directly from drom
+ * tb_drom_read_uid_only() - Read UID directly from DROM
+ * @sw: Router whose UID to read
+ * @uid: UID is placed here
  *
  * Does not use the cached copy in sw->drom. Used during resume to check switch
  * identity.
@@ -520,7 +522,14 @@ static int tb_drom_read_n(struct tb_switch *sw, u16 offset, u8 *val,
 }
 
 /**
- * tb_drom_read - copy drom to sw->drom and parse it
+ * tb_drom_read() - Copy DROM to sw->drom and parse it
+ * @sw: Router whose DROM to read and parse
+ *
+ * This function reads router DROM and if successful parses the entries and
+ * populates the fields in @sw accordingly. Can be called for any router
+ * generation.
+ *
+ * Returns %0 in case of success and negative errno otherwise.
  */
 int tb_drom_read(struct tb_switch *sw)
 {
-- 
2.29.2

Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> Fix kernel-doc descriptions of the two non-static functions. This also
> gets rid of the rest of the warnings on W=1 build.
> 
> Reported-by: Lee Jones <lee.jones@linaro.org>
> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>  drivers/thunderbolt/eeprom.c | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/thunderbolt/eeprom.c b/drivers/thunderbolt/eeprom.c
> index 63c64f503faa..dd03d3096653 100644
> --- a/drivers/thunderbolt/eeprom.c
> +++ b/drivers/thunderbolt/eeprom.c
> @@ -279,7 +279,9 @@ struct tb_drom_entry_port {
>  
>  
>  /**
> - * tb_drom_read_uid_only - read uid directly from drom
> + * tb_drom_read_uid_only() - Read UID directly from DROM

Just an FYI: the '()' aren't required per say.

> + * @sw: Router whose UID to read
> + * @uid: UID is placed here
>   *
>   * Does not use the cached copy in sw->drom. Used during resume to check switch
>   * identity.
> @@ -520,7 +522,14 @@ static int tb_drom_read_n(struct tb_switch *sw, u16 offset, u8 *val,
>  }
>  
>  /**
> - * tb_drom_read - copy drom to sw->drom and parse it
> + * tb_drom_read() - Copy DROM to sw->drom and parse it
> + * @sw: Router whose DROM to read and parse
> + *
> + * This function reads router DROM and if successful parses the entries and
> + * populates the fields in @sw accordingly. Can be called for any router
> + * generation.
> + *
> + * Returns %0 in case of success and negative errno otherwise.

What's %0?

>   */
>  int tb_drom_read(struct tb_switch *sw)
>  {

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

Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

On Thu, Jan 28, 2021 at 01:11:11PM +0000, Lee Jones wrote:
> On Thu, 28 Jan 2021, Mika Westerberg wrote:
> 
> > Fix kernel-doc descriptions of the two non-static functions. This also
> > gets rid of the rest of the warnings on W=1 build.
> > 
> > Reported-by: Lee Jones <lee.jones@linaro.org>
> > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > ---
> >  drivers/thunderbolt/eeprom.c | 13 +++++++++++--
> >  1 file changed, 11 insertions(+), 2 deletions(-)
> > 
> > diff --git a/drivers/thunderbolt/eeprom.c b/drivers/thunderbolt/eeprom.c
> > index 63c64f503faa..dd03d3096653 100644
> > --- a/drivers/thunderbolt/eeprom.c
> > +++ b/drivers/thunderbolt/eeprom.c
> > @@ -279,7 +279,9 @@ struct tb_drom_entry_port {
> >  
> >  
> >  /**
> > - * tb_drom_read_uid_only - read uid directly from drom
> > + * tb_drom_read_uid_only() - Read UID directly from DROM
> 
> Just an FYI: the '()' aren't required per say.

Right. I have been using them in this driver so I thought it is good
idea to add them here too while at it.

> > + * @sw: Router whose UID to read
> > + * @uid: UID is placed here
> >   *
> >   * Does not use the cached copy in sw->drom. Used during resume to check switch
> >   * identity.
> > @@ -520,7 +522,14 @@ static int tb_drom_read_n(struct tb_switch *sw, u16 offset, u8 *val,
> >  }
> >  
> >  /**
> > - * tb_drom_read - copy drom to sw->drom and parse it
> > + * tb_drom_read() - Copy DROM to sw->drom and parse it
> > + * @sw: Router whose DROM to read and parse
> > + *
> > + * This function reads router DROM and if successful parses the entries and
> > + * populates the fields in @sw accordingly. Can be called for any router
> > + * generation.
> > + *
> > + * Returns %0 in case of success and negative errno otherwise.
> 
> What's %0?

It is 0 but marked as "constant" in the output.

> 
> >   */
> >  int tb_drom_read(struct tb_switch *sw)
> >  {
> 
> -- 
> Lee Jones [李琼斯]
> Senior Technical Lead - Developer Services
> Linaro.org │ Open source software for Arm SoCs
> Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> On Thu, Jan 28, 2021 at 01:11:11PM +0000, Lee Jones wrote:
> > On Thu, 28 Jan 2021, Mika Westerberg wrote:
> > 
> > > Fix kernel-doc descriptions of the two non-static functions. This also
> > > gets rid of the rest of the warnings on W=1 build.
> > > 
> > > Reported-by: Lee Jones <lee.jones@linaro.org>
> > > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > > ---
> > >  drivers/thunderbolt/eeprom.c | 13 +++++++++++--
> > >  1 file changed, 11 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/drivers/thunderbolt/eeprom.c b/drivers/thunderbolt/eeprom.c
> > > index 63c64f503faa..dd03d3096653 100644
> > > --- a/drivers/thunderbolt/eeprom.c
> > > +++ b/drivers/thunderbolt/eeprom.c
> > > @@ -279,7 +279,9 @@ struct tb_drom_entry_port {
> > >  
> > >  
> > >  /**
> > > - * tb_drom_read_uid_only - read uid directly from drom
> > > + * tb_drom_read_uid_only() - Read UID directly from DROM
> > 
> > Just an FYI: the '()' aren't required per say.
> 
> Right. I have been using them in this driver so I thought it is good
> idea to add them here too while at it.
> 
> > > + * @sw: Router whose UID to read
> > > + * @uid: UID is placed here
> > >   *
> > >   * Does not use the cached copy in sw->drom. Used during resume to check switch
> > >   * identity.
> > > @@ -520,7 +522,14 @@ static int tb_drom_read_n(struct tb_switch *sw, u16 offset, u8 *val,
> > >  }
> > >  
> > >  /**
> > > - * tb_drom_read - copy drom to sw->drom and parse it
> > > + * tb_drom_read() - Copy DROM to sw->drom and parse it
> > > + * @sw: Router whose DROM to read and parse
> > > + *
> > > + * This function reads router DROM and if successful parses the entries and
> > > + * populates the fields in @sw accordingly. Can be called for any router
> > > + * generation.
> > > + *
> > > + * Returns %0 in case of success and negative errno otherwise.
> > 
> > What's %0?
> 
> It is 0 but marked as "constant" in the output.

Interesting.  I wonder what it actually does.

Not sure if it's just my eyes playing me up, but is the font slightly
different for items marked as const:

 mm/memblock.c: https://www.kernel.org/doc/html/latest/core-api/boot-time-mm.html

Anyway, either way:

Reviewed-by: Lee Jones <lee.jones@linaro.org>

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

Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions

[Lukas Wunner]

On Thu, Jan 28, 2021 at 03:29:31PM +0300, Mika Westerberg wrote:
>  /**
> - * tb_drom_read - copy drom to sw->drom and parse it
> + * tb_drom_read() - Copy DROM to sw->drom and parse it
> + * @sw: Router whose DROM to read and parse
> + *
> + * This function reads router DROM and if successful parses the entries and
> + * populates the fields in @sw accordingly. Can be called for any router
> + * generation.
> + *
> + * Returns %0 in case of success and negative errno otherwise.
>   */
>  int tb_drom_read(struct tb_switch *sw)
>  {

I'm confused by the terminology change of "router" vs. "switch".
Is this change mandated by USB4?

The parameter is a tb_switch, so calling it a router looks a little odd.

Thanks,

Lukas

Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

Hi,

On Thu, Jan 28, 2021 at 09:57:19PM +0100, Lukas Wunner wrote:
> On Thu, Jan 28, 2021 at 03:29:31PM +0300, Mika Westerberg wrote:
> >  /**
> > - * tb_drom_read - copy drom to sw->drom and parse it
> > + * tb_drom_read() - Copy DROM to sw->drom and parse it
> > + * @sw: Router whose DROM to read and parse
> > + *
> > + * This function reads router DROM and if successful parses the entries and
> > + * populates the fields in @sw accordingly. Can be called for any router
> > + * generation.
> > + *
> > + * Returns %0 in case of success and negative errno otherwise.
> >   */
> >  int tb_drom_read(struct tb_switch *sw)
> >  {
> 
> I'm confused by the terminology change of "router" vs. "switch".
> Is this change mandated by USB4?

Not mandated.

> The parameter is a tb_switch, so calling it a router looks a little odd.

Right. I'm trying to use the "new" terminology in the comments so that
people reading those might be able to match it better with the spec.
Even though in code we still have tb_switch, tb_port etc. Perhaps we can
mention in kernel-docs of struct tb_switch and others the corresponding
USB4 spec term?

[PATCH 3/5] thunderbolt: path: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

Fix kernel-doc descriptions of the two non-static functions. This also
gets rid of the warnings on W=1 build.

Reported-by: Lee Jones <lee.jones@linaro.org>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/path.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/thunderbolt/path.c b/drivers/thunderbolt/path.c
index ca7d738d66de..f63e205a35d9 100644
--- a/drivers/thunderbolt/path.c
+++ b/drivers/thunderbolt/path.c
@@ -466,6 +466,7 @@ void tb_path_deactivate(struct tb_path *path)
 
 /**
  * tb_path_activate() - activate a path
+ * @path: Path to activate
  *
  * Activate a path starting with the last hop and iterating backwards. The
  * caller must fill path->hops before calling tb_path_activate().
@@ -561,6 +562,7 @@ int tb_path_activate(struct tb_path *path)
 
 /**
  * tb_path_is_invalid() - check whether any ports on the path are invalid
+ * @path: Path to check
  *
  * Return: Returns true if the path is invalid, false otherwise.
  */
-- 
2.29.2

Re: [PATCH 3/5] thunderbolt: path: Fix kernel-doc descriptions of non-static functions

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> Fix kernel-doc descriptions of the two non-static functions. This also
> gets rid of the warnings on W=1 build.
> 
> Reported-by: Lee Jones <lee.jones@linaro.org>
> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>  drivers/thunderbolt/path.c | 2 ++
>  1 file changed, 2 insertions(+)

Reviewed-by: Lee Jones <lee.jones@linaro.org>

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

[PATCH 4/5] thunderbolt: nhi: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

Fix kernel-doc descriptions of the two non-static functions. This also
gets rids of the warnings on W=1 build.

Reported-by: Lee Jones <lee.jones@linaro.org>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/nhi.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/thunderbolt/nhi.c b/drivers/thunderbolt/nhi.c
index 7073c25248b3..782404eb10b0 100644
--- a/drivers/thunderbolt/nhi.c
+++ b/drivers/thunderbolt/nhi.c
@@ -592,6 +592,7 @@ EXPORT_SYMBOL_GPL(tb_ring_alloc_rx);
 
 /**
  * tb_ring_start() - enable a ring
+ * @ring: Ring to start
  *
  * Must not be invoked in parallel with tb_ring_stop().
  */
@@ -667,6 +668,7 @@ EXPORT_SYMBOL_GPL(tb_ring_start);
 
 /**
  * tb_ring_stop() - shutdown a ring
+ * @ring: Ring to stop
  *
  * Must not be invoked from a callback.
  *
-- 
2.29.2

Re: [PATCH 4/5] thunderbolt: nhi: Fix kernel-doc descriptions of non-static functions

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> Fix kernel-doc descriptions of the two non-static functions. This also
> gets rids of the warnings on W=1 build.
> 
> Reported-by: Lee Jones <lee.jones@linaro.org>
> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>  drivers/thunderbolt/nhi.c | 2 ++
>  1 file changed, 2 insertions(+)

Reviewed-by: Lee Jones <lee.jones@linaro.org>

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

[PATCH 5/5] thunderbolt: switch: Fix kernel-doc descriptions of non-static functions

[Mika Westerberg]

Fix kernel-doc descriptions of all non-static functions. This also gets
rid of the warnings on W=1 build.

Reported-by: Lee Jones <lee.jones@linaro.org>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/switch.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/drivers/thunderbolt/switch.c b/drivers/thunderbolt/switch.c
index 6ca3efba4520..6e2ca8f066f5 100644
--- a/drivers/thunderbolt/switch.c
+++ b/drivers/thunderbolt/switch.c
@@ -525,6 +525,8 @@ int tb_port_state(struct tb_port *port)
 
 /**
  * tb_wait_for_port() - wait for a port to become ready
+ * @port: Port to wait
+ * @wait_if_unplugged: Wait also when @port is unplugged
  *
  * Wait up to 1 second for a port to reach state TB_PORT_UP. If
  * wait_if_unplugged is set then we also wait if the port is in state
@@ -589,6 +591,8 @@ int tb_wait_for_port(struct tb_port *port, bool wait_if_unplugged)
 
 /**
  * tb_port_add_nfc_credits() - add/remove non flow controlled credits to port
+ * @port: Port to add/remove NFC credits
+ * @credits: Credits to add/remove
  *
  * Change the number of NFC credits allocated to @port by @credits. To remove
  * NFC credits pass a negative amount of credits.
@@ -646,6 +650,8 @@ int tb_port_set_initial_credits(struct tb_port *port, u32 credits)
 
 /**
  * tb_port_clear_counter() - clear a counter in TB_CFG_COUNTER
+ * @port: Port whose counters to clear
+ * @counter: Counter index to clear
  *
  * Return: Returns 0 on success or an error code on failure.
  */
@@ -2649,6 +2655,7 @@ void tb_switch_remove(struct tb_switch *sw)
 
 /**
  * tb_sw_set_unplugged() - set is_unplugged on switch and downstream switches
+ * @sw: Router to mark unplugged
  */
 void tb_sw_set_unplugged(struct tb_switch *sw)
 {
-- 
2.29.2

Re: [PATCH 5/5] thunderbolt: switch: Fix kernel-doc descriptions of non-static functions

[Lee Jones]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> Fix kernel-doc descriptions of all non-static functions. This also gets
> rid of the warnings on W=1 build.
> 
> Reported-by: Lee Jones <lee.jones@linaro.org>
> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>  drivers/thunderbolt/switch.c | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/drivers/thunderbolt/switch.c b/drivers/thunderbolt/switch.c
> index 6ca3efba4520..6e2ca8f066f5 100644
> --- a/drivers/thunderbolt/switch.c
> +++ b/drivers/thunderbolt/switch.c
> @@ -525,6 +525,8 @@ int tb_port_state(struct tb_port *port)
>  
>  /**
>   * tb_wait_for_port() - wait for a port to become ready
> + * @port: Port to wait
> + * @wait_if_unplugged: Wait also when @port is unplugged

Nit: @port is usually used to specify the parameter directly.  In this
case I think you just want to say 'port', as you're referencing the
physical (or virtual) port, rather than this functions parameter.

Other than that, looks good:

Reviewed-by: Lee Jones <lee.jones@linaro.org>

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