'\" t
.\"     Title: cxl-inject-media-poison
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-06-30
.\"    Manual: cxl Manual
.\"    Source: cxl
.\"  Language: English
.\"
.TH "CXL\-INJECT\-MEDIA\-POISON" "1" "2026-06-30" "cxl" "cxl Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
cxl-inject-media-poison \- Inject poison into CXL memory
.SH "SYNOPSIS"
.sp
.nf
\fIcxl inject\-media\-poison\fP <memdev> [<options>]
.fi
.br
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
Poison injection can cause system instability and should only be used
for debugging hardware and software error recovery flows. Use at your own risk!
.sp .5v
.RE
.sp
Inject poison into a CXL memory device\(cqs memory. CXL memdevs can be specified
by device name (e.g. "mem0"), device id ("X" in "memX"), or host device name
("0000:35:00.0").
.sp
Poison can only be used with CXL memory devices with poison injection support.
To see which CXL devices support poison injection, see the "poison_injectable"
attribute under the device in \fIcxl\-list\fP. An example of a device that
supports poison injection:
.sp
.if n .RS 4
.nf
.fam C
# cxl list \-u \-m mem0
{
        "memdev":"mem0",
        "ram_size":"256.00 MiB (268.44 MB)",
        "serial":"0",
        "host":"0000:0d:00.0",
        "firmware_version":"BWFW VERSION 00",
        "poison_injectable":true
}
.fam
.fi
.if n .RE
.sp
A device physical address is required for poison injection. The \fI\-a\fP/\fI\-\-address\fP
option is used to specify the device physical address to inject poison to. The
address can be given in either decimal or hexadecimal. For example:
.sp
.if n .RS 4
.nf
.fam C
# cxl inject\-media\-poison mem0 \-a 0x1000
poison inject at mem0:0x1000
# cxl list \-m mem0 \-u \-\-media\-errors
{
  "memdev":"mem0",
  "ram_size":"256.00 MiB (268.44 MB)",
  "serial":"0",
  "host":"0000:0d:00.0",
  "firmware_version":"BWFW VERSION 00",
  "media_errors":[
    {
      "offset":"0x1000",
      "length":64,
      "source":"Injected"
    }
  ]
}
.fam
.fi
.if n .RE
.sp
See the \fIclear\-media\-poison\fP command for how to clear poison from a CXL
memory device.
.sp
This command relies on the CXL debugfs to inject poison (normally mounted
at "/sys/kernel/debug/cxl"). If the CXL debugfs is inaccesible, the
"poison_injectable" attribute will always be set to "false".
.SH "OPTIONS"
.sp
\-a, \-\-address
.RS 4
Device physical address (DPA) to use for poison injection. Address can
be specified in hex or decimal. Required for poison injection.
.RE
.sp
\-\-debug
.RS 4
Enable debug output
.RE
.SH "SEE ALSO"
.sp
cxl\-list(1)
cxl\-clear\-media\-poison(1)