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