[RFC PATCH v7 3/8] dpll: documentation on DPLL subsystem interface

[Kubalewski, Arkadiusz]

>From: Jakub Kicinski <kuba at kernel.org>
>Sent: Friday, May 5, 2023 5:30 PM
>
>On Fri, 5 May 2023 14:16:53 +0100 Vadim Fedorenko wrote:
>> >> +Then there are two groups of configuration knobs:
>> >> +1) Set on a pin - the configuration affects all dpll devices pin is
>> >> +   registered to. (i.e. ``PIN_FREQUENCY``, ``PIN_DIRECTION``),
>> >
>> > Why is direction set on a pin? We can't chain DPLLs?
>>
>> We can chain DPLLs using pins only. We don't have any interface to
>> configure 2 pins to connect 2 different DPLLs to each other at the same
>> time. The configuration should take care of one pin being input and
>> other one being output. That's why we have direction property attached
>> to the pin, not the DPLL itself.
>
>Makes sense.

Hmmm, actually we already can register the same pin with 2 dplls, and it could
identify itself as an input for one dpll and as an output for the other. It
makes sense as change on one pin would again inform both dplls.

The dpll_pin_direction_get/set callbacks are already called with dpll, so
we are good, only one change would be needed is to move PIN_DIRECTION to the
pin-dpll configuration tuples on `pin-get`.

Thus, actually it looks like a bug now:
- pin-dpll tuple may report different direction for each dpll pin was
registered with
- userspace see this as pin specific property, but it would return different
values depending on which dpll was given as arg for pin-get command.

I will fix it, as it relates to the modifying spec in first place.

>
>> >> +Device driver implementation
>> >> +============================
>> >> +
>> >> +Device is allocated by ``dpll_device_get`` call. Second call with the
>> >> +same arguments doesn't create new object but provides pointer to
>> >> +previously created device for given arguments, it also increase refcount
>> >> +of that object.
>> >> +Device is deallocated by ``dpll_device_put`` call, which first decreases
>> >> +the refcount, once refcount is cleared the object is destroyed.
>> >
>> > You can add () after the function name and render the kdoc at the end
>> > of this doc. The `` marking will then be unnecessary.
>> >
>> Mmm... any examples of such a way of creating documentation? I was
>> following tls*.rst style, but without copying code-blocks.
>
>net_dim.rst, maybe?  driver.rst ? Feel free to ping me 1:1 if you're
>struggling, it should be fairly straightforward.