Netlink specification support for legacy Generic Netlink families
This document describes the many additional quirks and properties
required to describe older Generic Netlink families which form
genetlink-legacy protocol level.
Attributes listed directly at the root level of the spec file.
Generic Netlink family version, default is 1.
version has historically been used to introduce family changes
which may break backwards compatibility. Since compatibility breaking changes
are generally not allowed
version is very rarely used.
Attribute type nests
New Netlink families should use
multi-attr to define arrays.
Older families (e.g.
genetlink control family) attempted to
define array types reusing attribute type to carry information.
For reference the
multi-attr array may look like this:
ARRAY-ATTR is the array entry type.
array-nest creates the following structure:
It wraps the entire array in an extra attribute (hence 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.
type-value is a construct which uses attribute types to carry
information about a single object (often used when array is dumped
type-value can have multiple levels of nesting, for example
genetlink's policy dumps create the following structures:
Where the first level of nest has the policy index as it's attribute
type, it contains a single nest which has the attribute index as its
type. Inside the attr-index nest are the policy attributes. Modern
Netlink families should have instead defined this as a flat structure,
the nesting serves no good purpose here.
Enum (message ID) model
Modern families use the
unified message ID model, which uses
a single enumeration for all messages within family. Requests and
responses share the same message ID. Notifications have separate
IDs from the same space. For example given the following list
Requests and responses for operation
a will have the ID of 1,
the requests and responses of
b - 2 (since there is no explicit
value it's previous operation
+ 1). Notification
use the ID of 4, operation
d 5 etc.
directional model splits the ID assignment by the direction of
the message. Messages from and to the kernel can't be confused with
each other so this conserves the ID space (at the cost of making
the programming more cumbersome).
In this case
value attribute should be specified in the
reply sections of the operations (if an operation has both
dump the IDs are shared,
value should be set in
For notifications the
value is provided at the op level but it
only allocates a
reply (i.e. a "from-kernel" ID). Let's look
at an example:
In this case
a will use 2 when sending the message to the kernel
and expects message with ID 1 in response. Notification
a "from-kernel" ID which is 2.
c allocates "from-kernel" ID of 7.
d does not set
values explicitly in the spec
it will be allocated 3 for the request (
a is the previous operation
with a request section and the value of 2) and 8 for response (
the previous operation in the "from-kernel" direction).
Legacy families can define C structures both to be used as the contents of
an attribute and as a fixed message header. Structures are defined in
definitions and referenced in operations or attributes.
name - The attribute name of the struct member
type - One of the scalar types
display-hint - Same as for
Note that structures defined in YAML are implicitly packed according to C
conventions. For example, the following struct is 4 bytes, not 6 bytes:
Any padding must be explicitly added and C-like languages should infer the
need for explicit padding from whether the members are naturally aligned.
Here is the struct definition from above, declared in YAML:
binary attribute can be interpreted as a C structure using a
struct property with the name of the structure definition. The
struct property implies
sub-type: struct so it is not necessary to
specify a sub-type.
Legacy families also use
binary attributes to encapsulate C arrays. The
sub-type is used to identify the type of scalar to extract.
New Netlink families should never respond to a DO operation with multiple
NLM_F_MULTI set. Use a filtered dump instead.
At the spec level we can define a
dumps property for the
perhaps with values of
on how the parsing should be implemented (parse into a single reply
vs list of objects i.e. pretty much a dump).