Re: [PATCH RFC 13/20] Documentation: ctlv: Describe how to write a family

[Jason Gunthorpe <jgg@nvidia.com>]

On Wed, Oct 21, 2026 at 04:23:17PM +0200, Jiri Pirko wrote:
> >> +    attr-sets:
> >> +      - name: item-request
> >> +        attrs: item.index
> >> +        optional-attrs:
> >> +          - item.label
> >> +          - item.data
> >> +      - name: item-reply
> >> +        attrs: item.index
> >> +        optional-attrs: item.label
> >> +      - name: items-reply
> >> +        optional-attrs: list.item
> >
> >I haven't quite figured out what attr-sets is about. I think these
> >blocks should have some # comments with more guidance what is going on.
> 
> "group" defines attrs with all the description once. "set" just puts
> together multiple atrrs from multiple groups. Will try to document it
> more clearly.

Maybe also include a explanation why it is like this, how it should be
used, etc.

> >> +
> >> +    ops:
> >> +      - name: item-set
> >> +        type: action
> >> +        optional: true
> >> +        request:
> >> +          attrs: item-request
> >> +      - name: items-dump
> >> +        type: query
> >> +        availability: dynamic
> >> +        pre-post: true
> >> +        reply:
> >> +          attrs: items-reply
> >> +        suggested-reply-length: 4096
> >> +      - name: item-changed
> >> +        type: event
> >> +        reply:
> >> +          attrs: item-reply
> >> +
> >> +An attribute has one payload form: ``type``, ``enum``, ``flags``, ``attrs``, or
> >> +``blob``. An attr set names one message level. ``attrs`` are required and
> >> +``optional-attrs`` are optional. Its bounds and membership are ABI.
> >
> >The attribute first point of view is maybe a little too netlinky, I
> >prefer to think of this as a system call first, with a first class
> >'query' to get a list of things
> >
> >Alot of stuff this is going to deal with won't be the netlink esque
> >'dump a table, set a table' kind of flow, but a bunch of different
> >system calls with arguments.
> 
> 
> Can you elaborate a bit more about this please? I'm not clear about what
> you mean by this. "'query' to get a list of things" sound cryptic to me.
> Are you talking about doc or about family yaml as well?

Just documentation. Netlink sort of evolved from a table row based API
concept into something more complete, but here we are starting more
from a systemcall concept that also has some first class tables too.

Maybe it just isn't clear what the original doc paragraph is trying to
say.

> >> +.. code-block:: c
> >> +
> >> +    int ctlv_example_vendor_details_extension_fill(
> >> +                            void *priv, struct ctlv_op_ctx *ctx,
> >> +                            const struct ctlv_cursor *request,
> >> +                            struct ctlv_cursor *nest)
> >> +    {
> >> +            ctlv_example_vendor_vendor_serial_put(nest,
> >> +                                                   example_serial(priv));
> >> +            return 0;
> >> +    }
> >
> >I suppose this like RDMA and each HW driver using this gets its own
> >full scheme tree that only has its own stuff in it?
> 
> It's the "family". Each child inheriting a subsystem family. It fills
> up the subsystem family defines stubs/extensions. It can add ops too.

I haven't got that far in the patches, but I think it would be good to
spend more time here explaining the fundamentals of how the extension
mechanism is expected to be used..

It looks like RDMA to me where you have some 'common' and some
'driver' parts but at this point in the docs it isn't clear how that
is reached. Like does each driver gets its own family? What is a
'family chain' etc Where is it reported?

> >What about userspace, it "knows" somehow what to do?
> 
> Userspace sees the family chain. It also has ability to do introspection
> seeing right away which op supports with attrs in which nests.

I was hoping the introspection would not be essential to use the
interface..

Jason