Package: p4runtime
P4Runtime SpecificationThis 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 documentationThe latest version of the P4Runtime v1 specification is available:hereinHTMLformathereinPDFformatIt is updated every time a new commit is pushed to the master branch.OverviewP4 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.CommunityMeetings: the P4.org API Working Group meets every other Friday at
9:30AM (Pacific Time). Please see theP4 Working Groups Calendarfor meeting details.Email: join ourmailing
listto receive
announcements and stay up-to-date with Working Group activities.Slack: ask to join theP4 Slack Workspaceto get (or provide!)
interactive help.Compiling P4Runtime Protobuf filesBuild Using DockerYou 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 thedocker runcommand exits.These commands are the ones used by our CI system to ensure that the Protobuf
files stay semantically valid.Build Using BazelThe protobufs can also be built usingBazel.
The Bazel WORKSPACE and BUILD files are located in theproto folder.To build, runcdproto&&bazelbuild//...We runcontinuous integrationto ensure
this works with the latest version of Bazel.For an example of how to include P4Runtime in your own Bazel project, seebazel/example.Modification PolicyWe 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 ProcessesOnly 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 usesemantic versioningto 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 ProcessesWe now identify detailed processes for three classes of changes. The text below
refers tokey
committers, a
GitHub team that is authorized to modify the specification according to these
processes.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.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.API ChangesAny 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 ofp4runtime, 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 undergo/andpy/. 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 thedockercommand can be executed withoutsudo).Use generated P4Runtime libraryGoTo include the P4Runtime Go library to your project, you can add this repository url
to yourgo.modfile, for example:module your_module_name

go 1.13

require (
  github.com/p4lang/p4runtime v1.3.0
)PythonTo install P4Runtime Python library, use thepip3command:pip3installp4runtime# Or specifiy the versionpip3installp4runtime==1.3.0