| Message ID | 20231211164039.83034-7-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | tools/net/ynl: Add 'sub-message' support to ynl | expand |
On Mon, 11 Dec 2023 16:40:34 +0000 Donald Hunter wrote: > +Sub-messages > +------------ > + > +Several raw netlink families such as rt_link and tc have type-specific > +sub-messages. These sub-messages can appear as an attribute in a top-level or a > +nested attribute space. > + > +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: We may want to explain why we call this thing "sub-message". How about: Several raw netlink families such as rt_link and 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 of defining the format of the nest. In practice 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:
Jakub Kicinski <kuba@kernel.org> writes: > On Mon, 11 Dec 2023 16:40:34 +0000 Donald Hunter wrote: >> +Sub-messages >> +------------ >> + >> +Several raw netlink families such as rt_link and tc have type-specific >> +sub-messages. These sub-messages can appear as an attribute in a top-level or a >> +nested attribute space. >> + >> +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: > > We may want to explain why we call this thing "sub-message". How about: > > Several raw netlink families such as rt_link and 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 of defining the format of the nest. > In practice 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. I'll incorporate into next revision. Thanks! >> +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:
diff --git a/Documentation/userspace-api/netlink/netlink-raw.rst b/Documentation/userspace-api/netlink/netlink-raw.rst index f07fb9b9c101..e1d3e5ecfc6a 100644 --- a/Documentation/userspace-api/netlink/netlink-raw.rst +++ b/Documentation/userspace-api/netlink/netlink-raw.rst @@ -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,75 @@ group registration. - name: rtnlgrp-mctp-ifaddr value: 34 + +Sub-messages +------------ + +Several raw netlink families such as rt_link and tc have type-specific +sub-messages. These sub-messages can appear as an attribute in a top-level or a +nested attribute space. + +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.
Document the spec format used by netlink-raw families like rt and tc. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> --- .../userspace-api/netlink/netlink-raw.rst | 75 ++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-)