[PATCH RFC 02/13] dmaengine: sdxi: Add control structure definitions

[Nathan Lynch via B4 Relay <devnull+nathan.lynch.amd.com@kernel.org>]

From: Nathan Lynch <nathan.lynch@amd.com>

SDXI defines a multitude of control structures that reside in system
memory and are shared between software and the implementation.

Add:

* C struct definitions for the SDXI control structures to be used by
  the driver;
* Bitmask constants for accessing fields and subfields of the control
  structures;
* Symbolic constants corresponding to significant values such as
  context states and commands.

Co-developed-by: Wei Huang <wei.huang2@amd.com>
Signed-off-by: Wei Huang <wei.huang2@amd.com>
Signed-off-by: Nathan Lynch <nathan.lynch@amd.com>
---
 drivers/dma/sdxi/hw.h | 249 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 249 insertions(+)

diff --git a/drivers/dma/sdxi/hw.h b/drivers/dma/sdxi/hw.h
new file mode 100644
index 0000000000000000000000000000000000000000..4ac0e200773b0646e84a65794e02cdf9e583db6d
--- /dev/null
+++ b/drivers/dma/sdxi/hw.h
@@ -0,0 +1,249 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/* Copyright (C) 2025 Advanced Micro Devices, Inc. */
+
+/*
+ * Control structures and constants defined in the SDXI specification,
+ * with low-level accessors. The ordering of the structures here
+ * follows the order of their definitions in the SDXI spec.
+ *
+ * Names of structures, members, and subfields (bit ranges within
+ * members) are written to match the spec, generally. E.g. struct
+ * sdxi_cxt_l2_ent corresponds to CXT_L2_ENT in the spec.
+ *
+ * Note: a member can have a subfield whose name is identical to the
+ * member's name. E.g. CXT_L2_ENT's lv01_ptr.
+ *
+ * All reserved fields and bits (usually named "rsvd" or some
+ * variation) must be set to zero by the driver unless otherwise
+ * specified.
+ */
+
+#ifndef LINUX_SDXI_HW_H
+#define LINUX_SDXI_HW_H
+
+#include <asm/byteorder.h>
+#include <linux/bitfield.h>
+#include <linux/bits.h>
+#include <linux/build_bug.h>
+#include <linux/log2.h>
+#include <linux/stddef.h>
+#include <linux/types.h>
+
+/* Context Level 2 Table Entry (CXT_L2_ENT) */
+struct sdxi_cxt_l2_ent {
+	__le64 lv01_ptr;
+#define SDXI_CXT_L2_ENT_LV01_PTR GENMASK_ULL(63, 12)
+#define SDXI_CXT_L2_ENT_VL       BIT_ULL(0)
+} __packed;
+static_assert(sizeof(struct sdxi_cxt_l2_ent) == 8);
+
+/*
+ * The level 2 table is 4KB and has 512 level 1 pointer entries.
+ */
+#define SDXI_L2_TABLE_ENTRIES 512
+struct sdxi_cxt_l2_table {
+	struct sdxi_cxt_l2_ent entry[SDXI_L2_TABLE_ENTRIES];
+};
+static_assert(sizeof(struct sdxi_cxt_l2_table) == 4096);
+
+/* Context level 1 table entry (CXT_L1_ENT) */
+struct sdxi_cxt_l1_ent {
+	__le64 cxt_ctl_ptr;
+#define SDXI_CXT_L1_ENT_VL             BIT_ULL(0)
+#define SDXI_CXT_L1_ENT_KA             BIT_ULL(1)
+#define SDXI_CXT_L1_ENT_PV             BIT_ULL(2)
+#define SDXI_CXT_L1_ENT_CXT_CTL_PTR    GENMASK_ULL(63, 6)
+	__le64 akey_ptr;
+#define SDXI_CXT_L1_ENT_AKEY_SZ        GENMASK_ULL(3, 0)
+#define SDXI_CXT_L1_ENT_AKEY_PTR       GENMASK_ULL(63, 12)
+	__le32 misc0;
+#define SDXI_CXT_L1_ENT_PASID          GENMASK(19, 0)
+#define SDXI_CXT_L1_ENT_MAX_BUFFER     GENMASK(23, 20)
+	__le32 opb_000_enb;
+	__u8 rsvd_0[8];
+} __packed;
+static_assert(sizeof(struct sdxi_cxt_l1_ent) == 32);
+
+#define SDXI_L1_TABLE_ENTRIES 128
+struct sdxi_cxt_l1_table {
+	struct sdxi_cxt_l1_ent entry[SDXI_L1_TABLE_ENTRIES];
+};
+static_assert(sizeof(struct sdxi_cxt_l1_table) == 4096);
+
+/* Context control block (CXT_CTL) */
+struct sdxi_cxt_ctl {
+	__le64 ds_ring_ptr;
+#define SDXI_CXT_CTL_VL             BIT_ULL(0)
+#define SDXI_CXT_CTL_QOS            GENMASK_ULL(3, 2)
+#define SDXI_CXT_CTL_SE             BIT_ULL(4)
+#define SDXI_CXT_CTL_CSA            BIT_ULL(5)
+#define SDXI_CXT_CTL_DS_RING_PTR    GENMASK_ULL(63, 6)
+	__le32 ds_ring_sz;
+	__u8 rsvd_0[4];
+	__le64 cxt_sts_ptr;
+#define SDXI_CXT_CTL_CXT_STS_PTR    GENMASK_ULL(63, 4)
+	__le64 write_index_ptr;
+#define SDXI_CXT_CTL_WRITE_INDEX_PTR GENMASK_ULL(63, 3)
+	__u8 rsvd_1[32];
+} __packed;
+static_assert(sizeof(struct sdxi_cxt_ctl) == 64);
+
+/* Context Status (CXT_STS) */
+struct sdxi_cxt_sts {
+	__u8 state;
+#define SDXI_CXT_STS_STATE GENMASK(3, 0)
+	__u8 misc0;
+	__u8 rsvd_0[6];
+	__le64 read_index;
+} __packed;
+static_assert(sizeof(struct sdxi_cxt_sts) == 16);
+
+/* Valid values for FIELD_GET(SDXI_CXT_STS_STATE, sdxi_cxt_sts.state) */
+enum cxt_sts_state {
+	CXTV_STOP_SW  = 0x0,
+	CXTV_RUN      = 0x1,
+	CXTV_STOPG_SW = 0x2,
+	CXTV_STOP_FN  = 0x4,
+	CXTV_STOPG_FN = 0x6,
+	CXTV_ERR_FN   = 0xf,
+};
+
+static inline enum cxt_sts_state sdxi_cxt_sts_state(const struct sdxi_cxt_sts *sts)
+{
+	return FIELD_GET(SDXI_CXT_STS_STATE, READ_ONCE(sts->state));
+}
+
+/* Access key entry (AKEY_ENT) */
+struct sdxi_akey_ent {
+	__le16 intr_num;
+#define SDXI_AKEY_ENT_VL BIT(0)
+#define SDXI_AKEY_ENT_PV BIT(2)
+	__le16 tgt_sfunc;
+	__le32 pasid;
+#define SDXI_AKEY_ENT_PASID GENMASK(19, 0)
+	__le16 stag;
+	__u8   rsvd_0[2];
+	__le16 rkey;
+	__u8   rsvd_1[2];
+} __packed;
+static_assert(sizeof(struct sdxi_akey_ent) == 16);
+
+/* Error Log Header Entry (ERRLOG_HD_ENT) */
+struct sdxi_errlog_hd_ent {
+	__le32 opcode;
+	__le16 misc0;
+	__le16 cxt_num;
+	__le64 dsc_index;
+	__u8   rsvd_0[28];
+	__le16 err_class;
+	__u8   rsvd_1[2];
+	__le32 vendor[4];
+} __packed;
+static_assert(sizeof(struct sdxi_errlog_hd_ent) == 64);
+
+/* Completion status block (CST_BLK) */
+struct sdxi_cst_blk {
+	__le64 signal;
+	__le32 flags;
+#define SDXI_CST_BLK_ER_BIT BIT(31)
+	__u8 rsvd_0[20];
+} __packed;
+static_assert(sizeof(struct sdxi_cst_blk) == 32);
+
+/*
+ * Size of the "body" of each descriptor between the common opcode and
+ * csb_ptr fields.
+ */
+#define DSC_OPERATION_BYTES 52
+
+#define define_sdxi_dsc(tag_, name_, op_body_)				\
+	struct tag_ {							\
+		__le32 opcode;						\
+		op_body_						\
+		__le64 csb_ptr;						\
+	} name_;							\
+	static_assert(sizeof(struct tag_) ==				\
+		      sizeof(struct sdxi_dsc_generic));			\
+	static_assert(offsetof(struct tag_, csb_ptr) ==			\
+		      offsetof(struct sdxi_dsc_generic, csb_ptr))
+
+struct sdxi_desc {
+	union {
+		__le64 qw[8];
+
+		/* DSC_GENERIC - common header and footer */
+		struct_group_tagged(sdxi_dsc_generic, generic,
+			__le32 opcode;
+#define SDXI_DSC_VL  BIT(0)
+#define SDXI_DSC_SE  BIT(1)
+#define SDXI_DSC_FE  BIT(2)
+#define SDXI_DSC_CH  BIT(3)
+#define SDXI_DSC_CSR BIT(4)
+#define SDXI_DSC_RB  BIT(5)
+#define SDXI_DSC_FLAGS   GENMASK(5, 0)
+#define SDXI_DSC_SUBTYPE GENMASK(15, 8)
+#define SDXI_DSC_TYPE    GENMASK(26, 16)
+			__u8 operation[DSC_OPERATION_BYTES];
+			__le64 csb_ptr;
+#define SDXI_DSC_NP BIT_ULL(0)
+#define SDXI_DSC_CSB_PTR GENMASK_ULL(63, 5)
+		);
+
+		/* DmaBaseGrp: DSC_DMAB_NOP */
+		define_sdxi_dsc(sdxi_dsc_dmab_nop, nop,
+			__u8 rsvd_0[DSC_OPERATION_BYTES];
+		);
+
+#define SDXI_DSC_OP_TYPE_DMAB 0x001
+#define SDXI_DSC_OP_SUBTYPE_COPY 0x03
+		/* DmaBaseGrp: DSC_DMAB_COPY */
+		define_sdxi_dsc(sdxi_dsc_dmab_copy, copy,
+				__le32 size;
+				__u8 attr;
+				__u8 rsvd_0[3];
+				__le16 akey0;
+				__le16 akey1;
+				__le64 addr0;
+				__le64 addr1;
+				__u8 rsvd_1[24];
+				);
+
+#define SDXI_DSC_OP_TYPE_INTR 0x004
+#define SDXI_DSC_OP_SUBTYPE_INTR 0x00
+		/* IntrGrp: DSC_INTR */
+		define_sdxi_dsc(sdxi_dsc_intr, intr,
+			__u8 rsvd_0[8];
+			__le16 akey;
+			__u8 rsvd_1[42];
+		);
+
+#define SDXI_DSC_OP_TYPE_ADMIN 0x002
+#define SDXI_DSC_OP_SUBTYPE_CXT_START_NM 0x03
+#define SDXI_DSC_OP_SUBTYPE_CXT_START_RS 0x08
+		/* AdminGrp: DSC_CXT_START */
+		define_sdxi_dsc(sdxi_dsc_cxt_start, cxt_start,
+				__u8 rsvd_0;
+				__u8 vflags;
+				__le16 vf_num;
+				__le16 cxt_start;
+				__le16 cxt_end;
+				__u8 rsvd_1[4];
+				__le64 db_value;
+				__u8 rsvd_2[32];
+				);
+
+#define SDXI_DSC_OP_SUBTYPE_CXT_STOP     0x04
+		/* AdminGrp: DSC_CXT_STOP */
+		define_sdxi_dsc(sdxi_dsc_cxt_stop, cxt_stop,
+			__u8 rsvd_0;
+			__u8 vflags;
+			__le16 vf_num;
+			__le16 cxt_start;
+			__le16 cxt_end;
+			__u8 rsvd_1[44];
+		);
+	};
+};
+static_assert(sizeof(struct sdxi_desc) == 64);
+
+#endif /* LINUX_SDXI_HW_H */

-- 
2.39.5