History

ethtool: Expand documentation of struct ethtool_cmd

struct ethtool_cmd has very limited documentation; it contains several obscure or obsolete fields and several with non-obvious interpretation. Replace the inline comments (and some others below) with a full explanation of the semantics as well as I understand them, in kernel-doc format. Formally deprecate some fields that seem to be of historical use only. Extend the comment about 32/64-bit compatibility to cover all ethtool structures.

Ben Hutchings committed 12 years ago

Commit bf8fc601 parent 738b52b1 file · +90 −34Browse files

Unified · Split

include/uapi/linux/ethtool.h+90−34
@@ -16,37 +16,97 @@ · 15 unmodified lines
1616 #include <linux/types.h>
1717 #include <linux/if_ether.h>
1818
19−/* This should work for both 32 and 64 bit userland. */
19+/* All structures exposed to userland should be defined such that they
20+ * have the same layout for 32-bit and 64-bit userland.
21+ */
22+
23+/**
24+ * struct ethtool_cmd - link control and status
25+ * @cmd: Command number = %ETHTOOL_GSET or %ETHTOOL_SSET
26+ * @supported: Bitmask of %SUPPORTED_* flags for the link modes,
27+ * physical connectors and other link features for which the
28+ * interface supports autonegotiation or auto-detection.
29+ * Read-only.
30+ * @advertising: Bitmask of %ADVERTISED_* flags for the link modes,
31+ * physical connectors and other link features that are
32+ * advertised through autonegotiation or enabled for
33+ * auto-detection.
34+ * @speed: Low bits of the speed
35+ * @duplex: Duplex mode; one of %DUPLEX_*
36+ * @port: Physical connector type; one of %PORT_*
37+ * @phy_address: MDIO address of PHY (transceiver); 0 or 255 if not
38+ * applicable. For clause 45 PHYs this is the PRTAD.
39+ * @transceiver: Historically used to distinguish different possible
40+ * PHY types, but not in a consistent way. Deprecated.
41+ * @autoneg: Enable/disable autonegotiation and auto-detection;
42+ * either %AUTONEG_DISABLE or %AUTONEG_ENABLE
43+ * @mdio_support: Bitmask of %ETH_MDIO_SUPPORTS_* flags for the MDIO
44+ * protocols supported by the interface; 0 if unknown.
45+ * Read-only.
46+ * @maxtxpkt: Historically used to report TX IRQ coalescing; now
47+ * obsoleted by &struct ethtool_coalesce. Read-only; deprecated.
48+ * @maxrxpkt: Historically used to report RX IRQ coalescing; now
49+ * obsoleted by &struct ethtool_coalesce. Read-only; deprecated.
50+ * @speed_hi: High bits of the speed
51+ * @eth_tp_mdix: Ethernet twisted-pair MDI(-X) status; one of
52+ * %ETH_TP_MDI_*. If the status is unknown or not applicable, the
53+ * value will be %ETH_TP_MDI_INVALID. Read-only.
54+ * @eth_tp_mdix_ctrl: Ethernet twisted pair MDI(-X) control; one of
55+ * %ETH_TP_MDI_*. If MDI(-X) control is not implemented, reads
56+ * yield %ETH_TP_MDI_INVALID and writes may be ignored or rejected.
57+ * When written successfully, the link should be renegotiated if
58+ * necessary.
59+ * @lp_advertising: Bitmask of %ADVERTISED_* flags for the link modes
60+ * and other link features that the link partner advertised
61+ * through autonegotiation; 0 if unknown or not applicable.
62+ * Read-only.
63+ *
64+ * The link speed in Mbps is split between @speed and @speed_hi. Use
65+ * the ethtool_cmd_speed() and ethtool_cmd_speed_set() functions to
66+ * access it.
67+ *
68+ * If autonegotiation is disabled, the speed and @duplex represent the
69+ * fixed link mode and are writable if the driver supports multiple
70+ * link modes. If it is enabled then they are read-only; if the link
71+ * is up they represent the negotiated link mode; if the link is down,
72+ * the speed is 0, %SPEED_UNKNOWN or the highest enabled speed and
73+ * @duplex is %DUPLEX_UNKNOWN or the best enabled duplex mode.
74+ *
75+ * Some hardware interfaces may have multiple PHYs and/or physical
76+ * connectors fitted or do not allow the driver to detect which are
77+ * fitted. For these interfaces @port and/or @phy_address may be
78+ * writable, possibly dependent on @autoneg being %AUTONEG_DISABLE.
79+ * Otherwise, attempts to write different values may be ignored or
80+ * rejected.
81+ *
82+ * Users should assume that all fields not marked read-only are
83+ * writable and subject to validation by the driver. They should use
84+ * %ETHTOOL_GSET to get the current values before making specific
85+ * changes and then applying them with %ETHTOOL_SSET.
86+ *
87+ * Drivers that implement set_settings() should validate all fields
88+ * other than @cmd that are not described as read-only or deprecated,
89+ * and must ignore all fields described as read-only.
90+ *
91+ * Deprecated fields should be ignored by both users and drivers.
92+ */
2093 struct ethtool_cmd {
2194 __u32 cmd;
22− __u32 supported; /* Features this interface supports */
23− __u32 advertising; /* Features this interface advertises */
24− __u16 speed; /* The forced speed (lower bits) in
25− * Mbps. Please use
26− * ethtool_cmd_speed()/_set() to
27− * access it */
28− __u8 duplex; /* Duplex, half or full */
29− __u8 port; /* Which connector port */
30− __u8 phy_address; /* MDIO PHY address (PRTAD for clause 45).
31− * May be read-only or read-write
32− * depending on the driver.
33− */
34− __u8 transceiver; /* Which transceiver to use */
35− __u8 autoneg; /* Enable or disable autonegotiation */
36− __u8 mdio_support; /* MDIO protocols supported. Read-only.
37− * Not set by all drivers.
38− */
39− __u32 maxtxpkt; /* Tx pkts before generating tx int */
40− __u32 maxrxpkt; /* Rx pkts before generating rx int */
41− __u16 speed_hi; /* The forced speed (upper
42− * bits) in Mbps. Please use
43− * ethtool_cmd_speed()/_set() to
44− * access it */
45− __u8 eth_tp_mdix; /* twisted pair MDI-X status */
46− __u8 eth_tp_mdix_ctrl; /* twisted pair MDI-X control, when set,
47− * link should be renegotiated if necessary
48− */
49− __u32 lp_advertising; /* Features the link partner advertises */
95+ __u32 supported;
96+ __u32 advertising;
97+ __u16 speed;
98+ __u8 duplex;
99+ __u8 port;
100+ __u8 phy_address;
101+ __u8 transceiver;
102+ __u8 autoneg;
103+ __u8 mdio_support;
104+ __u32 maxtxpkt;
105+ __u32 maxrxpkt;
106+ __u16 speed_hi;
107+ __u8 eth_tp_mdix;
108+ __u8 eth_tp_mdix_ctrl;
109+ __u32 lp_advertising;
50110 __u32 reserved[2];
51111 };
52112
@@ -905,7 +965,6 @@ enum ethtool_sfeatures_retval_bits { · 852 unmodified lines
905965 #define SPARC_ETH_GSET ETHTOOL_GSET
906966 #define SPARC_ETH_SSET ETHTOOL_SSET
907967
908−/* Indicates what features are supported by the interface. */
909968 #define SUPPORTED_10baseT_Half (1 << 0)
910969 #define SUPPORTED_10baseT_Full (1 << 1)
911970 #define SUPPORTED_100baseT_Half (1 << 2)
@@ -934,7 +993,6 @@ enum ethtool_sfeatures_retval_bits { · 22 unmodified lines
934993 #define SUPPORTED_40000baseSR4_Full (1 << 25)
935994 #define SUPPORTED_40000baseLR4_Full (1 << 26)
936995
937−/* Indicates what features are advertised by the interface. */
938996 #define ADVERTISED_10baseT_Half (1 << 0)
939997 #define ADVERTISED_10baseT_Full (1 << 1)
940998 #define ADVERTISED_100baseT_Half (1 << 2)
@@ -999,9 +1057,7 @@ enum ethtool_sfeatures_retval_bits { · 58 unmodified lines
9991057 #define XCVR_DUMMY2 0x03
10001058 #define XCVR_DUMMY3 0x04
10011059
1002−/* Enable or disable autonegotiation. If this is set to enable,
1003− * the forced link modes above are completely ignored.
1004− */
1060+/* Enable or disable autonegotiation. */
10051061 #define AUTONEG_DISABLE 0x00
10061062 #define AUTONEG_ENABLE 0x01
10071063