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