[linux-block.git] / Documentation / netlink / genetlink-c.yaml

# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
%YAML 1.2
---
$id: http://kernel.org/schemas/netlink/genetlink-c.yaml#
$schema: https://json-schema.org/draft-07/schema

# Common defines
$defs:
  uint:
    type: integer
    minimum: 0
  len-or-define:
    type: [ string, integer ]
    pattern: ^[0-9A-Za-z_]+( - 1)?$
    minimum: 0

# Schema for specs
title: Protocol
description: Specification of a genetlink protocol
type: object
required: [ name, doc, attribute-sets, operations ]
additionalProperties: False
properties:
  name:
    description: Name of the genetlink family.
    type: string
  doc:
    type: string
  version:
    description: Generic Netlink family version. Default is 1.
    type: integer
    minimum: 1
  protocol:
    description: Schema compatibility level. Default is "genetlink".
    enum: [ genetlink, genetlink-c ]
  uapi-header:
    description: Path to the uAPI header, default is linux/${family-name}.h
    type: string
  # Start genetlink-c
  c-family-name:
    description: Name of the define for the family name.
    type: string
  c-version-name:
    description: Name of the define for the verion of the family.
    type: string
  max-by-define:
    description: Makes the number of attributes and commands be specified by a define, not an enum value.
    type: boolean
  # End genetlink-c

  definitions:
    description: List of type and constant definitions (enums, flags, defines).
    type: array
    items:
      type: object
      required: [ type, name ]
      additionalProperties: False
      properties:
        name:
          type: string
        header:
          description: For C-compatible languages, header which already defines this value.
          type: string
        type:
          enum: [ const, enum, flags ]
        doc:
          type: string
        # For const
        value:
          description: For const - the value.
          type: [ string, integer ]
        # For enum and flags
        value-start:
          description: For enum or flags the literal initializer for the first value.
          type: [ string, integer ]
        entries:
          description: For enum or flags array of values.
          type: array
          items:
            oneOf:
              - type: string
              - type: object
                required: [ name ]
                additionalProperties: False
                properties:
                  name:
                    type: string
                  value:
                    type: integer
                  doc:
                    type: string
        render-max:
          description: Render the max members for this enum.
          type: boolean
        # Start genetlink-c
        enum-name:
          description: Name for enum, if empty no name will be used.
          type: [ string, "null" ]
        name-prefix:
          description: For enum the prefix of the values, optional.
          type: string
        # End genetlink-c

  attribute-sets:
    description: Definition of attribute spaces for this family.
    type: array
    items:
      description: Definition of a single attribute space.
      type: object
      required: [ name, attributes ]
      additionalProperties: False
      properties:
        name:
          description: |
            Name used when referring to this space in other definitions, not used outside of the spec.
          type: string
        name-prefix:
          description: |
            Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
          type: string
        enum-name:
          description: Name for the enum type of the attribute.
          type: string
        doc:
          description: Documentation of the space.
          type: string
        subset-of:
          description: |
            Name of another space which this is a logical part of. Sub-spaces can be used to define
            a limited group of attributes which are used in a nest.
          type: string
        # Start genetlink-c
        attr-cnt-name:
          description: The explicit name for constant holding the count of attributes (last attr + 1).
          type: string
        attr-max-name:
          description: The explicit name for last member of attribute enum.
          type: string
        # End genetlink-c
        attributes:
          description: List of attributes in the space.
          type: array
          items:
            type: object
            required: [ name, type ]
            additionalProperties: False
            properties:
              name:
                type: string
              type: &attr-type
                enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64,
                        string, nest, array-nest, nest-type-value ]
              doc:
                description: Documentation of the attribute.
                type: string
              value:
                description: Value for the enum item representing this attribute in the uAPI.
                $ref: '#/$defs/uint'
              type-value:
                description: Name of the value extracted from the type of a nest-type-value attribute.
                type: array
                items:
                  type: string
              byte-order:
                enum: [ little-endian, big-endian ]
              multi-attr:
                type: boolean
              nested-attributes:
                description: Name of the space (sub-space) used inside the attribute.
                type: string
              enum:
                description: Name of the enum type used for the attribute.
                type: string
              enum-as-flags:
                description: |
                  Treat the enum as flags. In most cases enum is either used as flags or as values.
                  Sometimes, however, both forms are necessary, in which case header contains the enum
                  form while specific attributes may request to convert the values into a bitfield.
                type: boolean
              checks:
                description: Kernel input validation.
                type: object
                additionalProperties: False
                properties:
                  flags-mask:
                    description: Name of the flags constant on which to base mask (unsigned scalar types only).
                    type: string
                  min:
                    description: Min value for an integer attribute.
                    type: integer
                  min-len:
                    description: Min length for a binary attribute.
                    $ref: '#/$defs/len-or-define'
                  max-len:
                    description: Max length for a string or a binary attribute.
                    $ref: '#/$defs/len-or-define'
              sub-type: *attr-type

      # Make sure name-prefix does not appear in subsets (subsets inherit naming)
      dependencies:
        name-prefix:
          not:
            required: [ subset-of ]
        subset-of:
          not:
            required: [ name-prefix ]

  operations:
    description: Operations supported by the protocol.
    type: object
    required: [ list ]
    additionalProperties: False
    properties:
      enum-model:
        description: |
          The model of assigning values to the operations.
          "unified" is the recommended model where all message types belong
          to a single enum.
          "directional" has the messages sent to the kernel and from the kernel
          enumerated separately.
        enum: [ unified ]
      name-prefix:
        description: |
          Prefix for the C enum name of the command. The name is formed by concatenating
          the prefix with the upper case name of the command, with dashes replaced by underscores.
        type: string
      enum-name:
        description: Name for the enum type with commands.
        type: string
      async-prefix:
        description: Same as name-prefix but used to render notifications and events to separate enum.
        type: string
      async-enum:
        description: Name for the enum type with notifications/events.
        type: string
      list:
        description: List of commands
        type: array
        items:
          type: object
          additionalProperties: False
          required: [ name, doc ]
          properties:
            name:
              description: Name of the operation, also defining its C enum value in uAPI.
              type: string
            doc:
              description: Documentation for the command.
              type: string
            value:
              description: Value for the enum in the uAPI.
              $ref: '#/$defs/uint'
            attribute-set:
              description: |
                Attribute space from which attributes directly in the requests and replies
                to this command are defined.
              type: string
            flags: &cmd_flags
              description: Command flags.
              type: array
              items:
                enum: [ admin-perm ]
            dont-validate:
              description: Kernel attribute validation flags.
              type: array
              items:
                enum: [ strict, dump ]
            do: &subop-type
              description: Main command handler.
              type: object
              additionalProperties: False
              properties:
                request: &subop-attr-list
                  description: Definition of the request message for a given command.
                  type: object
                  additionalProperties: False
                  properties:
                    attributes:
                      description: |
                        Names of attributes from the attribute-set (not full attribute
                        definitions, just names).
                      type: array
                      items:
                        type: string
                reply: *subop-attr-list
                pre:
                  description: Hook for a function to run before the main callback (pre_doit or start).
                  type: string
                post:
                  description: Hook for a function to run after the main callback (post_doit or done).
                  type: string
            dump: *subop-type
            notify:
              description: Name of the command sharing the reply type with this notification.
              type: string
            event:
              type: object
              additionalProperties: False
              properties:
                attributes:
                  description: Explicit list of the attributes for the notification.
                  type: array
                  items:
                    type: string
            mcgrp:
              description: Name of the multicast group generating given notification.
              type: string
  mcast-groups:
    description: List of multicast groups.
    type: object
    required: [ list ]
    additionalProperties: False
    properties:
      list:
        description: List of groups.
        type: array
        items:
          type: object
          required: [ name ]
          additionalProperties: False
          properties:
            name:
              description: |
                The name for the group, used to form the define and the value of the define.
              type: string
            # Start genetlink-c
            c-define-name:
              description: Override for the name of the define in C uAPI.
              type: string
            # End genetlink-c
            flags: *cmd_flags
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