net/mlx5: HWS, updated API functions comments to kernel doc

Changed all the functions comments to adhere with kernel-doc formatting.
Signed-off-by: Yevgeny Kliteynik <kliteyn@nvidia.com>
Signed-off-by: Saeed Mahameed <saeedm@nvidia.com>
Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
Link: https://patch.msgid.link/20240911201757.1505453-2-saeed@kernel.orgSigned-off-by: Jakub Kicinski <kuba@kernel.org>

drivers/net/ethernet/mellanox/mlx5/core/steering/hws/mlx5hws.h

@@ -214,11 +214,12 @@ struct mlx5hws_action_dest_attr {
 	struct mlx5hws_action *reformat;
 };
 
-/* Check whether HWS is supported
+/**
+ * mlx5hws_is_supported - Check whether HWS is supported
  *
- * @param[in] mdev
- *	The device to check.
- * @return true if supported, false otherwise.
+ * @mdev: The device to check.
+ *
+ * Return: true if supported, false otherwise.
  */
 static inline bool mlx5hws_is_supported(struct mlx5_core_dev *mdev)
 {
@@ -234,92 +235,94 @@ static inline bool mlx5hws_is_supported(struct mlx5_core_dev *mdev)
 	return wqe_based_flow_table_update && ignore_flow_level_rtc_valid;
 }
 
-/* Open a context used for direct rule insertion using hardware steering.
- * Each context can contain multiple tables of different types.
+/**
+ * mlx5hws_context_open - Open a context used for direct rule insertion
+ * using hardware steering.
+ *
+ * @mdev: The device to be used for HWS.
+ * @attr: Attributes used for context open.
  *
- * @param[in] mdev
- *	The device to be used for HWS.
- * @param[in] attr
- *	Attributes used for context open.
- * @return pointer to mlx5hws_context on success NULL otherwise.
+ * Return: pointer to mlx5hws_context on success NULL otherwise.
  */
 struct mlx5hws_context *
 mlx5hws_context_open(struct mlx5_core_dev *mdev,
 		     struct mlx5hws_context_attr *attr);
 
-/* Close a context used for direct hardware steering.
+/**
+ * mlx5hws_context_close - Close a context used for direct hardware steering.
  *
- * @param[in] ctx
- *	mlx5hws context to close.
- * @return zero on success non zero otherwise.
+ * @ctx: mlx5hws context to close.
+ *
+ * Return: zero on success non zero otherwise.
  */
 int mlx5hws_context_close(struct mlx5hws_context *ctx);
 
-/* Set a peer context, each context can have multiple contexts as peers.
+/**
+ * mlx5hws_context_set_peer - Set a peer context.
+ * Each context can have multiple contexts as peers.
  *
- * @param[in] ctx
- *	The context in which the peer_ctx will be peered to it.
- * @param[in] peer_ctx
- *	The peer context.
- * @param[in] peer_vhca_id
- *	The peer context vhca id.
+ * @ctx: The context in which the peer_ctx will be peered to it.
+ * @peer_ctx: The peer context.
+ * @peer_vhca_id: The peer context vhca id.
  */
 void mlx5hws_context_set_peer(struct mlx5hws_context *ctx,
 			      struct mlx5hws_context *peer_ctx,
 			      u16 peer_vhca_id);
 
-/* Create a new direct rule table. Each table can contain multiple matchers.
+/**
+ * mlx5hws_table_create - Create a new direct rule table.
+ * Each table can contain multiple matchers.
+ *
+ * @ctx: The context in which the new table will be opened.
+ * @attr: Attributes used for table creation.
  *
- * @param[in] ctx
- *	The context in which the new table will be opened.
- * @param[in] attr
- *	Attributes used for table creation.
- * @return pointer to mlx5hws_table on success NULL otherwise.
+ * Return: pointer to mlx5hws_table on success NULL otherwise.
  */
 struct mlx5hws_table *
 mlx5hws_table_create(struct mlx5hws_context *ctx,
 		     struct mlx5hws_table_attr *attr);
 
-/* Destroy direct rule table.
+/**
+ * mlx5hws_table_destroy - Destroy direct rule table.
  *
- * @param[in] tbl
- *	Table to destroy.
- * @return zero on success non zero otherwise.
+ * @tbl: Table to destroy.
+ *
+ * Return: zero on success non zero otherwise.
  */
 int mlx5hws_table_destroy(struct mlx5hws_table *tbl);
 
-/* Get ID of the flow table.
+/**
+ * mlx5hws_table_get_id() - Get ID of the flow table.
+ *
+ * @tbl:Table to get ID of.
  *
- * @param[in] tbl
- *	Table to get ID of.
- * @return ID of the table.
+ * Return: ID of the table.
  */
 u32 mlx5hws_table_get_id(struct mlx5hws_table *tbl);
 
-/* Set default miss table for mlx5hws_table by using another mlx5hws_table
+/**
+ * mlx5hws_table_set_default_miss - Set default miss table for mlx5hws_table
+ * by using another mlx5hws_table.
  * Traffic which all table matchers miss will be forwarded to miss table.
  *
- * @param[in] tbl
- *	Source table
- * @param[in] miss_tbl
- *	Target (miss) table, or NULL to remove current miss table
- * @return zero on success non zero otherwise.
+ * @tbl: Source table
+ * @miss_tbl: Target (miss) table, or NULL to remove current miss table
+ *
+ * Return: zero on success non zero otherwise.
  */
 int mlx5hws_table_set_default_miss(struct mlx5hws_table *tbl,
 				   struct mlx5hws_table *miss_tbl);
 
-/* Create new match template based on items mask, the match template
- * will be used for matcher creation.
+/**
+ * mlx5hws_match_template_create - Create a new match template based on items mask.
+ * The match template will be used for matcher creation.
+ *
+ * @ctx: The context in which the new template will be created.
+ * @match_param: Describe the mask based on PRM match parameters.
+ * @match_param_sz: Size of match param buffer.
+ * @match_criteria_enable: Bitmap for each sub-set in match_criteria buffer.
  *
- * @param[in] ctx
- *	The context in which the new template will be created.
- * @param[in] match_param
- *	Describe the mask based on PRM match parameters
- * @param[in] match_param_sz
- *	Size of match param buffer
- * @param[in] match_criteria_enable
- *	Bitmap for each sub-set in match_criteria buffer
- * @return pointer to mlx5hws_match_template on success NULL otherwise
+ * Return: Pointer to mlx5hws_match_template on success, NULL otherwise.
  */
 struct mlx5hws_match_template *
 mlx5hws_match_template_create(struct mlx5hws_context *ctx,
@@ -327,52 +330,53 @@ mlx5hws_match_template_create(struct mlx5hws_context *ctx,
 			      u32 match_param_sz,
 			      u8 match_criteria_enable);
 
-/* Destroy match template.
+/**
+ * mlx5hws_match_template_destroy - Destroy a match template.
  *
- * @param[in] mt
- *	Match template to destroy.
- * @return zero on success non zero otherwise.
+ * @mt: Match template to destroy.
+ *
+ * Return: Zero on success, non-zero otherwise.
  */
 int mlx5hws_match_template_destroy(struct mlx5hws_match_template *mt);
 
-/* Create new action template based on action_type array, the action template
- * will be used for matcher creation.
+/**
+ * mlx5hws_action_template_create - Create a new action template based on an action_type array.
  *
- * @param[in] action_type
- *	An array of actions based on the order of actions which will be provided
+ * @action_type: An array of actions based on the order of actions which will be provided
  *               with rule_actions to mlx5hws_rule_create. The last action is marked
  *               using MLX5HWS_ACTION_TYP_LAST.
- * @return pointer to mlx5hws_action_template on success NULL otherwise
+ *
+ * Return: Pointer to mlx5hws_action_template on success, NULL otherwise.
  */
 struct mlx5hws_action_template *
 mlx5hws_action_template_create(enum mlx5hws_action_type action_type[]);
 
-/* Destroy action template.
+/**
+ * mlx5hws_action_template_destroy - Destroy action template.
  *
- * @param[in] at
- *	Action template to destroy.
- * @return zero on success non zero otherwise.
+ * @at: Action template to destroy.
+ *
+ * Return: zero on success non zero otherwise.
  */
 int mlx5hws_action_template_destroy(struct mlx5hws_action_template *at);
 
-/* Create a new direct rule matcher. Each matcher can contain multiple rules.
- * Matchers on the table will be processed by priority. Matching fields and
- * mask are described by the match template. In some cases multiple match
- * templates can be used on the same matcher.
- *
- * @param[in] table
- *	The table in which the new matcher will be opened.
- * @param[in] mt
- *	Array of match templates to be used on matcher.
- * @param[in] num_of_mt
- *	Number of match templates in mt array.
- * @param[in] at
- *	Array of action templates to be used on matcher.
- * @param[in] num_of_at
- *	Number of action templates in mt array.
- * @param[in] attr
- *	Attributes used for matcher creation.
- * @return pointer to mlx5hws_matcher on success NULL otherwise.
+/**
+ * mlx5hws_matcher_create - Create a new direct rule matcher.
+ *
+ * Each matcher can contain multiple rules. Matchers on the table will be
+ * processed by priority. Matching fields and mask are described by the
+ * match template. In some cases, multiple match templates can be used on
+ * the same matcher.
+ *
+ * @table: The table in which the new matcher will be opened.
+ * @mt: Array of match templates to be used on matcher.
+ * @num_of_mt: Number of match templates in mt array.
+ * @at: Array of action templates to be used on matcher.
+ * @num_of_at: Number of action templates in at array.
+ * @attr: Attributes used for matcher creation.
+ *
+ * Return: Pointer to mlx5hws_matcher on success, NULL otherwise.
+ *
  */
 struct mlx5hws_matcher *
 mlx5hws_matcher_create(struct mlx5hws_table *table,
@@ -382,81 +386,77 @@ mlx5hws_matcher_create(struct mlx5hws_table *table,
 		       u8 num_of_at,
 		       struct mlx5hws_matcher_attr *attr);
 
-/* Destroy direct rule matcher.
+/**
+ * mlx5hws_matcher_destroy - Destroy a direct rule matcher.
+ *
+ * @matcher: Matcher to destroy.
  *
- * @param[in] matcher
- *	Matcher to destroy.
- * @return zero on success non zero otherwise.
+ * Return: Zero on success, non-zero otherwise.
  */
 int mlx5hws_matcher_destroy(struct mlx5hws_matcher *matcher);
 
-/* Attach new action template to direct rule matcher.
+/**
+ * mlx5hws_matcher_attach_at - Attach a new action template to a direct rule matcher.
  *
- * @param[in] matcher
- *	Matcher to attach at to.
- * @param[in] at
- *	Action template to be attached to the matcher.
- * @return zero on success non zero otherwise.
+ * @matcher: Matcher to attach the action template to.
+ * @at: Action template to be attached to the matcher.
+ *
+ * Return: Zero on success, non-zero otherwise.
  */
 int mlx5hws_matcher_attach_at(struct mlx5hws_matcher *matcher,
 			      struct mlx5hws_action_template *at);
 
-/* Link two matchers and enable moving rules from src matcher to dst matcher.
- * Both matchers must be in the same table type, must be created with 'resizable'
- * property, and should have the same characteristics (e.g. same mt, same at).
+/**
+ * mlx5hws_matcher_resize_set_target - Link two matchers and enable moving rules.
  *
- * It is the user's responsibility to make sure that the dst matcher
- * was allocated with the appropriate size.
+ * Both matchers must be in the same table type, must be created with the
+ * 'resizable' property, and should have the same characteristics (e.g., same
+ * match templates and action templates). It is the user's responsibility to
+ * ensure that the destination matcher is allocated with the appropriate size.
  *
  * Once the function is completed, the user is:
- *  - allowed to move rules from src into dst matcher
- *  - no longer allowed to insert rules to the src matcher
+ * - Allowed to move rules from the source into the destination matcher.
+ * - No longer allowed to insert rules into the source matcher.
  *
- * The user is always allowed to insert rules to the dst matcher and
+ * The user is always allowed to insert rules into the destination matcher and
  * to delete rules from any matcher.
  *
- * @param[in] src_matcher
- *	source matcher for moving rules from
- * @param[in] dst_matcher
- *	destination matcher for moving rules to
- * @return zero on successful move, non zero otherwise.
+ * @src_matcher: Source matcher for moving rules from.
+ * @dst_matcher: Destination matcher for moving rules to.
+ *
+ * Return: Zero on successful move, non-zero otherwise.
  */
 int mlx5hws_matcher_resize_set_target(struct mlx5hws_matcher *src_matcher,
 				      struct mlx5hws_matcher *dst_matcher);
 
-/* Enqueue moving rule operation: moving rule from src matcher to a dst matcher
+/**
+ * mlx5hws_matcher_resize_rule_move - Enqueue moving rule operation.
+ *
+ * This function enqueues the operation of moving a rule from the source
+ * matcher to the destination matcher.
+ *
+ * @src_matcher: Matcher that the rule belongs to.
+ * @rule: The rule to move.
+ * @attr: Rule attributes.
  *
- * @param[in] src_matcher
- *	matcher that the rule belongs to
- * @param[in] rule
- *	the rule to move
- * @param[in] attr
- *	rule attributes
- * @return zero on success, non zero otherwise.
+ * Return: Zero on success, non-zero otherwise.
  */
 int mlx5hws_matcher_resize_rule_move(struct mlx5hws_matcher *src_matcher,
 				     struct mlx5hws_rule *rule,
 				     struct mlx5hws_rule_attr *attr);
 
-/* Enqueue create rule operation.
- *
- * @param[in] matcher
- *	The matcher in which the new rule will be created.
- * @param[in] mt_idx
- *	Match template index to create the match with.
- * @param[in] match_param
- *	The match parameter PRM buffer used for the value matching.
- * @param[in] rule_actions
- *	Rule action to be executed on match.
- * @param[in] at_idx
- *	Action template index to apply the actions with.
- * @param[in] num_of_actions
- *	Number of rule actions.
- * @param[in] attr
- *	Rule creation attributes.
- * @param[in, out] rule_handle
- *	A valid rule handle. The handle doesn't require any initialization.
- * @return zero on successful enqueue non zero otherwise.
+/**
+ * mlx5hws_rule_create - Enqueue create rule operation.
+ *
+ * @matcher: The matcher in which the new rule will be created.
+ * @mt_idx: Match template index to create the match with.
+ * @match_param: The match parameter PRM buffer used for value matching.
+ * @at_idx: Action template index to apply the actions with.
+ * @rule_actions: Rule actions to be executed on match.
+ * @attr: Rule creation attributes.
+ * @rule_handle: A valid rule handle. The handle doesn't require any initialization.
+ *
+ * Return: Zero on successful enqueue, non-zero otherwise.
  */
 int mlx5hws_rule_create(struct mlx5hws_matcher *matcher,
 			u8 mt_idx,
@@ -466,114 +466,106 @@ int mlx5hws_rule_create(struct mlx5hws_matcher *matcher,
 			struct mlx5hws_rule_attr *attr,
 			struct mlx5hws_rule *rule_handle);
 
-/* Enqueue destroy rule operation.
+/**
+ * mlx5hws_rule_destroy - Enqueue destroy rule operation.
  *
- * @param[in] rule
- *	The rule destruction to enqueue.
- * @param[in] attr
- *	Rule destruction attributes.
- * @return zero on successful enqueue non zero otherwise.
+ * @rule: The rule destruction to enqueue.
+ * @attr: Rule destruction attributes.
+ *
+ * Return: Zero on successful enqueue, non-zero otherwise.
  */
 int mlx5hws_rule_destroy(struct mlx5hws_rule *rule,
 			 struct mlx5hws_rule_attr *attr);
 
-/* Enqueue update actions on an existing rule.
+/**
+ * mlx5hws_rule_action_update - Enqueue update actions on an existing rule.
+ *
+ * @rule: A valid rule handle to update.
+ * @at_idx: Action template index to update the actions with.
+ * @rule_actions: Rule actions to be executed on match.
+ * @attr: Rule update attributes.
  *
- * @param[in, out] rule_handle
- *	A valid rule handle to update.
- * @param[in] at_idx
- *	Action template index to update the actions with.
- *  @param[in] rule_actions
- *	Rule action to be executed on match.
- * @param[in] attr
- *	Rule update attributes.
- * @return zero on successful enqueue non zero otherwise.
+ * Return: Zero on successful enqueue, non-zero otherwise.
  */
 int mlx5hws_rule_action_update(struct mlx5hws_rule *rule,
 			       u8 at_idx,
 			       struct mlx5hws_rule_action rule_actions[],
 			       struct mlx5hws_rule_attr *attr);
 
-/* Get action type.
+/**
+ * mlx5hws_action_get_type - Get action type.
  *
- * @param[in] action
- *	The action to get the type of.
- * @return action type.
+ * @action: The action to get the type of.
+ *
+ * Return: action type.
  */
 enum mlx5hws_action_type
 mlx5hws_action_get_type(struct mlx5hws_action *action);
 
-/* Create direct rule drop action.
+/**
+ * mlx5hws_action_create_dest_drop - Create a direct rule drop action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: Pointer to mlx5hws_action on success, NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_dest_drop(struct mlx5hws_context *ctx,
 				u32 flags);
 
-/* Create direct rule default miss action.
- * Defaults are RX: Drop TX: Wire.
+/**
+ * mlx5hws_action_create_default_miss - Create a direct rule default miss action.
+ * Defaults are RX: Drop, TX: Wire.
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * @ctx: The context in which the new action will be created.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: Pointer to mlx5hws_action on success, NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_default_miss(struct mlx5hws_context *ctx,
 				   u32 flags);
 
-/* Create direct rule goto table action.
+/**
+ * mlx5hws_action_create_dest_table - Create direct rule goto table action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @tbl: Destination table.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] tbl
- *	Destination table.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_dest_table(struct mlx5hws_context *ctx,
 				 struct mlx5hws_table *tbl,
 				 u32 flags);
 
-/* Create direct rule goto table number action.
+/**
+ * mlx5hws_action_create_dest_table_num - Create direct rule goto table number action.
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] tbl_num
- *	Destination table number.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * @ctx: The context in which the new action will be created.
+ * @tbl_num: Destination table number.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_dest_table_num(struct mlx5hws_context *ctx,
-				     u32 table_num, u32 flags);
-
-/* Create direct rule range match action.
- *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] field
- *	Field to comapare the value.
- * @param[in] hit_ft
- *	Flow table to go to on hit.
- * @param[in] miss_ft
- *	Flow table to go to on miss.
- * @param[in] min
- *	Minimal value of the field to be considered as hit.
- * @param[in] max
- *	Maximal value of the field to be considered as hit.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+				     u32 tbl_num, u32 flags);
+
+/**
+ * mlx5hws_action_create_dest_match_range - Create direct rule range match action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @field: Field to comapare the value.
+ * @hit_ft: Flow table to go to on hit.
+ * @miss_ft: Flow table to go to on miss.
+ * @min: Minimal value of the field to be considered as hit.
+ * @max: Maximal value of the field to be considered as hit.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_dest_match_range(struct mlx5hws_context *ctx,
@@ -582,33 +574,29 @@ mlx5hws_action_create_dest_match_range(struct mlx5hws_context *ctx,
 				       struct mlx5_flow_table *miss_ft,
 				       u32 min, u32 max, u32 flags);
 
-/* Create direct rule flow sampler action.
+/**
+ * mlx5hws_action_create_flow_sampler - Create direct rule flow sampler action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @sampler_id: Flow sampler object ID.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] sampler_id
- *	Flow sampler object ID.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_flow_sampler(struct mlx5hws_context *ctx,
 				   u32 sampler_id, u32 flags);
 
-/* Create direct rule goto vport action.
+/**
+ * mlx5hws_action_create_dest_vport - Create direct rule goto vport action.
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] vport_num
- *	Destination vport number.
- * @param[in] vhca_id_valid
- *	Tells if the vhca_id parameter is valid.
- * @param[in] vhca_id
- *	VHCA ID of the destination vport.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * @ctx: The context in which the new action will be created.
+ * @vport_num: Destination vport number.
+ * @vhca_id_valid: Tells if the vhca_id parameter is valid.
+ * @vhca_id: VHCA ID of the destination vport.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_dest_vport(struct mlx5hws_context *ctx,
@@ -617,48 +605,42 @@ mlx5hws_action_create_dest_vport(struct mlx5hws_context *ctx,
 				 u16 vhca_id,
 				 u32 flags);
 
-/* Create direct rule TAG action.
+/**
+ * mlx5hws_action_create_tag - Create direct rule TAG action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
-mlx5hws_action_create_tag(struct mlx5hws_context *ctx,
-			  u32 flags);
+mlx5hws_action_create_tag(struct mlx5hws_context *ctx, u32 flags);
 
-/* Create direct rule counter action.
+/**
+ * mlx5hws_action_create_counter - Create direct rule counter action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @obj_id: Direct rule counter object ID.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] obj_id
- *	Direct rule counter object ID.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_counter(struct mlx5hws_context *ctx,
 			      u32 obj_id,
 			      u32 flags);
 
-/* Create direct rule reformat action.
- *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] reformat_type
- *	Type of reformat prefixed with MLX5HWS_ACTION_TYP_REFORMAT.
- * @param[in] num_of_hdrs
- *	Number of provided headers in "hdrs" array.
- * @param[in] hdrs
- *	Headers array containing header information.
- * @param[in] log_bulk_size
- *	Number of unique values used with this reformat.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+/**
+ * mlx5hws_action_create_reformat - Create direct rule reformat action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @reformat_type: Type of reformat prefixed with MLX5HWS_ACTION_TYP_REFORMAT.
+ * @num_of_hdrs: Number of provided headers in "hdrs" array.
+ * @hdrs: Headers array containing header information.
+ * @log_bulk_size: Number of unique values used with this reformat.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_reformat(struct mlx5hws_context *ctx,
@@ -668,19 +650,16 @@ mlx5hws_action_create_reformat(struct mlx5hws_context *ctx,
 			       u32 log_bulk_size,
 			       u32 flags);
 
-/* Create direct rule modify header action.
+/**
+ * mlx5hws_action_create_modify_header - Create direct rule modify header action.
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] num_of_patterns
- *	Number of provided patterns in "patterns" array.
- * @param[in] patterns
- *	Patterns array containing pattern information.
- * @param[in] log_bulk_size
- *	Number of unique values used with this pattern.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * @ctx: The context in which the new action will be created.
+ * @num_of_patterns: Number of provided patterns in "patterns" array.
+ * @patterns: Patterns array containing pattern information.
+ * @log_bulk_size: Number of unique values used with this pattern.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_modify_header(struct mlx5hws_context *ctx,
@@ -689,17 +668,16 @@ mlx5hws_action_create_modify_header(struct mlx5hws_context *ctx,
 				    u32 log_bulk_size,
 				    u32 flags);
 
-/* Create direct rule ASO flow meter action.
+/**
+ * mlx5hws_action_create_aso_meter - Create direct rule ASO flow meter action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @obj_id: ASO object ID.
+ * @return_reg_c: Copy the ASO object value into this reg_c,
+ *		  after a packet hits a rule with this ASO object.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] obj_id
- *	ASO object ID.
- * @param[in] return_reg_c
- *	Copy the ASO object value into this reg_c, after a packet hits a rule with this ASO object.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_aso_meter(struct mlx5hws_context *ctx,
@@ -707,42 +685,41 @@ mlx5hws_action_create_aso_meter(struct mlx5hws_context *ctx,
 				u8 return_reg_c,
 				u32 flags);
 
-/* Create direct rule pop vlan action.
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+/**
+ * mlx5hws_action_create_pop_vlan - Create direct rule pop vlan action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_pop_vlan(struct mlx5hws_context *ctx, u32 flags);
 
-/* Create direct rule push vlan action.
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+/**
+ * mlx5hws_action_create_push_vlan - Create direct rule push vlan action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_push_vlan(struct mlx5hws_context *ctx, u32 flags);
 
-/* Create a dest array action, this action can duplicate packets and forward to
- * multiple destinations in the destination list.
- * @param[in] ctx
- *     The context in which the new action will be created.
- * @param[in] num_dest
- *     The number of dests attributes.
- * @param[in] dests
- *     The destination array. Each contains a destination action and can have
- *     additional actions.
- * @param[in] ignore_flow_level
- *     Boolean that says whether to turn on 'ignore_flow_level' for this dest.
- * @param[in] flow_source
- *     Source port of the traffic for this actions.
- * @param[in] flags
- *     Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+/**
+ * mlx5hws_action_create_dest_array - Create a dest array action, this action can
+ * duplicate packets and forward to multiple destinations in the destination list.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @num_dest: The number of dests attributes.
+ * @dests: The destination array. Each contains a destination action and can
+ *	   have additional actions.
+ * @ignore_flow_level: Whether to turn on 'ignore_flow_level' for this dest.
+ * @flow_source: Source port of the traffic for this actions.
+ * @flags: Action creation flags (enum mlx5hws_action_flags).
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_dest_array(struct mlx5hws_context *ctx,
@@ -752,19 +729,16 @@ mlx5hws_action_create_dest_array(struct mlx5hws_context *ctx,
 				 u32 flow_source,
 				 u32 flags);
 
-/* Create insert header action.
+/**
+ * mlx5hws_action_create_insert_header - Create insert header action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @num_of_hdrs: Number of provided headers in "hdrs" array.
+ * @hdrs: Headers array containing header information.
+ * @log_bulk_size: Number of unique values used with this insert header.
+ * @flags: Action creation flags. (enum mlx5hws_action_flags)
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] num_of_hdrs
- *	Number of provided headers in "hdrs" array.
- * @param[in] hdrs
- *	Headers array containing header information.
- * @param[in] log_bulk_size
- *	Number of unique values used with this insert header.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_insert_header(struct mlx5hws_context *ctx,
@@ -773,38 +747,38 @@ mlx5hws_action_create_insert_header(struct mlx5hws_context *ctx,
 				    u32 log_bulk_size,
 				    u32 flags);
 
-/* Create remove header action.
+/**
+ * mlx5hws_action_create_remove_header - Create remove header action.
  *
- * @param[in] ctx
- *	The context in which the new action will be created.
- * @param[in] attr
- *	attributes: specifies the remove header type, PRM start anchor and
+ * @ctx: The context in which the new action will be created.
+ * @attr: attributes that specifie the remove header type, PRM start anchor and
  *	  the PRM end anchor or the PRM start anchor and remove size in bytes.
- * @param[in] flags
- *	Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * @flags: Action creation flags. (enum mlx5hws_action_flags)
+ *
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_remove_header(struct mlx5hws_context *ctx,
 				    struct mlx5hws_action_remove_header_attr *attr,
 				    u32 flags);
 
-/* Create direct rule LAST action.
+/**
+ * mlx5hws_action_create_last - Create direct rule LAST action.
+ *
+ * @ctx: The context in which the new action will be created.
+ * @flags: Action creation flags. (enum mlx5hws_action_flags)
  *
- * @param[in] ctx
- *     The context in which the new action will be created.
- * @param[in] flags
- *     Action creation flags. (enum mlx5hws_action_flags)
- * @return pointer to mlx5hws_action on success NULL otherwise.
+ * Return: pointer to mlx5hws_action on success NULL otherwise.
  */
 struct mlx5hws_action *
 mlx5hws_action_create_last(struct mlx5hws_context *ctx, u32 flags);
 
-/* Destroy direct rule action.
+/**
+ * mlx5hws_action_destroy - Destroy direct rule action.
  *
- * @param[in] action
- *	The action to destroy.
- * @return zero on success non zero otherwise.
+ * @action: The action to destroy.
+ *
+ * Return: zero on success non zero otherwise.
  */
 int mlx5hws_action_destroy(struct mlx5hws_action *action);
 
@@ -818,42 +792,40 @@ struct mlx5hws_flow_op_result {
 	void *user_data;
 };
 
-/* Poll queue for rule creation and deletions completions.
+/**
+ * mlx5hws_send_queue_poll - Poll queue for rule creation and deletions completions.
+ *
+ * @ctx: The context to which the queue belong to.
+ * @queue_id: The id of the queue to poll.
+ * @res: Completion array.
+ * @res_nb: Maximum number of results to return.
  *
- * @param[in] ctx
- *	The context to which the queue belong to.
- * @param[in] queue_id
- *	The id of the queue to poll.
- * @param[in, out] res
- *	Completion array.
- * @param[in] res_nb
- *	Maximum number of results to return.
- * @return negative number on failure, the number of completions otherwise.
+ * Return: negative number on failure, the number of completions otherwise.
  */
 int mlx5hws_send_queue_poll(struct mlx5hws_context *ctx,
 			    u16 queue_id,
 			    struct mlx5hws_flow_op_result res[],
 			    u32 res_nb);
 
-/* Perform an action on the queue
+/**
+ * mlx5hws_send_queue_action - Perform an action on the queue
  *
- * @param[in] ctx
- *	The context to which the queue belong to.
- * @param[in] queue_id
- *	The id of the queue to perform the action on.
- * @param[in] actions
- *	Actions to perform on the queue. (enum mlx5hws_send_queue_actions)
- * @return zero on success non zero otherwise.
+ * @ctx: The context to which the queue belong to.
+ * @queue_id: The id of the queue to perform the action on.
+ * @actions: Actions to perform on the queue (enum mlx5hws_send_queue_actions)
+ *
+ * Return: zero on success non zero otherwise.
  */
 int mlx5hws_send_queue_action(struct mlx5hws_context *ctx,
 			      u16 queue_id,
 			      u32 actions);
 
-/* Dump HWS info
+/**
+ * mlx5hws_debug_dump - Dump HWS info
+ *
+ * @ctx: The context which to dump the info from.
  *
- * @param[in] ctx
- *	The context which to dump the info from.
- * @return zero on success non zero otherwise.
+ * Return: zero on success non zero otherwise.
  */
 int mlx5hws_debug_dump(struct mlx5hws_context *ctx);
 
@@ -865,7 +837,9 @@ struct mlx5hws_match_parameters {
 	u32 *match_buf; /* Device spec format */
 };
 
-/* Create a new BWC direct rule matcher.
+/**
+ * mlx5hws_bwc_matcher_create - Create a new BWC direct rule matcher.
+ *
  * This function does the following:
  *   - creates match template based on flow items
  *   - creates an empty action template
@@ -875,15 +849,12 @@ struct mlx5hws_match_parameters {
  *   - table->ctx must have BWC support
  *   - complex rules are not supported
  *
- * @param[in] table
- *	The table in which the new matcher will be opened
- * @param[in] priority
- *	Priority for this BWC matcher
- * @param[in] match_criteria_enable
- *	Bitmask that defines matching criteria
- * @param[in] mask
- *	Match parameters
- * @return pointer to mlx5hws_bwc_matcher on success or NULL otherwise.
+ * @table: The table in which the new matcher will be opened
+ * @priority: Priority for this BWC matcher
+ * @match_criteria_enable: Bitmask that defines matching criteria
+ * @mask: Match parameters
+ *
+ * Return: pointer to mlx5hws_bwc_matcher on success or NULL otherwise.
  */
 struct mlx5hws_bwc_matcher *
 mlx5hws_bwc_matcher_create(struct mlx5hws_table *table,
@@ -891,15 +862,18 @@ mlx5hws_bwc_matcher_create(struct mlx5hws_table *table,
 			   u8 match_criteria_enable,
 			   struct mlx5hws_match_parameters *mask);
 
-/* Destroy BWC direct rule matcher.
+/**
+ * mlx5hws_bwc_matcher_destroy - Destroy BWC direct rule matcher.
  *
- * @param[in] bwc_matcher
- *	Matcher to destroy
- * @return zero on success, non zero otherwise
+ * @bwc_matcher: Matcher to destroy
+ *
+ * Return: zero on success, non zero otherwise
  */
 int mlx5hws_bwc_matcher_destroy(struct mlx5hws_bwc_matcher *bwc_matcher);
 
-/* Create a new BWC rule.
+/**
+ * mlx5hws_bwc_rule_create - Create a new BWC rule.
+ *
  * Unlike the usual rule creation function, this one is blocking: when the
  * function returns, the rule is written to its place (no need to poll).
  * This function does the following:
@@ -916,15 +890,12 @@ int mlx5hws_bwc_matcher_destroy(struct mlx5hws_bwc_matcher *bwc_matcher);
  *   - matcher->tbl->ctx must have BWC support
  *   - separate BWC ctx queues are used
  *
- * @param[in] bwc_matcher
- *	The BWC matcher in which the new rule will be created.
- * @param[in] params
- *	Match perameters
- * @param[in] flow_source
- *	Flow source for this rule
- * @param[in] rule_actions
- *	Rule action to be executed on match
- * @return valid BWC rule handle on success, NULL otherwise
+ * @bwc_matcher: The BWC matcher in which the new rule will be created.
+ * @params: Match perameters
+ * @flow_source: Flow source for this rule
+ * @rule_actions: Rule action to be executed on match
+ *
+ * Return: valid BWC rule handle on success, NULL otherwise
  */
 struct mlx5hws_bwc_rule *
 mlx5hws_bwc_rule_create(struct mlx5hws_bwc_matcher *bwc_matcher,
@@ -932,21 +903,22 @@ mlx5hws_bwc_rule_create(struct mlx5hws_bwc_matcher *bwc_matcher,
 			u32 flow_source,
 			struct mlx5hws_rule_action rule_actions[]);
 
-/* Destroy BWC direct rule.
+/**
+ * mlx5hws_bwc_rule_destroy - Destroy BWC direct rule.
+ *
+ * @bwc_rule: Rule to destroy.
  *
- * @param[in] bwc_rule
- *	Rule to destroy
- * @return zero on success, non zero otherwise
+ * Return: zero on success, non zero otherwise.
  */
 int mlx5hws_bwc_rule_destroy(struct mlx5hws_bwc_rule *bwc_rule);
 
-/* Update actions on an existing BWC rule.
+/**
+ * mlx5hws_bwc_rule_action_update - Update actions on an existing BWC rule.
+ *
+ * @bwc_rule: Rule to update
+ * @rule_actions: Rule action to update with
  *
- * @param[in] bwc_rule
- *	Rule to update
- * @param[in] rule_actions
- *	Rule action to update with
- * @return zero on successful update, non zero otherwise.
+ * Return: zero on successful update, non zero otherwise.
  */
 int mlx5hws_bwc_rule_action_update(struct mlx5hws_bwc_rule *bwc_rule,
 				   struct mlx5hws_rule_action rule_actions[]);