Skip to content

Commit db898bc

Browse files
Vineet1101Vineet1101
authored
added docs for installing p4sim (#706)
* added docs for installing p4sim Signed-off-by: Vineet1101 <vineetgoel692@gmail.com> * added examples and p4sim section in the top level readme Signed-off-by: Vineet1101 <vineetgoel692@gmail.com> --------- Signed-off-by: Vineet1101 <vineetgoel692@gmail.com>
1 parent eb65f27 commit db898bc

4 files changed

Lines changed: 1254 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* [Introduction](#introduction)
77
* [Presentation](#presentation)
88
* [P4 Documentation](#p4-documentation)
9+
* [P4Sim] (#p4sim)
910
* [Obtaining required software](#obtaining-required-software)
1011
* [To build the virtual machine](#to-build-the-virtual-machine)
1112
* [Accessing the VM](#accessing-the-vm)
@@ -83,6 +84,23 @@ All exercises in this repository use the v1model architecture, the documentation
8384
1. The BMv2 Simple Switch target document accessible [here](https://github.com/p4lang/behavioral-model/blob/master/docs/simple_switch.md) talks mainly about the v1model architecture.
8485
2. The include file `v1model.p4` has extensive comments and can be accessed [here](https://github.com/p4lang/p4c/blob/master/p4include/v1model.p4).
8586

87+
## P4sim – A Simple P4 Behavioral Simulator
88+
89+
**P4sim** is a lightweight, dependency-free P4 packet-processing simulator designed for learning and experimentation.
90+
Unlike BMv2 or P4-DPDK, P4sim does **not** emulate a full switch pipeline. Instead, it provides a minimal execution environment that evaluates P4 parser, control, and deparser logic on user-provided packets.
91+
92+
P4sim is intended for:
93+
94+
* Running P4 programs without installing large data plane frameworks
95+
* Quickly testing parser and control-flow behavior
96+
* Understanding how P4 programs process packets step-by-step
97+
98+
P4sim is **not** a performance model and does not aim to replicate full-featured switch behavior (such as multitable pipelines, extern objects, or architecture-specific metadata).
99+
It is mainly a **teaching and debugging tool**.
100+
101+
To learn more or try P4sim examples, see:
102+
[`P4sim/README.md`](./doc/P4sim/README.md)
103+
86104
## Obtaining required software
87105

88106
If you are starting this tutorial at one of the proctored tutorial events,

‎doc/P4sim/README.md‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
# P4Sim: NS-3-Based P4 Simulation Environment
2+
3+
### Index
4+
5+
- [Local Deployment (ns-3.39)](#local-deployment-ns339)
6+
- Virtual Machine as Virtual Env
7+
- [ns-3 Version 3.x – 3.35](#setup-ns335)
8+
- [ns-3 Version 3.36 – 3.39](#setup-ns339)
9+
- [Appendix](#appendix)
10+
11+
## Installation & Usage Guide
12+
13+
It is recommended to use a **virtual machine** with Vagrant to simplify the installation and ensure compatibility.
14+
15+
## <a name="local-deployment-ns339"></a> Local Deployment (ns-3.39)
16+
17+
This guide walks you through setting up a local environment to run the P4Sim integrated with `ns-3.39` on Ubuntu 24.04. The full setup includes installing the behavioral model (`bmv2`), setting up SSH for remote access, and building the ns-3 project with P4Sim support. This is tested with `Ubuntu 24.04 LTS Desktop`.
18+
19+
> Note: The bmv2 and P4 software installation step will take **~3 hours** and consume up to **15GB** of disk space.
20+
21+
---
22+
23+
## 1. Initialize the Working Directory
24+
25+
Create a workspace and install basic development tools.
26+
27+
```bash
28+
sudo apt update
29+
mkdir ~/workdir
30+
cd ~/workdir
31+
sudo apt install git vim cmake
32+
```
33+
34+
---
35+
36+
## 2. Install P4 Behavioral Model (bmv2) and Dependencies
37+
38+
> This installs all necessary libraries and tools for P4 development (via the official `p4lang/tutorials` repo).
39+
40+
```bash
41+
cd ~
42+
git clone https://github.com/p4lang/tutorials
43+
mkdir ~/src
44+
cd ~/src
45+
../tutorials/vm-ubuntu-24.04/install.sh |& tee log.txt
46+
```
47+
48+
After installation, verify that `simple_switch` is available:
49+
50+
```bash
51+
simple_switch
52+
```
53+
54+
---
55+
56+
## 3. Clone and Build ns-3.39 with P4Simulator
57+
58+
### Step 3.1: Clone ns-3.39
59+
60+
```bash
61+
cd ~/workdir
62+
git clone https://github.com/nsnam/ns-3-dev-git.git ns3.39
63+
cd ns3.39
64+
git checkout ns-3.39
65+
```
66+
67+
### Step 3.2: Add P4Sim Module
68+
69+
```bash
70+
cd contrib
71+
git clone https://github.com/HapCommSys/p4sim.git
72+
cd p4sim
73+
sudo ./set_pkg_config_env.sh
74+
```
75+
76+
### Step 3.3: Configure and Build
77+
78+
```bash
79+
cd ../..
80+
./ns3 configure --enable-tests --enable-examples
81+
./ns3 build
82+
```
83+
84+
---
85+
86+
## 4. Run an Example
87+
88+
You can run a built-in example using:
89+
90+
```bash
91+
./ns3 run "exampleA" # This will run exampleA (name).
92+
```
93+
94+
---
95+
96+
## 5. Configure P4 Files in Your Simulation
97+
98+
You may need to **manually update file paths** for P4 artifacts in your simulation code.
99+
100+
Example path updates:
101+
102+
```cpp
103+
// p4 is the username
104+
std::string p4JsonPath = "/home/p4/workdir/ns3.39/contrib/p4sim/test/test_simple/test_simple.json";
105+
std::string flowTablePath = "/home/p4/workdir/ns3.39/contrib/p4sim/test/test_simple/flowtable_0.txt";
106+
std::string topoInput = "/home/p4/workdir/ns3.39/contrib/p4sim/test/test_simple/topo.txt";
107+
```
108+
109+
Make sure these paths match your actual working directory and files.
110+
111+
---
112+
113+
## Done!
114+
115+
You now have a working ns-3.39 simulator with P4 integration ready for your experiments.
116+
117+
---
118+
119+
## Feedback or Issues?
120+
121+
If you encounter problems or have suggestions, feel free to open an issue or contact the maintainer.
122+
123+
**Contact:** mingyu.ma@tu-dresden.de
124+
125+
126+
127+
# Virtual Machine as virtual env ##
128+
129+
`p4sim` integrates an NS-3-based P4 simulation environment with virtual machine configuration files sourced via sparse checkout from the [P4Lang Tutorials repository](https://github.com/p4lang/tutorials/tree/master).
130+
131+
The `vm` directory contains Vagrant configurations and bootstrap scripts for Ubuntu-based virtual machines (Ubuntu 24.04 recommended). These pre-configured environments streamline the setup process, ensuring compatibility and reducing installation issues.
132+
133+
Tested with:
134+
- P4Lang Tutorials Commit: `7273da1c2ac2fd05cea0a9dd0504184b8c955eae`
135+
- Date: `2025-01-25`
136+
137+
Notes:
138+
- Ensure you have `Vagrant` and `VirtualBox` installed before running `vagrant up dev`.
139+
- The setup script (`set_pkg_config_env.sh`) configures the required environment variables for P4Sim.
140+
- `Ubuntu 24.04` is the recommended OS for the virtual machine.
141+
142+
---
143+
144+
## <a name="setup-ns335"></a> Setup Instructions for ns-3 version 3.x - 3.35 (Build with `waf`)
145+
146+
This has been tested with ns-3 repo Tag `ns-3.35`.
147+
148+
### 1. Build the Virtual Machine
149+
```bash
150+
# with vm-ubuntu-24.04/Vagrantfile or vm-ubuntu-20.04/Vagrantfile
151+
vagrant up dev
152+
153+
sudo apt update
154+
sudo apt install git vim
155+
156+
cd ~
157+
git clone https://github.com/p4lang/tutorials
158+
mkdir ~/src
159+
cd ~/src
160+
../tutorials/vm-ubuntu-24.04/install.sh |& tee log.txt
161+
```
162+
163+
Please also **check the webpage**: [Introduction build venv of vm-ubuntu-24.04](https://github.com/p4lang/tutorials/tree/7273da1c2ac2fd05cea0a9dd0504184b8c955eae/vm-ubuntu-24.04#introduction), current version you need to install the tools by yourself: [install](https://github.com/p4lang/tutorials/tree/7273da1c2ac2fd05cea0a9dd0504184b8c955eae/vm-ubuntu-24.04#installing-open-source-p4-development-tools-on-the-vm)
164+
165+
This will create a virtual machine with name "P4 Tutorial Development" with the date. Please **test with `simple_switch` command**, to test if the `bmv2` is correct installed. Later we use the libs.
166+
167+
### 2. Clone the NS-3 Repository
168+
```bash
169+
cd
170+
mkdir workdir
171+
cd workdir
172+
git clone https://github.com/nsnam/ns-3-dev-git.git ns3.35
173+
cd ns3.35
174+
git checkout ns-3.35
175+
```
176+
177+
### 3. Clone & Integrate `p4sim` into NS-3
178+
```bash
179+
cd /home/p4/workdir/ns3.35/contrib/
180+
git clone https://github.com/HapCommSys/p4sim.git
181+
```
182+
183+
### 4. Set Up the Environment (for external libs)
184+
```bash
185+
cd /home/p4/workdir/ns3.35/contrib/p4sim/ # p4sim root directory
186+
sudo ./set_pkg_config_env.sh
187+
```
188+
189+
### 5. Patch for the ns-3 code
190+
```bash
191+
cd ../../ # in ns-3 root directory
192+
git apply ./contrib/p4sim/doc/changes.patch
193+
```
194+
195+
### 6. Configure & Build NS-3
196+
```bash
197+
# in ns-3 root directory
198+
./ns3 configure --enable-examples --enable-tests
199+
./ns3 build
200+
```
201+
202+
### 7. Run a Simulation Example
203+
```bash
204+
./ns3 run "exampleA" # This will run exampleA (name).
205+
206+
# In the p4sim example, you may need to adjust the path of p4 and other files.
207+
# For example:
208+
# std::string p4JsonPath =
209+
# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/test_simple.json";
210+
# std::string flowTablePath =
211+
# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/flowtable_0.txt";
212+
# std::string topoInput = "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/topo.txt";
213+
```
214+
215+
---
216+
217+
## <a name='setup-ns339'></a> Setup Instructions for ns-3 version 3.36 - 3.39 (Build with `Cmake`)
218+
219+
This has been tested with ns-3 repo Tag `ns-3.39`. Because the virtual machine will build BMv2 and libs with **C++17**, and ns-3 p4simulator using the external inlucde file and libs, therefore the ns-3 also need to build with **C++17**.
220+
The include file is: `/usr/local/include/bm`, the libs is `/usr/local/lib/libbmall.so`.
221+
222+
223+
### 1. Build the Virtual Machine
224+
```bash
225+
# with vm-ubuntu-24.04/Vagrantfile or vm-ubuntu-20.04/Vagrantfile
226+
vagrant up dev
227+
228+
sudo apt update
229+
sudo apt install git vim
230+
231+
cd ~
232+
git clone https://github.com/p4lang/tutorials
233+
mkdir ~/src
234+
cd ~/src
235+
../tutorials/vm-ubuntu-24.04/install.sh |& tee log.txt
236+
237+
```
238+
239+
Please also **check the webpage**: [Introduction build venv of vm-ubuntu-24.04](https://github.com/p4lang/tutorials/tree/7273da1c2ac2fd05cea0a9dd0504184b8c955eae/vm-ubuntu-24.04#introduction), current version you need to install the tools by yourself: [install](https://github.com/p4lang/tutorials/tree/7273da1c2ac2fd05cea0a9dd0504184b8c955eae/vm-ubuntu-24.04#installing-open-source-p4-development-tools-on-the-vm)
240+
241+
This will create a virtual machine with name "P4 Tutorial Development" with the date. Please **test with `simple_switch` command**, to test if the `bmv2` is correct installed. Later we use the libs.
242+
243+
### 2. install Cmake
244+
```bash
245+
sudo apt update
246+
sudo apt install cmake
247+
248+
```
249+
250+
### 3. Clone the NS-3 Repository
251+
```bash
252+
cd
253+
mkdir workdir
254+
cd workdir
255+
git clone https://github.com/nsnam/ns-3-dev-git.git ns3.39
256+
cd ns3.39
257+
git checkout ns-3.39
258+
```
259+
260+
### 4. Clone & Integrate `p4sim` into NS-3
261+
```bash
262+
cd /home/p4/workdir/ns3.39/contrib/
263+
git clone https://github.com/HapCommSys/p4sim.git
264+
```
265+
266+
### 5. Set Up the Environment (for external libs)
267+
```bash
268+
cd /home/p4/workdir/ns3.39/contrib/p4sim/ # p4sim root directory
269+
sudo ./set_pkg_config_env.sh
270+
```
271+
272+
### 6. Configure & Build NS-3
273+
```bash
274+
# in ns-3 root directory
275+
./ns3 configure --enable-tests --enable-examples
276+
./ns3 build
277+
```
278+
279+
### 7. Run a Simulation Example
280+
```bash
281+
./ns3 run "exampleA" # This will run exampleA (name).
282+
283+
# In the p4sim example, you may need to adjust the path of p4 and other files.
284+
# For example:
285+
# std::string p4JsonPath =
286+
# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/test_simple.json";
287+
# std::string flowTablePath =
288+
# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/flowtable_0.txt";
289+
# std::string topoInput = "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/topo.txt";
290+
```
291+
292+
---
293+
294+
# Install on a local machine
295+
296+
Not been tested yet.
297+
298+
# References
299+
300+
[1] [add_specific_folder_with_submodule_to_a_repository](https://www.reddit.com/r/git/comments/sme7k4/add_specific_folder_with_submodule_to_a_repository/)
301+
302+
[2] [P4Lang Tutorials repository](https://github.com/p4lang/tutorials/tree/master)
303+
304+
# <a name='appendix'></a> Appendix
305+
306+
After `Install P4 Behavioral Model (bmv2) and Dependencies`, you should have that:
307+
308+
```bash
309+
# For the libs
310+
(p4dev-python-venv) mm@bb24:~$ ls /usr/local/lib/ | grep bm
311+
libbmall.a
312+
libbmall.la
313+
libbmall.so
314+
libbmall.so.0
315+
libbmall.so.0.0.0
316+
libbm_grpc_dataplane.a
317+
libbm_grpc_dataplane.la
318+
libbm_grpc_dataplane.so
319+
libbm_grpc_dataplane.so.0
320+
libbm_grpc_dataplane.so.0.0.0
321+
libbmp4apps.a
322+
libbmp4apps.la
323+
libbmp4apps.so
324+
libbmp4apps.so.0
325+
libbmp4apps.so.0.0.0
326+
libbmpi.a
327+
libbmpi.la
328+
libbmpi.so
329+
libbmpi.so.0
330+
libbmpi.so.0.0.0
331+
332+
# For the include files
333+
(p4dev-python-venv) mm@bb24:~$ ls /usr/local/include/bm
334+
bm_apps PI PsaSwitch.h SimplePreLAG.h SimpleSwitch.h standard_types.h
335+
bm_grpc pna_nic_constants.h psa_switch_types.h simple_pre_lag_types.h simple_switch_types.h thrift
336+
bm_runtime PnaNic.h simple_pre_constants.h simple_pre_types.h spdlog
337+
bm_sim pna_nic_types.h SimplePre.h simple_switch standard_constants.h
338+
config.h psa_switch_constants.h simple_pre_lag_constants.h simple_switch_constants.h Standard.h
339+
340+
```
341+
342+
After running `sudo ./set_pkg_config_env.sh`, you should have that: (In between, we only use bm.)
343+
344+
```bash
345+
# set_pkg_config_env.sh, the p4simulator module requires the first (bm)
346+
pkg-config --list-all | grep xxx
347+
bm BMv2 - Behavioral Model
348+
simple_switch simple switch - Behavioral Model Target Simple Switch
349+
boost_system Boost System - Boost System
350+
351+
# SPD log from BMv2 should be blocked, ns-3 has it's own logging system.
352+
```

0 commit comments

Comments
 (0)