diff mbox

[dpdk-dev,1/3] net/mlx5: add missing function documentation

Message ID ad54d87cd39c1ad142fe9163c51317268e4b2b46.1518686930.git.nelio.laranjeiro@6wind.com (mailing list archive)
State Superseded, archived
Headers

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK

Commit Message

Nélio Laranjeiro Feb. 15, 2018, 9:29 a.m. UTC 
  Signed-off-by: Nelio Laranjeiro <nelio.laranjeiro@6wind.com>
Acked-by: Yongseok Koh <yskoh@mellanox.com>
---
 drivers/net/mlx5/mlx5_trigger.c | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

Comments

Adrien Mazarguil Feb. 16, 2018, 2:26 p.m. UTC | #1 
I hate to sound pedantic but...

On Thu, Feb 15, 2018 at 10:29:25AM +0100, Nelio Laranjeiro wrote:
> Signed-off-by: Nelio Laranjeiro <nelio.laranjeiro@6wind.com>
> Acked-by: Yongseok Koh <yskoh@mellanox.com>
> ---
>  drivers/net/mlx5/mlx5_trigger.c | 30 ++++++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
> 
> diff --git a/drivers/net/mlx5/mlx5_trigger.c b/drivers/net/mlx5/mlx5_trigger.c
> index f5711a998..a70b13d52 100644
> --- a/drivers/net/mlx5/mlx5_trigger.c
> +++ b/drivers/net/mlx5/mlx5_trigger.c
> @@ -14,6 +14,12 @@
>  #include "mlx5_rxtx.h"
>  #include "mlx5_utils.h"
>  
> +/**
> + * Stop traffic on Tx queues.
> + *
> + * @param  priv

...there's an extra space between @param and priv :)

> + *   Pointer to private structure.
> + */
>  static void
>  priv_txq_stop(struct priv *priv)
>  {
> @@ -23,6 +29,15 @@ priv_txq_stop(struct priv *priv)
>  		mlx5_priv_txq_release(priv, i);
>  }
>  
> +/**
> + * Start traffic on Tx queues.
> + *
> + * @param  priv

Ditto.

> + *   Pointer to private structure.
> + *
> + * @return
> + *   0 on success, errno on error.

This should more accurately read "0 on success, positive errno value
otherwise".

I would suggest to document these functions only after the errno mess is
sorted (patch 2/3 should come first) for a smaller amount of changes.

> + */
>  static int
>  priv_txq_start(struct priv *priv)
>  {
> @@ -58,6 +73,12 @@ priv_txq_start(struct priv *priv)
>  	return ret;
>  }
>  
> +/**
> + * Stop traffic on Rx queues.
> + *
> + * @param  priv

Extra space here also.

> + *   Pointer to private structure.
> + */
>  static void
>  priv_rxq_stop(struct priv *priv)
>  {
> @@ -67,6 +88,15 @@ priv_rxq_stop(struct priv *priv)
>  		mlx5_priv_rxq_release(priv, i);
>  }
>  
> +/**
> + * Start traffic on Rx queues.
> + *
> + * @param  priv

Again.

> + *   Pointer to private structure.
> + *
> + * @return
> + *   0 on success, errno on error.

Ditto regarding errno sign.

> + */
>  static int
>  priv_rxq_start(struct priv *priv)
>  {
> -- 
> 2.11.0
> 

There are other functions are not properly documented either, you might want
to add them for consistency:

mlx5_ethdev.c:
- mlx5_dev_supported_ptypes_get (no documentation)
- mlx5_link_update_unlocked_gset (return value)
- mlx5_link_update_unlocked_gs (return value)
- priv_link_update (return value)
- mlx5_link_update (return value)

mlx5_flow.c:
- mlx5_flow_create_eth (return value)
- mlx5_flow_create_vlan (return value)
- mlx5_flow_create_ipv4 (return value)
- mlx5_flow_create_ipv6 (return value)
- mlx5_flow_create_udp (return value)
- mlx5_flow_create_tcp (return value)
- mlx5_flow_create_vxlan (return value)
- mlx5_flow_create_flag_mark (return value)
- priv_flow_create_drop_queue (return in case of error)
- priv_flow_verify (inconsistent @return syntax)

mlx5_glue.c:
- mlx5_glue_* (too many of them and those are basic wrappers, don't bother)

mlx5_mr.c:
- priv_mr_verify (inconsistent @return syntax)

mlx5_rxq.c:
- mlx5_priv_rxq_ibv_verify (ditto)
- mlx5_priv_rxq_verify (ditto)
- mlx5_priv_ind_table_ibv_verify (ditto)
- mlx5_priv_hrxq_ibv_verify (ditto)

mlx5_rxtx.c:
- mlx5_tx_burst_raw_vec
- mlx5_tx_burst_vec
- mlx5_rx_burst_vec
- priv_check_raw_vec_tx_support
- priv_check_vec_tx_support
- rxq_check_vec_support
- priv_check_vec_rx_support

mlx5_trigger.c:
- Those are taken care of by the current patch.

mlx5_txq.c:
- mlx5_priv_txq_ibv_verify (inconsistent @return syntax)
- mlx5_priv_txq_verify (ditto)

mlx5_vlan.c
- mlx5_vlan_offload_set (return value)

I think that's all.
Nélio Laranjeiro Feb. 28, 2018, 3:12 p.m. UTC | #2 
- Removes unused SR-IOV flag.
- Adds missing documentation on some functions.
- Removes the spin-lock on the private structure.
- Standardize the return values of all functions as discussed on the mailing
  list [1].

[1] https://dpdk.org/ml/archives/dev/2018-January/087991.html

Nelio Laranjeiro (10):
  net/mlx5: fix sriov flag
  net/mlx5: name parameters in function prototypes
  net/mlx5: mark parameters with unused attribute
  net/mlx5: normalize function prototypes
  net/mlx5: add missing function documentation
  net/mlx5: remove useless empty lines
  net/mlx5: remove control path locks
  net/mlx5: prefix all function with mlx5
  net/mlx5: change non failing function return values
  net/mlx5: standardize on negative errno values

 drivers/net/mlx5/mlx5.c          | 234 ++++++--------
 drivers/net/mlx5/mlx5.h          | 240 ++++++--------
 drivers/net/mlx5/mlx5_ethdev.c   | 611 +++++++++++++++--------------------
 drivers/net/mlx5/mlx5_flow.c     | 664 ++++++++++++++++++++-------------------
 drivers/net/mlx5/mlx5_mac.c      |  42 ++-
 drivers/net/mlx5/mlx5_mr.c       | 130 ++++----
 drivers/net/mlx5/mlx5_rss.c      | 159 ++++------
 drivers/net/mlx5/mlx5_rxmode.c   |  28 +-
 drivers/net/mlx5/mlx5_rxq.c      | 488 ++++++++++++++--------------
 drivers/net/mlx5/mlx5_rxtx.c     |  49 ++-
 drivers/net/mlx5/mlx5_rxtx.h     | 161 +++++-----
 drivers/net/mlx5/mlx5_rxtx_vec.c |  25 +-
 drivers/net/mlx5/mlx5_socket.c   | 115 ++++---
 drivers/net/mlx5/mlx5_stats.c    | 189 +++++------
 drivers/net/mlx5/mlx5_trigger.c  | 234 +++++++-------
 drivers/net/mlx5/mlx5_txq.c      | 229 +++++++-------
 drivers/net/mlx5/mlx5_vlan.c     |  93 ++----
 17 files changed, 1761 insertions(+), 1930 deletions(-)
Nélio Laranjeiro March 5, 2018, 12:20 p.m. UTC | #3 
- Removes unused SR-IOV flag.
- Adds missing documentation on some functions.
- Removes the spin-lock on the private structure.
- Standardize the return values of all functions as discussed on the mailing
  list [1].

[1] https://dpdk.org/ml/archives/dev/2018-January/087991.html

Changes in v2:

 - fix a segfault in Tx queue release.

Nelio Laranjeiro (10):
  net/mlx5: fix sriov flag
  net/mlx5: name parameters in function prototypes
  net/mlx5: mark parameters with unused attribute
  net/mlx5: normalize function prototypes
  net/mlx5: add missing function documentation
  net/mlx5: remove useless empty lines
  net/mlx5: remove control path locks
  net/mlx5: prefix all function with mlx5
  net/mlx5: change non failing function return values
  net/mlx5: standardize on negative errno values

 drivers/net/mlx5/mlx5.c          | 236 ++++++--------
 drivers/net/mlx5/mlx5.h          | 240 ++++++--------
 drivers/net/mlx5/mlx5_ethdev.c   | 611 +++++++++++++++--------------------
 drivers/net/mlx5/mlx5_flow.c     | 664 ++++++++++++++++++++-------------------
 drivers/net/mlx5/mlx5_mac.c      |  42 ++-
 drivers/net/mlx5/mlx5_mr.c       | 130 ++++----
 drivers/net/mlx5/mlx5_rss.c      | 159 ++++------
 drivers/net/mlx5/mlx5_rxmode.c   |  28 +-
 drivers/net/mlx5/mlx5_rxq.c      | 488 ++++++++++++++--------------
 drivers/net/mlx5/mlx5_rxtx.c     |  49 ++-
 drivers/net/mlx5/mlx5_rxtx.h     | 161 +++++-----
 drivers/net/mlx5/mlx5_rxtx_vec.c |  25 +-
 drivers/net/mlx5/mlx5_socket.c   | 115 ++++---
 drivers/net/mlx5/mlx5_stats.c    | 189 +++++------
 drivers/net/mlx5/mlx5_trigger.c  | 234 +++++++-------
 drivers/net/mlx5/mlx5_txq.c      | 229 +++++++-------
 drivers/net/mlx5/mlx5_vlan.c     |  93 ++----
 17 files changed, 1761 insertions(+), 1932 deletions(-)
Shahaf Shuler March 18, 2018, 6:33 a.m. UTC | #4 
Monday, March 5, 2018 2:21 PM, Nelio Laranjeiro:
> - Removes unused SR-IOV flag.
> - Adds missing documentation on some functions.
> - Removes the spin-lock on the private structure.
> - Standardize the return values of all functions as discussed on the mailing
>   list [1].
> 
> [1]
> https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdp
> dk.org%2Fml%2Farchives%2Fdev%2F2018-
> January%2F087991.html&data=02%7C01%7Cshahafs%40mellanox.com%7Cf0
> 6e83bf350d44ba5f8908d58293a839%7Ca652971c7d2e4d9ba6a4d149256f461b
> %7C0%7C0%7C636558493060723163&sdata=mlYhk19ixx42hzEmUguXNq8rUe
> H7%2F5EIAF3AJD%2F6%2FNA%3D&reserved=0
> 

Series applied to next-net-mlx, thanks.
Ferruh Yigit March 21, 2018, 5:34 p.m. UTC | #5 
On 3/18/2018 6:33 AM, Shahaf Shuler wrote:
> Monday, March 5, 2018 2:21 PM, Nelio Laranjeiro:
>> - Removes unused SR-IOV flag.
>> - Adds missing documentation on some functions.
>> - Removes the spin-lock on the private structure.
>> - Standardize the return values of all functions as discussed on the mailing
>>   list [1].
>>
>> [1]
>> https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdp
>> dk.org%2Fml%2Farchives%2Fdev%2F2018-
>> January%2F087991.html&data=02%7C01%7Cshahafs%40mellanox.com%7Cf0
>> 6e83bf350d44ba5f8908d58293a839%7Ca652971c7d2e4d9ba6a4d149256f461b
>> %7C0%7C0%7C636558493060723163&sdata=mlYhk19ixx42hzEmUguXNq8rUe
>> H7%2F5EIAF3AJD%2F6%2FNA%3D&reserved=0
>>
> 
> Series applied to next-net-mlx, thanks. 

This is a good cleanup thanks for the effort.
diff mbox

Patch

diff --git a/drivers/net/mlx5/mlx5_trigger.c b/drivers/net/mlx5/mlx5_trigger.c
index f5711a998..a70b13d52 100644
--- a/drivers/net/mlx5/mlx5_trigger.c
+++ b/drivers/net/mlx5/mlx5_trigger.c
@@ -14,6 +14,12 @@ 
 #include "mlx5_rxtx.h"
 #include "mlx5_utils.h"
 
+/**
+ * Stop traffic on Tx queues.
+ *
+ * @param  priv
+ *   Pointer to private structure.
+ */
 static void
 priv_txq_stop(struct priv *priv)
 {
@@ -23,6 +29,15 @@  priv_txq_stop(struct priv *priv)
 		mlx5_priv_txq_release(priv, i);
 }
 
+/**
+ * Start traffic on Tx queues.
+ *
+ * @param  priv
+ *   Pointer to private structure.
+ *
+ * @return
+ *   0 on success, errno on error.
+ */
 static int
 priv_txq_start(struct priv *priv)
 {
@@ -58,6 +73,12 @@  priv_txq_start(struct priv *priv)
 	return ret;
 }
 
+/**
+ * Stop traffic on Rx queues.
+ *
+ * @param  priv
+ *   Pointer to private structure.
+ */
 static void
 priv_rxq_stop(struct priv *priv)
 {
@@ -67,6 +88,15 @@  priv_rxq_stop(struct priv *priv)
 		mlx5_priv_rxq_release(priv, i);
 }
 
+/**
+ * Start traffic on Rx queues.
+ *
+ * @param  priv
+ *   Pointer to private structure.
+ *
+ * @return
+ *   0 on success, errno on error.
+ */
 static int
 priv_rxq_start(struct priv *priv)
 {