Add a new YNL attribute `ignore-index` as a way to indicate that a given indexed-array attribute is really just used as an array, and hence the nested attribute-type aka. the index is unimportant. This means that the kernel never uses the index when processing received netlink messages, and that it doesn't add any additional information when sent by the kernel. For backward compatibility reasons the kernel can continue to set the index to a non-zero value in netlink messages, but it can safely be disregarded by clients when `ignore-index` is set to true. When the index is non-zero, it is often just an incremental iterator value, which provides no additional value, as the order of the array elements is already known based on the order in the netlink message. `ignore-index` is not added for the genetlink protocol, as any new families should use multi-attributes, unless they need the index. Signed-off-by: Asbjørn Sloth Tønnesen --- Documentation/netlink/genetlink-c.yaml | 6 ++++++ Documentation/netlink/genetlink-legacy.yaml | 6 ++++++ Documentation/netlink/netlink-raw.yaml | 6 ++++++ Documentation/userspace-api/netlink/genetlink-legacy.rst | 3 +++ 4 files changed, 21 insertions(+) diff --git a/Documentation/netlink/genetlink-c.yaml b/Documentation/netlink/genetlink-c.yaml index 5a234e9b5fa2e..5d022772cdb61 100644 --- a/Documentation/netlink/genetlink-c.yaml +++ b/Documentation/netlink/genetlink-c.yaml @@ -184,6 +184,12 @@ properties: nested-attributes: description: Name of the space (sub-space) used inside the attribute. type: string + ignore-index: + description: | + The indexed-array is just an array. The index, aka. the + nested attribute-type, can be disregarded, as it doesn't + contain anything interesting. + type: boolean enum: description: Name of the enum type used for the attribute. type: string diff --git a/Documentation/netlink/genetlink-legacy.yaml b/Documentation/netlink/genetlink-legacy.yaml index 66fb8653a3442..f7991a3c5e2a3 100644 --- a/Documentation/netlink/genetlink-legacy.yaml +++ b/Documentation/netlink/genetlink-legacy.yaml @@ -233,6 +233,12 @@ properties: nested-attributes: description: Name of the space (sub-space) used inside the attribute. type: string + ignore-index: + description: | + The indexed-array is just an array. The index, aka. the + nested attribute-type, can be disregarded, as it doesn't + contain anything interesting. + type: boolean enum: description: Name of the enum type used for the attribute. type: string diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml index 246fa07bccf68..1d2ff5f79cada 100644 --- a/Documentation/netlink/netlink-raw.yaml +++ b/Documentation/netlink/netlink-raw.yaml @@ -251,6 +251,12 @@ properties: nested-attributes: description: Name of the space (sub-space) used inside the attribute. type: string + ignore-index: + description: | + The indexed-array is just an array. The index, aka. the + nested attribute-type, can be disregarded, as it doesn't + contain anything interesting. + type: boolean enum: description: Name of the enum type used for the attribute. type: string diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst index fa005989193a1..839b0095c9a80 100644 --- a/Documentation/userspace-api/netlink/genetlink-legacy.rst +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -53,6 +53,9 @@ indexed-array limiting its size to 64kB). The ``ENTRY`` nests are special and have the index of the entry as their type instead of normal attribute type. +When ``ignore-index`` is set to ``true``, then the ``indexed-array`` is +just an array, and the index can be disregarded. + A ``sub-type`` is needed to describe what type in the ``ENTRY``. A ``nest`` ``sub-type`` means there are nest arrays in the ``ENTRY``, with the structure looks like:: -- 2.51.0