# p4lang/behavioral-model architecture

> Architecture diagram of the GitHub repository p4lang/behavioral-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p4lang/behavioral-model
- Repository: https://github.com/p4lang/behavioral-model

## Overview

bmv2 is a C++ reference software switch that interprets compiler-generated P4 JSON to process packets, and provides target variants and control-plane interfaces for development and debugging. The principal workflow is packet reception, parsing, ingress and egress P4 control flow, deparsing, and transmission. The graph also shows configuration loading, target runtimes, and debugging/observation capabilities. Workflow details are evidenced by the sampled simple-router implementation; other target and service wiring is included only where documented or shown in sampled entry points.

Main entry points: [`targets/simple_switch/simple_switch.cpp`](https://github.com/p4lang/behavioral-model/blob/main/targets/simple_switch/simple_switch.cpp) (Simple switch), [`src/bm_runtime/server.cpp`](https://github.com/p4lang/behavioral-model/blob/main/src/bm_runtime/server.cpp) (Thrift runtime), [`src/bm_sim/pipeline.cpp`](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/pipeline.cpp) (P4 pipeline), [`include/bm/bm_sim/queue.h`](https://github.com/p4lang/behavioral-model/blob/main/include/bm/bm_sim/queue.h) (Packet queues)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_packet["Packet processing"]
  node_switch["Switch core<br/>[switch.cpp]"]
  node_packetobj["Packet and PHV<br/>[packet.cpp]"]
  node_parser["P4 parser<br/>[parser.cpp]"]
  node_pipeline["P4 pipeline<br/>[pipeline.cpp]"]
  node_deparser["P4 deparser<br/>[deparser.cpp]"]
  node_queues["Packet queues<br/>[queue.h]"]
end

subgraph group_model["P4 model"]
  node_objects["P4 object loader<br/>[P4Objects.cpp]"]
  node_tables["Match-action tables<br/>[match_tables.cpp]"]
  node_stateful["Stateful resources<br/>[stateful.cpp]"]
  node_replication["Multicast replication<br/>[simple_pre.cpp]"]
end

subgraph group_targets["Switch targets"]
  node_simple["Simple switch<br/>[simple_switch.cpp]"]
  node_grpc["gRPC switch<br/>[main.cpp]"]
  node_psa["PSA switch<br/>[main.cpp]"]
  node_pna["PNA NIC<br/>[main.cpp]"]
end

subgraph group_control["Control plane"]
  node_runtime["Thrift runtime<br/>[server.cpp]"]
  node_pi["PI runtime<br/>[pi.cpp]"]
end

subgraph group_observability["Debugging"]
  node_debugger["Remote debugger<br/>[debugger.cpp]"]
  node_trace["Event logger<br/>[event_logger.cpp]"]
end

node_ports(("Packet ports"))
node_json["P4 JSON"]

node_ports -->|"delivers packets"| node_simple
node_simple -->|"enqueues packets"| node_queues
node_queues -->|"supplies packets"| node_packetobj
node_simple -->|"parses packets"| node_parser
node_parser -->|"populates headers"| node_packetobj
node_simple -->|"applies control flow"| node_pipeline
node_pipeline -->|"looks up entries"| node_tables
node_tables -->|"uses resources"| node_stateful
node_simple -->|"deparses packets"| node_deparser
node_deparser -->|"queues output"| node_queues
node_simple -->|"transmits packets"| node_ports
node_json -->|"configures model"| node_objects
node_objects -->|"loads P4 objects"| node_switch
node_simple -->|"starts service"| node_runtime
node_grpc -->|"starts service"| node_runtime
node_psa -->|"starts service"| node_runtime
node_pna -->|"starts service"| node_runtime
node_runtime -->|"controls switch"| node_switch
node_pi -.->|"implements control API"| node_switch
node_simple -->|"supports multicast"| node_replication
node_pipeline -->|"notifies control flow"| node_debugger
node_pipeline -->|"records events"| node_trace

click node_switch "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/switch.cpp"
click node_packetobj "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/packet.cpp"
click node_parser "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/parser.cpp"
click node_pipeline "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/pipeline.cpp"
click node_deparser "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/deparser.cpp"
click node_queues "https://github.com/p4lang/behavioral-model/blob/main/include/bm/bm_sim/queue.h"
click node_objects "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/P4Objects.cpp"
click node_tables "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/match_tables.cpp"
click node_stateful "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/stateful.cpp"
click node_replication "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/simple_pre.cpp"
click node_simple "https://github.com/p4lang/behavioral-model/blob/main/targets/simple_switch/simple_switch.cpp"
click node_grpc "https://github.com/p4lang/behavioral-model/blob/main/targets/simple_switch_grpc/main.cpp"
click node_psa "https://github.com/p4lang/behavioral-model/blob/main/targets/psa_switch/main.cpp"
click node_pna "https://github.com/p4lang/behavioral-model/blob/main/targets/pna_nic/main.cpp"
click node_runtime "https://github.com/p4lang/behavioral-model/blob/main/src/bm_runtime/server.cpp"
click node_pi "https://github.com/p4lang/behavioral-model/blob/main/PI/src/pi.cpp"
click node_debugger "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/debugger.cpp"
click node_trace "https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/event_logger.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_switch,node_packetobj,node_parser,node_pipeline,node_deparser,node_queues toneBlue
class node_objects,node_tables,node_stateful,node_replication toneAmber
class node_simple,node_grpc,node_psa,node_pna toneMint
class node_runtime,node_pi toneRose
class node_debugger,node_trace,node_ports,node_json toneIndigo
```

## Components

### Packet processing

- [Switch core](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/switch.cpp): `src/bm_sim/switch.cpp`
- [Packet and PHV](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/packet.cpp): `src/bm_sim/packet.cpp`
- [P4 parser](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/parser.cpp): `src/bm_sim/parser.cpp`
- [P4 pipeline](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/pipeline.cpp): `src/bm_sim/pipeline.cpp`
- [P4 deparser](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/deparser.cpp): `src/bm_sim/deparser.cpp`
- [Packet queues](https://github.com/p4lang/behavioral-model/blob/main/include/bm/bm_sim/queue.h): `include/bm/bm_sim/queue.h`

### P4 model

- [P4 object loader](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/P4Objects.cpp): `src/bm_sim/P4Objects.cpp`
- [Match-action tables](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/match_tables.cpp): `src/bm_sim/match_tables.cpp`
- [Stateful resources](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/stateful.cpp): `src/bm_sim/stateful.cpp`
- [Multicast replication](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/simple_pre.cpp): `src/bm_sim/simple_pre.cpp`

### Switch targets

- [Simple switch](https://github.com/p4lang/behavioral-model/blob/main/targets/simple_switch/simple_switch.cpp): `targets/simple_switch/simple_switch.cpp`
- [gRPC switch](https://github.com/p4lang/behavioral-model/blob/main/targets/simple_switch_grpc/main.cpp): `targets/simple_switch_grpc/main.cpp`
- [PSA switch](https://github.com/p4lang/behavioral-model/blob/main/targets/psa_switch/main.cpp): `targets/psa_switch/main.cpp`
- [PNA NIC](https://github.com/p4lang/behavioral-model/blob/main/targets/pna_nic/main.cpp): `targets/pna_nic/main.cpp`

### Control plane

- [Thrift runtime](https://github.com/p4lang/behavioral-model/blob/main/src/bm_runtime/server.cpp): `src/bm_runtime/server.cpp`
- [PI runtime](https://github.com/p4lang/behavioral-model/blob/main/PI/src/pi.cpp): `PI/src/pi.cpp`

### Debugging

- [Remote debugger](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/debugger.cpp): `src/bm_sim/debugger.cpp`
- [Event logger](https://github.com/p4lang/behavioral-model/blob/main/src/bm_sim/event_logger.cpp): `src/bm_sim/event_logger.cpp`

### Other components

- **Packet ports**
- **P4 JSON**

## Connections

- Packet ports → Simple switch: delivers packets
- Simple switch → Packet queues: enqueues packets
- Packet queues → Packet and PHV: supplies packets
- Simple switch → P4 parser: parses packets
- P4 parser → Packet and PHV: populates headers
- Simple switch → P4 pipeline: applies control flow
- P4 pipeline → Match-action tables: looks up entries
- Match-action tables → Stateful resources: uses resources
- Simple switch → P4 deparser: deparses packets
- P4 deparser → Packet queues: queues output
- Simple switch → Packet ports: transmits packets
- P4 JSON → P4 object loader: configures model
- P4 object loader → Switch core: loads P4 objects
- Simple switch → Thrift runtime: starts service
- gRPC switch → Thrift runtime: starts service
- PSA switch → Thrift runtime: starts service
- PNA NIC → Thrift runtime: starts service
- Thrift runtime → Switch core: controls switch
- PI runtime → Switch core: implements control API
- Simple switch → Multicast replication: supports multicast
- P4 pipeline → Remote debugger: notifies control flow
- P4 pipeline → Event logger: records events