diff mbox series

[RFC,mptcp-net-next,3/5] Documentation: netlink: add a YAML spec for mptcp

Message ID cb2ed01dd8797078c39c014e8c19eab5ddf1f0f2.1680801697.git.dcaratti@redhat.com (mailing list archive)
State Superseded, archived
Delegated to: Paolo Abeni
Headers show
Series YAML template for MPTCP netlink API | expand

Commit Message

Davide Caratti April 6, 2023, 5:31 p.m. UTC 
Signed-off-by: Davide Caratti <dcaratti@redhat.com>
---
 Documentation/netlink/specs/mptcp.yaml | 361 +++++++++++++++++++++++++
 1 file changed, 361 insertions(+)
 create mode 100644 Documentation/netlink/specs/mptcp.yaml

Comments

Paolo Abeni April 7, 2023, 7:56 a.m. UTC | #1 
On Thu, 2023-04-06 at 19:31 +0200, Davide Caratti wrote:
[...]
> +attribute-sets:
> +  -
> +    name: addr
> +    name-prefix: mptcp_pm_addr_attr_
> +    attributes:
> +      -
> +        name: unspec
> +        type: unused
> +        value: 0

This entry should not be needed, the tool should add it by default and
keep the first item with value == 1.

> +  -
> +    name: attr
> +    name-prefix: mptcp_pm_attr_
> +    attributes:
> +      -
> +        name: unspec
> +        type: unused
> +        value: 0
> +      -
> +        name: addr
> +        type: nest
> +        nested-attributes: addr
> +      -
> +        name: rcv_add_addrs
> +        type: u32
> +      -
> +        name: subflows
> +        type: u32
> +      -
> +        name: token
> +        type: u32
> +      -
> +        name: loc_id
> +        type: u8
> +      -
> +        name: addr_remote
> +        type: nest
> +        nested-attributes: addr

Is this the definition requiring patch 2/5 ?

Are there other attribute set requiring such change?

Thanks!

Paolo
Davide Caratti April 7, 2023, 9:52 a.m. UTC | #2 
hello Paolo, thanks for looking at this!

On Fri, Apr 07, 2023 at 09:56:39AM +0200, Paolo Abeni wrote:
> On Thu, 2023-04-06 at 19:31 +0200, Davide Caratti wrote:
> [...]
> > +attribute-sets:
> > +  -
> > +    name: addr
> > +    name-prefix: mptcp_pm_addr_attr_
> > +    attributes:
> > +      -
> > +        name: unspec
> > +        type: unused
> > +        value: 0
> 
> This entry should not be needed, the tool should add it by default and
> keep the first item with value == 1.

wouldn't this would break the uAPI? I mean, in the current one we have
MPTCP_PM_ADDR_ATTR_UNSPEC equal to zero. Removing the whole element would
make MPTCP_PM_ADDR_ATTR_UNSPEC disappear and potentially break the build
of userspace programs that use it. See below:

 $ git diff 
diff --git a/Documentation/netlink/specs/mptcp.yaml b/Documentation/netlink/specs/mptcp.yaml
index 910307b021ba..12974bf0cf10 100644
--- a/Documentation/netlink/specs/mptcp.yaml
+++ b/Documentation/netlink/specs/mptcp.yaml
@@ -91,10 +91,6 @@ attribute-sets:
     name: addr
     name-prefix: mptcp_pm_addr_attr_
     attributes:
-      -
-        name: unspec
-        type: unused
-        value: 0
       -
         name: family
         type: u16
 $ ./tools/net/ynl/ynl-gen-c.py --mode uapi  \
 > --spec Documentation/netlink/specs/mptcp.yaml --header \
 > | grep -B1 -A1 -i addr_attr_family
enum {
         MPTCP_PM_ADDR_ATTR_FAMILY = 1,
         MPTCP_PM_ADDR_ATTR_ID,

[...]

> > +      -
> > +        name: addr_remote
> > +        type: nest
> > +        nested-attributes: addr
> 
> Is this the definition requiring patch 2/5 ?

yes! I replied to your comment to patch 2/5 (and hopefully didn't mess with the names ;) )
 
> Are there other attribute set requiring such change?

currently ynl-gen-c.py supports only a single attribute-set for
each list of operations - but the effect on the generated code is
not relevant AFAIU.
diff mbox series

Patch

diff --git a/Documentation/netlink/specs/mptcp.yaml b/Documentation/netlink/specs/mptcp.yaml
new file mode 100644
index 000000000000..910307b021ba
--- /dev/null
+++ b/Documentation/netlink/specs/mptcp.yaml
@@ -0,0 +1,361 @@ 
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+
+name: mptcp_pm
+protocol: genetlink-legacy
+doc: Multipath TCP.
+
+c-family-name: mptcp_pm_name
+c-version-name: mptcp_pm_ver
+max-by-define: true
+kernel-policy: global
+
+definitions:
+  -
+    type: enum
+    name: event-type
+    enum-name: mptcp_event_type
+    name-prefix: mptcp_event_
+    entries:
+     -
+      name: unspec
+     -
+      name: created
+      value: 1
+      doc:
+        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport
+        A new MPTCP connection has been created. It is the good time to
+        allocate memory and send ADD_ADDR if needed. Depending on the
+        traffic-patterns it can take a long time until the
+        MPTCP_EVENT_ESTABLISHED is sent.
+     -
+      name: established
+      value: 2
+      doc:
+        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport
+        A MPTCP connection is established (can start new subflows).
+     -
+      name: closed
+      value: 3
+      doc:
+        token
+        A MPTCP connection has stopped.
+     -
+      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
+      doc:
+        token, rem_id
+        An address has been lost by the peer.
+     -
+      name: sub_established
+      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
+      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.
+     -
+      name: sub_priority
+      value: 13
+      doc:
+        token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
+        dport, backup, if_idx [, error]
+        The priority of a subflow has changed. 'error' should not be set.
+     -
+      name: listener_created
+      value: 15
+      doc:
+        family, sport, saddr4 | saddr6
+        A new PM listener is created.
+     -
+      name: listener_closed
+      value: 16
+      doc:
+        family, sport, saddr4 | saddr6
+        A PM listener is closed.
+
+attribute-sets:
+  -
+    name: addr
+    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
+      -
+        name: port
+        type: u16
+        byte-order: big-endian
+      -
+        name: flags
+        type: u32
+      -
+        name: if_idx
+        type: s32
+  -
+    name: subflow-attribute
+    name-prefix: mptcp_subflow_attr_
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: token_rem
+        type: u32
+      -
+        name: token_loc
+        type: u32
+      -
+        name: relwrite_seq
+        type: u32
+      -
+        name: map_seq
+        type: u64
+      -
+        name: map_sfseq
+        type: u32
+      -
+        name: ssn_offset
+        type: u32
+      -
+        name: map_datalen
+        type: u16
+      -
+        name: flags
+        type: u32
+      -
+        name: id_rem
+        type: u8
+      -
+        name: id_loc
+        type: u8
+      -
+        name: pad
+        type: pad
+  -
+    name: attr
+    name-prefix: mptcp_pm_attr_
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: addr
+        type: nest
+        nested-attributes: addr
+      -
+        name: rcv_add_addrs
+        type: u32
+      -
+        name: subflows
+        type: u32
+      -
+        name: token
+        type: u32
+      -
+        name: loc_id
+        type: u8
+      -
+        name: addr_remote
+        type: nest
+        nested-attributes: addr
+  -
+    name: event_attr
+    enum-name: mptcp_event_attr
+    name-prefix: mptcp_attr_
+    attributes:
+      -
+        name: UNSPEC
+        type: unused
+        value: 0
+      -
+        name: token
+        type: u32
+      -
+        name: family
+        type: u16
+      -
+        name: loc_id
+        type: u8
+      -
+        name: rem_id
+        type: u8
+      -
+        name: saddr4
+        type: u32
+        byte-order: big-endian
+      -
+        name: saddr6
+        type: binary
+        checks:
+          min-len: 16
+      -
+        name: daddr4
+        type: u32
+        byte-order: big-endian
+      -
+        name: daddr6
+        type: binary
+        checks:
+          min-len: 16
+      -
+        name: sport
+        type: u16
+        byte-order: big-endian
+      -
+        name: dport
+        type: u16
+        byte-order: big-endian
+      -
+        name: backup
+        type: u8
+      -
+        name: error
+        type: u8
+      -
+        name: flags
+        type: u16
+      -
+        name: timeout
+        type: u32
+      -
+        name: if_idx
+        type: u32
+      -
+        name: reset_reason
+        type: u32
+      -
+        name: reset_flags
+        type: u32
+      -
+        name: server_side
+        type: u8
+
+operations:
+  list:
+    -
+      name: unspec
+      doc: unused
+      value: 0
+    -
+      name: add_addr
+      doc: Add endpoint
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+
+      do:
+        request: &add_addr_attrs
+          attributes:
+            - addr
+    -
+      name: del_addr
+      doc: Delete endpoint
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+    -
+      name: get_addr
+      doc: Get endpoint information
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+        reply: *add_addr_attrs
+
+      dump:
+        reply: *add_addr_attrs
+    -
+      name:  flush_addrs
+      doc: flush addresses
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+    -
+      name: set_limits
+      doc: Set protocol limits
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: &mptcp_limits
+          attributes:
+            - rcv_add_addrs
+            - subflows
+    -
+      name: get_limits
+      doc: Get protocol limits
+      attribute-set: attr
+      do:
+        request: *mptcp_limits
+        reply: *mptcp_limits
+    -
+      name: set_flags
+      doc: Change endpoint flags
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+    -
+      name: announce
+      doc: announce new sf
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+        reply: *add_addr_attrs
+    -
+      name: remove
+      doc: announce removal
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+        reply: *add_addr_attrs
+    -
+      name: subflow_create
+      doc: todo
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+        reply: *add_addr_attrs
+    -
+      name: subflow_destroy
+      doc: todo
+      attribute-set: attr
+      flags: [ uns-admin-perm ]
+      do:
+        request: *add_addr_attrs
+        reply: *add_addr_attrs
+