Skip to contentSkip to conversation

devlink: Add devlink port documentation

PATCH Superseded Parav Pandit 4 participants 22 messages Nov 30, 2020 – Dec 8, 2020

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 devlink: Add devlink port documentation

Added documentation for devlink port and port function related commands.

---
 .../networking/devlink/devlink-port.rst       | 102 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 103 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +102 -0
new file mode 100644
index 000000000000..966d2ee328a6
@@ -0,0 +1,102 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` provides capability for a driver to expose various
+flavours of ports which exist on device. A devlink port can of an
+embedded switch (eswitch) present on the device.
+
+A devlink port can be of 3 diffferent types.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - This type is set for a devlink port when a physical link layer of the port
+       is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - This type is set for a devlink port when a physical link layer of the port
+       is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+Devlink port can be of few different flavours described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of port which is physically facing the user. This can be
+       a eswitch physical port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a interconnect port in a distributed switch architecture.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing PCI physical function(PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing PCI virtual function(VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port facing the user.
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates an virtual port facing the user.
+
+A devlink port may be for a controller consist of one or more PCI device(s).
+A devlink instance holds ports of two types of controllers.
+
+(1) controller discovered on same system where eswitch resides
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system.
+
+An example view of two controller systems::
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the port of a PCI function.
+A user can configure the port function attributes before enumerating the
+function. For example user may set the hardware address of the function
+represented by the devlink port.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
Signature · 1 line
2.26.2
#1 lore raw
Quoted 4 lines · Parav Pandit

Added documentation for devlink port and port function related commands.

Good to see this! I saw a couple of minor nits.

- Jake

Quoted 12 lines
---
 .../networking/devlink/devlink-port.rst       | 102 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 103 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +0 -0
new file mode 100644
index 000000000000..966d2ee328a6

Documentation/networking/devlink/devlink-port.rst line 10

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
@@ -0,0 +1,102 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` provides capability for a driver to expose various
+flavours of ports which exist on device. A devlink port can of an
+embedded switch (eswitch) present on the device.
+

Seems like a word is missing here in the "A devlink port can of an embedded switch". Perhaps "Can be of"?

Quoted 29 lines
Documentation/networking/devlink/devlink-port.rst new file +29 -0
+A devlink port can be of 3 diffferent types.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - This type is set for a devlink port when a physical link layer of the port
+       is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - This type is set for a devlink port when a physical link layer of the port
+       is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+Devlink port can be of few different flavours described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of port which is physically facing the user. This can be
+       a eswitch physical port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port.

Documentation/networking/devlink/devlink-port.rst line 49

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a interconnect port in a distributed switch architecture.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing PCI physical function(PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing PCI virtual function(VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port facing the user.
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates an virtual port facing the user.

DEVLINK_PORT_FLAVOUR_VIRTUAL is repeated.

Documentation/networking/devlink/devlink-port.rst line 53

Quoted 4 lines
Documentation/networking/devlink/devlink-port.rst new file +4 -0
+
+A devlink port may be for a controller consist of one or more PCI device(s).
+A devlink instance holds ports of two types of controllers.
+

s/consist/consisting/ ?

Quoted 62 lines
Documentation/networking/devlink/devlink-port.rst new file +49 -0
+(1) controller discovered on same system where eswitch resides
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system.
+
+An example view of two controller systems::
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the port of a PCI function.
+A user can configure the port function attributes before enumerating the
+function. For example user may set the hardware address of the function
+represented by the devlink port.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
#2 lore raw
Quoted 7 lines

From: Jacob Keller <[email protected]>
Sent: Tuesday, December 1, 2020 12:59 AM

Quoted 8 lines
Quoted 4 lines · Parav Pandit

Added documentation for devlink port and port function related commands.

Good to see this! I saw a couple of minor nits.

Thanks, fixing them.

Quoted 20 lines

- Jake

Quoted 18 lines
---
 .../networking/devlink/devlink-port.rst       | 102 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 103 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +5 -0
new file mode 100644
index 000000000000..966d2ee328a6
@@ -0,0 +1,102 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
Quoted 9 lines

Documentation/networking/devlink/devlink-port.rst line 10

Quoted 5 lines
Documentation/networking/devlink/devlink-port.rst new file +5 -0
+
+``devlink-port`` provides capability for a driver to expose various
+flavours of ports which exist on device. A devlink port can of an
+embedded switch (eswitch) present on the device.
+

Seems like a word is missing here in the "A devlink port can of an embedded switch". Perhaps "Can be of"?

Yes.

Quoted 33 lines
Quoted 33 lines
Documentation/networking/devlink/devlink-port.rst new file +33 -0
+A devlink port can be of 3 diffferent types.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - This type is set for a devlink port when a physical link layer of the port
+       is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - This type is set for a devlink port when a physical link layer of the port
+       is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+Devlink port can be of few different flavours described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of port which is physically facing the user. This can be
+       a eswitch physical port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a interconnect port in a distributed switch architecture.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing PCI physical function(PF).
Quoted 9 lines

Documentation/networking/devlink/devlink-port.rst line 49

Quoted 6 lines
Documentation/networking/devlink/devlink-port.rst new file +6 -0
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing PCI virtual function(VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port facing the user.
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates an virtual port facing the user.

DEVLINK_PORT_FLAVOUR_VIRTUAL is repeated.

Removing it.

Quoted 7 lines

Documentation/networking/devlink/devlink-port.rst line 53

Quoted 4 lines
Documentation/networking/devlink/devlink-port.rst new file +4 -0
+
+A devlink port may be for a controller consist of one or more PCI device(s).
+A devlink instance holds ports of two types of controllers.
+

s/consist/consisting/ ?

Yes.

#3 lore raw

PATCH v2 1/1 devlink: Add devlink port documentation

In reply to Parav Pandit

Added documentation for devlink port and port function related commands.

---
Changelog:
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 100 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 101 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +100 -0
new file mode 100644
index 000000000000..f3ed65acbd52
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` provides capability for a driver to expose various
+flavours of ports which exist on device. A devlink port can be of an
+embedded switch (eswitch) present on the device.
+
+A devlink port can be of 3 diffferent types.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - This type is set for a devlink port when a physical link layer of the port
+       is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - This type is set for a devlink port when a physical link layer of the port
+       is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+Devlink port can be of few different flavours described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of port which is physically facing the user. This can be
+       a eswitch physical port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a interconnect port in a distributed switch architecture.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing PCI physical function(PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing PCI virtual function(VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port facing the user.
+
+A devlink port may be for a controller consisting one or more PCI device(s).
+A devlink instance holds ports of two types of controllers.
+
+(1) controller discovered on same system where eswitch resides
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system.
+
+An example view of two controller systems::
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the port of a PCI function.
+A user can configure the port function attributes before enumerating the
+function. For example user may set the hardware address of the function
+represented by the devlink port.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
Signature · 1 line
2.26.2
Reviewed-by on v2 1/1
#4 lore raw
Quoted 10 lines

-----Original Message-----
From: Parav Pandit <[email protected]>
Sent: Monday, November 30, 2020 12:00 PM
To: [email protected]; [email protected]; [email protected]
Cc: Keller, Jacob E <[email protected]>; Parav Pandit <[email protected]>; Jiri Pirko <[email protected]>
Subject: [PATCH net-next v2] devlink: Add devlink port documentation

Quoted 4 lines

Added documentation for devlink port and port function related commands.

Quoted 134 lines

---
Changelog:
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 100 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 101 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +100 -0
new file mode 100644
index 000000000000..f3ed65acbd52
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` provides capability for a driver to expose various
+flavours of ports which exist on device. A devlink port can be of an
+embedded switch (eswitch) present on the device.
+
+A devlink port can be of 3 diffferent types.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - This type is set for a devlink port when a physical link layer of the port
+       is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - This type is set for a devlink port when a physical link layer of the port
+       is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+Devlink port can be of few different flavours described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of port which is physically facing the user. This can be
+       a eswitch physical port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a interconnect port in a distributed switch architecture.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing PCI physical function(PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing PCI virtual function(VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port facing the user.
+
+A devlink port may be for a controller consisting one or more PCI device(s).
+A devlink instance holds ports of two types of controllers.
+
+(1) controller discovered on same system where eswitch resides
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system.
+
+An example view of two controller systems::
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the port of a PCI function.
+A user can configure the port function attributes before enumerating the
+function. For example user may set the hardware address of the function
+represented by the devlink port.
Documentation/networking/devlink/index.rst +1 -1
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
--

2.26.2

maintainer
#5 lore raw
In reply to Parav Pandit

Documentation/networking/devlink/devlink-port.rst line 9

Quoted 12 lines · On Mon, 30 Nov 2020 22:00:25 +0200 Parav Pandit wrote:

Added documentation for devlink port and port function related commands.

+============

Documentation/networking/devlink/devlink-port.rst new file +6 -0
+Devlink Port
+============
+
+``devlink-port`` provides capability for a driver to expose various
+flavours of ports which exist on device. A devlink port can be of an
+embedded switch (eswitch) present on the device.

The wording is a little awkward here.

The first paragraph should clarify what object represents.

This just says it exposes ports that exist.

A better phrasing would be to say that these are ports of an eswitch, in trivial case the only ports will be the physical ports of the card.

Quoted 1 line

+A devlink port can be of 3 diffferent types.

"can be of" repeated from the previous line

Documentation/networking/devlink/devlink-port.rst line 19

Quoted 7 lines

+.. list-table:: List of devlink port types

Documentation/networking/devlink/devlink-port.rst new file +6 -0
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - This type is set for a devlink port when a physical link layer of the port

Is "physical link layer" a thing? I the common names are physical layer and a (data) link layer. I don't think I've seen physical link layer, or would know what it is...

Documentation/networking/devlink/devlink-port.rst line 26

Quoted 7 lines
Documentation/networking/devlink/devlink-port.rst new file +7 -0
+       is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - This type is set for a devlink port when a physical link layer of the port
+       is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.

IMO type should be after flavor. Flavor is a higher level attribute, only physical ports have a type.

Documentation/networking/devlink/devlink-port.rst line 36

Quoted 9 lines
Documentation/networking/devlink/devlink-port.rst new file +9 -0
+Devlink port can be of few different flavours described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of port which is physically facing the user. This can be

Hm. Not a great phrasing :(

It faces a physical networking layer. To me PCIe faces the user.

Documentation/networking/devlink/devlink-port.rst line 39

Quoted 3 lines
Documentation/networking/devlink/devlink-port.rst new file +3 -0
+       a eswitch physical port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port.

You need to mention this is a DSA-only thing.

Documentation/networking/devlink/devlink-port.rst line 41

Quoted 2 lines
Documentation/networking/devlink/devlink-port.rst new file +2 -0
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a interconnect port in a distributed switch architecture.

(DSA)

Documentation/networking/devlink/devlink-port.rst line 47

Quoted 6 lines
Documentation/networking/devlink/devlink-port.rst new file +6 -0
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing PCI physical function(PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing PCI virtual function(VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port facing the user.

No idea what that means from the description.

Quoted 1 line

+A devlink port may be for a controller consisting one or more PCI device(s).

Port can have multiple PCI devices?

Quoted 63 lines
Documentation/networking/devlink/devlink-port.rst new file +51 -0
+A devlink instance holds ports of two types of controllers.
+
+(1) controller discovered on same system where eswitch resides
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system.
+
+An example view of two controller systems::
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the port of a PCI function.
+A user can configure the port function attributes before enumerating the
+function. For example user may set the hardware address of the function
+represented by the devlink port.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
#6 lore raw
Quoted 21 lines

From: Jakub Kicinski <[email protected]>
Sent: Wednesday, December 2, 2020 7:05 AM

Documentation/networking/devlink/devlink-port.rst line 9

Quoted 12 lines · On Mon, 30 Nov 2020 22:00:25 +0200 Parav Pandit wrote:

Added documentation for devlink port and port function related commands.

+============

Documentation/networking/devlink/devlink-port.rst new file +6 -0
+Devlink Port
+============
+
+``devlink-port`` provides capability for a driver to expose various
+flavours of ports which exist on device. A devlink port can be of an
+embedded switch (eswitch) present on the device.

The wording is a little awkward here.

Quoted 7 lines

The first paragraph should clarify what object represents.

This just says it exposes ports that exist.

A better phrasing would be to say that these are ports of an eswitch, in trivial case the only ports will be the physical ports of the card.

Sometimes it is eswitch port, sometimes its physical port on card, sometimes virtual port. Will rephase.

Quoted 4 lines
Quoted 1 line

+A devlink port can be of 3 diffferent types.

"can be of" repeated from the previous line

Will rephase.

Quoted 9 lines

Documentation/networking/devlink/devlink-port.rst

Quoted 8 lines

+.. list-table:: List of devlink port types

Documentation/networking/devlink/devlink-port.rst new file +7 -0
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - This type is set for a devlink port when a physical link layer
+ of the port
Quoted 3 lines

Is "physical link layer" a thing? I the common names are physical layer and a (data) link layer. I don't think I've seen physical link layer, or would know what it is...

I will drop 'physical'. And just say link layer.

Quoted 9 lines

Documentation/networking/devlink/devlink-port.rst line 26

Quoted 8 lines
Documentation/networking/devlink/devlink-port.rst new file +7 -0
+       is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - This type is set for a devlink port when a physical link layer of the port
+       is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
Quoted 3 lines

IMO type should be after flavor. Flavor is a higher level attribute, only physical ports have a type.

I will shift flavour up.
virtual port flavour also has type as eth/ib.

Quoted 13 lines

Documentation/networking/devlink/devlink-port.rst

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+Devlink port can be of few different flavours described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of port which is physically facing the user. This can
+ be

Hm. Not a great phrasing :(

Quoted 2 lines

It faces a physical networking layer. To me PCIe faces the user.

PCIe and physical networking ports, both are visible to users.
Former is usually inside the server, later is more frequently visible outside where networking cable is connected.

So, how about wording it as,

Any kind of physical networking port.

Quoted 6 lines

Documentation/networking/devlink/devlink-port.rst line 39

Quoted 3 lines
Documentation/networking/devlink/devlink-port.rst new file +3 -0
+       a eswitch physical port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port.

You need to mention this is a DSA-only thing.

Ok. will add.

Quoted 5 lines

Documentation/networking/devlink/devlink-port.rst line 41

Quoted 2 lines
Documentation/networking/devlink/devlink-port.rst new file +2 -0
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a interconnect port in a distributed switch architecture.

(DSA)

Quoted 9 lines

Documentation/networking/devlink/devlink-port.rst line 47

Quoted 6 lines
Documentation/networking/devlink/devlink-port.rst new file +6 -0
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing PCI physical function(PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing PCI virtual function(VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port facing the user.

No idea what that means from the description.

Let me rephase it as below.

This indicates a virtual port for the virtual PCI device such as PCI VF.

Quoted 3 lines
Quoted 1 line

+A devlink port may be for a controller consisting one or more PCI device(s).

Port can have multiple PCI devices?

For each PCI device there is a port as depicted in the diagram from commit 3a2d9588c4f7.

Quoted 66 lines
Quoted 66 lines
Documentation/networking/devlink/devlink-port.rst new file +52 -0
+A devlink instance holds ports of two types of controllers.
+
+(1) controller discovered on same system where eswitch resides This
+is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system.
+
+An example view of two controller systems::
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+
+ ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the port of a PCI function.
+A user can configure the port function attributes before enumerating
+the function. For example user may set the hardware address of the
+function represented by the devlink port.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
#7 lore raw

PATCH v3 1/1 devlink: Add devlink port documentation

In reply to Parav Pandit

Added documentation for devlink port and port function related commands.

---
Changelog:
v2->v3:
- rephased many lines
- first paragraph now describe devlink port
- instead of saying PCI device/function, using PCI function every where
- changed 'physical link layer' to 'link layer'
- made devlink port type description more clear
- made devlink port flavour description more clear
- moved devlink port type table after port flavour
- added description for the example diagram
- describe CPU port that its linked to DSA
- made devlink port description for eswitch port more clear
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 111 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 112 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +111 -0
new file mode 100644
index 000000000000..8407bbe9ce88
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` is a port that exist on the device. A devlink port can
+be of one among many flavours. A devlink port flavour along with port
+attributes describe what a port represents.
+
+A device driver who intents to publish a devlink port, sets the
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be a eswitch physical
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing a networking port of
+       PCI virtual function (VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port for the virtual PCI device such as PCI VF.
+
+A devlink port types are described below.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+A controller consist of one or more PCI functions. Such PCI function can have one
+or more networking ports. A networking port of such PCI function is represented
+by the eswitch devlink port. A devlink instance holds ports of two types of
+controllers.
+
+(1) controller discovered on same system where eswitch resides:
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system. Such controller
+is called external controller.
+
+An example view of two controller systems::
+
+In this example a controller which contains the eswitch is local controller
+with controller number = 0. The second is a external controller having
+controller number = 1. Eswitch devlink instance has representor devlink
+ports for the PCI functions of both the controllers.
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the networking port of a
+PCI function. A user can configure the port function attributes before
+enumerating the function. For example user may set the hardware address of
+the function represented by the devlink port function.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
Signature · 1 line
2.26.2
reviewer
#8 lore raw

Hi--

Quoted 9 lines · Parav Pandit

Added documentation for devlink port and port function related commands.

---
Changelog:
v2->v3:
- rephased many lines

rephrased

Quoted 26 lines

- first paragraph now describe devlink port
- instead of saying PCI device/function, using PCI function every where
- changed 'physical link layer' to 'link layer'
- made devlink port type description more clear
- made devlink port flavour description more clear
- moved devlink port type table after port flavour
- added description for the example diagram
- describe CPU port that its linked to DSA
- made devlink port description for eswitch port more clear
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 111 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 112 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +0 -0
new file mode 100644
index 000000000000..8407bbe9ce88

Documentation/networking/devlink/devlink-port.rst line 7

Quoted 7 lines
Documentation/networking/devlink/devlink-port.rst new file +7 -0
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` is a port that exist on the device. A devlink port can

exists

Documentation/networking/devlink/devlink-port.rst line 11

Quoted 4 lines
Documentation/networking/devlink/devlink-port.rst new file +4 -0
+be of one among many flavours. A devlink port flavour along with port
+attributes describe what a port represents.
+
+A device driver who intents to publish a devlink port, sets the

that intends ^no comma

Documentation/networking/devlink/devlink-port.rst line 22

Quoted 11 lines
Documentation/networking/devlink/devlink-port.rst new file +11 -0
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be a eswitch physical

an

Quoted 5 lines
Documentation/networking/devlink/devlink-port.rst new file +5 -0
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.

Documentation/networking/devlink/devlink-port.rst line 37

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing a networking port of
+       PCI virtual function (VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port for the virtual PCI device such as PCI VF.
+
+A devlink port types are described below.

The devlink port types

Quoted 5 lines
Documentation/networking/devlink/devlink-port.rst new file +5 -0
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type

Documentation/networking/devlink/devlink-port.rst line 52

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+A controller consist of one or more PCI functions. Such PCI function can have one

consists

Quoted 9 lines
Documentation/networking/devlink/devlink-port.rst new file +9 -0
+or more networking ports. A networking port of such PCI function is represented
+by the eswitch devlink port. A devlink instance holds ports of two types of
+controllers.
+
+(1) controller discovered on same system where eswitch resides:
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.

Documentation/networking/devlink/devlink-port.rst line 71

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system. Such controller
+is called external controller.
+
+An example view of two controller systems::
+
+In this example a controller which contains the eswitch is local controller
+with controller number = 0. The second is a external controller having
+controller number = 1. Eswitch devlink instance has representor devlink
+ports for the PCI functions of both the controllers.

I find that sentence confusing but I don't know how to fix it.

Quoted 30 lines
Documentation/networking/devlink/devlink-port.rst new file +30 -0
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |

Documentation/networking/devlink/devlink-port.rst line 111

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the networking port of a
+PCI function. A user can configure the port function attributes before
+enumerating the function. For example user may set the hardware address of
+the function represented by the devlink port function.

thanks.

Signature · 1 line
~Randy
#9 lore raw
Quoted 130 lines

From: Randy Dunlap <[email protected]>
Sent: Thursday, December 3, 2020 7:57 AM

Hi--

Quoted 9 lines · Parav Pandit

Added documentation for devlink port and port function related commands.

---
Changelog:
v2->v3:
- rephased many lines

rephrased

Quoted 27 lines

- first paragraph now describe devlink port
- instead of saying PCI device/function, using PCI function every where
- changed 'physical link layer' to 'link layer'
- made devlink port type description more clear
- made devlink port flavour description more clear
- moved devlink port type table after port flavour
- added description for the example diagram
- describe CPU port that its linked to DSA
- made devlink port description for eswitch port more clear
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 111 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 112 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +0 -0
new file mode 100644
index 000000000000..8407bbe9ce88

Documentation/networking/devlink/devlink-port.rst line 8

Quoted 8 lines
Documentation/networking/devlink/devlink-port.rst new file +8 -0
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` is a port that exist on the device. A devlink port
+can

exists

Documentation/networking/devlink/devlink-port.rst line 11

Quoted 4 lines
Documentation/networking/devlink/devlink-port.rst new file +4 -0
+be of one among many flavours. A devlink port flavour along with port
+attributes describe what a port represents.
+
+A device driver who intents to publish a devlink port, sets the

that intends ^no comma

Documentation/networking/devlink/devlink-port.rst

Quoted 12 lines
Documentation/networking/devlink/devlink-port.rst new file +12 -0
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be a eswitch
+ physical

an

Quoted 5 lines
Documentation/networking/devlink/devlink-port.rst new file +5 -0
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.

Documentation/networking/devlink/devlink-port.rst line 37

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing a networking port of
+       PCI virtual function (VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port for the virtual PCI device such as PCI VF.
+
+A devlink port types are described below.

The devlink port types

Quoted 6 lines
Documentation/networking/devlink/devlink-port.rst new file +6 -0
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description

Documentation/networking/devlink/devlink-port.rst

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+A controller consist of one or more PCI functions. Such PCI function
+can have one

consists

Quoted 13 lines
Documentation/networking/devlink/devlink-port.rst new file +13 -0
+or more networking ports. A networking port of such PCI function is
+represented by the eswitch devlink port. A devlink instance holds
+ports of two types of controllers.
+
+(1) controller discovered on same system where eswitch resides:
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is located in one system and its
+devlink eswitch ports are located in a different system. Such
+controller is called external controller.
+
Quoted 9 lines

Documentation/networking/devlink/devlink-port.rst line 74

Quoted 6 lines
Documentation/networking/devlink/devlink-port.rst new file +6 -0
+An example view of two controller systems::
+
+In this example a controller which contains the eswitch is local
+controller with controller number = 0. The second is a external
+controller having controller number = 1. Eswitch devlink instance has
+representor devlink ports for the PCI functions of both the controllers.

I find that sentence confusing but I don't know how to fix it.

Will rewrite it as below and also address above comments.

In this example, external controller (identified by controller number = 1) doesn't have eswitch. Local controller (identified by controller number = 0) has the eswitch. Devlink instance on local Controller has eswitch devlink ports representing networking ports for both the controllers.

Quoted 35 lines
Quoted 35 lines
Documentation/networking/devlink/devlink-port.rst new file +35 -0
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+
+ ---------------------------------------------------------
+
+Port function configuration
+===========================
Quoted 8 lines

Documentation/networking/devlink/devlink-port.rst

Quoted 6 lines
Documentation/networking/devlink/devlink-port.rst new file +6 -0
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the networking port of
+a PCI function. A user can configure the port function attributes
+before enumerating the function. For example user may set the
+hardware address of the function represented by the devlink port function.

thanks.

Thanks for the review Randy.

Quoted 2 lines

--
~Randy

#10 lore raw

PATCH v4 1/1 devlink: Add devlink port documentation

In reply to Parav Pandit

Added documentation for devlink port and port function related commands.

---
Changelog:
v3->v4:
- changed 'exist' to 'exists'
- added 'an' eswitch
- changed 'can have one' to 'consists of'
- changed 'who intents' to 'that intends'
- removed unnecessary comma
- rewrote description for the example diagram
- changed 'controller consist of' to 'controller consists of'
v2->v3:
- rephrased many lines
- first paragraph now describe devlink port
- instead of saying PCI device/function, using PCI function every where
- changed 'physical link layer' to 'link layer'
- made devlink port type description more clear
- made devlink port flavour description more clear
- moved devlink port type table after port flavour
- added description for the example diagram
- describe CPU port that its linked to DSA
- made devlink port description for eswitch port more clear
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 111 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 112 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +111 -0
new file mode 100644
index 000000000000..ac18cb8041dc
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device. A devlink port can
+be of one among many flavours. A devlink port flavour along with port
+attributes describe what a port represents.
+
+A device driver that intends to publish a devlink port sets the
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be an eswitch physical
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing a networking port of
+       PCI virtual function (VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port for the virtual PCI device such as PCI VF.
+
+Devlink port types are described below.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.
+
+A controller consists of one or more PCI functions. Such PCI function consists
+of one or more networking ports. A networking port of such PCI function is
+represented by the eswitch devlink port. A devlink instance holds ports of two
+types of controllers.
+
+(1) controller discovered on same system where eswitch resides:
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.
+
+(2) controller located on external host system.
+This is the case where a controller is in one system and its devlink
+eswitch ports are in a different system. Such controller is called
+external controller.
+
+An example view of two controller systems::
+
+In this example, external controller (identified by controller number = 1)
+doesn't have eswitch. Local controller (identified by controller number = 0)
+has the eswitch. Devlink instance on local Controller has eswitch devlink
+ports representing networking ports for both the controllers.
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the networking port of a
+PCI function. A user can configure the port function attributes before
+enumerating the function. For example user may set the hardware address of
+the function represented by the devlink port function.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
Signature · 1 line
2.26.2
reviewer
#11 lore raw

Hi--

Documentation/networking/devlink/devlink-port.rst

Quoted 43 lines · Parav Pandit

Added documentation for devlink port and port function related commands.

---
Changelog:
v3->v4:
- changed 'exist' to 'exists'
- added 'an' eswitch
- changed 'can have one' to 'consists of'
- changed 'who intents' to 'that intends'
- removed unnecessary comma
- rewrote description for the example diagram
- changed 'controller consist of' to 'controller consists of'
v2->v3:
- rephrased many lines
- first paragraph now describe devlink port
- instead of saying PCI device/function, using PCI function every where
- changed 'physical link layer' to 'link layer'
- made devlink port type description more clear
- made devlink port flavour description more clear
- moved devlink port type table after port flavour
- added description for the example diagram
- describe CPU port that its linked to DSA
- made devlink port description for eswitch port more clear
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 111 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 112 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +0 -0
new file mode 100644
index 000000000000..ac18cb8041dc
@@ -0,0 +1,111 @@

I find that this doc is now readable. :)

Other people can comment on the technical details.

thanks.

Signature · 2 lines
~Randy
Acked-by: Randy Dunlap <[email protected]>
maintainer
#12 lore raw
In reply to Parav Pandit

Documentation/networking/devlink/devlink-port.rst

Quoted 11 lines · On Thu, 3 Dec 2020 20:02:55 +0200 Parav Pandit wrote:

Added documentation for devlink port and port function related commands.

+============

Documentation/networking/devlink/devlink-port.rst new file +4 -0
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device. 

Can we add something like:

Each port is a logically separate ingress/egress point of the device.

?

Quoted 21 lines

A devlink port can

Documentation/networking/devlink/devlink-port.rst new file +20 -0
+be of one among many flavours. A devlink port flavour along with port
+attributes describe what a port represents.
+
+A device driver that intends to publish a devlink port sets the
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be an eswitch physical
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.

Documentation/networking/devlink/devlink-port.rst line 37

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing a networking port of
+       PCI virtual function (VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port for the virtual PCI device such as PCI VF.
+
+Devlink port types are described below.

How about:

Physical ports can have different types based on the link layer:

Documentation/networking/devlink/devlink-port.rst line 47

Quoted 9 lines

+.. list-table:: List of devlink port types

Documentation/networking/devlink/devlink-port.rst new file +8 -0
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is InfiniBand.

Please wrap at 80 chars.

Documentation/networking/devlink/devlink-port.rst line 50

Quoted 3 lines
Documentation/networking/devlink/devlink-port.rst new file +3 -0
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.

How about:

This type is indicated by the user when driver should detect the port type automatically.

Quoted 1 line

+A controller consists of one or more PCI functions.

This need some intro. Like:

PCI controllers
---------------

In most cases PCI devices will have only one controller, with potentially multiple physical and virtual functions. Devices connected to multiple CPUs and SmartNICs, however, may have multiple controllers.

Quoted 2 lines

Such PCI function consists
+of one or more networking ports.

PCI function consists of networking ports? What do you mean by a networking port? All devlink ports are networking ports.

Quoted 2 lines

A networking port of such PCI function is
+represented by the eswitch devlink port.

What's eswitch devlink port? It was never defined.

Quoted 2 lines

A devlink instance holds ports of two
+types of controllers.

For devices with multiple controllers we can distinguish...

Documentation/networking/devlink/devlink-port.rst line 59

Quoted 3 lines
Documentation/networking/devlink/devlink-port.rst new file +3 -0
+(1) controller discovered on same system where eswitch resides:
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.

How is eswitch located on a system? Eswitch is in the NIC

I think you should say refer to eswitch being controlled by a system.

Quoted 39 lines
Documentation/networking/devlink/devlink-port.rst new file +38 -0
+(2) controller located on external host system.
+This is the case where a controller is in one system and its devlink
+eswitch ports are in a different system. Such controller is called
+external controller.
 
+An example view of two controller systems::
+
+In this example, external controller (identified by controller number = 1)
+doesn't have eswitch. Local controller (identified by controller number = 0)
+has the eswitch. Devlink instance on local Controller has eswitch devlink
+ports representing networking ports for both the controllers.
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+                 |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+                 | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+                 | | pf0 |______/________/       | pf1 |___/_______/     |
+                 | -------                       -------                 |

Documentation/networking/devlink/devlink-port.rst

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the networking port of a
+PCI function. 

Networking port of a PCI function?

Quoted 1 line

A user can configure the port function attributes

port function attributes?

Quoted 2 lines

before
+enumerating the function.

What does this mean? What does enumerate mean in this context?

Quoted 2 lines

For example user may set the hardware address of +the function represented by the devlink port function.

What's a hardware address? You mean MAC address?

#13 lore raw
Quoted 20 lines

From: Jakub Kicinski <[email protected]>
Sent: Sunday, December 6, 2020 1:57 AM

Documentation/networking/devlink/devlink-port.rst

Quoted 11 lines · On Thu, 3 Dec 2020 20:02:55 +0200 Parav Pandit wrote:

Added documentation for devlink port and port function related commands.

+============

Documentation/networking/devlink/devlink-port.rst new file +4 -0
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device.

Can we add something like:

Quoted 3 lines

Each port is a logically separate ingress/egress point of the device.

?

This may not be true when both physical ports are under bond.

Quoted 12 lines

Documentation/networking/devlink/devlink-port.rst line 37

Quoted 9 lines

A devlink port can

Documentation/networking/devlink/devlink-port.rst new file +7 -0
+be of one among many flavours. A devlink port flavour along with port
+attributes describe what a port represents.
+
+A device driver that intends to publish a devlink port sets the
+devlink port attributes and registers the devlink port.
+
+Devlink port types are described below.

How about:

Quoted 2 lines

Physical ports can have different types based on the link layer:

Ok. will add.

Quoted 10 lines

Documentation/networking/devlink/devlink-port.rst line 47

Quoted 9 lines

+.. list-table:: List of devlink port types

Documentation/networking/devlink/devlink-port.rst new file +8 -0
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is InfiniBand.
Quoted 2 lines

Please wrap at 80 chars.

Ack.

Quoted 9 lines

Documentation/networking/devlink/devlink-port.rst line 50

Quoted 3 lines
Documentation/networking/devlink/devlink-port.rst new file +3 -0
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when user prefers to set the port type
+       to be automatically detected by the device driver.

How about:

This type is indicated by the user when driver should detect the port type automatically.

Will change.

Quoted 11 lines
Quoted 1 line

+A controller consists of one or more PCI functions.

This need some intro. Like:

PCI controllers
---------------

In most cases PCI devices will have only one controller, with potentially multiple physical and virtual functions. Devices connected to multiple CPUs and SmartNICs, however, may have multiple controllers.

Quoted 6 lines
Quoted 2 lines

Such PCI function consists
+of one or more networking ports.

PCI function consists of networking ports? What do you mean by a networking port? All devlink ports are networking ports.

I am not sure this document should be a starting point to define such restriction.

Quoted 4 lines
Quoted 2 lines

A networking port of such PCI function is
+represented by the eswitch devlink port.

What's eswitch devlink port? It was never defined.

Eswitch devlink port is the port which sets eswitch attributes (id and length).

Quoted 6 lines
Quoted 3 lines

A devlink instance holds ports of two
+types of controllers.

For devices with multiple controllers we can distinguish...

Yes, will change.

Quoted 6 lines

Documentation/networking/devlink/devlink-port.rst line 59

Quoted 3 lines
Documentation/networking/devlink/devlink-port.rst new file +3 -0
+(1) controller discovered on same system where eswitch resides:
+This is the case where PCI PF/VF of a controller and devlink eswitch
+instance both are located on a single system.

How is eswitch located on a system? Eswitch is in the NIC

Yes, I meant eswitch devlink instance and controller devlink instance are same.
Will rephase.

Quoted 18 lines

I think you should say refer to eswitch being controlled by a system.

Documentation/networking/devlink/devlink-port.rst

Quoted 13 lines
Documentation/networking/devlink/devlink-port.rst new file +12 -0
+(2) controller located on external host system.
+This is the case where a controller is in one system and its devlink
+eswitch ports are in a different system. Such controller is called
+external controller.
 
+An example view of two controller systems::
+
+Port function configuration
+===========================
+
+When a port flavor is ``DEVLINK_PORT_FLAVOUR_PCI_PF`` or
+``DEVLINK_PORT_FLAVOUR_PCI_VF``, it represents the networking port of
+a PCI function.

Networking port of a PCI function?

Quoted 9 lines
Quoted 1 line

A user can configure the port function attributes

port function attributes?

Quoted 2 lines

before
+enumerating the function.

What does this mean? What does enumerate mean in this context?

Enumerate means before creating the device of the function.
However today due to SR-IOV limitation, it is before probing the function device.

Quoted 4 lines
Quoted 2 lines

For example user may set the hardware address of +the function represented by the devlink port function.

What's a hardware address? You mean MAC address?

Yes, MAC address.
Port function attribute is named as hardware address to be generic enough similar to other iproute2 tools.

maintainer
#14 lore raw
Quoted 18 lines · On Mon, 7 Dec 2020 04:46:14 +0000 Parav Pandit wrote:
Quoted 18 lines

From: Jakub Kicinski <[email protected]>
Sent: Sunday, December 6, 2020 1:57 AM

Documentation/networking/devlink/devlink-port.rst

Quoted 11 lines · On Thu, 3 Dec 2020 20:02:55 +0200 Parav Pandit wrote:

Added documentation for devlink port and port function related commands.

+============

Documentation/networking/devlink/devlink-port.rst new file +4 -0
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device.  

Can we add something like:

Quoted 4 lines
Quoted 3 lines

Each port is a logically separate ingress/egress point of the device.

?

This may not be true when both physical ports are under bond.

Bonding changes forwarding logic, not what points of egress ASIC has.

Quoted 7 lines
Quoted 6 lines
Quoted 2 lines

Such PCI function consists
+of one or more networking ports.

PCI function consists of networking ports? What do you mean by a networking port? All devlink ports are networking ports.

I am not sure this document should be a starting point to define such restriction.

Well it's the reality today. Adding "networking" everywhere in this document is pointless.

Quoted 5 lines
Quoted 4 lines
Quoted 2 lines

A networking port of such PCI function is
+represented by the eswitch devlink port.

What's eswitch devlink port? It was never defined.

Eswitch devlink port is the port which sets eswitch attributes (id and length).

You mean phys_port_id?

Quoted 7 lines
Quoted 5 lines
Quoted 2 lines

before
+enumerating the function.

What does this mean? What does enumerate mean in this context?

Enumerate means before creating the device of the function.
However today due to SR-IOV limitation, it is before probing the function device.

Can you rephrase to make the point clearer?

Quoted 6 lines
Quoted 4 lines
Quoted 2 lines

For example user may set the hardware address of +the function represented by the devlink port function.

What's a hardware address? You mean MAC address?

Yes, MAC address.
Port function attribute is named as hardware address to be generic enough similar to other iproute2 tools.

Right, but in iproute2 the context makes it clear. Here we could be talking about many things.

#15 lore raw
Quoted 25 lines

From: Jakub Kicinski <[email protected]>
Sent: Monday, December 7, 2020 11:10 PM

Quoted 5 lines · On Mon, 7 Dec 2020 04:46:14 +0000 Parav Pandit wrote:
Quoted 5 lines

From: Jakub Kicinski <[email protected]>
Sent: Sunday, December 6, 2020 1:57 AM

Quoted 1 line · On Thu, 3 Dec 2020 20:02:55 +0200 Parav Pandit wrote:

Added documentation for devlink port and port function related

commands.

Quoted 13 lines
Quoted 13 lines

Documentation/networking/devlink/devlink-port.rst

Quoted 10 lines

+============

Documentation/networking/devlink/devlink-port.rst new file +4 -0
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device.

Can we add something like:

Quoted 6 lines
Quoted 4 lines
Quoted 3 lines

Each port is a logically separate ingress/egress point of the device.

?

This may not be true when both physical ports are under bond.

Bonding changes forwarding logic, not what points of egress ASIC has.

Ok. Do CPU and DSA port also follow same?

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 3 lines

Such PCI function consists
+of one or more networking ports.

Quoted 9 lines
Quoted 4 lines
Quoted 3 lines

PCI function consists of networking ports? What do you mean by a networking port? All devlink ports are networking ports.

I am not sure this document should be a starting point to define such

restriction.

Well it's the reality today. Adding "networking" everywhere in this document is pointless.

Ok. so I drop networking and just say PCI function port.

Quoted 8 lines
Quoted 5 lines
Quoted 4 lines
Quoted 2 lines

A networking port of such PCI function is
+represented by the eswitch devlink port.

What's eswitch devlink port? It was never defined.

Eswitch devlink port is the port which sets eswitch attributes (id and

length).

You mean phys_port_id?

No. I mean phys_switch_id.

Quoted 11 lines
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines

before
+enumerating the function.

What does this mean? What does enumerate mean in this context?

Enumerate means before creating the device of the function. However today due to SR-IOV limitation, it is before probing the function

device.

Can you rephrase to make the point clearer?

Sure. Will do.

Quoted 11 lines
Quoted 7 lines
Quoted 5 lines
Quoted 3 lines

For example user may set the hardware address of +the function represented by the devlink port function.

What's a hardware address? You mean MAC address?

Yes, MAC address.
Port function attribute is named as hardware address to be generic enough

similar to other iproute2 tools.

Right, but in iproute2 the context makes it clear. Here we could be talking about many things.

Kernel interface is not restricted to mac address, nor the iproute2.
So I will mention as hardware address to be precise what is does and additionally mention that it is mac address for Ethernet ports.

Will send v5 addressing these comments.

maintainer
#16 lore raw
Quoted 7 lines · On Mon, 7 Dec 2020 20:00:53 +0000 Parav Pandit wrote:
Quoted 6 lines
Quoted 4 lines
Quoted 3 lines

Each port is a logically separate ingress/egress point of the device.

?

This may not be true when both physical ports are under bond.

Bonding changes forwarding logic, not what points of egress ASIC has.

Ok. Do CPU and DSA port also follow same?

Yes, DSA/CPU port types are points of egress to the devlink instance.

#17 lore raw
Quoted 8 lines

From: Jakub Kicinski <[email protected]>
Sent: Tuesday, December 8, 2020 1:43 AM

Quoted 2 lines · On Mon, 7 Dec 2020 20:00:53 +0000 Parav Pandit wrote:
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

Each port is a logically separate ingress/egress point of the device.

Quoted 7 lines
Quoted 5 lines
Quoted 4 lines
Quoted 2 lines
Quoted 1 line

?

This may not be true when both physical ports are under bond.

Bonding changes forwarding logic, not what points of egress ASIC has.

Ok. Do CPU and DSA port also follow same?

Yes, DSA/CPU port types are points of egress to the devlink instance.

Ok. got it. Thanks.

#18 lore raw

PATCH v5 1/1 devlink: Add devlink port documentation

In reply to Parav Pandit

Added documentation for devlink port and port function related commands.

---
Changelog:
v4->v5:
- described logically ingress and egress point of devlink port
- removed networking from devlink port description
- rephrased port type description
- introdue PCI controller section and description
- rephrased controller, device, function description
- removed confusing eswitch to system wording
- rephrased port function description
- added example of mac address in port function attribute description
v3->v4:
- changed 'exist' to 'exists'
- added 'an' eswitch
- changed 'can have one' to 'consists of'
- changed 'who intents' to 'that intends'
- removed unnecessary comma
- rewrote description for the example diagram
- changed 'controller consist of' to 'controller consists of'
v2->v3:
- rephrased many lines
- first paragraph now describe devlink port
- instead of saying PCI device/function, using PCI function every where
- changed 'physical link layer' to 'link layer'
- made devlink port type description more clear
- made devlink port flavour description more clear
- moved devlink port type table after port flavour
- added description for the example diagram
- describe CPU port that its linked to DSA
- made devlink port description for eswitch port more clear
v1->v2:
- Removed duplicate table entries for DEVLINK_PORT_FLAVOUR_VIRTUAL.
- replaced 'consist of' to 'consisting'
- changed 'can be' to 'can be of'

---
 .../networking/devlink/devlink-port.rst       | 116 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 117 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +116 -0
new file mode 100644
index 000000000000..dce87d2c07ac
@@ -0,0 +1,116 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device. It has a logically
+separate ingress/egress point of the device. A devlink port can be of one
+among many flavours. A devlink port flavour along with port attributes
+describe what a port represents.
+
+A device driver that intends to publish a devlink port sets the
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be an eswitch physical
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing a networking port of
+       PCI virtual function (VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port for the virtual PCI device such as PCI VF.
+
+Devlink port can have a different type based on the link layer described below.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is
+       Ethernet.
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is
+       InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when driver should detect the port
+       type automatically.
+
+PCI controllers
+---------------
+In most cases PCI device has only one controller. A controller consists of
+potentially multiple physical and virtual functions. Such PCI function consists
+of one or more ports. This port of the function is represented by the devlink
+eswitch port.
+
+A PCI Device connected to multiple CPUs or multiple PCI root complex or
+SmartNIC, however, may have multiple controllers. For a device with multiple
+controllers, each controller is distinguished by a unique controller number.
+An eswitch on the PCI device may suppport ports of multiple controllers. 
+
+An example view of two controller systems::
+
+In this example, external controller (identified by controller number = 1)
+doesn't have eswitch. Local controller (identified by controller number = 0)
+has the eswitch. Devlink instance on local controller has eswitch devlink
+ports representing ports for both the controllers.
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+    -----------  |           --------- ---------         ------- ------- |
+    | smartNIC|  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | pci rc  |==| -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | connect |  | | pf0 |______/________/       | pf1 |___/_______/     |
+    -----------  | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+A user can configure the port function attribute before enumerating the
+PCI function. Usually it means, user should configure port function attribute
+before a bus specific device for the function is created. However, when
+SRIOV is enabled, virtual function devices are created on the PCI bus.
+Hence, function attribute should be configured before binding virtual
+function device to the driver.
+
+User may set the hardware address of the function represented by the devlink
+port function. For Ethernet port function this means a MAC address.
Documentation/networking/devlink/index.rst +1 -0
index d82874760ae2..aab79667f97b 100644
@@ -18,6 +18,7 @@ general.
    devlink-info
    devlink-flash
    devlink-params
+   devlink-port
    devlink-region
    devlink-resource
    devlink-reload
Signature · 1 line
2.26.2
reviewer
#19 lore raw

Hi--

Quoted 5 lines · Parav Pandit

Added documentation for devlink port and port function related commands.

Quoted 7 lines

---
Changelog:
v4->v5:
- described logically ingress and egress point of devlink port
- removed networking from devlink port description
- rephrased port type description
- introdue PCI controller section and description

introduce

Quoted 17 lines

- rephrased controller, device, function description
- removed confusing eswitch to system wording
- rephrased port function description
- added example of mac address in port function attribute description

---
 .../networking/devlink/devlink-port.rst       | 116 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 117 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +0 -0
new file mode 100644
index 000000000000..dce87d2c07ac

Documentation/networking/devlink/devlink-port.rst line 8

Quoted 8 lines
Documentation/networking/devlink/devlink-port.rst new file +8 -0
@@ -0,0 +1,116 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device. It has a logically
+separate ingress/egress point of the device. A devlink port can be of one

port can be any one
of many flavours.

Quoted 39 lines
Documentation/networking/devlink/devlink-port.rst new file +39 -0
+among many flavours. A devlink port flavour along with port attributes
+describe what a port represents.
+
+A device driver that intends to publish a devlink port sets the
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be an eswitch physical
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
+     - This indicates an eswitch port representing a networking port of
+       PCI virtual function (VF).
+   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
+     - This indicates a virtual port for the virtual PCI device such as PCI VF.
+
+Devlink port can have a different type based on the link layer described below.
+
+.. list-table:: List of devlink port types
+   :widths: 23 90
+
+   * - Type
+     - Description
+   * - ``DEVLINK_PORT_TYPE_ETH``
+     - Driver should set this port type when a link layer of the port is
+       Ethernet.

Documentation/networking/devlink/devlink-port.rst line 57

Quoted 10 lines
Documentation/networking/devlink/devlink-port.rst new file +10 -0
+   * - ``DEVLINK_PORT_TYPE_IB``
+     - Driver should set this port type when a link layer of the port is
+       InfiniBand.
+   * - ``DEVLINK_PORT_TYPE_AUTO``
+     - This type is indicated by the user when driver should detect the port
+       type automatically.
+
+PCI controllers
+---------------
+In most cases PCI device has only one controller. A controller consists of

either PCI devices have
or a PCI device has

Documentation/networking/devlink/devlink-port.rst line 62

Quoted 5 lines
Documentation/networking/devlink/devlink-port.rst new file +5 -0
+potentially multiple physical and virtual functions. Such PCI function consists
+of one or more ports. This port of the function is represented by the devlink
+eswitch port.
+
+A PCI Device connected to multiple CPUs or multiple PCI root complex or

complexes

Documentation/networking/devlink/devlink-port.rst line 65

Quoted 3 lines
Documentation/networking/devlink/devlink-port.rst new file +3 -0
+SmartNIC, however, may have multiple controllers. For a device with multiple
+controllers, each controller is distinguished by a unique controller number.
+An eswitch on the PCI device may suppport ports of multiple controllers. 

support

Documentation/networking/devlink/devlink-port.rst line 67

Quoted 2 lines
Documentation/networking/devlink/devlink-port.rst new file +2 -0
+
+An example view of two controller systems::

I think that this is

An example view of a two-controller system::

instead of 2 controller systems. ?

Quoted 49 lines
Documentation/networking/devlink/devlink-port.rst new file +49 -0
+
+In this example, external controller (identified by controller number = 1)
+doesn't have eswitch. Local controller (identified by controller number = 0)
+has the eswitch. Devlink instance on local controller has eswitch devlink
+ports representing ports for both the controllers.
+
+                 ---------------------------------------------------------
+                 |                                                       |
+                 |           --------- ---------         ------- ------- |
+    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
+    | connect |  | -------                       -------                 |
+    -----------  |     | controller_num=1 (no eswitch)                   |
+                 ------|--------------------------------------------------
+                 (internal wire)
+                       |
+                 ---------------------------------------------------------
+                 | devlink eswitch ports and reps                        |
+                 | ----------------------------------------------------- |
+                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
+                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
+                 | ----------------------------------------------------- |
+                 |                                                       |
+                 |                                                       |
+    -----------  |           --------- ---------         ------- ------- |
+    | smartNIC|  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
+    | pci rc  |==| -------   ----/---- ---/----- ------- ---/--- ---/--- |
+    | connect |  | | pf0 |______/________/       | pf1 |___/_______/     |
+    -----------  | -------                       -------                 |
+                 |                                                       |
+                 |  local controller_num=0 (eswitch)                     |
+                 ---------------------------------------------------------
+
+Port function configuration
+===========================
+
+A user can configure the port function attribute before enumerating the
+PCI function. Usually it means, user should configure port function attribute
+before a bus specific device for the function is created. However, when
+SRIOV is enabled, virtual function devices are created on the PCI bus.
+Hence, function attribute should be configured before binding virtual
+function device to the driver.
+
+User may set the hardware address of the function represented by the devlink
+port function. For Ethernet port function this means a MAC address.
Signature · 1 line
~Randy
#20 lore raw

Hi Randy,

Quoted 7 lines

From: Randy Dunlap <[email protected]>
Sent: Tuesday, December 8, 2020 6:45 AM

Quoted 1 line

+An eswitch on the PCI device may suppport ports of multiple controllers.

support

Quoted 8 lines

Review

Quoted 2 lines
(quoted diff) +2 -0
+
+An example view of two controller systems::

I think that this is

An example view of a two-controller system::

instead of 2 controller systems. ?

Rephrasing it as "An example view of a system with two controllers" along with other comments.
Since Saeed is sending the sf patchset which also needs port documentation, I am sending v6 of this patch along with the change log in the subfunction patchset.

#21 lore raw
In reply to Randy Dunlap
Quoted 70 lines

From: Randy Dunlap <[email protected]>
Sent: Tuesday, December 8, 2020 6:45 AM

Hi--

Quoted 1 line · Parav Pandit

Added documentation for devlink port and port function related

commands.

Quoted 11 lines

---
Changelog:
v4->v5:
- described logically ingress and egress point of devlink port
- removed networking from devlink port description
- rephrased port type description
- introdue PCI controller section and description

introduce

Quoted 18 lines

- rephrased controller, device, function description
- removed confusing eswitch to system wording
- rephrased port function description
- added example of mac address in port function attribute description

---
 .../networking/devlink/devlink-port.rst       | 116 ++++++++++++++++++
 Documentation/networking/devlink/index.rst    |   1 +
 2 files changed, 117 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-port.rst
Documentation/networking/devlink/devlink-port.rst new file +0 -0
new file mode 100644
index 000000000000..dce87d2c07ac

Documentation/networking/devlink/devlink-port.rst line 9

Quoted 9 lines
Documentation/networking/devlink/devlink-port.rst new file +9 -0
@@ -0,0 +1,116 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Devlink Port
+============
+
+``devlink-port`` is a port that exists on the device. It has a
+logically separate ingress/egress point of the device. A devlink port
+can be of one

port can be any one
of many flavours.

Quoted 15 lines
Documentation/networking/devlink/devlink-port.rst new file +15 -0
+among many flavours. A devlink port flavour along with port
+attributes describe what a port represents.
+
+A device driver that intends to publish a devlink port sets the
+devlink port attributes and registers the devlink port.
+
+Devlink port flavours are described below.
+
+.. list-table:: List of devlink port flavours
+   :widths: 33 90
+
+   * - Flavour
+     - Description
+   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
+     - Any kind of physical networking port. This can be an eswitch physical
Quoted 8 lines

Documentation/networking/devlink/devlink-port.rst line 31

Quoted 8 lines
Documentation/networking/devlink/devlink-port.rst new file +8 -0
+       port or any other physical port on the device.
+   * - ``DEVLINK_PORT_FLAVOUR_DSA``
+     - This indicates a DSA interconnect port.
+   * - ``DEVLINK_PORT_FLAVOUR_CPU``
+     - This indicates a CPU port applicable only to DSA.
+   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
+     - This indicates an eswitch port representing a networking port of
+       PCI physical function (PF).

I forgot to remove 'networking' from the networking port here.
Will include this fix this in v6 in Saeed's subfunction patchset along with addressing Randy's comments.