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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date: Fri, 5 May 2023 08:29:35 -0700
From: Jakub Kicinski <kuba@...nel.org>
To: Vadim Fedorenko <vadim.fedorenko@...ux.dev>
Cc: Vadim Fedorenko <vadfed@...a.com>, Jiri Pirko <jiri@...nulli.us>,
 Arkadiusz Kubalewski <arkadiusz.kubalewski@...el.com>, Jonathan Lemon
 <jonathan.lemon@...il.com>, Paolo Abeni <pabeni@...hat.com>, Milena Olech
 <milena.olech@...el.com>, Michal Michalik <michal.michalik@...el.com>,
 linux-arm-kernel@...ts.infradead.org, poros@...hat.com,
 mschmidt@...hat.com, netdev@...r.kernel.org, linux-clk@...r.kernel.org
Subject: Re: [RFC PATCH v7 3/8] dpll: documentation on DPLL subsystem
 interface

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.

> >> +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.