From: Koichiro Den <den@valinux.co.jp>
To: "Jingoo Han" <jingoohan1@gmail.com>,
"Manivannan Sadhasivam" <mani@kernel.org>,
"Lorenzo Pieralisi" <lpieralisi@kernel.org>,
"Krzysztof Wilczyński" <kwilczynski@kernel.org>,
"Rob Herring" <robh@kernel.org>,
"Bjorn Helgaas" <bhelgaas@google.com>,
"Kishon Vijay Abraham I" <kishon@kernel.org>,
"Frank Li" <Frank.Li@kernel.org>
Cc: Marek Vasut <marek.vasut+renesas@mailbox.org>,
Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>,
linux-kernel@vger.kernel.org, linux-pci@vger.kernel.org
Subject: [PATCH v5 1/6] PCI: endpoint: Define endpoint DMA BAR metadata format
Date: Fri, 17 Jul 2026 14:06:30 +0900 [thread overview]
Message-ID: <20260717050635.2145014-2-den@valinux.co.jp> (raw)
In-Reply-To: <20260717050635.2145014-1-den@valinux.co.jp>
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@valinux.co.jp>
---
Changes in v5:
- 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 3af0fe95a92f..f2f5a42c6115 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20846,6 +20846,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.
+ * 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
next prev parent reply other threads:[~2026-07-17 5:06 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-07-17 5:06 [PATCH v5 0/6] PCI: endpoint: Expose endpoint DMA resources (part 2/3) Koichiro Den
2026-07-17 5:06 ` Koichiro Den [this message]
2026-07-17 5:06 ` [PATCH v5 2/6] PCI: endpoint: Add DMA auxiliary resource metadata Koichiro Den
2026-07-17 5:06 ` [PATCH v5 3/6] PCI: endpoint: Add API to delegate EPC DMA channels to the host Koichiro Den
2026-07-17 5:06 ` [PATCH v5 4/6] PCI: dwc: Expose endpoint DMA resources Koichiro Den
2026-07-17 5:06 ` [PATCH v5 5/6] dmaengine: dw-edma: Add delegated channel request helpers Koichiro Den
2026-07-17 5:06 ` [PATCH v5 6/6] PCI: dwc: Implement endpoint DMA channel delegation Koichiro Den
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20260717050635.2145014-2-den@valinux.co.jp \
--to=den@valinux.co.jp \
--cc=Frank.Li@kernel.org \
--cc=bhelgaas@google.com \
--cc=jingoohan1@gmail.com \
--cc=kishon@kernel.org \
--cc=kwilczynski@kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-pci@vger.kernel.org \
--cc=lpieralisi@kernel.org \
--cc=mani@kernel.org \
--cc=marek.vasut+renesas@mailbox.org \
--cc=robh@kernel.org \
--cc=yoshihiro.shimoda.uh@renesas.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®