linux-kernel - Re: [PATCH] PCI: Improve parameter docu for request APIs

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]

Message-ID: <5852280fa2764f9ca17f95f66541a945ad5b37ae.camel@redhat.com>
Date: Wed, 04 Dec 2024 10:39:35 +0100
From: Philipp Stanner <pstanner@...hat.com>
To: Bjorn Helgaas <helgaas@...nel.org>
Cc: Bjorn Helgaas <bhelgaas@...gle.com>, linux-pci@...r.kernel.org, 
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH] PCI: Improve parameter docu for request APIs

On Tue, 2024-12-03 at 15:37 -0600, Bjorn Helgaas wrote:
> On Tue, Dec 03, 2024 at 11:00:24AM +0100, Philipp Stanner wrote:
> > PCI region request functions have a @name parameter (sometimes
> > called
> > "res_name"). It is used in a log message to inform drivers about
> > request
> > collisions, i.e., when another driver has requested that region
> > already.
> > 
> > This message is only useful when it contains the actual owner of
> > the
> > region, i.e., which driver requested it. So far, a great many
> > drivers
> > misuse the @name parameter and just pass pci_name(), which doesn't
> > result in useful debug information.
> > 
> > Rename "res_name" to "name".
> > 
> > Detail @name's purpose in the docstrings.
> > 
> > Improve formatting a bit.
> > 
> > Signed-off-by: Philipp Stanner <pstanner@...hat.com>
> > ---
> >  drivers/pci/devres.c | 12 ++++----
> >  drivers/pci/pci.c    | 69 +++++++++++++++++++++-------------------
> > ----
> >  2 files changed, 39 insertions(+), 42 deletions(-)
> > 
> > diff --git a/drivers/pci/devres.c b/drivers/pci/devres.c
> > index 3b59a86a764b..ffaffa880b88 100644
> > --- a/drivers/pci/devres.c
> > +++ b/drivers/pci/devres.c
> > @@ -101,7 +101,7 @@ static inline void
> > pcim_addr_devres_clear(struct pcim_addr_devres *res)
> >   * @bar: BAR the range is within
> >   * @offset: offset from the BAR's start address
> >   * @maxlen: length in bytes, beginning at @offset
> > - * @name: name associated with the request
> > + * @name: name of the resource requestor
> 
> What if we say plainly:
> 
>   @name: name of driver requesting the resource
> 
> I can tweak this locally if you agree.
> 

Yup, sound like a good idea to me.

(nit: though I would say "name of the driver". But I'm also not a
native English speaker, so..)


P.