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

[PATCH v2 0/6] 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.

v1 can be found here:

  https://lore.kernel.org/linux-usb/20210128122934.36897-1-mika.westerberg@linux.intel.com/

Changes from v1:

  * Drop @ before port in patch 5/6.
  * Added tags from Lee Jones.
  * New patch that clarifies router/adapter USB4 terms in structs
    tb_switch/port.

Mika Westerberg (6):
  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
  thunderbolt: Add clarifying comments about USB4 terms router and adapter

 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 ++++++
 drivers/thunderbolt/tb.h     |  5 ++++
 6 files changed, 69 insertions(+), 7 deletions(-)

-- 
2.29.2

[PATCH v2 1/6] 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>
Reviewed-by: Lee Jones <lee.jones@linaro.org>
---
 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

[PATCH v2 2/6] 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>
Reviewed-by: Lee Jones <lee.jones@linaro.org>
---
 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

[PATCH v2 3/6] 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>
Reviewed-by: Lee Jones <lee.jones@linaro.org>
---
 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

[PATCH v2 4/6] 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>
Reviewed-by: Lee Jones <lee.jones@linaro.org>
---
 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

[PATCH v2 5/6] 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>
Reviewed-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/thunderbolt/switch.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/drivers/thunderbolt/switch.c b/drivers/thunderbolt/switch.c
index 6ca3efba4520..5377d0a3390f 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

[PATCH v2 6/6] thunderbolt: Add clarifying comments about USB4 terms router and adapter

[Mika Westerberg]

USB4 spec talks about routers and adapters whereas Thunderbolt 1-3
talked about CIO (Converged I/O) switches and ports. These are the same
thing but might cause confusion so add clarifying comments to struct
tb_switch and struct tb_port about the USB4 terms.

Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/tb.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/thunderbolt/tb.h b/drivers/thunderbolt/tb.h
index 31468de658e4..37679b54808d 100644
--- a/drivers/thunderbolt/tb.h
+++ b/drivers/thunderbolt/tb.h
@@ -138,6 +138,8 @@ struct tb_switch_tmu {
  *
  * When the switch is being added or removed to the domain (other
  * switches) you need to have domain lock held.
+ *
+ * In USB4 terminology this structure represents a router.
  */
 struct tb_switch {
 	struct device dev;
@@ -196,6 +198,9 @@ struct tb_switch {
  * @in_hopids: Currently allocated input HopIDs
  * @out_hopids: Currently allocated output HopIDs
  * @list: Used to link ports to DP resources list
+ *
+ * In USB4 terminology this structure represents an adapter (protocol or
+ * lane adapter).
  */
 struct tb_port {
 	struct tb_regs_port_header config;
-- 
2.29.2

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

[Mika Westerberg]

On Mon, Feb 01, 2021 at 03:16:23PM +0300, Mika Westerberg wrote:
> 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.
> 
> v1 can be found here:
> 
>   https://lore.kernel.org/linux-usb/20210128122934.36897-1-mika.westerberg@linux.intel.com/
> 
> Changes from v1:
> 
>   * Drop @ before port in patch 5/6.
>   * Added tags from Lee Jones.
>   * New patch that clarifies router/adapter USB4 terms in structs
>     tb_switch/port.
> 
> Mika Westerberg (6):
>   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
>   thunderbolt: Add clarifying comments about USB4 terms router and adapter

All applied to thunderbolt.git/next.