P4Runtime Release v1.4.1

Changes in v1.4.1

No content changes; tag was incremented only.

Changes in v1.4.0

• 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.

• 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.
  • 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.
  • Clarified the meaning of set and unset scalar and message fields, see
    section on default-valued fields.
  • Described Dataplane Volatile Objects, see section on
    Dataplane Volatile Objects.
  • Clarified use of bytestrings in messages, see section on
    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.

P4Runtime Release v1.4.0

TBD

P4Runtime Release v1.3.0

Third minor release for P4Runtime v1.

Changelog:

• API
  • P4Runtime was assigned TCP port 9559 by IANA.
  • Deprecate watch field (int32) in favor of watch_port (bytes). This allows using the watch port feature with the p4runtime_translation feature.
• specification
  • Move "Security considerations" section to P4Runtime server discussion.
  • Replace master, slave, master arbitration with more inclusive language: primary, backup, and client arbitration
  • Clarify that source locations for annotations are optional in the P4Info message.

P4Runtime Release v1.2.0

Second minor release for P4Runtime v1.

Changelog:

• API
  • Add new OPTIONAL match kind. At the moment, OPTIONAL is only supported by the v1model architecture, and not by PSA. It will eventually be included in the core P4 language.
  • Add support in P4Info for structured annotations, which are used to annotate objects with key-value lists or expression lists.
  • Add a new metadata field of type bytes to TableEntry. This is more flexible than the now deprecated controller_metadata field.
  • Add the ability to change the ID of table match fields, action parameters, Packet IO metadata fields, and Value Set match fields in P4Info by using the @id annotation.
  • Support using string as the controller type in the @p4runtime_translation annotation. Update syntax when using a fixed-width unsigned bitstring as the controller type.
  • Add optional P4 source locations to both structured and unstructured annotations.
• specification
  • Clarify the behavior of some corner cases involving action profiles and selectors, including the watch port feature.
• build
  • Overhaul of the Bazel build system
    • Fix rules: remove dependency on stackb/rules_proto, use bazelbuild/rules_proto instead,
    • Improve documentation.
    • Add an example Bazel project depending on the P4Runtime rules.

P4Runtime Release v1.2.0-rc.2

Second release candidate for P4Runtime v1.2.0. Includes improved Bazel support.

P4Runtime Release v1.2.0-rc.1

First release candidate for P4Runtime v1.2.0.

P4Runtime Release v1.1.0

First minor release for P4Runtime v1.

Almost identical to the v1.1.0-rc.1 pre-release, so refer to the release notes for that release. The only change is an edit to the specification to fix an inconsistency in the section describing consistency requirements for Write RPCs.

P4Runtime Release v1.1.0-rc.1

First release candidate for the first minor release for P4Runtime v1. Should not break backwards-compatibility at the P4Runtime message level. However, some significant changes were made to master-arbitration which will impact controller-failover for client and server implementations.

Changelog (copied from the Revision History Appendix):

• API
  • Major overhaul of master-arbitration: while the Protobuf messages did not change, the state machine that the server needs to implement is significantly different. Upon the master disconnection, the server no longer chooses the controller with the second highest election id as the new master. Instead, there will not be a new master until one of the controllers advertises an election id higher than any election id seen previously.
  • Add error field to stream messages sent by the server.
  • Add Capabilities RPC to query the P4Runtime API version implemented by the server.
  • Support wildcard reads for multicast groups and clone sessions.
  • Support for modifying direct resources of const tables.
  • Support P4 user-defined types for Packet IO metadata fields.
• specification
  • Clarify consistency requirements for Write and Read RPCs.
  • Add Appendix providing implementation advice for avoiding common pitfalls:
    • advice on setting gRPC Metadata Maximum Size
    • advice on setting gRPC Server Maximum Receive Message Size
  • Clarify limitations on supported types for FieldMatch, action Param, and Packet IO metadata fields.
  • Clarify that reading entire forwarding state with empty entity is not supported.
  • Document that @p4runtime_translation need only be supported when applied to type declarations in P4.

P4Runtime Release v1.0.0

This is the official v1.0.0 release. All backward-compatibility guarantees listed in the specification will be enforced from now on.

Changelog:

• API
  • removed obsolete references to P4_14 in proto files
  • fixed signed int (int<W>) representation: we now mandate sign-bit padding to be able to differentiate between positive & negative values while preserving our original goal of "non-disruptive P4 program updates"
  • ensured canonical representation of compound types (e.g. stacks) with P4Data
  • required idle_timeout_ns field to be set in the table_entry fields of the IdleTimeoutNotification message
  • major overhaul of Value Set programming, which was very much out-of-sync with the P4_16 spec: support for multi-field matches, support for @match annotation
  • added support for numeric translation of Counter / Meter / Register indices
  • corrected out-of-date comment in p4runtime.proto regarding match entry priority
  • better semantics for max_group_size field (P4Info) and max_size (P4Runtime)
• specification
  • typos & formatting issues fixed all over the place
  • clarified the meaning of the alias field in the P4Info Preamble message
  • described documentation annotations: @brief, @description and @pkginfo, which influence P4Info generation
  • added appendix listing all annotations primarily relevant to P4Info / P4Runtime; for each annotation we include a link to the relevant section in the spec
  • explicitly documented order of error statuses in WriteResponse
  • changed description of scenarios where P4 program is not available to emphasize usefulness of P4 program to build robust / correct systems
  • clarified how each P4Runtime client is identified to the server
  • improved description of master-slave arbitration and terminology used
  • clarifications regarding action profile programming: 0 is not a valid weight for members, members cannot be repeated in an action profile group (although action specifications can be "repeated" when doing one-shot programming), members can be shared across different groups
  • called out that idle timeout is not supported for default entries
  • refined the definition of read-write symmetry: the order of repeated fields is no longer required to be preserved for "entity programming", unless explicitly specified on a case-by-case basis
  • added information about which operations are allowed for immutable tables
  • included some security considerations & recommendations in the spec

P4Runtime Release v1.0.0-rc4

Changelog:

• API
  • improved some comments in Protobuf files and fixed comments formatting
  • moved to canonical representation for serializable enums (use integral value, not name)
  • removed complete flag from ReadResponse message
  • improved support for @defaultonly and @tableonly annotations: new scope field for ActionRef message in p4info.proto
  • support architecture-specific notifications on bi-directional P4Runtime stream
• specification
  • fixed typo in error report figure
  • clarified controller role definition
  • fixed value set example
  • added general guidelines on how to pick error codes & specified which error code to return in some common error cases
  • dropped "Lifetime of a Session" section because no one volunteered to write it
  • added link to latest version of PSA specification (v1.1.0)
  • clarified action selector programming and added information about new psa_empty_group_action table property
  • added section giving atomicity requirements for individual write operations
  • added discussion about table size and target requirements for how many entries must be supported
  • updated link to P4_16 specification (v1.1.0)
  • clarified valid values for multicast group ids and clone session ids