thunderbolt: Fix kernel-doc descriptions of non-static functions
Subsystems (2)
v2 cover thunderbolt: Fix kernel-doc descriptions of non-static functions
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/[email protected]/
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/[email protected]/
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(-)
Signature · 1 line
2.29.2
PATCH v2 1/6 thunderbolt: ctl: Fix kernel-doc descriptions of non-static functions
Fix kernel-doc descriptions of all non-static functions and struct tb_cfg. Gets rid of several warnings on W=1 builds too.
--- drivers/thunderbolt/ctl.c | 47 ++++++++++++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 5 deletions(-)
drivers/thunderbolt/ctl.c +42 -5
@@ -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.
Signature · 1 line
2.29.2
PATCH v2 2/6 thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
In reply to Mika WesterbergFix kernel-doc descriptions of the two non-static functions. This also gets rid of the rest of the warnings on W=1 build.
--- drivers/thunderbolt/eeprom.c | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-)
drivers/thunderbolt/eeprom.c +11 -2
@@ -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) {
Signature · 1 line
2.29.2
PATCH v2 3/6 thunderbolt: path: Fix kernel-doc descriptions of non-static functions
In reply to Mika WesterbergFix kernel-doc descriptions of the two non-static functions. This also gets rid of the warnings on W=1 build.
--- drivers/thunderbolt/path.c | 2 ++ 1 file changed, 2 insertions(+)
drivers/thunderbolt/path.c +2 -0
@@ -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. */
Signature · 1 line
2.29.2
PATCH v2 4/6 thunderbolt: nhi: Fix kernel-doc descriptions of non-static functions
In reply to Mika WesterbergFix kernel-doc descriptions of the two non-static functions. This also gets rids of the warnings on W=1 build.
--- drivers/thunderbolt/nhi.c | 2 ++ 1 file changed, 2 insertions(+)
drivers/thunderbolt/nhi.c +2 -0
@@ -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. *
Signature · 1 line
2.29.2
PATCH v2 5/6 thunderbolt: switch: Fix kernel-doc descriptions of non-static functions
In reply to Mika WesterbergFix kernel-doc descriptions of all non-static functions. This also gets rid of the warnings on W=1 build.
--- drivers/thunderbolt/switch.c | 7 +++++++ 1 file changed, 7 insertions(+)
drivers/thunderbolt/switch.c +7 -0
@@ -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) {
Signature · 1 line
2.29.2
PATCH v2 6/6 thunderbolt: Add clarifying comments about USB4 terms router and adapter
In reply to Mika WesterbergUSB4 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.
--- drivers/thunderbolt/tb.h | 5 +++++ 1 file changed, 5 insertions(+)
drivers/thunderbolt/tb.h +5 -0
@@ -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;
Signature · 1 line
2.29.2
Quoted 23 lines · 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/[email protected]/
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/[email protected]/
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.
Quoted 7 lines
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.