netlink: add schemas for YAML specs (e616c07c) · Commits · EulixOS / Software / Kernel

Documentation/netlink/genetlink-c.yaml

0 → 100644

+333 −0

Original line number	Diff line number	Diff line
		# SPDX-License-Identifier: GPL-2.0
		%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.
		"notify-split" has the notifications and request-response types in
		different enums.
		enum: [ unified, directional, notify-split ]
		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

Documentation/netlink/genetlink-legacy.yaml

0 → 100644

+356 −0

Original line number	Diff line number	Diff line
		# SPDX-License-Identifier: GPL-2.0
		%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

		# 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, genetlink-legacy ] # Trim
		# 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
		# Start genetlink-legacy
		kernel-policy:
		description: \|
		Defines if the input policy in the kernel is global, per-operation, or split per operation type.
		Default is split.
		enum: [ split, per-op, global ]
		# End genetlink-legacy

		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, struct ] # Trim
		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
		# Start genetlink-legacy
		members:
		description: List of struct members. Only scalars and strings members allowed.
		type: array
		items:
		type: object
		required: [ name, type ]
		additionalProperties: False
		properties:
		name:
		type: string
		type:
		enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string ]
		len:
		$ref: '#/$defs/len-or-define'
		# End genetlink-legacy

		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.
		"notify-split" has the notifications and request-response types in
		different enums.
		enum: [ unified, directional, notify-split ]
		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

Documentation/netlink/genetlink.yaml

0 → 100644

+298 −0

File added.

Preview size limit exceeded, changes collapsed.