From patchwork Fri Dec 8 19:35:15 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Vladimir Oltean X-Patchwork-Id: 13485810 X-Patchwork-Delegate: kuba@kernel.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=nxp.com header.i=@nxp.com header.b="RYEvIwqk" Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05on2045.outbound.protection.outlook.com [40.107.21.45]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F27FC1712 for ; Fri, 8 Dec 2023 11:36:55 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=O7Y7FknJhAtdZmzEwTU4s1HMem2Vj8Z2gP9jA1tdH9InT5OyrBCrU4GBJ83irHPcb2qvqho5Cua+TFRuBx3J2I7XlpDXzd7+/jEn0GiJRZPZ9pLcduukbIBbCBZOhgw9nM50SyVSWKPT7uvOjudO9vRnKNV2tTLWyyCt+Jw8kQ9zqKHQPxrsgeF+I/CuF+QJj1jh3RIX3Q6RhKiDHduVxV6yW9oRxOCxvzItIk44yyUWTMg0mxKdWiORomLaoeQxXAqyzm3VEZZoNUIM/c31ElLvwEKQqVy2qkmeozMt6E7L6mG/Jz5R2Ft2OHklDwaveAHz1BfZlQFYcR+7cxwtjQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=YXj9mnn60bcqUhEuemsfc+VvMMgJ+weiN/8/DPHM9Pw=; b=YLFICNz1CXc6XBIkziHJ1l72hNoGvLUzl5qUWPYOJtSErlXlBxM3TOG1OJmq5JuqqXFDnPEgHKz27kHe7nOmBUKCugwLCKVqfRL0hKd5zSHBQznZAd9ztno2RdzX41IGjdOAcGIYzka37RycnJ69cme44JQmAQZlHalWz4jTqqGAZ2d2YnPp2YAU+PP+oJW7WdrU/Tku8e0t2xv5jrL+8/nJkItoNImis7H6xFgXc2MUSRxqWbh4dIsmdTAVzybtcxBBTm9UJOP4APEaa/FWKdG6M9V8OY24NQY0U8BLJf4fRRN6aP34mTH6sxupTu2g3D8JVs38/y5NMqi0uPtLkg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nxp.com; dmarc=pass action=none header.from=nxp.com; dkim=pass header.d=nxp.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=YXj9mnn60bcqUhEuemsfc+VvMMgJ+weiN/8/DPHM9Pw=; b=RYEvIwqkzWy7u/9r08mUz1oXv2+t6g6SgH4PsJ2lmCwhbOeSZMQZYOP1k0c7EmoDkfpyXg/sk0da7POhSj0La2lpXH3QgyVejFitN7TDwUeqvIjXg5aYmXgHyCVyqMarRhE/o083y1hFJhqG6xn5MWQf1Oh9LugQppnoDAnqfrE= Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=nxp.com; Received: from AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) by GV1PR04MB9213.eurprd04.prod.outlook.com (2603:10a6:150:28::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7068.28; Fri, 8 Dec 2023 19:36:52 +0000 Received: from AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4]) by AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4%7]) with mapi id 15.20.7068.027; Fri, 8 Dec 2023 19:36:52 +0000 From: Vladimir Oltean To: netdev@vger.kernel.org Cc: "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Andrew Lunn , Florian Fainelli , Luiz Angelo Daros de Luca , =?utf-8?q?Alvin_=C5=A0iprag?= =?utf-8?q?a?= , Madhuri Sripada , Marcin Wojtas , Linus Walleij , Tobias Waldekranz , Arun Ramadoss , "Russell King (Oracle)" , Jonathan Corbet Subject: [PATCH net 1/4] docs: net: dsa: document the tagger-owned storage mechanism Date: Fri, 8 Dec 2023 21:35:15 +0200 Message-Id: <20231208193518.2018114-2-vladimir.oltean@nxp.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231208193518.2018114-1-vladimir.oltean@nxp.com> References: <20231208193518.2018114-1-vladimir.oltean@nxp.com> X-ClientProxiedBy: FR4P281CA0101.DEUP281.PROD.OUTLOOK.COM (2603:10a6:d10:cb::16) To AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: AM0PR04MB6452:EE_|GV1PR04MB9213:EE_ X-MS-Office365-Filtering-Correlation-Id: 0d9ce0a1-370e-40a6-c204-08dbf8250756 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: yBkxGcbw4KO8dTOvIt7/SJ1oFK646Xb/0r0P0ZsjyuEQBzXPunt5JDZiIGTztdoXGZZ+DqB5m0nfBzRRphatgJ5lZDBIZ8ap40Vj8OpIrFOMwjQQZjh4DOyJlvRt92NskErkTWzE4vebQi8V+hakCTORmmP9WtEz5FDSL2T8GoegpEpm6L8MUmKVB4moGGxXqteGDkBcxKM5jZIcOiou/W89TcMADWq8eI8O2QyrrjRlUO6p85h60PPZjKk2rCcqrShXxD60ALSWBoC0cjzr7fw6xnvCE15OoNM6Q8A0yd/pw1FSlEOaBoepOIvUsP2P2IVMRCy0B8WgS3q0QKhiOixn9sAD6ozTZ7jzPOqIsCR/Awu5WNC71TrTsZZJ6n8JZWNSQKxoP30aR69hhzEuNlJ92cZ69TggYWDWbx8V7/0JFX/YsIhuWD58EBdnU0SC+n+WHxg1LG1Zhm91ec6UVrq/wZg389XA5DRaJXiBkKPN3XopVDkBr774JRL5ExpRZ4jHPXno7VkR/hMrfboDjbMuzWnbfM8GVwbZmNL5dKbzRxSvryoiiXWkGFrXMXGvyGtjCq/Du2VwfyI1pvDQs0ty1RxeEw5o4KiLRn/xx4pi0NBTfVDfNvbToPyF+kx4 X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:AM0PR04MB6452.eurprd04.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230031)(39860400002)(136003)(396003)(376002)(346002)(366004)(230922051799003)(186009)(64100799003)(451199024)(1800799012)(38350700005)(66899024)(8676002)(6916009)(66476007)(66556008)(66946007)(54906003)(86362001)(36756003)(38100700002)(83380400001)(1076003)(8936002)(2616005)(26005)(52116002)(6512007)(6506007)(7416002)(2906002)(316002)(478600001)(6486002)(6666004)(5660300002)(41300700001)(4326008)(44832011);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: 3YDsMTxXpyGp5ADeeYA2PS3vd5NSaeDFS8rZCoRzYwhbYyIKKWz43Ti+GBIQ+aVlzsSD4ykaOJkWZ8IYco2TcjYf0bcGwYLplg46d/R+YUgVgq8A4+JG4TqqUSNbyklbVV3PkIsZTfBp0kGa7IxXN2RNr21MQAcvEeennKA0hgSdfCkO6AP8jewfDZwOxycEBAL+M+S3D0f8Ix97jq+wtQQ8zTyZ/wLVB9SLg6Dw1w4m7yhcyCXSZsnDXusTuuhsqkSvxrIq/JBvLGOI1R/mTQAqUKw6dflImvVqC+PXyPYEZv4zkyBrT4SIOqJZmcZUe9Se7NlVLIAa3Sfk6lLW/lAI18nfe55RPjJFB8Yhtmhyre2DD27lMvqeF/kuBWQkcAkwyJKf+sSrp72wu0bNNVW9waFlZsoJprEcj5FIVRYg0dNazXz1glNlHWp936VoznpIiUqL8mgLPJlL/SldO4VmQ0Yi1ymT1XBc5vmc26wS6HRS7hx/aYMJ0bhtuM8DM4AsySpvF8Q+lUeeGxLtN1W4+iTK8Tms3OlBKDLr0OAhEO2XUZvtHcbyxZfu++k5se1FHZ7UNXu0zPhd7VXfRaoIgVSWoHvl6tnzPWc29G57hX3EyT3R6ARd6JGthjRGdl/kLgnD3omvE3VIF15eTH29Qmf4m2F6Ume7aFpaqdc8w1xgr6R76i3svGMP6JzpEdbbjwNvH29vsHLT+RnptodG0IX+Lgrszi+eDHaMI7HV5zJ/DH7CgsKcaFT19C9c8b/KZgAJ+MTJ8QgjNOeyE4rX+m+Fgcyj9scLh6MWQXbbxzjZeJ0xx0xZqFUAZbNWtQToS+63zZsmPlWlqADVaHfbRmKJcA5Af0iSoR7EKYBiN43X1HSu3Jjc1UTy3D0WOEhugDqYD/ItpjnO8/0jFf+TQnqwucqtBa4mFQr3yOGM/bxDvF1+KIcEiKHivIdyN0J87ikE78XDWAswMTrXyMPXrx+eio61+89i7bE2bPXbZxrnknAlL6mFMklRqIdYagG7sYXnClPAori9LxR6tcOiqpIFNWLDiVCvgQ9tBkmT2te0R0idMrF2T8axIwUQ5zGPuQJfxvGtBMksTNJWriJA6khuxYB9rxSeQzp4vooZgDeq00fYvqoULHiTyvdcsTNxbaShB6ZaOBXKKjd3Z+MvnTZPXUv99mzOaMsjYP9prwt96/NjiuV530urfiIoWTkgBO/K6ASI95aFz9CnqsMH76B2IKSYgwieBCoYliIlBcqkKIls3RIraFUoJmlvFtC5AsAMOFaZ9Mfa1eOZVO+Y0d+o/jJS18A1ze4PyzMb/SeJPn/b2n4gfxBouSRGRVgeY43UIvzC+VB0rYeKlOQQHpQ7NQOUVUzp71/WFn3Lw4HdOJdMc7s4bH69d5tHVwedeosP5hw87xiAHMm/fLmm7QFDIQj2VhaH3D3mMw50MmfqPnxh3OKWgRkrCGUwMpCGrrsyls17IotKxJiMaxaGuA+PwMguoPV4jt6LNRIAfk17qdogOkc7cYQzXfBJvVEmx/lxr/nSg/DdD9Re5UN075tvEoPIMnEf9mZ68Q/4l6VwDjhqtv0hE7G829zWftPcO5EoL8QiT8XspiZSUw== X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-Network-Message-Id: 0d9ce0a1-370e-40a6-c204-08dbf8250756 X-MS-Exchange-CrossTenant-AuthSource: AM0PR04MB6452.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 08 Dec 2023 19:36:52.5847 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: 9MhR3WUvDqXJTt/3h6btLVHSDIRfG1nHQ7LOqqHsjxb0oFWD8w8S/CxkS0aLate5IpmuJIWRLq4/4vpye8EWoA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV1PR04MB9213 X-Patchwork-Delegate: kuba@kernel.org Introduced 2 years ago in commit dc452a471dba ("net: dsa: introduce tagger-owned storage for private and shared data"), the tagger-owned storage mechanism has recently sparked some discussions which denote a general lack of developer understanding / awareness of it. There was also a bug in the ksz switch driver which indicates the same thing. Admittedly, it is also not obvious to see the design constraints that led to the creation of such a complicated mechanism. Here are some paragraphs that explain what it's about. Signed-off-by: Vladimir Oltean Reviewed-by: Linus Walleij Reviewed-by: Florian Fainelli Reviewed-by: Alvin Šipraga --- Documentation/networking/dsa/dsa.rst | 59 ++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index 7b2e69cd7ef0..0c326a42eb81 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -221,6 +221,44 @@ receive all frames regardless of the value of the MAC DA. This can be done by setting the ``promisc_on_conduit`` property of the ``struct dsa_device_ops``. Note that this assumes a DSA-unaware conduit driver, which is the norm. +Separation between tagging protocol and switch drivers +------------------------------------------------------ + +Sometimes it is desirable to test the behavior of a given conduit interface +with a given switch protocol, to see how it responds to checksum offloading, +padding with tail tags, increased MTU, how the hardware parser sees DSA-tagged +frames, etc. + +To achieve that, any tagging protocol driver may be used with ``dsa_loop`` +(this requires modifying the ``dsa_loop_get_protocol()`` function +implementation). Therefore, tagging protocol drivers must not assume that they +are used only in conjunction with a particular switch driver. Concretely, the +tagging protocol driver should make no assumptions about the type of +``ds->priv``, and its core functionality should only rely on the data +structures offered by the DSA core for all switches (``struct dsa_switch``, +``struct dsa_port`` etc). + +Additionally, tagging protocol drivers must not depend on symbols exported by +any particular switch control path driver. Doing so would create a circular +dependency, because DSA, on behalf of the switch driver, already requests the +appropriate tagging protocol driver module to be loaded. + +Nonetheless, there are exceptional situations when switch-specific processing +is required in a tagging protocol driver. In some cases the tagger needs a +place to hold state; in other cases, the packet transmission procedure may +involve accessing switch registers. The tagger may also be processing packets +which are not destined for the network stack but for the switch driver's +management logic, and thus, the switch driver should have a handler for these +management frames. + +A mechanism, called tagger-owned storage (in reference to ``ds->tagger_data``), +exists, which permits tagging protocol drivers to allocate memory for each +switch that they connect to. Each tagging protocol driver may define its own +contract with switch drivers as to what this data structure contains. +Through the ``struct dsa_device_ops`` methods ``connect()`` and ``disconnect()``, +tagging protocol drivers are given the possibility to manage the +``ds->tagger_data`` pointer of any switch that they connect to. + Conduit network devices ----------------------- @@ -624,6 +662,27 @@ Switch configuration case, further calls to ``get_tag_protocol`` should report the protocol in current use. +- ``connect_tag_protocol``: optional method to notify the switch driver that a + tagging protocol driver has connected to this switch. Depending on the + contract established by the protocol given in the ``proto`` argument, the + tagger-owned storage (``ds->tagger_data``) may be expected to contain a + pointer to a data structure specific to the tagging protocol. This data + structure may contain function pointers to packet handlers that the switch + driver registers with the tagging protocol. If interested in these packets, + the switch driver must cast the ``ds->tagger_data`` pointer to the data type + established by the tagging protocol, and assign the packet handler function + pointers to methods that it owns. Since the memory pointed to by + ``ds->tagger_data`` is owned by the tagging protocol, the switch driver must + assume by convention that it has been allocated, and this method is only + provided for making initial adjustments to the contents of ``ds->tagger_data``. + It is also the reason why no ``disconnect_tag_protocol()`` counterpart is + provided. Additionally, a tagging protocol driver which makes use of + tagger-owned storage must not assume that the connected switch has + implemented the ``connect_tag_protocol()`` method (it may connect to a + ``dsa_loop`` switch, which does not). Therefore, a tagging protocol may + always rely on ``ds->tagger_data``, but it must treat the packet handlers + provided by the switch in this method as optional. + - ``setup``: setup function for the switch, this function is responsible for setting up the ``dsa_switch_ops`` private structure with all it needs: register maps, interrupts, mutexes, locks, etc. This function is also expected to properly From patchwork Fri Dec 8 19:35:16 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Vladimir Oltean X-Patchwork-Id: 13485811 X-Patchwork-Delegate: kuba@kernel.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=nxp.com header.i=@nxp.com header.b="R3t6Dh5B" Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05on2045.outbound.protection.outlook.com [40.107.21.45]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9B6351720 for ; Fri, 8 Dec 2023 11:36:57 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Sb+lQBHdbQO7uixgsFiLBPbQhf4bhUXcW43MDrrvcw1YN4aL2puNkbzstNktO7+i/O87EA/bJEhqxT8py8bMzn25E2jWMc9kxegCyFo4uuhPQ0b9obnAMiEzPvs6Hs2Lhl03JMkjp0s9+2LsBhgo4V7If106UfjWfY2m2p+fVoH3flTA6Yf0fkjit6W0gCU0un9OjVlRQoeIybqlOE3AKtm/LySpNZlqNAPRKI1o45SvGxc3IVfxGQH/2XU2liNwKvELoOt1+4/TWW1GCf82z8XDlUDc0aDbKxoYfo10dPcYSPutf6/KGRJ8blZZtRjtuFLq+FSiSK3ouqhuV2LiRg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=13KaXno3YDAEXeSK9DARmPeqqORymq9RDF0JvSnc1Jk=; b=HH2lxOJj33UN3KVhRfiV1fxVUxWmkXF7vGHcuj8wdJ21eVd5txBHilg8w9k/EzIrFBmxuv0vgjD0zxg5QVWtjtU1XW1ALEDKKbOjmIfz+uV00iEv/OVGq60U5GH8pnfJXxJr5mHIX/YLHM3+52iDYSiLdyRxQAzaDxAaCvpB/+0wEXFvZYvyla3+FgylmF0SYq+RVbEH8k/KBgVO6kPkDoVNEpk3DqyIeqNXgJIOLLQICcUn5WVw+/C8f8rb/bSquTHzuWwp+hl2SMv7DRyixroC0YVteWo7bDrH2bNqBpbdqauceLDQS4G2l/JOHcQzIqJYUg6yLyg4qyb45wKDsQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nxp.com; dmarc=pass action=none header.from=nxp.com; dkim=pass header.d=nxp.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=13KaXno3YDAEXeSK9DARmPeqqORymq9RDF0JvSnc1Jk=; b=R3t6Dh5BcR6nEsl76W1Rk7qLfWy50iYgh0g8CrLaC4gde4ZOR6pym5As0I77gfSUsEeScLkyakbDWIPHf9mrAoWKep4tKNKiKC0eiv3dJmIre8t7LFBvqME0wyHKhwFlvC9yMOQ0KFf4x7y+0Vsvw5FJ502rQNCyRoWSaz4ryTk= Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=nxp.com; Received: from AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) by GV1PR04MB9213.eurprd04.prod.outlook.com (2603:10a6:150:28::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7068.28; Fri, 8 Dec 2023 19:36:53 +0000 Received: from AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4]) by AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4%7]) with mapi id 15.20.7068.027; Fri, 8 Dec 2023 19:36:53 +0000 From: Vladimir Oltean To: netdev@vger.kernel.org Cc: "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Andrew Lunn , Florian Fainelli , Luiz Angelo Daros de Luca , =?utf-8?q?Alvin_=C5=A0iprag?= =?utf-8?q?a?= , Madhuri Sripada , Marcin Wojtas , Linus Walleij , Tobias Waldekranz , Arun Ramadoss , "Russell King (Oracle)" , Jonathan Corbet Subject: [PATCH net 2/4] docs: net: dsa: update platform_data documentation Date: Fri, 8 Dec 2023 21:35:16 +0200 Message-Id: <20231208193518.2018114-3-vladimir.oltean@nxp.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231208193518.2018114-1-vladimir.oltean@nxp.com> References: <20231208193518.2018114-1-vladimir.oltean@nxp.com> X-ClientProxiedBy: FR4P281CA0101.DEUP281.PROD.OUTLOOK.COM (2603:10a6:d10:cb::16) To AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: AM0PR04MB6452:EE_|GV1PR04MB9213:EE_ X-MS-Office365-Filtering-Correlation-Id: 2916f6a8-20e0-4a9c-086d-08dbf825081f X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: z8202h2pVlmiDxgQoL60HkUyuUpnPPJAkigavbYvp+PI9QG7cPdlu/SR3kRiYkylgBJP+xTYaG5DVvr+TInWN11ej4NwLWtr9ki55sT/kXYZ9hG9gpH8R6BW0YWdgxIf94eJrgXVhx1vy8pEieWpVDmucnyB80U667/Ym9FIYh0sb9IB4kq3G5FMaZiENbpUu+0yI8UH++KOU2WqtTkRYU5JhGC6xS5VVffuJHm3b3W3umZy1X67PBlBV7BtAdDfNoRHpxFBI+91tDK31m3z9hkguRVKm8JhoJFIwTSSICbT2tuUMzM8aYXx0OSRefWD948BySLEggRtP6V/Ety+fcN0O5YxCBxwfiykqZQFd4l+TGyUZqJyHsRG/5lTEx2o54o8ixgd2C6ACaZdcHrEyDpJe1MTmy6SLtXlEk2TSNE/rkNCaVe9hGjfZtPga9COmvZKlQbYBt449cfir8lwoHhwTCZyHHmD2RqpYk2fGc6t3xbm0ENaOyi1ffHOcPvDoIAuikzyNt/J8b2D03YtKSt51bS05x7du3cMRzS41jYMUiGaReoffzSQjgomNQIklzGFKijbx+Zzbe19QoWCfgUjda3KpUR/7UEK3qUmyvJyYmrNJwNvwjLYcXnAVKXyYwLpOE3/dHlYCEuiTmgfNPeOd1fjiQlbobGyiSXDQ1c= X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:AM0PR04MB6452.eurprd04.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230031)(39860400002)(136003)(396003)(376002)(346002)(366004)(230273577357003)(230173577357003)(230922051799003)(186009)(64100799003)(451199024)(1800799012)(38350700005)(8676002)(6916009)(66476007)(66556008)(66946007)(54906003)(86362001)(36756003)(38100700002)(83380400001)(1076003)(8936002)(2616005)(26005)(52116002)(6512007)(6506007)(7416002)(2906002)(316002)(478600001)(6486002)(6666004)(5660300002)(41300700001)(4326008)(44832011);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: K+/XUlU3OPdjWEsggRw4bmxSgWiiXZ3+ZNqKjEOkezobcZjgUzfUf/V0ZHV8lIwD4jsw7c9qSeGrKbnybC7uBU7x9YKiMB9WVDHj5JqdpE0f6+trHqQXZwo7dQTeVFX7PaQozk8E1D7S0hJY/sPHWjl19lrk8ufXfvipZN/e49clHLVWy1SFiagwtsYEc5Ua9xQhcIQwFs5q+TzIAMzoMFGgMiJkoR93KubKo14QxY2dO2G1zYbBaed0WA/6PdoFdOWzZ7JHlFAKGbrH5wy7pD7Wh9ix6OnLalD+rVhfNin66XQ7uZRG/Wlfciw/TV6WEj+Dze/QDB/4Ad09S12vgkbzJHMPDWU5ASgniZqigPsERzi5TPcLbX15ljeTA+SHvjq4A1zFNyrM/h1XVRiFtr2wj9ljupCBe8EejtCYcJoHf0jMFiEvaLofxEe1l9ZDyjl+5QyL+tbwp81YDvy0yA09Icp60d9VW2wln5h+hoEpQsB8hoWvxyG0AmaY/RNcgyLTRT/3A3FO5CdujvSZnKVL0BKHXwthKs8c0Fh85UH/CLCyNQutC9GE03bXTU7+9OlMG59utVfSrv0OrF9l3mCNPDzdjIiyL8M6dFCUTn2uiQjLO4pMmokHrmKKOeythIeJGirdxe5HkPkY91YQDK2g4cGcM+rFRVDxa4FBQAsX7w8VUh1Tz5I2/eBX4vyz1HhGLJMVpVIxOase7D5lkuwEq9mE9m8lnjr5dOepRhBYiD3CzSfRxgj/lJ+qE0wv8yUtypb54ZdHJqHPFMTX8mAK+QDYQqytZLV87Cnhd2I3QaFgl1qYloW0cs/1nTvtQHCIjVRZCQz36jVbaSFMKmVsOVBB9oP8LB5Zw4g4ym1/udt9i3XjgBkZG0/BmnL+x158JJ7qnYBLW2LjLNo1ecusR1mteW9XbDEvh/vKXHRI9lXkYYyuvuXo/k9Iv0pf1D9BMq7rydCncbMbZGx1XM3yS6Espzzg7pQJ9C+n6s0kJbCBVH+Wj3ijs/RGmFhWPE+zNHVEW+FdvWk8YeK2eY8+oBHY2AeVFVE1ukVmG7B9BFkyoc+jCgUfWy9zgw9jr9YNfyR7BAX921CkGY7NpRr1PbCEwSwGUkqVTMXQ16+0RC6kRWIhDZWbEka+WTEVbMzNDekhcpNMN/yiu4Lg1JGKY6vKs65XEdMIJvmbwXvp0wUbOmj2yisdOLKqEChewYQNjrDHwWLULoZv3xtqhff9dlLDXwbTIFF+lbZMwL5DOhnH8VC7RzzS3fYBqveuRC2vExS+flumzi5oQHJswMkgqmtsGFTVOSUZ1sF7z/toF+rGE0IwAIhHnc9J3pi/knC5V7Us/VxI6ctD/H/B8BISdOt9cY+7TslUfhuSCdYUtJlUxh+K5ClcPD7aSmLnTK8q/xM1nY81ekoAxUo8X+UzfJmX+KFmr3cWLbOgyUb2aX2R8ETJ6PPkHyIcRtoNWwTsvR+mlQ47LUmaAAkAVUwxYQaQqnuYOefkJ3TiEb+n/J+4lM5x/hYHrKwTTCU4lI4WAK1bNAENmPyomNB1rEbSTVHR910F8QU7ebApKHqoB4H7GIe2TRYFwisKufsu4n5sEAcQBxV1tnZXDQgggQ== X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-Network-Message-Id: 2916f6a8-20e0-4a9c-086d-08dbf825081f X-MS-Exchange-CrossTenant-AuthSource: AM0PR04MB6452.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 08 Dec 2023 19:36:53.8228 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: INHJ5XBVO4xZtxE2iQ4eppluLO84SsAF7h4JzLH2jrWNIIwn/6kNpD9d4cljapByUAC2iGIiv5KtA19lAj06lQ== X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV1PR04MB9213 X-Patchwork-Delegate: kuba@kernel.org We were documenting a bunch of stuff which was removed in commit 93e86b3bc842 ("net: dsa: Remove legacy probing support"). There's some further cleanup to do in struct dsa_chip_data, so rather than describing every possible field (when maybe we should be switching to kerneldoc format), just say what's important about it. Signed-off-by: Vladimir Oltean Reviewed-by: Linus Walleij Reviewed-by: Florian Fainelli Reviewed-by: Alvin Šipraga --- Documentation/networking/dsa/dsa.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index 0c326a42eb81..676c92136a0e 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -413,18 +413,17 @@ PHYs, external PHYs, or even external switches. Data structures --------------- -DSA data structures are defined in ``include/net/dsa.h`` as well as -``net/dsa/dsa_priv.h``: - -- ``dsa_chip_data``: platform data configuration for a given switch device, - this structure describes a switch device's parent device, its address, as - well as various properties of its ports: names/labels, and finally a routing - table indication (when cascading switches) - -- ``dsa_platform_data``: platform device configuration data which can reference - a collection of dsa_chip_data structures if multiple switches are cascaded, - the conduit network device this switch tree is attached to needs to be - referenced +DSA data structures are defined in ``include/linux/platform_data/dsa.h``, +``include/net/dsa.h`` as well as ``net/dsa/dsa_priv.h``: + +- ``dsa_chip_data``: platform data configuration for a given switch device. + Most notably, it is necessary to the DSA core because it holds a reference to + the conduit interface. It must be accessible through the + ``ds->dev->platform_data`` pointer at ``dsa_register_switch()`` time. It is + populated by board-specific code. The hardware switch driver may also have + its own portion of ``platform_data`` description. In that case, + ``ds->dev->platform_data`` can point to a switch-specific structure, which + encapsulates ``struct dsa_chip_data`` as its first element. - ``dsa_switch_tree``: structure assigned to the conduit network device under ``dsa_ptr``, this structure references a dsa_platform_data structure as well as From patchwork Fri Dec 8 19:35:17 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Vladimir Oltean X-Patchwork-Id: 13485812 X-Patchwork-Delegate: kuba@kernel.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=nxp.com header.i=@nxp.com header.b="tC+vUfpF" Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05on2045.outbound.protection.outlook.com [40.107.21.45]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E902098 for ; Fri, 8 Dec 2023 11:36:58 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=FZDKFrjVPARKUzZpSYpIfRZfAl5osaN5ggDWDDBhrJsJkC6QYfyGqi6YMOvh2rdmfHDDY4TMT3CUHP9FNQ4zU0vAx/astAcC0oeFEPNP+arcjxCVJ2mPDFBZLS8N/zQNDYJn+RofO+h86Okh5DVXc70Sv/e5JtLPTcaHHNTVV9gyv0syDr2r6MK5OS3/UUo7PNCbtLHNwgASVf553/qj2SgRdDymWOO6uSjN8H4T2MIulf/4Xp6Nt7KT5b1YOhDEUgw4+uLD8S4hgNtdmfp36EEToo629ZQtU85KYW0qi3agoRP9UOCr/Tw4Uf3jP3V5jaoPzdJ/BLhIqfnorlGn/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=Id324msxC4FP7tatrN+FNt8ShGKXuv6823a/jXbUlYM=; b=MkZq5XBh2AyXJYClryTYSXHMjBOzPcjYvaolbfY6bz/5w1cTHIifhXoUzPWA/LSfsUpv2Aj9oaniprGXAPbB7U89+bTCG4zvQk59RTikVZ6OZT9TlsXM4a55WnDfhWuPh4fx9pJJ10Czzftg7TAkugGEBaTDmqG+cqw3O/ZXqyvAKx/AQlFqyOEju0olvSJQnWlFU3d7jdRcvyE+ot8CykOuuU7ImVU2y5rPlZUTpkBFBTC+SjGkGzLTfkuJu3L6+Pw7onc1RR5J/J/xapElZPYLs5xts0bedM5LqT/zvXC+y2WqM4bQ25zK4KlCkCtZk8CsdsRMTVEbzFUxgdWtAw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nxp.com; dmarc=pass action=none header.from=nxp.com; dkim=pass header.d=nxp.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=Id324msxC4FP7tatrN+FNt8ShGKXuv6823a/jXbUlYM=; b=tC+vUfpFNKmGPTKFMbw43/ZpgoW+lTKx8Vxys6f4qYEwm3xX7NRTxpQDjmDybePPR2HWui52GEJ9n5mXhHeafBBOANarn37CCqSiIwFNdwELpRdmMBBd41V5XTXeWJ48p6l4rFORaSoAzT4JCbvIhB3UR4rKMfWrPQh3EyZVZMs= Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=nxp.com; Received: from AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) by GV1PR04MB9213.eurprd04.prod.outlook.com (2603:10a6:150:28::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7068.28; Fri, 8 Dec 2023 19:36:55 +0000 Received: from AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4]) by AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4%7]) with mapi id 15.20.7068.027; Fri, 8 Dec 2023 19:36:55 +0000 From: Vladimir Oltean To: netdev@vger.kernel.org Cc: "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Andrew Lunn , Florian Fainelli , Luiz Angelo Daros de Luca , =?utf-8?q?Alvin_=C5=A0iprag?= =?utf-8?q?a?= , Madhuri Sripada , Marcin Wojtas , Linus Walleij , Tobias Waldekranz , Arun Ramadoss , "Russell King (Oracle)" , Jonathan Corbet Subject: [PATCH net 3/4] docs: net: dsa: update user MDIO bus documentation Date: Fri, 8 Dec 2023 21:35:17 +0200 Message-Id: <20231208193518.2018114-4-vladimir.oltean@nxp.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231208193518.2018114-1-vladimir.oltean@nxp.com> References: <20231208193518.2018114-1-vladimir.oltean@nxp.com> X-ClientProxiedBy: FR4P281CA0101.DEUP281.PROD.OUTLOOK.COM (2603:10a6:d10:cb::16) To AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: AM0PR04MB6452:EE_|GV1PR04MB9213:EE_ X-MS-Office365-Filtering-Correlation-Id: e26bf1c3-f8f9-4ba9-d981-08dbf82508d1 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 6pCEZ8NpIFc2OWVtB9VFUDVA7gvPzTIXKqyC70lHOyIPvHr8x/h4YGLNo42pVTQmylcB0t4mdZqm68N8+XanAO4gtxu7XInglTu9p/I7saGd3lX+Gfn0LtndX5Z0N5zaCHSp90TrJiD4i7ockfodhBM8Rzwx3IY/gC2dBgB+hxRvkV4qUqRXSVZhDJ6rtd/fdz7JDFLZtGmD65lsBvhNoI1EXfSh//JdAC83Fg+jiggn09FssB8sYta4WqDE3iZ++1MQRDSR+3yV7tuBWyA4q06hZyuv0/5VRAYTX5H5kzidjs7YSAJlr5/DG531qvf7i6eT9v01WSdB0YaVWuQ5oad6k4phuNFX4hzNhM1gAkaPvVYbw5b2/NHD68Vp9BNmcGkiQGA61R9tOqKAK0FZxz7OzVRtcGgAiehlyx6XFKIBC1XcAZFLGPN1iFs3oLjCzpo/vDn4PP442SAIYtHbWyhGVwJkFf0p76O2TDs8pKw3JckWqeclCUT+SCuvOHAj3BSytHzB/mkUklQ2LNAX9oqovtG7kXJzcqpGlwigPYaYNqPLCVpGmhMx6GNbucrY4mbX8GVrYQYwf/GysmrNkxCfku/MPkzmjFG0FJRLIyGbAjPxTqHz+A6LUIL7vVim+gY7Wr4Z4n6rXIUcS/Do0NZOU3gyD7azo9R5/4btn78= X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:AM0PR04MB6452.eurprd04.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230031)(39860400002)(136003)(396003)(376002)(346002)(366004)(230273577357003)(230173577357003)(230922051799003)(186009)(64100799003)(451199024)(1800799012)(38350700005)(8676002)(6916009)(66476007)(66556008)(66946007)(54906003)(86362001)(36756003)(38100700002)(83380400001)(1076003)(8936002)(2616005)(26005)(52116002)(6512007)(6506007)(7416002)(2906002)(316002)(478600001)(6486002)(6666004)(5660300002)(41300700001)(4326008)(44832011);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: SFWKy614j3l8UiRyXhZQVDCEpeN/DHo+4NIgR8JD34B6YLDIXKzyZcp2usZLAgMPDqxhwDdeYqVqoJ7HC0OUJKKKtXBase3KoAApxNPPx0Xz1RUIffVxAdvkPrvtkkuz22btXyjpJ5zqsiEFOLl0MnqGQ3kCXARUvjOv+D0/lX057gsyPRnDItrBmKvGHreHtGetgfSgCIh7vSJOS7bxofmwZf2D0sadluWtw88Av4J2De1scmRvua3ofhydKwe9Tfz8OqXbYkt+m3DYFey7r5xtf5kiM7GKPPuq0jm2i60Ek3Uj+zN7fB0zZSrYyojQ6gxCpM4Lg7CA8wtacz59PuICAvd6nHzAN+LYI4hEpP99fPm2c3Wn9LLPs69iEL62aGWL0kpxzzGSY1Fx/Laq0UvWIA4W6swhwkLupVVfVgMPkygd290vXFx3Cn36Jy1IS4+Sww79gk15JiJjhn7+Idtux2k4fCjVQ2oHf8sw2uJeQPWwBokLYclRgGPFzNU2t7EJhGFRi6NjbSXl3QbP3NjUuZzKs90m87i9Y5DGs3GPyC2ukXuy4cG0lRdwKLwiCTtEdJEdMeU752/WDFbbWxftv76//w+eiI6YsZi4i5GYkUCqlgyWI+P3NdXhFTqgSX/9NApaSYlQPHqLeQHrLBxqE3C/NHAKKW2xqlhMrMmzo5rNx4pcJ52aIip/1uWNcxU8thCLY8Yi6NmmxjU4Kq4A6RVTD2tdKMmV62kArU3HOoZPb628DRVZIiJpJ9/vD6QUqAXbHwujbD2MaDq3rYFE6MdfZTHmrI0etxJkXKZL/5NgHrgjLdf0twxVYT9kDhcdxJiqmnNZnSnWZB9Ajv2C8eChEiRnE7EBDBH4PW2mLYROqwD1Av/c1jEBuQ0znPJf2x/yUxbWacvyVt1nQJezXgLbvXczjSCLzK/9RBrLTqv0bV0nFHIbvVmPs6IBpYDyBfVxN2T1iXSzMxBqHIzsTghDCQ8NEAJav6YOt3cpID2zenz2vq7gRyBRJbTzxS5FzRS7fTea47AYhMBQm6XlQVkrkHmo5Fu+FBRBir9BW0S/CBdu9vzlAJ0SeT6/qTZjM5w59Vbv4Khm+ADowd07o3vuW3E5K1JacpY7JmgTlgEJUVE8LT+OL1PZC0TwFvE2dLCMrICgtWd/jmZEfbiqLoAQIjKw/m7v7xQiTiHg7mb/QSsHe5HJgFdeFnm4NH16JCZU0vMbdrZZCDpqzACITvzlr0a0QCijvrPNNsheqKmk/fcvphxJd1/DEnrhA8I+LHAOyrQvAx83cdnZ1wmk8GeaWtgNoRJpO+Ww7J7KxkchJ5G0/4x3GftDGUWhA7Nu8NuEaMUu8HTa9N45BBEt9Fnh2fcebLhnURb36yIGvS+V+At5xpMIvqZ3HkmlJifh9wiufZz/PnM9umVPnQOJXq2oAbK8daueRcEfFwmwRmfB7D/Tq47vRVnQy3XJ0/elIEPymN0qOaC/UK3wy9UpQoLL9MP8MQUPwOMeHhkplBNzaY712NipdS8PbrfUZL0pKlbCrDhjzXTTCYmVOnRUldZSK3Kw6xVWh1OkcGwQAsb7IcpqKQvh+Otn5Upr/8IeX8RQDUdDajf+bfFozA== X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-Network-Message-Id: e26bf1c3-f8f9-4ba9-d981-08dbf82508d1 X-MS-Exchange-CrossTenant-AuthSource: AM0PR04MB6452.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 08 Dec 2023 19:36:55.0700 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: BuMe3bFP4FxfRgbaqYRs1Fpt+8n/6ikHlnj9NRePf54WzXRf/FVOF6he8Ya30f9YTYHMVSyT2JKPdiwFTQOpEw== X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV1PR04MB9213 X-Patchwork-Delegate: kuba@kernel.org There are people who are trying to push the ds->user_mii_bus feature past its sell-by date. I think part of the problem is the fact that the documentation presents it as this great functionality. Adapt it to 2023, where we have phy-handle to render it useless, at least with OF. Signed-off-by: Vladimir Oltean Reviewed-by: Linus Walleij Reviewed-by: Florian Fainelli Reviewed-by: Linus Walleij Reviewed-by: Alvin Šipraga --- Documentation/networking/dsa/dsa.rst | 36 ++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index 676c92136a0e..2cd91358421e 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -397,19 +397,41 @@ perspective:: User MDIO bus ------------- -In order to be able to read to/from a switch PHY built into it, DSA creates an -user MDIO bus which allows a specific switch driver to divert and intercept -MDIO reads/writes towards specific PHY addresses. In most MDIO-connected -switches, these functions would utilize direct or indirect PHY addressing mode -to return standard MII registers from the switch builtin PHYs, allowing the PHY -library and/or to return link status, link partner pages, auto-negotiation -results, etc. +The framework creates an MDIO bus for user ports (``ds->user_mii_bus``) when +both methods ``ds->ops->phy_read()`` and ``ds->ops->phy_write()`` are present. +However, this pointer may also be populated by the switch driver during the +``ds->ops->setup()`` method, with an MDIO bus managed by the driver. + +Its role is to permit user ports to connect to a PHY (usually internal) when +the more general ``phy-handle`` property is unavailable (either because the +MDIO bus is missing from the OF description, or because probing uses +``platform_data``). + +In most MDIO-connected switches, these functions would utilize direct or +indirect PHY addressing mode to return standard MII registers from the switch +builtin PHYs, allowing the PHY library and/or to return link status, link +partner pages, auto-negotiation results, etc. For Ethernet switches which have both external and internal MDIO buses, the user MII bus can be utilized to mux/demux MDIO reads and writes towards either internal or external MDIO devices this switch might be connected to: internal PHYs, external PHYs, or even external switches. +When using OF, the ``ds->user_mii_bus`` can be seen as a legacy feature, rather +than core functionality. Since 2014, the DSA OF bindings support the +``phy-handle`` property, which is a universal mechanism to reference a PHY, +be it internal or external. + +New switch drivers are encouraged to require the more universal ``phy-handle`` +property even for user ports with internal PHYs. This allows device trees to +interoperate with simpler variants of the drivers such as those from U-Boot, +which do not have the (redundant) fallback logic for ``ds->user_mii_bus``. + +The only use case for ``ds->user_mii_bus`` in new drivers would be for probing +on non-OF through ``platform_data``. In the distant future where this will be +possible through software nodes, there will be no need for ``ds->user_mii_bus`` +in new drivers at all. + Data structures --------------- From patchwork Fri Dec 8 19:35:18 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Vladimir Oltean X-Patchwork-Id: 13485813 X-Patchwork-Delegate: kuba@kernel.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=nxp.com header.i=@nxp.com header.b="Mqc9pjoL" Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05on2045.outbound.protection.outlook.com [40.107.21.45]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3E6721712 for ; Fri, 8 Dec 2023 11:37:00 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=dd4CMtnKm/a5zOsHNy2pgcNQZQ+enMFiBh0xsN6L2W4cIEJghf41LfqE5ASo8oPwM29utad01W1zcDwFjfgPIHnlTtZ1550rBjUOWg2UJPFzaFEHv05wi4XczBNpc9xS3TWgjlW8MpmqETeITmpTQtSugzMu0IaLRFer7+5qP23WmfYpOnQf0S4sWMae4j6FCPiio2K4Ze1hs0D6I3l2o6Oe2Ad/1bJkXl37vv2jfIh80JNxh/w3K7uuIr6p0+hbx9BhlLZQQqXYycwoJeBsq+F1jWiz61IVmHdt323TNviqMbuoBNC41q6Yqt2nszvP8tI2XXyFFM7fAe3pGRz73Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=LQcGMvpZiqBNTz/bJM6WqARp5rVSYM3EiQg6T5fIsx4=; b=IKNZYhe44IsFPz+yAWAFV433eqLg191KFiafCX06RQz1f8SLTBYQTPAjnjcT60NL7GEd2dfUkvix9d5i/m5sL0bUd5Rv+75yVvnpIjFBxmpyw3Is9f6Ig6caRexOjLRMuoFfDyQoD2/WB+gOFoSsIUKg1lftuESMmyWhmVy+DA1+yG5NhLoQ7Wy60xWdukljcPjKZ/P841z+bxmTY9ygoaqoQ+Xk9I3e/GS+TiaO7Ji6I/sH4K69/djta+ROtKWa7Gtp8xxGfTA8FJm2Bod2mvMRzQ/DTfblbrz2TsrPNz5AgZiOz8N3YacloGxAecMnwAl6GO8Cjk2RdOf6gu51nA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nxp.com; dmarc=pass action=none header.from=nxp.com; dkim=pass header.d=nxp.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=LQcGMvpZiqBNTz/bJM6WqARp5rVSYM3EiQg6T5fIsx4=; b=Mqc9pjoLlXvTGz55TuLOgYrlDdd0TWXeLaHbelUumnPKq8iMRE4lp2+WOhewbA3/Yhy2GEqhXAIps4hFEAhGyYoICN2S+DEukHK772tlu0IgtHZoySIm1ZlhtXnbjAHdvHsrwlZ6u3h8+VbdmqP4w/BJGMCvVFLytH0TbkRXb1o= Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=nxp.com; Received: from AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) by GV1PR04MB9213.eurprd04.prod.outlook.com (2603:10a6:150:28::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7068.28; Fri, 8 Dec 2023 19:36:56 +0000 Received: from AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4]) by AM0PR04MB6452.eurprd04.prod.outlook.com ([fe80::dd33:f07:7cfd:afa4%7]) with mapi id 15.20.7068.027; Fri, 8 Dec 2023 19:36:56 +0000 From: Vladimir Oltean To: netdev@vger.kernel.org Cc: "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Andrew Lunn , Florian Fainelli , Luiz Angelo Daros de Luca , =?utf-8?q?Alvin_=C5=A0iprag?= =?utf-8?q?a?= , Madhuri Sripada , Marcin Wojtas , Linus Walleij , Tobias Waldekranz , Arun Ramadoss , "Russell King (Oracle)" , Jonathan Corbet Subject: [PATCH net 4/4] docs: net: dsa: replace TODO section with info about history and devel ideas Date: Fri, 8 Dec 2023 21:35:18 +0200 Message-Id: <20231208193518.2018114-5-vladimir.oltean@nxp.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231208193518.2018114-1-vladimir.oltean@nxp.com> References: <20231208193518.2018114-1-vladimir.oltean@nxp.com> X-ClientProxiedBy: FR4P281CA0101.DEUP281.PROD.OUTLOOK.COM (2603:10a6:d10:cb::16) To AM0PR04MB6452.eurprd04.prod.outlook.com (2603:10a6:208:16d::21) Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: AM0PR04MB6452:EE_|GV1PR04MB9213:EE_ X-MS-Office365-Filtering-Correlation-Id: 0b0112c5-f298-4f67-1ebb-08dbf82509b9 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: rtrfxTZdTzwAWEx8IE4DiZUXa1VcAR8Hw2Wpfg6P+3d0TkiUHa18JlAuVoZPg7L17qb6H9rMh9/+FKequ+A1Hmw5Rb8IdDkHQxHR5Oso1xn54RBDlYDB++xLczTxxJ1qdZPzeviWZRcBCE0uKx+4aLJQxwhB4gysVWHEyosGCzA7XvDc1f12cCMGUYArKF7D/KtxcNvvq2hBWhosFfm54fjXyQ4jBQ0fWMth5j+pql3bfEtVRLlOAXJMLYFEgcRurOQi1t4VL8FIcucDH1H2LmZvyoxAeBWM2f1uUdALkjhZAHHNasfuWHa+AEVvns0P8GFgZCl2KNeoVkbQ4ybFK65uZnpyOurn/aKSQvgj92thazADZlSdnEPkjBUh9i+zBBmg6Lkp1mn9bo2ahw/GRsp5t4n+Fq9Si4Es8h8a/wOWDq5s0+txhDAJ2m+X7TIMBMrzDo2dNqpMR4Jt1W2u+7P6vkifAwpmUtcYXZMdINlaz+Z+rqc534SIzc4ajfQTcanQIFd2Nyr79lYmKBcILof4Siebpqqh+cQxBqbR3W5MX/u9nVRNNSrrcFBDMSu96Fb3oKsXaRi8GKhLnfakjGySQZ2HMF0Bav7zo7w80jX+pTW0HIoP06wM8RWTRnOKUD9goHbXchzJr3eF4mTdPhZ5RS3swmiKo2s9uQflyAE= X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:AM0PR04MB6452.eurprd04.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230031)(39860400002)(136003)(396003)(376002)(346002)(366004)(230273577357003)(230173577357003)(230922051799003)(186009)(64100799003)(451199024)(1800799012)(38350700005)(66899024)(8676002)(6916009)(66476007)(66556008)(66946007)(54906003)(86362001)(36756003)(38100700002)(83380400001)(1076003)(8936002)(2616005)(26005)(52116002)(6512007)(6506007)(7416002)(2906002)(30864003)(316002)(478600001)(6486002)(6666004)(5660300002)(41300700001)(4326008)(44832011);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: nOX9e51ststhuo7z2+DCrVUIRL2UWMKkhyphkuNpfiokCg4Vc3nhQqmVBVgLZyEl3DSnpMQvnokNMfrq1+hvm7rlZzPokWWbMxUpuh7fueHxOLj22+U8SQe9ces6CxpMchaTElvH4kwaXk71k7ZNsirIqQcHVaHnm7IDLrafxzSlcA2c68JDpc74GekUIfPUqlLJ6Mws2H3kgK9XQqMuMAO4IHc0zN0sZf3p1pO66/dmbtR0NIIgL7VrlD/dWG5suWDeIVVqgEwRW+OzlCcy6GT06rqdO7oZRx/J+3h99DKwzHA9QBVB8TiwYL+Cq4B2qH0mz2x/XADEm7KFRjPOMcL7bxO+HnRDS+eF1q+FtqMdGh8swQKmWPaC6Br+iPyCVv9R/zZU6CcL20wEMCOfwLutyLFa9APOFrUs6poOG388S/UOfABAD7M2Ej5FFrJAY1U+HqBaKZv12oftLIdI5MPmYhxk2W4Sv5edSTaBAp3UUQUZTwSKxBUyHnP9MMcyztTE002TFZAx97tz2JbKTo+CHrMB5EpJqb2DgdmxYOV4tJwfR6BXyK7EF2Ed5Sj2xeZXwseAqY47oko9oASKWlMh1dv0AxtkVrACDRIrbftYeJ/CUJUNg3haNb5NpscHBzGLMXsZrqCpHGLxzLslX0vh4ZZwzWnyweTTQr+BEMX3tqVwpa8zeiYg3fjCo+mLtf5gNFXSMSON9fBGqdIIEg7KbhjzmNO/9eGlbtX5G1V8n4cvpW0J0p3oJRDnEEsk/ohu4l/wWNKdjDWeyDdmfsBV7oaybikOMbEKa/Hoj/cOm6WzCot5P8J/B3qOEmyPan74nBTtHc065niXA1RZl1rEYsCNxDMOh2yPZ/pTrcSbMZAcJ3YvjI9ZdoCy4s09o2f5+5Oz4RnaqR1SdVrLnHNGQo7aG588NXjaovf9VjujgWmqw7gDA8UbzYOcQhQzmOoHlam2mmff9t1s5a/2FY+ENVt0vB1EwCFRQ5CKnfen5S+/x4BjYpsyDHIoe+5DyLsW6Hsx8OOK722AK5lgu3AzHfm/wI+RinkQgg/CDfAJGN5WKRi1aHwT/tjPOBHCO9WHfAiaC6tEDxuUDDElJXHcf5eTn0CkbS/ZDhgcnSVYmChx+gJkmiywlVo5d1W/CNVz4TbIoqpsPvRA53ufYsS0DHgj2MTlDaOtHyvw8dFLAFezP9iPywAywDelZurGg+FOwXl982LQd2O/OP+NdVaFhCx+jcGz2ZAB5OaBQopH/b7GvyrKIQW6ROBs+IpU71UXRgE+m+W4ItMPuptD4bISy7VlpVCZc6H9An/FrzNcVMiithhw08dQgv0cjsf/eeit6EXsXqW7WebIiciEXRxTYlKIo3eIhQZHYD1GSPxsdDeHuuQ1/AJZl5zY6ts4FZifUVKCe0tJ5+CC4bjaeYVst4ihwJEOo4jlHmflcST6t362rDo4de9MdSA3Mk9uPLw24LxJA4KlDHWDgsgRA1Pzk8zGEPL5607NT1+zhcM9T+bRU9l0ULb1oUWUvFOQ+0olh5xbV9jyXJ0nZ9KcinrNDbthKJYSS/y0RK7TUlLzqzr7SCkr7RdPRUcGYwRGh+ixDQ8yoShF5BArQCBnww== X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-Network-Message-Id: 0b0112c5-f298-4f67-1ebb-08dbf82509b9 X-MS-Exchange-CrossTenant-AuthSource: AM0PR04MB6452.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 08 Dec 2023 19:36:56.5309 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: CpFOzOQRk3kFbYNoQ+gfg/XV49OD+bP2/dHkot4tGL2f64gAmnreAA8mY2ht3/AzBP9Qdw4WSQlMRyobWs7sdA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV1PR04MB9213 X-Patchwork-Delegate: kuba@kernel.org It was a bit unclear to me what the TODO is about and what is even actionable about it. I had a discussion with Florian about it at NetConf 2023, and it seems that it's about the amount of boilerplate code that exists in switchdev drivers, and how that could be maybe made common with DSA, through something like another library. I think we are seeing a lot of people who are looking at DSA now, and there is a lot of misunderstanding about why things are the way they are, and which are the changes that would benefit the subsystem, compared to the changes that go against DSA's past development trend. I think what is missing is the context, which is admittedly a bit hard to grasp considering there are 15 years of development. Based on the git log and on the discussions where I participated, I tried to cobble up a section about DSA's history. Here and there, I've mentioned the limitations that I am aware of, and some possible ways forward. I'm also personally surprised by the amount of change in DSA over the years, and I hope that putting things into perspective will also encourage others to not think that it's set in stone the way it is now. Signed-off-by: Vladimir Oltean Reviewed-by: Linus Walleij --- Documentation/networking/dsa/dsa.rst | 186 +++++++++++++++++++++++++-- 1 file changed, 176 insertions(+), 10 deletions(-) diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index 2cd91358421e..305bb471fc02 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -1200,14 +1200,180 @@ methods must be implemented: - ``port_hsr_leave``: function invoked when a given switch port leaves a DANP/DANH and returns to normal operation as a standalone port. -TODO -==== - -Making SWITCHDEV and DSA converge towards an unified codebase -------------------------------------------------------------- +History and development directions +================================== -SWITCHDEV properly takes care of abstracting the networking stack with offload -capable hardware, but does not enforce a strict switch device driver model. On -the other DSA enforces a fairly strict device driver model, and deals with most -of the switch specific. At some point we should envision a merger between these -two subsystems and get the best of both worlds. +This section gives some background context to the developers who are eager to +make changes to the DSA core (``net/dsa/`` excepting ``tag_*.c`` files). + +Initially (2008), the DSA core was a platform driver for a platform device +representing the switch tree. Support for hardware switch chips lived in +separate modules, which were required to call the ``register_switch_driver()`` +method. The tree platform device was instantiated through ``platform_data``. + +Later (2013), the DSA core gained support for OF bindings. The initial bindings +(now no longer supported) expected a compatible string of "marvell,dsa" or +"brcm,bcm7445-switch-v4.0" for the tree, and, like the implementation of the +DSA core, also expected that all switches in the tree are MDIO devices on an +``mii_bus``. The initial bindings and core driver implementation first assumed +that all switches in the tree are connected to the same MDIO bus, then in 2015, +they were augmented such that each switch may be on its own MDIO bus. + +The early DSA core was more concerned with using switches as port multiplexers +and with managing auxiliary functionality like temperature sensors +(``CONFIG_NET_DSA_HWMON``) rather than with production-ready features. +Bridging and bonding were handled in software. Support for hardware-accelerated +bridging, by means of integrating with the ``switchdev`` framework, was added +in 2015. + +In mid 2016, the second (and current) device tree binding for DSA was +introduced. Here, individual switches are represented as devices in the Linux +device model sense, on arbitrary buses, not just MDIO. The limitation of being +able to describe a single CPU port was lifted (the driver support for multiple +CPU ports came much later, in 2022). During this time, DSA stopped playing the +role of a device model for switches, and ``register_switch_driver()`` was +replaced with ``dsa_register_switch()``, the modern mechanism through which +arbitrary devices may use DSA as a framework exclusively for integrating +Ethernet switch IP blocks with the network stack. + +With the conversion to the second device tree binding, DSA's support for +``platform_data`` (used in non-OF scenarios) was also changed to align. With +the DSA tree no longer being a platform device, the ``platform_data`` structure +moved to individual switch devices. + +Support for the initial device tree binding was subsequently removed in 2019. + +Probing through ``platform_data`` remains limited in functionality. The +``ds->dev->of_node`` and ``dp->dn`` pointers are NULL, and the OF API calls +made by drivers for discovering more complex setups fall back to the implicit +handling. There is no way to describe multi-chip trees, or switches with +multiple CPU ports. It is always assumed that shared ports are configured by +the driver to the maximum supported link speed (they do not use phylink). +User ports cannot connect to arbitrary PHYs, but are limited to +``ds->user_mii_bus``. + +Many switch drivers introduced since after DSA's second OF binding were not +designed to support probing through ``platform_data``. Most notably, +``device_get_match_data()`` and ``of_device_get_match_data()`` return NULL with +``platform_data``, so generally, drivers which do not have alternative +mechanisms for this do not support ``platform_data``. + +Extending the ``platform_data`` support implies adding more separate code. +An alternative worth exploring is growing DSA towards the ``fwnode`` API. +However, not the entire OF binding should be generalized to ``fwnode``. +The current bindings must be examined with a critical eye, and the properties +which are no longer considered good practice (like ``label``, because ``udev`` +offers this functionality) should first be deprecated in OF, and not migrated +to ``fwnode``. + +With ``fwnode`` support in the DSA framework, the ``fwnode_create_software_node()`` +API could be used as an alternative to ``platform_data``, to allow describing +and probing switches on non-OF. + +DSA is used to control very complex switching chips. Some devices have a +microprocessor, and in some cases, this microprocessor can run a variant of the +Linux kernel. Sometimes, the switch packet I/O procedure of the internal +microprocessor is different from the packet I/O procedure for an external host. +The internal processor may have access to switch queues, while the external +processor may require DSA tags. Other times, the microprocessor may also be +connected to the switch in a DSA fashion (using an internal MAC to MAC +connection). + +Since DSA is only concerned with switches where the packet I/O is handled +by an intermediate conduit driver, this leads to the situation where it is +recommended to have two drivers for the same switch hardware. When the queues +are accessed directly, a separate non-DSA driver should be used, with its own +skeleton which is integrated with ``switchdev`` on its own. + +In 2019, a DSA driver was added for the ``ocelot`` switch, which is a thin +front-end over a hardware library that is also common with a ``switchdev`` +driver. While this design is encouraged for other similar cases, code +duplication among multiple front-ends is a concern, so it may be desirable to +extract some of DSA's core functionality into a reusable library for Ethernet +switches. This could offer a driver-facing API similar to ``dsa_switch_ops``, +but the aspects relating to cross-chip management, to DSA tags and to the +conduit interface would remain DSA-specific. + +Traditionally, DSA switch drivers for discrete chips own the entire +``spi_device``, ``i2c_client``, ``mdio_device`` etc. When the chip is complex +and has multiple embedded peripherals (IRQ controller, GPIO controller, MDIO +controller, LED controller, sensors), the handling of these peripherals is +currently monolithic within the same device driver that also calls +``dsa_register_switch()``. + +But an internal microprocessor may have a very different view of the switch +address space, and may have discrete Linux drivers for each peripheral. +In 2023, the ``ocelot_ext`` driver was added, which deviated from the +traditional DSA driver architecture. Rather than probing on the entire +``spi_device``, it created a multi-function device (MFD) top-level driver for +it (associated with the SoC at large), and the switching IP is only one of the +children of the MFD (it is a platform device with regmaps provided by its +parent). The drivers for each peripheral in this switch SoC are the same when +controlled over SPI and when controlled by the internal processor. + +Authors of new switch drivers that use DSA are encouraged to have a wider view +of the peripherals on the chip that they are controlling, and to use the MFD +model to separate the components whenever possible. The general direction for +the DSA core is to shrink in size and to focus only on the Ethernet switching +IP and its ports. ``CONFIG_NET_DSA_HWMON`` was removed in 2017. Adding new +methods to ``struct dsa_switch_ops`` which are outside of DSA's core focus on +Ethernet is strongly discouraged. + +DSA's support for multi-chip trees also has limitations. After converting from +the first to the second OF binding, the switch tree stopped being a platform +device, and its probing became implicit, and distributed among its constituent +switch devices. There is currently a synchronization point in +``dsa_tree_setup_routing_table()``, through which the tree setup is performed +only once, when there is more than one switch in the tree. The first N-1 +switches will end their probing early, and the last switch will configure the +entire tree, and thus all the other switches, in its ``dsa_register_switch()`` +calling context. + +Furthermore, the synchronization point works because each switch is able to +determine, in a distributed manner, that the routing table is not complete, aka +that there is at least one switch which has not probed. This is only possible +because the ``link`` properties in the device tree describe the connections to +all other cascade ports in the tree, not just to the directly connected cascade +port. If only the latter were described, it could happen that a switch waits +for its direct neighbors to probe before setting up the tree, but not +necessarily for all switches in the tree (therefore, it sets up the tree too +early). + +With more than 3 switches in a tree, it becomes a difficult task to write +correct device trees which are not missing any link to the other cascade ports +in the tree. The routing table, based on which ``dsa_routing_port()`` works, is +directly taken from the device tree, although it could be computed through BFS +instead. This means that the device tree writer needs to specify more than just +the hardware description (represented by the direct cascade port connections). + +Simplifying the device tree bindings to require a single ``link`` phandle +cannot be done without rethinking the distributed probing scheme. One idea is +to reinstate the switch tree as a platform device, but this time created +dynamically by ``dsa_register_switch()`` if the switch's tree ID is not already +present in the system. The switch tree driver walks the device tree hop by hop, +following the ``link`` references, to discover all the other switches, and to +construct the full routing table. It then uses the component API to register +itself as an aggregate driver, with each of the discovered switches as a +component. When ``dsa_register_switch()`` completes for all component switches, +the tree probing continues and calls ``dsa_tree_setup()``. + +The cross-chip management layer (``net/dsa/switch.c``) can also be improved. +Currently ``struct dsa_switch_tree`` holds a list of ports rather than a list +of switches, and thus, calling one function for each switch in a tree is hard. +DSA currently uses one notifier chain per tree as a workaround for that, with +each switch registered as a listener (``dsa_switch_event()``). + +It is considered bad practice to use notifiers when the emitter and the +listener are known to each other, instead of a plain function call. Also, error +handling with notifiers is not robust. When one switch fails mid-operation, +there is no rollback to the previous state for switches which already completed +the operation successfully. + +To untangle this situation and improve the reliability of the cross-chip +management layer, it is necessary to split the DSA operations into ones which +can fail, and ones which cannot fail. For example, ``port_fdb_add()`` can fail, +whereas ``port_fdb_del()`` cannot. Then, cross-chip operations can take a +fallible function to make forward progress, and an infallible function for +rollback. However, it is unclear what to do in the case of ``change_mtu()``. +It is hard to classify this operation as either fallible or infallible. It is +also unclear how to deal with I/O access errors on the switch's management bus.