Commit | Line | Data |
---|---|---|
4e16b6a7 | 1 | # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) |
e616c07c JK |
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 | |
18 | title: Protocol | |
19 | description: Specification of a genetlink protocol | |
20 | type: object | |
21 | required: [ name, doc, attribute-sets, operations ] | |
22 | additionalProperties: False | |
23 | properties: | |
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 ] | |
e616c07c JK |
36 | uapi-header: |
37 | description: Path to the uAPI header, default is linux/${family-name}.h | |
38 | type: string | |
82b32970 | 39 | # Start genetlink-c |
e616c07c JK |
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 verion 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 | ||
199 | # Make sure name-prefix does not appear in subsets (subsets inherit naming) | |
200 | dependencies: | |
201 | name-prefix: | |
202 | not: | |
203 | required: [ subset-of ] | |
204 | subset-of: | |
205 | not: | |
206 | required: [ name-prefix ] | |
207 | ||
208 | operations: | |
209 | description: Operations supported by the protocol. | |
210 | type: object | |
211 | required: [ list ] | |
212 | additionalProperties: False | |
213 | properties: | |
214 | enum-model: | |
215 | description: | | |
216 | The model of assigning values to the operations. | |
217 | "unified" is the recommended model where all message types belong | |
218 | to a single enum. | |
219 | "directional" has the messages sent to the kernel and from the kernel | |
220 | enumerated separately. | |
8403bf04 | 221 | enum: [ unified ] |
e616c07c JK |
222 | name-prefix: |
223 | description: | | |
224 | Prefix for the C enum name of the command. The name is formed by concatenating | |
225 | the prefix with the upper case name of the command, with dashes replaced by underscores. | |
226 | type: string | |
227 | enum-name: | |
228 | description: Name for the enum type with commands. | |
229 | type: string | |
230 | async-prefix: | |
231 | description: Same as name-prefix but used to render notifications and events to separate enum. | |
232 | type: string | |
233 | async-enum: | |
234 | description: Name for the enum type with notifications/events. | |
235 | type: string | |
236 | list: | |
237 | description: List of commands | |
238 | type: array | |
239 | items: | |
240 | type: object | |
241 | additionalProperties: False | |
242 | required: [ name, doc ] | |
243 | properties: | |
244 | name: | |
245 | description: Name of the operation, also defining its C enum value in uAPI. | |
246 | type: string | |
247 | doc: | |
248 | description: Documentation for the command. | |
249 | type: string | |
250 | value: | |
251 | description: Value for the enum in the uAPI. | |
252 | $ref: '#/$defs/uint' | |
253 | attribute-set: | |
254 | description: | | |
255 | Attribute space from which attributes directly in the requests and replies | |
256 | to this command are defined. | |
257 | type: string | |
258 | flags: &cmd_flags | |
259 | description: Command flags. | |
260 | type: array | |
261 | items: | |
262 | enum: [ admin-perm ] | |
263 | dont-validate: | |
264 | description: Kernel attribute validation flags. | |
265 | type: array | |
266 | items: | |
267 | enum: [ strict, dump ] | |
268 | do: &subop-type | |
269 | description: Main command handler. | |
270 | type: object | |
271 | additionalProperties: False | |
272 | properties: | |
273 | request: &subop-attr-list | |
274 | description: Definition of the request message for a given command. | |
275 | type: object | |
276 | additionalProperties: False | |
277 | properties: | |
278 | attributes: | |
279 | description: | | |
280 | Names of attributes from the attribute-set (not full attribute | |
281 | definitions, just names). | |
282 | type: array | |
283 | items: | |
284 | type: string | |
285 | reply: *subop-attr-list | |
286 | pre: | |
287 | description: Hook for a function to run before the main callback (pre_doit or start). | |
288 | type: string | |
289 | post: | |
290 | description: Hook for a function to run after the main callback (post_doit or done). | |
291 | type: string | |
292 | dump: *subop-type | |
293 | notify: | |
294 | description: Name of the command sharing the reply type with this notification. | |
295 | type: string | |
296 | event: | |
297 | type: object | |
298 | additionalProperties: False | |
299 | properties: | |
300 | attributes: | |
301 | description: Explicit list of the attributes for the notification. | |
302 | type: array | |
303 | items: | |
304 | type: string | |
305 | mcgrp: | |
306 | description: Name of the multicast group generating given notification. | |
307 | type: string | |
308 | mcast-groups: | |
309 | description: List of multicast groups. | |
310 | type: object | |
311 | required: [ list ] | |
312 | additionalProperties: False | |
313 | properties: | |
314 | list: | |
315 | description: List of groups. | |
316 | type: array | |
317 | items: | |
318 | type: object | |
319 | required: [ name ] | |
320 | additionalProperties: False | |
321 | properties: | |
322 | name: | |
323 | description: | | |
324 | The name for the group, used to form the define and the value of the define. | |
325 | type: string | |
326 | # Start genetlink-c | |
327 | c-define-name: | |
328 | description: Override for the name of the define in C uAPI. | |
329 | type: string | |
330 | # End genetlink-c | |
331 | flags: *cmd_flags |