Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Vladimir Oltean <vladimir.oltean@nxp.com>
To:     netdev@vger.kernel.org
Cc:     linux-kernel@vger.kernel.org,
        "David S. Miller" <davem@davemloft.net>,
        Eric Dumazet <edumazet@google.com>,
        Jakub Kicinski <kuba@kernel.org>,
        Paolo Abeni <pabeni@redhat.com>,
        Michal Kubecek <mkubecek@suse.cz>,
        Claudiu Manoil <claudiu.manoil@nxp.com>,
        Vinicius Costa Gomes <vinicius.gomes@intel.com>,
        Xiaoliang Yang <xiaoliang.yang_1@nxp.com>,
        Kurt Kanzenbach <kurt@linutronix.de>,
        Rui Sousa <rui.sousa@nxp.com>,
        Ferenc Fejes <ferenc.fejes@ericsson.com>,
        Pranavi Somisetty <pranavi.somisetty@amd.com>,
        Harini Katakam <harini.katakam@amd.com>,
        Colin Foster <colin.foster@in-advantage.com>,
        UNGLinuxDriver@microchip.com,
        Alexandre Belloni <alexandre.belloni@bootlin.com>,
        Andrew Lunn <andrew@lunn.ch>,
        Florian Fainelli <f.fainelli@gmail.com>
Subject: [PATCH v2 net-next 03/12] docs: ethtool-netlink: document interface for MAC Merge layer
Date:   Wed, 11 Jan 2023 18:16:57 +0200
Message-Id: <20230111161706.1465242-4-vladimir.oltean@nxp.com>
In-Reply-To: <20230111161706.1465242-1-vladimir.oltean@nxp.com>
References: <20230111161706.1465242-1-vladimir.oltean@nxp.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?B7TbzZXX8smKVmcg0rQzADLtIuIITpUKKZLeNcrswxI9+BON4F/0Qdxvh+RZ?=
 =?us-ascii?Q?lO4rRT5iCNIVWyNrqgK4AlDs43OqIPEZjdsPCrNSwJBRY3SvcgEBKtCTWrLP?=
 =?us-ascii?Q?U4aP20oUltRoXwxxgj+GezgK9ZKWKRWscfxODKlaitb6y3GJEborSAvXrlwR?=
 =?us-ascii?Q?7zBj7vNz8Rw11tGaeHsS2LCqsmQ3eOx8zhppVPalnVnAd91eLyhex+eMxT7K?=
 =?us-ascii?Q?WC03QaiBHa2D/kjK/+bE2WrMunWzcueGDqFoRhrSa4CxEnJ26qvhdNjXccSG?=
 =?us-ascii?Q?RxfLMSz4HKlyKL7nb5LgZXwl3qFn997PpJFhjIgT1u7iQfbvjf/Pyy7CekBF?=
 =?us-ascii?Q?kqPZ8+FBpH3V/Hahci9ONywnQYKCBOLaoMxAudARTqQWQBBYnn/U9A9Z9m1z?=
 =?us-ascii?Q?TVzkuMyVgXuySf+05mIPgIAXKuQ2CqlsDOwBdAg8gEhFrSeJVMVvvxWKHTaX?=
 =?us-ascii?Q?sZqsstVRdFKElVnCDUEwaDl++AG8gMfpHWe1iqO5OCUkiZ3WEr0OilKtBx69?=
 =?us-ascii?Q?wx5vgzLnVTALCh2g7P4Dk99MrbaAnN9TIKPAYH5sRWLO1nvQFpgduukLG7iR?=
 =?us-ascii?Q?9ji4VP/5QnvNc0wdaKoJ5bmf+S5HselJpkVXoIZ4dMJ1ZjUaGTq2nfXWBubW?=
 =?us-ascii?Q?YRtOMn0+U6qRPvBKju1YApi9W6AxrdnadFH2Gk/SAezTVD5VLurHBmF0+V4C?=
 =?us-ascii?Q?vsqKsZKV95uVkRLpfJB7IqVBSHRPl/D+gtKKDeRweprx3lHZcgH43Ydy8hVd?=
 =?us-ascii?Q?DzTavSjjuE5wDzbSEA3T0JBDAN6d8o4k6xuUF6M0y6Qwz0OoyskF1wDpNB2L?=
 =?us-ascii?Q?H48bs8W47mOp1PK3ql0JlCbKaJWVhjn2+XBiY82GKbR5zlXpK41umRKSuBo0?=
 =?us-ascii?Q?40WhLJBpm+RT0YwG9cxoIx+wbaPyttIGoDGRCfS0732d7vbb9NbjMjHGpFzp?=
 =?us-ascii?Q?BNEFXjmfPlGRNh6yzkLw0g+4nBwGzZDNaDkAuUXQ7nxcSSrrcYXS0HgiT1oB?=
 =?us-ascii?Q?t1H1YtjiAvPT73LI3TJsaex355uwSOAn07wuJAHASEWQZTa7roPdQ7CzTRlD?=
 =?us-ascii?Q?4M9INc9Xw/9hSc18UPCITasKmC7YLw3Roj/zyykkedwqCOn8s0gTFtTzS7PS?=
 =?us-ascii?Q?nKUSj/XlmmRp7sgKEB2OHa2HacWW4O2BBrQ3o4VXuDk37r4x7DWACA0mqA52?=
 =?us-ascii?Q?Zl2Bw9YtGicWPHtsFFG5uUY13SMaZE489rp+dod/8ziZtV/A6pXoXhZcsnZc?=
 =?us-ascii?Q?w7s6KzUj+uIOjCM1cT0SijM8SeWKNfj0m4os1TqHcmQqnya/I8qrnYSfAHJz?=
 =?us-ascii?Q?ZIWgiRhaUGjX2oO3RGvQvDikL6F8K3ISOLTn+pxMftH/idpxnIvR+r+2dE8s?=
 =?us-ascii?Q?ob02Bn3oMQoJj3d6lruHJJg0RTEILg/nEAXuEk76sloRpfRJgjGjZHa33vpo?=
 =?us-ascii?Q?sX5PjHa0GKhoLS+7VddoVaHrKpNBZSOQxBKqxd/AuRY62VnoU0TrSIPFvegB?=
 =?us-ascii?Q?xg7Pg5RoTscg71svbikBIZ5wFBHKD3TY/xWzZyPKTdWD3YlITgkAKQ4y9Vul?=
 =?us-ascii?Q?3iW/8YClf7whG1IG26S+bepT/+P0gR1L72iV2hzuZ/FgRD7jqorNq9j7jQaK?=
 =?us-ascii?Q?4w=3D=3D?=
X-OriginatorOrg: nxp.com
X-MS-Exchange-CrossTenant-Network-Message-Id: dee1bc98-0e1a-42d5-913a-08daf3ef50fa
X-MS-Exchange-CrossTenant-AuthSource: VI1PR04MB5136.eurprd04.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 11 Jan 2023 16:17:21.0021
 (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: b4VAPOkfEwACYs7v+jmnzhtSU0HB345gJ3BBgASMOvvkwHBWEqRGZaunYKuBiap6MOxcRiDw6wfE4CDwHTwoTQ==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB9PR04MB8462
X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE,
        RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Show details about the structures passed back and forth related to MAC
Merge layer configuration, state and statistics. The rendered htmldocs
will be much more verbose due to the kerneldoc references.

Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
---
v1->v2: patch is new

 Documentation/networking/ethtool-netlink.rst | 103 +++++++++++++++++++
 Documentation/networking/statistics.rst      |   1 +
 2 files changed, 104 insertions(+)

diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst
index f10f8eb44255..490c2280ce4f 100644
--- a/Documentation/networking/ethtool-netlink.rst
+++ b/Documentation/networking/ethtool-netlink.rst
@@ -223,6 +223,8 @@ Userspace to kernel:
   ``ETHTOOL_MSG_PSE_SET``               set PSE parameters
   ``ETHTOOL_MSG_PSE_GET``               get PSE parameters
   ``ETHTOOL_MSG_RSS_GET``               get RSS settings
+  ``ETHTOOL_MSG_MM_GET``                get MAC merge layer state
+  ``ETHTOOL_MSG_MM_SET``                set MAC merge layer parameters
   ===================================== =================================
 
 Kernel to userspace:
@@ -265,6 +267,7 @@ Kernel to userspace:
   ``ETHTOOL_MSG_MODULE_GET_REPLY``         transceiver module parameters
   ``ETHTOOL_MSG_PSE_GET_REPLY``            PSE parameters
   ``ETHTOOL_MSG_RSS_GET_REPLY``            RSS settings
+  ``ETHTOOL_MSG_MM_GET_REPLY``             MAC merge layer status
   ======================================== =================================
 
 ``GET`` requests are sent by userspace applications to retrieve device
@@ -1716,6 +1719,104 @@ being used. Current supported options are toeplitz, xor or crc32.
 ETHTOOL_A_RSS_INDIR attribute returns RSS indrection table where each byte
 indicates queue number.
 
+MM_GET
+======
+
+Retrieve 802.3 MAC Merge parameters.
+
+Request contents:
+
+  ====================================  ======  ==========================
+  ``ETHTOOL_A_MM_HEADER``               nested  request header
+  ====================================  ======  ==========================
+
+Kernel response contents:
+
+  ================================  ======  ===================================
+  ``ETHTOOL_A_MM_HEADER``           Nested  request header
+
+  ``ETHTOOL_A_MM_SUPPORTED``        Bool    set if device supports the MM layer
+
+  ``ETHTOOL_A_MM_PMAC_ENABLED``     Bool    set if RX of preemptible and SMD-V
+                                            frames is enabled
+
+  ``ETHTOOL_A_MM_TX_ENABLED``       Bool    set if TX of preemptible frames is
+                                            administratively enabled (might be
+                                            inactive if verification failed)
+
+  ``ETHTOOL_A_MM_TX_ACTIVE``        Bool    set if TX of preemptible frames is
+                                            operationally enabled
+
+  ``ETHTOOL_A_MM_ADD_FRAG_SIZE``    U32     minimum size of transmitted
+                                            non-final fragments, in octets
+
+  ``ETHTOOL_A_MM_VERIFY_ENABLED``   Bool    set if TX of SMD-V frames is
+                                            administratively enabled (TX will
+                                            not take place when port is not up)
+
+  ``ETHTOOL_A_MM_VERIFY_STATUS``    U8      state of the Verify function
+
+  ``ETHTOOL_A_MM_VERIFY_TIME``      U32     delay between verification attempts
+
+  ``ETHTOOL_A_MM_MAX_VERIFY_TIME``  U32     maximum interval supported by
+                                            device
+
+  ``ETHTOOL_A_MM_STATS``            Nested  IEEE 802.3-2018 subclause 30.14.1
+                                            oMACMergeEntity statistics counters
+
+  ================================  ======  ===================================
+
+If ``ETHTOOL_A_MM_SUPPORTED`` is reported as false, the other netlink
+attributes will be absent.
+
+The attributes are populated by the device driver through the following
+structure:
+
+.. kernel-doc:: include/linux/ethtool.h
+    :identifiers: ethtool_mm_state
+
+The ``ETHTOOL_A_MM_VERIFY_STATUS`` will report one of the values from
+
+.. kernel-doc:: include/uapi/linux/ethtool.h
+    :identifiers: ethtool_mm_verify_status
+
+If ``ETHTOOL_A_MM_VERIFY_ENABLED`` was passed as false in the ``MM_SET``
+command, ``ETHTOOL_A_MM_VERIFY_STATUS`` will report either
+``ETHTOOL_MM_VERIFY_STATUS_INITIAL`` or ``ETHTOOL_MM_VERIFY_STATUS_DISABLED``,
+otherwise it should report one of the other states.
+
+It is recommended that drivers start with the pMAC disabled, and enable it upon
+user space request. It is also recommended that user space does not depend upon
+the default values from ``ETHTOOL_MSG_MM_GET`` requests.
+
+``ETHTOOL_A_MM_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in
+``ETHTOOL_A_HEADER_FLAGS``. The attribute will be empty if driver did not
+report any statistics. Drivers fill in the statistics in the following
+structure:
+
+.. kernel-doc:: include/linux/ethtool.h
+    :identifiers: ethtool_mm_stats
+
+MM_SET
+======
+
+Modifies the configuration of the 802.3 MAC Merge layer.
+
+Request contents:
+
+  ======================================  ======  ==========================
+  ``ETHTOOL_A_MM_VERIFY_TIME``            u32     see MM_GET description
+  ``ETHTOOL_A_MM_VERIFY_ENABLED``         bool    see MM_GET description
+  ``ETHTOOL_A_MM_TX_ENABLED``             bool    see MM_GET description
+  ``ETHTOOL_A_MM_PMAC_ENABLED``           bool    see MM_GET description
+  ``ETHTOOL_A_MM_ADD_FRAG_SIZE``          u32     see MM_GET description
+  ======================================  ======  ==========================
+
+The attributes are propagated to the driver through the following structure:
+
+.. kernel-doc:: include/linux/ethtool.h
+    :identifiers: ethtool_mm_cfg
+
 Request translation
 ===================
 
@@ -1817,4 +1918,6 @@ are netlink only.
   n/a                                 ``ETHTOOL_MSG_PHC_VCLOCKS_GET``
   n/a                                 ``ETHTOOL_MSG_MODULE_GET``
   n/a                                 ``ETHTOOL_MSG_MODULE_SET``
+  n/a                                 ``ETHTOOL_MSG_MM_GET``
+  n/a                                 ``ETHTOOL_MSG_MM_SET``
   =================================== =====================================
diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst
index c9aeb70dafa2..551b3cc29a41 100644
--- a/Documentation/networking/statistics.rst
+++ b/Documentation/networking/statistics.rst
@@ -171,6 +171,7 @@ statistics are supported in the following commands:
 
   - `ETHTOOL_MSG_PAUSE_GET`
   - `ETHTOOL_MSG_FEC_GET`
+  - `ETHTOOL_MSG_MM_GET`
 
 debugfs
 -------
-- 
2.34.1