# xilinx/hls_packet_processing architecture

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

- Interactive diagram: https://gitdiagram.com/xilinx/hls_packet_processing
- Repository: https://github.com/xilinx/hls_packet_processing

## Overview

HLS Packet Processing is a C++/Vivado HLS networking library with example FPGA applications. Its central workflow is to parse packet headers and payloads from streams, apply protocol or queue policy, and emit packets or metadata. The README documents both packet-oriented and stream-oriented APIs, while the applications demonstrate ARP caching, MOLD/ITCH parsing, priority-based packet buffering, and MQTTSN publish/subscribe. Several application internals were not sampled; links to those documented capabilities are shown only where supported or marked unverified.

Main entry points: [`apps/pynq_mqttsn/app.cpp`](https://github.com/xilinx/hls_packet_processing/blob/master/apps/pynq_mqttsn/app.cpp) (MQTTSN Protocol), [`apps/common/ip.hpp`](https://github.com/xilinx/hls_packet_processing/blob/master/apps/common/ip.hpp) (Packet APIs), [`apps/traffic_manager/app.cpp`](https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp) (Traffic Ingress), [`apps/mold_remover_packet/app.cpp`](https://github.com/xilinx/hls_packet_processing/blob/master/apps/mold_remover_packet/app.cpp) (MOLD Packet Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_packet["Packet Libraries"]
  node_packet_api["Packet APIs<br/>[ip.hpp]"]
end

subgraph group_state["State Helpers"]
  node_cam["CAM Lookup<br/>[cam.h]"]
  node_allocator["Buffer Allocator<br/>[allocator.h]"]
end

subgraph group_protocols["Protocol Apps"]
  node_arp["ARP Client<br/>[app.cpp]"]
  node_arp_cache[("ARP Cache<br/>[app.h]")]
  node_mold_packet["MOLD Packet Parser<br/>[app.cpp]"]
  node_mold_stream["MOLD Stream Parser<br/>[app.cpp]"]
  node_mqtt_entry["MQTTSN Entrypoints<br/>[main.cpp]"]
  node_mqttsn["MQTTSN Protocol<br/>[app.cpp]"]
end

subgraph group_forwarding["Packet Scheduling"]
  node_traffic_ingress["Traffic Ingress<br/>[app.cpp]"]
  node_packet_buffers[("Packet Buffers<br/>[app.cpp]")]
  node_priority_queue["Priority Queue<br/>[app.cpp]"]
  node_traffic_output["Scheduled Output<br/>[app.cpp]"]
end

node_stream_io(("AXI Stream I/O"))
node_sensor["Sensor Hardware"]
node_config(("Runtime Configuration"))
node_metadata(("Packet Metadata"))

node_arp -->|"parses headers"| node_packet_api
node_arp -->|"looks up"| node_arp_cache
node_arp_cache -->|"uses CAM"| node_cam
node_stream_io -.->|"supplies frames"| node_arp
node_stream_io -.->|"supplies packets"| node_mold_packet
node_stream_io -.->|"supplies packets"| node_mold_stream
node_mold_packet -->|"uses packet API"| node_packet_api
node_mold_stream -->|"uses stream API"| node_packet_api
node_mqtt_entry -.->|"runs protocol"| node_mqttsn
node_mqttsn -->|"uses packet API"| node_packet_api
node_mqttsn -->|"uses lookup"| node_cam
node_mqttsn -->|"stores messages"| node_allocator
node_sensor -.->|"provides readings"| node_mqttsn
node_config -.->|"configures run"| node_mqttsn
node_stream_io -.->|"supplies frames"| node_traffic_ingress
node_traffic_ingress -->|"parses headers"| node_packet_api
node_traffic_ingress -->|"stores packets"| node_packet_buffers
node_priority_queue -->|"selects buffers"| node_packet_buffers
node_priority_queue -->|"dispatches packets"| node_traffic_output
node_traffic_ingress -.->|"provides length and priority"| node_priority_queue
node_traffic_output -->|"emits packet metadata"| node_metadata
node_mold_packet -->|"emits metadata"| node_metadata
node_mold_stream -->|"emits metadata"| node_metadata

click node_packet_api "https://github.com/xilinx/hls_packet_processing/blob/master/apps/common/ip.hpp"
click node_cam "https://github.com/xilinx/hls_packet_processing/blob/master/apps/common/cam.h"
click node_allocator "https://github.com/xilinx/hls_packet_processing/blob/master/apps/common/allocator.h"
click node_arp "https://github.com/xilinx/hls_packet_processing/blob/master/apps/arp/app.cpp"
click node_arp_cache "https://github.com/xilinx/hls_packet_processing/blob/master/apps/arp/app.h"
click node_mold_packet "https://github.com/xilinx/hls_packet_processing/blob/master/apps/mold_remover_packet/app.cpp"
click node_mold_stream "https://github.com/xilinx/hls_packet_processing/blob/master/apps/mold_remover_stream/app.cpp"
click node_mqtt_entry "https://github.com/xilinx/hls_packet_processing/blob/master/apps/pynq_mqttsn/main.cpp"
click node_mqttsn "https://github.com/xilinx/hls_packet_processing/blob/master/apps/pynq_mqttsn/app.cpp"
click node_traffic_ingress "https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp"
click node_packet_buffers "https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp"
click node_priority_queue "https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp"
click node_traffic_output "https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.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_packet_api toneBlue
class node_cam,node_allocator toneAmber
class node_arp,node_arp_cache,node_mold_packet,node_mold_stream,node_mqtt_entry,node_mqttsn toneMint
class node_traffic_ingress,node_packet_buffers,node_priority_queue,node_traffic_output toneRose
class node_stream_io,node_sensor,node_config,node_metadata toneIndigo
```

## Components

### Packet Libraries

- [Packet APIs](https://github.com/xilinx/hls_packet_processing/blob/master/apps/common/ip.hpp): `apps/common/ip.hpp`

### State Helpers

- [CAM Lookup](https://github.com/xilinx/hls_packet_processing/blob/master/apps/common/cam.h): `apps/common/cam.h`
- [Buffer Allocator](https://github.com/xilinx/hls_packet_processing/blob/master/apps/common/allocator.h): `apps/common/allocator.h`

### Protocol Apps

- [ARP Client](https://github.com/xilinx/hls_packet_processing/blob/master/apps/arp/app.cpp): `apps/arp/app.cpp`
- [ARP Cache](https://github.com/xilinx/hls_packet_processing/blob/master/apps/arp/app.h): `apps/arp/app.h`
- [MOLD Packet Parser](https://github.com/xilinx/hls_packet_processing/blob/master/apps/mold_remover_packet/app.cpp): `apps/mold_remover_packet/app.cpp`
- [MOLD Stream Parser](https://github.com/xilinx/hls_packet_processing/blob/master/apps/mold_remover_stream/app.cpp): `apps/mold_remover_stream/app.cpp`
- [MQTTSN Entrypoints](https://github.com/xilinx/hls_packet_processing/blob/master/apps/pynq_mqttsn/main.cpp): `apps/pynq_mqttsn/main.cpp`
- [MQTTSN Protocol](https://github.com/xilinx/hls_packet_processing/blob/master/apps/pynq_mqttsn/app.cpp): `apps/pynq_mqttsn/app.cpp`

### Packet Scheduling

- [Traffic Ingress](https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp): `apps/traffic_manager/app.cpp`
- [Packet Buffers](https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp): `apps/traffic_manager/app.cpp`
- [Priority Queue](https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp): `apps/traffic_manager/app.cpp`
- [Scheduled Output](https://github.com/xilinx/hls_packet_processing/blob/master/apps/traffic_manager/app.cpp): `apps/traffic_manager/app.cpp`

### Other components

- **AXI Stream I/O**
- **Sensor Hardware**
- **Runtime Configuration**
- **Packet Metadata**

## Connections

- ARP Client → Packet APIs: parses headers (evidence: `apps/arp/app.cpp`)
- ARP Client → ARP Cache: looks up (evidence: `apps/arp/app.cpp`)
- ARP Cache → CAM Lookup: uses CAM (evidence: `apps/arp/app.h`)
- AXI Stream I/O → ARP Client: supplies frames
- AXI Stream I/O → MOLD Packet Parser: supplies packets
- AXI Stream I/O → MOLD Stream Parser: supplies packets
- MOLD Packet Parser → Packet APIs: uses packet API (evidence: `apps/mold_remover_packet/app.cpp`)
- MOLD Stream Parser → Packet APIs: uses stream API (evidence: `apps/mold_remover_stream/app.cpp`)
- MQTTSN Entrypoints → MQTTSN Protocol: runs protocol
- MQTTSN Protocol → Packet APIs: uses packet API (evidence: `apps/pynq_mqttsn/app.cpp`)
- MQTTSN Protocol → CAM Lookup: uses lookup (evidence: `apps/pynq_mqttsn/app.cpp`)
- MQTTSN Protocol → Buffer Allocator: stores messages (evidence: `apps/pynq_mqttsn/app.cpp`)
- Sensor Hardware → MQTTSN Protocol: provides readings
- Runtime Configuration → MQTTSN Protocol: configures run
- AXI Stream I/O → Traffic Ingress: supplies frames
- Traffic Ingress → Packet APIs: parses headers (evidence: `apps/traffic_manager/app.cpp`)
- Traffic Ingress → Packet Buffers: stores packets (evidence: `apps/traffic_manager/app.cpp`)
- Priority Queue → Packet Buffers: selects buffers (evidence: `apps/traffic_manager/app.cpp`)
- Priority Queue → Scheduled Output: dispatches packets (evidence: `apps/traffic_manager/app.cpp`)
- Traffic Ingress → Priority Queue: provides length and priority (evidence: `apps/traffic_manager/app.cpp`)
- Scheduled Output → Packet Metadata: emits packet metadata
- MOLD Packet Parser → Packet Metadata: emits metadata
- MOLD Stream Parser → Packet Metadata: emits metadata
