Re: [PATCH v6 1/6] PCI: endpoint: Define endpoint DMA BAR metadata format

[Koichiro Den]

On Tue, Aug 04, 2026 at 10:23:56AM -0500, Frank Li wrote:
> On Tue, Aug 04, 2026 at 12:38:50PM +0900, Koichiro Den wrote:
> > Define the BAR-resident metadata format used by endpoint functions that
> > expose an endpoint-integrated DMA controller to the host.
> >
> > A VSEC-based discovery scheme would be a natural fit, and existing
> > dw-edma-pcie providers such as Synopsys EDDA and AMD (Xilinx) MDB/CPM6
> > already use VSECs for DMA discovery. However, some endpoint controllers
> > cannot provide enough writable configuration-space storage for a
> > complete, controller-defined payload. Keep the extensible metadata in a
> > BAR instead, where the endpoint function controls the layout and size.
> >
> > The format describes the DMA register window, exported channel counts,
> > descriptor windows, optional auxiliary windows, endpoint-local descriptor
> > and auxiliary DMA addresses, and a ready bit that tells the host when the
> > described BAR windows are usable. Channel entries keep the auxiliary
> > window optional so layouts that need a separate data or auxiliary aperture
> > can describe it without a format bump.
> >
> > Signed-off-by: Koichiro Den <den@xxxxxxxxxxxxx>
> > ---
> > Changes in v6:
> >   - No changes.
> >
> >  MAINTAINERS                |   1 +
> >  include/linux/pci-ep-dma.h | 170 +++++++++++++++++++++++++++++++++++++
> >  2 files changed, 171 insertions(+)
> >  create mode 100644 include/linux/pci-ep-dma.h
> >
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 03febbc91a06..c503cf11b5a2 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -20933,6 +20933,7 @@ F:	Documentation/PCI/endpoint/*
> >  F:	Documentation/misc-devices/pci-endpoint-test.rst
> >  F:	drivers/misc/pci_endpoint_test.c
> >  F:	drivers/pci/endpoint/
> > +F:	include/linux/pci-ep-dma.h
> >  F:	tools/testing/selftests/pci_endpoint/
> >
> >  PCI ENHANCED ERROR HANDLING (EEH) FOR POWERPC
> > diff --git a/include/linux/pci-ep-dma.h b/include/linux/pci-ep-dma.h
> > new file mode 100644
> > index 000000000000..73f72455843c
> > --- /dev/null
> > +++ b/include/linux/pci-ep-dma.h
> > @@ -0,0 +1,170 @@
> > +/* SPDX-License-Identifier: GPL-2.0 */
> > +#ifndef __LINUX_PCI_EP_DMA_H
> > +#define __LINUX_PCI_EP_DMA_H
> > +
> > +#include <linux/bits.h>
> > +
> > +/*
> > + * BAR metadata format used by PCI endpoint functions that expose an
> > + * endpoint-integrated DMA controller to a PCI host.
> > + *
> > + * Offsets are relative to the beginning of the metadata blob. Multi-byte
> > + * fields are little-endian. The blob is normally placed at offset 0 of a
> > + * function BAR selected by the endpoint function and discovered by the host
> > + * driver using device-specific policy. Other data in the same BAR, such as a
> > + * standard MSI-X table or PBA, is outside this metadata format.
> > + *
> > + *          31                                                              0
> > + *          +---------------------------------------------------------------+
> > + * +0x000   | metadata magic                                                |
> > + *          +---------------------------------------------------------------+
> > + *          31                            16 15            8 7              0
> > + *          +-------------------------------+---------------+---------------+
> > + * +0x004   | metadata length               | reserved      | revision      |
> > + *          +-------------------------------+---------------+---------------+
> > + *          31 30 29     27 26          19 18          11 10           3 2  0
> > + *          +--+--+--------+--------------+--------------+--------------+---+
> > + * +0x008   |R |H |reserved| ch entry size| RD count     | WR count     |BAR|
> > + *          +--+--+--------+--------------+--------------+--------------+---+
> > + * +0x00c   | register window offset[31:0]                                  |
> > + *          +---------------------------------------------------------------+
> > + * +0x010   | register window offset[63:32]                                 |
> > + *          +---------------------------------------------------------------+
> > + *          31                            16 15            8 7              0
> > + *          +-------------------------------+---------------+---------------+
> > + * +0x014   | reserved                      | layout data   | layout        |
> > + *          +-------------------------------+---------------+---------------+
> > + * +0x018   | register window size                                          |
> > + *          +---------------------------------------------------------------+
> > + * +0x01c   | write table                                                   |
> > + *          | ( channel table entries #0 ~ #N )                             |
> > + *          +---------------------------------------------------------------+
> > + *          | read table                                                    |
> > + *          | ( channel table entries #0 ~ #N )                             |
> > + *          +---------------------------------------------------------------+
> > + *
> > + *          metadata magic: PCI_EP_DMA_METADATA_MAGIC.
> > + *          metadata length: byte size of the whole metadata blob. The value
> > + *                           must fit in PCI_EP_DMA_METADATA_HDR_LEN_FIELD and
> > + *                           in the BAR allocation that contains the metadata.
> > + *          revision: metadata format revision.
> > + *          R: ready bit. Set only by the endpoint after all fields and BAR
> > + *             windows described by this metadata have been programmed and can
> > + *             be used by the host. The host must not consume the windows
> > + *             before observing this bit.
> > + *          H: host-request bit. Set only by the host driver after it has found
> > + *             this metadata. The endpoint may use this as the trigger to
> > + *             program DMA window BAR subrange mappings, and may clear it while
> > + *             revoking R during teardown or reinitialization.
> 
> Is possible to put all H bit to sperate 32bit space to avoid
> Read-modify-write in case need sync with EP side although other bit is
> read only by host now.

That sounds reasonable. I'll respin it with the H bit in a spearate 32-bit word
and increase PCI_EP_DMA_METADATA_HDR_LEN to 0x20.

Thanks for the review,
Koichiro

> 
> Frank
> 
> > + *          ch entry size: byte stride between consecutive channel table
> > + *                         entries. Revision 1 requires at least
> > + *                         PCI_EP_DMA_METADATA_CH_ENTRY_SIZE bytes.
> > + *          RD count: number of exposed RC-to-endpoint DMA read channels and
> > + *                    read channel-table entries.
> > + *          WR count: number of exposed endpoint-to-RC DMA write channels and
> > + *                    write channel-table entries.
> > + *          BAR: BAR that contains the DMA controller register window.
> > + *          register window offset: BAR-local byte offset of the DMA controller
> > + *                                  register window in BAR.
> > + *          register window size: DMA controller register window size in bytes.
> > + *          layout: DMA controller register layout identifier.
> > + *          layout data: layout-specific data. For
> > + *                       PCI_EP_DMA_METADATA_REG_LAYOUT_DW_EDMA this is the
> > + *                       DesignWare eDMA/HDMA map format.
> > + *          write table: starts at PCI_EP_DMA_METADATA_HDR_LEN if write channel
> > + *                       count is non-zero.
> > + *          read table: starts at PCI_EP_DMA_METADATA_HDR_LEN plus the write
> > + *                      table size if read channel count is non-zero.
> > + *          reserved fields and bits: write zero and ignore on read.
> > + *
> > + *
> > + * Channel table entry:
> > + *
> > + *          31                 17 16 15 14   12 11 10     8 7                0
> > + *          +--------------------+--+--+-------+--+--------+----------------+
> > + * +0x000   | reserved           |A |rs|aux BAR|rs|desc BAR|hardware channel|
> > + *          +--------------------+--+--+-------+--+--------+----------------+
> > + * +0x004   | descriptor window BAR offset[31:0]                            |
> > + *          +---------------------------------------------------------------+
> > + * +0x008   | descriptor window BAR offset[63:32]                           |
> > + *          +---------------------------------------------------------------+
> > + * +0x00c   | descriptor window size                                        |
> > + *          +---------------------------------------------------------------+
> > + * +0x010   | descriptor DMA address[31:0]                                  |
> > + *          +---------------------------------------------------------------+
> > + * +0x014   | descriptor DMA address[63:32]                                 |
> > + *          +---------------------------------------------------------------+
> > + * +0x018   | auxiliary window BAR offset[31:0]                             |
> > + *          +---------------------------------------------------------------+
> > + * +0x01c   | auxiliary window BAR offset[63:32]                            |
> > + *          +---------------------------------------------------------------+
> > + * +0x020   | auxiliary window size                                         |
> > + *          +---------------------------------------------------------------+
> > + * +0x024   | auxiliary DMA address[31:0]                                   |
> > + *          +---------------------------------------------------------------+
> > + * +0x028   | auxiliary DMA address[63:32]                                  |
> > + *          +---------------------------------------------------------------+
> > + *
> > + *          A: auxiliary-window-valid bit. If clear, aux BAR and auxiliary
> > + *             window fields are ignored.
> > + *          aux BAR: BAR that contains the optional auxiliary window.
> > + *          desc BAR: BAR that contains the descriptor window.
> > + *          hardware channel: DMA controller's hardware channel number.
> > + *                            Revision 1 entries are currently consumed in dense
> > + *                            0-based order.
> > + *          descriptor window BAR offset: BAR-local byte offset of the
> > + *                                        descriptor window in desc BAR.
> > + *          descriptor window size: descriptor window size in bytes.
> > + *          descriptor DMA address: endpoint-local address used by the DMA
> > + *                                  controller to fetch descriptors.
> > + *          auxiliary window BAR offset: BAR-local byte offset of the auxiliary
> > + *                                       window in aux BAR.
> > + *          auxiliary window size: auxiliary window size in bytes.
> > + *          auxiliary DMA address: endpoint-local address corresponding to the
> > + *                                 auxiliary window.
> > + *          reserved fields and bits: write zero and ignore on read.
> > + */
> > +#define PCI_EP_DMA_METADATA_MAGIC		0x4d444550 /* "PEDM" */
> > +#define PCI_EP_DMA_METADATA_REV			0x1
> > +
> > +#define PCI_EP_DMA_METADATA_HDR_LEN		0x1c
> > +
> > +#define PCI_EP_DMA_METADATA_HDR			0x04
> > +#define  PCI_EP_DMA_METADATA_HDR_REV		GENMASK(7, 0)
> > +#define  PCI_EP_DMA_METADATA_HDR_LEN_FIELD	GENMASK(31, 16)
> > +
> > +#define PCI_EP_DMA_METADATA_CTRL		0x08
> > +#define  PCI_EP_DMA_METADATA_CTRL_REG_BAR	GENMASK(2, 0)
> > +#define  PCI_EP_DMA_METADATA_CTRL_WR_CH_COUNT	GENMASK(10, 3)
> > +#define  PCI_EP_DMA_METADATA_CTRL_RD_CH_COUNT	GENMASK(18, 11)
> > +#define  PCI_EP_DMA_METADATA_CTRL_CH_ENTRY_SIZE	GENMASK(26, 19)
> > +#define  PCI_EP_DMA_METADATA_CTRL_HOST_REQ	BIT(30)
> > +#define  PCI_EP_DMA_METADATA_CTRL_READY		BIT(31)
> > +
> > +#define PCI_EP_DMA_METADATA_REG_OFF_LO		0x0c
> > +#define PCI_EP_DMA_METADATA_REG_OFF_HI		0x10
> > +#define PCI_EP_DMA_METADATA_REG_LAYOUT		0x14
> > +#define  PCI_EP_DMA_METADATA_REG_LAYOUT_ID	GENMASK(7, 0)
> > +#define  PCI_EP_DMA_METADATA_REG_LAYOUT_DATA	GENMASK(15, 8)
> > +#define PCI_EP_DMA_METADATA_REG_SIZE		0x18
> > +
> > +#define PCI_EP_DMA_METADATA_REG_LAYOUT_DW_EDMA	0x1
> > +
> > +#define PCI_EP_DMA_METADATA_CH_ENTRY_SIZE	0x2c
> > +#define PCI_EP_DMA_METADATA_CH_CTRL		0x00
> > +#define  PCI_EP_DMA_METADATA_CH_CTRL_HW_CH	GENMASK(7, 0)
> > +#define  PCI_EP_DMA_METADATA_CH_CTRL_DESC_BAR	GENMASK(10, 8)
> > +#define  PCI_EP_DMA_METADATA_CH_CTRL_AUX_BAR	GENMASK(14, 12)
> > +#define  PCI_EP_DMA_METADATA_CH_CTRL_AUX_VALID	BIT(16)
> > +#define PCI_EP_DMA_METADATA_CH_DESC_OFF_LO	0x04
> > +#define PCI_EP_DMA_METADATA_CH_DESC_OFF_HI	0x08
> > +#define PCI_EP_DMA_METADATA_CH_DESC_SIZE	0x0c
> > +#define PCI_EP_DMA_METADATA_CH_DESC_ADDR_LO	0x10
> > +#define PCI_EP_DMA_METADATA_CH_DESC_ADDR_HI	0x14
> > +#define PCI_EP_DMA_METADATA_CH_AUX_OFF_LO	0x18
> > +#define PCI_EP_DMA_METADATA_CH_AUX_OFF_HI	0x1c
> > +#define PCI_EP_DMA_METADATA_CH_AUX_SIZE		0x20
> > +#define PCI_EP_DMA_METADATA_CH_AUX_ADDR_LO	0x24
> > +#define PCI_EP_DMA_METADATA_CH_AUX_ADDR_HI	0x28
> > +
> > +#endif /* __LINUX_PCI_EP_DMA_H */
> > --
> > 2.51.0
> >