# QoS Manager (qosmngr)

QoS Manager is an IOPSYS service for managing Quality of Service on OpenWrt-based residential gateways. It provides traffic classification, queue management, traffic shaping, ingress policing, and packet marking through both UCI configuration and the TR-181 `Device.QoS.` data model.

## Features

- **Traffic Classification** - Match packets by L2/L3/L4 criteria (IP, MAC, port, DSCP, VLAN, P-bit, protocol, DHCP options) and assign them to queues
- **Queue Management** - Up to 8 queues per port with Strict Priority (SP), Weighted Round Robin (WRR), or Weighted Fair Queuing (WFQ) scheduling
- **Egress Shaping** - Port-level and per-queue rate limiting with burst control
- **Ingress Policing** - Token bucket, single-rate three-color, and two-rate three-color metering (SoC-dependent)
- **Packet Marking** - Rewrite DSCP, 802.1p P-bit, and VLAN ID fields
- **VLAN Translation** - Bidirectional VLAN ID remapping between customer and provider networks
- **DSCP-to-P-bit Mapping** - Per-port mapping of DiffServ code points to 802.1p priority bits
- **Policy-Based Routing** - Direct classified traffic to alternate routing tables
- **Real-Time Statistics** - Per-queue TX/drop counters via ubus and TR-181 QueueStats

## Documentation

| Document | Description |
|---|---|
| [Architecture](docs/arch/architecture.md) | System overview, startup sequence, platform support matrix |
| [UCI Configuration Reference](docs/spec/uci/qos.md) | All classify/queue/shaper/policer parameters with descriptions and defaults |
| [TR-181 Data Model Reference](docs/spec/tr181_reference.md) | Full `Device.QoS.` parameter table with UCI mappings |
| [ubus API Reference](docs/spec/ubus/qos.md) | `queue_stats` method — input/output fields and examples |
| [Deployment Scenarios](docs/guide/qos_deployment_scenarios.md) | 27 worked examples covering common use cases, plus statistics and monitoring |
| [Troubleshooting](docs/guide/QoS_Troubleshooting.md) | Platform-specific debugging (Broadcom, Airoha, Linux/Generic) |

## Configuration

All configuration is stored in `/etc/config/qos` with four UCI section types:

| Section | Description |
|---|---|
| `classify` | Traffic classification rules (match criteria + actions) |
| `queue` | Per-port queue settings (scheduling, precedence, rate) |
| `shaper` | Port-level egress traffic shaping |
| `policer` | Ingress traffic policing / metering |

## TR-181 Data Model

| Object | Description |
|---|---|
| `Device.QoS.Classification.{i}.` | Traffic classification and marking rules |
| `Device.QoS.Queue.{i}.` | Queue configuration per port |
| `Device.QoS.QueueStats.{i}.` | Per-queue statistics (packets, bytes, drops) |
| `Device.QoS.Shaper.{i}.` | Port-level egress shaping |
| `Device.QoS.Policer.{i}.` | Ingress policing with token bucket metering |

## Platform Support

| Feature | Broadcom | Airoha | Linux/Generic |
|---|---|---|---|
| Queue scheduling (SP/WRR) | tmctl | qdmamgr | tc HTB/SFQ |
| Port shaping | tmctl | qdmamgr | tc TBF |
| Per-queue shaping | tmctl | qdmamgr (WAN) | tc HTB class |
| Ingress policing | tmctl | femgr | tc ingress + police |
| L2 classification | ebtables | ebtables | ebtables |
| L3/L4 classification | iptables | iptables | iptables |

## Dependencies

- libbbfdm-ubus, libbbfdm-api
- libuci, libubus, libubox
- libqos
- libjson-c
- tc-full (Linux/Airoha platforms)
- ebtables with kmod-ebt-vlantranslation, kmod-ebt-dscp2pbit, kmod-ebt-copyvlanpbits, kmod-ebt-pbits2priority

## License

GPL-2.0-only
