diff options
author | Jonathan Cameron <Jonathan.Cameron@huawei.com> | 2024-06-25 18:08:04 +0100 |
---|---|---|
committer | Michael S. Tsirkin <mst@redhat.com> | 2024-07-03 18:14:07 -0400 |
commit | efc4ad6f9901bbba08c0e11443ba89f18b1a28e9 (patch) | |
tree | e0cc1a735f0b12f42a6c39396f2ec95150873449 /qapi | |
parent | 0f130d9e372552ef900bfac062ffc6a77b4049cc (diff) |
hw/cxl/events: Improve QMP interfaces and documentation for add/release dynamic capacity.
New DCD command definitions updated in response to review comments
from Markus.
- Used CxlXXXX instead of CXLXXXXX for newly added types.
- Expanded some abreviations in type names to be easier to read.
- Additional documentation for some fields.
- Replace slightly vague cxl r3.1 references with
"Compute Express Link (CXL) Specification, Revision 3.1, XXXX"
to bring them inline with what it says on the specification cover.
Suggested-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Message-Id: <20240625170805.359278-2-Jonathan.Cameron@huawei.com>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Diffstat (limited to 'qapi')
-rw-r--r-- | qapi/cxl.json | 152 |
1 files changed, 94 insertions, 58 deletions
diff --git a/qapi/cxl.json b/qapi/cxl.json index 57d9f82014..a38622a0d1 100644 --- a/qapi/cxl.json +++ b/qapi/cxl.json @@ -363,9 +363,11 @@ 'data': {'path': 'str', 'type': 'CxlCorErrorType'}} ## -# @CXLDynamicCapacityExtent: +# @CxlDynamicCapacityExtent: # -# A single dynamic capacity extent +# A single dynamic capacity extent. This is a contiguous allocation +# of memory by Device Physical Address within a single Dynamic +# Capacity Region on a CXL Type 3 Device. # # @offset: The offset (in bytes) to the start of the region # where the extent belongs to. @@ -374,7 +376,7 @@ # # Since: 9.1 ## -{ 'struct': 'CXLDynamicCapacityExtent', +{ 'struct': 'CxlDynamicCapacityExtent', 'data': { 'offset':'uint64', 'len': 'uint64' @@ -382,22 +384,40 @@ } ## -# @CXLExtSelPolicy: +# @CxlExtentSelectionPolicy: # # The policy to use for selecting which extents comprise the added -# capacity, as defined in cxl spec r3.1 Table 7-70. -# -# @free: 0h = Free -# -# @contiguous: 1h = Continuous -# -# @prescriptive: 2h = Prescriptive -# -# @enable-shared-access: 3h = Enable Shared Access +# capacity, as defined in Compute Express Link (CXL) Specification, +# Revision 3.1, Table 7-70. +# +# @free: Device is responsible for allocating the requested memory +# capacity and is free to do this using any combination of +# supported extents. +# +# @contiguous: Device is responsible for allocating the requested +# memory capacity but must do so as a single contiguous +# extent. +# +# @prescriptive: The precise set of extents to be allocated is +# specified by the command. Thus allocation is being managed +# by the issuer of the allocation command, not the device. +# +# @enable-shared-access: Capacity has already been allocated to a +# different host using free, contiguous or prescriptive policy +# with a known tag. This policy then instructs the device to +# make the capacity with the specified tag available to an +# additional host. Capacity is implicit as it matches that +# already associated with the tag. Note that the extent list +# (and hence Device Physical Addresses) used are per host, so +# a device may use different representations on each host. +# The ordering of the extents provided to each host is indicated +# to the host using per extent sequence numbers generated by +# the device. Has a similar meaning for temporal sharing, but +# in that case there may be only one host involved. # # Since: 9.1 ## -{ 'enum': 'CXLExtSelPolicy', +{ 'enum': 'CxlExtentSelectionPolicy', 'data': ['free', 'contiguous', 'prescriptive', @@ -407,54 +427,60 @@ ## # @cxl-add-dynamic-capacity: # -# Command to initiate to add dynamic capacity extents to a host. It -# simulates operations defined in cxl spec r3.1 7.6.7.6.5. +# Initiate adding dynamic capacity extents to a host. This simulates +# operations defined in Compute Express Link (CXL) Specification, +# Revision 3.1, Section 7.6.7.6.5. Note that, currently, establishing +# success or failure of the full Add Dynamic Capacity flow requires +# out of band communication with the OS of the CXL host. # -# @path: CXL DCD canonical QOM path. +# @path: path to the CXL Dynamic Capacity Device in the QOM tree. # -# @host-id: The "Host ID" field as defined in cxl spec r3.1 -# Table 7-70. +# @host-id: The "Host ID" field as defined in Compute Express Link +# (CXL) Specification, Revision 3.1, Table 7-70. # # @selection-policy: The "Selection Policy" bits as defined in -# cxl spec r3.1 Table 7-70. It specifies the policy to use for -# selecting which extents comprise the added capacity. +# Compute Express Link (CXL) Specification, Revision 3.1, +# Table 7-70. It specifies the policy to use for selecting +# which extents comprise the added capacity. # -# @region: The "Region Number" field as defined in cxl spec r3.1 -# Table 7-70. The dynamic capacity region where the capacity -# is being added. Valid range is from 0-7. +# @region: The "Region Number" field as defined in Compute Express +# Link (CXL) Specification, Revision 3.1, Table 7-70. Valid +# range is from 0-7. # -# @tag: The "Tag" field as defined in cxl spec r3.1 Table 7-70. +# @tag: The "Tag" field as defined in Compute Express Link (CXL) +# Specification, Revision 3.1, Table 7-70. # -# @extents: The "Extent List" field as defined in cxl spec r3.1 -# Table 7-70. +# @extents: The "Extent List" field as defined in Compute Express Link +# (CXL) Specification, Revision 3.1, Table 7-70. # # Since : 9.1 ## { 'command': 'cxl-add-dynamic-capacity', 'data': { 'path': 'str', 'host-id': 'uint16', - 'selection-policy': 'CXLExtSelPolicy', + 'selection-policy': 'CxlExtentSelectionPolicy', 'region': 'uint8', '*tag': 'str', - 'extents': [ 'CXLDynamicCapacityExtent' ] + 'extents': [ 'CxlDynamicCapacityExtent' ] } } ## -# @CXLExtRemovalPolicy: +# @CxlExtentRemovalPolicy: # # The policy to use for selecting which extents comprise the released -# capacity, defined in the "Flags" field in cxl spec r3.1 Table 7-71. +# capacity, defined in the "Flags" field in Compute Express Link (CXL) +# Specification, Revision 3.1, Table 7-71. # -# @tag-based: value = 0h. Extents are selected by the device based -# on tag, with no requirement for contiguous extents. +# @tag-based: Extents are selected by the device based on tag, with +# no requirement for contiguous extents. # -# @prescriptive: value = 1h. Extent list of capacity to release is -# included in the request payload. +# @prescriptive: Extent list of capacity to release is included in +# the request payload. # # Since: 9.1 ## -{ 'enum': 'CXLExtRemovalPolicy', +{ 'enum': 'CxlExtentRemovalPolicy', 'data': ['tag-based', 'prescriptive'] } @@ -462,45 +488,55 @@ ## # @cxl-release-dynamic-capacity: # -# Command to initiate to release dynamic capacity extents from a -# host. It simulates operations defined in cxl spec r3.1 7.6.7.6.6. +# Initiate release of dynamic capacity extents from a host. This +# simulates operations defined in Compute Express Link (CXL) +# Specification, Revision 3.1, Section 7.6.7.6.6. Note that, +# currently, success or failure of the full Release Dynamic Capacity +# flow requires out of band communication with the OS of the CXL host. # -# @path: CXL DCD canonical QOM path. +# @path: path to the CXL Dynamic Capacity Device in the QOM tree. # -# @host-id: The "Host ID" field as defined in cxl spec r3.1 -# Table 7-71. +# @host-id: The "Host ID" field as defined in Compute Express Link +# (CXL) Specification, Revision 3.1, Table 7-71. # -# @removal-policy: Bit[3:0] of the "Flags" field as defined in cxl -# spec r3.1 Table 7-71. +# @removal-policy: Bit[3:0] of the "Flags" field as defined in +# Compute Express Link (CXL) Specification, Revision 3.1, +# Table 7-71. # -# @forced-removal: Bit[4] of the "Flags" field in cxl spec r3.1 -# Table 7-71. When set, device does not wait for a Release -# Dynamic Capacity command from the host. Host immediately -# loses access to released capacity. +# @forced-removal: Bit[4] of the "Flags" field in Compute Express +# Link (CXL) Specification, Revision 3.1, Table 7-71. When set, +# the device does not wait for a Release Dynamic Capacity command +# from the host. Instead, the host immediately looses access to +# the released capacity. # -# @sanitize-on-release: Bit[5] of the "Flags" field in cxl spec r3.1 -# Table 7-71. When set, device should sanitize all released -# capacity as a result of this request. +# @sanitize-on-release: Bit[5] of the "Flags" field in Compute +# Express Link (CXL) Specification, Revision 3.1, Table 7-71. +# When set, the device should sanitize all released capacity as +# a result of this request. This ensures that all user data +# and metadata is made permanently unavailable by whatever +# means is appropriate for the media type. Note that changing +# encryption keys is not sufficient. # -# @region: The "Region Number" field as defined in cxl spec r3.1 -# Table 7-71. The dynamic capacity region where the capacity -# is being added. Valid range is from 0-7. +# @region: The "Region Number" field as defined in Compute Express +# Link Specification, Revision 3.1, Table 7-71. Valid range +# is from 0-7. # -# @tag: The "Tag" field as defined in cxl spec r3.1 Table 7-71. +# @tag: The "Tag" field as defined in Compute Express Link (CXL) +# Specification, Revision 3.1, Table 7-71. # -# @extents: The "Extent List" field as defined in cxl spec r3.1 -# Table 7-71. +# @extents: The "Extent List" field as defined in Compute Express +# Link (CXL) Specification, Revision 3.1, Table 7-71. # # Since : 9.1 ## { 'command': 'cxl-release-dynamic-capacity', 'data': { 'path': 'str', 'host-id': 'uint16', - 'removal-policy': 'CXLExtRemovalPolicy', + 'removal-policy': 'CxlExtentRemovalPolicy', '*forced-removal': 'bool', '*sanitize-on-release': 'bool', 'region': 'uint8', '*tag': 'str', - 'extents': [ 'CXLDynamicCapacityExtent' ] + 'extents': [ 'CxlDynamicCapacityExtent' ] } } |