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