p4-guide: a working map of the P4 ecosystem

Notes, scripts and demos rather than a library

p4-guide holds a variety of potentially useful information for those wanting to work with the P4 programming language, and the collection reads more like a working notebook than a project with an API.

Three things live in it. First, install scripts that help build and install the p4c compiler and the behavioral-model projects along with their dependencies, on some recent versions of Ubuntu or Fedora. Second, a set of articles on various P4 topics, indexed in the docs directory. Third, a collection of small demo P4 programs, some of which exist in equivalent P4_14 and P4_16 versions of the language, which is exactly the transition most people are working through when they arrive here.

The subject is a language designed for packet processing, and the guide's framing of it is sharp. The short overview asks the reader to start with C and then remove loops, recursive calls, pointers, malloc and free, and it is blunt about the consequence: P4 is not a general purpose programming language, and it was never intended to be one.

The reason for the removals is stated rather than asserted. Without loops or recursive calls, the work done per packet can be bounded at compile time, which is what lets the same source target the highest performance programmable devices. Without pointers and dynamic allocation, arbitrary size data structures are not possible, but a tree of fixed depth can be built as a sequence of tables, with a depth 3 tree expressed as three P4 tables.

Building p4c and the behavioral model

The install scripts live in the `bin` directory, and the documentation for them is `bin/README-install-troubleshooting.md`, which carries both usage instructions and troubleshooting tips. The stated target is recent versions of Ubuntu or Fedora Linux.

A second, newer path exists for people who want to run programs on real hardware. The `ipdk` directory has newer instructions for installing IPDK on an Ubuntu 20.04 Linux system and for using the DPDK software switch to load and run P4 programs. That is a different level of ambition from running the behavioral model, because it puts your program behind a real NIC rather than inside a simulator.

Auto-generated documentation for the compiler also lives here, produced by doxygen, with the configuration files checked into the p4c repository itself, and the published site is linked at p4lang.github.io/p4c. Keeping the generated output here rather than in the compiler repository means the guide is the place to look when you want the reference documentation of the current compiler, including a list of the p4lang organisation repositories and a figure showing the dependencies between them, last updated in February 2024.

Demo programs you can run against simple_switch

The demo directories are the part of the guide with the most teaching value, and the structure is deliberate. A heavily commented P4_16 program sits at `demo1/demo1-heavily-commented.p4_16.p4`, which the guide suggests reading carefully to learn something about the language, and the numbered demo directories run from demo1 through demo7 and many more besides.

Each demo directory includes its own README with instructions for compiling the program and running it with the `simple_switch` software switch from the behavioral-model repository. That covers the two interactive steps that turn a demo into something you can experiment with: adding entries to the tables, and sending packets with Scapy that will be processed by the software switch.

The topic directories show what the author has been working through. There are directories for checksums, header stacks, match kinds, match ranges using TCAM, action profiles and selectors, data plane writable per table entry state, initial table entries, instantiation, namespaces, name annotations, extern annotations, exit statements, calling conventions, control plane types, add-on-miss tables, code generation, formal verification, flowcache, and both eBPF and Linux file access tracking. The tree also holds a `hub` directory, a `lpmtester` directory, a `compare-p4c-grammar-with-spec` directory, and a `loop-test-progs` directory for programs that test how the language handles loops.

Some of these look like bug reports written as runnable programs, which is a useful genre: a minimal reproduction that a compiler developer can run.

The cheat sheet of where constructs are allowed

A cheat sheet of where P4_16 language constructs are allowed to be used within a program is one of the more useful artefacts in the repository, published as a figure in PDF and as a text file. The language specification version it describes is 1.1.0.

The caveat attached to it is the important part. The cheat sheet describes what the P4_16 language specification allows, and P4_16 implementations may restrict your program to less than what is shown, or enable extensions not described there. The advice is to ask the creator of the implementation you are using to learn more. In practice, a hardware target and a software switch will differ, and a cheat sheet that did not flag that would be misleading.

A second cheat sheet, this one with example snippets of code, lives in the p4lang/tutorials repository and is linked from here.

The editor support notes matter for anyone who spends time in the language. They cover setting up several text editing programs for colour highlighting P4 programs and for quickly finding definitions of named things such as control blocks and tables, and the `editor-support` directory holds the configuration. For a language with a new syntax and a lot of type names, that is a real productivity difference, and it is the kind of thing a language guide is uniquely placed to solve.

The tree also has notes on using the Scapy library for creating, editing and decoding packets, which is what you need to make test packets for a P4 program, especially from within a general purpose language such as Python. A separate README covers the older version of those notes.

Parsers, tables and the control plane that fills them

The overview explains the two constructs that make P4 different from C, and the guide's account of them is worth reading closely.

Parsers are special constructs focused on the capabilities most needed when parsing the contents of a received packet into a sequence of headers. They are defined as finite state machines, with states you must name and define the possible transitions between. Loops are actually allowed in a parser state machine, but the highest performance targets will typically restrict loops to ones that can be unrolled to a compile-time known maximum number of iterations, with the example of parsing at most five MPLS headers.

The parser split also defines what a P4 program can and cannot see. Whatever part of a packet you do not parse into some header is, for that program, the payload of the packet, typically carried along unmodified, while header fields you do parse can be modified however you like.

Tables are the second construct. For each table you define a search key consisting of packet header fields and/or values of variables, and each table can have one or more actions defined for it. Then the guide makes the point that trips up newcomers: a P4 program represents only a small fraction of a complete working system. Control plane software, running on a general purpose CPU and written in C, C++, Java or Python, is responsible for adding and removing table entries, selecting the search key for each entry, and choosing the action to execute when a packet matches it.

Beyond that, a P4_16 architecture such as the Portable Switch Architecture defines counters, meters for enforcing average packet or bit rates, registers for limited stateful processing, and methods for recirculating a packet and multicasting it. Fields and variables are integers of arbitrary bit width up to an implementation maximum, and implementations need not implement floating point arithmetic, which the author expects most will not do because packet processing rarely needs it.

An index of the ecosystem, and the Go tools beside it

Beyond the language material, the guide is an index of the p4lang organisation. An overview of the p4lang GitHub repositories sits in a dedicated README, and a dependencies figure for those repositories exists in PDF, PNG and dot form, last updated in February 2024, so you can see how the compiler, the behavioral model, the tutorials and the specification relate.

Some of the tooling in the repository is written in Go. The module manifest is short:

module github.com/jafingerhut/p4-guide

go 1.22.4

require github.com/google/gopacket v1.1.19

The gopacket dependency makes sense for the kind of tools in the tree, such as the lpmtester directory for longest prefix match behaviour, since gopacket is the packet manipulation library for Go. The `golang` directory and the `go.sum` file sit alongside the P4 notes.

Elsewhere in the tree there is a `changes.md` file, an `issues` directory, a `formal-verification` directory, and a `docs` directory with the article index, plus a `README-using-bmv2.md` and a `README-troubleshooting.md` for working with the behavioral model switch.

On licensing and upkeep, no licence is listed for the project itself, while the source headers carry an SPDX identifier of Apache-2.0 and a 2024 copyright line for Andy Fingerhut. There are no GitHub releases, and the last push was on 2026-10-06, so the repository is maintained as a living set of notes rather than versioned artefacts.

Editorial conclusion

p4-guide suits a student or engineer who is learning P4 and wants runnable examples, a language cheat sheet and working notes on the software switch, rather than reading a specification alone. It is a poor fit as a production dependency, because it is documentation and scripts rather than a library, and it is a poor fit if you need support for a target beyond the Ubuntu and Fedora systems the install scripts cover. Before you rely on the install scripts, read `bin/README-install-troubleshooting.md`, check that the demo programs you plan to use match the P4_16 version you target, and treat the allowed-constructs cheat sheet as the language specification says it is, since implementations are free to restrict or extend it.

Frequently asked questions

Official sources

1. Issues
2. jafingerhut/p4-guide on GitHub
3. README