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 | 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 | 38 | * struct ethtool_cmd - DEPRECATED, link control and status |
| 31 | 39 | * This structure is DEPRECATED, please use struct ethtool_link_settings. |
| @@ -67,6 +75,7 @@ · 35 unmodified lines | ||
| 67 | 75 | * and other link features that the link partner advertised |
| 68 | 76 | * through autonegotiation; 0 if unknown or not applicable. |
| 69 | 77 | * Read-only. |
| 78 | + * @reserved: Reserved for future use; see the note on reserved space. | |
| 70 | 79 | * |
| 71 | 80 | * The link speed in Mbps is split between @speed and @speed_hi. Use |
| 72 | 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 | 164 | * @bus_info: Device bus address. This should match the dev_name() |
| 156 | 165 | * string for the underlying bus device, if there is one. May be |
| 157 | 166 | * an empty string. |
| 167 | + * @reserved2: Reserved for future use; see the note on reserved space. | |
| 158 | 168 | * @n_priv_flags: Number of flags valid for %ETHTOOL_GPFLAGS and |
| 159 | 169 | * %ETHTOOL_SPFLAGS commands; also the number of strings in the |
| 160 | 170 | * %ETH_SS_PRIV_FLAGS set |
| @@ -356,6 +366,7 @@ struct ethtool_eeprom { · 195 unmodified lines | ||
| 356 | 366 | * @tx_lpi_timer: Time in microseconds the interface delays prior to asserting |
| 357 | 367 | * its tx lpi (after reaching 'idle' state). Effective only when eee |
| 358 | 368 | * was negotiated and tx_lpi_enabled was set. |
| 369 | + * @reserved: Reserved for future use; see the note on reserved space. | |
| 359 | 370 | */ |
| 360 | 371 | struct ethtool_eee { |
| 361 | 372 | __u32 cmd; |
| @@ -374,6 +385,7 @@ struct ethtool_eee { · 12 unmodified lines | ||
| 374 | 385 | * @cmd: %ETHTOOL_GMODULEINFO |
| 375 | 386 | * @type: Standard the module information conforms to %ETH_MODULE_SFF_xxxx |
| 376 | 387 | * @eeprom_len: Length of the eeprom |
| 388 | + * @reserved: Reserved for future use; see the note on reserved space. | |
| 377 | 389 | * |
| 378 | 390 | * This structure is used to return the information to |
| 379 | 391 | * properly size memory for a subsequent call to %ETHTOOL_GMODULEEEPROM. |
| @@ -701,6 +713,7 @@ struct ethtool_gstrings { · 321 unmodified lines | ||
| 701 | 713 | /** |
| 702 | 714 | * struct ethtool_sset_info - string set information |
| 703 | 715 | * @cmd: Command number = %ETHTOOL_GSSET_INFO |
| 716 | + * @reserved: Reserved for future use; see the note on reserved space. | |
| 704 | 717 | * @sset_mask: On entry, a bitmask of string sets to query, with bits |
| 705 | 718 | * numbered according to &enum ethtool_stringset. On return, a |
| 706 | 719 | * bitmask of those string sets queried that are supported. |
| @@ -745,6 +758,7 @@ enum ethtool_test_flags { · 38 unmodified lines | ||
| 745 | 758 | * @flags: A bitmask of flags from &enum ethtool_test_flags. Some |
| 746 | 759 | * flags may be set by the user on entry; others may be set by |
| 747 | 760 | * the driver on return. |
| 761 | + * @reserved: Reserved for future use; see the note on reserved space. | |
| 748 | 762 | * @len: On return, the number of test results |
| 749 | 763 | * @data: Array of test results |
| 750 | 764 | * |
| @@ -945,6 +959,7 @@ union ethtool_flow_union { · 194 unmodified lines | ||
| 945 | 959 | * @vlan_etype: VLAN EtherType |
| 946 | 960 | * @vlan_tci: VLAN tag control information |
| 947 | 961 | * @data: user defined data |
| 962 | + * @padding: Reserved for future use; see the note on reserved space. | |
| 948 | 963 | * |
| 949 | 964 | * Note, @vlan_etype, @vlan_tci, and @data are only valid if %FLOW_EXT |
| 950 | 965 | * is set in &struct ethtool_rx_flow_spec @flow_type. |
| @@ -1120,7 +1135,8 @@ struct ethtool_rxfh_indir { · 169 unmodified lines | ||
| 1120 | 1135 | * hardware hash key. |
| 1121 | 1136 | * @hfunc: Defines the current RSS hash function used by HW (or to be set to). |
| 1122 | 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 | 1140 | * @rss_config: RX ring/queue index for each hash value i.e., indirection table |
| 1125 | 1141 | * of @indir_size __u32 elements, followed by hash key of @key_size |
| 1126 | 1142 | * bytes. |
| @@ -1288,7 +1304,9 @@ struct ethtool_sfeatures { · 161 unmodified lines | ||
| 1288 | 1304 | * @so_timestamping: bit mask of the sum of the supported SO_TIMESTAMPING flags |
| 1289 | 1305 | * @phc_index: device index of the associated PHC, or -1 if there is none |
| 1290 | 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 | 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 | 1311 | * The bits in the 'tx_types' and 'rx_filters' fields correspond to |
| 1294 | 1312 | * the 'hwtstamp_tx_types' and 'hwtstamp_rx_filters' enumeration values, |
| @@ -1944,6 +1962,8 @@ enum ethtool_reset_flags { · 649 unmodified lines | ||
| 1944 | 1962 | * autonegotiation; 0 if unknown or not applicable. Read-only. |
| 1945 | 1963 | * @transceiver: Used to distinguish different possible PHY types, |
| 1946 | 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 | 1968 | * If autonegotiation is disabled, the speed and @duplex represent the |
| 1949 | 1969 | * fixed link mode and are writable if the driver supports multiple |