netdev - Re: [PATCH net-next v3 0/8] ethtool: generate uapi header from the spec

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] [day] [month] [year] [list]

Message-ID: <20241203183905.3343d9a5@kernel.org>
Date: Tue, 3 Dec 2024 18:39:05 -0800
From: Jakub Kicinski <kuba@...nel.org>
To: Stanislav Fomichev <stfomichev@...il.com>
Cc: Stanislav Fomichev <sdf@...ichev.me>, netdev@...r.kernel.org,
 davem@...emloft.net, edumazet@...gle.com, pabeni@...hat.com,
 linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org, horms@...nel.org,
 donald.hunter@...il.com, corbet@....net, andrew+netdev@...n.ch,
 kory.maincent@...tlin.com, nicolas.dichtel@...nd.com
Subject: Re: [PATCH net-next v3 0/8] ethtool: generate uapi header from the
 spec

On Mon, 2 Dec 2024 21:07:38 -0800 Stanislav Fomichev wrote:
> diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
> index efa00665c191..859ae0cb1fd8 100644
> --- a/Documentation/netlink/specs/ethtool.yaml
> +++ b/Documentation/netlink/specs/ethtool.yaml
> @@ -60,7 +60,8 @@ uapi-header: linux/ethtool_netlink_generated.h
>      name-prefix: ethtool-c33-pse-ext-state-
>      header: linux/ethtool.h
>      entries:
> -        - none
> +        - name: none
> +          doc: none
> 
> The first one fixes the bullet list (seems like mixing entries with and
> without docs confuses ynl-gen-rst.py). 

Ah, yes, that makes sense, either all entries should be objects or all
should be strings. I will spare you trying to figure out how to enforce
that in jsonschema :)

nit: "-" and "name: none" on separate lines

>          -
>            name: error-condition
>            doc: Group of error_condition states
> @@ -875,15 +876,15 @@ uapi-header: linux/ethtool_netlink_generated.h
>          value: 0
>        -
>          name: pair
> -        doc: ETHTOOL_A_CABLE_PAIR_
> +        doc: ETHTOOL_A_CABLE_PAIR
>          type: u8
>        -
>          name: code
> -        doc: ETHTOOL_A_CABLE_RESULT_CODE_
> +        doc: ETHTOOL_A_CABLE_RESULT_CODE
>          type: u8
>        -
>          name: src
> -        doc: ETHTOOL_A_CABLE_INF_SRC_
> +        doc: ETHTOOL_A_CABLE_INF_SRC
>          type: u32
>    -
>      name: cable-fault-length
>
> And removing trailing _ fixes the rest (don't know why).

Mmm. Trailing _ must mean something in ReST.
Can't decide now whether we care more about supporting ReST formatting
in YAML docs or protecting unsuspecting developers from this sort of a
surprise. So let's do the easier thing for now.

> Any objections to folding it as is into v4? I can go on and try to
> understand why ynl-gen-rst.py behaves exactly that way, but not sure
> it would buy us anything?

Yup, v4 with more or less the diff above SGTM!