From 3da4aef81ca61c82c67b86af369ccd251607622e Mon Sep 17 00:00:00 2001 From: Nina Schoetterl-Glausch Date: Mon, 16 Oct 2023 20:39:05 +0200 Subject: [PATCH] qapi: machine.json: change docs regarding CPU topology Clarify roles of different architectures. Also change things a bit in anticipation of additional members being added. Suggested-by: Markus Armbruster Signed-off-by: Nina Schoetterl-Glausch Message-ID: <20231016183925.2384704-2-nsg@linux.ibm.com> Acked-by: Markus Armbruster [thuth: Updated some comments according to suggestions from Markus] Signed-off-by: Thomas Huth --- qapi/machine.json | 65 ++++++++++++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index a08b6576ca..f053245756 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -71,8 +71,7 @@ # # @thread-id: ID of the underlying host thread # -# @props: properties describing to which node/socket/core/thread -# virtual CPU belongs to, provided if supported by board +# @props: properties associated with a virtual CPU, e.g. the socket id # # @target: the QEMU system emulation target, which determines which # additional fields will be listed (since 3.0) @@ -899,28 +898,35 @@ # should be passed by management with device_add command when a CPU is # being hotplugged. # +# Which members are optional and which mandatory depends on the +# architecture and board. +# +# The ids other than the node-id specify the position of the CPU +# within the CPU topology (as defined by the machine property "smp", +# thus see also type @SMPConfiguration) +# # @node-id: NUMA node ID the CPU belongs to # -# @socket-id: socket number within node/board the CPU belongs to +# @socket-id: socket number within CPU topology the CPU belongs to # -# @die-id: die number within socket the CPU belongs to (since 4.1) +# @die-id: die number within the parent container the CPU belongs to +# (since 4.1) # -# @cluster-id: cluster number within die the CPU belongs to (since -# 7.1) +# @cluster-id: cluster number within the parent container the CPU +# belongs to (since 7.1) # -# @core-id: core number within cluster the CPU belongs to +# @core-id: core number within the parent container the CPU +# belongs to # -# @thread-id: thread number within core the CPU belongs to +# @thread-id: thread number within the core the CPU belongs to # -# Note: currently there are 6 properties that could be present but -# management should be prepared to pass through other properties -# with device_add command to allow for future interface extension. -# This also requires the filed names to be kept in sync with the -# properties passed to -device/device_add. +# Note: management should be prepared to pass through additional +# properties with device_add. # # Since: 2.7 ## { 'struct': 'CpuInstanceProperties', + # Keep these in sync with the properties device_add accepts 'data': { '*node-id': 'int', '*socket-id': 'int', '*die-id': 'int', @@ -1478,22 +1484,33 @@ # Schema for CPU topology configuration. A missing value lets QEMU # figure out a suitable value based on the ones that are provided. # +# The members other than @cpus and @maxcpus define a topology of +# containers. +# +# The ordering from highest/coarsest to lowest/finest is: +# @sockets, @dies, @clusters, @cores, @threads. +# +# Different architectures support different subsets of topology +# containers. +# +# For example, s390x does not have clusters and dies, and the socket +# is the parent container of cores. +# # @cpus: number of virtual CPUs in the virtual machine # -# @sockets: number of sockets in the CPU topology -# -# @dies: number of dies per socket in the CPU topology -# -# @clusters: number of clusters per die in the CPU topology (since -# 7.0) -# -# @cores: number of cores per cluster in the CPU topology -# -# @threads: number of threads per core in the CPU topology -# # @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual # machine # +# @sockets: number of sockets in the CPU topology +# +# @dies: number of dies per parent container +# +# @clusters: number of clusters per parent container (since 7.0) +# +# @cores: number of cores per parent container +# +# @threads: number of threads per core +# # Since: 6.1 ## { 'struct': 'SMPConfiguration', 'data': {