• Stars
    star
    146
  • Rank 252,769 (Top 5 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created over 6 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Specification documents for the P4Runtime control-plane API

P4Runtime Specification

This directory contains protobuf files, specifications and related artifacts for all versions of the P4Runtime API. Documentation and protobuf definitions are placed into two distinct top-level directories. In each of these directories, files are organized based on the P4Runtime major version number (e.g. v1) as follows:

.
├── docs
│   └── v1  # documentation for P4Runtime v1
├── proto
│   └── p4
│       ├── config
│       │   └── v1  # p4.config.v1 protobuf package (P4Info message definition)
│       └── v1  # p4.v1 protobuf package (P4Runtime service definition)

Git tags are used to mark minor and patch release versions.

Reading the latest version of the documentation

The latest version of the P4Runtime v1 specification is available:

  • here in HTML format
  • here in PDF format

It is updated every time a new commit is pushed to the main branch.

Overview

P4 is a language for programming the data plane of network devices. The P4Runtime API is a control plane specification for controlling the data plane elements of a device or program defined by a P4 program. This repository provides a precise definition of the P4Runtime API via protobuf (.proto) files and accompanying documentation. The target audience for this includes system architects and developers who want to write controller applications for P4 devices or switches.

Community

  • Meetings: the P4.org API Working Group meets every other Friday at 9:30AM (Pacific Time). Please see the P4 Working Groups Calendar for meeting details.
  • Email: join our mailing list to receive announcements and stay up-to-date with Working Group activities.
  • Slack: ask to join the P4 Slack Workspace to get (or provide!) interactive help.

Compiling P4Runtime Protobuf files

Build Using Docker

You can use Docker to run the protoc compiler on the P4Runtime Protobuf files and generate the Protobuf & gRPC bindings for C++, Python and Go:

docker build -t p4runtime -f codegen/Dockerfile .
docker run -v <OUT>:/out/ -t p4runtime /p4runtime/codegen/compile_protos.sh /out/

This will generate the bindings in the local <OUT> directory. You need to provide the absolute path for <OUT>. The default Docker user is root, so you may need to change the permissions manually for the generated files after the docker run command exits.

These commands are the ones used by our CI system to ensure that the Protobuf files stay semantically valid.

Build Using Bazel build protobufs

The protobufs can also be built using Bazel. The Bazel WORKSPACE and BUILD files are located in the proto folder.

To build, run

cd proto && bazel build //...

We run continuous integration to ensure this works with the latest version of Bazel.

For an example of how to include P4Runtime in your own Bazel project, see bazel/example.

Modification Policy

We use the following processes when making changes to the P4Runtime specification and associated documents. These processes are designed to be lightweight, to encourage active participation by members of the P4.org community, while also ensuring that all proposed changes are properly vetted before they are incorporated into the repository and released to the community.

Core Processes

  • Only members of the P4.org community may propose changes to the P4Runtime specification, and all contributed changes will be governed by the Apache-style license specified in the P4.org membership agreement.

  • We will use semantic versioning to track changes to the P4Runtime specification: major version numbers track API-incompatible changes; minor version numbers track backward-compatible changes; and patch versions make backward-compatible bug fixes. Generally speaking, the P4Runtime working group co-chairs will typically batch together multiple changes into a single release, as appropriate.

Detailed Processes

We now identify detailed processes for three classes of changes. The text below refers to key committers, a GitHub team that is authorized to modify the specification according to these processes.

  1. Non-Technical Changes: Changes that do not affect the definition of the API can be incorporated via a simple, lightweight review process: the author creates a pull request against the specification that a key committer must review and approve. The P4Runtime Working Group does not need to be explicitly notified. Such changes include improvements to the wording of the specification document, the addition of examples or figures, typo fixes, and so on.

  2. Technical Bug Fixes: Any changes that repair an ambiguity or flaw in the current API specification can also be incorporated via the same lightweight review process: the author creates a GitHub issue as well as a pull request against the specification that a key committer must review and approve. The key committer should use their judgment in deciding if the fix should be incorporated without broader discussion or if it should be escalated to the P4Runtime Working Group. In any event, the Working Group should be notified by email.

  3. API Changes Any change that substantially modifies the definition of the API, or extends it with new features, must be reviewed by the P4Runtime Working Group, either in an email discussion or a meeting. We imagine that such proposals would go through three stages: (i) a preliminary proposal with text that gives the motivation for the change and examples; (ii) a more detailed proposal with a discussion of relevant issues including the impact on existing programs; (iii) a final proposal accompanied by a design document, a pull request against the specification, and prototype implementation on a branch of p4runtime, and example(s) that illustrate the change. After approval, the author would create a GitHub issue as well as a 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 and Python files, which are hosted in this repository under go/ and 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

Go

To include the P4Runtime Go library to your project, you can add this repository url to your go.mod file, for example:

module your_module_name

go 1.13

require (
  github.com/p4lang/p4runtime v1.3.0
)

Python

To install P4Runtime Python library, use the pip3 command:

pip3 install p4runtime
# Or specify the version
pip3 install p4runtime==1.3.0

Guidelines for using Protocol Buffers (protobuf) in backwards-compatible ways

P4Runtime generally follows "Live at Head" development principles - new development happens on the main branch and there are no support branches. New releases are periodically created from the head of main.

P4Runtime follows semantic versioning for release numbering, which means changes to the P4Runtime protobuf definitions have implications on the next release number. The team has tried its best so far to avoid a major version number bump, but recognizes that one may be necessary in the future.

Whenever possible, it is best to introduce new functionality in backward compatible ways. For example when role config was introduced, an unset (empty) role configuration implies full pipeline access, which was the default behavior before the feature was introduced.

There are no strict rules here for updating P4Runtime protobuf message definitions, only advice written by those with experience in using protobuf for applications while they have been extended over time. They are here for learning and reference:

Some brief points, but not the full story:

  • Do not change or reuse field numbers.
  • Be careful when changing types.
  • You can deprecate fields, but do not remove them (and make sure that you continue to support them) until you are sure that all clients and servers are updated.

More Repositories

1

tutorials

P4 language tutorials
P4
1,332
star
2

p4c

P4_16 reference compiler
C++
671
star
3

behavioral-model

The reference P4 software switch
C++
536
star
4

p4-spec

TeX
175
star
5

p4factory

Compile P4 and run the P4 behavioral simulator
C
174
star
6

p4app-switchML

Switch ML Application
C++
167
star
7

PI

An implementation framework for a P4Runtime server
C++
165
star
8

switch

Consolidated switch repo (API, SAI and Nettlink)
C
152
star
9

ptf

Packet Test Framework
Python
144
star
10

p4pi

P4 on Raspberry Pi for Networking Education
JavaScript
123
star
11

p4app

Python
112
star
12

p4-applications

P4 Applications WG repo
P4
107
star
13

p4runtime-shell

An interactive Python shell for P4Runtime
Python
76
star
14

p4-dpdk-target

P4 driver SW for P4 DPDK target.
C++
56
star
15

pna

Portable NIC Architecture
P4
54
star
16

tdi

Table-Driven Interface (TDI) for a P4-programmable backend device.
C++
39
star
17

papers

Repository for papers related to P4
C
38
star
18

ntf

Network Test Framework
Python
37
star
19

education

P4 for Education
36
star
20

scapy-vxlan

A scapy clone, with support for additional packet headers
Python
36
star
21

p4-hlir

Python
32
star
22

p4ofagent

Openflow agent on a P4 dataplane
C
27
star
23

p4c-bm

Generates the JSON configuration for the behavioral-model (bmv2), as well as the C/C++ PD code
Python
24
star
24

p4lang.github.io

Deprecated P4.org website
HTML
23
star
25

p4analyzer

A Language Server Protocol (LSP) compliant analyzer for the P4 language
Rust
19
star
26

p4c-behavioral

[deprecated] P4 compiler for the behavioral model
C
18
star
27

p4app-TCP-INT

C
18
star
28

p4-constraints

Constraints on P4 objects enforced at runtime
C++
14
star
29

p4-build

Infrastructure needed to generate, build and install the PD library for a given P4 program
C++
12
star
30

gsoc

P4.org's Participation in Google Summer of Code
9
star
31

third-party

Third-party dependencies for p4lang software
Dockerfile
8
star
32

project-ideas

Ideas for P4 Projects.
6
star
33

target-utils

C
4
star
34

target-syslibs

C
3
star
35

hackathons

P4
2
star
36

governance

1
star