Add a note on expected handling of reserved fields, and references to all kdocs. This fixes a bunch of kdoc warnings.
Showing the changes to include/uapi (1 of 1 file). Show all
Unified · Split
| @@ -26,6 +26,14 @@ · 25 unmodified lines | |||
| 26 | * have the same layout for 32-bit and 64-bit userland. | 26 | * have the same layout for 32-bit and 64-bit userland. |
| 27 | */ | 27 | */ |
| 28 | 28 | ||
| 29 | /* Note on reserved space. | ||
| 30 | * Reserved fields must not be accessed directly by user space because | ||
| 31 | * they may be replaced by a different field in the future. They must | ||
| 32 | * be initialized to zero before making the request, e.g. via memset | ||
| 33 | * of the entire structure or implicitly by not being set in a structure | ||
| 34 | * initializer. | ||
| 35 | */ | ||
| 36 | |||
| 29 | /** | 37 | /** |
| 30 | * struct ethtool_cmd - DEPRECATED, link control and status | 38 | * struct ethtool_cmd - DEPRECATED, link control and status |
| 31 | * This structure is DEPRECATED, please use struct ethtool_link_settings. | 39 | * This structure is DEPRECATED, please use struct ethtool_link_settings. |
| @@ -67,6 +75,7 @@ · 35 unmodified lines | |||
| 67 | * and other link features that the link partner advertised | 75 | * and other link features that the link partner advertised |
| 68 | * through autonegotiation; 0 if unknown or not applicable. | 76 | * through autonegotiation; 0 if unknown or not applicable. |
| 69 | * Read-only. | 77 | * Read-only. |
| 78 | * @reserved: Reserved for future use; see the note on reserved space. | ||
| 70 | * | 79 | * |
| 71 | * The link speed in Mbps is split between @speed and @speed_hi. Use | 80 | * The link speed in Mbps is split between @speed and @speed_hi. Use |
| 72 | * the ethtool_cmd_speed() and ethtool_cmd_speed_set() functions to | 81 | * the ethtool_cmd_speed() and ethtool_cmd_speed_set() functions to |
| @@ -155,6 +164,7 @@ static inline __u32 ethtool_cmd_speed(const struct ethtool_cmd *ep) · 82 unmodified lines | |||
| 155 | * @bus_info: Device bus address. This should match the dev_name() | 164 | * @bus_info: Device bus address. This should match the dev_name() |
| 156 | * string for the underlying bus device, if there is one. May be | 165 | * string for the underlying bus device, if there is one. May be |
| 157 | * an empty string. | 166 | * an empty string. |
| 167 | * @reserved2: Reserved for future use; see the note on reserved space. | ||
| 158 | * @n_priv_flags: Number of flags valid for %ETHTOOL_GPFLAGS and | 168 | * @n_priv_flags: Number of flags valid for %ETHTOOL_GPFLAGS and |
| 159 | * %ETHTOOL_SPFLAGS commands; also the number of strings in the | 169 | * %ETHTOOL_SPFLAGS commands; also the number of strings in the |
| 160 | * %ETH_SS_PRIV_FLAGS set | 170 | * %ETH_SS_PRIV_FLAGS set |
| @@ -356,6 +366,7 @@ struct ethtool_eeprom { · 195 unmodified lines | |||
| 356 | * @tx_lpi_timer: Time in microseconds the interface delays prior to asserting | 366 | * @tx_lpi_timer: Time in microseconds the interface delays prior to asserting |
| 357 | * its tx lpi (after reaching 'idle' state). Effective only when eee | 367 | * its tx lpi (after reaching 'idle' state). Effective only when eee |
| 358 | * was negotiated and tx_lpi_enabled was set. | 368 | * was negotiated and tx_lpi_enabled was set. |
| 369 | * @reserved: Reserved for future use; see the note on reserved space. | ||
| 359 | */ | 370 | */ |
| 360 | struct ethtool_eee { | 371 | struct ethtool_eee { |
| 361 | __u32 cmd; | 372 | __u32 cmd; |
| @@ -374,6 +385,7 @@ struct ethtool_eee { · 12 unmodified lines | |||
| 374 | * @cmd: %ETHTOOL_GMODULEINFO | 385 | * @cmd: %ETHTOOL_GMODULEINFO |
| 375 | * @type: Standard the module information conforms to %ETH_MODULE_SFF_xxxx | 386 | * @type: Standard the module information conforms to %ETH_MODULE_SFF_xxxx |
| 376 | * @eeprom_len: Length of the eeprom | 387 | * @eeprom_len: Length of the eeprom |
| 388 | * @reserved: Reserved for future use; see the note on reserved space. | ||
| 377 | * | 389 | * |
| 378 | * This structure is used to return the information to | 390 | * This structure is used to return the information to |
| 379 | * properly size memory for a subsequent call to %ETHTOOL_GMODULEEEPROM. | 391 | * properly size memory for a subsequent call to %ETHTOOL_GMODULEEEPROM. |
| @@ -701,6 +713,7 @@ struct ethtool_gstrings { · 321 unmodified lines | |||
| 701 | /** | 713 | /** |
| 702 | * struct ethtool_sset_info - string set information | 714 | * struct ethtool_sset_info - string set information |
| 703 | * @cmd: Command number = %ETHTOOL_GSSET_INFO | 715 | * @cmd: Command number = %ETHTOOL_GSSET_INFO |
| 716 | * @reserved: Reserved for future use; see the note on reserved space. | ||
| 704 | * @sset_mask: On entry, a bitmask of string sets to query, with bits | 717 | * @sset_mask: On entry, a bitmask of string sets to query, with bits |
| 705 | * numbered according to &enum ethtool_stringset. On return, a | 718 | * numbered according to &enum ethtool_stringset. On return, a |
| 706 | * bitmask of those string sets queried that are supported. | 719 | * bitmask of those string sets queried that are supported. |
| @@ -745,6 +758,7 @@ enum ethtool_test_flags { · 38 unmodified lines | |||
| 745 | * @flags: A bitmask of flags from &enum ethtool_test_flags. Some | 758 | * @flags: A bitmask of flags from &enum ethtool_test_flags. Some |
| 746 | * flags may be set by the user on entry; others may be set by | 759 | * flags may be set by the user on entry; others may be set by |
| 747 | * the driver on return. | 760 | * the driver on return. |
| 761 | * @reserved: Reserved for future use; see the note on reserved space. | ||
| 748 | * @len: On return, the number of test results | 762 | * @len: On return, the number of test results |
| 749 | * @data: Array of test results | 763 | * @data: Array of test results |
| 750 | * | 764 | * |
| @@ -945,6 +959,7 @@ union ethtool_flow_union { · 194 unmodified lines | |||
| 945 | * @vlan_etype: VLAN EtherType | 959 | * @vlan_etype: VLAN EtherType |
| 946 | * @vlan_tci: VLAN tag control information | 960 | * @vlan_tci: VLAN tag control information |
| 947 | * @data: user defined data | 961 | * @data: user defined data |
| 962 | * @padding: Reserved for future use; see the note on reserved space. | ||
| 948 | * | 963 | * |
| 949 | * Note, @vlan_etype, @vlan_tci, and @data are only valid if %FLOW_EXT | 964 | * Note, @vlan_etype, @vlan_tci, and @data are only valid if %FLOW_EXT |
| 950 | * is set in &struct ethtool_rx_flow_spec @flow_type. | 965 | * is set in &struct ethtool_rx_flow_spec @flow_type. |
| @@ -1120,7 +1135,8 @@ struct ethtool_rxfh_indir { · 169 unmodified lines | |||
| 1120 | * hardware hash key. | 1135 | * hardware hash key. |
| 1121 | * @hfunc: Defines the current RSS hash function used by HW (or to be set to). | 1136 | * @hfunc: Defines the current RSS hash function used by HW (or to be set to). |
| 1122 | * Valid values are one of the %ETH_RSS_HASH_*. | 1137 | * Valid values are one of the %ETH_RSS_HASH_*. |
| 1123 | * @rsvd: Reserved for future extensions. | 1138 | * @rsvd8: Reserved for future use; see the note on reserved space. |
| 1139 | * @rsvd32: Reserved for future use; see the note on reserved space. | ||
| 1124 | * @rss_config: RX ring/queue index for each hash value i.e., indirection table | 1140 | * @rss_config: RX ring/queue index for each hash value i.e., indirection table |
| 1125 | * of @indir_size __u32 elements, followed by hash key of @key_size | 1141 | * of @indir_size __u32 elements, followed by hash key of @key_size |
| 1126 | * bytes. | 1142 | * bytes. |
| @@ -1288,7 +1304,9 @@ struct ethtool_sfeatures { · 161 unmodified lines | |||
| 1288 | * @so_timestamping: bit mask of the sum of the supported SO_TIMESTAMPING flags | 1304 | * @so_timestamping: bit mask of the sum of the supported SO_TIMESTAMPING flags |
| 1289 | * @phc_index: device index of the associated PHC, or -1 if there is none | 1305 | * @phc_index: device index of the associated PHC, or -1 if there is none |
| 1290 | * @tx_types: bit mask of the supported hwtstamp_tx_types enumeration values | 1306 | * @tx_types: bit mask of the supported hwtstamp_tx_types enumeration values |
| 1307 | * @tx_reserved: Reserved for future use; see the note on reserved space. | ||
| 1291 | * @rx_filters: bit mask of the supported hwtstamp_rx_filters enumeration values | 1308 | * @rx_filters: bit mask of the supported hwtstamp_rx_filters enumeration values |
| 1309 | * @rx_reserved: Reserved for future use; see the note on reserved space. | ||
| 1292 | * | 1310 | * |
| 1293 | * The bits in the 'tx_types' and 'rx_filters' fields correspond to | 1311 | * The bits in the 'tx_types' and 'rx_filters' fields correspond to |
| 1294 | * the 'hwtstamp_tx_types' and 'hwtstamp_rx_filters' enumeration values, | 1312 | * the 'hwtstamp_tx_types' and 'hwtstamp_rx_filters' enumeration values, |
| @@ -1944,6 +1962,8 @@ enum ethtool_reset_flags { · 649 unmodified lines | |||
| 1944 | * autonegotiation; 0 if unknown or not applicable. Read-only. | 1962 | * autonegotiation; 0 if unknown or not applicable. Read-only. |
| 1945 | * @transceiver: Used to distinguish different possible PHY types, | 1963 | * @transceiver: Used to distinguish different possible PHY types, |
| 1946 | * reported consistently by PHYLIB. Read-only. | 1964 | * reported consistently by PHYLIB. Read-only. |
| 1965 | * @reserved: Reserved for future use; see the note on reserved space. | ||
| 1966 | * @reserved1: Reserved for future use; see the note on reserved space. | ||
| 1947 | * | 1967 | * |
| 1948 | * If autonegotiation is disabled, the speed and @duplex represent the | 1968 | * If autonegotiation is disabled, the speed and @duplex represent the |
| 1949 | * fixed link mode and are writable if the driver supports multiple | 1969 | * fixed link mode and are writable if the driver supports multiple |