Skip to content

Commit

Permalink
Merge pull request #384 from smittal-bf/main
Browse files Browse the repository at this point in the history 
Update compiling-p4-programs.md
  • Loading branch information
@smittal-bf
smittal-bf authored Jan 24, 2024
2 parents 2a3ebc9 + 8cb7ccb commit ce1e48f
Showing 1 changed file with 103 additions and 108 deletions.
211 changes: 103 additions & 108 deletions docs/guides/es2k/compiling-p4-programs.md
View file
Original file line number Diff line number Diff line change
@@ -1,135 +1,130 @@
# Compiling P4 Programs for ES2K

## 1. Overview
This document explains how to install and use the Intel® IPU E2100 P4Tools
Container to compile a P4 program to build artifacts, including the `.pkg`
file, that can be deployed on ES2K.

This document explains how to install the Intel® IPU E2100 P4 Compiler
(`p4c-pna-xxp`) and Configurable Pipeline Tool (`cpt`), and use
them to compile a P4 program
The supported host OSes are listed in the "Supported Operating Systems"
section of the IPU Software User Guide (RDC Doc#778226), henceforth referred to
as the "IPU SWG".

## 2. Installing the P4 Compiler and Tools
## Build and run the P4Tools container

### 2.1 Install RPMs
The tools required to compile and build a custom p4 package
can be installed by building the P4 Tools Container.

Install the `cpt`, `p4c-pna-xxp`, and `p4-sde` packages on a
Fedora 37 x86_64 server, from RPMs in the release tarball.
See "Getting Started Guide with P4 on P4 Tools Container" in the
IPU SWG for instructions on building and launching the P4 Tools container.

```bash
# Extract RPMs from the tarball
tar xvzf mev-hw-b0-<release>-fedora37.tgz
cd host/packages/x86_64/
Once <your_p4_tools_container> is sucessfully built, proceed to the next step.

# Install RPMs on server
rpm -i cpt-<version>-ci.ts.release.<xxxx>.ehb0.5.15.fc37.x86_64.rpm
dnf localinstall p4c*.rpm --allowerasing
dnf localinstall p4-sde*.rpm --allowerasing
```

The packages will be installed under `/usr` directory. Note that these
RPMs are not relocatable.

### 2.2 Confirm tool versions

After installing the RPMs, verify the version numbers of the executables:
### Launch the P4Tools container

```bash
# Set environment variables
export LD_LIBRARY_PATH=/usr/lib:/usr/lib64:/usr/local/lib:/usr/local/lib64:$LD_LIBRARY_PATH

[root@host ~]# cpt --version
Intel(R) Configurable Pipeline Tool Version 3.8.0.16
Copyright (C) 2022 Intel Corporation. All rights reserved.
# Launch the P4Tools container on the host.
[user@host P4Tools] sudo docker exec -it <your_p4_tools_container> /bin/bash

[root@host ~] # p4c-pna-xxp --version
p4c-pna-xxp
Version 3.0.70.7
# Inside the container, verify the p4 compiler version.
[root@a54d354e447e /] p4c --version
p4c 1.2.3.7 (SHA: BUILD: release)
```

### 2.3 Address "no such file" error

If the `p4c-pna-xxp --version` command displays the following error message:

```text
error while loading shared libraries: libboost_iostreams.so.1.69.0:\
cannot open shared object file: No such file or directory
```
The `p4c` compiler should now be ready for use.

You will need to download and install the correct version of the Boost
libraries.

```bash
wget https://boostorg.jfrog.io/artifactory/main/release/1.69.0/source/boost_1_69_0.tar.gz
tar -xf boost_1_69_0.tar.gz
cd boost_1_69_0/
./bootstrap.sh
./b2
./b2 install
```

Verify the compiler version number:

```bash
[root@host ~] # p4c-pna-xxp --version
p4c-pna-xxp
Version 3.0.70.7
```
In previous versions of the SDK, `cpt` had to be invoked separately.
It is no longer necessary to do so.
`cpt` will be invoked automatically by specifying cpt flags to `p4c`.

The compiler should now be ready for use.
## Build reference P4 programs

## 3. P4 Reference Files
The `p4-programs` directory in the SDK folder contains a number of sample P4
programs. The SDK is contained in a tar file named
`intel-ipu-sdk-source-code-<$VERSION>.tgz`.

The `/usr/share/mev_reference_p4_files/` directory contains a number of sample
P4 programs.
Extract the p4-programs from the tarball.

```bash
[root@host ~]# ls -l /usr/share/mev_reference_p4_files/
total 28
-rw-r--r--. 1 root root 79 Jun 8 08:06 CONTENTS
drwxr-xr-x. 2 root root 4096 Jun 8 03:21 linux_networking
-rw-r--r--. 1 root root 1104 Jun 8 08:06 mev_sample.conf
drwxr-xr-x. 2 root root 4096 Jun 8 03:21 pna_connection_track
drwxr-xr-x. 2 root root 4096 Jun 8 03:21 simple_l2_demo
drwxr-xr-x. 2 root root 4096 Jun 8 03:21 simple_l2_mod_demo
drwxr-xr-x. 2 root root 4096 Jun 8 03:21 simple_l3_l4_pna
[root@host ~] ls -l $INTEL-IPU-SDK-<VERSION>/tools/pipeline/p4-programs
total 1100
-rw-r--r--. 1 user user 79 Dec 13 15:54 CONTENTS
drwxr-xr-x. 10 user user 4096 Dec 13 15:54 fxp-cxp-features
drwxr-xr-x. 10 user user 4096 Dec 13 15:54 fxp-net-scenarios
drwxr-xr-x. 7 user user 106 Dec 13 15:54 layer-2-forwarding
drwxr-xr-x. 8 user user 116 Dec 13 15:54 layer-3-forwarding
-rw-r--r--. 1 user user 81529 Dec 23 03:09 Makefile
-rw-r--r--. 1 user user 1494 Dec 13 15:54 mev_sample.conf
drwxr-xr-x. 2 user user 131 Dec 13 15:54 testsuite
```

Each P4 program has its own directory and an accompanying README file that
provides instructions on how to configure the IPU pipeline.

## 4. Compiling a P4 Program

Use `p4c-pna-xxp` to compile a P4 program. We will be using one of the reference
programs mentioned above.

```bash
# Set environment variables
export LD_LIBRARY_PATH=/usr/lib:/usr/lib64:/usr/local/lib:/usr/local/lib64:$LD_LIBRARY_PATH
export OUTPUT_DIR=/usr/share/mev_reference_p4_files/simple_l3_l4_pna

# Compile p4 program
p4c-pna-xxp -I/usr/lib -I/usr/share/p4c/p4include -I/usr/share/p4c/idpf-lib \
$OUTPUT_DIR/simple_l3_l4_pna.p4 -o $OUTPUT_DIR/simple_l3_l4_pna.s \
--p4runtime-files $OUTPUT_DIR/simple_l3_l4_pna.p4info.txt \
--context $OUTPUT_DIR/simple_l3_l4_pna.context.json \
--bfrt $OUTPUT_DIR/simple_l3_l4_pna.bf-rt.json
```

The compiler will generate the following files:

- simple_l3_l4_pna.p4info.txt
- simple_l3_l4_pna.bf-rt.json
- simple_l3_l4_pna.context.json
- simple_l3_l4_pna.s

These files are called _P4 artifacts_.

## 5. Generating a Pkg File

Use `cpt` to prepare the P4 artifacts for deployment:

```bash
cpt --npic --format csr --pbd -o simple_l3_l4_pna.pkg \
cpt_ver.s simple_l3_l4_pna.s
```
### Compiling a P4 Program

Use the `p4c` compiler driver to compile and build packages.
We will be using one of the reference programs mentioned above as an
example: `p4-programs/layer-3-forwarding/l3-fwd_p2p`.

The Makefile contains the exact commands to build the artifacts
for all the reference programs.

1. Copy the entire p4-programs directory from the host to the P4Tools
container.

```bash
sudo docker cp p4-programs/ <p4Tools container id>:/opt/
```

2. Set environment variables in the container prior to building.

```bash
[root@a54d354e447e p4-programs] which p4c
/opt/p4-tools/p4c/bin/p4c
[root@a54d354e447e p4-programs] export P4C_PATH=/opt/p4-tools/p4c/bin
export CPT_PATH=/opt/p4-tools/cpt/bin
export PATH=$P4C_PATH:$CPT_PATH:$PATH
export LD_LIBRARY_PATH=$P4C_PATH/../lib:/usr/local/lib:$LD_LIBRARY_PATH
export PREV_ARTIFACT_DIR=
```

3. Compile l3-fwd_p2p. All artifacts will be generated in the artifacts
directory.

```bash
[root@a54d354e447e ~] cd /opt/p4-programs

# Compiling /opt/p4-programs/layer-3-forwarding/l3-fwd_p2p/l3-fwd_p2p.p4
# and generating the runtime files and assembly...
[root@a54d354e447e p4-programs] make l3-fwd_p2p
/opt/p4-tools/p4c/bin/p4c --target idpf --arch pna
-I/opt/p4-tools/p4c/bin/../lib -I/opt/p4-tools/p4c/bin/../share/p4c/p4include
-I/opt/p4-tools/p4c/bin/../share/p4c/idpf-lib --package-by-domain
--p4runtime-files ./artifacts/l3-fwd_p2p/p4Info.txt --save-temps
-Xp4c "--Wdisable --no-pedantic --context ./artifacts/l3-fwd_p2p/context.json
--bfrt ./artifacts/l3-fwd_p2p/bf-rt.json"
--save-temps --npic --format csr --pkg-version 1.2 --pkg-name "FXP Package"
-Xassembler ".cpt_ver.s" /opt/p4-programs/layer-3-forwarding/l3-fwd_p2p/l3-fwd_p2p.p4
-o artifacts/l3-fwd_p2p
```

4. All output files, including the `.pkg` file, will be in the artifacts
directory.

```bash
[root@a54d354e447e p4-programs] ls -lrt artifacts/l3-fwd_p2p/
total 2884
-rw-r--r--. 1 root root 950608 Dec 22 23:57 l3-fwd_p2p_0b32dac62c9b4c18b3213e04a6bb8c5b.pkgo
-rw-r--r--. 1 root root 3045 Dec 23 00:18 p4Info.txt
-rw-r--r--. 1 root root 8866 Dec 23 00:18 bf-rt.json
-rw-r--r--. 1 root root 30390 Dec 23 00:18 context.json
-rw-r--r--. 1 root root 37269 Dec 23 00:18 l3-fwd_p2p.s
-rw-r--r--. 1 root root 950608 Dec 23 00:18 l3-fwd_p2p_b222a542c1474685bd70a36994d16101.pkgo
-rw-r--r--. 1 root root 950608 Dec 23 00:18 l3-fwd_p2p.pkg
```

These files are called _P4 artifacts_.

## Deploying P4 programs

Please see [Deploying P4 Programs](deploying-p4-programs.md)
for details about deployment.

0 comments on commit ce1e48f

Please sign in to comment.