Commit 991eb0f0 authored by Davide Caratti's avatar Davide Caratti Committed by Geliang Tang
Browse files

Documentation: netlink: add a YAML spec for mptcp 

mainline inclusion
from mainline-v6.7-rc1
commit bc8aeb2045e22fe8fc86b6b4a7d63f61c29734c9
category: feature
bugzilla: https://gitee.com/openeuler/kernel/issues/I9VYQ9
CVE: NA

Reference: https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=bc8aeb2045e22fe8fc86b6b4a7d63f61c29734c9

--------------------------------

it describes most of the current netlink interface (uAPI definitions,
doit/dumpit operations and attributes)

Link: https://github.com/multipath-tcp/mptcp_net-next/issues/340


Acked-by: default avatarPaolo Abeni <pabeni@redhat.com>
Signed-off-by: default avatarDavide Caratti <dcaratti@redhat.com>
Signed-off-by: default avatarMat Martineau <martineau@kernel.org>
Link: https://lore.kernel.org/r/20231023-send-net-next-20231023-1-v2-4-16b1f701f900@kernel.org


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
Reviewed-by: default avatarJackie Liu <liuyun01@kylinos.cn>
Signed-off-by: default avatarGeliang Tang <tanggeliang@kylinos.cn>
parent 7134ba69

Documentation/netlink/specs/mptcp.yaml

0 → 100644
+391 −0
Original line number Diff line number Diff line 
# 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: per-op



definitions:

  -

    type: enum

    name: event-type

    enum-name: mptcp-event-type

    name-prefix: mptcp-event-

    entries:

     -

      name: unspec

      doc: unused event

     -

      name: created

      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

      doc:

        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport

        A MPTCP connection is established (can start new subflows).

     -

      name: closed

      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

      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

      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

      doc:

        family, sport, saddr4 | saddr6

        A PM listener is closed.



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:

          exact-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: endpoint

    name-prefix: mptcp-pm-endpoint-

    attributes:

      -

        name: addr

        type: nest

        nested-attributes: address

  -

    name: attr

    name-prefix: mptcp-pm-attr-

    attributes:

      -

        name: unspec

        type: unused

        value: 0

      -

        name: addr

        type: nest

        nested-attributes: address

      -

        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: address

  -

    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: endpoint

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: &add-addr-attrs

        request:

          attributes:

            - addr

    -

      name: del-addr

      doc: Delete endpoint

      attribute-set: endpoint

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: *add-addr-attrs

    -

      name: get-addr

      doc: Get endpoint information

      attribute-set: endpoint

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: &get-addr-attrs

        request:

          attributes:

           - addr

        reply:

          attributes:

           - addr

      dump:

        reply:

         attributes:

           - addr

    -

      name:  flush-addrs

      doc: flush addresses

      attribute-set: endpoint

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: *add-addr-attrs

    -

      name: set-limits

      doc: Set protocol limits

      attribute-set: attr

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: &mptcp-limits

        request:

          attributes:

            - rcv-add-addrs

            - subflows

    -

      name: get-limits

      doc: Get protocol limits

      attribute-set: attr

      dont-validate: [ strict ]

      do: &mptcp-get-limits

        request:

           attributes:

            - rcv-add-addrs

            - subflows

        reply:

          attributes:

            - rcv-add-addrs

            - subflows

    -

      name: set-flags

      doc: Change endpoint flags

      attribute-set: attr

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: &mptcp-set-flags

        request:

          attributes:

            - addr

            - token

            - addr-remote

    -

      name: announce

      doc: announce new sf

      attribute-set: attr

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: &announce-add

        request:

          attributes:

            - addr

            - token

    -

      name: remove

      doc: announce removal

      attribute-set: attr

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do:

        request:

         attributes:

           - token

           - loc-id

    -

      name: subflow-create

      doc: todo

      attribute-set: attr

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: &sf-create

        request:

          attributes:

            - addr

            - token

            - addr-remote

    -

      name: subflow-destroy

      doc: todo

      attribute-set: attr

      dont-validate: [ strict ]

      flags: [ uns-admin-perm ]

      do: *sf-create

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -15002,6 +15002,7 @@ W: https://github.com/multipath-tcp/mptcp_net-next/wiki 
B:	https://github.com/multipath-tcp/mptcp_net-next/issues

T:	git https://github.com/multipath-tcp/mptcp_net-next.git export-net

T:	git https://github.com/multipath-tcp/mptcp_net-next.git export

F:	Documentation/netlink/specs/mptcp.yaml

F:	Documentation/networking/mptcp-sysctl.rst

F:	include/net/mptcp.h

F:	include/trace/events/mptcp.h