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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <ZCGPy+90DsRpsicj@debian.me>
Date:   Mon, 27 Mar 2023 19:44:59 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     Donald Hunter <donald.hunter@...il.com>, netdev@...r.kernel.org,
        Jakub Kicinski <kuba@...nel.org>,
        "David S. Miller" <davem@...emloft.net>,
        Eric Dumazet <edumazet@...gle.com>,
        Paolo Abeni <pabeni@...hat.com>,
        Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     donald.hunter@...hat.com
Subject: Re: [PATCH net-next v5 6/7] docs: netlink: document struct support
 for genetlink-legacy

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@...il.com>

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

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)