# QoS Manager — Architecture

## Overview

The QoS Manager (`qosmngr`) is an IOPSYS service that manages Quality of Service configuration on OpenWrt-based residential gateways. It provides:

- **Traffic classification** - Match packets by L2/L3/L4 criteria and assign them to queues
- **Queue management** - Configure per-port queues with SP, WRR, or WFQ scheduling
- **Egress shaping** - Rate-limit outgoing traffic at port or per-queue level
- **Ingress policing** - Meter and enforce incoming traffic rates (SoC-dependent)
- **Packet marking** - Rewrite DSCP, 802.1p P-bit, and VLAN ID fields
- **Policy-based routing** - Direct traffic to alternate routing tables
- **Queue statistics** - Real-time per-queue TX/drop counters via ubus and TR-181

The service exposes its configuration through both UCI (`/etc/config/qos`) and the TR-181 `Device.QoS.` data model via bbfdm.

### System Limits

| Resource | Maximum |
|---|---|
| Classification entries | 50 |
| Queue entries | 100 |
| Policer entries | 50 |
| Queues per port | 8 (or 4 on some SoCs) |
| Traffic classes | 0-7 |

### Dependencies

- `libbbfdm-ubus`, `libbbfdm-api` - TR-181 data model framework
- `libuci` - UCI configuration parsing
- `libubus` - OpenWrt IPC
- `libqos` - SoC-specific QoS hardware abstraction
- `tc-full` - Linux traffic control (generic/Airoha platforms)
- `ebtables` - L2 bridge filtering (VLAN translation, DSCP-to-P-bit)

---

## Architecture

```
+------------------+     +------------------+     +------------------+
| TR-181 (bbfdm)   |     |   UCI Config     |     |   ubus API       |
| Device.QoS.*     |     | /etc/config/qos  |     | qos.queue_stats  |
+--------+---------+     +--------+---------+     +--------+---------+
         |                         |                        |
         +------------+------------+------------------------+
                      |
              +-------v--------+
              |    qosmngr     |
              |   daemon       |
              +-------+--------+
                      |
         +------------+------------+
         |            |            |
   +-----v-----+ +---v------+ +---v--------+
   | ebtables   | | iptables | | Platform   |
   | (L2 rules) | | (L3/L4)  | | HW driver  |
   +------------+ +----------+ +------------+
                                     |
                        +------------+------------+
                        |            |            |
                   +----v---+  +----v----+  +----v----+
                   |Broadcom|  | Airoha  |  | Linux   |
                   | tmctl  |  | qdmamgr |  | tc/HTB  |
                   +--------+  +---------+  +---------+
```

### Startup Sequence

1. **UCI defaults** (`/etc/uci-defaults/60-qos_config_generate`) auto-generate queue configs from `/etc/board.json`
2. **UCI defaults** (`/etc/uci-defaults/61-qos_classify_generate`) create default classification rules (DNS, DHCP, IGMP, ICMP to highest-priority queue)
3. **Init script** (`/etc/init.d/qos`, START=21) runs platform-specific `init_qos.sh` then launches the `qosmngr` daemon
4. **Daemon** registers the `Device.QoS.` data model with bbfdm and the `qos` ubus object

### Applying Configuration Changes

After modifying `/etc/config/qos`, reload the service:

```bash
# Reload QoS (re-applies all rules without full restart)
/etc/init.d/qos reload

# Full restart
/etc/init.d/qos restart
```

---

## Platform Support

qosmngr supports three platform backends:

| Feature | Broadcom (brcmbca) | Airoha | Linux/Generic |
|---|---|---|---|
| Queue scheduling (SP) | tmctl | qdmamgr | tc HTB |
| Queue scheduling (WRR) | tmctl | qdmamgr | tc SFQ |
| Port shaping | tmctl | qdmamgr | tc TBF |
| Per-queue shaping | tmctl | qdmamgr (WAN only) | tc HTB class |
| Ingress policing | tmctl | femgr ratelimit | tc ingress + police |
| L2 classification | ebtables | ebtables | ebtables |
| L3/L4 classification | iptables | iptables | iptables |
| VLAN translation | ebtables vlantranslation | ebtables vlantranslation | ebtables vlantranslation |
| DSCP-to-P-bit | ebtables dscp2pbit | ebtables dscp2pbit | ebtables dscp2pbit |
| Max queues per port | 8 | 8 | 8 |

### Platform-Specific Notes

- **Broadcom:** Uses `tmctl` for traffic management, `ethswctl` for switch control, `bdmf_shell` for data model framework access, and `fcctl` for flow cache.
- **Airoha:** Uses `qdmamgr_lan`/`qdmamgr_wan` for QDMA management, `femgr` for ratelimit initialization, and `qosrule` for discipline control. Per-queue shaping is WAN-only. Auto-detects WAN link speed via rule engine on link-up events.
- **Linux/Generic:** Uses standard Linux `tc` with HTB (Hierarchical Token Bucket) for queue hierarchy, TBF (Token Bucket Filter) for port shaping, and SFQ (Stochastic Fairness Queueing) for WRR queues. Requires `tc-full` package.
