linux-kernel - Re: [PATCH v5 11/12] Documentation: PCI: convert endpoint/pci-test-function.txt to reST

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] [day] [month] [year] [list]

Message-ID: <20190514144451.uxa4bkipmltllv5k@mail.google.com>
Date:   Tue, 14 May 2019 22:44:53 +0800
From:   Changbin Du <changbin.du@...il.com>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
Cc:     Changbin Du <changbin.du@...il.com>, bhelgaas@...gle.com,
        corbet@....net, linux-pci@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v5 11/12] Documentation: PCI: convert
 endpoint/pci-test-function.txt to reST

On Mon, May 13, 2019 at 12:04:23PM -0300, Mauro Carvalho Chehab wrote:
> Em Mon, 13 May 2019 22:19:59 +0800
> Changbin Du <changbin.du@...il.com> escreveu:
> 
> > This converts the plain text documentation to reStructuredText format and
> > add it to Sphinx TOC tree. No essential content change.
> > 
> > Signed-off-by: Changbin Du <changbin.du@...il.com>
> > Acked-by: Bjorn Helgaas <bhelgaas@...gle.com>
> > ---
> >  Documentation/PCI/endpoint/index.rst          |  1 +
> >  ...est-function.txt => pci-test-function.rst} | 34 ++++++++++++-------
> >  2 files changed, 22 insertions(+), 13 deletions(-)
> >  rename Documentation/PCI/endpoint/{pci-test-function.txt => pci-test-function.rst} (84%)
> > 
> > diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
> > index 3951de9f923c..b680a3fc4fec 100644
> > --- a/Documentation/PCI/endpoint/index.rst
> > +++ b/Documentation/PCI/endpoint/index.rst
> > @@ -9,3 +9,4 @@ PCI Endpoint Framework
> >  
> >     pci-endpoint
> >     pci-endpoint-cfs
> > +   pci-test-function
> > diff --git a/Documentation/PCI/endpoint/pci-test-function.txt b/Documentation/PCI/endpoint/pci-test-function.rst
> > similarity index 84%
> > rename from Documentation/PCI/endpoint/pci-test-function.txt
> > rename to Documentation/PCI/endpoint/pci-test-function.rst
> > index 5916f1f592bb..63148df97232 100644
> > --- a/Documentation/PCI/endpoint/pci-test-function.txt
> > +++ b/Documentation/PCI/endpoint/pci-test-function.rst
> > @@ -1,5 +1,10 @@
> > -				PCI TEST
> > -		    Kishon Vijay Abraham I <kishon@...com>
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=================
> > +PCI Test Function
> > +=================
> > +
> > +:Author: Kishon Vijay Abraham I <kishon@...com>
> >  
> >  Traditionally PCI RC has always been validated by using standard
> >  PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
> > @@ -23,30 +28,31 @@ The PCI endpoint test device has the following registers:
> >  	8) PCI_ENDPOINT_TEST_IRQ_TYPE
> >  	9) PCI_ENDPOINT_TEST_IRQ_NUMBER
> >  
> > -*) PCI_ENDPOINT_TEST_MAGIC
> > +* PCI_ENDPOINT_TEST_MAGIC
> >  
> >  This register will be used to test BAR0. A known pattern will be written
> >  and read back from MAGIC register to verify BAR0.
> >  
> > -*) PCI_ENDPOINT_TEST_COMMAND:
> > +* PCI_ENDPOINT_TEST_COMMAND
> >  
> >  This register will be used by the host driver to indicate the function
> >  that the endpoint device must perform.
> >  
> > -Bitfield Description:
> > +Bitfield Description::
> > +
> >    Bit 0		: raise legacy IRQ
> >    Bit 1		: raise MSI IRQ
> >    Bit 2		: raise MSI-X IRQ
> >    Bit 3		: read command (read data from RC buffer)
> >    Bit 4		: write command (write data to RC buffer)
> > -  Bit 5		: copy command (copy data from one RC buffer to another
> > -		  RC buffer)
> > +  Bit 5		: copy command (copy data from one RC buffer to another RC buffer)
> 
> Why not use a table instead?
>
hmm, table looks better.
> >  
> > -*) PCI_ENDPOINT_TEST_STATUS
> > +* PCI_ENDPOINT_TEST_STATUS
> >  
> >  This register reflects the status of the PCI endpoint device.
> >  
> > -Bitfield Description:
> > +Bitfield Description::
> > +
> >    Bit 0		: read success
> >    Bit 1		: read fail
> >    Bit 2		: write success
> > @@ -57,31 +63,33 @@ Bitfield Description:
> >    Bit 7		: source address is invalid
> >    Bit 8		: destination address is invalid
> 
> Same here.
> 
> If you replace the two bitfield descriptions to table:
> 	Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
> 
sure.

> >  
> > -*) PCI_ENDPOINT_TEST_SRC_ADDR
> > +* PCI_ENDPOINT_TEST_SRC_ADDR
> >  
> >  This register contains the source address (RC buffer address) for the
> >  COPY/READ command.
> >  
> > -*) PCI_ENDPOINT_TEST_DST_ADDR
> > +* PCI_ENDPOINT_TEST_DST_ADDR
> >  
> >  This register contains the destination address (RC buffer address) for
> >  the COPY/WRITE command.
> >  
> > -*) PCI_ENDPOINT_TEST_IRQ_TYPE
> > +* PCI_ENDPOINT_TEST_IRQ_TYPE
> >  
> >  This register contains the interrupt type (Legacy/MSI) triggered
> >  for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
> >  
> >  Possible types:
> > +
> >   - Legacy	: 0
> >   - MSI		: 1
> >   - MSI-X	: 2
> >
Also take this as table.

> > -*) PCI_ENDPOINT_TEST_IRQ_NUMBER
> > +* PCI_ENDPOINT_TEST_IRQ_NUMBER
> >  
> >  This register contains the triggered ID interrupt.
> >  
> >  Admissible values:
> > +
> >   - Legacy	: 0
> >   - MSI		: [1 .. 32]
> >   - MSI-X	: [1 .. 2048]
> 
> 
> 
> Thanks,
> Mauro

-- 
Cheers,
Changbin Du