diff options
author | Donald Hunter <donald.hunter@gmail.com> | 2023-03-27 11:31:37 +0300 |
---|---|---|
committer | Jakub Kicinski <kuba@kernel.org> | 2023-03-29 09:54:43 +0300 |
commit | 88e288968412ec1ca3d3b2d96956baa543fdfe82 (patch) | |
tree | 07a4f5d83653606c28ee0ac610401adec022d505 /Documentation/userspace-api/netlink | |
parent | 643ef4a676e3a1ff1312e9fea6ae777c9a92fcd3 (diff) | |
download | linux-88e288968412ec1ca3d3b2d96956baa543fdfe82.tar.xz |
docs: netlink: document struct support for genetlink-legacy
Describe the genetlink-legacy support for using struct definitions
for fixed headers and for binary attributes.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Diffstat (limited to 'Documentation/userspace-api/netlink')
-rw-r--r-- | Documentation/userspace-api/netlink/genetlink-legacy.rst | 74 |
1 files changed, 71 insertions, 3 deletions
diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst index 3bf0bcdf21d8..b8fdcf7f6615 100644 --- a/Documentation/userspace-api/netlink/genetlink-legacy.rst +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -162,9 +162,77 @@ Other quirks (todo) Structures ---------- -Legacy families can define C structures both to be used as the contents -of an attribute and as a fixed message header. The plan is to define -the structs in ``definitions`` and link the appropriate attrs. +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. Note that +structures defined in YAML are implicitly packed according to C +conventions. For example, the following struct is 4 bytes, not 6 bytes: + +.. code-block:: c + + struct { + u8 a; + u16 b; + u8 c; + } + +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: + +.. code-block:: yaml + + definitions: + - + name: message-header + type: struct + members: + - + name: a + type: u8 + - + name: b + type: u16 + - + name: c + type: u8 + +Fixed Headers +~~~~~~~~~~~~~ + +Fixed message headers can be added to operations using ``fixed-header``. +The default ``fixed-header`` can be set in ``operations`` and it can be set +or overridden for each operation. + +.. code-block:: yaml + + operations: + fixed-header: message-header + list: + - + name: get + fixed-header: custom-header + attribute-set: message-attrs + +Attributes +~~~~~~~~~~ + +A ``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. + +.. code-block:: yaml + + attribute-sets: + - + name: stats-attrs + attributes: + - + name: stats + type: binary + struct: vport-stats Multi-message DO ---------------- |