devlink: Add devlink port documentation
Subsystems (4)
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
@@ -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
@@ -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
Quoted 4 lines · Parav Pandit
Added documentation for devlink port and port function related commands.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>
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.rstDocumentation/networking/devlink/devlink-port.rst new file +0
-0
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@@ -18,6 +18,7 @@ general. devlink-info devlink-flash devlink-params + devlink-port devlink-region devlink-resource devlink-reload
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.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>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.rstDocumentation/networking/devlink/devlink-port.rst new file +5
-0@@ -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_VIRTUALis 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.
PATCH v2 1/1 devlink: Add devlink port documentation
In reply to Parav PanditAdded 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
@@ -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
@@ -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
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.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>
Quoted 134 lines
---
Changelog:v1->v2:
- Removed duplicate table entries forDEVLINK_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.rstDocumentation/networking/devlink/devlink-port.rst new file +100
-0@@ -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@@ -18,6 +18,7 @@ general. devlink-info devlink-flash devlink-params + devlink-port devlink-region devlink-resource devlink-reload --2.26.2
Jakub Kicinski
maintainerDocumentation/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.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>+============
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@@ -18,6 +18,7 @@ general. devlink-info devlink-flash devlink-params + devlink-port devlink-region devlink-resource devlink-reload
Quoted 21 lines
From: Jakub Kicinski <[email protected]>
Sent: Wednesday, December 2, 2020 7:05 AMDocumentation/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.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>+============
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 + beHm. 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@@ -18,6 +18,7 @@ general. devlink-info devlink-flash devlink-params + devlink-port devlink-region devlink-resource devlink-reload
PATCH v3 1/1 devlink: Add devlink port documentation
In reply to Parav PanditAdded 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 clearv1->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
@@ -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
@@ -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
Randy Dunlap
reviewerHi--
Quoted 9 lines · Parav Pandit
Added documentation for devlink port and port function related commands.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>---
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 clearv1->v2:
- Removed duplicate table entries forDEVLINK_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.rstDocumentation/networking/devlink/devlink-port.rst new file +0
-0
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
Quoted 130 lines
From: Randy Dunlap <[email protected]>
Sent: Thursday, December 3, 2020 7:57 AMHi--
Quoted 9 lines · Parav Pandit
Added documentation for devlink port and port function related commands.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>---
Changelog:v2->v3:
- rephased many linesrephrased
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 clearv1->v2:
- Removed duplicate table entries forDEVLINK_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.rstDocumentation/networking/devlink/devlink-port.rst new file +0
-0Documentation/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 +canexists
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 thethat 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 + physicalan
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 + - DescriptionDocumentation/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 oneconsists
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
PATCH v4 1/1 devlink: Add devlink port documentation
In reply to Parav PanditAdded 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 clearv1->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
@@ -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
@@ -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
Randy Dunlap
reviewerHi--
Documentation/networking/devlink/devlink-port.rst
Quoted 43 lines · Parav Pandit
Added documentation for devlink port and port function related commands.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>---
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 clearv1->v2:
- Removed duplicate table entries forDEVLINK_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.rstDocumentation/networking/devlink/devlink-port.rst new file +0
-0@@ -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]>
Jakub Kicinski
maintainerDocumentation/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.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>+============
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?
Quoted 20 lines
From: Jakub Kicinski <[email protected]>
Sent: Sunday, December 6, 2020 1:57 AMDocumentation/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.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>+============
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.
Jakub Kicinski
maintainerQuoted 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 AMDocumentation/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.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>+============
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.
Quoted 25 lines
From: Jakub Kicinski <[email protected]>
Sent: Monday, December 7, 2020 11:10 PMQuoted 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 AMQuoted 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
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>+============
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 enoughsimilar 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.
Jakub Kicinski
maintainerQuoted 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.
Quoted 8 lines
From: Jakub Kicinski <[email protected]>
Sent: Tuesday, December 8, 2020 1:43 AMQuoted 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.
PATCH v5 1/1 devlink: Add devlink port documentation
In reply to Parav PanditAdded 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 descriptionv3->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 clearv1->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
@@ -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
@@ -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
Randy Dunlap
reviewerHi--
Quoted 5 lines · Parav Pandit
Added documentation for devlink port and port function related commands.
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>
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.rstDocumentation/networking/devlink/devlink-port.rst new file +0
-0
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
Hi Randy,
Quoted 7 lines
From: Randy Dunlap <[email protected]>
Sent: Tuesday, December 8, 2020 6:45 AMQuoted 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.
Quoted 70 lines
From: Randy Dunlap <[email protected]>
Sent: Tuesday, December 8, 2020 6:45 AMHi--
Quoted 1 line · Parav Pandit
Added documentation for devlink port and port function related
commands.
Quoted 11 lines
Signed-off-by Parav Pandit <[email protected]>Reviewed-by Jiri Pirko <[email protected]>Reviewed-by Jacob Keller <[email protected]>---
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 descriptionintroduce
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.rstDocumentation/networking/devlink/devlink-port.rst new file +0
-0Documentation/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 oneport 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.