GNU Linux-libre 6.9.1-gnu
[releases.git] / Documentation / netlink / specs / mptcp_pm.yaml
1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
2
3 name: mptcp_pm
4 protocol: genetlink-legacy
5 doc: Multipath TCP.
6
7 c-family-name: mptcp-pm-name
8 c-version-name: mptcp-pm-ver
9 max-by-define: true
10 kernel-policy: per-op
11 cmd-cnt-name: --mptcp-pm-cmd-after-last
12
13 definitions:
14   -
15     type: enum
16     name: event-type
17     enum-name: mptcp-event-type
18     name-prefix: mptcp-event-
19     entries:
20      -
21       name: unspec
22       doc: unused event
23      -
24       name: created
25       doc:
26         token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport
27         A new MPTCP connection has been created. It is the good time to
28         allocate memory and send ADD_ADDR if needed. Depending on the
29         traffic-patterns it can take a long time until the
30         MPTCP_EVENT_ESTABLISHED is sent.
31      -
32       name: established
33       doc:
34         token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport
35         A MPTCP connection is established (can start new subflows).
36      -
37       name: closed
38       doc:
39         token
40         A MPTCP connection has stopped.
41      -
42       name: announced
43       value: 6
44       doc:
45         token, rem_id, family, daddr4 | daddr6 [, dport]
46         A new address has been announced by the peer.
47      -
48       name: removed
49       doc:
50         token, rem_id
51         An address has been lost by the peer.
52      -
53       name: sub-established
54       value: 10
55       doc:
56         token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
57         dport, backup, if_idx [, error]
58         A new subflow has been established. 'error' should not be set.
59      -
60       name: sub-closed
61       doc:
62         token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
63         dport, backup, if_idx [, error]
64         A subflow has been closed. An error (copy of sk_err) could be set if an
65         error has been detected for this subflow.
66      -
67       name: sub-priority
68       value: 13
69       doc:
70         token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
71         dport, backup, if_idx [, error]
72         The priority of a subflow has changed. 'error' should not be set.
73      -
74       name: listener-created
75       value: 15
76       doc:
77         family, sport, saddr4 | saddr6
78         A new PM listener is created.
79      -
80       name: listener-closed
81       doc:
82         family, sport, saddr4 | saddr6
83         A PM listener is closed.
84
85 attribute-sets:
86   -
87     name: address
88     name-prefix: mptcp-pm-addr-attr-
89     attributes:
90       -
91         name: unspec
92         type: unused
93         value: 0
94       -
95         name: family
96         type: u16
97       -
98         name: id
99         type: u8
100       -
101         name: addr4
102         type: u32
103         byte-order: big-endian
104       -
105         name: addr6
106         type: binary
107         checks:
108           exact-len: 16
109       -
110         name: port
111         type: u16
112         byte-order: big-endian
113       -
114         name: flags
115         type: u32
116       -
117         name: if-idx
118         type: s32
119   -
120     name: subflow-attribute
121     name-prefix: mptcp-subflow-attr-
122     attributes:
123       -
124         name: unspec
125         type: unused
126         value: 0
127       -
128         name: token-rem
129         type: u32
130       -
131         name: token-loc
132         type: u32
133       -
134         name: relwrite-seq
135         type: u32
136       -
137         name: map-seq
138         type: u64
139       -
140         name: map-sfseq
141         type: u32
142       -
143         name: ssn-offset
144         type: u32
145       -
146         name: map-datalen
147         type: u16
148       -
149         name: flags
150         type: u32
151       -
152         name: id-rem
153         type: u8
154       -
155         name: id-loc
156         type: u8
157       -
158         name: pad
159         type: pad
160   -
161     name: endpoint
162     name-prefix: mptcp-pm-endpoint-
163     attributes:
164       -
165         name: addr
166         type: nest
167         nested-attributes: address
168   -
169     name: attr
170     name-prefix: mptcp-pm-attr-
171     attr-cnt-name: --mptcp-attr-after-last
172     attributes:
173       -
174         name: unspec
175         type: unused
176         value: 0
177       -
178         name: addr
179         type: nest
180         nested-attributes: address
181       -
182         name: rcv-add-addrs
183         type: u32
184       -
185         name: subflows
186         type: u32
187       -
188         name: token
189         type: u32
190       -
191         name: loc-id
192         type: u8
193       -
194         name: addr-remote
195         type: nest
196         nested-attributes: address
197   -
198     name: event-attr
199     enum-name: mptcp-event-attr
200     name-prefix: mptcp-attr-
201     attributes:
202       -
203         name: unspec
204         type: unused
205         value: 0
206       -
207         name: token
208         type: u32
209       -
210         name: family
211         type: u16
212       -
213         name: loc-id
214         type: u8
215       -
216         name: rem-id
217         type: u8
218       -
219         name: saddr4
220         type: u32
221         byte-order: big-endian
222       -
223         name: saddr6
224         type: binary
225         checks:
226           min-len: 16
227       -
228         name: daddr4
229         type: u32
230         byte-order: big-endian
231       -
232         name: daddr6
233         type: binary
234         checks:
235           min-len: 16
236       -
237         name: sport
238         type: u16
239         byte-order: big-endian
240       -
241         name: dport
242         type: u16
243         byte-order: big-endian
244       -
245         name: backup
246         type: u8
247       -
248         name: error
249         type: u8
250       -
251         name: flags
252         type: u16
253       -
254         name: timeout
255         type: u32
256       -
257         name: if_idx
258         type: u32
259       -
260         name: reset-reason
261         type: u32
262       -
263         name: reset-flags
264         type: u32
265       -
266         name: server-side
267         type: u8
268
269 operations:
270   list:
271     -
272       name: unspec
273       doc: unused
274       value: 0
275     -
276       name: add-addr
277       doc: Add endpoint
278       attribute-set: endpoint
279       dont-validate: [ strict ]
280       flags: [ uns-admin-perm ]
281       do: &add-addr-attrs
282         request:
283           attributes:
284             - addr
285     -
286       name: del-addr
287       doc: Delete endpoint
288       attribute-set: endpoint
289       dont-validate: [ strict ]
290       flags: [ uns-admin-perm ]
291       do: *add-addr-attrs
292     -
293       name: get-addr
294       doc: Get endpoint information
295       attribute-set: attr
296       dont-validate: [ strict ]
297       flags: [ uns-admin-perm ]
298       do: &get-addr-attrs
299         request:
300           attributes:
301            - addr
302            - token
303         reply:
304           attributes:
305            - addr
306       dump:
307         reply:
308          attributes:
309            - addr
310     -
311       name:  flush-addrs
312       doc: flush addresses
313       attribute-set: endpoint
314       dont-validate: [ strict ]
315       flags: [ uns-admin-perm ]
316       do: *add-addr-attrs
317     -
318       name: set-limits
319       doc: Set protocol limits
320       attribute-set: attr
321       dont-validate: [ strict ]
322       flags: [ uns-admin-perm ]
323       do: &mptcp-limits
324         request:
325           attributes:
326             - rcv-add-addrs
327             - subflows
328     -
329       name: get-limits
330       doc: Get protocol limits
331       attribute-set: attr
332       dont-validate: [ strict ]
333       do: &mptcp-get-limits
334         request:
335            attributes:
336             - rcv-add-addrs
337             - subflows
338         reply:
339           attributes:
340             - rcv-add-addrs
341             - subflows
342     -
343       name: set-flags
344       doc: Change endpoint flags
345       attribute-set: attr
346       dont-validate: [ strict ]
347       flags: [ uns-admin-perm ]
348       do: &mptcp-set-flags
349         request:
350           attributes:
351             - addr
352             - token
353             - addr-remote
354     -
355       name: announce
356       doc: announce new sf
357       attribute-set: attr
358       dont-validate: [ strict ]
359       flags: [ uns-admin-perm ]
360       do: &announce-add
361         request:
362           attributes:
363             - addr
364             - token
365     -
366       name: remove
367       doc: announce removal
368       attribute-set: attr
369       dont-validate: [ strict ]
370       flags: [ uns-admin-perm ]
371       do:
372         request:
373          attributes:
374            - token
375            - loc-id
376     -
377       name: subflow-create
378       doc: todo
379       attribute-set: attr
380       dont-validate: [ strict ]
381       flags: [ uns-admin-perm ]
382       do: &sf-create
383         request:
384           attributes:
385             - addr
386             - token
387             - addr-remote
388     -
389       name: subflow-destroy
390       doc: todo
391       attribute-set: attr
392       dont-validate: [ strict ]
393       flags: [ uns-admin-perm ]
394       do: *sf-create