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