1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linu 1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
2 %YAML 1.2 2 %YAML 1.2
3 --- 3 ---
4 $id: http://kernel.org/schemas/netlink/genetli 4 $id: http://kernel.org/schemas/netlink/genetlink-legacy.yaml#
5 $schema: https://json-schema.org/draft-07/sche 5 $schema: https://json-schema.org/draft-07/schema
6 6
7 # Common defines 7 # Common defines
8 $defs: 8 $defs:
9 uint: 9 uint:
10 type: integer 10 type: integer
11 minimum: 0 11 minimum: 0
12 len-or-define: 12 len-or-define:
13 type: [ string, integer ] 13 type: [ string, integer ]
14 pattern: ^[0-9A-Za-z_-]+( - 1)?$ 14 pattern: ^[0-9A-Za-z_-]+( - 1)?$
15 minimum: 0 15 minimum: 0
16 len-or-limit: 16 len-or-limit:
17 # literal int or limit based on fixed-widt 17 # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc.
18 type: [ string, integer ] 18 type: [ string, integer ]
19 pattern: ^[su](8|16|32|64)-(min|max)$ 19 pattern: ^[su](8|16|32|64)-(min|max)$
20 minimum: 0 20 minimum: 0
21 21
22 # Schema for specs 22 # Schema for specs
23 title: Protocol 23 title: Protocol
24 description: Specification of a genetlink prot 24 description: Specification of a genetlink protocol
25 type: object 25 type: object
26 required: [ name, doc, attribute-sets, operati 26 required: [ name, doc, attribute-sets, operations ]
27 additionalProperties: False 27 additionalProperties: False
28 properties: 28 properties:
29 name: 29 name:
30 description: Name of the genetlink family. 30 description: Name of the genetlink family.
31 type: string 31 type: string
32 doc: 32 doc:
33 type: string 33 type: string
34 protocol: 34 protocol:
35 description: Schema compatibility level. D 35 description: Schema compatibility level. Default is "genetlink".
36 enum: [ genetlink, genetlink-c, genetlink- 36 enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim
37 uapi-header: 37 uapi-header:
38 description: Path to the uAPI header, defa 38 description: Path to the uAPI header, default is linux/${family-name}.h
39 type: string 39 type: string
40 # Start genetlink-c 40 # Start genetlink-c
41 c-family-name: 41 c-family-name:
42 description: Name of the define for the fa 42 description: Name of the define for the family name.
43 type: string 43 type: string
44 c-version-name: 44 c-version-name:
45 description: Name of the define for the ve 45 description: Name of the define for the version of the family.
46 type: string 46 type: string
47 max-by-define: 47 max-by-define:
48 description: Makes the number of attribute 48 description: Makes the number of attributes and commands be specified by a define, not an enum value.
49 type: boolean 49 type: boolean
50 cmd-max-name: 50 cmd-max-name:
51 description: Name of the define for the la 51 description: Name of the define for the last operation in the list.
52 type: string 52 type: string
53 cmd-cnt-name: 53 cmd-cnt-name:
54 description: The explicit name for constan 54 description: The explicit name for constant holding the count of operations (last operation + 1).
55 type: string 55 type: string
56 # End genetlink-c 56 # End genetlink-c
57 # Start genetlink-legacy 57 # Start genetlink-legacy
58 kernel-policy: 58 kernel-policy:
59 description: | 59 description: |
60 Defines if the input policy in the kerne 60 Defines if the input policy in the kernel is global, per-operation, or split per operation type.
61 Default is split. 61 Default is split.
62 enum: [ split, per-op, global ] 62 enum: [ split, per-op, global ]
63 version: 63 version:
64 description: Generic Netlink family versio 64 description: Generic Netlink family version. Default is 1.
65 type: integer 65 type: integer
66 minimum: 1 66 minimum: 1
67 # End genetlink-legacy 67 # End genetlink-legacy
68 68
69 definitions: 69 definitions:
70 description: List of type and constant def 70 description: List of type and constant definitions (enums, flags, defines).
71 type: array 71 type: array
72 items: 72 items:
73 type: object 73 type: object
74 required: [ type, name ] 74 required: [ type, name ]
75 additionalProperties: False 75 additionalProperties: False
76 properties: 76 properties:
77 name: 77 name:
78 type: string 78 type: string
79 header: 79 header:
80 description: For C-compatible langua 80 description: For C-compatible languages, header which already defines this value.
81 type: string 81 type: string
82 type: 82 type:
83 enum: [ const, enum, flags, struct ] 83 enum: [ const, enum, flags, struct ] # Trim
84 doc: 84 doc:
85 type: string 85 type: string
86 # For const 86 # For const
87 value: 87 value:
88 description: For const - the value. 88 description: For const - the value.
89 type: [ string, integer ] 89 type: [ string, integer ]
90 # For enum and flags 90 # For enum and flags
91 value-start: 91 value-start:
92 description: For enum or flags the l 92 description: For enum or flags the literal initializer for the first value.
93 type: [ string, integer ] 93 type: [ string, integer ]
94 entries: 94 entries:
95 description: For enum or flags array 95 description: For enum or flags array of values.
96 type: array 96 type: array
97 items: 97 items:
98 oneOf: 98 oneOf:
99 - type: string 99 - type: string
100 - type: object 100 - type: object
101 required: [ name ] 101 required: [ name ]
102 additionalProperties: False 102 additionalProperties: False
103 properties: 103 properties:
104 name: 104 name:
105 type: string 105 type: string
106 value: 106 value:
107 type: integer 107 type: integer
108 doc: 108 doc:
109 type: string 109 type: string
110 render-max: 110 render-max:
111 description: Render the max members 111 description: Render the max members for this enum.
112 type: boolean 112 type: boolean
113 # Start genetlink-c 113 # Start genetlink-c
114 enum-name: 114 enum-name:
115 description: Name for enum, if empty 115 description: Name for enum, if empty no name will be used.
116 type: [ string, "null" ] 116 type: [ string, "null" ]
117 name-prefix: 117 name-prefix:
118 description: For enum the prefix of 118 description: For enum the prefix of the values, optional.
119 type: string 119 type: string
120 # End genetlink-c 120 # End genetlink-c
121 # Start genetlink-legacy 121 # Start genetlink-legacy
122 members: 122 members:
123 description: List of struct members. 123 description: List of struct members. Only scalars and strings members allowed.
124 type: array 124 type: array
125 items: 125 items:
126 type: object 126 type: object
127 required: [ name, type ] 127 required: [ name, type ]
128 additionalProperties: False 128 additionalProperties: False
129 properties: 129 properties:
130 name: 130 name:
131 type: string 131 type: string
132 type: 132 type:
133 description: The netlink attri 133 description: The netlink attribute type
134 enum: [ u8, u16, u32, u64, s8, 134 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ]
135 len: 135 len:
136 $ref: '#/$defs/len-or-define' 136 $ref: '#/$defs/len-or-define'
137 byte-order: 137 byte-order:
138 enum: [ little-endian, big-end 138 enum: [ little-endian, big-endian ]
139 doc: 139 doc:
140 description: Documentation for 140 description: Documentation for the struct member attribute.
141 type: string 141 type: string
142 enum: 142 enum:
143 description: Name of the enum 143 description: Name of the enum type used for the attribute.
144 type: string 144 type: string
145 display-hint: &display-hint 145 display-hint: &display-hint
146 description: | 146 description: |
147 Optional format indicator th 147 Optional format indicator that is intended only for choosing
148 the right formatting mechani 148 the right formatting mechanism when displaying values of this
149 type. 149 type.
150 enum: [ hex, mac, fddi, ipv4, 150 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
151 # End genetlink-legacy 151 # End genetlink-legacy
152 152
153 attribute-sets: 153 attribute-sets:
154 description: Definition of attribute space 154 description: Definition of attribute spaces for this family.
155 type: array 155 type: array
156 items: 156 items:
157 description: Definition of a single attr 157 description: Definition of a single attribute space.
158 type: object 158 type: object
159 required: [ name, attributes ] 159 required: [ name, attributes ]
160 additionalProperties: False 160 additionalProperties: False
161 properties: 161 properties:
162 name: 162 name:
163 description: | 163 description: |
164 Name used when referring to this s 164 Name used when referring to this space in other definitions, not used outside of the spec.
165 type: string 165 type: string
166 name-prefix: 166 name-prefix:
167 description: | 167 description: |
168 Prefix for the C enum name of the 168 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
169 type: string 169 type: string
170 enum-name: 170 enum-name:
171 description: | 171 description: |
172 Name for the enum type of the attr 172 Name for the enum type of the attribute, if empty no name will be used.
173 type: [ string, "null" ] 173 type: [ string, "null" ]
174 doc: 174 doc:
175 description: Documentation of the sp 175 description: Documentation of the space.
176 type: string 176 type: string
177 subset-of: 177 subset-of:
178 description: | 178 description: |
179 Name of another space which this i 179 Name of another space which this is a logical part of. Sub-spaces can be used to define
180 a limited group of attributes whic 180 a limited group of attributes which are used in a nest.
181 type: string 181 type: string
182 # Start genetlink-c 182 # Start genetlink-c
183 attr-cnt-name: 183 attr-cnt-name:
184 description: The explicit name for c 184 description: The explicit name for constant holding the count of attributes (last attr + 1).
185 type: string 185 type: string
186 attr-max-name: 186 attr-max-name:
187 description: The explicit name for l 187 description: The explicit name for last member of attribute enum.
188 type: string 188 type: string
189 # End genetlink-c 189 # End genetlink-c
190 attributes: 190 attributes:
191 description: List of attributes in t 191 description: List of attributes in the space.
192 type: array 192 type: array
193 items: 193 items:
194 type: object 194 type: object
195 required: [ name ] 195 required: [ name ]
196 additionalProperties: False 196 additionalProperties: False
197 properties: 197 properties:
198 name: 198 name:
199 type: string 199 type: string
200 type: &attr-type 200 type: &attr-type
201 description: The netlink attri 201 description: The netlink attribute type
202 enum: [ unused, pad, flag, bin 202 enum: [ unused, pad, flag, binary, bitfield32,
203 uint, sint, u8, u16, u 203 uint, sint, u8, u16, u32, u64, s32, s64,
204 string, nest, indexed- 204 string, nest, indexed-array, nest-type-value ]
205 doc: 205 doc:
206 description: Documentation of 206 description: Documentation of the attribute.
207 type: string 207 type: string
208 value: 208 value:
209 description: Value for the enu 209 description: Value for the enum item representing this attribute in the uAPI.
210 $ref: '#/$defs/uint' 210 $ref: '#/$defs/uint'
211 type-value: 211 type-value:
212 description: Name of the value 212 description: Name of the value extracted from the type of a nest-type-value attribute.
213 type: array 213 type: array
214 items: 214 items:
215 type: string 215 type: string
216 byte-order: 216 byte-order:
217 enum: [ little-endian, big-end 217 enum: [ little-endian, big-endian ]
218 multi-attr: 218 multi-attr:
219 type: boolean 219 type: boolean
220 nested-attributes: 220 nested-attributes:
221 description: Name of the space 221 description: Name of the space (sub-space) used inside the attribute.
222 type: string 222 type: string
223 enum: 223 enum:
224 description: Name of the enum 224 description: Name of the enum type used for the attribute.
225 type: string 225 type: string
226 enum-as-flags: 226 enum-as-flags:
227 description: | 227 description: |
228 Treat the enum as flags. In 228 Treat the enum as flags. In most cases enum is either used as flags or as values.
229 Sometimes, however, both for 229 Sometimes, however, both forms are necessary, in which case header contains the enum
230 form while specific attribut 230 form while specific attributes may request to convert the values into a bitfield.
231 type: boolean 231 type: boolean
232 checks: 232 checks:
233 description: Kernel input vali 233 description: Kernel input validation.
234 type: object 234 type: object
235 additionalProperties: False 235 additionalProperties: False
236 properties: 236 properties:
237 flags-mask: 237 flags-mask:
238 description: Name of the f 238 description: Name of the flags constant on which to base mask (unsigned scalar types only).
239 type: string 239 type: string
240 min: 240 min:
241 description: Min value for 241 description: Min value for an integer attribute.
242 $ref: '#/$defs/len-or-limi 242 $ref: '#/$defs/len-or-limit'
243 max: 243 max:
244 description: Max value for 244 description: Max value for an integer attribute.
245 $ref: '#/$defs/len-or-limi 245 $ref: '#/$defs/len-or-limit'
246 min-len: 246 min-len:
247 description: Min length fo 247 description: Min length for a binary attribute.
248 $ref: '#/$defs/len-or-defi 248 $ref: '#/$defs/len-or-define'
249 max-len: 249 max-len:
250 description: Max length fo 250 description: Max length for a string or a binary attribute.
251 $ref: '#/$defs/len-or-defi 251 $ref: '#/$defs/len-or-define'
252 exact-len: 252 exact-len:
253 description: Exact length 253 description: Exact length for a string or a binary attribute.
254 $ref: '#/$defs/len-or-defi 254 $ref: '#/$defs/len-or-define'
255 unterminated-ok: 255 unterminated-ok:
256 description: | 256 description: |
257 For string attributes, d 257 For string attributes, do not check whether attribute
258 contains the terminating 258 contains the terminating null character.
259 type: boolean 259 type: boolean
260 sub-type: *attr-type 260 sub-type: *attr-type
261 display-hint: *display-hint 261 display-hint: *display-hint
262 # Start genetlink-c 262 # Start genetlink-c
263 name-prefix: 263 name-prefix:
264 type: string 264 type: string
265 # End genetlink-c 265 # End genetlink-c
266 # Start genetlink-legacy 266 # Start genetlink-legacy
267 struct: 267 struct:
268 description: Name of the struc 268 description: Name of the struct type used for the attribute.
269 type: string 269 type: string
270 # End genetlink-legacy 270 # End genetlink-legacy
271 271
272 # Make sure name-prefix does not appear 272 # Make sure name-prefix does not appear in subsets (subsets inherit naming)
273 dependencies: 273 dependencies:
274 name-prefix: 274 name-prefix:
275 not: 275 not:
276 required: [ subset-of ] 276 required: [ subset-of ]
277 subset-of: 277 subset-of:
278 not: 278 not:
279 required: [ name-prefix ] 279 required: [ name-prefix ]
280 280
281 # type property is only required if not 281 # type property is only required if not in subset definition
282 if: 282 if:
283 properties: 283 properties:
284 subset-of: 284 subset-of:
285 not: 285 not:
286 type: string 286 type: string
287 then: 287 then:
288 properties: 288 properties:
289 attributes: 289 attributes:
290 items: 290 items:
291 required: [ type ] 291 required: [ type ]
292 292
293 operations: 293 operations:
294 description: Operations supported by the p 294 description: Operations supported by the protocol.
295 type: object 295 type: object
296 required: [ list ] 296 required: [ list ]
297 additionalProperties: False 297 additionalProperties: False
298 properties: 298 properties:
299 enum-model: 299 enum-model:
300 description: | 300 description: |
301 The model of assigning values to the 301 The model of assigning values to the operations.
302 "unified" is the recommended model w 302 "unified" is the recommended model where all message types belong
303 to a single enum. 303 to a single enum.
304 "directional" has the messages sent 304 "directional" has the messages sent to the kernel and from the kernel
305 enumerated separately. 305 enumerated separately.
306 enum: [ unified, directional ] # Trim 306 enum: [ unified, directional ] # Trim
307 name-prefix: 307 name-prefix:
308 description: | 308 description: |
309 Prefix for the C enum name of the co 309 Prefix for the C enum name of the command. The name is formed by concatenating
310 the prefix with the upper case name 310 the prefix with the upper case name of the command, with dashes replaced by underscores.
311 type: string 311 type: string
312 enum-name: 312 enum-name:
313 description: | 313 description: |
314 Name for the enum type with commands 314 Name for the enum type with commands, if empty no name will be used.
315 type: [ string, "null" ] 315 type: [ string, "null" ]
316 async-prefix: 316 async-prefix:
317 description: Same as name-prefix but u 317 description: Same as name-prefix but used to render notifications and events to separate enum.
318 type: string 318 type: string
319 async-enum: 319 async-enum:
320 description: | 320 description: |
321 Name for the enum type with commands 321 Name for the enum type with commands, if empty no name will be used.
322 type: [ string, "null" ] 322 type: [ string, "null" ]
323 # Start genetlink-legacy 323 # Start genetlink-legacy
324 fixed-header: &fixed-header 324 fixed-header: &fixed-header
325 description: | 325 description: |
326 Name of the structure defining the o 326 Name of the structure defining the optional fixed-length protocol
327 header. This header is placed in a m 327 header. This header is placed in a message after the netlink and
328 genetlink headers and before any att 328 genetlink headers and before any attributes.
329 type: string 329 type: string
330 # End genetlink-legacy 330 # End genetlink-legacy
331 list: 331 list:
332 description: List of commands 332 description: List of commands
333 type: array 333 type: array
334 items: 334 items:
335 type: object 335 type: object
336 additionalProperties: False 336 additionalProperties: False
337 required: [ name, doc ] 337 required: [ name, doc ]
338 properties: 338 properties:
339 name: 339 name:
340 description: Name of the operati 340 description: Name of the operation, also defining its C enum value in uAPI.
341 type: string 341 type: string
342 doc: 342 doc:
343 description: Documentation for t 343 description: Documentation for the command.
344 type: string 344 type: string
345 value: 345 value:
346 description: Value for the enum 346 description: Value for the enum in the uAPI.
347 $ref: '#/$defs/uint' 347 $ref: '#/$defs/uint'
348 attribute-set: 348 attribute-set:
349 description: | 349 description: |
350 Attribute space from which att 350 Attribute space from which attributes directly in the requests and replies
351 to this command are defined. 351 to this command are defined.
352 type: string 352 type: string
353 flags: &cmd_flags 353 flags: &cmd_flags
354 description: Command flags. 354 description: Command flags.
355 type: array 355 type: array
356 items: 356 items:
357 enum: [ admin-perm, uns-admin- 357 enum: [ admin-perm, uns-admin-perm ]
358 dont-validate: 358 dont-validate:
359 description: Kernel attribute va 359 description: Kernel attribute validation flags.
360 type: array 360 type: array
361 items: 361 items:
362 enum: [ strict, dump, dump-str 362 enum: [ strict, dump, dump-strict ]
363 config-cond: 363 config-cond:
364 description: | 364 description: |
365 Name of the kernel config opti 365 Name of the kernel config option gating the presence of
366 the operation, without the 'CO 366 the operation, without the 'CONFIG_' prefix.
367 type: string 367 type: string
368 # Start genetlink-legacy 368 # Start genetlink-legacy
369 fixed-header: *fixed-header 369 fixed-header: *fixed-header
370 # End genetlink-legacy 370 # End genetlink-legacy
371 do: &subop-type 371 do: &subop-type
372 description: Main command handle 372 description: Main command handler.
373 type: object 373 type: object
374 additionalProperties: False 374 additionalProperties: False
375 properties: 375 properties:
376 request: &subop-attr-list 376 request: &subop-attr-list
377 description: Definition of t 377 description: Definition of the request message for a given command.
378 type: object 378 type: object
379 additionalProperties: False 379 additionalProperties: False
380 properties: 380 properties:
381 attributes: 381 attributes:
382 description: | 382 description: |
383 Names of attributes fr 383 Names of attributes from the attribute-set (not full attribute
384 definitions, just name 384 definitions, just names).
385 type: array 385 type: array
386 items: 386 items:
387 type: string 387 type: string
388 # Start genetlink-legacy 388 # Start genetlink-legacy
389 value: 389 value:
390 description: | 390 description: |
391 ID of this message if 391 ID of this message if value for request and response differ,
392 i.e. requests and resp 392 i.e. requests and responses have different message enums.
393 $ref: '#/$defs/uint' 393 $ref: '#/$defs/uint'
394 # End genetlink-legacy 394 # End genetlink-legacy
395 reply: *subop-attr-list 395 reply: *subop-attr-list
396 pre: 396 pre:
397 description: Hook for a func 397 description: Hook for a function to run before the main callback (pre_doit or start).
398 type: string 398 type: string
399 post: 399 post:
400 description: Hook for a func 400 description: Hook for a function to run after the main callback (post_doit or done).
401 type: string 401 type: string
402 dump: *subop-type 402 dump: *subop-type
403 notify: 403 notify:
404 description: Name of the command 404 description: Name of the command sharing the reply type with this notification.
405 type: string 405 type: string
406 event: 406 event:
407 type: object 407 type: object
408 additionalProperties: False 408 additionalProperties: False
409 properties: 409 properties:
410 attributes: 410 attributes:
411 description: Explicit list o 411 description: Explicit list of the attributes for the notification.
412 type: array 412 type: array
413 items: 413 items:
414 type: string 414 type: string
415 mcgrp: 415 mcgrp:
416 description: Name of the multica 416 description: Name of the multicast group generating given notification.
417 type: string 417 type: string
418 mcast-groups: 418 mcast-groups:
419 description: List of multicast groups. 419 description: List of multicast groups.
420 type: object 420 type: object
421 required: [ list ] 421 required: [ list ]
422 additionalProperties: False 422 additionalProperties: False
423 properties: 423 properties:
424 list: 424 list:
425 description: List of groups. 425 description: List of groups.
426 type: array 426 type: array
427 items: 427 items:
428 type: object 428 type: object
429 required: [ name ] 429 required: [ name ]
430 additionalProperties: False 430 additionalProperties: False
431 properties: 431 properties:
432 name: 432 name:
433 description: | 433 description: |
434 The name for the group, used t 434 The name for the group, used to form the define and the value of the define.
435 type: string 435 type: string
436 # Start genetlink-c 436 # Start genetlink-c
437 c-define-name: 437 c-define-name:
438 description: Override for the na 438 description: Override for the name of the define in C uAPI.
439 type: string 439 type: string
440 # End genetlink-c 440 # End genetlink-c
441 flags: *cmd_flags 441 flags: *cmd_flags
442 442
443 kernel-family: 443 kernel-family:
444 description: Additional global attributes 444 description: Additional global attributes used for kernel C code generation.
445 type: object 445 type: object
446 additionalProperties: False 446 additionalProperties: False
447 properties: 447 properties:
448 headers: 448 headers:
449 description: | 449 description: |
450 List of extra headers which should b 450 List of extra headers which should be included in the source
451 of the generated code. 451 of the generated code.
452 type: array 452 type: array
453 items: 453 items:
454 type: string 454 type: string
455 sock-priv: 455 sock-priv:
456 description: | 456 description: |
457 Literal name of the type which is us 457 Literal name of the type which is used within the kernel
458 to store the socket state. The type 458 to store the socket state. The type / structure is internal
459 to the kernel, and is not defined in 459 to the kernel, and is not defined in the spec.
460 type: string 460 type: string
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.