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
p4lang · Jun 18, 2020 · 16c55ee · 16c55ee
1 parent 0fd82c2
commit 16c55ee
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 46 deletions.
diff --git 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
@@ -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<W>`
 + an `enum` with an underlying type of `bit<W>`, 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<W>`, 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<W>` or `enum bit<W>`, 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, <X>)` annotation in
+the source code, then the P4Info `bitwidth` field should follow these
+rules:
+
+ * if `<X>` is `n`, where `n` is a positive integer, then the `bitwidth`
+   field should be assigned the value `n`
+ * if `<X>` is `bit<W>`, where `W` is a postive integer, then the
+   `bitwidth` field should be assigned value `W`
+ * if `<X>` 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 `<X>` are illegal
 
 Otherwise, `bitwidth` should be equal to `W` where `bit<W>` or `enum
 bit<W>` 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
@@ -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 <[email protected]>
-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
@@ -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,