adopted and modified P4-14 description on parser value set to P4-16 (#…

…602)

p4-16/spec/P4-16-spec.mdk

@@ -1403,6 +1403,7 @@ that may retain information across packets:
 
 - `table`s: Tables are read-only for the data plane, but their
   entries can be modified by the control-plane,
+
 - `extern` objects: many objects have state that can be read and
   written by the control plane and data plane. All constructs from the P4~14~ language
   version that encapsulate state (e.g., counters, meters, registers) are
@@ -4197,6 +4198,7 @@ instantiate a `control` block within a `parser`.
 parserLocalElement
     : constantDeclaration
     | variableDeclaration
+    | valueSetDeclaration
     | instantiation
     ;
 ~ End P4Grammar
@@ -4412,6 +4414,37 @@ select (p.tcp.port) {
 The expression `16w0 &&& 16w0xFC00` describes the set of 16-bit
 values whose most significant six bits are zero.
 
+Some targets may support parser value set, see Section [#sec-value-set]. Given
+a type `T` for the type parameter of the value set, the type of the value set
+is `set<T>`. The type of the value set must match to the type of all other
+`keysetExpression` in the same `select` expression. If there is a mismatch, the
+compiler must raise an error. The type of the values in the set must be one of
+bit<>, tuple, and struct.
+
+For example, to allow the control plane API to specify TCP reserved ports at
+runtime, one could write:
+
+~ Begin P4Example
+struct vsk_t {
+    @match(ternary)
+    bit<16> port;
+}
+value_set<vsk_t>(4) pvs;
+select (p.tcp.port) {
+    pvs: runtime_defined_port;
+    _: other_port;
+}
+~ End P4Example
+
+The above example allows the runtime API to populate up to 4 different
+`keysetExpression`s in the `value_set`. If the `value_set` takes a struct
+as type parameter, the runtime API can use the struct field names to
+name the objects in the value set. The match type of the struct field is
+specified with the `@match` annotation. If the `@match` annotation is not
+specified on a struct field, by default it is assumed to be `@match(exact)`.
+A single non-exact field must be placed into a struct by itself, with the
+desired `@match` annotation.
+
 ## verify { #sec-verify }
 
 The `verify` statement provides a simple form of error
@@ -4815,6 +4848,39 @@ the time budget allocated for parsing, the parser should transition to
 `reject` and set
 the standard error `error.ParserTimeout`.
 
+##  Parser Value Sets { #sec-value-set }
+
+In some cases, the values that determine the transition from one parser state
+to another need to be determined at run time. MPLS is one example where the
+value of the MPLS label field is used to determine what headers follow the MPLS
+tag and this mapping may change dynamically at run time. To support this
+functionality, P4 supports the notion of a Parser Value Set. This is a named
+set of values with a run time API to add and remove values from the set.
+
+Value sets are declared locally within a parser. They should be declared before
+being referenced in parser `keysetExpression` and can be used as a label in a
+select expression.
+
+Parser Value Sets support a `size` argument to provide hints to the compiler to
+reserve hardware resource to implement the value set. For example, this parser
+value set:
+
+~ Begin P4Example
+value_set<bit<16>>(4) pvs;
+~ End P4Example
+
+creates a value_set of size 4 with entries of type `bit<16>`.
+
+The semantics of the `size` argument is similar to the `size` property of a
+table. If a value set has a `size` argument with value `N`, it is recommended
+that a compiler should choose a data plane implementation that is capable of
+storing `N` value set entries. See "Size property of P4 tables and parser value
+sets" [^P4SizeProperty] for further discussion on the implementation of parser
+value set size.
+
+The value set is populated by the control-plane by methods specified in the
+P4 Runtime specification.
+
 # Control blocks { #sec-control }
 
 P4 parsers are responsible for extracting bits from a packet into
@@ -6564,9 +6630,9 @@ This appendix summarizes restrictions on compile time and run time
 calls that can be made.  Many of them are described earlier in this
 document, but are collected here for easy reference.
 
-The stateful types of objects in P4~16~ are packages, parsers,
-controls, externs, and tables.  All other types are referred to as
-"value types" here.
+The stateful types of objects in P4~16~ are packages, parsers, controls,
+externs, tables, and value-sets.  All other types are referred to as "value
+types" here.
 
 Some guiding principles:
 
@@ -6583,6 +6649,9 @@ Some guiding principles:
   and cannot be instantiated at the top level.  There is no syntax for
   specifying parameters that are tables.  Tables are only intended to
   be used from within the control where they are defined.
+- Value-sets can be instantiated in an enclosing parser or at the top level.
+  There is no syntax for specifying parameters that are value-sets. Value-sets
+  can be shared between the parsers as long as they are in the scope.
 
 A note on recursion: It is expected that some architectures will
 define capabilities for recirculating a packet to be processed again
@@ -6604,6 +6673,7 @@ constructor parameters to other types.
 | control     | yes     |  no    | yes     |  no    |
 | extern      | yes     | yes    | yes     | yes    |
 | table       |  no     |  no    |  no     |  no    |
+| value-set   |  no     |  no    |  no     |  no    |
 | value types | yes     | yes    | yes     | yes    |
 |-------------|---------|--------|---------|--------|
 
@@ -6636,6 +6706,7 @@ program, but constants may.
 | control     |  no       |  no     | no      | yes     |  no    |
 | extern      | yes       |  no     | yes     | yes     |  no    |
 | table       |  no       |  no     | no      | yes     |  no    |
+| value-set   | yes       |  no     | yes     | no      |  no    |
 | value types | N/A       | N/A     |N/A      |N/A      | N/A    |
 |-------------|-----------|---------|---------|---------|--------|
 
@@ -6653,6 +6724,7 @@ parameters: parsers, controls, extern methods, and actions.
 | control     |  no       |  no     | no      | no      |
 | extern      | yes       | yes     | yes     | no      |
 | table       |  no       |  no     | no      | no      |
+| value-set   |  no       |  no     | no      | no      |
 | value types | yes       | yes     | yes     | yes     |
 |-------------|-----------|---------|---------|---------|
 
@@ -6661,8 +6733,9 @@ type, or no value at all (specified by a return type of `void`).
 
 The next table lists restrictions on what kinds of calls can be made
 from which places in a P4 program.  Calling a parser, control, or
-table means invoking its `apply()` method.  The row for `extern`
-describes where extern method calls can be made from.
+table means invoking its `apply()` method. Calling a value-set means using it
+in a select expression. The row for `extern` describes where extern method
+calls can be made from.
 
 One way that an extern can be called from the top level of a parser or
 control is in an initializer expression for a declared variable,
@@ -6680,6 +6753,7 @@ e.g. `bit<32> x = rand.get();`.
 | control     |  no       | yes     | no        | no      | no     |
 | extern      | yes       | yes     | yes       | yes     | no     |
 | table       |  no       | yes     | no        | no      | no     |
+| value-set   | yes       | no      | no        | no      | no     |
 | action      |  no       | yes     | no        | yes     | no     |
 | value types | N/A       | N/A     | N/A       | N/A     | N/A    |
 |-------------|-----------|---------|-----------|---------|--------|