Re: [PATCH v2 3/3] Documentation: PCI: Add PCI DMA endpoint function documentation

[Koichiro Den]

On Mon, May 25, 2026 at 11:05:05AM -0700, Randy Dunlap wrote:
> Hi,
> 
> On 5/24/26 11:34 PM, Koichiro Den wrote:
> > Add a function description and a user guide for pci-epf-dma. Describe
> > the BAR-resident metadata consumed by dw-edma-pcie, the configfs
> > attributes, endpoint controller requirements and the host-side DMAengine
> > usage model.
> > 
> > Signed-off-by: Koichiro Den <den@xxxxxxxxxxxxx>
> > ---
> >  Documentation/PCI/endpoint/index.rst          |   2 +
> >  .../PCI/endpoint/pci-dma-function.rst         | 182 ++++++++++++++++
> >  Documentation/PCI/endpoint/pci-dma-howto.rst  | 200 ++++++++++++++++++
> >  3 files changed, 384 insertions(+)
> >  create mode 100644 Documentation/PCI/endpoint/pci-dma-function.rst
> >  create mode 100644 Documentation/PCI/endpoint/pci-dma-howto.rst
> 
> 
> > diff --git a/Documentation/PCI/endpoint/pci-dma-function.rst b/Documentation/PCI/endpoint/pci-dma-function.rst
> > new file mode 100644
> > index 000000000000..54caf4fafe00
> > --- /dev/null
> > +++ b/Documentation/PCI/endpoint/pci-dma-function.rst
> > @@ -0,0 +1,182 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +================
> > +PCI DMA Function
> > +================
> > +
> > +:Author: Koichiro Den <den@xxxxxxxxxxxxx>
> > +
> > +The PCI DMA endpoint function exposes an endpoint-integrated DMA controller
> > +to the PCI host as a PCI DMA controller.  A matching host-side driver
> > +discovers the endpoint DMA metadata and registers the delegated channels with
> > +the Linux DMAengine framework, so host DMAengine clients can submit
> > +transfers.
> > +
> > +An endpoint Linux system can already use an endpoint-integrated DMA
> > +controller locally through the normal DMAengine API, for example to transfer
> > +data between endpoint memory and host addresses reachable over PCI.  The PCI
> > +DMA function provides a different ownership model: it delegates selected
> > +local DMA channels to the host, so a host DMAengine client can request and
> > +program those endpoint-side channels through the host's DMAengine API.
> > +
> > +To make that possible, the endpoint function publishes the DMA controller
> > +register window and descriptor memory layout to the host, reserves the
> > +selected local DMA channels on the endpoint side, and lets the host program
> > +those channels directly.
> > +
> > +Constructs Used for Implementing DMA
> > +====================================
> > +
> > +The PCI DMA function uses the following endpoint-side resources and
> > +configuration:
> > +
> > +	1) DMA controller register window
> > +	2) DMA descriptor memory for endpoint-to-RC channels
> > +	3) DMA descriptor memory for RC-to-endpoint channels
> > +	4) MSI or MSI-X interrupt vectors selected through configfs
> > +	5) One endpoint BAR used to publish metadata
> > +	6) If needed, one endpoint BAR used for dynamically mapped DMA windows
> > +
> > +The endpoint controller reports the DMA controller register and descriptor
> > +resources through the endpoint auxiliary resource interface.  The PCI DMA
> > +function uses those descriptions to build the host-visible metadata and to map
> > +resources that are not already visible to the host.
> > +
> 
> Most of the headings/titles in these 2 documentation files don't use ':' at the
> end of the headings. I suppose that we don't have any explicit docs guidelines
> for that[*], but these (below) stand out as unusual to me (mostly due to the overall
> inconsistency but also because headings just don't typically end with a colon
> IME.

Hi Randy,

Thanks for the review.
I had pci-ntb-function.rst open side by side while writing this up, to keep the
style consistent among Documentation/PCI/endpoint/pci-*-function.rst files.

If the direction of this series looks acceptable and I end up respinnning the
series, I will add a cleanup patch for the existing pci-*-function.rst files and
follow your suggestion there as well.

Best regards,
Koichiro

> 
> > +DMA Controller Register Window:
> > +-------------------------------
> > +
> > +It contains the DMA controller registers programmed by the host-side driver
> > +to submit transfers, control channels and handle DMA interrupts.
> > +
> > +DMA Descriptor Memory:
> > +----------------------
> > +
> > +It contains the descriptor memory used by the DMA controller.  The PCI DMA
> > +function exposes descriptor memory for the delegated endpoint-to-RC and
> > +RC-to-endpoint channels.
> > +
> > +MSI/MSI-X Interrupt Vectors:
> > +----------------------------
> > +
> > +They are used by the delegated DMA channels to signal completion and error
> > +conditions to the host-side driver.
> > +
> > +Metadata BAR:
> > +-------------
> > +
> > +It is the endpoint BAR used to publish the endpoint DMA metadata and handshake
> > +bits.  The BAR remains stable while the endpoint function programs the DMA
> > +windows.
> > +
> > +DMA Window BAR:
> > +---------------
> > +
> > +It is the endpoint BAR used for DMA resources that are not already visible
> > +through a fixed BAR.  The endpoint function may switch this BAR to subrange
> > +mapping after the host-side driver has found the metadata BAR.
> 
> *: other than Documentation/doc-guide/sphinx.rst, where heading styles are listed
>    without colons.
> 
> -- 
> ~Randy
>