* [PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions
@ 2021-01-28 12:29 Mika Westerberg
2021-01-28 12:29 ` [PATCH 1/5] thunderbolt: ctl: " Mika Westerberg
` (4 more replies)
0 siblings, 5 replies; 15+ messages in thread
From: Mika Westerberg @ 2021-01-28 12:29 UTC (permalink / raw
To: linux-usb
Cc: Yehezkel Bernat, Michael Jamet, Andreas Noever, Lukas Wunner,
Lee Jones, 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
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH 1/5] thunderbolt: ctl: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 [PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions Mika Westerberg
@ 2021-01-28 12:29 ` Mika Westerberg
2021-01-28 13:13 ` Lee Jones
2021-01-28 12:29 ` [PATCH 2/5] thunderbolt: eeprom: " Mika Westerberg
` (3 subsequent siblings)
4 siblings, 1 reply; 15+ messages in thread
From: Mika Westerberg @ 2021-01-28 12:29 UTC (permalink / raw
To: linux-usb
Cc: Yehezkel Bernat, Michael Jamet, Andreas Noever, Lukas Wunner,
Lee Jones, 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
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 [PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions Mika Westerberg
2021-01-28 12:29 ` [PATCH 1/5] thunderbolt: ctl: " Mika Westerberg
@ 2021-01-28 12:29 ` Mika Westerberg
2021-01-28 13:11 ` Lee Jones
2021-01-28 20:57 ` Lukas Wunner
2021-01-28 12:29 ` [PATCH 3/5] thunderbolt: path: " Mika Westerberg
` (2 subsequent siblings)
4 siblings, 2 replies; 15+ messages in thread
From: Mika Westerberg @ 2021-01-28 12:29 UTC (permalink / raw
To: linux-usb
Cc: Yehezkel Bernat, Michael Jamet, Andreas Noever, Lukas Wunner,
Lee Jones, 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
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PATCH 3/5] thunderbolt: path: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 [PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions Mika Westerberg
2021-01-28 12:29 ` [PATCH 1/5] thunderbolt: ctl: " Mika Westerberg
2021-01-28 12:29 ` [PATCH 2/5] thunderbolt: eeprom: " Mika Westerberg
@ 2021-01-28 12:29 ` Mika Westerberg
2021-01-28 13:11 ` Lee Jones
2021-01-28 12:29 ` [PATCH 4/5] thunderbolt: nhi: " Mika Westerberg
2021-01-28 12:29 ` [PATCH 5/5] thunderbolt: switch: " Mika Westerberg
4 siblings, 1 reply; 15+ messages in thread
From: Mika Westerberg @ 2021-01-28 12:29 UTC (permalink / raw
To: linux-usb
Cc: Yehezkel Bernat, Michael Jamet, Andreas Noever, Lukas Wunner,
Lee Jones, 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
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PATCH 4/5] thunderbolt: nhi: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 [PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions Mika Westerberg
` (2 preceding siblings ...)
2021-01-28 12:29 ` [PATCH 3/5] thunderbolt: path: " Mika Westerberg
@ 2021-01-28 12:29 ` Mika Westerberg
2021-01-28 13:07 ` Lee Jones
2021-01-28 12:29 ` [PATCH 5/5] thunderbolt: switch: " Mika Westerberg
4 siblings, 1 reply; 15+ messages in thread
From: Mika Westerberg @ 2021-01-28 12:29 UTC (permalink / raw
To: linux-usb
Cc: Yehezkel Bernat, Michael Jamet, Andreas Noever, Lukas Wunner,
Lee Jones, 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
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PATCH 5/5] thunderbolt: switch: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 [PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions Mika Westerberg
` (3 preceding siblings ...)
2021-01-28 12:29 ` [PATCH 4/5] thunderbolt: nhi: " Mika Westerberg
@ 2021-01-28 12:29 ` Mika Westerberg
2021-01-28 13:06 ` Lee Jones
4 siblings, 1 reply; 15+ messages in thread
From: Mika Westerberg @ 2021-01-28 12:29 UTC (permalink / raw
To: linux-usb
Cc: Yehezkel Bernat, Michael Jamet, Andreas Noever, Lukas Wunner,
Lee Jones, 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
^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH 5/5] thunderbolt: switch: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 ` [PATCH 5/5] thunderbolt: switch: " Mika Westerberg
@ 2021-01-28 13:06 ` Lee Jones
0 siblings, 0 replies; 15+ messages in thread
From: Lee Jones @ 2021-01-28 13:06 UTC (permalink / raw
To: Mika Westerberg
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lukas Wunner
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 4/5] thunderbolt: nhi: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 ` [PATCH 4/5] thunderbolt: nhi: " Mika Westerberg
@ 2021-01-28 13:07 ` Lee Jones
0 siblings, 0 replies; 15+ messages in thread
From: Lee Jones @ 2021-01-28 13:07 UTC (permalink / raw
To: Mika Westerberg
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lukas Wunner
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 ` [PATCH 2/5] thunderbolt: eeprom: " Mika Westerberg
@ 2021-01-28 13:11 ` Lee Jones
2021-01-28 14:22 ` Mika Westerberg
2021-01-28 20:57 ` Lukas Wunner
1 sibling, 1 reply; 15+ messages in thread
From: Lee Jones @ 2021-01-28 13:11 UTC (permalink / raw
To: Mika Westerberg
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lukas Wunner
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 3/5] thunderbolt: path: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 ` [PATCH 3/5] thunderbolt: path: " Mika Westerberg
@ 2021-01-28 13:11 ` Lee Jones
0 siblings, 0 replies; 15+ messages in thread
From: Lee Jones @ 2021-01-28 13:11 UTC (permalink / raw
To: Mika Westerberg
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lukas Wunner
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/5] thunderbolt: ctl: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 ` [PATCH 1/5] thunderbolt: ctl: " Mika Westerberg
@ 2021-01-28 13:13 ` Lee Jones
0 siblings, 0 replies; 15+ messages in thread
From: Lee Jones @ 2021-01-28 13:13 UTC (permalink / raw
To: Mika Westerberg
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lukas Wunner
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
2021-01-28 13:11 ` Lee Jones
@ 2021-01-28 14:22 ` Mika Westerberg
2021-01-28 14:40 ` Lee Jones
0 siblings, 1 reply; 15+ messages in thread
From: Mika Westerberg @ 2021-01-28 14:22 UTC (permalink / raw
To: Lee Jones
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lukas Wunner
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
2021-01-28 14:22 ` Mika Westerberg
@ 2021-01-28 14:40 ` Lee Jones
0 siblings, 0 replies; 15+ messages in thread
From: Lee Jones @ 2021-01-28 14:40 UTC (permalink / raw
To: Mika Westerberg
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lukas Wunner
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
2021-01-28 12:29 ` [PATCH 2/5] thunderbolt: eeprom: " Mika Westerberg
2021-01-28 13:11 ` Lee Jones
@ 2021-01-28 20:57 ` Lukas Wunner
2021-01-29 7:04 ` Mika Westerberg
1 sibling, 1 reply; 15+ messages in thread
From: Lukas Wunner @ 2021-01-28 20:57 UTC (permalink / raw
To: Mika Westerberg
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lee Jones
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions
2021-01-28 20:57 ` Lukas Wunner
@ 2021-01-29 7:04 ` Mika Westerberg
0 siblings, 0 replies; 15+ messages in thread
From: Mika Westerberg @ 2021-01-29 7:04 UTC (permalink / raw
To: Lukas Wunner
Cc: linux-usb, Yehezkel Bernat, Michael Jamet, Andreas Noever,
Lee Jones
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?
^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2021-01-29 7:06 UTC | newest]
Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-01-28 12:29 [PATCH 0/5] thunderbolt: Fix kernel-doc descriptions of non-static functions Mika Westerberg
2021-01-28 12:29 ` [PATCH 1/5] thunderbolt: ctl: " Mika Westerberg
2021-01-28 13:13 ` Lee Jones
2021-01-28 12:29 ` [PATCH 2/5] thunderbolt: eeprom: " Mika Westerberg
2021-01-28 13:11 ` Lee Jones
2021-01-28 14:22 ` Mika Westerberg
2021-01-28 14:40 ` Lee Jones
2021-01-28 20:57 ` Lukas Wunner
2021-01-29 7:04 ` Mika Westerberg
2021-01-28 12:29 ` [PATCH 3/5] thunderbolt: path: " Mika Westerberg
2021-01-28 13:11 ` Lee Jones
2021-01-28 12:29 ` [PATCH 4/5] thunderbolt: nhi: " Mika Westerberg
2021-01-28 13:07 ` Lee Jones
2021-01-28 12:29 ` [PATCH 5/5] thunderbolt: switch: " Mika Westerberg
2021-01-28 13:06 ` Lee Jones
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.