Merge branch 'tools-net-ynl-add-sub-message-support-to-ynl' (509afc74) · Commits · git / linux-net

Documentation/Makefile

+3 −3

Original line number	Diff line number	Diff line
		@@ -106,10 +106,10 @@ YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml))
		YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP))

		$(YNL_INDEX): $(YNL_RST_FILES)
		@$(YNL_TOOL) -o $@ -x
		$(Q)$(YNL_TOOL) -o $@ -x

		$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml
		@$(YNL_TOOL) -i $< -o $@
		$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL)
		$(Q)$(YNL_TOOL) -i $< -o $@

		htmldocs: $(YNL_INDEX)
		@$(srctree)/scripts/sphinx-pre-install --version-check

Documentation/netlink/netlink-raw.yaml

+62 −3

Original line number	Diff line number	Diff line
		@@ -126,8 +126,10 @@ properties:
		name:
		type: string
		type:
		description: The netlink attribute type
		enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ]
		description: \|
		The netlink attribute type. Members of type 'binary' or 'pad'
		must also have the 'len' property set.
		enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary, pad ]
		len:
		$ref: '#/$defs/len-or-define'
		byte-order:
		@@ -150,6 +152,14 @@ properties:
		the right formatting mechanism when displaying values of this
		type.
		enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
		if:
		properties:
		type:
		oneOf:
		- const: binary
		- const: pad
		then:
		required: [ len ]
		# End genetlink-legacy

		attribute-sets:
		@@ -202,7 +212,8 @@ properties:
		description: The netlink attribute type
		enum: [ unused, pad, flag, binary, bitfield32,
		u8, u16, u32, u64, s8, s16, s32, s64,
		string, nest, array-nest, nest-type-value ]
		string, nest, array-nest, nest-type-value,
		sub-message ]
		doc:
		description: Documentation of the attribute.
		type: string
		@@ -261,6 +272,17 @@ properties:
		description: Name of the struct type used for the attribute.
		type: string
		# End genetlink-legacy
		# Start netlink-raw
		sub-message:
		description: \|
		Name of the sub-message definition to use for the attribute.
		type: string
		selector:
		description: \|
		Name of the attribute to use for dynamic selection of sub-message
		format specifier.
		type: string
		# End netlink-raw

		# Make sure name-prefix does not appear in subsets (subsets inherit naming)
		dependencies:
		@@ -283,6 +305,43 @@ properties:
		items:
		required: [ type ]

		# Start netlink-raw
		sub-messages:
		description: Definition of sub message attributes
		type: array
		items:
		type: object
		additionalProperties: False
		required: [ name, formats ]
		properties:
		name:
		description: Name of the sub-message definition
		type: string
		formats:
		description: Dynamically selected format specifiers
		type: array
		items:
		type: object
		additionalProperties: False
		required: [ value ]
		properties:
		value:
		description: \|
		Value to match for dynamic selection of sub-message format
		specifier.
		type: string
		fixed-header:
		description: \|
		Name of the struct definition to use as the fixed header
		for the sub message.
		type: string
		attribute-set:
		description: \|
		Name of the attribute space from which to resolve attributes
		in the sub message.
		type: string
		# End netlink-raw

		operations:
		description: Operations supported by the protocol.
		type: object

Documentation/netlink/specs/rt_link.yaml

+438 −11

Original line number	Diff line number	Diff line
		@@ -66,8 +66,9 @@ definitions:
		name: ifi-family
		type: u8
		-
		name: padding
		type: u8
		name: pad
		type: pad
		len: 1
		-
		name: ifi-type
		type: u16
		@@ -82,6 +83,18 @@ definitions:
		-
		name: ifi-change
		type: u32
		-
		name: ifla-bridge-id
		type: struct
		members:
		-
		name: prio
		type: u16
		-
		name: addr
		type: binary
		len: 6
		display-hint: mac
		-
		name: ifla-cacheinfo
		type: struct
		@@ -707,11 +720,9 @@ definitions:
		name: family
		type: u8
		-
		name: pad1
		type: u8
		-
		name: pad2
		type: u16
		name: pad
		type: pad
		len: 3
		-
		name: ifindex
		type: u32
		@@ -966,8 +977,9 @@ attribute-sets:
		type: string
		-
		name: data
		type: binary
		# kind specific nest, e.g. linkinfo-bridge-attrs
		type: sub-message
		sub-message: linkinfo-data-msg
		selector: kind
		-
		name: xstats
		type: binary
		@@ -976,10 +988,12 @@ attribute-sets:
		type: string
		-
		name: slave-data
		type: binary
		# kind specific nest
		type: sub-message
		sub-message: linkinfo-member-data-msg
		selector: slave-kind
		-
		name: linkinfo-bridge-attrs
		name-prefix: ifla-br-
		attributes:
		-
		name: forward-delay
		@@ -1011,9 +1025,11 @@ attribute-sets:
		-
		name: root-id
		type: binary
		struct: ifla-bridge-id
		-
		name: bridge-id
		type: binary
		struct: ifla-bridge-id
		-
		name: root-port
		type: u16
		@@ -1041,6 +1057,7 @@ attribute-sets:
		-
		name: group-addr
		type: binary
		display-hint: mac
		-
		name: fdb-flush
		type: binary
		@@ -1123,6 +1140,376 @@ attribute-sets:
		-
		name: mcast-querier-state
		type: binary
		-
		name: linkinfo-brport-attrs
		name-prefix: ifla-brport-
		attributes:
		-
		name: state
		type: u8
		-
		name: priority
		type: u16
		-
		name: cost
		type: u32
		-
		name: mode
		type: flag
		-
		name: guard
		type: flag
		-
		name: protect
		type: flag
		-
		name: fast-leave
		type: flag
		-
		name: learning
		type: flag
		-
		name: unicast-flood
		type: flag
		-
		name: proxyarp
		type: flag
		-
		name: learning-sync
		type: flag
		-
		name: proxyarp-wifi
		type: flag
		-
		name: root-id
		type: binary
		struct: ifla-bridge-id
		-
		name: bridge-id
		type: binary
		struct: ifla-bridge-id
		-
		name: designated-port
		type: u16
		-
		name: designated-cost
		type: u16
		-
		name: id
		type: u16
		-
		name: "no"
		type: u16
		-
		name: topology-change-ack
		type: u8
		-
		name: config-pending
		type: u8
		-
		name: message-age-timer
		type: u64
		-
		name: forward-delay-timer
		type: u64
		-
		name: hold-timer
		type: u64
		-
		name: flush
		type: flag
		-
		name: multicast-router
		type: u8
		-
		name: pad
		type: pad
		-
		name: mcast-flood
		type: flag
		-
		name: mcast-to-ucast
		type: flag
		-
		name: vlan-tunnel
		type: flag
		-
		name: bcast-flood
		type: flag
		-
		name: group-fwd-mask
		type: u16
		-
		name: neigh-suppress
		type: flag
		-
		name: isolated
		type: flag
		-
		name: backup-port
		type: u32
		-
		name: mrp-ring-open
		type: flag
		-
		name: mrp-in-open
		type: flag
		-
		name: mcast-eht-hosts-limit
		type: u32
		-
		name: mcast-eht-hosts-cnt
		type: u32
		-
		name: locked
		type: flag
		-
		name: mab
		type: flag
		-
		name: mcast-n-groups
		type: u32
		-
		name: mcast-max-groups
		type: u32
		-
		name: neigh-vlan-suppress
		type: flag
		-
		name: backup-nhid
		type: u32
		-
		name: linkinfo-gre-attrs
		name-prefix: ifla-gre-
		attributes:
		-
		name: link
		type: u32
		-
		name: iflags
		type: u16
		-
		name: oflags
		type: u16
		-
		name: ikey
		type: u32
		-
		name: okey
		type: u32
		-
		name: local
		type: binary
		display-hint: ipv4
		-
		name: remote
		type: binary
		display-hint: ipv4
		-
		name: ttl
		type: u8
		-
		name: tos
		type: u8
		-
		name: pmtudisc
		type: u8
		-
		name: encap-limit
		type: u32
		-
		name: flowinfo
		type: u32
		-
		name: flags
		type: u32
		-
		name: encap-type
		type: u16
		-
		name: encap-flags
		type: u16
		-
		name: encap-sport
		type: u16
		-
		name: encap-dport
		type: u16
		-
		name: collect-metadata
		type: flag
		-
		name: ignore-df
		type: u8
		-
		name: fwmark
		type: u32
		-
		name: erspan-index
		type: u32
		-
		name: erspan-ver
		type: u8
		-
		name: erspan-dir
		type: u8
		-
		name: erspan-hwid
		type: u16
		-
		name: linkinfo-geneve-attrs
		name-prefix: ifla-geneve-
		attributes:
		-
		name: id
		type: u32
		-
		name: remote
		type: binary
		display-hint: ipv4
		-
		name: ttl
		type: u8
		-
		name: tos
		type: u8
		-
		name: port
		type: u16
		-
		name: collect-metadata
		type: flag
		-
		name: remote6
		type: binary
		display-hint: ipv6
		-
		name: udp-csum
		type: u8
		-
		name: udp-zero-csum6-tx
		type: u8
		-
		name: udp-zero-csum6-rx
		type: u8
		-
		name: label
		type: u32
		-
		name: ttl-inherit
		type: u8
		-
		name: df
		type: u8
		-
		name: inner-proto-inherit
		type: flag
		-
		name: linkinfo-iptun-attrs
		name-prefix: ifla-iptun-
		attributes:
		-
		name: link
		type: u32
		-
		name: local
		type: binary
		display-hint: ipv4
		-
		name: remote
		type: binary
		display-hint: ipv4
		-
		name: ttl
		type: u8
		-
		name: tos
		type: u8
		-
		name: encap-limit
		type: u8
		-
		name: flowinfo
		type: u32
		-
		name: flags
		type: u16
		-
		name: proto
		type: u8
		-
		name: pmtudisc
		type: u8
		-
		name: 6rd-prefix
		type: binary
		display-hint: ipv6
		-
		name: 6rd-relay-prefix
		type: binary
		display-hint: ipv4
		-
		name: 6rd-prefixlen
		type: u16
		-
		name: 6rd-relay-prefixlen
		type: u16
		-
		name: encap-type
		type: u16
		-
		name: encap-flags
		type: u16
		-
		name: encap-sport
		type: u16
		-
		name: encap-dport
		type: u16
		-
		name: collect-metadata
		type: flag
		-
		name: fwmark
		type: u32
		-
		name: linkinfo-tun-attrs
		name-prefix: ifla-tun-
		attributes:
		-
		name: owner
		type: u32
		-
		name: group
		type: u32
		-
		name: type
		type: u8
		-
		name: pi
		type: u8
		-
		name: vnet-hdr
		type: u8
		-
		name: persist
		type: u8
		-
		name: multi-queue
		type: u8
		-
		name: num-queues
		type: u32
		-
		name: num-disabled-queues
		type: u32
		-
		name: linkinfo-vrf-attrs
		name-prefix: ifla-vrf-
		attributes:
		-
		name: table
		type: u32
		-
		name: xdp-attrs
		attributes:
		@@ -1241,6 +1628,46 @@ attribute-sets:
		name: used
		type: u8

		sub-messages:
		-
		name: linkinfo-data-msg
		formats:
		-
		value: bridge
		attribute-set: linkinfo-bridge-attrs
		-
		value: erspan
		attribute-set: linkinfo-gre-attrs
		-
		value: gre
		attribute-set: linkinfo-gre-attrs
		-
		value: gretap
		attribute-set: linkinfo-gre-attrs
		-
		value: geneve
		attribute-set: linkinfo-geneve-attrs
		-
		value: ipip
		attribute-set: linkinfo-iptun-attrs
		-
		value: sit
		attribute-set: linkinfo-iptun-attrs
		-
		value: tun
		attribute-set: linkinfo-tun-attrs
		-
		value: vrf
		attribute-set: linkinfo-vrf-attrs
		-
		name: linkinfo-member-data-msg
		formats:
		-
		value: bridge
		attribute-set: linkinfo-brport-attrs
		-
		value: bond

		operations:
		enum-model: directional
		list:

Documentation/netlink/specs/tc.yaml

0 → 100644

+2031 −0

File added.

Preview size limit exceeded, changes collapsed.

Documentation/userspace-api/netlink/netlink-raw.rst

+95 −1

Original line number	Diff line number	Diff line
		@@ -14,7 +14,8 @@ Specification
		The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>`
		schema with properties that are needed to specify the protocol numbers and
		multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more
		information.
		information. The raw netlink families also make use of type-specific
		sub-messages.

		Globals
		-------
		@@ -56,3 +57,96 @@ group registration.
		-
		name: rtnlgrp-mctp-ifaddr
		value: 34

		Sub-messages
		------------

		Several raw netlink families such as
		:doc:`rt_link<../../networking/netlink_spec/rt_link>` and
		:doc:`tc<../../networking/netlink_spec/tc>` use attribute nesting as an
		abstraction to carry module specific information.

		Conceptually it looks as follows::

		[OUTER NEST OR MESSAGE LEVEL]
		[GENERIC ATTR 1]
		[GENERIC ATTR 2]
		[GENERIC ATTR 3]
		[GENERIC ATTR - wrapper]
		[MODULE SPECIFIC ATTR 1]
		[MODULE SPECIFIC ATTR 2]

		The ``GENERIC ATTRs`` at the outer level are defined in the core (or rt_link or
		core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their
		own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the
		example above shows attributes nesting inside the wrapper, the modules generally
		have full freedom to define the format of the nest. In practice the payload of
		the wrapper attr has very similar characteristics to a netlink message. It may
		contain a fixed header / structure, netlink attributes, or both. Because of
		those shared characteristics we refer to the payload of the wrapper attribute as
		a sub-message.

		A sub-message attribute uses the value of another attribute as a selector key to
		choose the right sub-message format. For example if the following attribute has
		already been decoded:

		.. code-block:: json

		{ "kind": "gre" }

		and we encounter the following attribute spec:

		.. code-block:: yaml

		-
		name: data
		type: sub-message
		sub-message: linkinfo-data-msg
		selector: kind

		Then we look for a sub-message definition called ``linkinfo-data-msg`` and use
		the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the
		correct format for the sub-message:

		.. code-block:: yaml

		sub-messages:
		name: linkinfo-data-msg
		formats:
		-
		value: bridge
		attribute-set: linkinfo-bridge-attrs
		-
		value: gre
		attribute-set: linkinfo-gre-attrs
		-
		value: geneve
		attribute-set: linkinfo-geneve-attrs

		This would decode the attribute value as a sub-message with the attribute-set
		called ``linkinfo-gre-attrs`` as the attribute space.

		A sub-message can have an optional ``fixed-header`` followed by zero or more
		attributes from an ``attribute-set``. For example the following
		``tc-options-msg`` sub-message defines message formats that use a mixture of
		``fixed-header``, ``attribute-set`` or both together:

		.. code-block:: yaml

		sub-messages:
		-
		name: tc-options-msg
		formats:
		-
		value: bfifo
		fixed-header: tc-fifo-qopt
		-
		value: cake
		attribute-set: tc-cake-attrs
		-
		value: netem
		fixed-header: tc-netem-qopt
		attribute-set: tc-netem-attrs

		Note that a selector attribute must appear in a netlink message before any
		sub-message attributes that depend on it.