From 575dbe8f42179c1fba7704f9e1d944f5266aead6 Mon Sep 17 00:00:00 2001
From: Jonathan DiLorenzo <dilo@google.com>
Date: Fri, 9 Feb 2024 21:35:29 +0000
Subject: [PATCH] Update specification to discuss new meter types.

---
 docs/v1/P4Runtime-Spec.mdk      | 42 +++++++++++++++++++++++++++------
 docs/v1/references.bib          |  5 ++++
 proto/p4/config/v1/p4info.proto |  3 ++-
 3 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/docs/v1/P4Runtime-Spec.mdk b/docs/v1/P4Runtime-Spec.mdk
index 0dc5fef4..6f674673 100755
--- 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
index 4d259343..ae47c0d6 100644
--- 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
index 807e4fef..9851a1d1 100644
--- 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.