qapi/cxl.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3
   4 ##
   5 # = CXL devices
   6 ##
   7
   8 ##
   9 # @CxlEventLog:
  10 #
  11 # CXL has a number of separate event logs for different types of
  12 # events.  Each such event log is handled and signaled independently.
  13 #
  14 # @informational: Information Event Log
  15 #
  16 # @warning: Warning Event Log
  17 #
  18 # @failure: Failure Event Log
  19 #
  20 # @fatal: Fatal Event Log
  21 #
  22 # Since: 8.1
  23 ##
  24 { 'enum': 'CxlEventLog',
  25   'data': ['informational',
  26            'warning',
  27            'failure',
  28            'fatal']
  29  }
  30
  31 ##
  32 # @cxl-inject-general-media-event:
  33 #
  34 # Inject an event record for a General Media Event (CXL r3.0
  35 # 8.2.9.2.1.1).  This event type is reported via one of the event logs
  36 # specified via the log parameter.
  37 #
  38 # @path: CXL type 3 device canonical QOM path
  39 #
  40 # @log: event log to add the event to
  41 #
  42 # @flags: Event Record Flags.  See CXL r3.0 Table 8-42 Common Event
  43 #     Record Format, Event Record Flags for subfield definitions.
  44 #
  45 # @dpa: Device Physical Address (relative to @path device).  Note
  46 #     lower bits include some flags.  See CXL r3.0 Table 8-43 General
  47 #     Media Event Record, Physical Address.
  48 #
  49 # @descriptor: Memory Event Descriptor with additional memory event
  50 #     information.  See CXL r3.0 Table 8-43 General Media Event
  51 #     Record, Memory Event Descriptor for bit definitions.
  52 #
  53 # @type: Type of memory event that occurred.  See CXL r3.0 Table 8-43
  54 #     General Media Event Record, Memory Event Type for possible
  55 #     values.
  56 #
  57 # @transaction-type: Type of first transaction that caused the event
  58 #     to occur.  See CXL r3.0 Table 8-43 General Media Event Record,
  59 #     Transaction Type for possible values.
  60 #
  61 # @channel: The channel of the memory event location.  A channel is an
  62 #     interface that can be independently accessed for a transaction.
  63 #
  64 # @rank: The rank of the memory event location.  A rank is a set of
  65 #     memory devices on a channel that together execute a transaction.
  66 #
  67 # @device: Bitmask that represents all devices in the rank associated
  68 #     with the memory event location.
  69 #
  70 # @component-id: Device specific component identifier for the event.
  71 #     May describe a field replaceable sub-component of the device.
  72 #
  73 # Since: 8.1
  74 ##
  75 { 'command': 'cxl-inject-general-media-event',
  76   'data': { 'path': 'str', 'log': 'CxlEventLog', 'flags': 'uint8',
  77             'dpa': 'uint64', 'descriptor': 'uint8',
  78             'type': 'uint8', 'transaction-type': 'uint8',
  79             '*channel': 'uint8', '*rank': 'uint8',
  80             '*device': 'uint32', '*component-id': 'str' } }
  81
  82 ##
  83 # @cxl-inject-dram-event:
  84 #
  85 # Inject an event record for a DRAM Event (CXL r3.0 8.2.9.2.1.2).
  86 # This event type is reported via one of the event logs specified via
  87 # the log parameter.
  88 #
  89 # @path: CXL type 3 device canonical QOM path
  90 #
  91 # @log: Event log to add the event to
  92 #
  93 # @flags: Event Record Flags.  See CXL r3.0 Table 8-42 Common Event
  94 #     Record Format, Event Record Flags for subfield definitions.
  95 #
  96 # @dpa: Device Physical Address (relative to @path device).  Note
  97 #     lower bits include some flags.  See CXL r3.0 Table 8-44 DRAM
  98 #     Event Record, Physical Address.
  99 #
 100 # @descriptor: Memory Event Descriptor with additional memory event
 101 #     information.  See CXL r3.0 Table 8-44 DRAM Event Record, Memory
 102 #     Event Descriptor for bit definitions.
 103 #
 104 # @type: Type of memory event that occurred.  See CXL r3.0 Table 8-44
 105 #     DRAM Event Record, Memory Event Type for possible values.
 106 #
 107 # @transaction-type: Type of first transaction that caused the event
 108 #     to occur.  See CXL r3.0 Table 8-44 DRAM Event Record,
 109 #     Transaction Type for possible values.
 110 #
 111 # @channel: The channel of the memory event location.  A channel is an
 112 #     interface that can be independently accessed for a transaction.
 113 #
 114 # @rank: The rank of the memory event location.  A rank is a set of
 115 #     memory devices on a channel that together execute a transaction.
 116 #
 117 # @nibble-mask: Identifies one or more nibbles that the error affects
 118 #
 119 # @bank-group: Bank group of the memory event location, incorporating
 120 #     a number of Banks.
 121 #
 122 # @bank: Bank of the memory event location.  A single bank is accessed
 123 #     per read or write of the memory.
 124 #
 125 # @row: Row address within the DRAM.
 126 #
 127 # @column: Column address within the DRAM.
 128 #
 129 # @correction-mask: Bits within each nibble.  Used in order of bits
 130 #     set in the nibble-mask.  Up to 4 nibbles may be covered.
 131 #
 132 # Since: 8.1
 133 ##
 134 { 'command': 'cxl-inject-dram-event',
 135   'data': { 'path': 'str', 'log': 'CxlEventLog', 'flags': 'uint8',
 136             'dpa': 'uint64', 'descriptor': 'uint8',
 137             'type': 'uint8', 'transaction-type': 'uint8',
 138             '*channel': 'uint8', '*rank': 'uint8', '*nibble-mask': 'uint32',
 139             '*bank-group': 'uint8', '*bank': 'uint8', '*row': 'uint32',
 140             '*column': 'uint16', '*correction-mask': [ 'uint64' ]
 141            }}
 142
 143 ##
 144 # @cxl-inject-memory-module-event:
 145 #
 146 # Inject an event record for a Memory Module Event (CXL r3.0
 147 # 8.2.9.2.1.3).  This event includes a copy of the Device Health
 148 # info at the time of the event.
 149 #
 150 # @path: CXL type 3 device canonical QOM path
 151 #
 152 # @log: Event Log to add the event to
 153 #
 154 # @flags: Event Record Flags.  See CXL r3.0 Table 8-42 Common Event
 155 #     Record Format, Event Record Flags for subfield definitions.
 156 #
 157 # @type: Device Event Type.  See CXL r3.0 Table 8-45 Memory Module
 158 #     Event Record for bit definitions for bit definiions.
 159 #
 160 # @health-status: Overall health summary bitmap.  See CXL r3.0 Table
 161 #     8-100 Get Health Info Output Payload, Health Status for bit
 162 #     definitions.
 163 #
 164 # @media-status: Overall media health summary.  See CXL r3.0 Table
 165 #     8-100 Get Health Info Output Payload, Media Status for bit
 166 #     definitions.
 167 #
 168 # @additional-status: See CXL r3.0 Table 8-100 Get Health Info Output
 169 #     Payload, Additional Status for subfield definitions.
 170 #
 171 # @life-used: Percentage (0-100) of factory expected life span.
 172 #
 173 # @temperature: Device temperature in degrees Celsius.
 174 #
 175 # @dirty-shutdown-count: Number of times the device has been unable to
 176 #     determine whether data loss may have occurred.
 177 #
 178 # @corrected-volatile-error-count: Total number of correctable errors
 179 #     in volatile memory.
 180 #
 181 # @corrected-persistent-error-count: Total number of correctable
 182 #     errors in persistent memory
 183 #
 184 # Since: 8.1
 185 ##
 186 { 'command': 'cxl-inject-memory-module-event',
 187   'data': { 'path': 'str', 'log': 'CxlEventLog', 'flags' : 'uint8',
 188             'type': 'uint8', 'health-status': 'uint8',
 189             'media-status': 'uint8', 'additional-status': 'uint8',
 190             'life-used': 'uint8', 'temperature' : 'int16',
 191             'dirty-shutdown-count': 'uint32',
 192             'corrected-volatile-error-count': 'uint32',
 193             'corrected-persistent-error-count': 'uint32'
 194             }}
 195
 196 ##
 197 # @cxl-inject-poison:
 198 #
 199 # Poison records indicate that a CXL memory device knows that a
 200 # particular memory region may be corrupted.  This may be because of
 201 # locally detected errors (e.g. ECC failure) or poisoned writes
 202 # received from other components in the system.  This injection
 203 # mechanism enables testing of the OS handling of poison records which
 204 # may be queried via the CXL mailbox.
 205 #
 206 # @path: CXL type 3 device canonical QOM path
 207 #
 208 # @start: Start address; must be 64 byte aligned.
 209 #
 210 # @length: Length of poison to inject; must be a multiple of 64 bytes.
 211 #
 212 # Since: 8.1
 213 ##
 214 { 'command': 'cxl-inject-poison',
 215   'data': { 'path': 'str', 'start': 'uint64', 'length': 'size' }}
 216
 217 ##
 218 # @CxlUncorErrorType:
 219 #
 220 # Type of uncorrectable CXL error to inject.  These errors are
 221 # reported via an AER uncorrectable internal error with additional
 222 # information logged at the CXL device.
 223 #
 224 # @cache-data-parity: Data error such as data parity or data ECC error
 225 #     CXL.cache
 226 #
 227 # @cache-address-parity: Address parity or other errors associated
 228 #     with the address field on CXL.cache
 229 #
 230 # @cache-be-parity: Byte enable parity or other byte enable errors on
 231 #     CXL.cache
 232 #
 233 # @cache-data-ecc: ECC error on CXL.cache
 234 #
 235 # @mem-data-parity: Data error such as data parity or data ECC error
 236 #     on CXL.mem
 237 #
 238 # @mem-address-parity: Address parity or other errors associated with
 239 #     the address field on CXL.mem
 240 #
 241 # @mem-be-parity: Byte enable parity or other byte enable errors on
 242 #     CXL.mem.
 243 #
 244 # @mem-data-ecc: Data ECC error on CXL.mem.
 245 #
 246 # @reinit-threshold: REINIT threshold hit.
 247 #
 248 # @rsvd-encoding: Received unrecognized encoding.
 249 #
 250 # @poison-received: Received poison from the peer.
 251 #
 252 # @receiver-overflow: Buffer overflows (first 3 bits of header log
 253 #     indicate which)
 254 #
 255 # @internal: Component specific error
 256 #
 257 # @cxl-ide-tx: Integrity and data encryption tx error.
 258 #
 259 # @cxl-ide-rx: Integrity and data encryption rx error.
 260 #
 261 # Since: 8.0
 262 ##
 263
 264 { 'enum': 'CxlUncorErrorType',
 265   'data': ['cache-data-parity',
 266            'cache-address-parity',
 267            'cache-be-parity',
 268            'cache-data-ecc',
 269            'mem-data-parity',
 270            'mem-address-parity',
 271            'mem-be-parity',
 272            'mem-data-ecc',
 273            'reinit-threshold',
 274            'rsvd-encoding',
 275            'poison-received',
 276            'receiver-overflow',
 277            'internal',
 278            'cxl-ide-tx',
 279            'cxl-ide-rx'
 280            ]
 281  }
 282
 283 ##
 284 # @CXLUncorErrorRecord:
 285 #
 286 # Record of a single error including header log.
 287 #
 288 # @type: Type of error
 289 #
 290 # @header: 16 DWORD of header.
 291 #
 292 # Since: 8.0
 293 ##
 294 { 'struct': 'CXLUncorErrorRecord',
 295   'data': {
 296       'type': 'CxlUncorErrorType',
 297       'header': [ 'uint32' ]
 298   }
 299 }
 300
 301 ##
 302 # @cxl-inject-uncorrectable-errors:
 303 #
 304 # Command to allow injection of multiple errors in one go.  This
 305 # allows testing of multiple header log handling in the OS.
 306 #
 307 # @path: CXL Type 3 device canonical QOM path
 308 #
 309 # @errors: Errors to inject
 310 #
 311 # Since: 8.0
 312 ##
 313 { 'command': 'cxl-inject-uncorrectable-errors',
 314   'data': { 'path': 'str',
 315              'errors': [ 'CXLUncorErrorRecord' ] }}
 316
 317 ##
 318 # @CxlCorErrorType:
 319 #
 320 # Type of CXL correctable error to inject
 321 #
 322 # @cache-data-ecc: Data ECC error on CXL.cache
 323 #
 324 # @mem-data-ecc: Data ECC error on CXL.mem
 325 #
 326 # @crc-threshold: Component specific and applicable to 68 byte Flit
 327 #     mode only.
 328 #
 329 # @cache-poison-received: Received poison from a peer on CXL.cache.
 330 #
 331 # @mem-poison-received: Received poison from a peer on CXL.mem
 332 #
 333 # @physical: Received error indication from the physical layer.
 334 #
 335 # Since: 8.0
 336 ##
 337 { 'enum': 'CxlCorErrorType',
 338   'data': ['cache-data-ecc',
 339            'mem-data-ecc',
 340            'crc-threshold',
 341            'retry-threshold',
 342            'cache-poison-received',
 343            'mem-poison-received',
 344            'physical']
 345 }
 346
 347 ##
 348 # @cxl-inject-correctable-error:
 349 #
 350 # Command to inject a single correctable error.  Multiple error
 351 # injection of this error type is not interesting as there is no
 352 # associated header log.  These errors are reported via AER as a
 353 # correctable internal error, with additional detail available from
 354 # the CXL device.
 355 #
 356 # @path: CXL Type 3 device canonical QOM path
 357 #
 358 # @type: Type of error.
 359 #
 360 # Since: 8.0
 361 ##
 362 {'command': 'cxl-inject-correctable-error',
 363  'data': {'path': 'str', 'type': 'CxlCorErrorType'}}