ethdev: group constant definitions in Doxygen
PATCH 1/1 ethdev: group constant definitions in Doxygen
A lot of flags are parts of a group but are documented alone. The Doxygen syntax @{ and @} for grouping is used to make flags appear together and have a common description.
Some Rx/Tx offload flags and RSS definitions are not grouped because they need to be all properly documented first.
--- lib/ethdev/rte_ethdev.h | 71 ++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 23 deletions(-)
lib/ethdev/rte_ethdev.h +48 -23
@@ -276,7 +276,7 @@ struct rte_eth_stats {/**< Total number of queue packets received that are dropped. */ }; -/** +/**@{@name Link speed capabilities * Device supported speeds bitmap flags */ #define ETH_LINK_SPEED_AUTONEG (0 << 0)/**< Autonegotiate (all speeds) */
@@ -296,8 +296,9 @@ struct rte_eth_stats {#define ETH_LINK_SPEED_56G (1 << 13)/**< 56 Gbps */ #define ETH_LINK_SPEED_100G (1 << 14)/**< 100 Gbps */ #define ETH_LINK_SPEED_200G (1 << 15)/**< 200 Gbps */ +/**@}*/ -/** +/**@{@name Link speed * Ethernet numeric link speeds in Mbps */ #define ETH_SPEED_NUM_NONE 0/**< Not defined */
@@ -315,6 +316,7 @@ struct rte_eth_stats {#define ETH_SPEED_NUM_100G 100000/**< 100 Gbps */ #define ETH_SPEED_NUM_200G 200000/**< 200 Gbps */ #define ETH_SPEED_NUM_UNKNOWN UINT32_MAX/**< Unknown */ +/**@}*/ /** * A structure used to retrieve link-level information of an Ethernet port.
@@ -327,7 +329,9 @@ struct rte_eth_link { uint16_t link_status : 1; /**< ETH_LINK_[DOWN/UP] */ }__rte_aligned (8 );/**< aligned for atomic64 read/write */ -/* Utility constants */ +/**@{@name Link negotiation +* Constants used in link management. +*/ #define ETH_LINK_HALF_DUPLEX 0/**< Half-duplex connection (see link_duplex). */ #define ETH_LINK_FULL_DUPLEX 1/**< Full-duplex connection (see link_duplex). */ #define ETH_LINK_DOWN 0/**< Link is down (see link_status). */
@@ -335,6 +339,7 @@ struct rte_eth_link {#define ETH_LINK_FIXED 0/**< No autonegotiation (see link_autoneg). */ #define ETH_LINK_AUTONEG 1/**< Autonegotiated (see link_autoneg). */ #define RTE_ETH_LINK_MAX_STR_LEN 40/**< Max length of default link string. */ +/**@}*/ /** * A structure used to configure the ring threshold registers of an RX/TX
@@ -346,12 +351,13 @@ struct rte_eth_thresh {uint8_t wthresh;/**< Ring writeback threshold. */ }; -/** -* Simple flags are used for rte_eth_conf.rxmode.mq_mode. +/**@{@name Multi-queue mode +* @see rte_eth_conf.rxmode.mq_mode. */ -#define ETH_MQ_RX_RSS_FLAG 0x1 -#define ETH_MQ_RX_DCB_FLAG 0x2 -#define ETH_MQ_RX_VMDQ_FLAG 0x4 +#define ETH_MQ_RX_RSS_FLAG 0x1/**< Enable RSS. @see rte_eth_rss_conf */ +#define ETH_MQ_RX_DCB_FLAG 0x2/**< Enable DCB. */ +#define ETH_MQ_RX_VMDQ_FLAG 0x4/**< Enable VMDq. */ +/**@}*/ /** * A set of values to identify what method is to be used to route
@@ -782,28 +788,30 @@ rte_eth_rss_hf_refine(uint64_t rss_hf)#define ETH_RSS_RETA_SIZE_512 512#define RTE_RETA_GROUP_SIZE 64 -/* Definitions used for VMDQ and DCB functionality */ +/**@{@name VMDq and DCB maximums */ #define ETH_VMDQ_MAX_VLAN_FILTERS 64/**< Maximum nb. of VMDQ vlan filters. */ #define ETH_DCB_NUM_USER_PRIORITIES 8/**< Maximum nb. of DCB priorities. */ #define ETH_VMDQ_DCB_NUM_QUEUES 128/**< Maximum nb. of VMDQ DCB queues. */ #define ETH_DCB_NUM_QUEUES 128/**< Maximum nb. of DCB queues. */ +/**@}*/ -/* DCB capability defines */ +/**@{@name DCB capabilities */ #define ETH_DCB_PG_SUPPORT 0x00000001/**< Priority Group(ETS) support. */ #define ETH_DCB_PFC_SUPPORT 0x00000002/**< Priority Flow Control support. */ +/**@}*/ -/* Definitions used for VLAN Offload functionality */ +/**@{@name VLAN offload bits */ #define ETH_VLAN_STRIP_OFFLOAD 0x0001/**< VLAN Strip On/Off */ #define ETH_VLAN_FILTER_OFFLOAD 0x0002/**< VLAN Filter On/Off */ #define ETH_VLAN_EXTEND_OFFLOAD 0x0004/**< VLAN Extend On/Off */ #define ETH_QINQ_STRIP_OFFLOAD 0x0008/**< QINQ Strip On/Off */ -/* Definitions used for mask VLAN setting */ #define ETH_VLAN_STRIP_MASK 0x0001/**< VLAN Strip setting mask */ #define ETH_VLAN_FILTER_MASK 0x0002/**< VLAN Filter setting mask*/ #define ETH_VLAN_EXTEND_MASK 0x0004/**< VLAN Extend setting mask*/ #define ETH_QINQ_STRIP_MASK 0x0008/**< QINQ Strip setting mask */ #define ETH_VLAN_ID_MAX 0x0FFF/**< VLAN ID is in lower 12 bits*/ +/**@}*/ /* Definitions used for receive MAC address */ #define ETH_NUM_RECEIVE_MAC_ADDR 128/**< Maximum nb. of receive mac addr. */
@@ -811,21 +819,28 @@ rte_eth_rss_hf_refine(uint64_t rss_hf)/* Definitions used for unicast hash */ #define ETH_VMDQ_NUM_UC_HASH_ARRAY 128/**< Maximum nb. of UC hash array. */ -/* Definitions used for VMDQ pool rx mode setting */ +/**@{@name VMDq Rx mode +* @see rte_eth_vmdq_rx_conf.rx_mode +*/ #define ETH_VMDQ_ACCEPT_UNTAG 0x0001/**< accept untagged packets. */ #define ETH_VMDQ_ACCEPT_HASH_MC 0x0002/**< accept packets in multicast table . */ #define ETH_VMDQ_ACCEPT_HASH_UC 0x0004/**< accept packets in unicast table. */ #define ETH_VMDQ_ACCEPT_BROADCAST 0x0008/**< accept broadcast packets. */ #define ETH_VMDQ_ACCEPT_MULTICAST 0x0010/**< multicast promiscuous. */ +/**@}*/ /** Maximum nb. of vlan per mirror rule */ #define ETH_MIRROR_MAX_VLANS 64 +/**@{@name Mirroring type +* @see rte_eth_mirror_conf.rule_type +*/ #define ETH_MIRROR_VIRTUAL_POOL_UP 0x01/**< Virtual Pool uplink Mirroring. */ #define ETH_MIRROR_UPLINK_PORT 0x02/**< Uplink Port Mirroring. */ #define ETH_MIRROR_DOWNLINK_PORT 0x04/**< Downlink Port Mirroring. */ #define ETH_MIRROR_VLAN 0x08/**< VLAN Mirroring. */ #define ETH_MIRROR_VIRTUAL_POOL_DOWN 0x10/**< Virtual Pool downlink Mirroring. */ +/**@}*/ /** * A structure used to configure VLAN traffic mirror of an Ethernet port.
@@ -1587,12 +1602,11 @@ struct rte_eth_dev_info {void *reserved_ptrs[2 ];/**< Reserved for future fields */ }; -/** -* RX/TX queue states -*/ -#define RTE_ETH_QUEUE_STATE_STOPPED 0 -#define RTE_ETH_QUEUE_STATE_STARTED 1 -#define RTE_ETH_QUEUE_STATE_HAIRPIN 2 +/**@{@name Rx/Tx queue states */ +#define RTE_ETH_QUEUE_STATE_STOPPED 0/**< Queue stopped. */ +#define RTE_ETH_QUEUE_STATE_STARTED 1/**< Queue started. */ +#define RTE_ETH_QUEUE_STATE_HAIRPIN 2/**< Queue used for hairpin. */ +/**@}*/ /** * Ethernet device RX queue information structure.
@@ -1744,10 +1758,7 @@ struct rte_eth_fec_capa { } \ }while (0 ) -/** -* l2 tunnel configuration. -*/ - +/**@{@name L2 tunnel configuration */ /**< l2 tunnel enable mask */#define ETH_L2_TUNNEL_ENABLE_MASK 0x00000001/**< l2 tunnel insertion mask */
@@ -1756,6 +1767,7 @@ struct rte_eth_fec_capa {#define ETH_L2_TUNNEL_STRIPPING_MASK 0x00000004/**< l2 tunnel forwarding mask */ #define ETH_L2_TUNNEL_FORWARDING_MASK 0x00000008 +/**@}*/ /** * Function type used for RX packet processing packet callbacks.
@@ -1837,6 +1849,10 @@ struct rte_eth_dev_owner {char name[RTE_ETH_MAX_OWNER_NAME_LEN ];/**< The owner name. */ }; +/**@{@name Device flags +* Flags internally saved in rte_eth_dev_data.dev_flags +* and reported in rte_eth_dev_info.dev_flags. +*/ /** PMD supports thread-safe flow operations */ #define RTE_ETH_DEV_FLOW_OPS_THREAD_SAFE 0x0001/** Device supports link state interrupt */
@@ -1854,6 +1870,7 @@ struct rte_eth_dev_owner {* PMDs filling the queue xstats themselves should not set this flag */ #define RTE_ETH_DEV_AUTOFILL_QUEUE_XSTATS 0x0040 +/**@}*/ /** * Iterates over valid ethdev ports owned by a specific owner.
@@ -5074,9 +5091,13 @@ rte_eth_rx_descriptor_done(uint16_t port_id, uint16_t queue_id, uint16_t offset)return (*dev->rx_descriptor_done)(dev->data->rx_queues[queue_id], offset); } +/**@{@name Rx hardware descriptor states +* @see rte_eth_rx_descriptor_status +*/ #define RTE_ETH_RX_DESC_AVAIL 0/**< Desc available for hw. */ #define RTE_ETH_RX_DESC_DONE 1/**< Desc done, filled by hw. */ #define RTE_ETH_RX_DESC_UNAVAIL 2/**< Desc used by driver or hw. */ +/**@}*/ /** * Check the status of a Rx descriptor in the queue
@@ -5132,9 +5153,13 @@ rte_eth_rx_descriptor_status(uint16_t port_id, uint16_t queue_id,return (*dev->rx_descriptor_status)(rxq, offset); } +/**@{@name Tx hardware descriptor states +* @see rte_eth_tx_descriptor_status +*/ #define RTE_ETH_TX_DESC_FULL 0/**< Desc filled for hw, waiting xmit. */ #define RTE_ETH_TX_DESC_DONE 1/**< Desc done, packet is transmitted. */ #define RTE_ETH_TX_DESC_UNAVAIL 2/**< Desc used by driver or hw. */ +/**@}*/ /** * Check the status of a Tx descriptor in the queue.
Signature · 1 line
2.33.0
Quoted 26 lines · Thomas Monjalon
A lot of flags are parts of a group but are documented alone. The Doxygen syntax @{ and @} for grouping is used to make flags appear together and have a common description.
Some Rx/Tx offload flags and RSS definitions are not grouped because they need to be all properly documented first.
Signed-off-by Thomas Monjalon <[email protected]>--- lib/ethdev/rte_ethdev.h | 71 ++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 23 deletions(-)lib/ethdev/rte_ethdev.h +1
-1@@ -276,7 +276,7 @@ struct rte_eth_stats {/**< Total number of queue packets received that are dropped. */ }; -/** +/**@{@name Link speed capabilities * Device supported speeds bitmap flags */ #define ETH_LINK_SPEED_AUTONEG (0 << 0)/**< Autonegotiate (all speeds) */
lib/ethdev/rte_ethdev.h struct rte_eth_stats { · line 299
Quoted 4 lines
lib/ethdev/rte_ethdev.h +1
-0@@ -296,8 +296,9 @@ struct rte_eth_stats {#define ETH_LINK_SPEED_56G (1 << 13)/**< 56 Gbps */ #define ETH_LINK_SPEED_100G (1 << 14)/**< 100 Gbps */ #define ETH_LINK_SPEED_200G (1 << 15)/**< 200 Gbps */ +/**@}*/
+1 to use Doxygen grouping, and changes looks good to me.
Quoted 21 lines · Ferruh Yigit
Quoted 20 lines · Thomas Monjalon
A lot of flags are parts of a group but are documented alone. The Doxygen syntax @{ and @} for grouping is used to make flags appear together and have a common description.
Some Rx/Tx offload flags and RSS definitions are not grouped because they need to be all properly documented first.
Signed-off-by Thomas Monjalon <[email protected]>--- lib/ethdev/rte_ethdev.h | 71 ++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 23 deletions(-)lib/ethdev/rte_ethdev.h +0
-0@@ -276,7 +276,7 @@ struct rte_eth_stats {/**< Total number of queue packets received that are dropped. */ };
Quoted 11 lines
lib/ethdev/rte_ethdev.h struct rte_eth_stats { · line 299
Quoted 10 lines
lib/ethdev/rte_ethdev.h +2
-1-/** +/**@{@name Link speed capabilities * Device supported speeds bitmap flags */ #define ETH_LINK_SPEED_AUTONEG (0 << 0)/**< Autonegotiate (all speeds) */ @@ -296,8 +296,9 @@ struct rte_eth_stats {#define ETH_LINK_SPEED_56G (1 << 13)/**< 56 Gbps */ #define ETH_LINK_SPEED_100G (1 << 14)/**< 100 Gbps */ #define ETH_LINK_SPEED_200G (1 << 15)/**< 200 Gbps */ +/**@}*/ +1 to use Doxygen grouping, and changes looks good to me.
+1
Quoted 11 lines · Thomas Monjalon
A lot of flags are parts of a group but are documented alone. The Doxygen syntax @{ and @} for grouping is used to make flags appear together and have a common description.
Some Rx/Tx offload flags and RSS definitions are not grouped because they need to be all properly documented first.
Signed-off-by Thomas Monjalon<[email protected]>--- lib/ethdev/rte_ethdev.h | 71 ++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 23 deletions(-)
lgtm, this is a nice enhancement when reading the api guide.
Quoted 8 lines · Kevin Traynor
Quoted 7 lines · Thomas Monjalon
A lot of flags are parts of a group but are documented alone. The Doxygen syntax @{ and @} for grouping is used to make flags appear together and have a common description.
Some Rx/Tx offload flags and RSS definitions are not grouped because they need to be all properly documented first.
Quoted 9 lines
Quoted 4 lines
Signed-off-by Thomas Monjalon<[email protected]>---
lib/ethdev/rte_ethdev.h| 71 ++++++++++++++++++++++++++++-------------1 file changed, 48 insertions(+), 23 deletions(-)lgtm, this is a nice enhancement when reading the api guide.
Acked-by Kevin Traynor <[email protected]>
Converting to explicit acks:
Applied to dpdk-next-net/main, thanks.