P4sim is a high-performance simulation framework that brings P4-programmable data plane processing into the ns-3 network simulator. It enables researchers and developers to model, execute, and evaluate P4 programs within realistic end-to-end network simulations, tightly coupling a P4-driven packet processing engine with ns-3's flexible network modeling for fine-grained analysis of programmable networks at scale.

P4sim is open-source software licensed under the Apache License 2.0.

Key Features

• Behavioral accuracy: the packet processing pipeline is based on BMv2, ensuring the same reference behavior model used by the broader P4 community.
• ns-3 integration: network topology, traffic generation, and timing are fully managed by ns-3, making it straightforward to configure experiments or compose P4sim with other ns-3 modules.
• BMv2 compatibility: existing P4 programs and flow-table entry scripts written for BMv2 can be used directly in P4sim without modification.
• Accurate timing models: packet scheduling and queuing faithfully reflect realistic network timing behavior.
• High-performance simulation: designed to handle large-scale network scenarios and high traffic rates in ns-3 simulation environments.

Architectural Overview

This repository provides two P4 switch architectures in ns-3. Arch 1 (main branch) follows a bridge-based design, where each port corresponds to an external NetDevice (e.g., CSMA or P2P), offering flexibility but limited control over port-level behavior. Arch 2 (switch_channel branch) introduces a switch-centric design, in which ports are internal components of the P4SwitchNetDevice and interconnected via a switched Ethernet channel, enabling fine-grained control, improved modularity, and closer alignment with real-world programmable switch architectures.

The branch switch_channel now is ongoing development and may contain breaking changes. The main branch is stable and recommended for users who want to get started with P4sim immediately.

Publications

• 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]

Installation & Setup

The following steps set up a local environment to run P4sim with ns-3.39 on Ubuntu 24.04 LTS.

Note: The BMv2 and P4 software installation will take 1–2 hours and consume up to 15 GB of disk space.

Why ns-3.39 or earlier? Starting from ns-3.40, ns-3 requires C++20. However, BMv2 is currently built with C++17. P4sim therefore supports ns-3.39 and earlier versions. We plan to upgrade once a C++20-compatible BMv2 build becomes available.

Step 1: Initialize the Working Directory

sudo apt update
sudo apt install git vim cmake
mkdir ~/workdir && cd ~/workdir

Step 2: Install BMv2 and P4 Dependencies

Install all required libraries and tools via the official p4lang/tutorials repository:

cd ~
git clone https://github.com/p4lang/tutorials
mkdir ~/src && cd ~/src
../tutorials/vm-ubuntu-24.04/install.sh |& tee log.txt

Verify the installation:

Step 3: Clone and Build ns-3.39 with P4sim

cd ~/workdir
git clone https://github.com/nsnam/ns-3-dev-git.git ns3.39
cd ns3.39 && git checkout ns-3.39

Add the P4sim module:

cd contrib
git clone https://github.com/HapCommSys/p4sim.git
cd p4sim && sudo ./set_pkg_config_env.sh

Configure and build:

cd ../..
./ns3 configure --enable-tests --enable-examples
./ns3 build

Step 4: Set the P4SIM_DIR Environment Variable

P4sim resolves P4 artifact paths (JSON pipelines, flow tables, topology files) via the P4SIM_DIR environment variable. Add it to your shell profile:

echo 'export P4SIM_DIR="$HOME/workdir/ns3.39/contrib/p4sim"' >> ~/.bashrc
source ~/.bashrc

Tip: If P4SIM_DIR is not set, P4sim falls back to a path derived from the executable location, but setting it explicitly is recommended for reliability.

Step 5: Run an Example

./ns3 run p4-v1model-ipv4-forwarding

No manual path editing is required — all examples use portable path helpers. A full list of available example names can be found in examples/CMakeLists.txt.

See the full step-by-step guide (including VM setup) in doc/vm-env.md.

Supported P4 Architectures

Switch Parameters

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:

Notes:

1. When using a CSMA channel, the P4 program must handle ARP explicitly.
2. Buffer attributes only take effect if the selected architecture models that buffer.
3. EnableTracing currently supports basic throughput measurement only.

P4sim Development Workflow

Using P4sim typically involves the following steps:

1. Develop the P4 program — implement your packet processing logic in P4 (headers, parsers, match-action tables, control flow).
2. Compile the P4 program — use p4c to generate the corresponding JSON pipeline description.
3. Create an ns-3 simulation script — write a simulation script (e.g. in scratch/ or examples/) and assign P4-enabled switches to the desired nodes.
4. Configure the control plane — populate match-action tables and implement any required control-plane logic before or during the simulation.
5. Run and observe — execute the simulation and collect performance metrics such as throughput, latency, and packet traces.

Examples

See the full list and descriptions in doc/examples.md.

Selected examples:

In the paper, P4sim is evaluated using representative networking scenarios demonstrating its capability to model basic tunneling (custom header encapsulation/decapsulation) and load balancing (distributing traffic across multiple network paths using P4 pipelines).

Known Limitations

The packet processing rate SwitchRate (packets per second) must currently be configured manually for each switch. An inappropriate value can cause the switch to enter an idle polling loop, leading to wasted CPU cycles. Automatic rate tuning is planned for a future release.

Generating Doxygen Documentation

sudo apt install doxygen graphviz dia
./ns3 configure --enable-tests --enable-examples
./ns3 build
./ns3 docs doxygen
xdg-open build/doxygen/html/index.html

Maintainers & Contributors

• Maintainers: Mingyu Ma
• Contributors: Thanks to GSoC 2025 with Davide support and contributor Vineet.