aboutsummaryrefslogtreecommitdiff
path: root/qapi
diff options
context:
space:
mode:
authorJonathan Cameron <Jonathan.Cameron@huawei.com>2024-06-25 18:08:04 +0100
committerMichael S. Tsirkin <mst@redhat.com>2024-07-03 18:14:07 -0400
commitefc4ad6f9901bbba08c0e11443ba89f18b1a28e9 (patch)
treee0cc1a735f0b12f42a6c39396f2ec95150873449 /qapi
parent0f130d9e372552ef900bfac062ffc6a77b4049cc (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.json152
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' ]
}
}