| Message ID | 20210128122934.36897-3-mika.westerberg@linux.intel.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | thunderbolt: Fix kernel-doc descriptions of non-static functions | expand |
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) > {
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
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>
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
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?
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) {
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(-)