psa: document @groupaction annotation for ActionSelector groups

[sanket-jadhav-cse]

Summary

Documents the @groupaction annotation in the PSA specification for use with ActionSelector group actions in P4Runtime one-shot action selector programming.

The feature was added to P4Runtime, and the follow-up discussion concluded that this annotation is architecture-specific and should be documented in the PSA specification rather than the base P4 language specification.

Changes

• Adds a Group Actions subsection to PSA Section 8.12, Action Selector.
• Documents that group actions execute logically before the selected member action.
• Defines @groupaction as required for group actions and restricts it to group-action use only.
• Documents that @groupaction cannot be combined with @tableonly or @defaultonly.
• Documents the one-shot P4Runtime limitation.
• Adds a PSA Reserved Annotations appendix entry for @groupaction.

Validation

• git diff --check
• make -C p4-16/psa

The build completed successfully. The environment emitted optional dependency warnings for rouge and prawn-gmagick; these do not affect this documentation change.

Related

• Support group_action field in ActionProfileActionSet p4runtime#594
• Details of new proposed annotation for specifying which action in a table-with-action-selector's actions list is the one for groups p4runtime#605
• Update P4 Spec with group_actions #1392

[matthewtlam]

Thanks for a nice first attempt @Sanketjadhav31. The language and semantics of this is a bit tricky

[matthewtlam]

Is _group action_ a formatting thing?

[jafingerhut]

According to AsciiDoc documentation, it is used to make the enclosed text italic: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

[matthewtlam]

Maybe we should make it explicit since english is not an obvious language. But we would say it cannot be used as a table entry and cannot be used a a table default action. The other way could be misinterpreted depending on the brackets or how the user reads it

[jafingerhut]

Perhaps the following might be more explicit, as a suggested replacement for the last sentence in the paragraph above?

As specified in the P4Runtime specification, attempting to use an action annotated with @groupaction as a table entry action or as a table default action must fail and return an appropriate error status.

[matthewtlam]

+1 to what the suggestion replacement

[matthewtlam]

single named --> non-group

[jafingerhut]

It also seems clear to simply say "Because an action ..." with no adjectives before "action"

[matthewtlam]

@jfingerh PTAL to see if we have the same understanding

[jafingerhut]

Looks good to me.

[jafingerhut]

@matthewtlam Please take a look at the most recent version to see if you approve.

[matthewtlam]

Thanks @Sanketjadhav31. LGTM!