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

[Randy Dunlap]

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.

> +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