P4sim is a P4-driven network simulator that integrates P4, the programmable data plane language, with ns-3, one of the most widely used network simulators. It embeds the BMv2 behavioral model so that user-written P4 programs execute inside ns-3 simulations, producing bit-accurate forwarding behaviour.
P4sim is open-source software licensed under the Apache License 2.0.
- Mingyu Ma, Giang T. Nguyen. "P4sim: Programming Protocol-independent Packet Processors in ns-3." 2025. [ACM DL] [arXiv]
- Reproducibility artifact: p4sim-artifact-icns3 — accepted at the 2025 International Conference on ns-3 (ICNS3).
Our implementation builds upon the P4-driven Network Simulator Module described in:
- Bai, Jiasong, et al. "NS4: Enabling programmable data plane simulation." Proc. of the Symposium on SDN Research, pp. 1–7, 2018. [ACM DL]
- Fan, Chengze, et al. "NS4: A P4-driven network simulator." Proc. of the SIGCOMM Posters and Demos, pp. 105–107, 2017. [ACM DL]
See the full step-by-step guide in doc/vm-env.md.
Quick start (assuming BMv2 is already installed):
cd <ns-3-root>/contrib
git clone https://github.com/HapCommSys/p4sim.git
cd p4sim && sudo ./set_pkg_config_env.sh
cd ../..
./ns3 configure --enable-tests --enable-examples
./ns3 build
# Set the environment variable (add to ~/.bashrc for persistence)
export P4SIM_DIR="$PWD/contrib/p4sim"
# Run an example
./ns3 run p4-v1model-ipv4-forwarding| Value | Architecture | BMv2 Target |
|---|---|---|
| 0 | V1model | simple_switch |
| 1 | PSA | psa_switch |
| 2 | PNA | pna_nic |
The forwarding behaviour is defined by the P4 program and its flow-table configuration. The following ns-3 attributes on ns3::P4SwitchNetDevice control simulation-level settings:
| Attribute | Description |
|---|---|
JsonPath |
Path to the compiled P4 JSON file |
FlowTablePath |
Path to the flow-table configuration file |
P4SwitchArch |
Architecture selector (0 = V1model, 1 = PSA, 2 = PNA) |
ChannelType |
Channel type (0 = CSMA, 1 = point-to-point) |
SwitchRate |
Processing rate in packets per second |
QueueBufferSize |
Total queue buffer size (packets) |
InputBufferSizeLow |
Input buffer size for low-priority (external) packets |
InputBufferSizeHigh |
Input buffer size for high-priority (internal) packets |
EnableTracing |
Enable basic throughput tracing |
EnableSwap |
Enable runtime swapping of the P4 configuration |
Notes:
- When using a CSMA channel, the P4 program must handle ARP explicitly.
- Buffer attributes only take effect if the selected architecture models that buffer.
EnableTracingcurrently supports basic throughput measurement only.
See the full list and descriptions in doc/examples.md.
Selected examples:
| Script | Description |
|---|---|
p4-v1model-ipv4-forwarding |
2-host, 1-switch IPv4 forwarding (V1model) |
p4-psa-ipv4-forwarding |
Same topology, PSA architecture |
p4-basic-example |
4-host, 4-switch mesh (V1model) |
p4-basic-tunnel |
3-host tunnel with custom header |
p4-firewall |
Stateful firewall |
p4-l3-router |
3-router line topology, L3 forwarding |
p4-link-monitoring |
In-band link utilisation probes |
p4-spine-leaf-topo |
Spine-leaf with ECMP load balancing |
p4-topo-fattree |
Auto-generated fat-tree topology |
p4-queue-test |
QoS-aware queuing |
p4-source-routing |
Source routing with custom headers |
p4-basic-controller |
Runtime controller flow-table updates |
sudo apt install doxygen graphviz dia
./ns3 configure --enable-tests --enable-examples
./ns3 build
./ns3 docs doxygen
xdg-open build/doxygen/html/index.html