| Message ID | 20230815194254.89570-3-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | tools/net/ynl: Add support for netlink-raw families | expand |
| Context | Check | Description |
|---|---|---|
| netdev/tree_selection | success | Clearly marked for net-next |
| netdev/apply | fail | Patch does not apply to net-next |
On Tue, 15 Aug 2023 20:42:46 +0100 Donald Hunter wrote: > Add description of genetlink-legacy specific attributes to the ynl spec > documentation. > > Signed-off-by: Donald Hunter <donald.hunter@gmail.com> > --- > Documentation/userspace-api/netlink/specs.rst | 47 +++++++++++++++++++ > 1 file changed, 47 insertions(+) Should we merge this with genetlink-legacy.rst? > diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst > index 2e4acde890b7..dde70f9674d4 100644 > --- a/Documentation/userspace-api/netlink/specs.rst > +++ b/Documentation/userspace-api/netlink/specs.rst > @@ -443,3 +443,50 @@ nest > > Attribute containing other (nested) attributes. > ``nested-attributes`` specifies which attribute set is used inside. > + > +genetlink-legacy > +================ > + > +The genetlink-legacy schema extends the genetlink schema with some additional > +properties that are needed to support legacy genetlink families. > + > +Globals > +------- > + > + - ``kernel-policy`` - Specify whether the kernel input policy is ``global``, > + ``per-op`` or ``split``. Maybe a few more words: Specify whether the kernel input policy is ``global`` i.e. the same for all operation of the family, defined for each operation individually (``per-op``), or separately for each operation and operation type (do vs dump) - ``split``. > + ``per-op`` or ``split``. > +Struct definitions > +------------------ > + > +There is a new type of definition called ``struct`` which is used for declaring > +the C struct format of fixed headers and binary attributes. > + > +members > +~~~~~~~ > + > + - ``name`` - The attribute name of the struct member > + - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, > + ``s16``, ``s32``, ``s64``, ``string`` or ``binary``. > + - ``byte-order`` - ``big-endian`` or ``little-endian`` > + - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for > + attribute definitions. Hm, genetlink-legacy.rst has this: https://docs.kernel.org/next/userspace-api/netlink/genetlink-legacy.html#structures But the larger section is called "Other quirks (todo)" I guess you have tackled most of the items in this section so we shouldn't call it "todo" ?
Jakub Kicinski <kuba@kernel.org> writes: > On Tue, 15 Aug 2023 20:42:46 +0100 Donald Hunter wrote: >> Add description of genetlink-legacy specific attributes to the ynl spec >> documentation. >> >> Signed-off-by: Donald Hunter <donald.hunter@gmail.com> >> --- >> Documentation/userspace-api/netlink/specs.rst | 47 +++++++++++++++++++ >> 1 file changed, 47 insertions(+) > > Should we merge this with genetlink-legacy.rst? Sure, I can do that. > >> diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst >> index 2e4acde890b7..dde70f9674d4 100644 >> --- a/Documentation/userspace-api/netlink/specs.rst >> +++ b/Documentation/userspace-api/netlink/specs.rst >> @@ -443,3 +443,50 @@ nest >> >> Attribute containing other (nested) attributes. >> ``nested-attributes`` specifies which attribute set is used inside. >> + >> +genetlink-legacy >> +================ >> + >> +The genetlink-legacy schema extends the genetlink schema with some additional >> +properties that are needed to support legacy genetlink families. >> + >> +Globals >> +------- >> + >> + - ``kernel-policy`` - Specify whether the kernel input policy is ``global``, >> + ``per-op`` or ``split``. > > Maybe a few more words: > > Specify whether the kernel input policy is ``global`` i.e. the same for > all operation of the family, defined for each operation individually > (``per-op``), or separately for each operation and operation type > (do vs dump) - ``split``. Ack. As an aside, what do we mean by "kernel input policy"? >> + ``per-op`` or ``split``. > >> +Struct definitions >> +------------------ >> + >> +There is a new type of definition called ``struct`` which is used for declaring >> +the C struct format of fixed headers and binary attributes. >> + >> +members >> +~~~~~~~ >> + >> + - ``name`` - The attribute name of the struct member >> + - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, >> + ``s16``, ``s32``, ``s64``, ``string`` or ``binary``. >> + - ``byte-order`` - ``big-endian`` or ``little-endian`` >> + - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for >> + attribute definitions. > > Hm, genetlink-legacy.rst has this: > > https://docs.kernel.org/next/userspace-api/netlink/genetlink-legacy.html#structures > > But the larger section is called "Other quirks (todo)" > I guess you have tackled most of the items in this section > so we shouldn't call it "todo" ? I'll clean up genetlink-legacy.rst when I merge these changes. Thanks for the review!
Donald Hunter <donald.hunter@gmail.com> writes: > Jakub Kicinski <kuba@kernel.org> writes: > >> On Tue, 15 Aug 2023 20:42:46 +0100 Donald Hunter wrote: >>> + >>> +Globals >>> +------- >>> + >>> + - ``kernel-policy`` - Specify whether the kernel input policy is ``global``, >>> + ``per-op`` or ``split``. >> >> Maybe a few more words: >> >> Specify whether the kernel input policy is ``global`` i.e. the same for >> all operation of the family, defined for each operation individually >> (``per-op``), or separately for each operation and operation type >> (do vs dump) - ``split``. > > Ack. As an aside, what do we mean by "kernel input policy"? So I've just spotted that kernel-policy is already documented in core-api/netlink.rst and I guess I shouldn't be documenting it in the userspace-api at all? I could add a reference to the core-api docs so that it's easier to find the kernel side docs when reading the userspace-api?
On Wed, 16 Aug 2023 14:16:33 +0100 Donald Hunter wrote: > > Ack. As an aside, what do we mean by "kernel input policy"? > > So I've just spotted that kernel-policy is already documented in > core-api/netlink.rst and I guess I shouldn't be documenting it in the > userspace-api at all? I could add a reference to the core-api docs so > that it's easier to find the kernel side docs when reading the > userspace-api? Ah, yes, reference sounds good. But we should also add split to the doc, I only see ``global`` and ``per-op`` described?
diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst index 2e4acde890b7..dde70f9674d4 100644 --- a/Documentation/userspace-api/netlink/specs.rst +++ b/Documentation/userspace-api/netlink/specs.rst @@ -443,3 +443,50 @@ nest Attribute containing other (nested) attributes. ``nested-attributes`` specifies which attribute set is used inside. + +genetlink-legacy +================ + +The genetlink-legacy schema extends the genetlink schema with some additional +properties that are needed to support legacy genetlink families. + +Globals +------- + + - ``kernel-policy`` - Specify whether the kernel input policy is ``global``, + ``per-op`` or ``split``. + +Struct definitions +------------------ + +There is a new type of definition called ``struct`` which is used for declaring +the C struct format of fixed headers and binary attributes. + +members +~~~~~~~ + + - ``name`` - The attribute name of the struct member + - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, + ``s16``, ``s32``, ``s64``, ``string`` or ``binary``. + - ``byte-order`` - ``big-endian`` or ``little-endian`` + - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for + attribute definitions. + +Attributes +---------- + +The genetlink-legacy families can use binary attributes that contain C struct +data. This is specified using a ``struct`` property containing the name of the +struct definition. + + - ``struct`` - Name of the struct definition to be used for the attribute. + +Operations +---------- + +The genetlink-legacy families can use a binary fixed header that contains C +struct data. + + - ``fixed-header`` - name of the struct definition to be used for the fixed + header data. This can be specified as a default for all operations and on a + per-operation basis.
Add description of genetlink-legacy specific attributes to the ynl spec documentation. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> --- Documentation/userspace-api/netlink/specs.rst | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+)