net/mlx4: enhance header files comments

Add missing comments and fix those not Doxygen-friendly.

Since the private structure definition is modified, use this opportunity to
add one remaining missing include required by one of its fields
(sys/queue.h for LIST_HEAD()).

Signed-off-by: Adrien Mazarguil <adrien.mazarguil@6wind.com>
Acked-by: Nelio Laranjeiro <nelio.laranjeiro@6wind.com>

diff --git a/drivers/net/mlx4/mlx4.h b/drivers/net/mlx4/mlx4.h
index 71cbced..1799951 100644 (file)
--- a/drivers/net/mlx4/mlx4.h
+++ b/drivers/net/mlx4/mlx4.h
@@ -36,6 +36,7 @@
 
 #include <net/if.h>
 #include <stdint.h>
+#include <sys/queue.h>
 
 /* Verbs headers do not support -pedantic. */
 #ifdef PEDANTIC
@@ -51,13 +52,13 @@
 #include <rte_interrupts.h>
 #include <rte_mempool.h>
 
-/* Request send completion once in every 64 sends, might be less. */
+/** Request send completion once in every 64 sends, might be less. */
 #define MLX4_PMD_TX_PER_COMP_REQ 64
 
-/* Maximum size for inline data. */
+/** Maximum size for inline data. */
 #define MLX4_PMD_MAX_INLINE 0
 
-/*
+/**
  * Maximum number of cached Memory Pools (MPs) per TX queue. Each RTE MP
  * from which buffers are to be transmitted will have to be mapped by this
  * driver to their own Memory Region (MR). This is a slow operation.
@@ -68,10 +69,10 @@
 #define MLX4_PMD_TX_MP_CACHE 8
 #endif
 
-/* Interrupt alarm timeout value in microseconds. */
+/** Interrupt alarm timeout value in microseconds. */
 #define MLX4_INTR_ALARM_TIMEOUT 100000
 
-/* Port parameter. */
+/** Port parameter. */
 #define MLX4_PMD_PORT_KVARG "port"
 
 enum {
@@ -84,29 +85,31 @@ enum {
        PCI_DEVICE_ID_MELLANOX_CONNECTX3PRO = 0x1007,
 };
 
+/** Driver name reported to lower layers and used in log output. */
 #define MLX4_DRIVER_NAME "net_mlx4"
 
 struct rxq;
 struct txq;
 struct rte_flow;
 
+/** Private data structure. */
 struct priv {
-       struct rte_eth_dev *dev; /* Ethernet device. */
-       struct ibv_context *ctx; /* Verbs context. */
-       struct ibv_device_attr device_attr; /* Device properties. */
-       struct ibv_pd *pd; /* Protection Domain. */
-       struct ether_addr mac; /* MAC address. */
-       struct ibv_flow *mac_flow; /* Flow associated with MAC address. */
+       struct rte_eth_dev *dev; /**< Ethernet device. */
+       struct ibv_context *ctx; /**< Verbs context. */
+       struct ibv_device_attr device_attr; /**< Device properties. */
+       struct ibv_pd *pd; /**< Protection Domain. */
+       struct ether_addr mac; /**< MAC address. */
+       struct ibv_flow *mac_flow; /**< Flow associated with MAC address. */
        /* Device properties. */
-       uint16_t mtu; /* Configured MTU. */
-       uint8_t port; /* Physical port number. */
-       uint32_t started:1; /* Device started, flows enabled. */
-       uint32_t vf:1; /* This is a VF device. */
-       uint32_t intr_alarm:1; /* An interrupt alarm is scheduled. */
-       uint32_t isolated:1; /* Toggle isolated mode. */
-       struct rte_intr_handle intr_handle; /* Port interrupt handle. */
-       struct rte_flow_drop *flow_drop_queue; /* Flow drop queue. */
-       LIST_HEAD(mlx4_flows, rte_flow) flows;
+       uint16_t mtu; /**< Configured MTU. */
+       uint8_t port; /**< Physical port number. */
+       uint32_t started:1; /**< Device started, flows enabled. */
+       uint32_t vf:1; /**< This is a VF device. */
+       uint32_t intr_alarm:1; /**< An interrupt alarm is scheduled. */
+       uint32_t isolated:1; /**< Toggle isolated mode. */
+       struct rte_intr_handle intr_handle; /**< Port interrupt handle. */
+       struct rte_flow_drop *flow_drop_queue; /**< Flow drop queue. */
+       LIST_HEAD(, rte_flow) flows; /**< Configured flow rule handles. */
 };
 
 /* mlx4_ethdev.c */

diff --git a/drivers/net/mlx4/mlx4_flow.h b/drivers/net/mlx4/mlx4_flow.h
index fbb775d..459030c 100644 (file)
--- a/drivers/net/mlx4/mlx4_flow.h
+++ b/drivers/net/mlx4/mlx4_flow.h
@@ -52,6 +52,7 @@
 #include <rte_flow_driver.h>
 #include <rte_byteorder.h>
 
+/** PMD-specific (mlx4) definition of a flow rule handle. */
 struct rte_flow {
        LIST_ENTRY(rte_flow) next; /**< Pointer to the next flow structure. */
        struct ibv_flow *ibv_flow; /**< Verbs flow. */
@@ -65,6 +66,7 @@ struct mlx4_flow {
        unsigned int offset; /**< Offset in bytes in the ibv_attr buffer. */
 };
 
+/** Flow rule target descriptor. */
 struct mlx4_flow_action {
        uint32_t drop:1; /**< Target is a drop queue. */
        uint32_t queue:1; /**< Target is a receive queue. */

diff --git a/drivers/net/mlx4/mlx4_rxtx.h b/drivers/net/mlx4/mlx4_rxtx.h
index fec998a..365b585 100644 (file)
--- a/drivers/net/mlx4/mlx4_rxtx.h
+++ b/drivers/net/mlx4/mlx4_rxtx.h
@@ -85,8 +85,8 @@ struct rxq {
 
 /** Tx element. */
 struct txq_elt {
-       struct ibv_send_wr wr; /* Work request. */
-       struct ibv_sge sge; /* Scatter/gather element. */
+       struct ibv_send_wr wr; /**< Work request. */
+       struct ibv_sge sge; /**< Scatter/gather element. */
        struct rte_mbuf *buf; /**< Buffer. */
 };
 

diff --git a/drivers/net/mlx4/mlx4_utils.h b/drivers/net/mlx4/mlx4_utils.h
index 0fbdc71..b9c02d5 100644 (file)
--- a/drivers/net/mlx4/mlx4_utils.h
+++ b/drivers/net/mlx4/mlx4_utils.h
@@ -49,7 +49,7 @@
  * information replace the driver name (MLX4_DRIVER_NAME) in log messages.
  */
 
-/* Return the file name part of a path. */
+/** Return the file name part of a path. */
 static inline const char *
 pmd_drv_log_basename(const char *s)
 {
@@ -98,7 +98,7 @@ pmd_drv_log_basename(const char *s)
 #define WARN(...) PMD_DRV_LOG(WARNING, __VA_ARGS__)
 #define ERROR(...) PMD_DRV_LOG(ERR, __VA_ARGS__)
 
-/* Allocate a buffer on the stack and fill it with a printf format string. */
+/** Allocate a buffer on the stack and fill it with a printf format string. */
 #define MKSTR(name, ...) \
        char name[snprintf(NULL, 0, __VA_ARGS__) + 1]; \
        \