Documentation/netlink/genetlink-c.yaml - linux - Git at Google

 # 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 ]
   # Start genetlink-c
   uapi-header:
     description: Path to the uAPI header, default is linux/${family-name}.h
     type: string
   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
	# 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 ]
	# Start genetlink-c
	uapi-header:
	description: Path to the uAPI header, default is linux/${family-name}.h
	type: string
	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