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@xxxxxxxxx > > - 10/03/2003 > > - Revised Feb 12, 2004 by Martine Silbermann > > - email: Martine.Silbermann@xxxxxx > > - Revised Jun 25, 2004 by Tom L Nguyen > > - Revised Jul 9, 2008 by Matthew Wilcox <willy@xxxxxxxxxxxxxxx> > > - 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@xxxxxxxxx> 10/03/2003 > > + - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@xxxxxx> > > + - Revised Jun 25, 2004 by Tom L Nguyen > > + - Revised Jul 9, 2008 by Matthew Wilcox <willy@xxxxxxxxxxxxxxx> > > + 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
