[PATCH v1 36/44] selftests: sdxi: add shared descriptor and context helpers
From: Wei Huang
Date: Thu Nov 19 2026 - 15:31:50 EST
Add shared helpers for opening SDXI devices, creating contexts and
building descriptors used by the functional selftests.
Co-developed-by: Wei Huang <wei.huang2@xxxxxxx>
Signed-off-by: Wei Huang <wei.huang2@xxxxxxx>
Signed-off-by: Nathan Lynch <nathan.lynch@xxxxxxx>
---
tools/testing/selftests/sdxi/Makefile | 28 +++
tools/testing/selftests/sdxi/lib/context.c | 195 +++++++++++++++++
tools/testing/selftests/sdxi/lib/descriptor.h | 55 +++++
.../selftests/sdxi/lib/fixture-context.h | 126 +++++++++++
.../selftests/sdxi/lib/fixture-device.h | 44 ++++
tools/testing/selftests/sdxi/lib/lib.c | 206 ++++++++++++++++++
tools/testing/selftests/sdxi/lib/lib.h | 61 ++++++
7 files changed, 715 insertions(+)
create mode 100644 tools/testing/selftests/sdxi/lib/context.c
create mode 100644 tools/testing/selftests/sdxi/lib/descriptor.h
create mode 100644 tools/testing/selftests/sdxi/lib/fixture-context.h
create mode 100644 tools/testing/selftests/sdxi/lib/fixture-device.h
create mode 100644 tools/testing/selftests/sdxi/lib/lib.c
create mode 100644 tools/testing/selftests/sdxi/lib/lib.h
diff --git a/tools/testing/selftests/sdxi/Makefile b/tools/testing/selftests/sdxi/Makefile
index 107a9bd08f04..f2af46ac041f 100644
--- a/tools/testing/selftests/sdxi/Makefile
+++ b/tools/testing/selftests/sdxi/Makefile
@@ -3,3 +3,31 @@ CFLAGS += -std=gnu17 -Og -Wall -Wextra $(werror) $(TOOLS_INCLUDES) $(KHDR_INCLUD
CPPFLAGS += -I../../../include/ -Ilib/
include ../lib.mk
+
+HOSTAR ?= ar
+
+LIBDIR := $(OUTPUT)/lib
+LIB := $(LIBDIR)/lib.a
+
+all: $(LIB)
+
+LIBDEPS := \
+ Makefile \
+ lib/descriptor.h \
+ lib/fixture-context.h \
+ lib/fixture-device.h \
+ lib/lib.h
+# Library
+LIBSRC := context.c lib.c
+LIBOBJ := $(LIBSRC:%.c=$(LIBDIR)/%.o)
+EXTRA_CLEAN += $(LIBOBJ) $(LIB)
+
+$(LIB): $(LIBOBJ)
+ $(HOSTAR) rcs $@ $^
+
+$(LIBDIR)/%.o: ./lib/%.c $(LIBDEPS)
+ mkdir -p $(LIBDIR)
+ $(CC) $< $(CFLAGS) $(CPPFLAGS) -o $@ -c
+
+$(TEST_GEN_PROGS): $(LIB)
+$(TEST_GEN_PROGS_EXTENDED): $(LIB)
diff --git a/tools/testing/selftests/sdxi/lib/context.c b/tools/testing/selftests/sdxi/lib/context.c
new file mode 100644
index 000000000000..0fde2d22f3b8
--- /dev/null
+++ b/tools/testing/selftests/sdxi/lib/context.c
@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * SDXI selftest context helpers.
+ *
+ * Copyright (C) 2026 Advanced Micro Devices, Inc.
+ */
+
+#include <errno.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+#include <unistd.h>
+
+#include <linux/kernel.h>
+#include <linux/sdxi.h>
+
+#include "lib.h"
+
+#define alloc(...) \
+ ({ \
+ size_t sz = sizeof(__VA_ARGS__); \
+ void *ptr = malloc(sz); \
+ if (ptr) \
+ memset(ptr, 0, sz); \
+ (typeof(__VA_ARGS__) *)ptr; \
+ })
+
+enum {
+ SELFTEST_SDXI_CAP0_DB_STRIDE_SHIFT = 20,
+ SELFTEST_SDXI_CAP0_DB_STRIDE_MASK = 0x7,
+};
+
+static size_t sdxi_page_size(void)
+{
+ long page_size = sysconf(_SC_PAGESIZE);
+
+ if (page_size <= 0)
+ return 4096;
+
+ return (size_t)page_size;
+}
+
+size_t sdxi_context_db_stride_bytes(int device_fd)
+{
+ struct sdxi_dev_info_args info = {};
+ uint64_t shift;
+
+ info.argsz = sizeof(info);
+ if (ioctl(device_fd, SDXI_GET_DEV_INFO, &info) != 0)
+ return 0;
+
+ shift = (info.cap0 >> SELFTEST_SDXI_CAP0_DB_STRIDE_SHIFT) &
+ SELFTEST_SDXI_CAP0_DB_STRIDE_MASK;
+
+ return 4096ull << shift;
+}
+
+static void sdxi_context_munmap_safe(void *addr, size_t bytes)
+{
+ if (!addr || addr == MAP_FAILED || bytes == 0)
+ return;
+
+ (void)munmap(addr, bytes);
+}
+
+struct sdxi_context *sdxi_context_create(void)
+{
+ struct sdxi_create_cxt_args arg = {
+ .argsz = sizeof(struct sdxi_create_cxt_args),
+ .ds_ring_entries = 1024,
+ };
+ struct sdxi_context *cxt;
+ void *doorbell = MAP_FAILED;
+ void *write_idx = MAP_FAILED;
+ void *cxt_sts = MAP_FAILED;
+ void *ring = MAP_FAILED;
+ size_t page_size;
+ size_t doorbell_bytes;
+ size_t ring_bytes;
+ int cxt_fd = -1;
+ int device_fd;
+ int err;
+
+ cxt = alloc(*cxt);
+ if (!cxt)
+ return NULL;
+
+ errno = 0;
+ device_fd = open("/dev/sdxi0", O_RDWR | O_CLOEXEC);
+ if (device_fd < 0)
+ goto free_cxt;
+
+ page_size = sdxi_page_size();
+ doorbell_bytes = sdxi_context_db_stride_bytes(device_fd);
+ if (doorbell_bytes == 0)
+ goto close_fd;
+
+ ring_bytes = (size_t)arg.ds_ring_entries * sizeof(cxt->ring->entry[0]);
+ cxt_sts = mmap(NULL, page_size, PROT_READ | PROT_WRITE,
+ MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+ write_idx = mmap(NULL, page_size, PROT_READ | PROT_WRITE,
+ MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+ ring = mmap(NULL, ring_bytes, PROT_READ | PROT_WRITE,
+ MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+ if (cxt_sts == MAP_FAILED || write_idx == MAP_FAILED ||
+ ring == MAP_FAILED)
+ goto unmap_local;
+
+ arg.cxt_sts_base = (uint64_t)(uintptr_t)cxt_sts;
+ arg.write_index_base = (uint64_t)(uintptr_t)write_idx;
+ arg.ds_ring_base = (uint64_t)(uintptr_t)ring;
+
+ err = ioctl(device_fd, SDXI_CREATE_CXT, &arg);
+ if (err)
+ goto unmap_local;
+
+ cxt_fd = arg.cxt_fd;
+ if (cxt_fd < 0)
+ goto unmap_local;
+
+ ring_bytes = (size_t)arg.ds_ring_entries * sizeof(cxt->ring->entry[0]);
+
+ doorbell = mmap(NULL, doorbell_bytes, PROT_WRITE, MAP_SHARED,
+ cxt_fd, arg.doorbell_mmap_base);
+ if (doorbell == MAP_FAILED)
+ goto unmap;
+
+ *cxt = (struct sdxi_context) {
+ .device_fd = device_fd,
+ .cxt_fd = cxt_fd,
+ .pasid = arg.pasid,
+ .doorbell = doorbell,
+ .doorbell_bytes = doorbell_bytes,
+ .write_idx = write_idx,
+ .write_idx_bytes = page_size,
+ .cxt_sts = cxt_sts,
+ .cxt_sts_bytes = page_size,
+ .ring = ring,
+ .ring_bytes = ring_bytes,
+ .n_entries = arg.ds_ring_entries,
+ };
+
+ return cxt;
+
+unmap:
+ (void)ioctl(cxt_fd, SDXI_QUIESCE_CXT,
+ &(struct sdxi_quiesce_cxt_args) {
+ .argsz = sizeof(struct sdxi_quiesce_cxt_args),
+ });
+ sdxi_context_munmap_safe(doorbell, doorbell_bytes);
+unmap_local:
+ sdxi_context_munmap_safe(write_idx, page_size);
+ sdxi_context_munmap_safe(cxt_sts, page_size);
+ sdxi_context_munmap_safe(ring,
+ (size_t)arg.ds_ring_entries *
+ sizeof(cxt->ring->entry[0]));
+close_fd:
+ if (cxt_fd >= 0)
+ (void)close(cxt_fd);
+ (void)close(device_fd);
+free_cxt:
+ free(cxt);
+ return NULL;
+}
+
+void sdxi_context_destroy(struct sdxi_context *cxt)
+{
+ if (!cxt)
+ return;
+
+ (void)ioctl(cxt->cxt_fd, SDXI_QUIESCE_CXT,
+ &(struct sdxi_quiesce_cxt_args) {
+ .argsz = sizeof(struct sdxi_quiesce_cxt_args),
+ });
+ sdxi_context_munmap_safe(cxt->doorbell, cxt->doorbell_bytes);
+ sdxi_context_munmap_safe(cxt->write_idx, cxt->write_idx_bytes);
+ sdxi_context_munmap_safe(cxt->cxt_sts, cxt->cxt_sts_bytes);
+ sdxi_context_munmap_safe(cxt->ring, cxt->ring_bytes);
+ (void)close(cxt->cxt_fd);
+ (void)close(cxt->device_fd);
+ free(cxt);
+}
+
+bool sdxi_context_running(const struct sdxi_context *cxt)
+{
+ struct sdxi_cxt_sts *sts = cxt->cxt_sts;
+ enum {
+ CXTV_RUN = 1,
+ };
+
+ return (READ_ONCE(sts->state) & 0xf) == CXTV_RUN;
+}
diff --git a/tools/testing/selftests/sdxi/lib/descriptor.h b/tools/testing/selftests/sdxi/lib/descriptor.h
new file mode 100644
index 000000000000..9a0d88248dec
--- /dev/null
+++ b/tools/testing/selftests/sdxi/lib/descriptor.h
@@ -0,0 +1,55 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * SDXI selftest descriptor encoders.
+ *
+ * Copyright (C) 2026 Advanced Micro Devices, Inc.
+ */
+
+#ifndef SELFTEST_SDXI_DESCRIPTOR_H
+#define SELFTEST_SDXI_DESCRIPTOR_H
+
+#include "linux/build_bug.h"
+#include "linux/compiler.h"
+#include "linux/types.h"
+
+// Size of the "body" of each descriptor between the common opcode and
+// csb_ptr fields.
+#define SDXI_DESC_PAYLOAD_BYTES 52
+
+#define declare_sdxi_desc_payload(_name, _layout) \
+ struct _name _layout __packed; \
+ static_assert(sizeof(struct _name) == SDXI_DESC_PAYLOAD_BYTES, \
+ "descriptor payload size mismatch")
+
+declare_sdxi_desc_payload(sdxi_desc_nop, {
+ __u8 empty[SDXI_DESC_PAYLOAD_BYTES];
+ });
+
+declare_sdxi_desc_payload(sdxi_desc_copy, {
+ __le32 size;
+ __u8 attr;
+ __u8 rsvd_0[3];
+ __le16 akey0;
+ __le16 akey1;
+ __le64 addr0;
+ __le64 addr1;
+ __u8 rsvd_1[24];
+ });
+
+struct sdxi_desc {
+ union {
+ struct {
+ __le32 opcode;
+ union {
+ __u8 operation[SDXI_DESC_PAYLOAD_BYTES];
+ struct sdxi_desc_nop nop;
+ struct sdxi_desc_copy copy;
+ };
+ __le64 csb_ptr;
+ };
+ __le64 qw[8];
+ };
+} __packed __aligned(64);
+static_assert(sizeof(struct sdxi_desc) == 64, "descriptor size mismatch");
+
+#endif /* SELFTEST_SDXI_DESCRIPTOR_H */
diff --git a/tools/testing/selftests/sdxi/lib/fixture-context.h b/tools/testing/selftests/sdxi/lib/fixture-context.h
new file mode 100644
index 000000000000..6eb95e819236
--- /dev/null
+++ b/tools/testing/selftests/sdxi/lib/fixture-context.h
@@ -0,0 +1,126 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * SDXI selftest context fixture.
+ *
+ * Copyright (C) 2026 Advanced Micro Devices, Inc.
+ */
+
+#ifndef SELFTEST_SDXI_FIXTURE_CONTEXT_H
+#define SELFTEST_SDXI_FIXTURE_CONTEXT_H
+
+#include <errno.h>
+#include <fcntl.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+#include <unistd.h>
+
+#include <linux/sdxi.h>
+
+#include "lib.h"
+
+#include "../../kselftest_harness.h"
+
+FIXTURE(sdxi_context) {
+ struct sdxi_context context;
+};
+
+FIXTURE_SETUP(sdxi_context)
+{
+ struct sdxi_context *cxt = &self->context;
+ int cxt_fd;
+ int device_fd;
+ long page_size;
+ size_t doorbell_bytes;
+ size_t ring_bytes;
+ void *cxt_sts;
+ void *ring;
+ void *write_idx;
+
+ errno = 0;
+ device_fd = open("/dev/sdxi0", O_RDWR | O_CLOEXEC);
+ ASSERT_GE(device_fd, 0) {
+ if (errno == ENOENT)
+ SKIP(return,
+ "/dev/sdxi0 does not exist");
+ if (errno == EACCES && geteuid() != 0)
+ SKIP(return,
+ "insufficient privileges");
+ }
+
+ struct sdxi_create_cxt_args arg = {
+ .argsz = sizeof(struct sdxi_create_cxt_args),
+ .ds_ring_entries = 1024,
+ };
+
+ page_size = sysconf(_SC_PAGESIZE);
+ ASSERT_GT(page_size, 0);
+ ring_bytes = (size_t)arg.ds_ring_entries * sizeof(cxt->ring->entry[0]);
+
+ cxt_sts = mmap(NULL, (size_t)page_size, PROT_READ | PROT_WRITE,
+ MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+ write_idx = mmap(NULL, (size_t)page_size, PROT_READ | PROT_WRITE,
+ MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+ ring = mmap(NULL, ring_bytes, PROT_READ | PROT_WRITE,
+ MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+
+ ASSERT_NE(cxt_sts, MAP_FAILED);
+ ASSERT_NE(write_idx, MAP_FAILED);
+ ASSERT_NE(ring, MAP_FAILED);
+
+ /* Fault in and invalidate the ring before the device can fetch it. */
+ memset(ring, 0, ring_bytes);
+
+ arg.cxt_sts_base = (uint64_t)(uintptr_t)cxt_sts;
+ arg.write_index_base = (uint64_t)(uintptr_t)write_idx;
+ arg.ds_ring_base = (uint64_t)(uintptr_t)ring;
+
+ ASSERT_EQ(ioctl(device_fd, SDXI_CREATE_CXT, &arg), 0);
+ ASSERT_GE(arg.cxt_fd, 0);
+ cxt_fd = arg.cxt_fd;
+ doorbell_bytes = sdxi_context_db_stride_bytes(device_fd);
+ ASSERT_GT(doorbell_bytes, 0U);
+
+ *cxt = (struct sdxi_context) {
+ .device_fd = device_fd,
+ .cxt_fd = cxt_fd,
+ .pasid = arg.pasid,
+ .doorbell = mmap(NULL, doorbell_bytes,
+ PROT_WRITE, MAP_SHARED,
+ cxt_fd, arg.doorbell_mmap_base),
+ .doorbell_bytes = doorbell_bytes,
+ .write_idx = write_idx,
+ .write_idx_bytes = (size_t)page_size,
+ .cxt_sts = cxt_sts,
+ .cxt_sts_bytes = (size_t)page_size,
+ .ring = ring,
+ .ring_bytes = ring_bytes,
+ .n_entries = arg.ds_ring_entries,
+ };
+
+ EXPECT_NE(cxt->doorbell, MAP_FAILED);
+ EXPECT_NE(cxt->write_idx, MAP_FAILED);
+ EXPECT_NE(cxt->cxt_sts, MAP_FAILED);
+ EXPECT_NE(cxt->ring, MAP_FAILED);
+}
+
+FIXTURE_TEARDOWN(sdxi_context)
+{
+ struct sdxi_context *cxt = &self->context;
+ struct sdxi_quiesce_cxt_args quiesce = {};
+
+ quiesce.argsz = sizeof(quiesce);
+
+ EXPECT_EQ(ioctl(cxt->cxt_fd, SDXI_QUIESCE_CXT, &quiesce),
+ 0);
+ EXPECT_EQ(munmap(cxt->doorbell, cxt->doorbell_bytes), 0);
+ EXPECT_EQ(munmap(cxt->write_idx, cxt->write_idx_bytes), 0);
+ EXPECT_EQ(munmap(cxt->cxt_sts, cxt->cxt_sts_bytes), 0);
+ EXPECT_EQ(munmap(cxt->ring, cxt->ring_bytes), 0);
+ EXPECT_EQ(close(cxt->cxt_fd), 0);
+ EXPECT_EQ(close(cxt->device_fd), 0);
+}
+
+#endif /* SELFTEST_SDXI_FIXTURE_CONTEXT_H */
diff --git a/tools/testing/selftests/sdxi/lib/fixture-device.h b/tools/testing/selftests/sdxi/lib/fixture-device.h
new file mode 100644
index 000000000000..bd6a26151732
--- /dev/null
+++ b/tools/testing/selftests/sdxi/lib/fixture-device.h
@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * SDXI selftest device fixture.
+ *
+ * Copyright (C) 2026 Advanced Micro Devices, Inc.
+ */
+
+#ifndef SELFTEST_SDXI_FIXTURE_DEVICE_H
+#define SELFTEST_SDXI_FIXTURE_DEVICE_H
+
+#include <errno.h>
+#include <fcntl.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+
+#include <linux/sdxi.h>
+
+#include "lib.h"
+
+#include "../../kselftest_harness.h"
+
+FIXTURE(dev_sdxi) {
+ int fd;
+};
+
+FIXTURE_SETUP(dev_sdxi) {
+ errno = 0;
+ self->fd = open("/dev/sdxi0", O_RDONLY | O_CLOEXEC);
+ ASSERT_GE(self->fd, 0) {
+ if (errno == ENOENT)
+ SKIP(return,
+ "/dev/sdxi0 does not exist");
+ if (errno == EACCES && geteuid() != 0)
+ SKIP(return,
+ "insufficient privileges");
+ }
+}
+
+FIXTURE_TEARDOWN(dev_sdxi) {
+ EXPECT_EQ(close(self->fd), 0);
+}
+
+#endif /* SELFTEST_SDXI_FIXTURE_DEVICE_H */
diff --git a/tools/testing/selftests/sdxi/lib/lib.c b/tools/testing/selftests/sdxi/lib/lib.c
new file mode 100644
index 000000000000..26a9470d2c97
--- /dev/null
+++ b/tools/testing/selftests/sdxi/lib/lib.c
@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * SDXI selftest library helpers.
+ *
+ * Copyright (C) 2026 Advanced Micro Devices, Inc.
+ */
+
+#include <stdatomic.h>
+#include <time.h>
+#include <errno.h>
+
+#include "linux/kernel.h"
+#include "linux/bitfield.h"
+#include "linux/bits.h"
+#include "linux/types.h"
+
+#include "descriptor.h"
+#include "lib.h"
+
+#define DESC_SUBTYPE GENMASK(15, 8)
+#define DESC_TYPE GENMASK(26, 16)
+#define DESC_VL BIT(0)
+#define DESC_SE BIT(1)
+#define DESC_FE BIT(2)
+#define DESC_CH BIT(3)
+#define DESC_CSR BIT(4)
+#define DESC_RB BIT(5)
+
+#define DESC_NP BIT_ULL(0)
+#define DESC_CSB_PTR GENMASK_ULL(63, 5)
+
+enum sdxi_op_group {
+ OPGRP_DMAB = 0x001,
+};
+
+enum sdxi_operation {
+ DMAB_NOP = 0x01,
+ DMAB_COPY = 0x03,
+};
+
+struct sdxi_desc sdxi_dsc_encode_rsvd(void)
+{
+ u32 opcode =
+ FIELD_PREP(DESC_VL, 1) |
+ FIELD_PREP(DESC_SE, 0) |
+ FIELD_PREP(DESC_FE, 1) |
+ FIELD_PREP(DESC_CH, 0) |
+ FIELD_PREP(DESC_CSR, 1) |
+ FIELD_PREP(DESC_SUBTYPE, 0) |
+ FIELD_PREP(DESC_TYPE, 0);
+ u64 csb_ptr =
+ FIELD_PREP(DESC_NP, 1) |
+ FIELD_PREP(DESC_CSB_PTR, 0);
+
+ return (struct sdxi_desc) {
+ .opcode = cpu_to_le32(opcode),
+ .csb_ptr = cpu_to_le64(csb_ptr),
+ };
+}
+
+struct sdxi_desc sdxi_dsc_encode_nop(void)
+{
+ u32 opcode =
+ FIELD_PREP(DESC_VL, 1) |
+ FIELD_PREP(DESC_SE, 0) |
+ FIELD_PREP(DESC_FE, 1) |
+ FIELD_PREP(DESC_CH, 0) |
+ FIELD_PREP(DESC_CSR, 1) |
+ FIELD_PREP(DESC_SUBTYPE, DMAB_NOP) |
+ FIELD_PREP(DESC_TYPE, OPGRP_DMAB);
+ u64 csb_ptr =
+ FIELD_PREP(DESC_NP, 1) |
+ FIELD_PREP(DESC_CSB_PTR, 0);
+
+ return (struct sdxi_desc) {
+ .opcode = cpu_to_le32(opcode),
+ .csb_ptr = cpu_to_le64(csb_ptr),
+ };
+}
+
+struct sdxi_desc sdxi_dsc_encode_copy(void *dest, const void *src, size_t n)
+{
+ u32 opcode =
+ FIELD_PREP(DESC_VL, 1) |
+ FIELD_PREP(DESC_SE, 0) |
+ FIELD_PREP(DESC_FE, 1) |
+ FIELD_PREP(DESC_CH, 0) |
+ FIELD_PREP(DESC_CSR, 1) |
+ FIELD_PREP(DESC_SUBTYPE, DMAB_COPY) |
+ FIELD_PREP(DESC_TYPE, OPGRP_DMAB);
+ u64 csb_ptr =
+ FIELD_PREP(DESC_NP, 1) |
+ FIELD_PREP(DESC_CSB_PTR, 0);
+
+ return (struct sdxi_desc) {
+ .opcode = cpu_to_le32(opcode),
+ .csb_ptr = cpu_to_le64(csb_ptr),
+
+ .copy = (struct sdxi_desc_copy) {
+ .size = cpu_to_le32(n - 1),
+
+ // Note that akeys are hardcoded to 1 here and
+ // in the driver.
+ .akey0 = cpu_to_le16(1),
+ .akey1 = cpu_to_le16(1),
+ .addr0 = cpu_to_le64((uintptr_t)src),
+ .addr1 = cpu_to_le64((uintptr_t)dest),
+ },
+ };
+}
+
+static void copy_desc_to_ring(struct descriptor_ring *ring, size_t idx,
+ const struct sdxi_desc *src)
+{
+ struct sdxi_desc *dst;
+
+ idx = idx % ARRAY_SIZE(ring->entry);
+ dst = &ring->entry[idx];
+
+ for (size_t i = 1; i < ARRAY_SIZE(src->qw); ++i)
+ dst->qw[i] = src->qw[i];
+
+ atomic_thread_fence(memory_order_acq_rel);
+
+ dst->qw[0] = src->qw[0];
+}
+
+static u64 sample_read_index(const struct sdxi_context *cxt)
+{
+ return le64_to_cpu(READ_ONCE(cxt->cxt_sts->read_index));
+}
+
+int sdxi_submit_async(struct sdxi_context *cxt, const struct sdxi_desc *desc, u64 *pos)
+{
+ u64 read, old_write, new_write;
+
+ if (!sdxi_context_running(cxt))
+ return -EIO;
+
+ read = le64_to_cpu(READ_ONCE(cxt->cxt_sts->read_index));
+ atomic_thread_fence(memory_order_acq_rel);
+ old_write = le64_to_cpu(READ_ONCE(*cxt->write_idx));
+
+ if (read > old_write)
+ return -EINVAL;
+
+ new_write = old_write + 1;
+ if (new_write - read > cxt->n_entries)
+ return -ENOSPC;
+
+ WRITE_ONCE(*cxt->write_idx, cpu_to_le64(new_write));
+ atomic_thread_fence(memory_order_acq_rel);
+ copy_desc_to_ring(cxt->ring, old_write, desc);
+ WRITE_ONCE(*cxt->doorbell, cpu_to_le64(new_write));
+
+ if (pos)
+ *pos = old_write;
+ return 0;
+}
+
+// Submit nops until the function increments the read index or the
+// threshold is reached. Sleeps 1ms between each nop.
+static int force_read_index_advance(struct sdxi_context *cxt, u64 target)
+{
+ struct sdxi_desc nop = sdxi_dsc_encode_nop();
+
+ for (size_t tries = 1000; tries > 0; --tries) {
+ if (sample_read_index(cxt) >= target)
+ return 0;
+ sdxi_submit_async(cxt, &nop, NULL);
+ nanosleep(&(struct timespec) {
+ .tv_nsec = 1000000,
+ }, NULL);
+ }
+
+ fprintf(stderr, "Failed to force read index advance to %llu\n",
+ (unsigned long long)target);
+ return -ETIMEDOUT;
+}
+
+int sdxi_submit_sync(struct sdxi_context *cxt, const struct sdxi_desc *desc)
+{
+ u64 pos;
+ int err;
+
+ err = sdxi_submit_async(cxt, desc, &pos);
+ if (err)
+ return err;
+
+ return force_read_index_advance(cxt, pos + 1);
+}
+
+int sdxi_submit_oneshot(const struct sdxi_desc *desc)
+{
+ struct sdxi_context *context = sdxi_context_create();
+ int err;
+
+ if (!context)
+ return -EIO;
+
+ err = sdxi_submit_async(context, desc, NULL);
+
+ sdxi_context_destroy(context);
+
+ return err;
+}
diff --git a/tools/testing/selftests/sdxi/lib/lib.h b/tools/testing/selftests/sdxi/lib/lib.h
new file mode 100644
index 000000000000..38e7d665085e
--- /dev/null
+++ b/tools/testing/selftests/sdxi/lib/lib.h
@@ -0,0 +1,61 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * SDXI selftest library helpers.
+ *
+ * Copyright (C) 2026 Advanced Micro Devices, Inc.
+ */
+
+#ifndef SELFTEST_SDXI_LIB_H
+#define SELFTEST_SDXI_LIB_H
+
+#include <inttypes.h>
+#include <stdbool.h>
+
+#include "descriptor.h"
+#include "linux/build_bug.h"
+#include "linux/types.h"
+
+struct sdxi_cxt_sts {
+ __u8 state;
+ __u8 misc0;
+ __u8 rsvd_0[6];
+ __le64 read_index;
+};
+
+enum {
+ SDXI_DESC_RING_ENTRIES = 1024,
+};
+
+struct descriptor_ring {
+ struct sdxi_desc entry[SDXI_DESC_RING_ENTRIES];
+};
+
+struct sdxi_context {
+ int device_fd;
+ int cxt_fd;
+ __u32 pasid;
+ __le64 *doorbell;
+ size_t doorbell_bytes;
+ __le64 *write_idx;
+ size_t write_idx_bytes;
+ size_t n_entries;
+ struct sdxi_cxt_sts *cxt_sts;
+ size_t cxt_sts_bytes;
+ struct descriptor_ring *ring;
+ size_t ring_bytes;
+};
+
+size_t sdxi_context_db_stride_bytes(int device_fd);
+struct sdxi_context *sdxi_context_create(void);
+void sdxi_context_destroy(struct sdxi_context *cxt);
+bool sdxi_context_running(const struct sdxi_context *cxt);
+
+struct sdxi_desc sdxi_dsc_encode_copy(void *dest, const void *src, size_t n);
+struct sdxi_desc sdxi_dsc_encode_nop(void);
+struct sdxi_desc sdxi_dsc_encode_rsvd(void);
+
+int sdxi_submit_async(struct sdxi_context *cxt, const struct sdxi_desc *desc, u64 *pos);
+int sdxi_submit_sync(struct sdxi_context *cxt, const struct sdxi_desc *desc);
+int sdxi_submit_oneshot(const struct sdxi_desc *desc);
+
+#endif/* SELFTEST_SDXI_LIB_H */
--
2.56.1