On Fri, 17 Jul 2026 17:27:06 -0500 Terry Bowman <[email protected]> wrote:
> Add Documentation/driver-api/cxl/linux/protocol-error-handling.rst > describing the end-to-end CXL protocol error path: AER ingress, the > AER-CXL kfifo handoff, the cxl_core consumer worker, RCD/RCH special > cases, severity policy, trace events, and a source code map. > > This documents the architecture introduced by the preceding patches in > this series. > > Assisted-by: Claude:claude-opus-4.7 > Signed-off-by: Terry Bowman <[email protected]> A couple of trivial things inline to tidy up. Actual text seems good to me. Reviewed-by: Jonathan Cameron <[email protected]> > > --- > Changes in v17->v18: > - Simplify document for readability (Jonathan) > - Drop historical context that goes stale (Jonathan) > - Shorten ASCII flow diagram (Jonathan) > - Drop manual backtick markup, use automarkup (Jonathan) > - Clarify USP/DSP as single switch component (Dave) > - Fix line wrapping to 80 chars (Jonathan) > --- > Documentation/driver-api/cxl/index.rst | 1 + > .../cxl/linux/protocol-error-handling.rst | 222 ++++++++++++++++++ > 2 files changed, 223 insertions(+) > create mode 100644 > Documentation/driver-api/cxl/linux/protocol-error-handling.rst > > diff --git a/Documentation/driver-api/cxl/index.rst > b/Documentation/driver-api/cxl/index.rst > index 3dfae1d310ca5..6861b2e5726a3 100644 > --- a/Documentation/driver-api/cxl/index.rst > +++ b/Documentation/driver-api/cxl/index.rst > @@ -42,6 +42,7 @@ that have impacts on each other. The docs here break up > configurations steps. > linux/dax-driver > linux/memory-hotplug > linux/access-coordinates > + linux/protocol-error-handling > > .. toctree:: > :maxdepth: 2 > diff --git a/Documentation/driver-api/cxl/linux/protocol-error-handling.rst > b/Documentation/driver-api/cxl/linux/protocol-error-handling.rst > new file mode 100644 > index 0000000000000..67f0492e56702 > --- /dev/null > +++ b/Documentation/driver-api/cxl/linux/protocol-error-handling.rst > @@ -0,0 +1,222 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +============================== > +CXL Protocol Error Handling > +============================== > + > +CXL devices report protocol-layer failures (CXL.cachemem RAS) as PCIe Why short wrap? Docs are 80 chars I think. > +AER Internal Errors: PCI_ERR_COR_INTERNAL for correctable events and > +PCI_ERR_UNC_INTN for uncorrectable events. The actual fault > +information lives in CXL RAS capability registers, not in the PCIe AER > +status registers. > +Error flow > +========== > + > +.. code-block:: text > + > + CXL device raises AER Internal Error > + (PCI_ERR_COR_INTERNAL or PCI_ERR_UNC_INTN) > + | > + v > + +--------------------------------------+ > + | AER core (aer.c) | > + | aer_irq() -> aer_isr() | > + | -> find_source_device() | > + | -> handle_error_source(dev, info) | > + +--------------------------------------+ > + | > + v > + +--------------------------------------+ > + | handle_error_source() dispatch | > + | | > + | 1. cxl_rch_handle_error() | > + | [always; filters internally] | > + | | > + | 2. if is_cxl_error(): | Smells like a missing space. > + | cxl_forward_error() | > + | [enqueue to kfifo] | > + | | > + | 3. if cxl_pending && non-CE: | > + | cxl_proto_err_flush() | > + | [sync drain before recovery] | > + | | > + | 4. pci_aer_handle_error() [always] | > + +--------------------------------------+ > + | > + (kfifo -> workqueue) > + | > + v > + +--------------------------------------+ > + | __cxl_proto_err_work_fn() consumer | > + | | > + | if is_cxl_restricted(pdev): | > + | cxl_handle_rdport_errors() | > + | [RCH dport RAS first] | > + | | > + | port = find_cxl_port_by_dev( | > + | &pdev->dev, NULL) | > + | dport = cxl_find_dport_by_dev( | > + | port, &pdev->dev) | > + | [dport NULL for EP/USP; set RP/DSP] | check the alignment here as well. A couple of extra spaces in the lines above I think. > + | | > + | cxl_handle_proto_error() | > + +--------------------------------------+ > + | | > + v v > + +-----------------+ +--------------------+ > + | CE | | UCE | > + | cxl_handle_ | | cxl_do_recovery() | > + | cor_ras() | | read RAS status | > + | trace + clear | | trace + panic | > + +-----------------+ +--------------------+ > + > +cxl_do_recovery() reads the CXL RAS uncorrectable status register. > +If UE bits are set, it emits the trace event and panics. If no bits > +are set (e.g. RAS mapped but error already cleared), it logs a > +diagnostic and defers to AER recovery. > + > + > +Severity policy > +=============== > + > +**CE** - cxl_handle_cor_ras() reads the CXL RAS correctable status > +register, clears set bits, and emits a cxl_aer_correctable_error > +trace event. No recovery action. > + > +**UCE (non-fatal, and fatal on Root Port/Downstream Port)** - > cxl_do_recovery() reads the CXL RAS Wrap needs an update here. > +uncorrectable status register. If UE bits are set, the kernel panics. > +CXL.cachemem traffic cannot be safely recovered once an uncorrectable > +error is signaled; continuing risks silent data corruption across > +interleaved HDM regions. This panic policy applies to the native AER > +path. On firmware-first (CPER/GHES) platforms the CPER handler emits > +trace events only and does not call cxl_do_recovery().
