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

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Low] docs: Incorrect function ctlv_op_emit() in ctlv.rst example
- [Low] docs: Incorrect generated family descriptor name in ctlv.rst example
--

commit 44307a0d2c96bec6fed10bf4f0610aa2e3baf41c
Author: Jiri Pirko <jiri@resnulli.us>

Documentation: ctlv: Describe how to write a family

Describe the YAML language, generated family descriptors, lifecycle,
operations, events, blobs, inheritance and compatible extension rules.

> diff --git a/Documentation/driver-api/ctlv.rst b/Documentation/driver-api/ctlv.rst
> new file mode 100644
> index 0000000000000..461e2977a4839
> --- /dev/null
> +++ b/Documentation/driver-api/ctlv.rst

[ ... ]

> +    struct ctlv_example_vendor_init_info info = {
> +            .dev = dev,
> +    };
> +    struct ctlv_device *ctlvdev;
> +
> +    ctlvdev = ctlv_create(dev, &ctlv_example_vendor_ctlv_family, &info);

[Severity: Low]
Does this code use the correct generated family descriptor name? Based on the
YAML family name ctlv-example-vendor, the expected generated C struct name
would be ctlv_example_vendor_family. It seems the _ctlv part is improperly
inserted here.

> +    if (IS_ERR(ctlvdev))

[ ... ]

> +    if (IS_ERR(ctx)) {
> +            if (PTR_ERR(ctx) == -ENOMEM)
> +                    ctlv_event_lost(ctlvdev,
> +                                    CTLV_EXAMPLE_OP_THING_HAPPENED);
> +            return;
> +    }
> +    ctlv_example_generation_put(event, priv->generation);
> +    ctlv_op_emit(ctx);

[Severity: Low]
Is ctlv_op_emit() the correct API call here? Earlier in the documentation,
event emission is shown using ctlv_event_emit(). Using an incorrect API
name here could lead to compile-time errors for driver authors attempting to
follow the guide.

> +
> +ctlv_event_lost() allocates nothing and does not sleep. For each subscribed
> +file description it advances the event sequence and aggregates the loss into
> +the preallocated EVENT_OVERFLOW record. The caller keeps the device alive
> +and serializes the report with normal emission of that event. Like event
> +emission, it is not called from interrupt context. It is only for an event that
> +actually occurred but could not be constructed: do not call it for an aborted
> +event or for copy-allocation and full-queue drops already accounted for by
> +ctlv_op_emit(). Reports after event shutdown or the terminal

[Severity: Low]
Should this text reference ctlv_event_emit() instead of the non-existent
ctlv_op_emit() function?

> +DEVICE_REMOVED record are ignored.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261015145053.3664509-1-jiri@resnulli.us?part=13