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

[Frank Li]

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.

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
>