Documentation: netlink: add a YAML spec for mptcp

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: Paolo Abeni <pabeni@redhat.com>
Signed-off-by: Davide Caratti <dcaratti@redhat.com>
Signed-off-by: Mat Martineau <martineau@kernel.org>
Link: https://lore.kernel.org/r/20231023-send-net-next-20231023-1-v2-4-16b1f701f900@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Davide Caratti 2023-10-23 11:17:08 -07:00 committed by Jakub Kicinski
parent 1d0507f468
commit bc8aeb2045
2 changed files with 392 additions and 0 deletions

View File

@ -0,0 +1,391 @@
# 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

View File

@ -14960,6 +14960,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