Merge branch 'netlink-protocol-specs' (c554520f) · Commits · EulixOS / Software / Kernel

Documentation/core-api/index.rst

+1 −0

Original line number	Diff line number	Diff line
		@@ -127,6 +127,7 @@ Documents that don't fit elsewhere or which have yet to be categorized.
		:maxdepth: 1

		librs
		netlink

		.. only:: subproject and html

Documentation/core-api/netlink.rst

0 → 100644

+101 −0

Original line number	Diff line number	Diff line
		.. SPDX-License-Identifier: BSD-3-Clause

		.. _kernel_netlink:

		===================================
		Netlink notes for kernel developers
		===================================

		General guidance
		================

		Attribute enums
		---------------

		Older families often define "null" attributes and commands with value
		of ``0`` and named ``unspec``. This is supported (``type: unused``)
		but should be avoided in new families. The ``unspec`` enum values are
		not used in practice, so just set the value of the first attribute to ``1``.

		Message enums
		-------------

		Use the same command IDs for requests and replies. This makes it easier
		to match them up, and we have plenty of ID space.

		Use separate command IDs for notifications. This makes it easier to
		sort the notifications from replies (and present them to the user
		application via a different API than replies).

		Answer requests
		---------------

		Older families do not reply to all of the commands, especially NEW / ADD
		commands. User only gets information whether the operation succeeded or
		not via the ACK. Try to find useful data to return. Once the command is
		added whether it replies with a full message or only an ACK is uAPI and
		cannot be changed. It's better to err on the side of replying.

		Specifically NEW and ADD commands should reply with information identifying
		the created object such as the allocated object's ID (without having to
		resort to using ``NLM_F_ECHO``).

		NLM_F_ECHO
		----------

		Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
		to take effect. This is useful for programs that need precise feedback
		from the kernel (for example for logging purposes).

		Support dump consistency
		------------------------

		If iterating over objects during dump may skip over objects or repeat
		them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``.
		This is usually implemented by maintaining a generation id for the
		structure and recording it in the ``seq`` member of struct netlink_callback.

		Netlink specification
		=====================

		Documentation of the Netlink specification parts which are only relevant
		to the kernel space.

		Globals
		-------

		kernel-policy
		~~~~~~~~~~~~~

		Defines if the kernel validation policy is per operation (``per-op``)
		or for the entire family (``global``). New families should use ``per-op``
		(default) to be able to narrow down the attributes accepted by a specific
		command.

		checks
		------

		Documentation for the ``checks`` sub-sections of attribute specs.

		unterminated-ok
		~~~~~~~~~~~~~~~

		Accept strings without the null-termination (for legacy families only).
		Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type.

		max-len
		~~~~~~~

		Defines max length for a binary or string attribute (corresponding
		to the ``len`` member of struct nla_policy). For string attributes terminating
		null character is not counted towards ``max-len``.

		The field may either be a literal integer value or a name of a defined
		constant. String types may reduce the constant by one
		(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating
		character so implementations should recognize such pattern.

		min-len
		~~~~~~~

		Similar to ``max-len`` but defines minimum length.

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

File added.

Preview size limit exceeded, changes collapsed.

Documentation/netlink/genetlink.yaml

0 → 100644

+298 −0

File added.

Preview size limit exceeded, changes collapsed.