From patchwork Wed Sep 11 20:17:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Saeed Mahameed X-Patchwork-Id: 13801047 X-Patchwork-Delegate: kuba@kernel.org Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 736591BA883 for ; Wed, 11 Sep 2024 20:18:01 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1726085881; cv=none; b=hMFtH6DhLFLvGzXKZqpgzZCRuAauzsfwNFuhxJsqpo3KyQt1rsO85Jdu+9IhHhh6u5nh+6Rb6KeDNTJm522R9zQkR2LfPVZBSWUNjOzrgt9ktPElsZaulxay2UGQN72ZRlB+R8fwxjHmZupJmjCPZ+r/U+YJJ9hY3vBKCRb049g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1726085881; c=relaxed/simple; bh=7qZ1F2VgJlPpLeccSdcT4WgbVy6DgDNw3zdU77a1A2w=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MVMRv2oFq41mz2xow4gLbUIKwQSQRGzcnjv/tVIEmbnWhYTz50TMBgC7erv922crtUesOkpgtdM45zHcG63EnLS/gWooBWWvUFynJyOfywWGNHz6xgCMp8c/lzMqqND/T26xDFFAdNvHNEMFZFWal6wcQxbrT1hRyS9Z3fAxuWg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=EPZxPItq; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="EPZxPItq" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E9BB8C4CEC0; Wed, 11 Sep 2024 20:18:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1726085881; bh=7qZ1F2VgJlPpLeccSdcT4WgbVy6DgDNw3zdU77a1A2w=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EPZxPItqaQECXXxY9kBPrmeRptb60O59byRpFUNwmNKCObNNC7F4yot7VpUuzJPKK eyvulV+D+EcAESmIAouToYnVyVG6PMk8pm7BA6zLtF37D4fGY5weVYV0G67Hg1fmfO NfaJyC43vHv1Aif6kpmPvL/KPmBFAnXPYi79L9jg5H+dP8ZiX0555fryttuzZZMMYA mgCk3K3F8FmdSXgYX5Q3DFo3DDg6PW985xKpS+T8qQz7I5N6xfPgiceyL5WPHhwvDZ lWeEp+wH9WhJqU3XE6SrChSrkjI5JIpCP+RrzI0jl/jrtYaxXKnJJNEu6VDVCDMFVb 9Fwhe7MqltD+Q== From: Saeed Mahameed To: "David S. Miller" , Jakub Kicinski , Paolo Abeni , Eric Dumazet Cc: Saeed Mahameed , netdev@vger.kernel.org, Tariq Toukan , Gal Pressman , Leon Romanovsky , Yevgeny Kliteynik Subject: [net-next 01/15] net/mlx5: HWS, updated API functions comments to kernel doc Date: Wed, 11 Sep 2024 13:17:43 -0700 Message-ID: <20240911201757.1505453-2-saeed@kernel.org> X-Mailer: git-send-email 2.46.0 In-Reply-To: <20240911201757.1505453-1-saeed@kernel.org> References: <20240911201757.1505453-1-saeed@kernel.org> Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Patchwork-Delegate: kuba@kernel.org From: Yevgeny Kliteynik Changed all the functions comments to adhere with kernel-doc formatting. Signed-off-by: Yevgeny Kliteynik Signed-off-by: Saeed Mahameed Reviewed-by: Jacob Keller --- .../mellanox/mlx5/core/steering/hws/mlx5hws.h | 756 +++++++++--------- 1 file changed, 364 insertions(+), 392 deletions(-) diff --git a/drivers/net/ethernet/mellanox/mlx5/core/steering/hws/mlx5hws.h b/drivers/net/ethernet/mellanox/mlx5/core/steering/hws/mlx5hws.h index 9a85d4e12f77..f39d636ff39a 100644 --- a/drivers/net/ethernet/mellanox/mlx5/core/steering/hws/mlx5hws.h +++ b/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. + * + * @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. * - * @param[in] 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. * - * @param[in] matcher - * Matcher to destroy. - * @return zero on success non zero otherwise. + * @matcher: Matcher to destroy. + * + * 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. + * + * @matcher: Matcher to attach the action template to. + * @at: Action template to be attached to the 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. + * 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. * - * @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. + * @src_matcher: Matcher that the rule belongs to. + * @rule: The rule to move. + * @attr: Rule attributes. + * + * 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. + * + * @rule: The rule destruction to enqueue. + * @attr: Rule destruction attributes. * - * @param[in] rule - * The rule destruction to enqueue. - * @param[in] attr - * Rule destruction attributes. - * @return zero on successful enqueue non zero otherwise. + * 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. * - * @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. + * @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. + * + * 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. + * + * @action: The action to get the type of. * - * @param[in] action - * The action to get the type of. - * @return action type. + * 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. * - * @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_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. + * + * @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_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. * - * @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. + * @ctx: The context in which the new action will be created. + * @tbl: Destination table. + * @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(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. + * + * @ctx: The context in which the new action will be created. + * @tbl_num: Destination table number. + * @flags: Action creation flags (enum mlx5hws_action_flags). * - * @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. + * 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. * - * @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. + * @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). + * + * 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. + * + * @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). * - * @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. + * 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. * - * @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_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 - * 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. + * @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. + * @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[]);