Re: [PATCH 1/4] Documentation/driver-api/cxl: Add a testing page

[Alison Schofield <alison.schofield@intel.com>]

On Tue, Oct 13, 2026 at 09:17:52PM -0700, Alison Schofield wrote:
> 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.

Gaobin's question about updating the CMD_CMD_RC_TABLE w the new 4.0
definitions made me realize this doc could use some words around
maintaining the kunit tests, ie keeping them running.

see snippet below...


> +
> +KUnit
> +=====
> +
> +KUnit tests run self-contained logic in the kernel without any CXL topology.
> +KUnit is suited to logic that can be exercised with controlled test inputs,
> +including encode/decode helpers, address translation and interleave calculations,
> +parsers of device- or firmware-supplied data, and mailbox command handling
> +through a stub transport.
> +
> +To run all of the CXL KUnit tests, from the top of the kernel tree::
> +
> +  ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/cxl
> +
> +This builds a test kernel in .kunit/ using drivers/cxl/.kunitconfig and runs it
> +under User Mode Linux (UML). The running kernel is not modified, and no
> +installation is required. The test kernel runs the tests, reports the results,
> +and exits.
> +
> +Add --arch=x86_64 to run the tests under QEMU instead.
> +
> +Running during development
> +--------------------------
> +
> +kunit.py builds in .kunit/, but kbuild does not allow an out-of-tree build when
> +the source tree already contains an in-tree build. If you build the kernel
> +in-tree, use a separate worktree for KUnit. The worktree contains the committed
> +sources at the selected revision::
> +
> +  git worktree add ../linux-kunit HEAD
> +  cd ../linux-kunit
> +  ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/cxl
> +
> +To run a single suite, name it::
> +
> +  ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/cxl cxl_core_mbox
> +
> +Enable KASAN when testing memory safety error paths. It can detect an out-of-bounds
> +access even when the resulting value does not cause a test assertion to fail::
> +
> +  ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/cxl \
> +      --arch=x86_64 --kconfig_add CONFIG_KASAN=y
> +

Here's what I think (so far) folks need to know about maintenance-

Maintaining KUnit tests
=======================

Use loop bounds and table sizes from the code under test, such as
ARRAY_SIZE() of a lookup table, so tests adapt as the code evolves.
Derive expected results from the specification, not the implementation,
so tests can detect unintended behavior changes.

When a patch changes behavior covered by a test, update the test in the
same patch. For example, add newly supported encodings to a valid-value
table or adjust the expected errno for a new return code.

A failing test may indicate a regression or a test that needs updating.
Run the CXL KUnit tests throughout development, not just before posting,
to catch either case while making changes.


> +Adding a KUnit test
> +-------------------
> +
> +A CXL KUnit test follows these rules:
> +
> +- Place the test in a tests/ directory beside the code under test, in a
> +  file named <name>_kunit.c.
> +
> +- Derive the module and suite names from the path below drivers/cxl/, excluding
> +  tests/. For example, drivers/cxl/core/tests/port_kunit.c produces module
> +  cxl_core_port_kunit and suite cxl_core_port, while drivers/cxl/tests/port_kunit.c
> +  produces module cxl_port_kunit and suite cxl_port.
> +
> +- Build new suites under CONFIG_CXL_KUNIT_TEST rather than introducing a separate
> +  Kconfig option for each suite. Individual suites can be selected by name with
> +  kunit.py or by loading their module.
> +
> +- If the code under test depends on another configuration option, such as
> +  CONFIG_CXL_REGION, make the test build conditional on that option in tests/Makefile
> +  and enable it in drivers/cxl/.kunitconfig.
> +
> +- Use exported interfaces where possible, importing the CXL symbol namespace as needed.
> +
> +When to add a test
> +==================
> +
> +New or modified self-contained logic should be accompanied by KUnit coverage where
> +practical. Extend an existing suite when possible, or introduce a new one for
> +functionality that is not yet covered.
> +
> +Bug fixes should include regression coverage that reproduces the problem without
> +the fix.
> +
> +Changes to topology-dependent behavior should be covered by cxl_test tests in ndctl.
> +KUnit coverage complements, but does not replace, cxl_test.
> -- 
> 2.37.3
>