From 16c55eebd887c949b59d6997bb2d841a59c6bb32 Mon Sep 17 00:00:00 2001 From: Antonin Bas Date: Fri, 5 Jun 2020 15:06:30 -0700 Subject: [PATCH] Changes for P4Runtime release 1.2.0-rc.1 * Update version to 1.2.0-rc.1 for release * Update references to P4_16 spec from 1.2.0 to 1.2.1 * Update companion documents --- docs/v1/P4Runtime-Spec.mdk | 23 ++++++++----- docs/v1/guidance-for-generating-p4info.md | 39 ++++++++++++++++------- docs/v1/p4runtime-id-notes.md | 16 ++-------- docs/v1/references.bib | 26 +++++++-------- 4 files changed, 58 insertions(+), 46 deletions(-) diff --git a/docs/v1/P4Runtime-Spec.mdk b/docs/v1/P4Runtime-Spec.mdk index 55dbaca4..8b985ca5 100755 --- a/docs/v1/P4Runtime-Spec.mdk +++ b/docs/v1/P4Runtime-Spec.mdk @@ -1,5 +1,5 @@ Title : P4Runtime Specification -Title Note: version 1.2.0-dev +Title Note: version 1.2.0-rc.1 Title Footer: &date; Author: The P4.org API Working Group Heading depth: 5 @@ -231,7 +231,7 @@ P4Runtime is designed to be implemented in conjunction with the P4~16~ language version or later. P4~14~ programs should be translated into P4~16~ to be made compatible with P4Runtime. This version of P4Runtime utilizes features which are not in P4~16~ 1.0, but were introduced in P4~16~ 1.1.0 [@P4Revisions110]. For -this version of P4Runtime, we recommend using P4~16~ 1.2.0 [@P4Spec]. +this version of P4Runtime, we recommend using P4~16~ 1.2.1 [@P4Spec]. ## In Scope @@ -6071,18 +6071,25 @@ man-in-the-middle attacks between the server and client. ## Revision History -### Changes in v1.2.0 (under development) +### Changes in v1.2.0 * Add new `OPTIONAL` match kind. At the moment, `OPTIONAL` is only supported by - the v1model architecture [@v1model], and not by PSA. We hope that it will be - included in the core P4 language by the time P4Runtime v1.2.0 is released. -* Added a new `metadata` field of type `bytes` to `TableEntry`. This is more + the v1model architecture [@v1model], and not by PSA. It will eventually be + included in the core P4 language. +* Add support in P4Info for structured annotations, which are used to annotate + objects with key-value lists or expression lists. +* Add a new `metadata` field of type `bytes` to `TableEntry`. This is more flexible than the now deprecated `controller_metadata` field. -* Added the ability to change the ID of table match fields, action parameters, +* Add the ability to change the ID of table match fields, action parameters, Packet IO metadata fields, and Value Set match fields in P4Info by using the `@id` annotation. -* Clarified the behavior of some corner cases involving action profiles and +* Clarify the behavior of some corner cases involving action profiles and selectors, including the watch port feature. +* Support using `string` as the controller type in the `@p4runtime_translation` + annotation. Update syntax when using a fixed-width unsigned bitstring as the + controller type. +* Add optional P4 source locations to both structured and unstructured + annotations. ### Changes in v1.1.0 diff --git a/docs/v1/guidance-for-generating-p4info.md b/docs/v1/guidance-for-generating-p4info.md index 1ddb1255..54262426 100644 --- a/docs/v1/guidance-for-generating-p4info.md +++ b/docs/v1/guidance-for-generating-p4info.md @@ -38,7 +38,7 @@ representing the name of the library, its major version, etc. ## Handling P4_16 `type` and the `p4runtime_translation` annotation -The P4Runtime v1.1 specification restricts the types that it supports +The P4Runtime v1.2 specification restricts the types that it supports for the following kinds of things: + table search key fields, defined in the P4Info message in a @@ -54,16 +54,16 @@ for the following kinds of things: Later in this section, we will use the term "constrained value" for brevity, instead of repeating all of the kinds of objects listed -above. For such values, the P4Runtime specification v1.1 supports all +above. For such values, the P4Runtime specification v1.2 supports all of the following types, but currently no others: + `bit` + an `enum` with an underlying type of `bit`, also called a serializable `enum` (TBD whether all of the pieces needed to make - this work are actually supported for P4Runtime 1.1) + this work are actually supported for P4Runtime 1.2) + a `typedef` or `type` name that, when "followed back" to the lowest base type, is one of the above. (As of the P4_16 language - specification version 1.2.0, it is not required to support a `type` + specification version 1.2.1, it is not required to support a `type` definition with a serializable `enum` as its base type. See [p4runtime issue #192](https://github.com/p4lang/p4runtime/issues/192).) @@ -100,7 +100,7 @@ type_list(x) { Note that `type_list(x)` always starts with zero or more `type` names, and always ends with one type that is neither a `type` nor `typedef` name, e.g. `bit`, a header type, struct type, etc. It never -contains the name of a type declared using `typedef`. P4Runtime v1.1 +contains the name of a type declared using `typedef`. P4Runtime v1.2 only supports `p4runtime_translation` annotations on `type` definitions. If any such annotations occur on a `typedef` definition, they should be ignored. @@ -111,7 +111,7 @@ of type names. In order to create such a cycle, the first `type` or type name, and this is not allowed. If the last type is not `bit` or `enum bit`, that is an error -for P4Runtime v1.1. The "base" type must always be one of those for +for P4Runtime v1.2. The "base" type must always be one of those for every constrained value. @@ -131,10 +131,18 @@ message. ### `bitwidth` field If `first_type` is a `type` name, _and_ if the `type` definition for -this type has a `p4runtime_translation(uri_string, n)` annotation in -the source code, then the P4Info `bitwidth` field should be assigned -the value `n` that is the second parameter of that -`p4runtime_translation` annotation. +this type has a `p4runtime_translation(uri_string, )` annotation in +the source code, then the P4Info `bitwidth` field should follow these +rules: + + * if `` is `n`, where `n` is a positive integer, then the `bitwidth` + field should be assigned the value `n` + * if `` is `bit`, where `W` is a postive integer, then the + `bitwidth` field should be assigned value `W` + * if `` is `string`, then the `bitwidth` field should be unset + (which in Protobuf version 3 is the same as setting it explicitly to + 0) + * all other cases for `` are illegal Otherwise, `bitwidth` should be equal to `W` where `bit` or `enum bit` is the last element of `type_list(x)`. @@ -249,6 +257,13 @@ type T1_t T2_t; T2_t f3; ``` +Note that starting with P4Runtime v1.2.0, the following syntax for the +`p4runtime_translation` is equivalent (and preferred): +``` +@p4runtime_translation("mycompany.com/myco_p4lib/v1/T1_t", bit<32>) +type T1uint_t T1_t; +``` + ``` Execution trace for call to type_list(f3): tlist = [] @@ -351,7 +366,7 @@ definition of `T1_t` in the program, `type T1uint T1_t`, has a ## Example 4: field with a type defined via `type`, with `p4runtime_translation` annotation -This example is very similar to Example 3, except that both `type` +This example is very similar to Example 3, except that all three `type` definitions have a `p4runtime_translation` annotation. ``` @@ -443,7 +458,7 @@ message. Should `type_name` be `"enum1_t"`, and then `"enum1_t"` should be described within the `type_info` field of the message? -As of early March 2019, `p4c` does not support users defining their +As of early June 2020, `p4c` does not support users defining their own `type` definitions with a serializable `enum` like `enum1_t` as the base type. The disadvantage with this situation is that there is no way to define a serializable `enum` type for a constrained value, diff --git a/docs/v1/p4runtime-id-notes.md b/docs/v1/p4runtime-id-notes.md index 7ff61fb5..f69deda0 100644 --- a/docs/v1/p4runtime-id-notes.md +++ b/docs/v1/p4runtime-id-notes.md @@ -9,19 +9,9 @@ in one place notes on those identifiers, including: + When the values are chosen + What is their scope in "space" and time in which they must be unique -This document was written while referring to the P4Runtime API -specification as of this commit of the Github repository -https://github.com/p4lang/p4runtime - -``` -commit c9cd4af17c2d562d6e4ec760237f16fea9558fcb -Author: Chris Sommers <31145757+chrispsommers@users.noreply.github.com> -Date: Fri Mar 27 13:43:31 2020 -0700 -``` - -This is after version 1.1.0 of the specification was released, and it -is expected that version 1.2.0 will be released soon after this time, -with very few (if any) changes from the version above. +This document was written at the time of the release of P4Runtime +v1.2.0. If you refer to other P4Runtime specification versions, you may +find some small inconsistencies with respect to this document. Here is a complete list of Google Protobuf `.proto` files in this version of the p4lang/p4runtime repository: diff --git a/docs/v1/references.bib b/docs/v1/references.bib index cbe499f0..b1114ec0 100644 --- a/docs/v1/references.bib +++ b/docs/v1/references.bib @@ -31,7 +31,7 @@ @ONLINE { Stratum @ONLINE { P4ComplexTypes, title = "Complex types in $P4_{16}$", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-p4-type" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-p4-type" } @ONLINE { ProtoDefaults, @@ -47,27 +47,27 @@ @ONLINE { PIRepo @ONLINE { P4TableProperties, title = "Table properties in $P4_{16}$", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-table-props" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-table-props" } @ONLINE { P4ValueSets, title = "Value Sets in $P4_{16}$", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-value-set" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-value-set" } @ONLINE { P4SelectExpr, title = "Select expressions in $P4_{16}$", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-select" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-select" } @ONLINE { P4Revisions110, title = "Summary of changes made in $P4_{16}$ version 1.1.0", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-summary-of-changes-made-in-version-110" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-summary-of-changes-made-in-version-110" } @ONLINE { P4Spec, - title = "$P4_{16}$ 1.2.0 specification", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html" + title = "$P4_{16}$ 1.2.1 specification", + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html" } @ONLINE { PSA, @@ -77,7 +77,7 @@ @ONLINE { PSA @ONLINE { P4Enums, title = "Enums in $P4_{16}$", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-enum-types" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-enum-types" } @ONLINE { ProtoAny, @@ -113,7 +113,7 @@ @ONLINE { P4APIWGCharter @ONLINE { P4NewTypes, title = "Introducing new types in $P4_{16}$", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-newtype" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-newtype" } @ONLINE { APIVersioning, @@ -138,7 +138,7 @@ @ONLINE { RFC2698 @ONLINE { P4MatchTypes, title = "Match types in P4", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-match-kind-type" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-match-kind-type" } @ONLINE { gRPCStreamC, @@ -153,7 +153,7 @@ @ONLINE { gRPCAuth @ONLINE { P4ActionAnnotations, title = "P4 standard annotations on table actions", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-table-action-anno" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-table-action-anno" } @ONLINE { PSAActionSelector, @@ -173,7 +173,7 @@ @ONLINE { PSAAtomicityOfControlPlaneOps @ONLINE { P4Concurrency, title = "P4 Concurrency Model", - url = "https://p4.org/p4-spec/docs/P4-16-v1.2.0.html#sec-concurrency" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-concurrency" } @ONLINE { PSATranslation, @@ -193,7 +193,7 @@ @ONLINE { ProtoOneOfBackwardsCompatibility @ONLINE { P4Annotations, title = "P4 Annotations", - url = "https://p4.org/p4-spec/docs/P4-16-working-spec.html#sec-annotations" + url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-annotations" } @ONLINE { v1model,