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