diff options
Diffstat (limited to 'Documentation/networking/ethtool-netlink.rst')
| -rw-r--r-- | Documentation/networking/ethtool-netlink.rst | 272 |
1 files changed, 268 insertions, 4 deletions
diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index f10f8eb44255..e1bc6186d7ea 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -106,7 +106,7 @@ modifying a bitmap, the former changes the bit set in mask to values set in value and preserves the rest; the latter sets the bits set in the bitmap and clears the rest. -Compact form: nested (bitset) atrribute contents: +Compact form: nested (bitset) attribute contents: ============================ ====== ============================ ``ETHTOOL_A_BITSET_NOMASK`` flag no mask, only a list @@ -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 @@ -780,7 +783,7 @@ Kernel response contents: ``ETHTOOL_A_FEATURES_ACTIVE`` bitset diff old vs. new active ==================================== ====== ========================== -Request constains only one bitset which can be either value/mask pair (request +Request contains only one bitset which can be either value/mask pair (request to change specific feature bits and leave the rest) or only a value (request to set all features to specified set). @@ -871,6 +874,7 @@ Kernel response contents: ``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode + ``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode ==================================== ====== =========================== ``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` indicates whether the device is usable with @@ -880,8 +884,8 @@ separate buffers. The device configuration must make it possible to receive full memory pages of data, for example because MTU is high enough or through HW-GRO. -``ETHTOOL_A_RINGS_TX_PUSH`` flag is used to enable descriptor fast -path to send packets. In ordinary path, driver fills descriptors in DRAM and +``ETHTOOL_A_RINGS_[RX|TX]_PUSH`` flag is used to enable descriptor fast +path to send or receive packets. In ordinary path, driver fills descriptors in DRAM and notifies NIC hardware. In fast path, driver pushes descriptors to the device through MMIO writes, thus reducing the latency. However, enabling this feature may increase the CPU cost. Drivers may enforce additional per-packet @@ -903,6 +907,7 @@ Request contents: ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode + ``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode ==================================== ====== =========================== Kernel checks that requested ring sizes do not exceed limits reported by @@ -1004,6 +1009,9 @@ Kernel response contents: ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx =========================================== ====== ======================= Attributes are only included in reply if their value is not zero or the @@ -1022,6 +1030,17 @@ each packet event resets the timer. In this mode timer is used to force the interrupt if queue goes idle, while busy queues depend on the packet limit to trigger interrupts. +Tx aggregation consists of copying frames into a contiguous buffer so that they +can be submitted as a single IO operation. ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` +describes the maximum size in bytes for the submitted buffer. +``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` describes the maximum number of frames +that can be aggregated into a single buffer. +``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` describes the amount of time in usecs, +counted since the first packet arrival in an aggregated block, after which the +block should be sent. +This feature is mainly of interest for specific USB devices which does not cope +well with frequent small-sized URBs transmissions. + COALESCE_SET ============ @@ -1055,6 +1074,9 @@ Request contents: ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx =========================================== ====== ======================= Request is rejected if it attributes declared as unsupported by driver (i.e. @@ -1072,8 +1094,18 @@ Request contents: ===================================== ====== ========================== ``ETHTOOL_A_PAUSE_HEADER`` nested request header + ``ETHTOOL_A_PAUSE_STATS_SRC`` u32 source of statistics ===================================== ====== ========================== +``ETHTOOL_A_PAUSE_STATS_SRC`` is optional. It takes values from: + +.. kernel-doc:: include/uapi/linux/ethtool.h + :identifiers: ethtool_mac_stats_src + +If absent from the request, stats will be provided with +an ``ETHTOOL_A_PAUSE_STATS_SRC`` attribute in the response equal to +``ETHTOOL_MAC_STATS_SRC_AGGREGATE``. + Kernel response contents: ===================================== ====== ========================== @@ -1488,6 +1520,7 @@ Request contents: ======================================= ====== ========================== ``ETHTOOL_A_STATS_HEADER`` nested request header + ``ETHTOOL_A_STATS_SRC`` u32 source of statistics ``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats ======================================= ====== ========================== @@ -1496,6 +1529,8 @@ Kernel response contents: +-----------------------------------+--------+--------------------------------+ | ``ETHTOOL_A_STATS_HEADER`` | nested | reply header | +-----------------------------------+--------+--------------------------------+ + | ``ETHTOOL_A_STATS_SRC`` | u32 | source of statistics | + +-----------------------------------+--------+--------------------------------+ | ``ETHTOOL_A_STATS_GRP`` | nested | one or more group of stats | +-+---------------------------------+--------+--------------------------------+ | | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` | @@ -1557,6 +1592,11 @@ Low and high bounds are inclusive, for example: etherStatsPkts512to1023Octets 512 1023 ============================= ==== ==== +``ETHTOOL_A_STATS_SRC`` is optional. Similar to ``PAUSE_GET``, it takes values +from ``enum ethtool_mac_stats_src``. If absent from the request, stats will be +provided with an ``ETHTOOL_A_STATS_SRC`` attribute in the response equal to +``ETHTOOL_MAC_STATS_SRC_AGGREGATE``. + PHC_VCLOCKS_GET =============== @@ -1716,6 +1756,225 @@ 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. +PLCA_GET_CFG +============ + +Gets the IEEE 802.3cg-2019 Clause 148 Physical Layer Collision Avoidance +(PLCA) Reconciliation Sublayer (RS) attributes. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_PLCA_HEADER`` nested request header + ===================================== ====== ========================== + +Kernel response contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PLCA_HEADER`` nested reply header + ``ETHTOOL_A_PLCA_VERSION`` u16 Supported PLCA management + interface standard/version + ``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State + ``ETHTOOL_A_PLCA_NODE_ID`` u32 PLCA unique local node ID + ``ETHTOOL_A_PLCA_NODE_CNT`` u32 Number of PLCA nodes on the + network, including the + coordinator + ``ETHTOOL_A_PLCA_TO_TMR`` u32 Transmit Opportunity Timer + value in bit-times (BT) + ``ETHTOOL_A_PLCA_BURST_CNT`` u32 Number of additional packets + the node is allowed to send + within a single TO + ``ETHTOOL_A_PLCA_BURST_TMR`` u32 Time to wait for the MAC to + transmit a new frame before + terminating the burst + ====================================== ====== ============================= + +When set, the optional ``ETHTOOL_A_PLCA_VERSION`` attribute indicates which +standard and version the PLCA management interface complies to. When not set, +the interface is vendor-specific and (possibly) supplied by the driver. +The OPEN Alliance SIG specifies a standard register map for 10BASE-T1S PHYs +embedding the PLCA Reconcialiation Sublayer. See "10BASE-T1S PLCA Management +Registers" at https://www.opensig.org/about/specifications/. + +When set, the optional ``ETHTOOL_A_PLCA_ENABLED`` attribute indicates the +administrative state of the PLCA RS. When not set, the node operates in "plain" +CSMA/CD mode. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.1 +aPLCAAdminState / 30.16.1.2.1 acPLCAAdminControl. + +When set, the optional ``ETHTOOL_A_PLCA_NODE_ID`` attribute indicates the +configured local node ID of the PHY. This ID determines which transmit +opportunity (TO) is reserved for the node to transmit into. This option is +corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.4 aPLCALocalNodeID. The valid +range for this attribute is [0 .. 255] where 255 means "not configured". + +When set, the optional ``ETHTOOL_A_PLCA_NODE_CNT`` attribute indicates the +configured maximum number of PLCA nodes on the mixing-segment. This number +determines the total number of transmit opportunities generated during a +PLCA cycle. This attribute is relevant only for the PLCA coordinator, which is +the node with aPLCALocalNodeID set to 0. Follower nodes ignore this setting. +This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.3 +aPLCANodeCount. The valid range for this attribute is [1 .. 255]. + +When set, the optional ``ETHTOOL_A_PLCA_TO_TMR`` attribute indicates the +configured value of the transmit opportunity timer in bit-times. This value +must be set equal across all nodes sharing the medium for PLCA to work +correctly. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.5 +aPLCATransmitOpportunityTimer. The valid range for this attribute is +[0 .. 255]. + +When set, the optional ``ETHTOOL_A_PLCA_BURST_CNT`` attribute indicates the +configured number of extra packets that the node is allowed to send during a +single transmit opportunity. By default, this attribute is 0, meaning that +the node can only send a single frame per TO. When greater than 0, the PLCA RS +keeps the TO after any transmission, waiting for the MAC to send a new frame +for up to aPLCABurstTimer BTs. This can only happen a number of times per PLCA +cycle up to the value of this parameter. After that, the burst is over and the +normal counting of TOs resumes. This option is corresponding to +``IEEE 802.3cg-2019`` 30.16.1.1.6 aPLCAMaxBurstCount. The valid range for this +attribute is [0 .. 255]. + +When set, the optional ``ETHTOOL_A_PLCA_BURST_TMR`` attribute indicates how +many bit-times the PLCA RS waits for the MAC to initiate a new transmission +when aPLCAMaxBurstCount is greater than 0. If the MAC fails to send a new +frame within this time, the burst ends and the counting of TOs resumes. +Otherwise, the new frame is sent as part of the current burst. This option +is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.7 aPLCABurstTimer. The +valid range for this attribute is [0 .. 255]. Although, the value should be +set greater than the Inter-Frame-Gap (IFG) time of the MAC (plus some margin) +for PLCA burst mode to work as intended. + +PLCA_SET_CFG +============ + +Sets PLCA RS parameters. + +Request contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PLCA_HEADER`` nested request header + ``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State + ``ETHTOOL_A_PLCA_NODE_ID`` u8 PLCA unique local node ID + ``ETHTOOL_A_PLCA_NODE_CNT`` u8 Number of PLCA nodes on the + netkork, including the + coordinator + ``ETHTOOL_A_PLCA_TO_TMR`` u8 Transmit Opportunity Timer + value in bit-times (BT) + ``ETHTOOL_A_PLCA_BURST_CNT`` u8 Number of additional packets + the node is allowed to send + within a single TO + ``ETHTOOL_A_PLCA_BURST_TMR`` u8 Time to wait for the MAC to + transmit a new frame before + terminating the burst + ====================================== ====== ============================= + +For a description of each attribute, see ``PLCA_GET_CFG``. + +PLCA_GET_STATUS +=============== + +Gets PLCA RS status information. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_PLCA_HEADER`` nested request header + ===================================== ====== ========================== + +Kernel response contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PLCA_HEADER`` nested reply header + ``ETHTOOL_A_PLCA_STATUS`` u8 PLCA RS operational status + ====================================== ====== ============================= + +When set, the ``ETHTOOL_A_PLCA_STATUS`` attribute indicates whether the node is +detecting the presence of the BEACON on the network. This flag is +corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.2 aPLCAStatus. + +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_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_TX_MIN_FRAG_SIZE`` u32 minimum size of transmitted + non-final fragments, in octets + ``ETHTOOL_A_MM_RX_MIN_FRAG_SIZE`` u32 minimum size of received non-final + fragments, in octets + ``ETHTOOL_A_MM_VERIFY_ENABLED`` bool set if TX of SMD-V frames is + administratively enabled + ``ETHTOOL_A_MM_VERIFY_STATUS`` u8 state of the verification function + ``ETHTOOL_A_MM_VERIFY_TIME`` u32 delay between verification attempts + ``ETHTOOL_A_MM_MAX_VERIFY_TIME``` u32 maximum verification interval + supported by device + ``ETHTOOL_A_MM_STATS`` nested IEEE 802.3-2018 subclause 30.14.1 + oMACMergeEntity statistics counters + ================================= ====== =================================== + +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_TX_MIN_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 +2076,9 @@ 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_PLCA_GET_CFG`` + n/a ``ETHTOOL_MSG_PLCA_SET_CFG`` + n/a ``ETHTOOL_MSG_PLCA_GET_STATUS`` + n/a ``ETHTOOL_MSG_MM_GET`` + n/a ``ETHTOOL_MSG_MM_SET`` =================================== ===================================== |