Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.37 as permitted sender) client-ip=23.128.96.37;
Date:   Tue, 10 Oct 2023 18:08:39 -0700
From:   Jakub Kicinski <kuba@kernel.org>
To:     Matthieu Baerts <matttbe@kernel.org>
Cc:     mptcp@lists.linux.dev, "David S. Miller" <davem@davemloft.net>,
        Eric Dumazet <edumazet@google.com>,
        Paolo Abeni <pabeni@redhat.com>,
        Mat Martineau <martineau@kernel.org>, netdev@vger.kernel.org,
        linux-kernel@vger.kernel.org, Davide Caratti <dcaratti@redhat.com>
Subject: Re: [PATCH net-next 3/6] Documentation: netlink: add a YAML spec
 for mptcp
Message-ID: <20231010180839.0617d61d@kernel.org>
In-Reply-To: <20231010-upstream-net-next-20231006-mptcp-ynl-v1-3-18dd117e8f50@kernel.org>
References: <20231010-upstream-net-next-20231006-mptcp-ynl-v1-0-18dd117e8f50@kernel.org>
        <20231010-upstream-net-next-20231006-mptcp-ynl-v1-3-18dd117e8f50@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Tue, 10 Oct 2023 21:21:44 +0200 Matthieu Baerts wrote:
> +definitions:
> +  -
> +    type: enum
> +    name: event-type
> +    enum-name: mptcp_event_type
> +    name-prefix: mptcp_event_

I think you can use - instead of _ here.
For consistency with other families?

> +    entries:
> +     -
> +      name: unspec
> +      value: 0

90% sure enums still start at 0, only attrs and msgs now default to 1.

> +     -
> +      name: announced
> +      value: 6
> +      doc:
> +        token, rem_id, family, daddr4 | daddr6 [, dport]
> +        A new address has been announced by the peer.
> +     -
> +      name: removed
> +      value: 7

Follows 6 so no need for value?

> +      doc:
> +        token, rem_id
> +        An address has been lost by the peer.
> +     -
> +      name: sub_established

Similarly for names we generally recommend - as a separator.
Looks more natural in places where it's used as a string, eg Python.
Well, I guess at least to me it does :)

> +      value: 10
> +      doc:
> +        token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
> +        dport, backup, if_idx [, error]
> +        A new subflow has been established. 'error' should not be set.
> +     -
> +      name: sub_closed
> +      value: 11

and here, /value/d, s/_/-/

> +      doc:
> +        token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
> +        dport, backup, if_idx [, error]
> +        A subflow has been closed. An error (copy of sk_err) could be set if an
> +        error has been detected for this subflow.

> +attribute-sets:
> +  -
> +    name: address
> +    name-prefix: mptcp_pm_addr_attr_
> +    attributes:
> +      -
> +        name: unspec
> +        type: unused
> +        value: 0
> +      -
> +        name: family
> +        type: u16
> +      -
> +        name: id
> +        type: u8
> +      -
> +        name: addr4
> +        type: u32
> +        byte-order: big-endian
> +      -
> +        name: addr6
> +        type: binary
> +        checks:
> +          min-len: 16

Do you not want the exact length for this?
If YNL doesn't support something just LMK, we add stuff as needed..