diff --git a/doc/P4sim/README.md b/doc/P4sim/README.md
index bc085125..a055072d 100644
--- a/doc/P4sim/README.md
+++ b/doc/P4sim/README.md
@@ -1,61 +1,58 @@
-# P4Sim: NS-3-Based P4 Simulation Environment
+# P4sim: P4-Programmable Packet Processing in ns-3
-### Index
+P4sim ([GitHub](https://github.com/HapCommSys/p4sim)) is a high-performance simulation framework that brings P4-programmable data plane processing into the [ns-3 network simulator](https://www.nsnam.org/). 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.
-- [Local Deployment (ns-3.39)](#local-deployment-ns339)
-- Virtual Machine as Virtual Env
- - [ns-3 Version 3.x – 3.35](#setup-ns335)
- - [ns-3 Version 3.36 – 3.39](#setup-ns339)
-- [Appendix](#appendix)
+Key features include:
-## Installation & Usage Guide
+* **Behavioral accuracy**: the packet processing pipeline is based on [bmv2](https://github.com/p4lang/behavioral-model), 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.
-It is recommended to use a **virtual machine** with Vagrant to simplify the installation and ensure compatibility.
+Supported P4 architecture specifications:
-## Local Deployment (ns-3.39)
+* V1model
+* Portable Switch Architecture (PSA)
+* Portable NIC Architecture (PNA) — not yet fully implemented
-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`.
+## Getting Started
-> Note: The bmv2 and P4 software installation step will take **~3 hours** and consume up to **15GB** of disk space.
+### Installation
----
+The following steps set up a local environment to run P4sim with `ns-3.39` on **Ubuntu 24.04 LTS**. The setup has been tested on Ubuntu 24.04 LTS Desktop.
-## 1. Initialize the Working Directory
+> **Note:** The bmv2 and P4 software installation will take **1–2 hours** and consume up to **15 GB** of disk space.
-Create a workspace and install basic development tools.
+> **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
```bash
sudo apt update
+sudo apt install git vim cmake
mkdir ~/workdir
cd ~/workdir
-sudo apt install git vim cmake
```
----
-
-## 2. Install P4 Behavioral Model (bmv2) and Dependencies
+#### Step 2: Install bmv2 and P4 Dependencies
-> This installs all necessary libraries and tools for P4 development (via the official `p4lang/tutorials` repo).
+Install all required libraries and tools via the official [p4lang/tutorials](https://github.com/p4lang/tutorials) repository:
```bash
cd ~
git clone https://github.com/p4lang/tutorials
-mkdir ~/src
-cd ~/src
+mkdir ~/src && cd ~/src
../tutorials/vm-ubuntu-24.04/install.sh |& tee log.txt
```
-After installation, verify that `simple_switch` is available:
+Verify the installation:
```bash
-simple_switch
+simple_switch --version
```
----
-
-## 3. Clone and Build ns-3.39 with P4Simulator
-
-### Step 3.1: Clone ns-3.39
+#### Step 3: Clone and Build ns-3.39 with P4sim
```bash
cd ~/workdir
@@ -64,16 +61,15 @@ cd ns3.39
git checkout ns-3.39
```
-### Step 3.2: Add P4Sim Module
+Add the P4sim module:
```bash
cd contrib
git clone https://github.com/HapCommSys/p4sim.git
-cd p4sim
-sudo ./set_pkg_config_env.sh
+cd p4sim && sudo ./set_pkg_config_env.sh
```
-### Step 3.3: Configure and Build
+Configure and build:
```bash
cd ../..
@@ -81,272 +77,56 @@ cd ../..
./ns3 build
```
----
-
-## 4. Run an Example
+#### Step 4: Set the `P4SIM_DIR` Environment Variable
-You can run a built-in example using:
+P4sim resolves P4 artifact paths (JSON pipelines, flow tables, topology files) via the `P4SIM_DIR` environment variable. Add it to your shell profile:
```bash
-./ns3 run "exampleA" # This will run exampleA (name).
-```
-
----
-
-## 5. Configure P4 Files in Your Simulation
-
-You may need to **manually update file paths** for P4 artifacts in your simulation code.
-
-Example path updates:
-
-```cpp
-// p4 is the username
-std::string p4JsonPath = "/home/p4/workdir/ns3.39/contrib/p4sim/test/test_simple/test_simple.json";
-std::string flowTablePath = "/home/p4/workdir/ns3.39/contrib/p4sim/test/test_simple/flowtable_0.txt";
-std::string topoInput = "/home/p4/workdir/ns3.39/contrib/p4sim/test/test_simple/topo.txt";
+echo 'export P4SIM_DIR="$HOME/workdir/ns3.39/contrib/p4sim"' >> ~/.bashrc
+source ~/.bashrc
```
-Make sure these paths match your actual working directory and files.
-
----
-
-## Done!
-
-You now have a working ns-3.39 simulator with P4 integration ready for your experiments.
-
----
-
-## Feedback or Issues?
-
-If you encounter problems or have suggestions, feel free to open an issue or contact the maintainer.
-
-**Contact:** mingyu.ma@tu-dresden.de
-
-
-
-# Virtual Machine as virtual env ##
-
-`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).
-
-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.
+> **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.
-Tested with:
-- P4Lang Tutorials Commit: `7273da1c2ac2fd05cea0a9dd0504184b8c955eae`
-- Date: `2025-01-25`
+#### Step 5: Run an Example
-Notes:
-- Ensure you have `Vagrant` and `VirtualBox` installed before running `vagrant up dev`.
-- The setup script (`set_pkg_config_env.sh`) configures the required environment variables for P4Sim.
-- `Ubuntu 24.04` is the recommended OS for the virtual machine.
-
----
-
-## Setup Instructions for ns-3 version 3.x - 3.35 (Build with `waf`)
-
-This has been tested with ns-3 repo Tag `ns-3.35`.
-
-### 1. Build the Virtual Machine
```bash
-# with vm-ubuntu-24.04/Vagrantfile or vm-ubuntu-20.04/Vagrantfile
-vagrant up dev
-
-sudo apt update
-sudo apt install git vim
-
-cd ~
-git clone https://github.com/p4lang/tutorials
-mkdir ~/src
-cd ~/src
-../tutorials/vm-ubuntu-24.04/install.sh |& tee log.txt
+./ns3 run p4-v1model-ipv4-forwarding
+# ./ns3 run [example name]
```
-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)
+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`](https://github.com/HapCommSys/p4sim/blob/main/examples/CMakeLists.txt).
-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.
+### P4sim Development Workflow
-### 2. Clone the NS-3 Repository
-```bash
-cd
-mkdir workdir
-cd workdir
-git clone https://github.com/nsnam/ns-3-dev-git.git ns3.35
-cd ns3.35
-git checkout ns-3.35
-```
+Using P4sim typically involves the following steps:
-### 3. Clone & Integrate `p4sim` into NS-3
-```bash
-cd /home/p4/workdir/ns3.35/contrib/
-git clone https://github.com/HapCommSys/p4sim.git
-```
+1. **Develop the P4 Program**: Implement your packet processing logic in P4 (e.g., defining headers, parsers, match-action tables, and 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 the `scratch/` directory) and assign P4-enabled switches to the desired nodes.
+4. **Configure Control Plane Logic**: Populate match-action tables and implement the required control-plane logic before or during simulation runtime.
+5. **Run and Observe**: Execute the simulation and collect performance metrics such as throughput, latency, and packet traces.
-### 4. Set Up the Environment (for external libs)
-```bash
-cd /home/p4/workdir/ns3.35/contrib/p4sim/ # p4sim root directory
-sudo ./set_pkg_config_env.sh
-```
+## Use Cases
-### 5. Patch for the ns-3 code
-```bash
-cd ../../ # in ns-3 root directory
-git apply ./contrib/p4sim/doc/changes.patch
-```
+In the [paper](https://dl.acm.org/doi/10.1145/3747204.3747210), P4sim is evaluated using representative networking scenarios, demonstrating its capability to model:
-### 6. Configure & Build NS-3
-```bash
-# in ns-3 root directory
-./ns3 configure --enable-examples --enable-tests
-./ns3 build
-```
+* Basic Tunneling — validating support for custom header encapsulations and decapsulations.
+* Load Balancing — distributing traffic across multiple network paths using P4 pipelines.
-### 7. Run a Simulation Example
-```bash
-./ns3 run "exampleA" # This will run exampleA (name).
-
-# In the p4sim example, you may need to adjust the path of p4 and other files.
-# For example:
-# std::string p4JsonPath =
-# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/test_simple.json";
-# std::string flowTablePath =
-# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/flowtable_0.txt";
-# std::string topoInput = "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/topo.txt";
-```
+More use cases can be found [here](https://github.com/HapCommSys/p4sim/blob/main/doc/examples.md), demonstrating that P4sim can serve both research and educational purposes, enabling exploration of programmable data-plane behaviors in realistic network contexts.
----
+## Known Limitations
-## Setup Instructions for ns-3 version 3.36 - 3.39 (Build with `Cmake`)
+The packet processing rate `SwitchRate` (in packets per second, pps) 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.
-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**.
-The include file is: `/usr/local/include/bm`, the libs is `/usr/local/lib/libbmall.so`.
+## Publications & Credits
+**Papers:**
-### 1. Build the Virtual Machine
-```bash
-# with vm-ubuntu-24.04/Vagrantfile or vm-ubuntu-20.04/Vagrantfile
-vagrant up dev
+- Mingyu Ma, Giang T. Nguyen. **"P4sim: Programming Protocol-independent Packet Processors in ns-3."** 2025. [[ACM DL]](https://dl.acm.org/doi/10.1145/3747204.3747210) [[arXiv]](https://arxiv.org/abs/2503.17554)
-sudo apt update
-sudo apt install git vim
-
-cd ~
-git clone https://github.com/p4lang/tutorials
-mkdir ~/src
-cd ~/src
-../tutorials/vm-ubuntu-24.04/install.sh |& tee log.txt
-
-```
+**Maintainers & Contributors:**
-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)
-
-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.
-
-### 2. install Cmake
-```bash
-sudo apt update
-sudo apt install cmake
-
-```
-
-### 3. Clone the NS-3 Repository
-```bash
-cd
-mkdir workdir
-cd workdir
-git clone https://github.com/nsnam/ns-3-dev-git.git ns3.39
-cd ns3.39
-git checkout ns-3.39
-```
-
-### 4. Clone & Integrate `p4sim` into NS-3
-```bash
-cd /home/p4/workdir/ns3.39/contrib/
-git clone https://github.com/HapCommSys/p4sim.git
-```
-
-### 5. Set Up the Environment (for external libs)
-```bash
-cd /home/p4/workdir/ns3.39/contrib/p4sim/ # p4sim root directory
-sudo ./set_pkg_config_env.sh
-```
-
-### 6. Configure & Build NS-3
-```bash
-# in ns-3 root directory
-./ns3 configure --enable-tests --enable-examples
-./ns3 build
-```
-
-### 7. Run a Simulation Example
-```bash
-./ns3 run "exampleA" # This will run exampleA (name).
-
-# In the p4sim example, you may need to adjust the path of p4 and other files.
-# For example:
-# std::string p4JsonPath =
-# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/test_simple.json";
-# std::string flowTablePath =
-# "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/flowtable_0.txt";
-# std::string topoInput = "/home/p4/workdir/ns3.35/contrib/p4sim/test/test_simple/topo.txt";
-```
-
----
-
-# Install on a local machine
-
-Not been tested yet.
-
-# References
-
-[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/)
-
-[2] [P4Lang Tutorials repository](https://github.com/p4lang/tutorials/tree/master)
-
-# Appendix
-
-After `Install P4 Behavioral Model (bmv2) and Dependencies`, you should have that:
-
-```bash
-# For the libs
-(p4dev-python-venv) mm@bb24:~$ ls /usr/local/lib/ | grep bm
-libbmall.a
-libbmall.la
-libbmall.so
-libbmall.so.0
-libbmall.so.0.0.0
-libbm_grpc_dataplane.a
-libbm_grpc_dataplane.la
-libbm_grpc_dataplane.so
-libbm_grpc_dataplane.so.0
-libbm_grpc_dataplane.so.0.0.0
-libbmp4apps.a
-libbmp4apps.la
-libbmp4apps.so
-libbmp4apps.so.0
-libbmp4apps.so.0.0.0
-libbmpi.a
-libbmpi.la
-libbmpi.so
-libbmpi.so.0
-libbmpi.so.0.0.0
-
-# For the include files
-(p4dev-python-venv) mm@bb24:~$ ls /usr/local/include/bm
-bm_apps PI PsaSwitch.h SimplePreLAG.h SimpleSwitch.h standard_types.h
-bm_grpc pna_nic_constants.h psa_switch_types.h simple_pre_lag_types.h simple_switch_types.h thrift
-bm_runtime PnaNic.h simple_pre_constants.h simple_pre_types.h spdlog
-bm_sim pna_nic_types.h SimplePre.h simple_switch standard_constants.h
-config.h psa_switch_constants.h simple_pre_lag_constants.h simple_switch_constants.h Standard.h
-
-```
-
-After running `sudo ./set_pkg_config_env.sh`, you should have that: (In between, we only use bm.)
-
-```bash
-# set_pkg_config_env.sh, the p4simulator module requires the first (bm)
-pkg-config --list-all | grep xxx
- bm BMv2 - Behavioral Model
- simple_switch simple switch - Behavioral Model Target Simple Switch
- boost_system Boost System - Boost System
-
-# SPD log from BMv2 should be blocked, ns-3 has it's own logging system.
-```
\ No newline at end of file
+- **Maintainers**: [Mingyu Ma](mailto:mingyu.ma@tu-dresden.de)
+- **Contributors**: Thanks to [GSoC 2025](https://summerofcode.withgoogle.com/) with [Davide](mailto:d.scano89@gmail.com) support and contributor [Vineet](https://github.com/Vineet1101).
\ No newline at end of file