Update specification to discuss new meter types.

p4lang · Feb 9, 2024 · 575dbe8 · 575dbe8
1 parent 750885b
commit 575dbe8
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 8 deletions.
diff --git a/docs/v1/P4Runtime-Spec.mdk b/docs/v1/P4Runtime-Spec.mdk
@@ -1712,13 +1712,25 @@ 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.
+    * `SINGLE_RATE_TWO_COLOR`: This is a simplified version of RFC 2697 
+      [@RFC2697], which restricts meters to use only a single rate to mark 
+      packets GREEN or RED. RFC 2697 allows three colors by additionally
+      providing an Excess Burst Size (EBS) that P4Runtime does not make
+      available.
+
 
 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
@@ -4231,10 +4243,21 @@ 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 a simplified version of RFC 2697 [@RFC2697]
+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 *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
@@ -4257,6 +4280,11 @@ message MeterConfig {
 }
 ~ End Proto
 
+A MeterConfig for a *Single Rate Two Color Marker* typed meter must only be
+accepted if `pir` and `pburst` are either both unset, or equal to `cir` and
+`cburst` respectively. Otherwise, the server should return an `INVALID_ARGUMENT`
+error.
+
 ### `DirectMeterEntry`
 
 A direct meter is a direct resource associated with a `TableEntry` (see [Direct

diff --git a/docs/v1/references.bib b/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"

diff --git a/proto/p4/config/v1/p4info.proto b/proto/p4/config/v1/p4info.proto
@@ -340,7 +340,8 @@ message MeterSpec {
     BYTES = 1;
     PACKETS = 2;
   }
-  // Used to distinguish
+  // Used to restrict the MeterConfigs that can be used to instantiate the
+  // meter.
   enum Type {
     // As described in RFC 2698, allows meters to use two rates to split packets
     // into three potential colors.