Repository files navigation

O4 is a domain-specific data-plane programming language, allowing to specify custom packet handling in programmablenetwork devices. It compiles to P4, and is therefore compatible with all state-of-the-art P4 targets. With O4 one canwrite more concise software, reducing the required lines of code of up to 80% compared to an equivalent P4implementation.

code/├── examples/               - P4/O4 Example Program├── metrics/                - Implementations of Evaluation Metrics├── o4/                     - O4 Compiler├── p4include/├── plots/              │   ├── result_plots.py     - Evaluation Plots│   ├── survey.csv          - Raw Survey Results│   └── survey_plots.py     - Survey Plots├── docker-compose.yml├── README.md└── requirements.txt        - Requirements for Python Scripts

The current O4 compiler runs with:

• P4-16 version: 1.2.2
• Racket version: 8.1 or higher

To setup the O4 compiler, make sure you have Racket installed:

$ racket --versionWelcome to Racket v8.1 [cs].

Then install theo4 package from the repository root:

raco pkg install code/o4

Now compile the given test file from the repository root to make sure everything works as expected:

$ racket code/o4/test.o4Finished lexing and parsing of source in 0.006 secondsFinished back end compilation in 0.112 secondsFinished writing compilation output to file code/examples/o4_compilation_output.p4

Optional: The O4 compiler can directly invoke the P4 compiler after it has finished. To set this up, one has tosetrun_p4_compiler totrue and configurep4_compiler_executable andp4_compiler_argumentsinconfig.json accordingly.

For more information seeInvoking the P4 compiler.

Make sure that you finished theSetup and have verified that the compiler works as expected.

An O4 source file has to start with#lang o4 followed by a newline:

#lang o4header header_t {    bit<32>[4] values;}struct headers {    header_t test_header;}control test_control(inout headers hdr) {    factory test_factory (int index, bit<32> value) {        action test_action () {            hdr.test_header.values[index] = value;        }        return test_action;    }    apply {        for (int i in [0, 1, 2, 3]) {            test_factory(i, (bit<32>) i)();        }    }}

To compile an O4 source file, run the O4 compiler from the repository root (otherwise the relative paths might not workas intended):

$ racket path/from/repository/root/to/o4/source/file

The O4 compiler allows to automatically invoke a subprocess after the compilation finished successfully. This can beused to chain together the O4 and P4 compilers.

To turn this feature on, you have to setrun_p4_compiler totrue in theconfig.json file. In the same file you canalso specify which executable to run, withp4_compiler_executable. To pass any arguments to the call you can usethep4_compiler_arguments.

We provide a docker-compose file that sets up ap4c Docker container and maps allrequired files into it, allowing to execute any p4c call with little setup required. If you pointthep4_compiler_executable to your local Docker executable, the pre-configured command in the config file will callthe p4c pretty-printer.

If you instead want to further compile the output of the O4 compiler onto a BMv2 target, you have to adapt the commandin the config file to match:

docker compose -f code/docker-compose.yml run --rm p4c --target bmv2 --arch v1model o4_compilation_output.p4

The O4 compiler ships with a suite of over 230 test cases, which test many of the most important features of thecompiler implementation.

To run these test, first install theo4 package as described inSetup, then simply run:

raco test -p o4

To make a deep dive into the source code easier, we provide an overview of the most important components of the O4compiler and their interactions. This section assumes some familiarity with Racket and the#lang functionality.

Themain.rkt file is a good starting point for getting into the code, as it contains both theread-syntax procedureand the#%module-begin macro of the O4 language. The main file also contains calls to theparse function ofthebrag library, invoking the front end, using the tokenizer infrontend/lexer-tokenizer.rkt and the grammarinfrontend/parser.rkt, to tokenize and parse the input file. Furthermore, it contains the call too4-program, theentrypoint to the backend, with its binding given inbackend/o4-program.rkt

The backend logic is split into individual sections that correspond to the commented sections in the O4 grammar. Animportant part of the back end is the context data structure, which stores global information that is passed throughoutall predicates in the back end. The context is always required via the globalcontext.rktfile, which is done purely for convenience. The actual context logic is defined in the files in thecontext/ folder.If you decide to dig into the context logic, we recommend to start with thecontext/base.rkt file, as it contains themain struct definitions and helper functions used throughout the context logic.

It might also make sense to have a look at the commonly used utility functions inutils/util.rkt, before diving intothe back end code.

Additional to the O4 language, we provide two helper dialects that allow to investigate the output of the tokenizer andparser respectively.

To invoke these dialects, simply change the#lang line in an O4 program to#lang o4/utils/tokenize-onlyor#lang o4/utils/parse-only and run the file using the usualracket command.

The following is an overview of the current limitations of the O4 compiler:

• The architecture definition sub-language is not supported (extern-, error-, match-kind-, parser-type-, control-type-,package-type-declarations).
• Annotations are not supported (do not cause syntax errors, but are simply ignored).
• Theheader_union,type,switch,this andabstract keywords and their respective functionality are notsupported.
• Valuesets are not supported.
• The ternary operator is not supported.
• Header stacks are not detected and will be treated as arrays (they will be expanded).
• Dot-prefixed variables are not fully supported.
• Tuple types are not fully supported.
• Only very basic type checking is performed (e.g. one can use incompatible types for factory parameters and arguments).
• Array types cannot be used in typedef declarations, as function return types, in specified enum declarations, in castexpressions, in type argument lists and as loop iterators.
• Factory bodies can only be instances ofaction,table andextern types.
• for loops can only loop over 1D arrays.

• The proceduresset-variable,set-parameter,set-factory andset-factory-call are missing error handlers.
• Certain usages of expression arrays allow for arrays with improper structure.