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