| Message ID | 20230327083138.96044-7-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 88e288968412ec1ca3d3b2d96956baa543fdfe82 |
| 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, 80 lines checked |
| netdev/kdoc | success | Errors and warnings before: 0 this patch: 0 |
| netdev/source_inline | success | Was 0 now: 0 |
On Mon, Mar 27, 2023 at 09:31:37AM +0100, Donald Hunter wrote: > 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 > + Nit: The indentation for code-block codes should be relative to code-block:: declaration (e.g. if it starts from column 4, the first column of code is also at 4). > +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 > ---------------- Otherwise LGTM, thanks! Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
On Date: Mon, 27 Mar 2023 19:44:59 +0700, Bagas Sanjaya wrote: > On Mon, Mar 27, 2023 at 09:31:37AM +0100, Donald Hunter wrote: [...] >> + >> +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 >> + > > Nit: The indentation for code-block codes should be relative to > code-block:: declaration (e.g. if it starts from column 4, the first > column of code is also at 4). Hey Bagas, I don't believe there is any such restriction. :-\ Where did you find it ? Thanks, Akira
On 3/27/23 21:39, Akira Yokosawa wrote: >> Nit: The indentation for code-block codes should be relative to >> code-block:: declaration (e.g. if it starts from column 4, the first >> column of code is also at 4). > > Hey Bagas, > > I don't believe there is any such restriction. :-\ > Where did you find it ? > This current doc renders well (no warnings), but personally I found that aligning codes in the code-block:: is aesthetically better in my eyes (I expect the leading spaces as margin).
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 ----------------
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 | 74 ++++++++++++++++++- 1 file changed, 71 insertions(+), 3 deletions(-)