From 3da4aef81ca61c82c67b86af369ccd251607622e Mon Sep 17 00:00:00 2001 From: Nina Schoetterl-Glausch Date: Mon, 16 Oct 2023 20:39:05 +0200 Subject: 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 | 59 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 21 deletions(-) (limited to 'qapi') diff --git a/qapi/machine.json b/qapi/machine.json index a08b657..f053245 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. # -# @cpus: number of virtual CPUs in the virtual machine -# -# @sockets: number of sockets in the CPU topology +# The members other than @cpus and @maxcpus define a topology of +# containers. # -# @dies: number of dies per socket in the CPU topology +# The ordering from highest/coarsest to lowest/finest is: +# @sockets, @dies, @clusters, @cores, @threads. # -# @clusters: number of clusters per die in the CPU topology (since -# 7.0) +# Different architectures support different subsets of topology +# containers. # -# @cores: number of cores per cluster in the CPU topology +# For example, s390x does not have clusters and dies, and the socket +# is the parent container of cores. # -# @threads: number of threads per core in the CPU topology +# @cpus: number of virtual CPUs in the virtual machine # # @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': { -- cgit v1.1 From 5de1aff2555275ef182197eddcadb276364ace38 Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Mon, 16 Oct 2023 20:39:06 +0200 Subject: CPU topology: extend with s390 specifics S390 adds two new SMP levels, drawers and books to the CPU topology. S390 CPUs have specific topology features like dedication and entitlement. These indicate to the guest information on host vCPU scheduling and help the guest make better scheduling decisions. Add the new levels to the relevant QAPI structs. Add all the supported topology levels, dedication and entitlement as properties to S390 CPUs. Create machine-common.json so we can later include it in machine-target.json also. Signed-off-by: Pierre Morel Reviewed-by: Nina Schoetterl-Glausch Co-developed-by: Nina Schoetterl-Glausch Reviewed-by: Thomas Huth Signed-off-by: Nina Schoetterl-Glausch Message-ID: <20231016183925.2384704-3-nsg@linux.ibm.com> Signed-off-by: Thomas Huth --- qapi/machine-common.json | 21 +++++++++++++++++++++ qapi/machine.json | 21 ++++++++++++++++++--- qapi/meson.build | 1 + qapi/qapi-schema.json | 1 + 4 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 qapi/machine-common.json (limited to 'qapi') diff --git a/qapi/machine-common.json b/qapi/machine-common.json new file mode 100644 index 0000000..fa6bd71 --- /dev/null +++ b/qapi/machine-common.json @@ -0,0 +1,21 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. + +## +# = Machines S390 data types +## + +## +# @CpuS390Entitlement: +# +# An enumeration of CPU entitlements that can be assumed by a virtual +# S390 CPU +# +# Since: 8.2 +## +{ 'enum': 'CpuS390Entitlement', + 'prefix': 'S390_CPU_ENTITLEMENT', + 'data': [ 'auto', 'low', 'medium', 'high' ] } diff --git a/qapi/machine.json b/qapi/machine.json index f053245..17b69a6 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -9,6 +9,7 @@ ## { 'include': 'common.json' } +{ 'include': 'machine-common.json' } ## # @SysEmuTarget: @@ -907,7 +908,13 @@ # # @node-id: NUMA node ID the CPU belongs to # -# @socket-id: socket number within CPU topology the CPU belongs to +# @drawer-id: drawer number within CPU topology the CPU belongs to +# (since 8.2) +# +# @book-id: book number within parent container the CPU belongs to +# (since 8.2) +# +# @socket-id: socket number within parent container the CPU belongs to # # @die-id: die number within the parent container the CPU belongs to # (since 4.1) @@ -928,6 +935,8 @@ { 'struct': 'CpuInstanceProperties', # Keep these in sync with the properties device_add accepts 'data': { '*node-id': 'int', + '*drawer-id': 'int', + '*book-id': 'int', '*socket-id': 'int', '*die-id': 'int', '*cluster-id': 'int', @@ -1488,7 +1497,7 @@ # containers. # # The ordering from highest/coarsest to lowest/finest is: -# @sockets, @dies, @clusters, @cores, @threads. +# @drawers, @books, @sockets, @dies, @clusters, @cores, @threads. # # Different architectures support different subsets of topology # containers. @@ -1501,7 +1510,11 @@ # @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual # machine # -# @sockets: number of sockets in the CPU topology +# @drawers: number of drawers in the CPU topology (since 8.2) +# +# @books: number of books in the CPU topology (since 8.2) +# +# @sockets: number of sockets per parent container # # @dies: number of dies per parent container # @@ -1515,6 +1528,8 @@ ## { 'struct': 'SMPConfiguration', 'data': { '*cpus': 'int', + '*drawers': 'int', + '*books': 'int', '*sockets': 'int', '*dies': 'int', '*clusters': 'int', diff --git a/qapi/meson.build b/qapi/meson.build index 60a668b..f81a375 100644 --- a/qapi/meson.build +++ b/qapi/meson.build @@ -36,6 +36,7 @@ qapi_all_modules = [ 'error', 'introspect', 'job', + 'machine-common', 'machine', 'machine-target', 'migration', diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 6594afb..c01ec33 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -66,6 +66,7 @@ { 'include': 'introspect.json' } { 'include': 'qom.json' } { 'include': 'qdev.json' } +{ 'include': 'machine-common.json' } { 'include': 'machine.json' } { 'include': 'machine-target.json' } { 'include': 'replay.json' } -- cgit v1.1 From f4f54b582f4b78f4cfd5a6912e88aef4f11e3e3c Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Mon, 16 Oct 2023 20:39:08 +0200 Subject: target/s390x/cpu topology: handle STSI(15) and build the SYSIB On interception of STSI(15.1.x) the System Information Block (SYSIB) is built from the list of pre-ordered topology entries. Signed-off-by: Pierre Morel Reviewed-by: Nina Schoetterl-Glausch Co-developed-by: Nina Schoetterl-Glausch Reviewed-by: Thomas Huth Acked-by: Markus Armbruster Signed-off-by: Nina Schoetterl-Glausch Message-ID: <20231016183925.2384704-5-nsg@linux.ibm.com> Signed-off-by: Thomas Huth --- qapi/machine-target.json | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'qapi') diff --git a/qapi/machine-target.json b/qapi/machine-target.json index f0a6b72..93cbf1c 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -361,3 +361,17 @@ 'TARGET_MIPS', 'TARGET_LOONGARCH64', 'TARGET_RISCV' ] } } + +## +# @CpuS390Polarization: +# +# An enumeration of CPU polarization that can be assumed by a virtual +# S390 CPU +# +# Since: 8.2 +## +{ 'enum': 'CpuS390Polarization', + 'prefix': 'S390_CPU_POLARIZATION', + 'data': [ 'horizontal', 'vertical' ], + 'if': 'TARGET_S390X' +} -- cgit v1.1 From a457c2ab5af7d69fd96f0aef2d33800bdc082b8c Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Mon, 16 Oct 2023 20:39:13 +0200 Subject: qapi/s390x/cpu topology: set-cpu-topology qmp command The modification of the CPU attributes are done through a monitor command. It allows to move the core inside the topology tree to optimize the cache usage in the case the host's hypervisor previously moved the CPU. The same command allows to modify the CPU attributes modifiers like polarization entitlement and the dedicated attribute to notify the guest if the host admin modified scheduling or dedication of a vCPU. With this knowledge the guest has the possibility to optimize the usage of the vCPUs. The command has a feature unstable for the moment. Signed-off-by: Pierre Morel Reviewed-by: Nina Schoetterl-Glausch Co-developed-by: Nina Schoetterl-Glausch Reviewed-by: Thomas Huth Signed-off-by: Nina Schoetterl-Glausch Acked-by: Markus Armbruster Message-ID: <20231016183925.2384704-10-nsg@linux.ibm.com> Signed-off-by: Thomas Huth --- qapi/machine-target.json | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'qapi') diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 93cbf1c..7688f32 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -4,6 +4,8 @@ # This work is licensed under the terms of the GNU GPL, version 2 or later. # See the COPYING file in the top-level directory. +{ 'include': 'machine-common.json' } + ## # @CpuModelInfo: # @@ -375,3 +377,43 @@ 'data': [ 'horizontal', 'vertical' ], 'if': 'TARGET_S390X' } + +## +# @set-cpu-topology: +# +# Modify the topology by moving the CPU inside the topology tree, +# or by changing a modifier attribute of a CPU. +# Absent values will not be modified. +# +# @core-id: the vCPU ID to be moved +# +# @socket-id: destination socket to move the vCPU to +# +# @book-id: destination book to move the vCPU to +# +# @drawer-id: destination drawer to move the vCPU to +# +# @entitlement: entitlement to set +# +# @dedicated: whether the provisioning of real to virtual CPU is dedicated +# +# Features: +# +# @unstable: This command is experimental. +# +# Returns: Nothing on success. +# +# Since: 8.2 +## +{ 'command': 'set-cpu-topology', + 'data': { + 'core-id': 'uint16', + '*socket-id': 'uint16', + '*book-id': 'uint16', + '*drawer-id': 'uint16', + '*entitlement': 'CpuS390Entitlement', + '*dedicated': 'bool' + }, + 'features': [ 'unstable' ], + 'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] } +} -- cgit v1.1 From ad2d1afc1d7158e1d94f6f7a3efe6efc15dca51c Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Mon, 16 Oct 2023 20:39:14 +0200 Subject: machine: adding s390 topology to query-cpu-fast S390x provides two more topology attributes, entitlement and dedication. Let's add these CPU attributes to the QAPI command query-cpu-fast. Signed-off-by: Pierre Morel Reviewed-by: Nina Schoetterl-Glausch Co-developed-by: Nina Schoetterl-Glausch Reviewed-by: Thomas Huth Acked-by: Markus Armbruster Signed-off-by: Nina Schoetterl-Glausch Message-ID: <20231016183925.2384704-11-nsg@linux.ibm.com> Signed-off-by: Thomas Huth --- qapi/machine.json | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'qapi') diff --git a/qapi/machine.json b/qapi/machine.json index 17b69a6..b4bd26f 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -57,9 +57,16 @@ # # @cpu-state: the virtual CPU's state # +# @dedicated: the virtual CPU's dedication (since 8.2) +# +# @entitlement: the virtual CPU's entitlement (since 8.2) +# # Since: 2.12 ## -{ 'struct': 'CpuInfoS390', 'data': { 'cpu-state': 'CpuS390State' } } +{ 'struct': 'CpuInfoS390', + 'data': { 'cpu-state': 'CpuS390State', + '*dedicated': 'bool', + '*entitlement': 'CpuS390Entitlement' } } ## # @CpuInfoFast: -- cgit v1.1 From 1cfe52b7824067962357493475f0c36c7900f799 Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Mon, 16 Oct 2023 20:39:16 +0200 Subject: qapi/s390x/cpu topology: CPU_POLARIZATION_CHANGE QAPI event When the guest asks to change the polarization this change is forwarded to the upper layer using QAPI. The upper layer is supposed to take according decisions concerning CPU provisioning. Signed-off-by: Pierre Morel Reviewed-by: Thomas Huth Reviewed-by: Nina Schoetterl-Glausch Co-developed-by: Nina Schoetterl-Glausch Acked-by: Markus Armbruster Signed-off-by: Nina Schoetterl-Glausch Message-ID: <20231016183925.2384704-13-nsg@linux.ibm.com> Signed-off-by: Thomas Huth --- qapi/machine-target.json | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'qapi') diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 7688f32..ac93a5f 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -417,3 +417,38 @@ 'features': [ 'unstable' ], 'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] } } + +## +# @CPU_POLARIZATION_CHANGE: +# +# Emitted when the guest asks to change the polarization. +# +# The guest can tell the host (via the PTF instruction) whether the +# CPUs should be provisioned using horizontal or vertical polarization. +# +# On horizontal polarization the host is expected to provision all vCPUs +# equally. +# +# On vertical polarization the host can provision each vCPU differently. +# The guest will get information on the details of the provisioning +# the next time it uses the STSI(15) instruction. +# +# @polarization: polarization specified by the guest +# +# Features: +# +# @unstable: This event is experimental. +# +# Since: 8.2 +# +# Example: +# +# <- { "event": "CPU_POLARIZATION_CHANGE", +# "data": { "polarization": "horizontal" }, +# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +## +{ 'event': 'CPU_POLARIZATION_CHANGE', + 'data': { 'polarization': 'CpuS390Polarization' }, + 'features': [ 'unstable' ], + 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } +} -- cgit v1.1 From 154893a784cb3f1349fce65ab6038e0bc462d218 Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Mon, 16 Oct 2023 20:39:17 +0200 Subject: qapi/s390x/cpu topology: add query-s390x-cpu-polarization command The query-s390x-cpu-polarization qmp command returns the current CPU polarization of the machine. Signed-off-by: Pierre Morel Reviewed-by: Thomas Huth Reviewed-by: Nina Schoetterl-Glausch Co-developed-by: Nina Schoetterl-Glausch Acked-by: Markus Armbruster Signed-off-by: Nina Schoetterl-Glausch Message-ID: <20231016183925.2384704-14-nsg@linux.ibm.com> Signed-off-by: Thomas Huth --- qapi/machine-target.json | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'qapi') diff --git a/qapi/machine-target.json b/qapi/machine-target.json index ac93a5f..4e55adb 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -452,3 +452,33 @@ 'features': [ 'unstable' ], 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } } + +## +# @CpuPolarizationInfo: +# +# The result of a CPU polarization query. +# +# @polarization: the CPU polarization +# +# Since: 8.2 +## +{ 'struct': 'CpuPolarizationInfo', + 'data': { 'polarization': 'CpuS390Polarization' }, + 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } +} + +## +# @query-s390x-cpu-polarization: +# +# Features: +# +# @unstable: This command is experimental. +# +# Returns: the machine's CPU polarization +# +# Since: 8.2 +## +{ 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo', + 'features': [ 'unstable' ], + 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } +} -- cgit v1.1 From 0d177cdd2ba402f7f0aee301e56037311c7a8781 Mon Sep 17 00:00:00 2001 From: Pierre Morel Date: Mon, 16 Oct 2023 20:39:18 +0200 Subject: docs/s390x/cpu topology: document s390x cpu topology Add some basic examples for the definition of cpu topology in s390x. Signed-off-by: Pierre Morel Co-developed-by: Nina Schoetterl-Glausch Reviewed-by: Thomas Huth Signed-off-by: Nina Schoetterl-Glausch Message-ID: <20231016183925.2384704-15-nsg@linux.ibm.com> Signed-off-by: Thomas Huth --- qapi/machine.json | 2 ++ 1 file changed, 2 insertions(+) (limited to 'qapi') diff --git a/qapi/machine.json b/qapi/machine.json index b4bd26f..6c9d2f6 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -909,6 +909,8 @@ # Which members are optional and which mandatory depends on the # architecture and board. # +# For s390x see :ref:`cpu-topology-s390x`. +# # 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) -- cgit v1.1