wifi: nl80211: Document sta-info nested attribute
Subsystems (3)
cover wifi: nl80211: Document sta-info nested attribute
There are many undocumented attribute in nl80211 specification documentation, this patch series aims to document NL80211_ATTR_STA_INFO nested attribute from the previous binary type.
This patch merges/supersedes 2 related patches.
---
Hilal Rahmatullah (2):
wifi: nl80211: add sta-info nested attribute
net: ynl: allow u8 sub-type for indexed array
Documentation/netlink/specs/nl80211.yaml | 368 ++++++++++++++++++++++++++++++- tools/net/ynl/pyynl/ynl_gen_c.py | 2 +- 2 files changed, 368 insertions(+), 2 deletions(-)
---
base-commit: 3d6d817622b0a9721e3cc404df3469171582be13
change-id: 20260821-work-b9d257341ca7
Best regards,
Signature · 1 line
Hilal Rahmatullah <[email protected]>
PATCH 1/2 wifi: nl80211: add sta-info nested attribute
Add NL80211_ATTR_STA_INFO nested attribute definition, along with its related attributes and enum.
--- Documentation/netlink/specs/nl80211.yaml | 368 ++++++++++++++++++++++++++++++- 1 file changed, 367 insertions(+), 1 deletion(-)
Documentation/netlink/specs/nl80211.yaml +367 -1
@@ -211,6 +211,76 @@ definitions: - ht20 - ht40minus - ht40plus + - + name: eht-gi + type: enum + name-prefix: nl80211-rate-info-eht-gi- + entries: + - 0-8 + - 1-6 + - 3-2 + - + name: eht-ru-alloc + type: enum + name-prefix: nl80211-rate-info-he-ru-alloc- + entries: + - "26" + - "52" + - 52p26 + - "106" + - 106p26 + - "242" + - "484" + - 484p242 + - "996" + - 996p484 + - 996p484p242 + - 2x996 + - 2x996p484 + - 3x996 + - 3x996p484 + - 4x996 + - + name: he-gi + type: enum + name-prefix: nl80211-rate-info-he-gi- + entries: + - 0-8 + - 1-6 + - 3-2 + - + name: he-ru-alloc + type: enum + name-prefix: nl80211-rate-info-he-ru-alloc- + entries: + - "26" + - "52" + - "106" + - "242" + - "484" + - "996" + - 2x996 + - + name: mesh-power-mode + type: enum + name-prefix: nl80211-mesh-power- + entries: + - unknown + - active + - light-sleep + - deep-sleep + - + name: plink-state + type: enum + name-prefix: nl80211-plink- + entries: + - listen + - opn-snt + - opn-rcvd + - cnf-rcvd + - estab + - holding + - blocked - name: sta-flag-update type: struct
@@ -297,7 +367,8 @@ attribute-sets: type: u32 - name: sta-info - type: binary # TODO: nest + type: nest + nested-attributes: sta-info-attrs - name: wiphy-bands type: nest
@@ -1601,6 +1672,111 @@ attribute-sets: name: nan type: nest nested-attributes: frame-type-attrs + - + name: rate-info-attrs + enum-name: nl80211-rate-info + name-prefix: nl80211-rate-info- + attributes: + - + name: bitrate + type: u16 + - + name: mcs + type: u8 + - + name: 40-mhz-width + type: flag + - + name: short-gi + type: flag + - + name: bitrate32 + type: u32 + - + name: vht-mcs + type: u8 + - + name: vht-nss + type: u8 + - + name: 80-mhz-width + type: flag + - + name: 80p80-mhz-width + type: unused + - + name: 160-mhz-width + type: flag + - + name: 10-mhz-width + type: flag + - + name: 5-mhz-width + type: flag + - + name: he-mcs + type: u8 + - + name: he-nss + type: u8 + - + name: he-gi + type: u8 + enum: he-gi + - + name: he-dcm + type: u8 + - + name: he-ru-alloc + type: u8 + enum: he-ru-alloc + - + name: 320-mhz-width + type: flag + - + name: eht-mcs + type: u8 + - + name: eht-nss + type: u8 + - + name: eht-gi + type: u8 + enum: eht-gi + - + name: eht-ru-alloc + type: u8 + enum: eht-ru-alloc + - + name: s1g-mcs + type: u8 + - + name: s1g-nss + type: u8 + - + name: 1-mhz-width + type: flag + - + name: 2-mhz-width + type: flag + - + name: 4-mhz-width + type: flag + - + name: 8-mhz-width + type: flag + - + name: 16-mhz-width + type: flag + - + name: uhr-mcs + type: u8 + - + name: uhr-elr + type: flag + - + name: uhr-im + type: flag - name: sar-attributes enum-name: nl80211-sar-attrs
@@ -1631,6 +1807,172 @@ attribute-sets: - name: end-freq type: u32 + - + name: sta-bss-param-attrs + enum-name: nl80211-sta-bss-param + name-prefix: nl80211-sta-bss-param- + attributes: + - + name: cts-prot + type: flag + - + name: short-preamble + type: flag + - + name: short-slot-time + type: flag + - + name: dtim-period + type: u8 + - + name: beacon-interval + type: u16 + - + name: sta-info-attrs + enum-name: nl80211-sta-info + name-prefix: nl80211-sta-info- + attributes: + - + name: inactive-time + type: u32 + - + name: rx-bytes + type: u32 + - + name: tx-bytes + type: u32 + - + name: llid + type: u16 + - + name: plid + type: u16 + - + name: plink-state + type: u8 + enum: plink-state + - + name: signal + type: u8 + - + name: tx-bitrate + type: nest + nested-attributes: rate-info-attrs + - + name: rx-packets + type: u32 + - + name: tx-packets + type: u32 + - + name: tx-retries + type: u32 + - + name: tx-failed + type: u32 + - + name: signal-avg + type: u8 + - + name: rx-bitrate + type: nest + nested-attributes: rate-info-attrs + - + name: bss-param + type: nest + nested-attributes: sta-bss-param-attrs + - + name: connected-time + type: u32 + - + name: sta-flags + type: binary + struct: sta-flag-update + - + name: beacon-loss + type: u32 + - + name: t-offset + type: s64 + - + name: local-pm + type: u32 + enum: mesh-power-mode + - + name: peer-pm + type: u32 + enum: mesh-power-mode + - + name: nonpeer-pm + type: u32 + enum: mesh-power-mode + - + name: rx-bytes64 + type: u64 + - + name: tx-bytes64 + type: u64 + - + name: chain-signal + type: indexed-array + sub-type: u8 + - + name: chain-signal-avg + type: indexed-array + sub-type: u8 + - + name: expected-throughput + type: u32 + - + name: rx-drop-misc + type: u64 + - + name: beacon-rx + type: u64 + - + name: beacon-signal-avg + type: u8 + - + name: tid-stats + type: indexed-array + sub-type: nest + nested-attributes: tid-stats-attrs + - + name: rx-duration + type: u64 + - + name: pad + type: binary + - + name: ack-signal + type: u8 + - + name: ack-signal-avg + type: s8 + - + name: rx-mpdus + type: u32 + - + name: fcs-error-count + type: u32 + - + name: connected-to-gate + type: u8 + - + name: tx-duration + type: u64 + - + name: airtime-weight + type: u16 + - + name: airtime-link-metric + type: u32 + - + name: assoc-at-boottime + type: u64 + - + name: connected-to-as + type: u8 - name: supported-iftypes enum-name: nl80211-iftype
@@ -1672,6 +2014,30 @@ attribute-sets: - name: nan type: flag + - + name: tid-stats-attrs + enum-name: nl80211-tid-stats + name-prefix: nl80211-tid-stats- + attributes: + - + name: rx-msdu + type: u64 + - + name: tx-msdu + type: u64 + - + name: tx-msdu-retries + type: u64 + - + name: tx-msdu-failed + type: u64 + - + name: pad + type: binary + - + name: txq-stats + type: nest + nested-attributes: txq-stats-attrs - name: txq-stats-attrs name-prefix: nl80211-txq-stats-
Signature · 1 line
2.53.0
Jakub Kicinski
maintainerRe: [PATCH 1/2] wifi: nl80211: add sta-info nested attribute
This is an AI-generated review of your patch. The human sending this email has considered the AI review valid, or at least plausible.
---
wifi: nl80211: add sta-info nested attribute
This converts NL80211_ATTR_STA_INFO in the nl80211 YAML spec from an opaque binary blob into a proper nest, and adds the sta-info-attrs, rate-info-attrs, sta-bss-param-attrs and tid-stats-attrs attribute sets plus the enum definitions they reference.
A few questions about the new definitions below.
Quoted 8 lines
Documentation/netlink/specs/nl80211.yaml +0
-0@@ -211,6 +211,76 @@ definitions: - ht20 - ht40minus - ht40plus
[ ... ]
Documentation/netlink/specs/nl80211.yaml definitions: · line 225
Quoted 4 lines
Documentation/netlink/specs/nl80211.yaml +4
-0+ - + name: eht-ru-alloc + type: enum + name-prefix: nl80211-rate-info-he-ru-alloc-
^^^^
[Severity: Medium]
Is the he- prefix here a copy/paste slip? The sixteen entries below match enum nl80211_eht_ru_alloc in include/uapi/linux/nl80211.h exactly in order (26, 52, 52p26, 106, 106p26, 242, 484, 484p242, 996, 996p484, 996p484p242, 2x996, 2x996p484, 3x996, 3x996p484, 4x996), and those constants are spelled NL80211_RATE_INFO_EHT_RU_ALLOC_*, so the prefix would need to be nl80211-rate-info-eht-ru-alloc- to describe the uAPI.
As written, this definition and the he-ru-alloc definition a few lines further down carry the same name-prefix but assign different values to the same suffixes. The HE enum has value 2 == 106, while this list has value 2 == 52p26.
Since the generator builds constant names from name-prefix:
tools/net/ynl/pyynl/ynl_gen_c.py:EnumSet.__init__() {
...
self.value_pfx = yaml.get('name-prefix', f"{family.ident_name}-{yaml['name']}-")
...
}wouldn't a --mode uapi render emit two conflicting definitions of NL80211_RATE_INFO_HE_RU_ALLOC_26/52/106/242/484/996/2X996? The spec is installed for user space via make install-specs, so the wrong names are directly consumable. I checked the tip of the series and the he- prefix is still there, so it does not look like a later patch corrects it.
Quoted 17 lines
Documentation/netlink/specs/nl80211.yaml +17
-0+ entries: + - "26" + - "52" + - 52p26 + - "106" + - 106p26 + - "242" + - "484" + - 484p242 + - "996" + - 996p484 + - 996p484p242 + - 2x996 + - 2x996p484 + - 3x996 + - 3x996p484 + - 4x996
[ ... ]
Quoted 12 lines
Documentation/netlink/specs/nl80211.yaml +12
-0+ - + name: he-ru-alloc + type: enum + name-prefix: nl80211-rate-info-he-ru-alloc- + entries: + - "26" + - "52" + - "106" + - "242" + - "484" + - "996" + - 2x996
[ ... ]
Quoted 9 lines
Documentation/netlink/specs/nl80211.yaml +5
-0@@ -1601,6 +1672,111 @@ attribute-sets: name: nan type: nest nested-attributes: frame-type-attrs + - + name: rate-info-attrs + enum-name: nl80211-rate-info + name-prefix: nl80211-rate-info- + attributes:
[ ... ]
Documentation/netlink/specs/nl80211.yaml attribute-sets: · line 1749
Quoted 4 lines
Documentation/netlink/specs/nl80211.yaml +4
-0+ - + name: eht-ru-alloc + type: u8 + enum: eht-ru-alloc
This is the attribute that picks up the mis-prefixed definition above, so the spec currently describes EHT RU-allocation values under HE constant names.
[ ... ]
Quoted 4 lines
Documentation/netlink/specs/nl80211.yaml +0
-0@@ -1631,6 +1807,172 @@ attribute-sets: - name: end-freq type: u32
[ ... ]
Quoted 5 lines
Documentation/netlink/specs/nl80211.yaml +5
-0+ - + name: sta-info-attrs + enum-name: nl80211-sta-info + name-prefix: nl80211-sta-info- + attributes:
[ ... ]
Documentation/netlink/specs/nl80211.yaml attribute-sets: · line 1922
Quoted 8 lines
Documentation/netlink/specs/nl80211.yaml +8
-0+ - + name: chain-signal + type: indexed-array + sub-type: u8 + - + name: chain-signal-avg + type: indexed-array + sub-type: u8
[Severity: Low]
Does a ynl build still work at this commit? AttrSet.new_attr() only accepts three sub-types for indexed arrays and raises otherwise:
tools/net/ynl/pyynl/ynl_gen_c.py:AttrSet.new_attr() {
...
elif elem['type'] == 'indexed-array' and 'sub-type' in elem:
if elem["sub-type"] in ['binary', 'nest', 'u32']:
t = TypeIndexedArray(self.family, self, elem, value)
else:
raise Exception(f'new_attr: unsupported sub-type {elem["sub-type"]}')
...
}tools/net/ynl/generated/Makefile generates for every spec except conntrack and nftables, so nl80211.yaml is processed and make -C tools/net/ynl would abort here.
The following patch in the series, "net: ynl: allow u8 sub-type for indexed array", adds 'u8' to that whitelist, and at the series tip the list reads ['binary', 'nest', 'u32', 'u8'], so only the intermediate commits are affected. Would swapping the order of the two patches keep the tree bisectable?
[ ... ]
Documentation/netlink/specs/nl80211.yaml attribute-sets: · line 1939
Quoted 5 lines
Documentation/netlink/specs/nl80211.yaml +5
-0+ - + name: tid-stats + type: indexed-array + sub-type: nest + nested-attributes: tid-stats-attrs
[Severity: Medium]
Should the TID index offset be recorded somewhere here? The plain indexed-array model says the entry nests have the index of the entry as their type, but the kernel does not use a 0-based index:
net/wireless/nl80211.c:nl80211_send_station() {
...
for (tid = 0; tid < IEEE80211_NUM_TIDS + 1; tid++) {
struct cfg80211_tid_stats *tidstats = &sinfo->pertid[tid];
if (!tidstats->filled)
continue;
tidattr = nla_nest_start_noflag(msg, tid + 1);
...
}and include/uapi/linux/nl80211.h documents it as "the inner attribute number is the TID+1 and the special TID 16 (i.e. value 17) is used for non-QoS frames".
Because unfilled TIDs are skipped, the array is also sparse, and the C generator throws the entry type away:
tools/net/ynl/pyynl/ynl_gen_c.py:TypeIndexedArray._attr_get() {
...
get_lines = [f'attr_{self.c_name} = attr;',
'ynl_attr_for_each_nested(attr2, attr) {',
'\tif (__ynl_attr_validate(yarg, attr2, type))',
'\t\treturn YNL_PARSE_CB_ERROR;',
f'\tn_{self.c_name}++;',
'}']
...
}so a generated C consumer fills a dense array in encounter order and reports per-TID counters against the wrong TID. The Python library keeps the raw index as a dict key, so there the offset is only undocumented.
Note the same construct two attributes earlier is genuinely 0-based:
net/wireless/nl80211.c:nl80211_put_signal() {
...
for (i = 0; i < ARRAY_SIZE(sinfo->chain_signal); i++) {
...
if (nla_put_u8(msg, i, signal[i]))
...
}Can the two different index semantics be distinguished from this spec as it stands?
[ ... ]
Cross-instance finding from sashiko-gemini (68565e9f44913e1546bdedfd69f80fe6b57cbeb2edfb4bc54f79467c320b20e1):
[Severity: Medium]
The pad attributes in sta-info-attrs and tid-stats-attrs violate the netlink YAML policy by using type binary instead of pad.
Signature · 1 line
pw-bot: cr
PATCH 2/2 net: ynl: allow u8 sub-type for indexed array
In reply to Hilal Rahmatullahadd u8 to the supported sub-type for indexed array, it is needed for NL80211_STA_INFO_CHAIN_SIGNAL serialization.
--- tools/net/ynl/pyynl/ynl_gen_c.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
tools/net/ynl/pyynl/ynl_gen_c.py +1 -1
@@ -1158,7 +1158,7 @@ class AttrSet(SpecAttrSet): elif elem['type'] == 'nest': t = TypeNest(self.family, self, elem, value) elif elem['type'] == 'indexed-array' and 'sub-type' in elem: - if elem["sub-type"] in ['binary', 'nest', 'u32']: + if elem["sub-type"] in ['binary', 'nest', 'u32', 'u8']: t = TypeIndexedArray(self.family, self, elem, value) else: raise Exception(f'new_attr: unsupported sub-type {elem["sub-type"]}')
Signature · 1 line
2.53.0
Jakub Kicinski
maintainerRe: [PATCH 2/2] net: ynl: allow u8 sub-type for indexed array
This is an AI-generated review of your patch. The human sending this email has considered the AI review valid, or at least plausible.
---
net: ynl: allow u8 sub-type for indexed array
This adds u8 to the list of sub-types accepted by AttrSet.new_attr() for indexed-array attributes in tools/net/ynl/pyynl/ynl_gen_c.py, so that the nl80211 chain-signal attributes can be described in the YAML spec. Without it the generator rejects the sub-type outright.
tools/net/ynl/pyynl/ynl_gen_c.py class AttrSet(SpecAttrSet): · line 1161
Quoted 10 lines
tools/net/ynl/pyynl/ynl_gen_c.py +1
-1@@ -1158,7 +1158,7 @@ class AttrSet(SpecAttrSet): elif elem['type'] == 'nest': t = TypeNest(self.family, self, elem, value) elif elem['type'] == 'indexed-array' and 'sub-type' in elem: - if elem["sub-type"] in ['binary', 'nest', 'u32']: + if elem["sub-type"] in ['binary', 'nest', 'u32', 'u8']:
[Severity: Medium]
Should this patch come before the spec change in the series?
The preceding commit cb06a9dc93de ("wifi: nl80211: add sta-info nested attribute") already adds chain-signal and chain-signal-avg to Documentation/netlink/specs/nl80211.yaml:
-
name: chain-signal
type: indexed-array
sub-type: u8SpecAttrSet.__init__() in tools/net/ynl/pyynl/lib/nlspec.py calls new_attr() for every attribute of every attribute set at spec parse time, regardless of which ops or generation mode are requested:
for elem in self.yaml['attributes']:
...
attr = self.new_attr(elem, val)
so at the intermediate commit AttrSet.new_attr() takes the else branch and raises 'new_attr: unsupported sub-type u8'.
nl80211 is part of GENS in tools/net/ynl/generated/Makefile, which globs all specs and only filters out conntrack and nftables:
SPECS_PATHS=$(wildcard $(SPECS_DIR)/*.yaml)
GENS_UNSUP=conntrack nftables
GENS=$(filter-out ${GENS_UNSUP},$(patsubst $(SPECS_DIR)/%.yaml,%,${SPECS_PATHS}))Does that mean make -C tools/net/ynl and ynl-regen.sh fail for anyone who lands on or bisects to cb06a9dc93de? Reordering so the generator support lands first, or squashing the two, would avoid that.
[Severity: Medium]
Does the scalar indexed-array path lose the entry index that NL80211_STA_INFO_CHAIN_SIGNAL relies on?
Documentation/userspace-api/netlink/genetlink-legacy.rst describes the entry attribute type as the index:
The ``ENTRY`` nests are special and have the index of the entry as their type instead of normal attribute type.
nl80211_put_signal() keys each u8 on the chain number and skips chains that are not in the mask, so the emitted index sequence can be sparse:
for (i = 0; i < IEEE80211_MAX_CHAINS; i++) {
if (!(mask & BIT(i)))
continue;
if (nla_put_u8(msg, i, signal[i]))Sparse masks do occur in practice, for example ath10k_htt_rx_h_signal() sets each bit of status->chains independently based on per-chain RSSI validity.
The generated parser for scalar sub-types in _multi_parse() stores entries densely and drops ynl_attr_type(attr):
elif aspec.sub_type in scalars:
ri.cw.p(f"dst->{aspec.c_name}[i] = ynl_attr_get_{aspec.sub_type}(attr);")
ri.cw.p('i++;')So a message carrying chains 0 and 2 is reported as _count.chain_signal = 2 with the chain-2 value sitting at index 1, and TypeIndexedArray.attr_put() would then re-serialize it as index 1:
for (i = 0; i < {var}->_count.{c_name}; i++)
ynl_attr_put_u8(nlh, i, {var}->{c_name}[i]);YnlFamily._decode_array_attr() in tools/net/ynl/pyynl/lib/ynl.py has the same loss since it appends item.as_scalar() to a plain list without recording item.type.
The lossy path predates this patch, since only u32 indexed arrays were allowed and the in-tree u32 user arp-ip-target is dense. Is it worth carrying the index alongside the value before routing nl80211 chain-signal through this path, so per-chain values are not attributed to the wrong chain?
tools/net/ynl/pyynl/ynl_gen_c.py class AttrSet(SpecAttrSet): · line 1164
Quoted 2 lines
tools/net/ynl/pyynl/ynl_gen_c.py +0
-0else: raise Exception(f'new_attr: unsupported sub-type {elem["sub-type"]}')
[Severity: Medium]
One more thing on the spec added by the preceding commit of this series, in Documentation/netlink/specs/nl80211.yaml. The new eht-ru-alloc enum declares the HE name prefix:
name: eht-ru-alloc
type: enum
name-prefix: nl80211-rate-info-he-ru-alloc-while include/uapi/linux/nl80211.h names these values with the EHT prefix:
enum nl80211_eht_ru_alloc {
NL80211_RATE_INFO_EHT_RU_ALLOC_26,
NL80211_RATE_INFO_EHT_RU_ALLOC_52,
NL80211_RATE_INFO_EHT_RU_ALLOC_52P26,The same patch adds he-ru-alloc with that identical prefix:
name: he-ru-alloc
type: enum
name-prefix: nl80211-rate-info-he-ru-alloc-The generator builds the C enumerators straight from that prefix:
self.value_pfx = yaml.get('name-prefix', f"{family.ident_name}-{yaml['name']}-")
self.c_name = c_upper(self.enum_set.value_pfx + self.name)
cw.p(entry.c_name + suffix) /* render_uapi() */so uapi generation from this spec emits NL80211_RATE_INFO_HE_RU_ALLOC_26/52/106/242/484/2x996 twice, and the EHT-only entries (52p26, 106p26, 484p242, 996p484, 996p484p242, 2x996p484, 3x996, 3x996p484, 4x996) come out under NL80211_RATE_INFO_HE_RU_ALLOC_* names that do not exist in the UAPI header. No in-tree build runs --mode uapi for nl80211 today, so nothing breaks right now.
Should the eht-ru-alloc prefix be nl80211-rate-info-eht-ru-alloc- instead?