Merge remote-tracking branch 'upstream/main' into version-1.4.0-rc

Signed-off-by: chris <[email protected]>

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
@@ -4269,10 +4299,26 @@ entity for each of the instances, specifying the `counter_id` and
 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,6 +6547,9 @@ properties, but we may include on in future versions of the API.
 
 ### Changes in v1.4.0
 
+* 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.
 * Add a `PlatformProperties` message specifying desired underlying platform
   properties to the `PkgInfo` message.
 * Add a `metadata` field to the `MulticastGroupEntry` message.
@@ -6588,6 +6656,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"