Fixes #491 update v1.4.0 changelog

README.md

@@ -144,9 +144,9 @@ processes.
    pull request against the specification that a key committer must review and
    approve.
 
-When updating the Protobuf files in a pull request, you will also need to update
+>**Generated protobuf files**: When updating the Protobuf files in a pull request, you will also need to update
 the generated Go and Python files, which are hosted in this repository under
-[go/](go/) and [py/](py/). This can be done easily by running `./codegen/update.sh`,
+[go/](go/) and [py/](py/). This can be done easily **by running `./codegen/update.sh`**,
 provided docker is installed and your user is part of the "docker" group
 (which means that the `docker` command can be executed without `sudo`).
 

docs/v1/P4Runtime-Spec.mdk

@@ -1546,6 +1546,11 @@ control plane. This message contains the following fields:
   set a different default action at runtime or change the default action's
   arguments.
 
+* `initial_default_action`, the default action that is executed with the
+   specified arguments when the table does not match.  If no explicit
+   default action is set, the identifier of this field will default to
+   the id of the `NoAction` action.
+
 * `implementation_id`, the `uint32` identifier of the "implementation" of this
   table. 0 (default value) means that the table is a regular (direct) match
   table. Otherwise, this field will carry the ID of an extern instance specified
@@ -1749,14 +1754,39 @@ Both `Meter` and `DirectMeter` messages share the following fields:
   extern instance.
 
 * `spec`, a message of type `MeterSpec` used to describe the capabilities of
-  this meter extern instance. Currently, the `MeterSpec` message is used to
-  carry only the meter unit, which can be any of the `MeterSpec.Unit` enum
-  values:
+  this meter extern instance. The `MeterSpec` message is used to describe the
+  meter unit and the meter type. The meter unit can be any of the
+  `MeterSpec.Unit` enum values:
     * `UNSPECIFIED`: reserved value.
     * `BYTES`, which signifies that this meter can be configured with rates
       expressed in bytes/second.
     * `PACKETS`, for rates expressed in packets/second.
 
+  The meter type can be any of the `MeterSpec.Type` enum values:
+    * `TWO_RATE_THREE_COLOR`: This is the *Two Rate Three Color Marker* (trTCM)
+      defined in RFC 2698 [@RFC2698]. This is the standard P4Runtime meter type
+      and allows meters to use two rates to split packets into three potential
+      colors: GREEN, YELLOW, or RED. This mode is the default, but can also be
+      set explicitly in a P4 program by adding the `@two_rate_three_color`
+      annotation to the meter definition.
+      For example, in a V1Model P4 program, we might define a trTCM direct meter
+      as follows:
+      ~ Begin P4Example
+      @two_rate_three_color
+      direct_meter<color_type>(MeterType.bytes) my_meter;
+      ~ End P4Example
+    * `SINGLE_RATE_THREE_COLOR`: This is the *Single Rate Three Color Marker*
+      (srTCM) defined in RFC 2697 [@RFC2697]. This allows meters to use one rate
+      and an Excess Burst Size (EBS) to split packets into three potential
+      colors: GREEN, YELLOW, or RED. In a P4 program, this mode can be set by
+      adding the `@single_rate_three_color` annotation to the meter definition.
+    * `SINGLE_RATE_TWO_COLOR`: This is a simplified version of RFC 2697
+      [@RFC2697], and the `SINGLE_RATE_THREE_COLOR` mode above.
+      `SINGLE_RATE_TWO_COLOR` restricts meters to use only a single rate
+      specified by the Committed Information Rate (CIR) and Committed Burst Size
+      (CBS) to mark packets GREEN or RED. In a P4 program, this mode can be set
+      by adding the `@single_rate_two_color` annotation to the meter definition.
+
 For indexed meters, the `Meter` message contains also a `size` field, an `int64`
 representing the maximum number of independent cells that can be held by this
 meter. Conversely, the `DirectMeter` message contains a `direct_table_id` field
@@ -3381,7 +3411,7 @@ property in the P4~16~ source code, with no `const` qualifier before
 `entries`, and at least one entry in that list.  In the P4Info, such
 tables have `has_initial_entries` flag equal to true, but
 `is_const_table` is false.  For tables declared with `const entries`,
-see Section [#sec-constant-tables].
+see Section on [Constant Tables](#sec-constant-tables).
 
 Every P4 table falls into one of three categories:
 
@@ -3416,8 +3446,8 @@ number of entries supported by the target for the table.
 
 The contents of preinitialized tables can be queried by the client
 through a `ReadRequest`.  The server fills in the same fields in the
-response as it does for constant tables, as described in Section
-[#sec-constant-tables], and with the same restrictions on table
+response as it does for constant tables, as described in Section on
+[Constant Tables](#sec-constant-tables), and with the same restrictions on table
 features supported.
 
 If the table requires a priority value for entries, the priorities of
@@ -4264,15 +4294,31 @@ entity for each of the instances, specifying the `counter_id` and
   values for all indirect counters in the array identified by the unique id
   `counter_id`.
 
-## `MeterEntry` & `DirectMeterEntry`
+## `MeterEntry` & `DirectMeterEntry` { #sec-meter-directmeter }
 
 Meters are an advanced mechanism for keeping statistics, involving stateful
 "marking" and usually "throttling" of packets based on configured rates of
 traffic. The PSA metering function is based on the *Two Rate Three Color Marker*
-(trTCM) defined in RFC 2698 [@RFC2698]. The trTCM meters an arbitrary packet
-stream using two configured rates --- the Peak Information Rate (PIR) and
-Committed Information Rate (CIR), and their associated burst sizes --- and
-"marks" its packets as GREEN, YELLOW or RED based on the observed rate.
+(trTCM) defined in RFC 2698 [@RFC2698]. P4Runtime clients may additionally
+restrict meter usage on a table to RFC 2697's [@RFC2697] *Single Rate Three
+Color Marker* (srTCM) or a simplified version of it that we call *Single Rate
+Two Color Marker*. The type of a table's meter is set by the `MeterSpec.Type` as
+described in the [Meter & DirectMeter section](#sec-meter-directmeter).
+
+The trTCM meters an arbitrary packet stream using two configured rates ---
+the Peak Information Rate (PIR) and Committed Information Rate (CIR), and their
+associated burst sizes --- and "marks" its packets as GREEN, YELLOW or RED based
+on the observed rate.
+
+The srTCM meters an arbitrary packet stream using a single configured rate ---
+the Committed Information Rate (CIR) and its associated burst size --- as well
+as the Excess Burst Size (EBS) and "marks" its packets as GREEN, YELLOW or RED
+based on the observed rate.
+
+The *Single Rate Two Color Marker* meters an arbitary packet stream using a
+single configured rate --- the Committed Information Rate (CIR) and its
+associated burst size --- and "marks" its packets as GREEN or RED based on the
+observed rate.
 
 `MeterEntry` & `DirectMeterEntry` have an additional field `counter_data` that
 may hold per color counter data for targets that support it, and that must
@@ -4292,9 +4338,28 @@ message MeterConfig {
   int64 cburst = 2;  // Committed Burst Size
   int64 pir = 3;  // Peak Information Rate
   int64 pburst = 4;  // Peak Burst Size
+  int64 eburst = 5; // Excess burst size (only used for srTCM)
 }
 ~ End Proto
 
+A MeterConfig for a trTCM typed meter must only be accepted if `eburst` is
+unset. Otherwise, the server should return an `INVALID_ARGUMENT` error.
+
+A MeterConfig for a srTCM typed meter must only be accepted if `pir` and
+`pburst` are equal to `cir` and `cburst` respectively. Otherwise, the server
+should return an `INVALID_ARGUMENT` error.
+
+A MeterConfig for a *Single Rate Two Color Marker* typed meter must only be
+accepted if `pir` and `pburst` are equal to `cir` and `cburst` respectively and
+`eburst` is unset. Otherwise, the server should return an `INVALID_ARGUMENT`
+error.
+
+Note: Any acceptable MeterConfig for a *Single Rate Two Color Marker* typed
+meter is also acceptable for either of the other two meter types and will mark
+packets identically in all three cases. Thus, changing the meter type from
+*Single Rate Two Color Marker* to *Single Rate Three Color Marker* or
+*Two Rate Three Color Marker* is a non-breaking change.
+
 ### `DirectMeterEntry`
 
 A direct meter is a direct resource associated with a `TableEntry` (see [Direct
@@ -6482,37 +6547,59 @@ properties, but we may include on in future versions of the API.
 
 ### Changes in v1.4.0
 
-* Add a `PlatformProperties` message specifying desired underlying platform
-  properties to the `PkgInfo` message.
-* Add a `metadata` field to the `MulticastGroupEntry` message.
-* Clarify that the limitation on supported types for `FieldMatch`, action
-  `Param`, and Packet IO metadata fields (no support for signed integers, with
-  type `int<W>`) apply to all minor revisions of P4Runtime v1, not just to
-  P4Runtime v1.0.
-* Fix invalid `action_profile_id` in the One Shot Action Selector Programming
-  example.
-* Specify Read behavior in the absence of a P4Info (`ForwardingPipelineConfig`
-  not set yet).
-* Clarify that for updates of type `INSERT`, error codes other than
-  `INVALID_ARGUMENT` can be returned when applicable.
-* Enable C++ Arena Allocation [@ArenaAllocation] by default in p4runtime.proto.
-* Add support for string role identifiers and deprecate integer role
-  identifiers.
-* Add support for specifying a role in `ReadRequest` messages: if present, only
-  entities belonging to this specific role are returned.
-* Specify that `max_group_size` must be less than or equal to `size` for Action
-  Selectors.
-* Simplify specification for arbitration updates for which there is no change to
-  the controller's `election_id`; in particular, a "no-op" arbitration update
-  from a primary controller (the controller already was, and remains, the
-  primary controller) is essentially treated the same way as an arbitration
-  update which leads to the election of a new primary controller.
-* Enable P4Runtime servers to provide per-color counter values when direct or
-  indirect meter entries are read.
-* Clarify that the (`device_id`, `role`, `election_id`) 3-tuples are only unique
-  for live controllers.
-* Add a `selector_size_semantics` field to the `ActionProfile` message
-  in P4Info.
+* Actions
+  * Fix invalid `action_profile_id` in the One Shot Action Selector Programming
+    example.
+  * Specify that `max_group_size` must be less than or equal to `size` for Action
+    Selectors.
+  * Add a `selector_size_semantics` field to the `ActionProfile` message
+    in P4Info.
+
+* Controller Sessions, Roles, Arbitration:
+  * Clarify controller session establishment, maintenance, role and arbitration
+  * Simplify specification for arbitration updates for which there is no change to
+    the controller's `election_id`; in particular, a "no-op" arbitration update
+    from a primary controller (the controller already was, and remains, the
+    primary controller) is essentially treated the same way as an arbitration
+    update which leads to the election of a new primary controller.
+  * Add support for string role identifiers and deprecate integer role identifiers.
+  * Add support for specifying a role in `ReadRequest` messages: if present, only
+    entities belonging to this specific role are returned.
+  * Clarify that the (`device_id`, `role`, `election_id`) 3-tuples are only unique
+    for live controllers.
+
+* Meters
+  * Add a `Type` field to the `MeterSpec` message allowing users to restrict the
+    type of meters that can be used for a table and a new `eburst` field to the
+    `MeterConfig` message for use with one of the new `MeterSpec` types. See
+    Section on [Meter & DirectMeter](#sec-meter-directmeter).
+  * Defined new meter annotations `@two_rate_three_color`, `@single_rate_two_color`, `@single_rate_three_color`
+  * Enable P4Runtime servers to provide per-color counter values when direct or
+    indirect meter entries are read.
+
+* Miscellaneous
+  * Add a `PlatformProperties` message specifying desired underlying platform
+    properties to the `PkgInfo` message.
+  * Specify Read behavior in the absence of a P4Info (`ForwardingPipelineConfig`
+    not set yet).
+  * Clarify that for updates of type `INSERT`, error codes other than
+    `INVALID_ARGUMENT` can be returned when applicable.
+  * Enable C++ Arena Allocation [@ArenaAllocation] by default in p4runtime.proto.
+  * Clarified the meaning of set and unset scalar and message fields, see section [#sec-default-valued-fields].
+  * Described Dataplane Volatile Objects, see section [sec-data-plane-volatile-objects]
+  * Clarified use of bytestrings in messages, see section on [Bytestrings](#sec-bytestrings)
+
+* Replication
+  * Add a `metadata` field to the `MulticastGroupEntry` message.
+  * In message `Replica`, replaced primitive field `uint32 egress_port` in a compatible manner with new `oneof port_kind` containing preferred new field `bytes port`.
+
+* Tables
+  * Clarify that the limitation on supported types for `FieldMatch`, action
+    `Param`, and Packet IO metadata fields (no support for signed integers, with
+    type `int<W>`) apply to all minor revisions of P4Runtime v1, not just to
+    P4Runtime v1.0.
+  * Add `has_initial_entries` and `is_const` field fields to `Table` message to distinguish mutable and immutable initial table entries,
+    see Section on [Constant Tables](#sec-constant-tables).
 
 ### Changes in v1.3.0
 
@@ -6588,6 +6675,9 @@ the purpose of adding features for the P4Runtime API.
 | `@max_group_size`          | See sections [#sec-p4info-action-profile], [#sec-action-profile-group-programming] |
 | `@selector_size_semantics` | See section [#sec-p4info-action-profile] |
 | `@max_member_weight`       | See section [#sec-p4info-action-profile] |
+| `@two_rate_three_color`    | See section [#sec-meter-directmeter] |
+| `@single_rate_three_color` | See section [#sec-meter-directmeter] |
+| `@single_rate_two_color`   | See section [#sec-meter-directmeter] |
 | `@pkginfo`                 | See section [#sec-annotating-p4-code-with-pkginfo] |
 | `@platform_property`       | See section [#sec-annotating-p4-code-with-pkginfo] |
 | `@p4runtime_translation`   | See sections [#sec-user-defined-types], [#sec-translation-of-port-numbers] |

docs/v1/p4runtime-id-notes.md

@@ -136,6 +136,7 @@ them may be 0, described in the notes.
 | Field name | Message type | Type of P4 object referred to | Notes |
 | ---------- | ------------ | ----------------------------- | ----- |
 | `const_default_action_id` | `Table` | `Action` | 0 means "the table's `default_action` is not declared `const` |
+| `initial_default_action` | `Table` | `Action` | The initial default action used by the table. Can be overridden at runtime. |
 | `implementation_id` | `Table` | `ActionProfile` | 0 means "this table has no `implementation` table property. |
 | `direct_resource_ids` | `Table` | `DirectCounter` or `DirectMeter` | repeated so that a single table can refer to up to one of each |
 | `id` | sub-message `ActionRef` inside `Table` | `Action` | `ActionRef` messages are repeated, with a separate one for each action the table might invoke.  `ActionRef` messages contain optional annotation and `Scope` values that are specific to how a particular table is allowed to use that `Action` |

docs/v1/references.bib

@@ -151,6 +151,11 @@ @ONLINE { RFC2698
     url = "https://tools.ietf.org/html/rfc2698"
 }
 
+@ONLINE { RFC2697,
+    title = "A Single Rate Three Color Marker",
+    url = "https://tools.ietf.org/html/rfc2697"
+}
+
 @ONLINE { P4MatchTypes,
     title = "Match types in P4",
     url = "https://p4.org/p4-spec/docs/P4-16-v1.2.1.html#sec-match-kind-type"