[dpdk-dev] [PATCH] ethdev: group constant definitions in Doxygen

[dpdk-dev] [PATCH] ethdev: group constant definitions in Doxygen

[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 <thomas@monjalon.net>
---
 lib/ethdev/rte_ethdev.h | 71 ++++++++++++++++++++++++++++-------------
 1 file changed, 48 insertions(+), 23 deletions(-)

diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
index d2b27c351f..0924c9fc68 100644
--- a/lib/ethdev/rte_ethdev.h
+++ b/lib/ethdev/rte_ethdev.h
@@ -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.
-- 
2.33.0

Re: [dpdk-dev] [PATCH] ethdev: group constant definitions in Doxygen

[Ferruh Yigit]

On 8/30/2021 11:42 AM, Thomas Monjalon wrote:
> 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 <thomas@monjalon.net>
> ---
>  lib/ethdev/rte_ethdev.h | 71 ++++++++++++++++++++++++++++-------------
>  1 file changed, 48 insertions(+), 23 deletions(-)
> 
> diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
> index d2b27c351f..0924c9fc68 100644
> --- a/lib/ethdev/rte_ethdev.h
> +++ b/lib/ethdev/rte_ethdev.h
> @@ -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 */
> +/**@}*/

+1 to use Doxygen grouping, and changes looks good to me.

Re: [dpdk-dev] [PATCH] ethdev: group constant definitions in Doxygen

[Andrew Rybchenko]

On 9/9/21 8:02 PM, Ferruh Yigit wrote:
> On 8/30/2021 11:42 AM, Thomas Monjalon wrote:
>> 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 <thomas@monjalon.net>
>> ---
>>  lib/ethdev/rte_ethdev.h | 71 ++++++++++++++++++++++++++++-------------
>>  1 file changed, 48 insertions(+), 23 deletions(-)
>>
>> diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
>> index d2b27c351f..0924c9fc68 100644
>> --- a/lib/ethdev/rte_ethdev.h
>> +++ b/lib/ethdev/rte_ethdev.h
>> @@ -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 */
>> +/**@}*/
> +1 to use Doxygen grouping, and changes looks good to me.

+1

Re: [dpdk-dev] [PATCH] ethdev: group constant definitions in Doxygen

[Kevin Traynor]

On 30/08/2021 11:42, Thomas Monjalon wrote:
> 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<thomas@monjalon.net>
> ---
>   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 <ktraynor@redhat.com>

Re: [dpdk-dev] [PATCH] ethdev: group constant definitions in Doxygen

[Ferruh Yigit]

On 9/23/2021 5:35 PM, Kevin Traynor wrote:
> On 30/08/2021 11:42, Thomas Monjalon wrote:
>> 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<thomas@monjalon.net>
>> ---
>>   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 <ktraynor@redhat.com>
> 

Converting to explicit acks:
Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>


Applied to dpdk-next-net/main, thanks.