| Message ID | 20230324191900.21828-7-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | ynl: add support for user headers and struct attrs | expand |
| Context | Check | Description |
|---|---|---|
| netdev/series_format | success | Posting correctly formatted |
| netdev/tree_selection | success | Clearly marked for net-next |
| netdev/fixes_present | success | Fixes tag not required for -next series |
| netdev/header_inline | success | No static functions without inline keyword in header files |
| netdev/build_32bit | success | Errors and warnings before: 18 this patch: 18 |
| netdev/cc_maintainers | success | CCed 7 of 7 maintainers |
| netdev/build_clang | success | Errors and warnings before: 18 this patch: 18 |
| netdev/verify_signedoff | success | Signed-off-by tag matches author and committer |
| netdev/deprecated_api | success | None detected |
| netdev/check_selftest | success | No net selftest shell script |
| netdev/verify_fixes | success | No Fixes tag |
| netdev/build_allmodconfig_warn | success | Errors and warnings before: 18 this patch: 18 |
| netdev/checkpatch | success | total: 0 errors, 0 warnings, 0 checks, 60 lines checked |
| netdev/kdoc | success | Errors and warnings before: 0 this patch: 0 |
| netdev/source_inline | success | Was 0 now: 0 |
On Fri, 24 Mar 2023 19:18:59 +0000 Donald Hunter wrote: > 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. > +of an attribute and as a fixed message header. Structs are defined > +in ``definitions`` and referenced in operations or attributes. We should call out that the structs in YAML are implicitly "packed" (in the C sense of the word), so struct { u8 a; u16 b; u8 c; } is 4 bytes not 6 bytes. Any padding must be explicitly, C-like languages should infer the need for explicit packing from whether the members are naturally aligned. > +.. code-block:: yaml > + > + definitions: > + - > + name: message-header > + type: struct > + members: > + - > + name: a > + type: u32 > + - > + name: b > + type: string Maybe not the most fortunate example :) cause I think that for string/binary we'll need an explicit length. Maybe not for last one if it's a flexible array... but that's rare in NL. The rest LGTM, thanks!
Jakub Kicinski <kuba@kernel.org> writes: > On Fri, 24 Mar 2023 19:18:59 +0000 Donald Hunter wrote: >> 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. >> +of an attribute and as a fixed message header. Structs are defined >> +in ``definitions`` and referenced in operations or attributes. > > We should call out that the structs in YAML are implicitly "packed" > (in the C sense of the word), so struct { u8 a; u16 b; u8 c; } is > 4 bytes not 6 bytes. > > Any padding must be explicitly, C-like languages should infer the need > for explicit packing from whether the members are naturally aligned. I'll update the text to mention padding, with this example. >> +.. code-block:: yaml >> + >> + definitions: >> + - >> + name: message-header >> + type: struct >> + members: >> + - >> + name: a >> + type: u32 >> + - >> + name: b >> + type: string > > Maybe not the most fortunate example :) cause I think that for > string/binary we'll need an explicit length. Maybe not for > last one if it's a flexible array... but that's rare in NL. Ah, good point. I'll change the example to match the struct above. > The rest LGTM, thanks!
diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst index 3bf0bcdf21d8..6b385a9e6d0b 100644 --- a/Documentation/userspace-api/netlink/genetlink-legacy.rst +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -163,8 +163,58 @@ 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. +of an attribute and as a fixed message header. Structs are defined +in ``definitions`` and referenced in operations or attributes. + +.. code-block:: yaml + + definitions: + - + name: message-header + type: struct + members: + - + name: a + type: u32 + - + name: b + type: string + +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 ----------------
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> --- .../netlink/genetlink-legacy.rst | 54 ++++++++++++++++++- 1 file changed, 52 insertions(+), 2 deletions(-)