Re: [PATCH net-next v5 6/7] docs: netlink: document struct support for genetlink-legacy

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3022 bytes --]

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>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]