lkml.org 
[lkml]   [2019]   [Mar]   [31]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format
On Fri, Mar 29, 2019 at 09:00:09PM -0700, Matthew Wilcox wrote:
> On Sat, Mar 30, 2019 at 12:04:06AM +0800, Changbin Du wrote:
> > @@ -1,13 +1,18 @@
> > - The MSI Driver Guide HOWTO
> > - Tom L Nguyen tom.l.nguyen@intel.com
> > - 10/03/2003
> > - Revised Feb 12, 2004 by Martine Silbermann
> > - email: Martine.Silbermann@hp.com
> > - Revised Jun 25, 2004 by Tom L Nguyen
> > - Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> > - Copyright 2003, 2008 Intel Corporation
> > +.. SPDX-License-Identifier: GPL-2.0
> > +.. include:: <isonum.txt>
> > +
> > +==========================
> > +The MSI Driver Guide HOWTO
> > +==========================
> > +
> > +:Authors: - Tom L Nguyen <tom.l.nguyen@intel.com> 10/03/2003
> > + - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@hp.com>
> > + - Revised Jun 25, 2004 by Tom L Nguyen
> > + - Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> > + Copyright 2003, 2008 Intel Corporation
>
> The copyright line doesn't work quite the way it should in the rendered HTML.
>
> It seems to me it should be:
>
> :Copyright: 2003, 2008 Intel Corporation
>
> Tom has used an ambiguous date format; given it appeared in the tree
> in December 2003, I suspect he's used middle-endian format. It doesn't
> really seem relevant to have the dates here any more, so we could skip
> including them. Also, none of these email addresses work, so perhaps
> just drop those too.
>
> :Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
>
yeah, looks better. Thanks.

> > 1. About this guide
> > +===================
>
> Should we drop the numbering of sections as part of this conversion?
> I'd be inclined to.
>
yes, sphix can generate the numbering.

> > 4.2 Using MSI
> > +-------------
> >
> > Most of the hard work is done for the driver in the PCI layer. The driver
> > simply has to request that the PCI layer set up the MSI capability for this
> > device.
> >
> > To automatically use MSI or MSI-X interrupt vectors, use the following
> > -function:
> > +function::
> >
> > int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
> > unsigned int max_vecs, unsigned int flags);
>
> This should really be turned into kernel-doc and moved to pci.h, but
> that seems like an awfully large amount of work to ask you to do when
> you're already doing so much to improve the situation.
>
> This is also a really bad document. It has three audiences; people
> configuring their kernel, people writing device drivers and people trying
> to debug why their kernel doesn't work. Again, that's not on you to
> fix, but it's pretty frustrating to see so much good information so
> badly organised.
I agree. But content improvment is out of this topic. So I will just
do the conversion in this serias.

--
Cheers,
Changbin Du

\
 
 \ /
  Last update: 2019-03-31 07:19    [W:0.083 / U:0.192 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site