From: Maxime Chevallier <maxime.chevallier@bootlin.com> To: davem@davemloft.net Cc: "Maxime Chevallier" <maxime.chevallier@bootlin.com>, netdev@vger.kernel.org, linux-kernel@vger.kernel.org, thomas.petazzoni@bootlin.com, "Andrew Lunn" <andrew@lunn.ch>, "Jakub Kicinski" <kuba@kernel.org>, "Eric Dumazet" <edumazet@google.com>, "Paolo Abeni" <pabeni@redhat.com>, "Russell King" <linux@armlinux.org.uk>, linux-arm-kernel@lists.infradead.org, "Christophe Leroy" <christophe.leroy@csgroup.eu>, "Herve Codina" <herve.codina@bootlin.com>, "Florian Fainelli" <f.fainelli@gmail.com>, "Heiner Kallweit" <hkallweit1@gmail.com>, "Vladimir Oltean" <vladimir.oltean@nxp.com>, "Köry Maincent" <kory.maincent@bootlin.com>, "Jesse Brandeburg" <jesse.brandeburg@intel.com>, "Jonathan Corbet" <corbet@lwn.net>, "Marek Behún" <kabel@kernel.org>, "Piergiorgio Beruto" <piergiorgio.beruto@gmail.com>, "Oleksij Rempel" <o.rempel@pengutronix.de>, "Nicolò Veronese" <nicveronese@gmail.com> Subject: [PATCH net-next v4 13/13] Documentation: networking: document phy_link_topology Date: Fri, 15 Dec 2023 18:12:35 +0100 [thread overview] Message-ID: <20231215171237.1152563-14-maxime.chevallier@bootlin.com> (raw) In-Reply-To: <20231215171237.1152563-1-maxime.chevallier@bootlin.com> The newly introduced phy_link_topology tracks all ethernet PHYs that are attached to a netdevice. Document the base principle, internal and external APIs. As the phy_link_topology is expected to be extended, this documentation will hold any further improvements and additions made relative to topology handling. Signed-off-by: Maxime Chevallier <maxime.chevallier@bootlin.com> --- V4: No changes V3: New patch Documentation/networking/index.rst | 1 + .../networking/phy-link-topology.rst | 121 ++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 Documentation/networking/phy-link-topology.rst diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 69f3d6dcd9fd..a2c45a75a4a6 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -88,6 +88,7 @@ Contents: operstates packet_mmap phonet + phy-link-topology pktgen plip ppp_generic diff --git a/Documentation/networking/phy-link-topology.rst b/Documentation/networking/phy-link-topology.rst new file mode 100644 index 000000000000..d66ee9711ac1 --- /dev/null +++ b/Documentation/networking/phy-link-topology.rst @@ -0,0 +1,121 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +PHY link topology +================= + +Overview +======== + +The PHY link topology representation in the networking stack aims at representing +the hardware layout for any given Ethernet link. + +An Ethernet Interface from userspace's poing of view is nothing but a +:c:type:`struct net_device <net_device>`, which exposes configuration options +trough the legacy ioctls and the ethool netlink commands. The base assumption +when designing these configuration channels were that the link looked +something like this :: + + +-----------------------+ +----------+ +--------------+ + | Ethernet Controller / | | Ethernet | | Connector / | + | MAC | ------ | PHY | ---- | Port | ---... to LP + +-----------------------+ +----------+ +--------------+ + struct net_device struct phy_device + +Commands that needs to configure the PHY will go through the net_device.phydev +field to reach the PHY and perform the relevant configuration. + +This assumption falls appart in more complex topologies that can arise when, +for example, using SFP transceivers (although that's not the only specific case). + +Here, we have 2 basic scenarios. Either the MAC is able to output a serialized +interface, that can directly be fed to an SFP cage, such as SGMII, 1000BaseX, +10GBaseR, etc. + +The link topology then looks like this (when an SFP module is inserted) :: + + +-----+ SGMII +------------+ + | MAC | ------- | SFP Module | + +-----+ +------------+ + +Knowing that some modules embed a PHY, the actual link is more like :: + + +-----+ SGMII +--------------+ + | MAC | -------- | PHY (on SFP) | + +-----+ +--------------+ + +In this case, the SFP PHY is handled by phylib, and registered by phylink through +its SFP upstream ops. + +Now some Ethernet controllers aren't able to output a serialized interface, so +we can't directly connect them to an SFP cage. However, some PHYs can be used +as media-converters, to translate the non-serialized MAC MII interface to a +serialized MII interface fed to the SFP :: + + +-----+ RGMII +-----------------------+ SGMII +--------------+ + | MAC | ------- | PHY (media converter) | ------- | PHY (on SFP) | + +-----+ +-----------------------+ +--------------+ + +This is where the model of having a single net_device.phydev pointer shows its +limitations, as we now have 2 PHYs on the link. + +The phy_link topology framework aims at providing a way to keep track of every +PHY on the link, for use by both kernel drivers and subsystems, but also to +report the topology to userspace, allowing to target individual PHYs in configuration +commands. + +API +=== + +The :c:type:`struct phy_link_topology <phy_link_topology>` is a per-netdevice +resource, that gets initialized at netdevice creation. Once it's initialized, +it is then possible to register PHYs to the topology through : + +:c:func:`phy_link_topo_add_phy` + +Besides registering the PHY to the topology, this call will also assign a unique +index to the PHY, which can then be reported to userspace to refer to this PHY +(akin to the ifindex). This index is a u32, ranging from 1 to U32_MAX. The value +0 is reserved to indicate the PHY doesn't belong to any topology yet. + +The PHY can then be removed from the topology through + +:c:func:`phy_link_topo_del_phy` + +These function are already hooked into the phylib subsystem, so all PHYs that +are linked to a net_device through :c:func:`phy_attach_direct` will automatically +join the netdev's topology. + +PHYs that are on a SFP module will also be automatically registered IF the SFP +upstream is phylink (so, no media-converter). + +PHY drivers that can be used as SFP upstream need to call :c:func:`phy_sfp_attach_phy` +and :c:func:`phy_sfp_detach_phy`, which can be used as a +.attach_phy / .detach_phy implementation for the +:c:type:`struct sfp_upstream_ops <sfp_upstream_ops>`. + +UAPI +==== + +There exist a set of netlink commands to query the link topology from userspace, +see ``Documentation/networking/ethtool-netlink.rst``. + +The whole point of having a topology representation is to assign the phyindex +field in :c:type:`struct phy_device <phy_device>`. This index is reported to +userspace using the ``ETHTOOL_MSG_PHY_GET`` ethtnl command. Performing a DUMP operation +will result in all PHYs from all net_device being listed. The DUMP command +accepts either a ``ETHTOOL_A_HEADER_DEV_INDEX`` or ``ETHTOOL_A_HEADER_DEV_NAME`` +to be passed in the request to filter the DUMP to a single net_device. + +The retrieved index can then be passed as a request parameter using the +``ETHTOOL_A_HEADER_PHY_INDEX`` field in the following ethnl commands : + +* ``ETHTOOL_MSG_STRSET_GET`` to get the stats strig set from a given PHY +* ``ETHTOOL_MSG_CABLE_TEST_ACT`` and ``ETHTOOL_MSG_CABLE_TEST_ACT``, to perform + cable testing on a given PHY on the link (most likely the outermost PHY) +* ``ETHTOOL_MSG_PSE_SET`` and ``ETHTOOL_MSG_PSE_GET`` for PHY-controlled PoE and PSE settings +* ``ETHTOOL_MSG_PLCA_GET_CFG``, ``ETHTOOL_MSG_PLCA_SET_CFG`` and ``ETHTOOL_MSG_PLCA_GET_STATUS`` + to set the PLCA (Physical Layer Collision Avoidance) parameters + +Note that the PHY index can be passed to other requests, which will silently +ignore it if present and irrelevant. -- 2.43.0
WARNING: multiple messages have this Message-ID (diff)
From: Maxime Chevallier <maxime.chevallier@bootlin.com> To: davem@davemloft.net Cc: "Maxime Chevallier" <maxime.chevallier@bootlin.com>, netdev@vger.kernel.org, linux-kernel@vger.kernel.org, thomas.petazzoni@bootlin.com, "Andrew Lunn" <andrew@lunn.ch>, "Jakub Kicinski" <kuba@kernel.org>, "Eric Dumazet" <edumazet@google.com>, "Paolo Abeni" <pabeni@redhat.com>, "Russell King" <linux@armlinux.org.uk>, linux-arm-kernel@lists.infradead.org, "Christophe Leroy" <christophe.leroy@csgroup.eu>, "Herve Codina" <herve.codina@bootlin.com>, "Florian Fainelli" <f.fainelli@gmail.com>, "Heiner Kallweit" <hkallweit1@gmail.com>, "Vladimir Oltean" <vladimir.oltean@nxp.com>, "Köry Maincent" <kory.maincent@bootlin.com>, "Jesse Brandeburg" <jesse.brandeburg@intel.com>, "Jonathan Corbet" <corbet@lwn.net>, "Marek Behún" <kabel@kernel.org>, "Piergiorgio Beruto" <piergiorgio.beruto@gmail.com>, "Oleksij Rempel" <o.rempel@pengutronix.de>, "Nicolò Veronese" <nicveronese@gmail.com> Subject: [PATCH net-next v4 13/13] Documentation: networking: document phy_link_topology Date: Fri, 15 Dec 2023 18:12:35 +0100 [thread overview] Message-ID: <20231215171237.1152563-14-maxime.chevallier@bootlin.com> (raw) In-Reply-To: <20231215171237.1152563-1-maxime.chevallier@bootlin.com> The newly introduced phy_link_topology tracks all ethernet PHYs that are attached to a netdevice. Document the base principle, internal and external APIs. As the phy_link_topology is expected to be extended, this documentation will hold any further improvements and additions made relative to topology handling. Signed-off-by: Maxime Chevallier <maxime.chevallier@bootlin.com> --- V4: No changes V3: New patch Documentation/networking/index.rst | 1 + .../networking/phy-link-topology.rst | 121 ++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 Documentation/networking/phy-link-topology.rst diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 69f3d6dcd9fd..a2c45a75a4a6 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -88,6 +88,7 @@ Contents: operstates packet_mmap phonet + phy-link-topology pktgen plip ppp_generic diff --git a/Documentation/networking/phy-link-topology.rst b/Documentation/networking/phy-link-topology.rst new file mode 100644 index 000000000000..d66ee9711ac1 --- /dev/null +++ b/Documentation/networking/phy-link-topology.rst @@ -0,0 +1,121 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +PHY link topology +================= + +Overview +======== + +The PHY link topology representation in the networking stack aims at representing +the hardware layout for any given Ethernet link. + +An Ethernet Interface from userspace's poing of view is nothing but a +:c:type:`struct net_device <net_device>`, which exposes configuration options +trough the legacy ioctls and the ethool netlink commands. The base assumption +when designing these configuration channels were that the link looked +something like this :: + + +-----------------------+ +----------+ +--------------+ + | Ethernet Controller / | | Ethernet | | Connector / | + | MAC | ------ | PHY | ---- | Port | ---... to LP + +-----------------------+ +----------+ +--------------+ + struct net_device struct phy_device + +Commands that needs to configure the PHY will go through the net_device.phydev +field to reach the PHY and perform the relevant configuration. + +This assumption falls appart in more complex topologies that can arise when, +for example, using SFP transceivers (although that's not the only specific case). + +Here, we have 2 basic scenarios. Either the MAC is able to output a serialized +interface, that can directly be fed to an SFP cage, such as SGMII, 1000BaseX, +10GBaseR, etc. + +The link topology then looks like this (when an SFP module is inserted) :: + + +-----+ SGMII +------------+ + | MAC | ------- | SFP Module | + +-----+ +------------+ + +Knowing that some modules embed a PHY, the actual link is more like :: + + +-----+ SGMII +--------------+ + | MAC | -------- | PHY (on SFP) | + +-----+ +--------------+ + +In this case, the SFP PHY is handled by phylib, and registered by phylink through +its SFP upstream ops. + +Now some Ethernet controllers aren't able to output a serialized interface, so +we can't directly connect them to an SFP cage. However, some PHYs can be used +as media-converters, to translate the non-serialized MAC MII interface to a +serialized MII interface fed to the SFP :: + + +-----+ RGMII +-----------------------+ SGMII +--------------+ + | MAC | ------- | PHY (media converter) | ------- | PHY (on SFP) | + +-----+ +-----------------------+ +--------------+ + +This is where the model of having a single net_device.phydev pointer shows its +limitations, as we now have 2 PHYs on the link. + +The phy_link topology framework aims at providing a way to keep track of every +PHY on the link, for use by both kernel drivers and subsystems, but also to +report the topology to userspace, allowing to target individual PHYs in configuration +commands. + +API +=== + +The :c:type:`struct phy_link_topology <phy_link_topology>` is a per-netdevice +resource, that gets initialized at netdevice creation. Once it's initialized, +it is then possible to register PHYs to the topology through : + +:c:func:`phy_link_topo_add_phy` + +Besides registering the PHY to the topology, this call will also assign a unique +index to the PHY, which can then be reported to userspace to refer to this PHY +(akin to the ifindex). This index is a u32, ranging from 1 to U32_MAX. The value +0 is reserved to indicate the PHY doesn't belong to any topology yet. + +The PHY can then be removed from the topology through + +:c:func:`phy_link_topo_del_phy` + +These function are already hooked into the phylib subsystem, so all PHYs that +are linked to a net_device through :c:func:`phy_attach_direct` will automatically +join the netdev's topology. + +PHYs that are on a SFP module will also be automatically registered IF the SFP +upstream is phylink (so, no media-converter). + +PHY drivers that can be used as SFP upstream need to call :c:func:`phy_sfp_attach_phy` +and :c:func:`phy_sfp_detach_phy`, which can be used as a +.attach_phy / .detach_phy implementation for the +:c:type:`struct sfp_upstream_ops <sfp_upstream_ops>`. + +UAPI +==== + +There exist a set of netlink commands to query the link topology from userspace, +see ``Documentation/networking/ethtool-netlink.rst``. + +The whole point of having a topology representation is to assign the phyindex +field in :c:type:`struct phy_device <phy_device>`. This index is reported to +userspace using the ``ETHTOOL_MSG_PHY_GET`` ethtnl command. Performing a DUMP operation +will result in all PHYs from all net_device being listed. The DUMP command +accepts either a ``ETHTOOL_A_HEADER_DEV_INDEX`` or ``ETHTOOL_A_HEADER_DEV_NAME`` +to be passed in the request to filter the DUMP to a single net_device. + +The retrieved index can then be passed as a request parameter using the +``ETHTOOL_A_HEADER_PHY_INDEX`` field in the following ethnl commands : + +* ``ETHTOOL_MSG_STRSET_GET`` to get the stats strig set from a given PHY +* ``ETHTOOL_MSG_CABLE_TEST_ACT`` and ``ETHTOOL_MSG_CABLE_TEST_ACT``, to perform + cable testing on a given PHY on the link (most likely the outermost PHY) +* ``ETHTOOL_MSG_PSE_SET`` and ``ETHTOOL_MSG_PSE_GET`` for PHY-controlled PoE and PSE settings +* ``ETHTOOL_MSG_PLCA_GET_CFG``, ``ETHTOOL_MSG_PLCA_SET_CFG`` and ``ETHTOOL_MSG_PLCA_GET_STATUS`` + to set the PLCA (Physical Layer Collision Avoidance) parameters + +Note that the PHY index can be passed to other requests, which will silently +ignore it if present and irrelevant. -- 2.43.0 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next prev parent reply other threads:[~2023-12-15 17:13 UTC|newest] Thread overview: 64+ messages / expand[flat|nested] mbox.gz Atom feed top 2023-12-15 17:12 [PATCH net-next v4 00/13] Introduce PHY listing and link_topology tracking Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-15 17:12 ` [PATCH net-next v4 01/13] net: phy: Introduce ethernet link topology representation Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-15 21:45 ` Vladimir Oltean 2023-12-15 21:45 ` Vladimir Oltean 2023-12-17 16:57 ` Andrew Lunn 2023-12-17 16:57 ` Andrew Lunn 2023-12-18 8:49 ` Maxime Chevallier 2023-12-18 8:49 ` Maxime Chevallier 2023-12-18 9:11 ` Maxime Chevallier 2023-12-18 9:11 ` Maxime Chevallier 2023-12-18 6:04 ` kernel test robot 2023-12-18 6:04 ` kernel test robot 2023-12-18 8:10 ` kernel test robot 2023-12-18 8:10 ` kernel test robot 2023-12-15 17:12 ` [PATCH net-next v4 02/13] net: sfp: pass the phy_device when disconnecting an sfp module's PHY Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-15 17:12 ` [PATCH net-next v4 03/13] net: phy: add helpers to handle sfp phy connect/disconnect Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-15 17:12 ` [PATCH net-next v4 04/13] net: sfp: Add helper to return the SFP bus name Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-17 17:07 ` Andrew Lunn 2023-12-17 17:07 ` Andrew Lunn 2023-12-15 17:12 ` [PATCH net-next v4 05/13] net: ethtool: Allow passing a phy index for some commands Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-16 11:48 ` kernel test robot 2023-12-16 11:48 ` kernel test robot 2023-12-17 17:11 ` Andrew Lunn 2023-12-17 17:11 ` Andrew Lunn 2023-12-15 17:12 ` [PATCH net-next v4 06/13] netlink: specs: add phy-index as a header parameter Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-17 17:11 ` Andrew Lunn 2023-12-17 17:11 ` Andrew Lunn 2023-12-15 17:12 ` [PATCH net-next v4 07/13] net: ethtool: Introduce a command to list PHYs on an interface Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-19 8:55 ` Simon Horman 2023-12-19 8:55 ` Simon Horman 2023-12-15 17:12 ` [PATCH net-next v4 08/13] netlink: specs: add ethnl PHY_GET command set Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-15 17:12 ` [PATCH net-next v4 09/13] net: ethtool: plca: Target the command to the requested PHY Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-18 9:55 ` Andrew Lunn 2023-12-18 9:55 ` Andrew Lunn 2023-12-15 17:12 ` [PATCH net-next v4 10/13] net: ethtool: pse-pd: " Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-18 9:58 ` Andrew Lunn 2023-12-18 9:58 ` Andrew Lunn 2023-12-21 17:31 ` Maxime Chevallier 2023-12-21 17:31 ` Maxime Chevallier 2023-12-15 17:12 ` [PATCH net-next v4 11/13] net: ethtool: cable-test: " Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-18 9:58 ` Andrew Lunn 2023-12-18 9:58 ` Andrew Lunn 2023-12-15 17:12 ` [PATCH net-next v4 12/13] net: ethtool: strset: Allow querying phy stats by index Maxime Chevallier 2023-12-15 17:12 ` Maxime Chevallier 2023-12-18 10:00 ` Andrew Lunn 2023-12-18 10:00 ` Andrew Lunn 2023-12-15 17:12 ` Maxime Chevallier [this message] 2023-12-15 17:12 ` [PATCH net-next v4 13/13] Documentation: networking: document phy_link_topology Maxime Chevallier 2023-12-18 10:10 ` Andrew Lunn 2023-12-18 10:10 ` Andrew Lunn 2023-12-19 8:58 ` Simon Horman 2023-12-19 8:58 ` Simon Horman
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20231215171237.1152563-14-maxime.chevallier@bootlin.com \ --to=maxime.chevallier@bootlin.com \ --cc=andrew@lunn.ch \ --cc=christophe.leroy@csgroup.eu \ --cc=corbet@lwn.net \ --cc=davem@davemloft.net \ --cc=edumazet@google.com \ --cc=f.fainelli@gmail.com \ --cc=herve.codina@bootlin.com \ --cc=hkallweit1@gmail.com \ --cc=jesse.brandeburg@intel.com \ --cc=kabel@kernel.org \ --cc=kory.maincent@bootlin.com \ --cc=kuba@kernel.org \ --cc=linux-arm-kernel@lists.infradead.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux@armlinux.org.uk \ --cc=netdev@vger.kernel.org \ --cc=nicveronese@gmail.com \ --cc=o.rempel@pengutronix.de \ --cc=pabeni@redhat.com \ --cc=piergiorgio.beruto@gmail.com \ --cc=thomas.petazzoni@bootlin.com \ --cc=vladimir.oltean@nxp.com \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.