coqos_add(1)

🎀 coqos_add(1) — Qualcomm Atheros Open Powerline Toolkit 🎀

okay bestie, gather round, we're doing coqos_add from the Qualcomm Atheros Open Powerline Toolkit and it's gonna be a whole thing (in the best way). 💖

---

✨ NAME ✨

coqos_add — Add a managed data stream 💅

---

🌸 SYNOPSIS 🌸

coqos_add action priority rate ttl operand condition [condition] [...] [device] [...]

---

🦋 DESCRIPTION 🦋

Heads up bestie: this page is under construction. 🚧 Not me reading a manpage that's still being written, but here we are.

So what this does: it adds a managed stream to one or more powerline devices using the VS_CONN_ADD message. That's a vendor specific message type, and if you wanna know what it actually is inside, go consult the Qualcomm Atheros Firmware Technical Reference Manual, because that's where the lore lives. 📖✨

This program is part of the Qualcomm Atheros Powerline Toolkit. For the big-picture overview and installation instructions, go check out the plc man page. 🫶

---

🌈 BACKGROUND 🌈

Bandwidth management is basically the vibe-checker of your streams: it prioritizes streams so that when one of the conditions below gets detected, the data from the lowest priority stream gets dropped first. The whole point is making sure the rest of the streams keep running at their full potential. 👑

Here are the situations that trigger it:

• Degraded line condition — the channel degrades to the point where the available PHY rate from the transmitter to the receiver is too low, and it's all because of the variability of the power line's characteristics. 😭
• Over subscription — too much data is being sent per second, so you get packet loss from excessive collisions, which comes from excessive channel oversubscription. it's giving chaos ngl. 💀
• Lack of channel Capacity — when a new source starts up, there's just not enough channel capacity to support it. rip. 🙈

---

💅 OPTIONS 💅

• -e — Redirects stderr messages to stdout. By convention, progress messages and error messages get printed on stderr, while primary program output goes to stdout. This option prints all output on stdout for when that's what you want. ✨
• -i interface — Select the host Ethernet interface. All requests get sent via this host interface, and only responses received via this host interface are recognized. The default interface is eth1, because most people use eth0 as their principle network connection. But — if the environment string "PLC" is defined, then it takes precedence over the default interface. And this option takes precedence over either default. so like, hierarchy. 👑
• -q — Suppresses status messages on stderr. shhh. 🤫
• -r — Display relative memory offsets on output. This option is the default. (yes bestie, it's already on, you don't gotta ask twice 💖)
• -v — Prints additional information on stdout. Specifically, this option dumps outgoing Ethernet packets on stdout. 🫣
• -?, --help — Displays program help information on stderr. This option takes precedence over all other options on the command line except version information. 🆘
• -!, --version — Displays program version information on stderr. This option takes precedence over all other options on the command line except help information. Use this one when you're sending screen dumps to Atheros technical staff. 📸

---

🍓 ARGUMENTS 🍓

• action — The action taken for frames that satisfy the selection criteria. Valid actions are "CAP0", "CAP1", "CAP2", "CAP3", which specify the channel access priority queue. CAP0 and CAP1 are for best effort data. CAP2 is for video and non urgent MMEs. CAP3 is for voice, urgent MMEs and control messages such as IGMP and MLD. 📶
• priority — The relative priority of this stream. Valid values are 0 through 15, where 0 is the lowest priority and 15 is the highest. ⭐
• destination — The destination MAC address. 📮
• rate — The average expected data rate for this stream. Valid values are 1 to 9000, where the units are in 10kbps, so the minimum rate is 10kbps and the maximum rate is 90mbps. 🏎️
• ttl — The time to live for this stream. Valid values are 10000 to 2000000, where the units are in microseconds, so the minimum time is 10 milliseconds and the maximum time is 2 seconds. ⏳
• operand — The operand specifies the logical relationship between conditions before the action is taken. Valid operands are listed and described under OPERANDS. 🔗
• condition — A conditional expression consisting of a field, operator and value. See CONDITIONS for more information. 🧐
• device — The MAC address of some powerline device. More than one address may be specified on the command line. If more than one address is specified, then operations are performed on each device in turn. The default address is "local". See DEVICES for more information. 🏠

---

🧚 CONDITIONS 🧚

A condition consists of a field, an operator and a value. One condition is required, but three are permitted. Condition order is not important, but all conditions must appear after the operand and before the control. 📝

• field — The field is the part of the Ethernet frame to be examined. Some fields are not valid for some actions, but this program does not enforce such rules, since validation is performed by runtime firmware on each device. Recognized fields are listed and described under FIELDS. 🔍
• operator — The operator specifies the relationship that must exist between the field and value in order for the condition to evaluate True. Currently, only equality operators are supported. Valid operators are listed and described under OPERATORS. ⚖️
• value — The value must be appropriate to the field type. Some fields are MAC or IP addresses, some are integers, some are bitmaps and others are states. Integers and bitmaps may be expressed in binary, decimal or hexadecimal format. Binary values start with 0b. Hexadecimal values start with 0x. States are expressed using keywords. Users are responsible for knowing how many bits are significant for each type of value. Valid values are described along with fields under FIELDS. 🔢

---

👑 OPERANDS 👑

The operand indicates the logical relationship that must exist between conditions in the rule set before the action is applied to a frame. Operands are expressed as discrete alphanumeric strings, entered in upper, lower or mixed character case. If you fail to enter a known operand, you'll get an error message that lists all possible operands. They are position sensitive. One operand is allowed, and it must appear after the action and before any condition. 📌

• Any — Apply the action to frames that satisfy any of the conditions. This is equivalent to the logical or operation. 🎯
• All — Apply the action to frames that satisfy all of the conditions. This is equivalent to the logical and operation. 💯
• Always — Apply the action to all frames, regardless of any and all conditions that may be specified. 🌀

🌸 FIELDS 🌸

Okay bestie, so fields are literally the little peepholes into the frame that get inspected during selection, plus they tell you the size and format of the value you're allowed to put in the condition statement. They're written as discrete alphanumeric strings, and you can type them in upper, lower or mixed character case — she's flexible like that 💅. If you type a field that isn't known, you get an error message that lists all possible fields. Rude but helpful.

• ET — a 16-bit Ethertype, expressed in decimal, hexadecimal or binary. The format is described in IEEE Standard 802-2001 [4].
• EthDA — a 48-bit Ethernet destination address, expressed in hexadecimal. The format is described in IEEE Standard 802-2001 [4].
• EthSA — a 48-bit Ethernet source address, expressed in hexadecimal. The format is described in IEEE Standard 802-2001 [4].
• VLANUP — an 8-bit Ethernet VLAN tag where the lower 3 bits are the User Priority sub-field of a VLAN Tag defined in IEEE Std 802.1Q-1998 (Virtual Bridged Local Area Networks) [11]. The upper 5 bits should be zero.
• VLANID — a 16-bit VLAN identifier where the lower 12 bits are the VLAN Identifier (VID) defined in IEEE Std 802.1Q-1998 (Virtual Bridged Local Area Networks) [11]. The upper 4 bits should be zero.
• IPV4TOS — an 8-bit Type-of-Service code where the format is defined in the RFC 791 (Internet Protocol) [14].
• IPV4PROT — an 8-bit Ethernet Protocol identifier. The format is defined in the RFC 791 (Internet Protocol) [14].
• IPV4SA — a 32-bit Internet Protocol source address expressed in dotted-decimal notation. The official format is defined in RFC 791 (Internet Protocol) [14]. Our implementation permits empty octets and leading zeros within fields. For example, "..." is equivalent to "0.0.0.0 and "127..000.001" is equivalent to "127.0.0.1".
• IPV4DA — a 32-bit Internet Protocol destination address expressed in dotted-decimal notation. The official format is defined in RFC 791 (internet Protocol) [14]. Our implementation permits empty octets and leading zeros within fields. For example, "..." is equivalent to "0.0.0.0 and "127..000.001" is equivalent to "127.0.0.1".
• IPV6TC — an 8-bit Internet Protocol V6 traffic class expressed as defined in RFC 2460 (Internet Protocol Version 6) [17].
• IPV6FL — a 24-bit IPV6 flow label where the lower 20 bits are the IPv6 Flow Label defined in RFC 2460 (Internat Protocol Version 6) [17]. The upper 4 bits should be zero. The value can be entered either as a decimal, binary or hex integer.
• IPV6SA — a 128-bit IPV6 source address expressed as colon-separated hexadecmial quartets (octet pairs). The official format is defined in RFC 2460 (Internet Protocol Version 6) [17]. Our implementation permits multiple empty fields, abreviated fields and leading zeros within fields. When multiple empty fields appear, only the right-most occurance expands to zeros. For example, "FFFF::DDDD::BBBB::AAAA" is equivalent to "FFFF:0000:DDDD:0000:BBBB:0000:0000:AAAA".
• IPV6DA — a 128-bit IPV6 destination address expressed as colon-separated hexadecimal quartets (octet pairs). The official format is defined in RFC 2460 (Internet Protocol Version 6) [17]. Our implementation permits multiple empty fields, abbreviated fields and leading zeros within fields. When multiple empty fields appear, only the right-most occurance expands to zeros. For example, "AAAA::BBBB::CCCC::DDDD" is equivalent to "AAAA:0000:BBBB:0000:CCCC:0000:0000:DDDD".
• TCPSP — a 16-bit TCP source port as a decimal integer. The format is defined in RFC 793 (Transmission Control Protocol [15]).
• TCPDP — a 16-bit TCP destination port expressed as a decimal integer. The format is defined in RFC 793 (Transmission Control Protocol [15]).
• UDPSP — a 16-bit UDP source port expressed as a decimal integer. The format is defined in RFC 768 (User Datagram Protocol [13]).
• UDPDP — a 16-bit UDP destination port expressed as a decimal integer. The format is defined in RFC 768 (User Datagram Protocol [13]).
• IPSP — a 16-bit IP source port expressed as a decimal integer. This condition applies to either TCP or UDP packets, depending on the protocol used, and is valid only for actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop".
• IPDP — a 16-bit IP destination port expressed as a decimal integer. This condition applies to either TCP or UDP packets, depending on the protocol used, and is valid only for actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop".
• MME — a 24-bit Atheros HomePlugAV Management Message type expressed in hexadecimal. The first byte is the MMV and the next two bytes are the MMTYPE for a HomePlug AV frame as defined in the HomePlug AV Specification. The MMTYPE will match any MME sub-type (Request; Confirm; Indicate; Response). This field is only valid for action "Boost".

---

✨ OPERATORS ✨

An operator is like the equality bouncer between a field and a value. It's an alphanumeric string entered in upper, lower or mixed character case. If you fail to enter a known operator, you get an error message that lists all possible operators. Operators are position sensitive and must appear between each field and value — no skipping the line, bestie.

• Is — indicates that the frame field must equal the associated value for the condition to evaluate true.
• Not — indicates that the frame field must not equal the associated value for the condition to true true.

---

🎀 STATES 🎀

A state is a special case of value. Cute, right?

• True,On,Yes,Present — indicates a positive state or presence of some entity. All are equivalent and can be used interchangeably. Double negatives are permitted, so "Is True" is equivalent to "Not False".
• False,Off,No,Missing — indicates a negative state or absence of some entity. All are equivalent and can be used interchangeably. Double negatives are permitted, so "Is False" is equivalent to "Not True".

---

💖 DEVICES 💖

Powerline devices use Ethernet Media Access Control (MAC) addresses. A MAC address is a 48-bit value entered as 12 hexadecimal digits in upper, lower or mixed character case. Octets may be separated with colons for clarity. For example, "00b052000001", "00:b0:52:00:00:01" and "00b052:000001" are valid and equivalent. Slay.

The following MAC addresses are common or special and may be entered by name instead of number.

• all — same as "broadcast".
• broadcast — a synonym for the Ethernet broadcast address, FF:FF:FF:FF:FF:FF. All devices, whether local, remote or foreign recognize messages sent to this address. A remote device is any device at the far end of a powerline connection. A foreign device is any device not manufactured by Atheros.
• local — a synonym for the Qualcomm Atheros vendor specific Local Management Address (LMA), 00:B0:52:00:00:01. All local Atheros devices recognize this address but remote and foreign devices do not. A remote device is any device at the far end of a powerline connection. A foreign device is any device not manufactured by Atheros.

---

🌈 REFERENCES 🌈

See the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for more information.

---

💀 DISCLAIMER 💀

Atheros HomePlug AV Vendor Specific Management Message structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. Consequently, public information may not be available. Qualcomm Atheros reserves the right to modify message structure and content in future firmware releases without any obligation to notify or compensate users of this program. No cap.

---

🔥 EXAMPLES 🔥

The following example adds a temporary stream to device 00:b0:52:BA:BE:01 which will then manage the bandwidth for that stream until removed with program coqos_rel.

# coqos_add CAP2 15 5000 200000 any ethda is 192.168.105 00:B0:52:BA:BE:01

This adds a stream to the bandwidth manager that sets all traffic to destination address of 192.168.0.105 as priority 15 (the highest priority). This would then need to also be sent to each device on the network. Refer to int6krule for more details on how to specify conditions.

---

🦋 SEE ALSO 🦋

coqos_info(1), coqos_man(1), coqos_mod(1), coqos_rel(1)

---

👑 CREDITS 👑

• Bill Wike
• Nathaniel Houghton
• Charles Maier

---

And that's the whole vibe, bestie. The footer says open-plc-utils-0.0.3, November 2013, and coqos_add(1) — so you know exactly which era of icon behavior you're reading. 💖✨