[PATCH net-next] devlink: Improve the port attributes description

[PATCH net-next] devlink: Improve the port attributes description

[Parav Pandit]

Improve the description of devlink port attributes PF, VF and SF
numbers.

Reviewed-by: Shay Drory <shayd@nvidia.com>
Reviewed-by: Mark Bloch <mbloch@nvidia.com>
Reviewed-by: Jiri Pirko <jiri@nvidia.com>
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
 include/net/devlink.h | 11 ++++++-----
 net/devlink/port.c    | 11 ++++++-----
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/include/net/devlink.h b/include/net/devlink.h
index fbb9a2668e24..a1fd37dcdc73 100644
--- a/include/net/devlink.h
+++ b/include/net/devlink.h
@@ -35,7 +35,7 @@ struct devlink_port_phys_attrs {
 /**
  * struct devlink_port_pci_pf_attrs - devlink port's PCI PF attributes
  * @controller: Associated controller number
- * @pf: Associated PCI PF number for this port.
+ * @pf: associated PCI function number for the devlink port instance
  * @external: when set, indicates if a port is for an external controller
  */
 struct devlink_port_pci_pf_attrs {
@@ -47,8 +47,9 @@ struct devlink_port_pci_pf_attrs {
 /**
  * struct devlink_port_pci_vf_attrs - devlink port's PCI VF attributes
  * @controller: Associated controller number
- * @pf: Associated PCI PF number for this port.
- * @vf: Associated PCI VF for of the PCI PF for this port.
+ * @pf: associated PCI function number for the devlink port instance
+ * @vf: associated PCI VF number of a PF for the devlink port instance;
+ *	VF number starts from 0 for the first PCI virtual function
  * @external: when set, indicates if a port is for an external controller
  */
 struct devlink_port_pci_vf_attrs {
@@ -61,8 +62,8 @@ struct devlink_port_pci_vf_attrs {
 /**
  * struct devlink_port_pci_sf_attrs - devlink port's PCI SF attributes
  * @controller: Associated controller number
- * @sf: Associated PCI SF for of the PCI PF for this port.
- * @pf: Associated PCI PF number for this port.
+ * @sf: associated SF number of a PF for the devlink port instance
+ * @pf: associated PCI function number for the devlink port instance
  * @external: when set, indicates if a port is for an external controller
  */
 struct devlink_port_pci_sf_attrs {
diff --git a/net/devlink/port.c b/net/devlink/port.c
index be9158b4453c..939081a0e615 100644
--- a/net/devlink/port.c
+++ b/net/devlink/port.c
@@ -1376,7 +1376,7 @@ EXPORT_SYMBOL_GPL(devlink_port_attrs_set);
  *
  *	@devlink_port: devlink port
  *	@controller: associated controller number for the devlink port instance
- *	@pf: associated PF for the devlink port instance
+ *	@pf: associated PCI function number for the devlink port instance
  *	@external: indicates if the port is for an external controller
  */
 void devlink_port_attrs_pci_pf_set(struct devlink_port *devlink_port, u32 controller,
@@ -1402,8 +1402,9 @@ EXPORT_SYMBOL_GPL(devlink_port_attrs_pci_pf_set);
  *
  *	@devlink_port: devlink port
  *	@controller: associated controller number for the devlink port instance
- *	@pf: associated PF for the devlink port instance
- *	@vf: associated VF of a PF for the devlink port instance
+ *	@pf: associated PCI function number for the devlink port instance
+ *	@vf: associated PCI VF number of a PF for the devlink port instance;
+ *	     VF number starts from 0 for the first PCI virtual function
  *	@external: indicates if the port is for an external controller
  */
 void devlink_port_attrs_pci_vf_set(struct devlink_port *devlink_port, u32 controller,
@@ -1430,8 +1431,8 @@ EXPORT_SYMBOL_GPL(devlink_port_attrs_pci_vf_set);
  *
  *	@devlink_port: devlink port
  *	@controller: associated controller number for the devlink port instance
- *	@pf: associated PF for the devlink port instance
- *	@sf: associated SF of a PF for the devlink port instance
+ *	@pf: associated PCI function number for the devlink port instance
+ *	@sf: associated SF number of a PF for the devlink port instance
  *	@external: indicates if the port is for an external controller
  */
 void devlink_port_attrs_pci_sf_set(struct devlink_port *devlink_port, u32 controller,
-- 
2.26.2

Re: [PATCH net-next] devlink: Improve the port attributes description

[Samudrala, Sridhar]

On 12/19/2024 7:01 AM, Parav Pandit wrote:
> Improve the description of devlink port attributes PF, VF and SF
> numbers.
> 
> Reviewed-by: Shay Drory <shayd@nvidia.com>
> Reviewed-by: Mark Bloch <mbloch@nvidia.com>
> Reviewed-by: Jiri Pirko <jiri@nvidia.com>
> Signed-off-by: Parav Pandit <parav@nvidia.com>

Reviewed-by: Sridhar Samudrala <sridhar.samudrala@intel.com>

> ---
>   include/net/devlink.h | 11 ++++++-----
>   net/devlink/port.c    | 11 ++++++-----
>   2 files changed, 12 insertions(+), 10 deletions(-)
> 
> diff --git a/include/net/devlink.h b/include/net/devlink.h
> index fbb9a2668e24..a1fd37dcdc73 100644
> --- a/include/net/devlink.h
> +++ b/include/net/devlink.h
> @@ -35,7 +35,7 @@ struct devlink_port_phys_attrs {
>   /**
>    * struct devlink_port_pci_pf_attrs - devlink port's PCI PF attributes
>    * @controller: Associated controller number
> - * @pf: Associated PCI PF number for this port.
> + * @pf: associated PCI function number for the devlink port instance
>    * @external: when set, indicates if a port is for an external controller
>    */
>   struct devlink_port_pci_pf_attrs {
> @@ -47,8 +47,9 @@ struct devlink_port_pci_pf_attrs {
>   /**
>    * struct devlink_port_pci_vf_attrs - devlink port's PCI VF attributes
>    * @controller: Associated controller number
> - * @pf: Associated PCI PF number for this port.
> - * @vf: Associated PCI VF for of the PCI PF for this port.
> + * @pf: associated PCI function number for the devlink port instance
> + * @vf: associated PCI VF number of a PF for the devlink port instance;
> + *	VF number starts from 0 for the first PCI virtual function
>    * @external: when set, indicates if a port is for an external controller
>    */
>   struct devlink_port_pci_vf_attrs {
> @@ -61,8 +62,8 @@ struct devlink_port_pci_vf_attrs {
>   /**
>    * struct devlink_port_pci_sf_attrs - devlink port's PCI SF attributes
>    * @controller: Associated controller number
> - * @sf: Associated PCI SF for of the PCI PF for this port.
> - * @pf: Associated PCI PF number for this port.
> + * @sf: associated SF number of a PF for the devlink port instance
> + * @pf: associated PCI function number for the devlink port instance
>    * @external: when set, indicates if a port is for an external controller
>    */
>   struct devlink_port_pci_sf_attrs {
> diff --git a/net/devlink/port.c b/net/devlink/port.c
> index be9158b4453c..939081a0e615 100644
> --- a/net/devlink/port.c
> +++ b/net/devlink/port.c
> @@ -1376,7 +1376,7 @@ EXPORT_SYMBOL_GPL(devlink_port_attrs_set);
>    *
>    *	@devlink_port: devlink port
>    *	@controller: associated controller number for the devlink port instance
> - *	@pf: associated PF for the devlink port instance
> + *	@pf: associated PCI function number for the devlink port instance
>    *	@external: indicates if the port is for an external controller
>    */
>   void devlink_port_attrs_pci_pf_set(struct devlink_port *devlink_port, u32 controller,
> @@ -1402,8 +1402,9 @@ EXPORT_SYMBOL_GPL(devlink_port_attrs_pci_pf_set);
>    *
>    *	@devlink_port: devlink port
>    *	@controller: associated controller number for the devlink port instance
> - *	@pf: associated PF for the devlink port instance
> - *	@vf: associated VF of a PF for the devlink port instance
> + *	@pf: associated PCI function number for the devlink port instance
> + *	@vf: associated PCI VF number of a PF for the devlink port instance;
> + *	     VF number starts from 0 for the first PCI virtual function
>    *	@external: indicates if the port is for an external controller
>    */
>   void devlink_port_attrs_pci_vf_set(struct devlink_port *devlink_port, u32 controller,
> @@ -1430,8 +1431,8 @@ EXPORT_SYMBOL_GPL(devlink_port_attrs_pci_vf_set);
>    *
>    *	@devlink_port: devlink port
>    *	@controller: associated controller number for the devlink port instance
> - *	@pf: associated PF for the devlink port instance
> - *	@sf: associated SF of a PF for the devlink port instance
> + *	@pf: associated PCI function number for the devlink port instance
> + *	@sf: associated SF number of a PF for the devlink port instance
>    *	@external: indicates if the port is for an external controller
>    */
>   void devlink_port_attrs_pci_sf_set(struct devlink_port *devlink_port, u32 controller,

Re: [PATCH net-next] devlink: Improve the port attributes description

[Jakub Kicinski]

On Thu, 19 Dec 2024 17:01:58 +0200 Parav Pandit wrote:
> Improve the description of devlink port attributes PF, VF and SF
> numbers.

Please provide more context. It's not obvious why you remove PF from
descriptions but not VF or SF.
-- 
pw-bot: cr

RE: [PATCH net-next] devlink: Improve the port attributes description

[Parav Pandit]

Hi Jakub,

> From: Jakub Kicinski <kuba@kernel.org>
> Sent: Monday, December 23, 2024 11:40 PM
> 
> On Thu, 19 Dec 2024 17:01:58 +0200 Parav Pandit wrote:
> > Improve the description of devlink port attributes PF, VF and SF
> > numbers.
> 
> Please provide more context. It's not obvious why you remove PF from
> descriptions but not VF or SF.

'PF number' was vague and source of confusion. Some started thinking that it is some kind of index like how VF number is an index.
So 'PF number' is rewritten to bring the clarity that it's the function number of the PCI device which is very will described in the PCI spec.

For VF number, the description is added describing it's an index starting from 0 (unlike pci spec where vf number starts from 1).
SF number is user supplied number so nothing to remove there.

Re: [PATCH net-next] devlink: Improve the port attributes description

[Jakub Kicinski]

On Tue, 24 Dec 2024 03:40:34 +0000 Parav Pandit wrote:
> > On Thu, 19 Dec 2024 17:01:58 +0200 Parav Pandit wrote:  
> > > Improve the description of devlink port attributes PF, VF and SF
> > > numbers.  
> > 
> > Please provide more context. It's not obvious why you remove PF from
> > descriptions but not VF or SF.  
> 
> 'PF number' was vague and source of confusion. Some started thinking that it is some kind of index like how VF number is an index.
> So 'PF number' is rewritten to bring the clarity that it's the function number of the PCI device which is very will described in the PCI spec.

Just to make sure I understand - you're trying to emphasize that 
the PF number is just an arbitrary ID of the PCIe PF within the chip, 
not necessarily related to any BDF numbering sequence?

If that's the case I think the motivation makes sense. But IMHO
the execution is not ideal, I offer the fact we're having this
exchange as a proof of the point not getting across :(

May be better to explain this in a couple of sentences somewhere
(actually I get the feeling we already have such an explanation
but I can't find it. Perhaps it was just talked about on the list)
and then just point to that longer explanation in the attr kdocs?

> For VF number, the description is added describing it's an index starting from 0 (unlike pci spec where vf number starts from 1).
> SF number is user supplied number so nothing to remove there.

nit: -EOUTLOOK.. please wrap the lines in your replies at 80 chars.

RE: [PATCH net-next] devlink: Improve the port attributes description

[Parav Pandit]

> From: Jakub Kicinski <kuba@kernel.org>
> Sent: Friday, December 27, 2024 11:49 PM
> 
> On Tue, 24 Dec 2024 03:40:34 +0000 Parav Pandit wrote:
> > > On Thu, 19 Dec 2024 17:01:58 +0200 Parav Pandit wrote:
> > > > Improve the description of devlink port attributes PF, VF and SF
> > > > numbers.
> > >
> > > Please provide more context. It's not obvious why you remove PF from
> > > descriptions but not VF or SF.
> >
> > 'PF number' was vague and source of confusion. Some started thinking that
> it is some kind of index like how VF number is an index.
> > So 'PF number' is rewritten to bring the clarity that it's the function number
> of the PCI device which is very will described in the PCI spec.
> 
> Just to make sure I understand - you're trying to emphasize that the PF
> number is just an arbitrary ID of the PCIe PF within the chip, not necessarily
> related to any BDF numbering sequence?
Right. The proposed kdoc update clearly defines the pf as the 'F' of the BDF
that matches the PCIe spec, reflecting the existing implementation of
multiple drivers.

Also, the patch is clarifying the VF number (that is slightly deviated from
the pci spec).

> 
> If that's the case I think the motivation makes sense. But IMHO the execution
> is not ideal, I offer the fact we're having this exchange as a proof of the point
> not getting across :(
> 
> May be better to explain this in a couple of sentences somewhere (actually I
> get the feeling we already have such an explanation but I can't find it.
> Perhaps it was just talked about on the list) and then just point to that longer
> explanation in the attr kdocs?
What part of the 'longer explanation' would you like to have in the attr kdocs?
Do you mean to tell that it is the 'F' of the BDF?
'PCI function number' as wrote in v1 is a string that one can grep very easily
in the PCI spec; hence I didn't write it as 'F' of the BDF..

Can you please check v1 commit log - is the motivation explained enough?

> 
> > For VF number, the description is added describing it's an index starting
> from 0 (unlike pci spec where vf number starts from 1).
> > SF number is user supplied number so nothing to remove there.
> 
> nit: -EOUTLOOK.. please wrap the lines in your replies at 80 chars.
Ack.