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