{"id":13510721,"url":"https://github.com/p4lang/p4runtime","last_synced_at":"2026-02-13T08:22:20.101Z","repository":{"id":40460316,"uuid":"139471616","full_name":"p4lang/p4runtime","owner":"p4lang","description":"Specification documents for the P4Runtime control-plane API","archived":false,"fork":false,"pushed_at":"2025-05-09T17:19:32.000Z","size":8228,"stargazers_count":155,"open_issues_count":89,"forks_count":96,"subscribers_count":27,"default_branch":"main","last_synced_at":"2025-05-12T08:07:11.842Z","etag":null,"topics":["p4","p4lang","p4runtime"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/p4lang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-02T17:08:40.000Z","updated_at":"2025-05-09T17:16:12.000Z","dependencies_parsed_at":"2024-09-16T23:10:19.604Z","dependency_job_id":"715be57f-3700-47dc-9273-cbba6e67dd7f","html_url":"https://github.com/p4lang/p4runtime","commit_stats":{"total_commits":236,"total_committers":42,"mean_commits":5.619047619047619,"dds":0.7033898305084746,"last_synced_commit":"9512a41af6fad2db4a3665b5c893646a31c4b1b4"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p4lang%2Fp4runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p4lang%2Fp4runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p4lang%2Fp4runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p4lang%2Fp4runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/p4lang","download_url":"https://codeload.github.com/p4lang/p4runtime/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253700618,"owners_count":21949695,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["p4","p4lang","p4runtime"],"created_at":"2024-08-01T02:01:51.616Z","updated_at":"2026-02-13T08:22:20.084Z","avatar_url":"https://github.com/p4lang.png","language":"Rust","funding_links":[],"categories":["Python","others"],"sub_categories":[],"readme":"# P4Runtime Specification\n\nThis directory contains protobuf files, specifications and related artifacts for\nall versions of the P4Runtime API. Documentation and protobuf definitions are\nplaced into two distinct top-level directories. In each of these directories,\nfiles are organized based on the P4Runtime major version number (e.g. v1) as\nfollows:\n```\n.\n├── docs\n│   └── v1  # documentation for P4Runtime v1\n├── proto\n│   └── p4\n│       ├── config\n│       │   └── v1  # p4.config.v1 protobuf package (P4Info message definition)\n│       └── v1  # p4.v1 protobuf package (P4Runtime service definition)\n```\n\nGit tags are used to mark minor and patch release versions.\n\n## Reading the latest version of the documentation\n\nThe latest version of the P4Runtime v1 specification is available:\n* [here](https://p4.org/wp-content/uploads/sites/53/p4-spec/docs/p4runtime-spec-working-draft-html-version.html)\n  in **HTML** format\n* [here](https://p4.org/wp-content/uploads/sites/53/p4-spec/docs/p4runtime-spec-working-draft-pdf-version.html)\n  in **PDF** format\n\nIt is updated every time a new commit is pushed to the main branch.\n\n## Overview\n\nP4 is a language for programming the data plane of network devices. The\nP4Runtime API is a control plane specification for controlling the data plane\nelements of a device or program defined by a P4 program. This repository\nprovides a precise definition of the P4Runtime API via protobuf (.proto) files\nand accompanying documentation. The target audience for this includes system\narchitects and developers who want to write controller applications for P4\ndevices or switches.\n\n# Community\n\n * **Meetings**: the P4.org API Working Group meets every other Friday at\n   9:30AM (Pacific Time). Please see the [P4 Working Groups Calendar](https://calendar.google.com/calendar/u/0/embed?src=j4to42rsjqtfks0qb7iah8gous@group.calendar.google.com\u0026ctz=America/Los_Angeles)\n   for meeting details.\n * **Email**: join our [mailing\n   list](https://lists.p4.org/mailman/listinfo/p4-dev_lists.p4.org) to receive\n   announcements and stay up-to-date with Working Group activities.\n * **Slack**: ask to join the [P4 Slack Workspace] to get (or provide!)\n   interactive help.\n\n# Compiling P4Runtime Protobuf files\n\n## Build Using Docker\n\nYou can use Docker to run the protoc compiler on the P4Runtime Protobuf files\nand generate the Protobuf \u0026 gRPC bindings for C++, Python and Go:\n\n```\ndocker build -t p4runtime -f codegen/Dockerfile .\ndocker run -v \u003cOUT\u003e:/out/ -t p4runtime /p4runtime/codegen/compile_protos.sh /out/\n```\n\nThis will generate the bindings in the local `\u003cOUT\u003e` directory. **You need to\nprovide the absolute path for `\u003cOUT\u003e`.** The default Docker user is root, so you\nmay need to change the permissions manually for the generated files after the\n`docker run` command exits.\n\nThese commands are the ones used by our CI system to ensure that the Protobuf\nfiles stay semantically valid.\n\n## Build Using Bazel ![build protobufs](https://github.com/p4lang/p4runtime/workflows/build%20protobufs/badge.svg)\n\nThe protobufs can also be built using [Bazel](https://bazel.build/).\nThe Bazel WORKSPACE and BUILD files are located in the [proto folder](proto/).\n\nTo build, run\n```sh\ncd proto \u0026\u0026 bazel build //...\n```\n\nWe run [continuous integration](.github/workflows/ci-build-proto.yml) to ensure\nthis works with the latest version of Bazel.\n\nFor an example of how to include P4Runtime in your own Bazel project, see\n[bazel/example](bazel/example).\n\n# Modification Policy\n\nWe use the following processes when making changes to the P4Runtime\nspecification and associated documents. These processes are designed to be\nlightweight, to encourage active participation by members of the P4.org\ncommunity, while also ensuring that all proposed changes are properly vetted\nbefore they are incorporated into the repository and released to the community.\n\n## Core Processes\n\n* Only members of the P4.org community may propose changes to the P4Runtime\n  specification, and all contributed changes will be governed by the\n  Apache-style license specified in the P4.org membership agreement.\n\n* We will use [semantic versioning](http://semver.org/) to track changes to the\n  P4Runtime specification: major version numbers track API-incompatible changes;\n  minor version numbers track backward-compatible changes; and patch versions\n  make backward-compatible bug fixes. Generally speaking, the P4Runtime working\n  group co-chairs will typically batch together multiple changes into a single\n  release, as appropriate.\n\n## Detailed Processes\n\nWe now identify detailed processes for three classes of changes. The text below\nrefers to [key\ncommitters](https://github.com/orgs/p4lang/teams/p4lang-key-committers), a\nGitHub team that is authorized to modify the specification according to these\nprocesses.\n\n1. **Non-Technical Changes:** Changes that do not affect the definition of the\n   API can be incorporated via a simple, lightweight review process: the author\n   creates a pull request against the specification that a key committer must\n   review and approve. The P4Runtime Working Group does not need to be\n   explicitly notified. Such changes include improvements to the wording of the\n   specification document, the addition of examples or figures, typo fixes, and\n   so on.\n\n2. **Technical Bug Fixes:** Any changes that repair an ambiguity or flaw in the\n   current API specification can also be incorporated via the same lightweight\n   review process: the author creates a GitHub issue as well as a pull request\n   against the specification that a key committer must review and approve. The\n   key committer should use their judgment in deciding if the fix should be\n   incorporated without broader discussion or if it should be escalated to the\n   P4Runtime Working Group. In any event, the Working Group should be notified\n   by email.\n\n3. **API Changes** Any change that substantially modifies the definition of the\n   API, or extends it with new features, must be reviewed by the P4Runtime\n   Working Group, either in an email discussion or a meeting. We imagine that\n   such proposals would go through three stages: (i) a preliminary proposal with\n   text that gives the motivation for the change and examples; (ii) a more\n   detailed proposal with a discussion of relevant issues including the impact\n   on existing programs; (iii) a final proposal accompanied by a design\n   document, a pull request against the specification, and prototype\n   implementation on a branch of `p4runtime`, and example(s) that illustrate the\n   change. After approval, the author would create a GitHub issue as well as a\n   pull request against the specification that a key committer must review and\n   approve.\n\n\u003e**Generated protobuf files**: When updating the Protobuf files in a pull request, you will also need to update\nthe generated Go and Python files, which are hosted in this repository under\n[go/](go/) and [py/](py/). This can be done easily **by running `./codegen/update.sh`**,\nprovided docker is installed and your user is part of the \"docker\" group\n(which means that the `docker` command can be executed without `sudo`).\n\n## Use generated P4Runtime library\n\n### Go\n\nTo include the P4Runtime Go library to your project, you can add this repository url\nto your `go.mod` file, for example:\n\n```\nmodule your_module_name\n\ngo 1.13\n\nrequire (\n  github.com/p4lang/p4runtime v1.3.0\n)\n```\n\n### Python\n\nTo install P4Runtime Python library, use the `pip3` command:\n\n```bash\npip3 install p4runtime\n# Or specify the version\npip3 install p4runtime==1.3.0\n```\n\n### Rust\n\nSee the [rust/README.md](rust/README.md).\n\n## Guidelines for using Protocol Buffers (protobuf) in backwards-compatible ways\n\nP4Runtime generally follows \"Live at Head\" development principles - new\ndevelopment happens on the `main` branch and there are no support branches.\nNew releases are periodically created from the head of `main`.\n\nP4Runtime follows [semantic versioning](https://semver.org/) for release\nnumbering, which means changes to the P4Runtime protobuf definitions have\nimplications on the next release number. The team has tried its best so\nfar to avoid a major version number bump, but recognizes that one may be\nnecessary in the future.\n\nWhenever possible, it is best to introduce new functionality in backward\ncompatible ways. For example when role config was introduced, an unset\n(empty) role configuration implies full pipeline access, which was the\ndefault behavior before the feature was introduced.\n\nThere are no strict rules here for updating P4Runtime protobuf message\ndefinitions, only advice written by those with experience in using\nprotobuf for applications while they have been extended over\ntime.  They are here for learning and reference:\n\n* [Updating Proto Definitions Without Updating Code](https://developers.google.com/protocol-buffers/docs/overview#updating-defs)\n* [Updating A Message Type](https://developers.google.com/protocol-buffers/docs/proto3#updating)\n* [Backwards-compatibility issues in `oneof` fields](https://developers.google.com/protocol-buffers/docs/proto3#backwards-compatibility_issues)\n* [API design guide](https://cloud.google.com/apis/design)\n\nSome brief points, but not the full story:\n\n* Do not change or reuse field numbers.\n* Be careful when changing types.\n* You can deprecate fields, but do not remove them (and make sure that\n  you continue to support them) until you are sure that all clients\n  and servers are updated.\n\n\n[P4 Slack Workspace]: https://p4-lang.slack.com/join/shared_invite/enQtODA0NzY4Mjc5MTExLTRlMWVmN2I5ZTY4MTAzMDI3MGQ1OTZjM2ZmM2Q1MWE2YzZjYTQ2ZWMyMGUyYjQ2ZmIxMjFjZDE4ZThiN2ZkZWI\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp4lang%2Fp4runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp4lang%2Fp4runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp4lang%2Fp4runtime/lists"}