PSA Annotations to specify packet ordering constraints

[jafingerhut]

This issue was raised by @jamescoole-cisco on this PR: #552

Creating a separate issue for it, to allow that PR to be merged in before we have answers for this issue.

[jafingerhut]

Comment by @jamescoole-cisco copied and pasted here:

Since a subset of applications will care about ordering, I think it would be good to recommend or require that implementors provide a way for users to request that the compiler preserve ordering per-application. A simple way to expose this would be a compiler switch, but a #pragma like used for OpenCL extensions might be better so that the requirement travels with the application source.

https://www.khronos.org/registry/OpenCL/sdk/1.0/docs/man/xhtml/EXTENSION.html

This seems like an improvement over "asking the vendor" for a couple of reasons.

First, without being able to specify this as a requirement in the source, portability becomes a function of whether the application compiles on a given target and whatever response the user got if/when they asked the switch vendor about ordering guarantees.

Also, for some targets whether these recommendations are met might not come directly from the device architecture, and might instead be possible with some tradeoffs. For example, a high-level synthesis tool may be able to increase parallelism when ordering isn't required by the program, but could support ordering when required by linearizing the pipeline, at the cost of latency and/or area.

[jafingerhut]

James, definitely reasonable suggestions there. The only part I am hesitating on is a good way to define and name such annotations/pragmas in the source code. I could imagine starting with a separate PSA-standard name for each of the 4 recommendations described in the text here, but suspect that there might be variations on them that will end up being useful.

Maybe we just stick a stake in the sand and give PSA-standard names to these 4 recommendations for now, and handle future ones as they become clearer?

[jafingerhut]

In another issue, @mbudiu-vmw proposed that for 'global' pragma type things, one way might be to have a global const definition, e.g. for a program version number with a standard-defined const name, and then P4_16 annotations can be put on that const definition. Those would be considered global annotations applying to the whole program.

[jamescoole-cisco]

Yep, I think it makes sense to just define names for the four current recommendations so that each can be required by a program.

If there are other guarantees that architectures want to offer, those could be vendor extensions handled similarly to PSA's defined names. If they become popular, they could be rolled into future PSAs with standardized names.

Using annotations may be better than adding pragmas, but would they need to be pinned to a top-level variable declaration? It might be confusing to mix variable and pragma naming. How about something like this?

@ordering("psa_RECOMMENDATION_1") // standard
@ordering("acme_<>") // vendor
PSA_Switch(/*...*/) main;

[mihaibudiu]

Of course, main is the right place for the annotations!
Strings are not checked by the compiler, so if you can use other types there it would be better.
Annotations always take expressions, and not types; that may be a problem. You cannot say
@convert(bit<32>)

[jamescoole-cisco]

I don't think type arguments are needed for this annotation, but it might be a useful language extension for other use cases.