[linux-block.git] / Documentation / netlink / genetlink.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-legacy.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
  len-or-limit:
    # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc.
    type: [ string, integer ]
    pattern: ^[su](8|16|32|64)-(min|max)$
    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
  protocol:
    description: Schema compatibility level. Default is "genetlink".
    enum: [ genetlink ]
  uapi-header:
    description: Path to the uAPI header, default is linux/${family-name}.h
    type: string

  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

  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
        attributes:
          description: List of attributes in the space.
          type: array
          items:
            type: object
            required: [ name ]
            additionalProperties: False
            properties:
              name:
                type: string
              type: &attr-type
                enum: [ unused, pad, flag, binary,
                        uint, sint, u8, u16, u32, u64, s32, s64,
                        string, nest, indexed-array, 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.
                    $ref: '#/$defs/len-or-limit'
                  max:
                    description: Max value for an integer attribute.
                    $ref: '#/$defs/len-or-limit'
                  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'
                  exact-len:
                    description: Exact length for a string or a binary attribute.
                    $ref: '#/$defs/len-or-define'
              sub-type: *attr-type
              display-hint: &display-hint
                description: |
                  Optional format indicator that is intended only for choosing
                  the right formatting mechanism when displaying values of this
                  type.
                enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]

      # 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 ]

      # type property is only required if not in subset definition
      if:
        properties:
          subset-of:
            not:
              type: string
      then:
        properties:
          attributes:
            items:
              required: [ type ]

  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, dump-strict ]
            config-cond:
              description: |
                Name of the kernel config option gating the presence of
                the operation, without the 'CONFIG_' prefix.
              type: string
            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
            flags: *cmd_flags

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