Guide to p4lang repositories and some other public info about P4
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
action-profile-and-selector Add a couple of links to new README-troubleshooting.md file Sep 21, 2018
bin Update example working log for Ubuntu 18.04 running install-p4dev-p4r… Oct 18, 2018
calling-convention Add a couple of links to new README-troubleshooting.md file Sep 21, 2018
checksum Update README for checksum example with latest status -- it works! Sep 21, 2018
control-plane-types Add simple P4_16 v1model arch program with digest and its JSON P4Info… Apr 20, 2018
demo1 Do an editing pass on README-p4runtime.md Oct 18, 2018
demo2 Update to latest recommended p4c command line options for compiling May 26, 2018
demo3 Update to latest recommended p4c command line options for compiling May 26, 2018
demo4 Update a few older style p4c commands Aug 11, 2018
demo5 Update a few older style p4c commands Aug 11, 2018
docs Added another potential down side of using hit indexes for a TCAM tha… Jul 20, 2018
editor-support Add 'type' as new keyword for P4_16 syntax highlighting in Emacs Aug 19, 2018
instantiation Refine notes on hash tables to specifically multi-way hash tables Feb 21, 2018
linux-veth-bug Add new Ubuntu Linux kernel version to test results page Oct 2, 2018
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
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 One more small fix to TCP option parsing example code Nov 10, 2017
transcript Add partial transcript of a LightReading webinar on P4Runtime Jul 18, 2018
v1model-special-ops A little more massaging of v1model-special-ops docs Oct 4, 2018
README-demos.md Add links to new install script and README for trying P4Runtime API s… Oct 17, 2018
README-editor-support.md Add instructions for installing Exuberant ctags on macOS Aug 27, 2018
README-header-stacks.md Add links to related Github issues Sep 29, 2017
README-p4lang-repos.md Update a few older style p4c commands Aug 11, 2018
README-scapy.md Add some details of Scapy versions while tracking down UDP checksum bugs Oct 27, 2017
README-troubleshooting.md Add a couple of links to new README-troubleshooting.md file Sep 21, 2018
README-using-bmv2.md Add a couple of links to new README-troubleshooting.md file Sep 21, 2018
README.md Add links to new install script and README for trying P4Runtime API s… Oct 17, 2018
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 Add 'return <expression>' explicitly as supported inside function def… Oct 2, 2018
p4-16-allowed-constructs.pdf Add 'return <expression>' explicitly as supported inside function def… Oct 2, 2018
p4-16-allowed-constructs.png Add 'return <expression>' explicitly as supported inside function def… Oct 2, 2018
p4-16-allowed-constructs.txt Add 'return <expression>' explicitly as supported inside function def… Oct 2, 2018

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

    • Two 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:
      • The older shell script installs simple_switch, which uses the older Thrift API protocol to communicate with a controller.
      • The newer shell script also installs simple_switch_grpc, which uses the newer P4Runtime API protocol to communicate with a controller.
    • A figure with the dependencies between these repositories.
  • 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 emulator from the behavior_model repository, including interactively adding table entries to the tables, and send packets using Scapy that will be processed by the emulator.
  • 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.

  • Another useful 'cheat sheet' with example snippets of code is in the p4lang/tutorials repository.

  • A very brief overview of P4 (in about 500 words), to get a flavor for what it is like:

    • 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.
    • 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 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.
  • 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.
    • Controls could call other controls in P4_14, but there were no parameters or return values. All side effects had to 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. Extern 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 this is gradually changing.