Skip to content
Guide to p4lang repositories and some other public info about P4
P4 Python Shell Emacs Lisp Makefile
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
action-profile-and-selector Update v1model signatures of old P4 programs Oct 18, 2018
bin Update output logs for install-p4dev-v2.sh script on 3 Ubuntu versions Dec 3, 2019
calling-convention Add a couple of links to new README-troubleshooting.md file Sep 21, 2018
checksum Small updates to checksum README.md file Dec 27, 2018
control-plane-types Add simple P4_16 v1model arch program with digest and its JSON P4Info… Apr 20, 2018
demo1 Remove sysrepod from README-p4runtime.md directions for demo1 program Nov 7, 2019
demo2 Correct a few file names in demo2 README.md Dec 3, 2019
demo3 Update last versions of open source P4 tools on which demo3 was tested Dec 3, 2019
demo4 Update a few older style p4c commands Aug 11, 2018
demo5 Update some demo programs to use 1-arg version of mark_to_drop() May 15, 2019
demo6 Minor updates to demo6 README.md -- everything still works with lates… Dec 3, 2019
demo7 Move baes_test.py to common pylib directory Jun 11, 2019
docs Add short doc with some informal things that get tricky if you add im… Feb 19, 2019
editor-support Add 'type' as new keyword for P4_16 syntax highlighting in Emacs Aug 19, 2018
header-stack Add simple P4 program for parsing a variable number of MPLS headers Dec 24, 2018
instantiation A few more corrections to instantiations/README.md document Jun 5, 2019
linux-veth-bug Add a couple more good Ubuntu Linux kernel versions to veth bug table Aug 7, 2019
multipackage Refine notes on hash tables to specifically multi-way hash tables Feb 21, 2018
multipipeline Add note of some P4 programs that compile cleanly Jul 24, 2017
namespaces Add simple example of one possible syntax for P4_16 namespaces Mar 16, 2019
overlays Add another disadvantage to RESUBMIT_ANNOT resubmit example Apr 22, 2019
p4c-issue1713 Add README.md for new directory Feb 7, 2019
p4runtime Update all mark_to_drop() calls to mark_to_drop(stdmeta) May 15, 2019
psa-examples Update all mark_to_drop() calls to mark_to_drop(stdmeta) May 15, 2019
pylib Small change to base_test.py needed for protobuf 3.6.1 Oct 18, 2019
rewrite-examples Update rewrite-examples P4_16 source code for latest v1model.p4 Nov 11, 2017
run-time-params Add error messages to run-time-params example P4_16 programs Aug 26, 2017
select-fields Update README a bit more. Dec 11, 2017
tcp-options-parser Update all mark_to_drop() calls to mark_to_drop(stdmeta) May 15, 2019
templates Update a v1model template program for recent v1model mark_to_drop change Apr 28, 2019
top-level-name-conflicts Enhancements to generate-p416-test-programs.py May 14, 2019
traffic-management Update all mark_to_drop() calls to mark_to_drop(stdmeta) May 15, 2019
transcript Add partial transcript of a LightReading webinar on P4Runtime Jul 18, 2018
v1model-special-ops Update all mark_to_drop() calls to mark_to_drop(stdmeta) May 15, 2019
variable-length-header Minor fixes Dec 1, 2018
README-demos.md Add mention of demo6 to README-demos.md Jun 3, 2019
README-editor-support.md Fix Emacs Lisp regexes for matching P4 source file names Feb 13, 2019
README-header-stacks.md Update resolution section of notes on header stacks May 24, 2019
README-p4lang-repos.md Add new p4lang repositories to repo list Mar 31, 2019
README-scapy.md Omit needless words. Mar 20, 2019
README-troubleshooting.md Fix typo and make troubleshooting link to a specific section May 15, 2019
README-using-bmv2.md Updates to README-using-bmv2.md to reflect recent changes to install … Nov 12, 2019
README.md Move descriptions of the 3 install scripts into the README ... Oct 20, 2019
changes.md A few small additions to the P4_16 allowed constructs figure Jul 8, 2019
dependencies.dot Mark p4factory and p4c-behavioral as deprecated in dependencies.dot Jun 24, 2017
dependencies.pdf Mark p4factory and p4c-behavioral as deprecated in dependencies.dot Jun 24, 2017
dependencies.png Mark p4factory and p4c-behavioral as deprecated in dependencies.dot Jun 24, 2017
p4-16-allowed-constructs.dot A few small additions to the P4_16 allowed constructs figure Jul 8, 2019
p4-16-allowed-constructs.pdf A few small additions to the P4_16 allowed constructs figure Jul 8, 2019
p4-16-allowed-constructs.png A few small additions to the P4_16 allowed constructs figure Jul 8, 2019
p4-16-allowed-constructs.txt A few small additions to the P4_16 allowed constructs figure Jul 8, 2019

README.md

Introduction

This repository contains a variety of potentially useful information for those wanting to work with the P4 programming language.

Contents:

  • An overview of the p4lang organization Github repositories

    • Three install scripts to assist you in building and installing p4c and behavioral-model projects and their dependencies on an Ubuntu 16.04 or 18.04 Linux machine:
      • See here for instructions and trouble-shooting tips for using these scripts.
    • A figure with the dependencies between these repositories (last updated June 2017 so may be slightly out of date).
  • A collection of small demo P4 programs, some of them with equivalent versions written in both P4_14 and P4_16 versions of the language.

    • includes a heavily commented P4_16 program, which by reading carefully one may learn some things about the P4_16 language.
    • Each of the demo directories includes its own README.md file with instructions for compiling the program and running it with the simple_switch software switch from the behavioral-model repository, including interactively adding table entries to the tables, and send packets using Scapy that will be processed by the software switch.
  • Instructions for setting up several text editing programs for color highlighting P4 programs, and quickly finding definitions for named things like control blocks and tables.

  • 'Cheat sheet' of where P4_16 language constructs are allowed to be used within a program.

    • figure
    • text
    • NOTE: This describes where language constructs are allowed by the P4_16 language specification (version 1.1.0). P4_16 implementations may restrict your program to less than what is shown here, or enable extensions not described here. Ask the creator of the implementation you are using to learn more.
  • Another useful 'cheat sheet' with example snippets of code is in the p4lang/tutorials repository.

  • Some notes on using the Scapy library for creating, editing, and decoding packets, useful when creating test packets to send to a P4 program being tested, especially within the control of a general purpose programming language (i.e. Python).

  • A very brief overview of P4 (in about 500 words), to get a flavor for what it is like (assuming you are familiar with the programming language C):

    • Start with C.
    • Remove loops, recursive calls, pointers, malloc, and free. When your mind recovers from reeling over these drastic limitations, you will clearly realize that P4 is not a general purpose programming language. It was not designed to be.
      • Without loops or recursive calls, the work done per packet can be bounded at compilation time, which helps when targeting the highest performance P4-programmable devices.
      • Without pointers, malloc, and free, general purpose data structures like linked lists, trees, etc. having arbitrary size is not possible. You can implement trees with fixed depth, e.g. a depth 3 tree could be implemented via a sequence of 3 P4 tables.
    • Add special constructs called parsers, focused on the capabilities most needed when parsing the contents of a received packet into a sequence of headers.
      • Parsers are defined as finite state machines, with states that you must name and define what the possible transitions are between them. It is actually allowed to have loops in the parser finite state machine, but the highest performance targets will typically restrict you to loops that can be unrolled to a compile-time known maximum number of iterations, e.g. for parsing a sequence of MPLS headers at most 5 headers long (where 5, or some other value, is a number you pick in your source code).
      • P4 is focused on packet header processing. Whatever part of a packet you do not parse into some header is, for that P4 program, considered the "payload" of the packet, which is typically carried along, unmodified, with the packet when you are done processing it. You can modify header fields however you like.
    • Add special constructs called tables, where for each one you define a search key consisting of a number of packet header fields and/or values of variables in your P4 program. Each table can also have one or more actions defined for them.
      • A P4 program represents only a small fraction of a complete working system. Control plane software that would typically be running on a general purpose CPU, written in one or more general purpose programming languages like C, C++, Java, Python, etc., is responsible for adding and removing entries to these tables, selecting for each entry the search key to be matched against, and the action to be executed if, while processing a packet, that table entry is matched.
    • A P4_16 "architecture" like the Portable Switch Architecture (PSA) also defines a library of other constructs, such as packet/byte counters, meters for enforcing average packet and/or bit rates on forwarded traffic, registers for some limited kinds of stateful packet processing, and methods for recirculating a packet, multicasting it to multiple destinations, etc.
    • Fields and variables can be integers of arbitrary bit width (up to some maximum size allowed by a particular implementation), with results of arithmetic operations well defined for all operations. P4 implementations need not implement floating point arithmetic, and I expect most would not because such things are not needed for the majority of packet processing applications. P4 implementations also need not implement multiplication, division, or modulo operations, again given that such operations are often not needed for most packet processing applications.
    • Note that integer arithmetic is sufficient for implementing fixed point operations, because fixed point add/subtract/shift can be viewed as the corresponding operations on integers that are in smaller units, e.g. an integer could be used to represent time in multiples of 0.8 nanoseconds, as opposed to in units of nanoseconds, which would be convenient if an implementation had a clock speed of 1.25 GHz and measured time in integer number of clock cycles (1 cycle / 0.8 nanosec = 1.25 GHz).
  • Some advantages of P4_16 over P4_14:

    • You can write assignments that look like C/C++/Java, rather than modify_field(dst, src); all over the place, and you can have arithmetic expressions on the right-hand side instead of add_to_field/subtract_from_field/etc. This is not additional power in the language, but it is a nice convenience for those familiar with those other languages.
    • You may call controls from other controls in P4_14, but there are no parameters or return values. All side effects must be done via access to global variables. In P4_16, there are no global variables -- you may pass parameters with directionality in, out, inout.
    • Tables must be, and externs may be, defined within the scope of a control, and are then accessible only from that control, which can be useful for keeping the code that accesses those objects closer to it, and knowing where they can be accessed from. Externs are used for things like counters, meters, and registers that were part of the base P4_14 language, but in P4_16 are defined as extern add-ons in the Portable Switch Architecture specification).
  • Disadvantages of P4_16 vs P4_14:

    • Tool and vendor support is not as good for P4_16 as of Jan 2018, but support for P4_16 is improving over time.
You can’t perform that action at this time.