From 4656e0605b69f3b10bec86582c290bbd75d9b1b3 Mon Sep 17 00:00:00 2001 From: chris Date: Fri, 30 Aug 2024 15:03:46 -0700 Subject: [PATCH 1/5] Update 1.4.0 changelog per https://github.com/p4lang/p4runtime/issues/491 Signed-off-by: chris --- docs/v1/P4Runtime-Spec.mdk | 89 +++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 35 deletions(-) diff --git a/docs/v1/P4Runtime-Spec.mdk b/docs/v1/P4Runtime-Spec.mdk index 92cd2e2b..18df0090 100755 --- a/docs/v1/P4Runtime-Spec.mdk +++ b/docs/v1/P4Runtime-Spec.mdk @@ -4294,7 +4294,7 @@ 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 @@ -6547,40 +6547,59 @@ 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. -* Clarify that the limitation on supported types for `FieldMatch`, action - `Param`, and Packet IO metadata fields (no support for signed integers, with - type `int`) 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 + [Meter & DirectMeter section](#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 [#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`) 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 [#sec-constant-tables]. ### Changes in v1.3.0 From 97e6b854b81e55575de6490df7f4b55aeeff73e7 Mon Sep 17 00:00:00 2001 From: chris Date: Fri, 30 Aug 2024 15:13:04 -0700 Subject: [PATCH 2/5] Accentuate protobuf update procedure in README. Signed-off-by: chris --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 41cb9c05..d92b6688 100644 --- a/README.md +++ b/README.md @@ -144,12 +144,11 @@ 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 -the generated Go, Python and Rust files, which are hosted in this repository -under [go/](go/), [py/](py/) and [rust/](rust/). 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`). +>**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`**, +provided docker is installed and your user is part of the "docker" group +(which means that the `docker` command can be executed without `sudo`). ## Use generated P4Runtime library From 801a533e2b1b1d08c7607c644aa29a2eb816ab7c Mon Sep 17 00:00:00 2001 From: chris Date: Fri, 30 Aug 2024 15:25:30 -0700 Subject: [PATCH 3/5] Fix section refs. Signed-off-by: chris --- docs/v1/P4Runtime-Spec.mdk | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/v1/P4Runtime-Spec.mdk b/docs/v1/P4Runtime-Spec.mdk index 18df0090..98012645 100755 --- a/docs/v1/P4Runtime-Spec.mdk +++ b/docs/v1/P4Runtime-Spec.mdk @@ -3411,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: @@ -3446,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 @@ -6572,7 +6572,7 @@ properties, but we may include on in future versions of the API. * 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 - [Meter & DirectMeter section](#sec-meter-directmeter). + 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. @@ -6587,7 +6587,7 @@ properties, but we may include on in future versions of the API. * 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 [#sec-bytestrings] + * Clarified use of bytestrings in messages, see section on [Bytestrings](#sec-bytestrings) * Replication * Add a `metadata` field to the `MulticastGroupEntry` message. @@ -6599,7 +6599,7 @@ properties, but we may include on in future versions of the API. type `int`) 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 [#sec-constant-tables]. + see Section on [Constant Tables](#sec-constant-tables). ### Changes in v1.3.0 From fdf185249bd60409a5fa9893d877bd08ef18732f Mon Sep 17 00:00:00 2001 From: chris Date: Mon, 16 Sep 2024 14:24:52 -0700 Subject: [PATCH 4/5] Added Rust code generation to changelog. Fixed some ref links. Signed-off-by: chris --- docs/v1/P4Runtime-Spec.mdk | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/v1/P4Runtime-Spec.mdk b/docs/v1/P4Runtime-Spec.mdk index 98012645..194bba1b 100755 --- a/docs/v1/P4Runtime-Spec.mdk +++ b/docs/v1/P4Runtime-Spec.mdk @@ -2265,8 +2265,8 @@ The reads and writes a client issues towards a server should be symmetrical and unambiguous. More specifically, if a client writes a P4 entity and then reads it back then the client should expect that the message it wrote and the message it read should match if the RPCs finished successfully (with the exception of parts -of the response known to be data plane volatile, as explained in section -[#sec-data-plane-volatile-objects]). Consider the following pseudocode as an +of the response known to be data plane volatile, as explained in section on +[Data plane volatile objects](#sec-data-plane-volatile-objects)). Consider the following pseudocode as an example: ~ Begin Pseudo @@ -3411,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 on [Constant Tables](#sec-constant-tables). +see section on [Constant Tables](#sec-constant-tables). Every P4 table falls into one of three categories: @@ -3446,7 +3446,7 @@ 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 on +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. @@ -6568,11 +6568,15 @@ properties, but we may include on in future versions of the API. * Clarify that the (`device_id`, `role`, `election_id`) 3-tuples are only unique for live controllers. +* Generated code + * Enable C++ Arena Allocation [@ArenaAllocation] by default in p4runtime.proto. + * Added Rust code generation + * 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). + 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. @@ -6584,8 +6588,8 @@ properties, but we may include on in future versions of the API. 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]. + * Clarified the meaning of set and unset scalar and message fields, see + section on [default-valued fields](#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) @@ -6599,7 +6603,7 @@ properties, but we may include on in future versions of the API. type `int`) 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). + see section on [Constant Tables](#sec-constant-tables). ### Changes in v1.3.0 From 76670be1377f7e172ed69d97538cf2b9c865c852 Mon Sep 17 00:00:00 2001 From: chris Date: Mon, 16 Sep 2024 14:58:41 -0700 Subject: [PATCH 5/5] Fixed 80-char column limit violations. Signed-off-by: chris --- docs/v1/P4Runtime-Spec.mdk | 65 ++++++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 28 deletions(-) diff --git a/docs/v1/P4Runtime-Spec.mdk b/docs/v1/P4Runtime-Spec.mdk index 194bba1b..f08ab862 100755 --- a/docs/v1/P4Runtime-Spec.mdk +++ b/docs/v1/P4Runtime-Spec.mdk @@ -2266,7 +2266,8 @@ unambiguous. More specifically, if a client writes a P4 entity and then reads it back then the client should expect that the message it wrote and the message it read should match if the RPCs finished successfully (with the exception of parts of the response known to be data plane volatile, as explained in section on -[Data plane volatile objects](#sec-data-plane-volatile-objects)). Consider the following pseudocode as an +[Data plane volatile objects](#sec-data-plane-volatile-objects)). +Consider the following pseudocode as an example: ~ Begin Pseudo @@ -6550,59 +6551,67 @@ properties, but we may include on in future versions of the API. * 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. + * 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. + * 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. * Generated code - * Enable C++ Arena Allocation [@ArenaAllocation] by default in p4runtime.proto. + * Enable C++ Arena Allocation [@ArenaAllocation] by default in + p4runtime.proto. * Added Rust code generation * 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` + * 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). + * 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. * Clarified the meaning of set and unset scalar and message fields, see section on [default-valued fields](#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) + * Described Dataplane Volatile Objects, see section on + [Dataplane Volatile Objects](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`. + * 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`) 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, + `Param`, and Packet IO metadata fields (no support for signed integers, + with type `int`) 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