From patchwork Tue Feb 13 15:04:30 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxime Chevallier X-Patchwork-Id: 200484 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:bc8a:b0:106:860b:bbdd with SMTP id dn10csp603655dyb; Tue, 13 Feb 2024 07:14:25 -0800 (PST) X-Forwarded-Encrypted: i=3; AJvYcCV/UfA5NOnaJRxIOpccr9BmEqIBONVE1FnMT9Tv1FLw5QPlQhX5ZgZ8xyAMzjOczcLd1TDBl2tCtJRM3qgx8w51ineBaQ== X-Google-Smtp-Source: AGHT+IF8CP8QnwxwXIKC9HoDguYje8Tbya91t3B9Ad5rfCDqbTyZphx1+vEsp97Z8z8QFv2kDYNV X-Received: by 2002:a17:902:d58d:b0:1db:4c8d:9135 with SMTP id k13-20020a170902d58d00b001db4c8d9135mr721495plh.8.1707837265391; Tue, 13 Feb 2024 07:14:25 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1707837265; cv=pass; d=google.com; s=arc-20160816; b=0E10G4ssr6zLAjGb48qKvN2S+zKAp6CPLLZAbivP+4BmcYWpbCT5g9IGfKkbMHXefT mSt53QxF4kNrljMj/kkNHcjTheynuq/ZL6LBYXvJYnCKTohfQPsgF5HCrDbPOPDdvQvU T9NFe3YZCny1PiCtltAsuSHAfXIkv0gFaO3gJp30KQTSZAhO+KBCGz0YJg1GRe8oUy0Q as2N9fKy5fyW1RMK2tVMKV0rtcCPO0hYYQh0sGrvzSEtgsfSUYRnAZ4DSA2XiuAI6uid ujwGq7V4rdL0wShBiSEyYuk//fdts2navQJ4ES4qg5FtJsnKCly/Z/DStlWxD+ZCVFa5 TtGw== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=h7WMOt1ze7IKBjWKorPDQc+EzFaDeiOqVddzYKHv2ks=; fh=CPWSkVmmOY6DjMOz5d5UZNxLEWhmHEWK9V8KEu74EVM=; b=mGbSJjZwB8CepxtH0uzfZcMBVzzHaatl0f+BdSc66tUsTNP0AXTo+/ECvbbA1tqVpl 0lGb1xRXWGWoBG8YTic+oOu6nUOKfdt27dTUHTWLw7dAzT66VvuLV+aqdmLgrIrE4dq7 d4e9b+lpSUHvh342VDB/hEM8pnXmOVYQt3REueRui0QI/YIISXF3F2Ev9pNxmOmlJplt XoATt+U0tOLaE+7nl4zu5GPdSaabBgFUQizvURKeIg/uzetqtaIpBY7gHNgSPfY/36t4 AAtDpSLgnuCr4hs0WAqBCbGdQPZbMhMUl+OQ+yy5JbDvI2MwimM6Mblxr21CzESmn6fW s6wQ==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=GyPezfDS; arc=pass (i=1 spf=pass spfdomain=bootlin.com dkim=pass dkdomain=bootlin.com dmarc=pass fromdomain=bootlin.com); spf=pass (google.com: domain of linux-kernel+bounces-63778-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-63778-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=bootlin.com X-Forwarded-Encrypted: i=2; AJvYcCVezJYm8aa3021K4Nh0BVNxCqdTXdH7U0+kjvEHzWlSjluEP7broqWB8dS2Denf+riDqLfV+qRBU5zw7wnYlTaFAUZJgQ== Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [2604:1380:45e3:2400::1]) by mx.google.com with ESMTPS id e7-20020a170902784700b001db35c3088bsi1228282pln.105.2024.02.13.07.14.25 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 13 Feb 2024 07:14:25 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-63778-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1; Authentication-Results: mx.google.com; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=GyPezfDS; arc=pass (i=1 spf=pass spfdomain=bootlin.com dkim=pass dkdomain=bootlin.com dmarc=pass fromdomain=bootlin.com); spf=pass (google.com: domain of linux-kernel+bounces-63778-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-63778-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=bootlin.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id B285F2859E3 for ; Tue, 13 Feb 2024 15:11:13 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 82F88612F3; Tue, 13 Feb 2024 15:05:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=bootlin.com header.i=@bootlin.com header.b="GyPezfDS" Received: from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net [217.70.183.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id F133360DDC; Tue, 13 Feb 2024 15:04:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=217.70.183.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707836697; cv=none; b=Z4RZbBlExaWHJhtOtkFt2aVrCq7Yv5bER0pWCDmDIwBUDgxzrq2Cfn0IEqDRXqnLUhx9wtjj+ulYMzsQPcz7Sx5slDbXZlVOo60jTzBuWON9AvzZtfSFiEfAFWFyYzxAhosywTGWnK+8xStbfaiGHqdoThv1447+mYoSO3098fA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707836697; c=relaxed/simple; bh=vrBPISOOJ+7feBnFQa20LdUxn/SOlHalkdrgKO4Fq9E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Ld49NueEQaISGeKay/yT8Kt7sJirtmQ+xyx0EcCy1mgMW6and4Cb3Ma3U9qWQLDWQAHD6wKoG8VId7M+yo5L+mGOemLZOXw1lhUvNL/WWtYQCwAWBwXb34KoS3SKmER6yASd3K+LZXwIp41LkNAXeWS91oBM25glsuMjpkUNxF0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=bootlin.com; spf=pass smtp.mailfrom=bootlin.com; dkim=pass (2048-bit key) header.d=bootlin.com header.i=@bootlin.com header.b=GyPezfDS; arc=none smtp.client-ip=217.70.183.201 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=bootlin.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=bootlin.com Received: by mail.gandi.net (Postfix) with ESMTPSA id 527681BF210; Tue, 13 Feb 2024 15:04:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1707836693; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=h7WMOt1ze7IKBjWKorPDQc+EzFaDeiOqVddzYKHv2ks=; b=GyPezfDSbZU0CQ5MR5q/6gSaqP7K1Od5Bz9MACY0kPiGfjqsb7CJziTgnKgdCkbNaQK4OK yF3MdSNxaBRO9s9FtYoN2woQznFCY/1ru5pb+1fPZujsAkW7O8tDW9iUsPOD5cqhlr/oAY vd9kBg4c7eYbWOyGHx9ak7g2LXuuThrABqOshoEZfzLV6xEHmEVes+8HA9upLng3w4bBsM 2l5c2EN4BZDjk/7Fi6zVxk0boMaolGuK88fEfgfDRJ22j14Lx5FIAcELeTjNEof6vENo4D ujnbYOCBCXpWT+eIC16JoD0mUv/lL42+jQxEVrbnZ15FjNg7z1nJ1GgsS8JIfg== From: Maxime Chevallier To: davem@davemloft.net Cc: Maxime Chevallier , netdev@vger.kernel.org, linux-kernel@vger.kernel.org, thomas.petazzoni@bootlin.com, Andrew Lunn , Jakub Kicinski , Eric Dumazet , Paolo Abeni , Russell King , linux-arm-kernel@lists.infradead.org, Christophe Leroy , Herve Codina , Florian Fainelli , Heiner Kallweit , Vladimir Oltean , =?utf-8?q?K=C3=B6ry_Maincent?= , Jesse Brandeburg , Jonathan Corbet , =?utf-8?q?Marek_Beh=C3=BAn?= , Piergiorgio Beruto , Oleksij Rempel , =?utf-8?q?Nicol=C3=B2_Veronese?= , Simon Horman , mwojtas@chromium.org Subject: [PATCH net-next v7 13/13] Documentation: networking: document phy_link_topology Date: Tue, 13 Feb 2024 16:04:30 +0100 Message-ID: <20240213150431.1796171-14-maxime.chevallier@bootlin.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240213150431.1796171-1-maxime.chevallier@bootlin.com> References: <20240213150431.1796171-1-maxime.chevallier@bootlin.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-GND-Sasl: maxime.chevallier@bootlin.com X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1790797168358407444 X-GMAIL-MSGID: 1790797168358407444 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 --- V7: No changes V6: No changes V5: Fixed a lot of typos 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..1fd8e904ef4b --- /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 point of view is nothing but a +:c:type:`struct net_device `, which exposes configuration options +through 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 apart 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 ` 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 `. + +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 `. 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 string 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.