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

P4Runtime Release v1.0.0-rc3

Changelog:

• API
  • relaxed constraints on Protobuf bytestrings for more compact representation and better support for upgrade scenarios
  • added support for one-short action selector programming
  • support for "new" types (P4_16 user-defined types) in order to enable translation (e.g. port ids)
  • added reserved SDN port numbers to p4runtime.proto
  • removed color-awareness information from P4Info
  • added ability to associate a cookie to a forwarding-pipeline configuration, which enables verifying which config is used by the switch without retrieving the whole config over P4Runtime
• specification
  • moved to Open Document Format for figures (.odg files) for easier editing
  • added section on API versioning
  • added section on extending P4Runtime for new P4_16 architectures
• build
  • renamed BAZEL rules to abide by agreed-upon convention
  • new Docker image (specific to this project) to build the specification, includes soffice to generate figures from .odg files

P4Runtime Release v1.0.0-rc2

This is the first release we are doing since moving the specification document from gDoc to Github. As a result most of the effort went into translating the spec to a properly-formatted Madoko document.

Changelog:

• specification
  • convert to Madoko (thanks @chrispsommers for the initial conversion work from gDoc!)
  • updated "In Scope" section
  • improved grammar all over document
• protobuf files
  • fix typo in comments
• build
  • added BAZEL rules to build Protobuf / gRPC libraries