linux.git/Documentation/userspace-api/netlink, branch v6.12.80

ynl: support binary and integer sub-type for indexed-array

2024-04-06T05:32:49+00:00

Add binary and integer sub-type support for indexed-array to display bond
arp and ns targets. Here is what the result looks like:

 # ip link add bond0 type bond mode 1 \
   arp_ip_target 192.168.1.1,192.168.1.2 ns_ip6_target 2001::1,2001::2
 # ./tools/net/ynl/cli.py --spec Documentation/netlink/specs/rt_link.yaml \
   --do getlink --json '{"ifname": "bond0"}' --output-json | jq '.linkinfo'

    "arp-ip-target": [
      "192.168.1.1",
      "192.168.1.2"
    ],
    [...]
    "ns-ip6-target": [
      "2001::1",
      "2001::2"
    ],

Signed-off-by: Hangbin Liu 
Link: https://lore.kernel.org/r/20240404063114.1221532-3-liuhangbin@gmail.com
Signed-off-by: Jakub Kicinski

ynl: rename array-nest to indexed-array

2024-04-06T05:32:49+00:00

Some implementations, like bonding, has nest array with same attr type.
To support all kinds of entries under one nest array. As discussed[1],
let's rename array-nest to indexed-array, and assuming the value is
a nest by passing the type via sub-type.

[1] https://lore.kernel.org/netdev/20240312100105.16a59086@kernel.org/

Suggested-by: Jakub Kicinski 
Signed-off-by: Hangbin Liu 
Link: https://lore.kernel.org/r/20240404063114.1221532-2-liuhangbin@gmail.com
Signed-off-by: Jakub Kicinski

doc/netlink: Describe nested structs in netlink raw docs

2024-02-01T05:19:19+00:00

Add a description and example of nested struct definitions
to the netlink raw documentation.

Signed-off-by: Donald Hunter 
Reviewed-by: Jiri Pirko 
Link: https://lore.kernel.org/r/20240129223458.52046-12-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski

doc/netlink: Describe sub-message selector resolution

2024-02-01T05:19:18+00:00

Update the netlink-raw docs to add a description of sub-message selector
resolution to explain that selector resolution is constrained by the
spec.

Signed-off-by: Donald Hunter 
Reviewed-by: Jiri Pirko 
Link: https://lore.kernel.org/r/20240129223458.52046-4-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski

doc/netlink: Document the sub-message format for netlink-raw

2023-12-18T22:39:43+00:00

Document the spec format used by netlink-raw families like rt and tc.

Reviewed-by: Jakub Kicinski 
Signed-off-by: Donald Hunter 
Link: https://lore.kernel.org/r/20231215093720.18774-4-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski

docs: netlink: add NLMSG_DONE message format for doit actions

2023-12-04T22:42:12+00:00

In case NLMSG_DONE message is sent as a reply to doit action, multiple
kernel implementation do not send anything else than struct nlmsghdr.
Add this note to the Netlink intro documentation.

Signed-off-by: Jiri Pirko 
Reviewed-by: Bagas Sanjaya 
Link: https://lore.kernel.org/r/20231201180154.864007-1-jiri@resnulli.us
Signed-off-by: Jakub Kicinski

docs: netlink: link to family documentations from spec info

2023-12-01T07:17:53+00:00

To increase the chances of people finding the rendered docs
add a link to specs.rst and index.rst.

Add a label in the generated index.rst and while at it adjust
the title a little bit.

Reviewed-by: Breno Leitao 
Reviewed-by: Donald Hunter 
Reviewed-by: Jiri Pirko 
Link: https://lore.kernel.org/r/20231129041427.2763074-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski

tools: ynl-gen: introduce support for bitfield32 attribute type

2023-10-23T23:12:46+00:00

Introduce support for attribute type bitfield32.
Note that since the generated code works with struct nla_bitfield32,
the generator adds netlink.h to the list of includes for userspace
headers in case any bitfield32 is present.

Note that this is added only to genetlink-legacy scheme as requested
by Jakub Kicinski.

Signed-off-by: Jiri Pirko 
Reviewed-by: Jacob Keller 
Link: https://lore.kernel.org/r/20231021112711.660606-3-jiri@resnulli.us
Signed-off-by: Jakub Kicinski

netlink: add variable-length / auto integers

2023-10-20T10:43:35+00:00

We currently push everyone to use padding to align 64b values
in netlink. Un-padded nla_put_u64() doesn't even exist any more.

The story behind this possibly start with this thread:
https://lore.kernel.org/netdev/20121204.130914.1457976839967676240.davem@davemloft.net/
where DaveM was concerned about the alignment of a structure
containing 64b stats. If user space tries to access such struct
directly:

	struct some_stats *stats = nla_data(attr);
	printf("A: %llu", stats->a);

lack of alignment may become problematic for some architectures.
These days we most often put every single member in a separate
attribute, meaning that the code above would use a helper like
nla_get_u64(), which can deal with alignment internally.
Even for arches which don't have good unaligned access - access
aligned to 4B should be pretty efficient.
Kernel and well known libraries deal with unaligned input already.

Padded 64b is quite space-inefficient (64b + pad means at worst 16B
per attr vs 32b which takes 8B). It is also more typing:

    if (nla_put_u64_pad(rsp, NETDEV_A_SOMETHING_SOMETHING,
                        value, NETDEV_A_SOMETHING_PAD))

Create a new attribute type which will use 32 bits at netlink
level if value is small enough (probably most of the time?),
and (4B-aligned) 64 bits otherwise. Kernel API is just:

    if (nla_put_uint(rsp, NETDEV_A_SOMETHING_SOMETHING, value))

Calling this new type "just" sint / uint with no specific size
will hopefully also make people more comfortable with using it.
Currently telling people "don't use u8, you may need the bits,
and netlink will round up to 4B, anyway" is the #1 comment
we give to newcomers.

In terms of netlink layout it looks like this:

         0       4       8       12      16
32b:     [nlattr][ u32  ]
64b:     [  pad ][nlattr][     u64      ]
uint(32) [nlattr][ u32  ]
uint(64) [nlattr][     u64      ]

Signed-off-by: Jakub Kicinski 
Acked-by: Nicolas Dichtel 
Signed-off-by: David S. Miller

docs: netlink: clean up after deprecating version

2023-10-18T00:59:51+00:00

Jiri moved version to legacy specs in commit 0f07415ebb78 ("netlink:
specs: don't allow version to be specified for genetlink").
Update the documentation.

Reviewed-by: Jiri Pirko 
Link: https://lore.kernel.org/r/20231016214540.1822392-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski