cxl: Add KUnit tests and documentation

Changes in v2:
- Use explicit hex designators in the decoder count table to match the spec (JonathanC)
- Generalize arch option and add help ref in testing page (AnisaS)
- Explicitly initialize the mock return_code to SUCCESS (MingL)
- Add a 'Maintaining KUnit tests' section to testing page
- Wrap long lines in testing page (JonathanC)
- Rebase on 7.4-rc1
v1: https://lore.kernel.org/linux-cxl/[email protected]/

The CXL subsystem has no KUnit tests. Its automated test coverage comes from cxl_test and the ndctl suite, which exercise the driver stack through an emulated CXL topology. KUnit complements that coverage by testing self- contained logic and error paths in isolation.

This series introduces CXL KUnit infrastructure and documentation describing how it complements the existing cxl_test coverage.

The first KUnit suite, a collection of related test cases, exercises the HDM decoder interleave encoding helpers, providing a starting point for testing self-contained CXL logic. The second suite exercises mailbox command handling, including error paths that are difficult to reach through cxl_test.

The mailbox tests also demonstrate the value of regression coverage. An unknown device return code can cause an out-of-bounds read and allow a failed command to be reported as successful. The series corrects that behavior, then adds tests that reproduce the failure without the correction. With KASAN enabled, the tests also expose the out-of-bounds read.

Together, the two suites establish a pattern for adding KUnit coverage to CXL, both for existing functionality and for bugs as they are found.

Alison Schofield (3):
Documentation/driver-api/cxl: Add a testing page
cxl: Add KUnit tests for HDM decoder encoding helpers cxl/mbox: Add KUnit tests for cxl_internal_send_cmd()

Gaobin Huang (1):
cxl/mbox: Treat unknown device return codes as errors

 Documentation/driver-api/cxl/index.rst   |   1 +
 Documentation/driver-api/cxl/testing.rst | 139 +++++++++++++
 drivers/cxl/.kunitconfig                 |   4 +
 drivers/cxl/Kconfig                      |  16 ++
 drivers/cxl/Makefile                     |   1 +
 drivers/cxl/core/Makefile                |   1 +
 drivers/cxl/core/tests/Makefile          |   5 +
 drivers/cxl/core/tests/mbox_kunit.c      | 250 +++++++++++++++++++++++
 drivers/cxl/cxlmem.h                     |   6 +
 drivers/cxl/tests/Makefile               |   5 +
 drivers/cxl/tests/hdm_encoding_kunit.c   | 159 ++++++++++++++
 11 files changed, 587 insertions(+)
 create mode 100644 Documentation/driver-api/cxl/testing.rst
 create mode 100644 drivers/cxl/.kunitconfig
 create mode 100644 drivers/cxl/core/tests/Makefile
 create mode 100644 drivers/cxl/core/tests/mbox_kunit.c
 create mode 100644 drivers/cxl/tests/Makefile
 create mode 100644 drivers/cxl/tests/hdm_encoding_kunit.c

base-commit: 6628e7d4c6b25c8d18f1345e3a20d21829aae7e4

2.37.3

The CXL documentation does not describe the subsystem's testing infrastructure or provide guidance on choosing between cxl_test and KUnit.

Add a testing page that describes when to use each framework, how to run the tests, and how to add a CXL KUnit test.

---
 Documentation/driver-api/cxl/index.rst   |   1 +
 Documentation/driver-api/cxl/testing.rst | 136 +++++++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 Documentation/driver-api/cxl/testing.rst

index 3dfae1d310ca..786c189366ca 100644
@@ -15,6 +15,7 @@ that have impacts on each other.  The docs here break up configurations steps.
    theory-of-operation
    maturity-map
    conventions
+   testing
 
 .. toctree::
    :maxdepth: 2

2.37.3

The CXL subsystem has no KUnit infrastructure for testing self-contained logic.

Introduce CONFIG_CXL_KUNIT_TEST and drivers/cxl/.kunitconfig, along with an initial suite for the HDM decoder interleave encoding helpers. The suite checks valid and invalid encodings and round-trip conversions.

Use a single Kconfig option for all CXL KUnit suites, with each suite built as a separate module. This allows new suites to be added without requiring additional configuration options.

The HDM decoder helpers provide a starting point for establishing the location, naming, and configuration conventions for future CXL KUnit tests.

---
 drivers/cxl/.kunitconfig               |   4 +
 drivers/cxl/Kconfig                    |  16 +++
 drivers/cxl/Makefile                   |   1 +
 drivers/cxl/tests/Makefile             |   5 +
 drivers/cxl/tests/hdm_encoding_kunit.c | 159 +++++++++++++++++++++++++
 5 files changed, 185 insertions(+)
 create mode 100644 drivers/cxl/.kunitconfig
 create mode 100644 drivers/cxl/tests/Makefile
 create mode 100644 drivers/cxl/tests/hdm_encoding_kunit.c

new file mode 100644
index 000000000000..4fee684f5ff6
@@ -0,0 +1,4 @@
+CONFIG_KUNIT=y
+CONFIG_PCI=y
+CONFIG_CXL_BUS=y
+CONFIG_CXL_KUNIT_TEST=y

index 80aeb0d556bd..fdd57a4118db 100644
@@ -243,4 +243,20 @@ config CXL_ATL
 	depends on CXL_REGION
 	depends on ACPI_PRMT && AMD_NB
 
+config CXL_KUNIT_TEST
+	tristate "KUnit tests for CXL" if !KUNIT_ALL_TESTS
+	depends on KUNIT
+	default KUNIT_ALL_TESTS
+	help
+	  This builds the KUnit tests for the CXL subsystem. When built
+	  as a module, each test suite is its own cxl_<name>_kunit
+	  module. This one option covers every CXL KUnit test, so new
+	  tests need no new configuration.
+
+	  For more information on KUnit and unit tests in general,
+	  please refer to the KUnit documentation in
+	  Documentation/dev-tools/kunit/.
+
+	  If unsure, say N.
+
 endif

index 2caa90fa4bf2..d57fb0e9e7da 100644
@@ -13,6 +13,7 @@ obj-$(CONFIG_CXL_ACPI) += cxl_acpi.o
 obj-$(CONFIG_CXL_PMEM) += cxl_pmem.o
 obj-$(CONFIG_CXL_MEM) += cxl_mem.o
 obj-$(CONFIG_CXL_PCI) += cxl_pci.o
+obj-$(CONFIG_CXL_KUNIT_TEST) += tests/
 
 cxl_port-y := port.o
 cxl_acpi-y := acpi.o

new file mode 100644
index 000000000000..aa5e4f8e3638
@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: GPL-2.0
+ccflags-y += -I$(srctree)/drivers/cxl
+
+obj-$(CONFIG_CXL_KUNIT_TEST) += cxl_hdm_encoding_kunit.o
+cxl_hdm_encoding_kunit-y := hdm_encoding_kunit.o

2.37.3

From: Gaobin Huang <[email protected]>

cxl_mbox_cmd_rc2errno() and cxl_mbox_cmd_rc2str() use the device's 16-bit return code to index cxl_mbox_cmd_rctable[]. A return code outside the table's range causes an out-of-bounds read, potentially allowing a failed command to be reported as successful.

Check the return code against the table size. Report unknown codes as -ENXIO, the errno used for most device-reported errors, and describe them as "unknown return code".

Found with a QEMU Type-3 device returning codes 001Fh and 0020h, which are defined in CXL 4.0 but not yet recognized by Linux [1].

[1] https://lore.kernel.org/linux-cxl/[email protected]/

---
 drivers/cxl/cxlmem.h | 6 ++++++
 1 file changed, 6 insertions(+)

index 35268d1c387c..e64fb09fe79a 100644
@@ -6,6 +6,7 @@
 #include <linux/pci.h>
 #include <linux/cdev.h>
 #include <linux/uuid.h>
+#include <linux/array_size.h>
 #include <linux/node.h>
 #include <cxl/event.h>
 #include <cxl/mailbox.h>

@@ -206,13 +207,18 @@ static const
 struct cxl_mbox_cmd_rc cxl_mbox_cmd_rctable[] ={ CMD_CMD_RC_TABLE };
 #undef C
 
+/* The return code comes from the device and may be one this table lacks */
 static inline const char *cxl_mbox_cmd_rc2str(struct cxl_mbox_cmd *mbox_cmd)
 {
+	if (mbox_cmd->return_code >= ARRAY_SIZE(cxl_mbox_cmd_rctable))
+		return "unknown return code";
 	return cxl_mbox_cmd_rctable[mbox_cmd->return_code].desc;
 }
 
 static inline int cxl_mbox_cmd_rc2errno(struct cxl_mbox_cmd *mbox_cmd)
 {
+	if (mbox_cmd->return_code >= ARRAY_SIZE(cxl_mbox_cmd_rctable))
+		return -ENXIO;
 	return cxl_mbox_cmd_rctable[mbox_cmd->return_code].err;
 }
 

2.37.3

cxl_internal_send_cmd() validates mailbox payload sizes, translates device return codes to errnos, and checks returned output sizes. Existing cxl_test coverage does not exercise many of its error paths.

Add a KUnit suite that replaces mbox_send() with a stub transport, allowing tests to control transport errors, device return codes, and output sizes.

The suite covers command forwarding, payload size limits, transport errors, defined and unknown device return codes, background commands, and fixed versus variable output sizes.

The unknown return code cases provide regression coverage for "cxl/mbox:
Treat unknown device return codes as errors". Without that change, the tests fail and KASAN reports a global out-of-bounds read.

The suite uses the existing CONFIG_CXL_KUNIT_TEST option, allowing it to run without additional configuration.

---
 Documentation/driver-api/cxl/testing.rst |   3 +
 drivers/cxl/core/Makefile                |   1 +
 drivers/cxl/core/tests/Makefile          |   5 +
 drivers/cxl/core/tests/mbox_kunit.c      | 250 +++++++++++++++++++++++
 4 files changed, 259 insertions(+)
 create mode 100644 drivers/cxl/core/tests/Makefile
 create mode 100644 drivers/cxl/core/tests/mbox_kunit.c

index 923492b6bfa9..6ce1cb581ec4 100644
@@ -122,6 +122,9 @@ A CXL KUnit test follows these rules:
 - Use exported interfaces where possible, importing the CXL symbol namespace as
   needed.
 
+For an example of testing mailbox command handling with a stub transport, see
+drivers/cxl/core/tests/mbox_kunit.c.
+
 When to add a test
 ==================
 

index ce7213818d3c..b2627933b7fb 100644
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: GPL-2.0
 obj-$(CONFIG_CXL_BUS) += cxl_core.o
 obj-$(CONFIG_CXL_SUSPEND) += suspend.o
+obj-$(CONFIG_CXL_KUNIT_TEST) += tests/
 
 ccflags-y += -I$(srctree)/drivers/cxl
 CFLAGS_trace.o = -DTRACE_INCLUDE_PATH=. -I$(src)

new file mode 100644
index 000000000000..08d97303d0d1
@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: GPL-2.0
+ccflags-y += -I$(srctree)/drivers/cxl
+
+obj-$(CONFIG_CXL_KUNIT_TEST) += cxl_core_mbox_kunit.o
+cxl_core_mbox_kunit-y := mbox_kunit.o

2.37.3

Applied to cxl/next:
533928808ac1 cxl/mbox: Add KUnit tests for cxl_internal_send_cmd() a0481710d758 cxl/mbox: Treat unknown device return codes as errors 70965c844464 cxl: Add KUnit tests for HDM decoder encoding helpers feade4648c97 Documentation/driver-api/cxl: Add a testing page