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