Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 1 | # -*- Mode: Python -*- |
Andrea Bolognani | f7160f3 | 2020-07-29 20:50:24 +0200 | [diff] [blame] | 2 | # vim: filetype=python |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 3 | # |
| 4 | # This work is licensed under the terms of the GNU GPL, version 2 or later. |
| 5 | # See the COPYING file in the top-level directory. |
| 6 | |
Pierre Morel | a457c2a | 2023-10-16 20:39:13 +0200 | [diff] [blame] | 7 | { 'include': 'machine-common.json' } |
| 8 | |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 9 | ## |
| 10 | # @CpuModelInfo: |
| 11 | # |
| 12 | # Virtual CPU model. |
| 13 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 14 | # A CPU model consists of the name of a CPU definition, to which delta |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 15 | # changes are applied (e.g. features added/removed). Most magic |
| 16 | # values that an architecture might require should be hidden behind |
| 17 | # the name. However, if required, architectures can expose relevant |
| 18 | # properties. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 19 | # |
| 20 | # @name: the name of the CPU definition the model is based on |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 21 | # |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 22 | # @props: a dictionary of QOM properties to be applied |
| 23 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 24 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 25 | ## |
| 26 | { 'struct': 'CpuModelInfo', |
| 27 | 'data': { 'name': 'str', |
Collin Walling | 442110b | 2024-07-26 16:36:46 -0400 | [diff] [blame] | 28 | '*props': 'any' } } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 29 | |
| 30 | ## |
| 31 | # @CpuModelExpansionType: |
| 32 | # |
| 33 | # An enumeration of CPU model expansion types. |
| 34 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 35 | # @static: Expand to a static CPU model, a combination of a static |
| 36 | # base model name and property delta changes. As the static base |
| 37 | # model will never change, the expanded CPU model will be the |
| 38 | # same, independent of QEMU version, machine type, machine |
| 39 | # options, and accelerator options. Therefore, the resulting |
| 40 | # model can be used by tooling without having to specify a |
| 41 | # compatibility machine - e.g. when displaying the "host" model. |
| 42 | # The @static CPU models are migration-safe. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 43 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 44 | # @full: Expand all properties. The produced model is not guaranteed |
| 45 | # to be migration-safe, but allows tooling to get an insight and |
| 46 | # work with model details. |
| 47 | # |
John Snow | d461c27 | 2024-06-26 18:21:16 -0400 | [diff] [blame] | 48 | # .. note:: When a non-migration-safe CPU model is expanded in static |
| 49 | # mode, some features enabled by the CPU model may be omitted, |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 50 | # because they can't be implemented by a static CPU model |
| 51 | # definition (e.g. cache info passthrough and PMU passthrough in |
| 52 | # x86). If you need an accurate representation of the features |
| 53 | # enabled by a non-migration-safe CPU model, use @full. If you |
| 54 | # need a static representation that will keep ABI compatibility |
| 55 | # even when changing QEMU version or machine-type, use @static (but |
| 56 | # keep in mind that some features may be omitted). |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 57 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 58 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 59 | ## |
| 60 | { 'enum': 'CpuModelExpansionType', |
| 61 | 'data': [ 'static', 'full' ] } |
| 62 | |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 63 | ## |
| 64 | # @CpuModelCompareResult: |
| 65 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 66 | # An enumeration of CPU model comparison results. The result is |
Markus Armbruster | 9e27207 | 2023-07-20 09:16:09 +0200 | [diff] [blame] | 67 | # usually calculated using e.g. CPU features or CPU generations. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 68 | # |
| 69 | # @incompatible: If model A is incompatible to model B, model A is not |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 70 | # guaranteed to run where model B runs and the other way around. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 71 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 72 | # @identical: If model A is identical to model B, model A is |
| 73 | # guaranteed to run where model B runs and the other way around. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 74 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 75 | # @superset: If model A is a superset of model B, model B is |
| 76 | # guaranteed to run where model A runs. There are no guarantees |
| 77 | # about the other way. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 78 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 79 | # @subset: If model A is a subset of model B, model A is guaranteed to |
| 80 | # run where model B runs. There are no guarantees about the other |
| 81 | # way. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 82 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 83 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 84 | ## |
| 85 | { 'enum': 'CpuModelCompareResult', |
| 86 | 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } |
| 87 | |
| 88 | ## |
| 89 | # @CpuModelBaselineInfo: |
| 90 | # |
| 91 | # The result of a CPU model baseline. |
| 92 | # |
| 93 | # @model: the baselined CpuModelInfo. |
| 94 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 95 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 96 | ## |
| 97 | { 'struct': 'CpuModelBaselineInfo', |
| 98 | 'data': { 'model': 'CpuModelInfo' }, |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 99 | 'if': 'TARGET_S390X' } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 100 | |
| 101 | ## |
| 102 | # @CpuModelCompareInfo: |
| 103 | # |
| 104 | # The result of a CPU model comparison. |
| 105 | # |
| 106 | # @result: The result of the compare operation. |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 107 | # |
| 108 | # @responsible-properties: List of properties that led to the |
| 109 | # comparison result not being identical. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 110 | # |
| 111 | # @responsible-properties is a list of QOM property names that led to |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 112 | # both CPUs not being detected as identical. For identical models, |
| 113 | # this list is empty. If a QOM property is read-only, that means |
| 114 | # there's no known way to make the CPU models identical. If the |
| 115 | # special property name "type" is included, the models are by |
| 116 | # definition not identical and cannot be made identical. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 117 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 118 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 119 | ## |
| 120 | { 'struct': 'CpuModelCompareInfo', |
| 121 | 'data': { 'result': 'CpuModelCompareResult', |
| 122 | 'responsible-properties': ['str'] }, |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 123 | 'if': 'TARGET_S390X' } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 124 | |
| 125 | ## |
| 126 | # @query-cpu-model-comparison: |
| 127 | # |
David Hildenbrand | 1a533ce | 2024-03-25 16:01:41 +0100 | [diff] [blame] | 128 | # Compares two CPU models, @modela and @modelb, returning how they |
| 129 | # compare in a specific configuration. The results indicates how |
| 130 | # both models compare regarding runnability. This result can be |
| 131 | # used by tooling to make decisions if a certain CPU model will |
| 132 | # run in a certain configuration or if a compatible CPU model has |
| 133 | # to be created by baselining. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 134 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 135 | # Usually, a CPU model is compared against the maximum possible CPU |
| 136 | # model of a certain configuration (e.g. the "host" model for KVM). |
| 137 | # If that CPU model is identical or a subset, it will run in that |
| 138 | # configuration. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 139 | # |
| 140 | # The result returned by this command may be affected by: |
| 141 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 142 | # * QEMU version: CPU models may look different depending on the QEMU |
| 143 | # version. (Except for CPU models reported as "static" in |
| 144 | # query-cpu-definitions.) |
| 145 | # * machine-type: CPU model may look different depending on the |
| 146 | # machine-type. (Except for CPU models reported as "static" in |
| 147 | # query-cpu-definitions.) |
| 148 | # * machine options (including accelerator): in some architectures, |
| 149 | # CPU models may look different depending on machine and accelerator |
| 150 | # options. (Except for CPU models reported as "static" in |
| 151 | # query-cpu-definitions.) |
| 152 | # * "-cpu" arguments and global properties: arguments to the -cpu |
| 153 | # option and global properties may affect expansion of CPU models. |
| 154 | # Using query-cpu-model-expansion while using these is not advised. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 155 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 156 | # Some architectures may not support comparing CPU models. s390x |
| 157 | # supports comparing CPU models. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 158 | # |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 159 | # @modela: description of the first CPU model to compare, referred to |
| 160 | # as "model A" in CpuModelCompareResult |
David Hildenbrand | 1a533ce | 2024-03-25 16:01:41 +0100 | [diff] [blame] | 161 | # |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 162 | # @modelb: description of the second CPU model to compare, referred to |
| 163 | # as "model B" in CpuModelCompareResult |
David Hildenbrand | 1a533ce | 2024-03-25 16:01:41 +0100 | [diff] [blame] | 164 | # |
| 165 | # Returns: a CpuModelCompareInfo describing how both CPU models |
| 166 | # compare |
Markus Armbruster | 2746f06 | 2024-02-27 12:39:12 +0100 | [diff] [blame] | 167 | # |
| 168 | # Errors: |
| 169 | # - if comparing CPU models is not supported |
| 170 | # - if a model cannot be used |
| 171 | # - if a model contains an unknown cpu definition name, unknown |
| 172 | # properties or properties with wrong types. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 173 | # |
John Snow | d461c27 | 2024-06-26 18:21:16 -0400 | [diff] [blame] | 174 | # .. note:: This command isn't specific to s390x, but is only |
| 175 | # implemented on this architecture currently. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 176 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 177 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 178 | ## |
| 179 | { 'command': 'query-cpu-model-comparison', |
| 180 | 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, |
| 181 | 'returns': 'CpuModelCompareInfo', |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 182 | 'if': 'TARGET_S390X' } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 183 | |
| 184 | ## |
| 185 | # @query-cpu-model-baseline: |
| 186 | # |
David Hildenbrand | 1a533ce | 2024-03-25 16:01:41 +0100 | [diff] [blame] | 187 | # Baseline two CPU models, @modela and @modelb, creating a compatible |
| 188 | # third model. The created model will always be a static, |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 189 | # migration-safe CPU model (see "static" CPU model expansion for |
| 190 | # details). |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 191 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 192 | # This interface can be used by tooling to create a compatible CPU |
| 193 | # model out two CPU models. The created CPU model will be identical |
| 194 | # to or a subset of both CPU models when comparing them. Therefore, |
| 195 | # the created CPU model is guaranteed to run where the given CPU |
| 196 | # models run. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 197 | # |
| 198 | # The result returned by this command may be affected by: |
| 199 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 200 | # * QEMU version: CPU models may look different depending on the QEMU |
| 201 | # version. (Except for CPU models reported as "static" in |
| 202 | # query-cpu-definitions.) |
| 203 | # * machine-type: CPU model may look different depending on the |
| 204 | # machine-type. (Except for CPU models reported as "static" in |
| 205 | # query-cpu-definitions.) |
| 206 | # * machine options (including accelerator): in some architectures, |
| 207 | # CPU models may look different depending on machine and accelerator |
| 208 | # options. (Except for CPU models reported as "static" in |
| 209 | # query-cpu-definitions.) |
| 210 | # * "-cpu" arguments and global properties: arguments to the -cpu |
| 211 | # option and global properties may affect expansion of CPU models. |
| 212 | # Using query-cpu-model-expansion while using these is not advised. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 213 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 214 | # Some architectures may not support baselining CPU models. s390x |
| 215 | # supports baselining CPU models. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 216 | # |
David Hildenbrand | 1a533ce | 2024-03-25 16:01:41 +0100 | [diff] [blame] | 217 | # @modela: description of the first CPU model to baseline |
| 218 | # |
| 219 | # @modelb: description of the second CPU model to baseline |
| 220 | # |
| 221 | # Returns: a CpuModelBaselineInfo describing the baselined CPU model |
Markus Armbruster | 2746f06 | 2024-02-27 12:39:12 +0100 | [diff] [blame] | 222 | # |
| 223 | # Errors: |
| 224 | # - if baselining CPU models is not supported |
| 225 | # - if a model cannot be used |
| 226 | # - if a model contains an unknown cpu definition name, unknown |
| 227 | # properties or properties with wrong types. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 228 | # |
John Snow | d461c27 | 2024-06-26 18:21:16 -0400 | [diff] [blame] | 229 | # .. note:: This command isn't specific to s390x, but is only |
| 230 | # implemented on this architecture currently. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 231 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 232 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 233 | ## |
| 234 | { 'command': 'query-cpu-model-baseline', |
| 235 | 'data': { 'modela': 'CpuModelInfo', |
| 236 | 'modelb': 'CpuModelInfo' }, |
| 237 | 'returns': 'CpuModelBaselineInfo', |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 238 | 'if': 'TARGET_S390X' } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 239 | |
| 240 | ## |
| 241 | # @CpuModelExpansionInfo: |
| 242 | # |
| 243 | # The result of a cpu model expansion. |
| 244 | # |
| 245 | # @model: the expanded CpuModelInfo. |
| 246 | # |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 247 | # @deprecated-props: a list of properties that are flagged as |
| 248 | # deprecated by the CPU vendor. The list depends on the |
| 249 | # CpuModelExpansionType: "static" properties are a subset of the |
| 250 | # enabled-properties for the expanded model; "full" properties are |
| 251 | # a set of properties that are deprecated across all models for |
| 252 | # the architecture. (since: 9.1). |
Collin Walling | 442110b | 2024-07-26 16:36:46 -0400 | [diff] [blame] | 253 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 254 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 255 | ## |
| 256 | { 'struct': 'CpuModelExpansionInfo', |
Collin Walling | 442110b | 2024-07-26 16:36:46 -0400 | [diff] [blame] | 257 | 'data': { 'model': 'CpuModelInfo', |
| 258 | 'deprecated-props' : { 'type': ['str'], |
| 259 | 'if': 'TARGET_S390X' } }, |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 260 | 'if': { 'any': [ 'TARGET_S390X', |
| 261 | 'TARGET_I386', |
Song Gao | 31f694b | 2023-10-20 16:49:25 +0800 | [diff] [blame] | 262 | 'TARGET_ARM', |
Daniel Henrique Barboza | aeb2bc5 | 2023-10-18 16:56:34 -0300 | [diff] [blame] | 263 | 'TARGET_LOONGARCH64', |
| 264 | 'TARGET_RISCV' ] } } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 265 | |
| 266 | ## |
| 267 | # @query-cpu-model-expansion: |
| 268 | # |
David Hildenbrand | 1a533ce | 2024-03-25 16:01:41 +0100 | [diff] [blame] | 269 | # Expands a given CPU model, @model, (or a combination of CPU model + |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 270 | # additional options) to different granularities, specified by @type, |
| 271 | # allowing tooling to get an understanding what a specific CPU model |
| 272 | # looks like in QEMU under a certain configuration. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 273 | # |
| 274 | # This interface can be used to query the "host" CPU model. |
| 275 | # |
| 276 | # The data returned by this command may be affected by: |
| 277 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 278 | # * QEMU version: CPU models may look different depending on the QEMU |
| 279 | # version. (Except for CPU models reported as "static" in |
| 280 | # query-cpu-definitions.) |
| 281 | # * machine-type: CPU model may look different depending on the |
| 282 | # machine-type. (Except for CPU models reported as "static" in |
| 283 | # query-cpu-definitions.) |
| 284 | # * machine options (including accelerator): in some architectures, |
| 285 | # CPU models may look different depending on machine and accelerator |
| 286 | # options. (Except for CPU models reported as "static" in |
| 287 | # query-cpu-definitions.) |
| 288 | # * "-cpu" arguments and global properties: arguments to the -cpu |
| 289 | # option and global properties may affect expansion of CPU models. |
| 290 | # Using query-cpu-model-expansion while using these is not advised. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 291 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 292 | # Some architectures may not support all expansion types. s390x |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 293 | # supports "full" and "static". Arm only supports "full". |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 294 | # |
David Hildenbrand | 1a533ce | 2024-03-25 16:01:41 +0100 | [diff] [blame] | 295 | # @model: description of the CPU model to expand |
| 296 | # |
| 297 | # @type: expansion type, specifying how to expand the CPU model |
| 298 | # |
| 299 | # Returns: a CpuModelExpansionInfo describing the expanded CPU model |
Markus Armbruster | 2746f06 | 2024-02-27 12:39:12 +0100 | [diff] [blame] | 300 | # |
| 301 | # Errors: |
| 302 | # - if expanding CPU models is not supported |
| 303 | # - if the model cannot be expanded |
| 304 | # - if the model contains an unknown CPU definition name, unknown |
| 305 | # properties or properties with a wrong type |
| 306 | # - if an expansion type is not supported |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 307 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 308 | # Since: 2.8 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 309 | ## |
| 310 | { 'command': 'query-cpu-model-expansion', |
| 311 | 'data': { 'type': 'CpuModelExpansionType', |
| 312 | 'model': 'CpuModelInfo' }, |
| 313 | 'returns': 'CpuModelExpansionInfo', |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 314 | 'if': { 'any': [ 'TARGET_S390X', |
| 315 | 'TARGET_I386', |
Song Gao | 31f694b | 2023-10-20 16:49:25 +0800 | [diff] [blame] | 316 | 'TARGET_ARM', |
Daniel Henrique Barboza | aeb2bc5 | 2023-10-18 16:56:34 -0300 | [diff] [blame] | 317 | 'TARGET_LOONGARCH64', |
| 318 | 'TARGET_RISCV' ] } } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 319 | |
| 320 | ## |
| 321 | # @CpuDefinitionInfo: |
| 322 | # |
| 323 | # Virtual CPU definition. |
| 324 | # |
| 325 | # @name: the name of the CPU definition |
| 326 | # |
| 327 | # @migration-safe: whether a CPU definition can be safely used for |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 328 | # migration in combination with a QEMU compatibility machine when |
| 329 | # migrating between different QEMU versions and between hosts with |
| 330 | # different sets of (hardware or software) capabilities. If not |
| 331 | # provided, information is not available and callers should not |
| 332 | # assume the CPU definition to be migration-safe. (since 2.8) |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 333 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 334 | # @static: whether a CPU definition is static and will not change |
| 335 | # depending on QEMU version, machine type, machine options and |
| 336 | # accelerator options. A static model is always migration-safe. |
| 337 | # (since 2.8) |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 338 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 339 | # @unavailable-features: List of properties that prevent the CPU model |
| 340 | # from running in the current host. (since 2.8) |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 341 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 342 | # @typename: Type name that can be used as argument to |
| 343 | # @device-list-properties, to introspect properties configurable |
| 344 | # using -cpu or -global. (since 2.9) |
Eduardo Habkost | 7d753f6 | 2019-06-27 21:28:36 -0300 | [diff] [blame] | 345 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 346 | # @alias-of: Name of CPU model this model is an alias for. The target |
| 347 | # of the CPU model alias may change depending on the machine type. |
| 348 | # Management software is supposed to translate CPU model aliases |
| 349 | # in the VM configuration, because aliases may stop being |
| 350 | # migration-safe in the future (since 4.1) |
Robert Hoo | 61ad65d | 2020-09-22 15:14:14 +0800 | [diff] [blame] | 351 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 352 | # @deprecated: If true, this CPU model is deprecated and may be |
| 353 | # removed in in some future version of QEMU according to the QEMU |
| 354 | # deprecation policy. (since 5.2) |
| 355 | # |
| 356 | # @unavailable-features is a list of QOM property names that represent |
| 357 | # CPU model attributes that prevent the CPU from running. If the QOM |
| 358 | # property is read-only, that means there's no known way to make the |
| 359 | # CPU model run in the current host. Implementations that choose not |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 360 | # to provide specific information return the property name "type". If |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 361 | # the property is read-write, it means that it MAY be possible to run |
| 362 | # the CPU model in the current host if that property is changed. |
| 363 | # Management software can use it as hints to suggest or choose an |
| 364 | # alternative for the user, or just to generate meaningful error |
| 365 | # messages explaining why the CPU model can't be used. If |
| 366 | # @unavailable-features is an empty list, the CPU model is runnable |
| 367 | # using the current host and machine-type. If @unavailable-features |
| 368 | # is not present, runnability information for the CPU is not |
| 369 | # available. |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 370 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 371 | # Since: 1.2 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 372 | ## |
| 373 | { 'struct': 'CpuDefinitionInfo', |
| 374 | 'data': { 'name': 'str', |
| 375 | '*migration-safe': 'bool', |
| 376 | 'static': 'bool', |
| 377 | '*unavailable-features': [ 'str' ], |
Eduardo Habkost | 7d753f6 | 2019-06-27 21:28:36 -0300 | [diff] [blame] | 378 | 'typename': 'str', |
Robert Hoo | 61ad65d | 2020-09-22 15:14:14 +0800 | [diff] [blame] | 379 | '*alias-of' : 'str', |
| 380 | 'deprecated' : 'bool' }, |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 381 | 'if': { 'any': [ 'TARGET_PPC', |
| 382 | 'TARGET_ARM', |
| 383 | 'TARGET_I386', |
| 384 | 'TARGET_S390X', |
Xiaojuan Yang | 425876f | 2022-06-06 20:43:11 +0800 | [diff] [blame] | 385 | 'TARGET_MIPS', |
Daniel Henrique Barboza | c0177f9 | 2023-04-11 15:35:10 -0300 | [diff] [blame] | 386 | 'TARGET_LOONGARCH64', |
| 387 | 'TARGET_RISCV' ] } } |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 388 | |
| 389 | ## |
| 390 | # @query-cpu-definitions: |
| 391 | # |
| 392 | # Return a list of supported virtual CPU definitions |
| 393 | # |
Markus Armbruster | d93ed1b | 2023-04-25 08:42:10 +0200 | [diff] [blame] | 394 | # Returns: a list of CpuDefinitionInfo |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 395 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 396 | # Since: 1.2 |
Markus Armbruster | 7f7b4e7 | 2019-06-19 22:10:45 +0200 | [diff] [blame] | 397 | ## |
| 398 | { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], |
Marc-André Lureau | 8a9f1e1 | 2021-08-04 12:31:05 +0400 | [diff] [blame] | 399 | 'if': { 'any': [ 'TARGET_PPC', |
| 400 | 'TARGET_ARM', |
| 401 | 'TARGET_I386', |
| 402 | 'TARGET_S390X', |
Xiaojuan Yang | 425876f | 2022-06-06 20:43:11 +0800 | [diff] [blame] | 403 | 'TARGET_MIPS', |
Daniel Henrique Barboza | c0177f9 | 2023-04-11 15:35:10 -0300 | [diff] [blame] | 404 | 'TARGET_LOONGARCH64', |
| 405 | 'TARGET_RISCV' ] } } |
Pierre Morel | f4f54b5 | 2023-10-16 20:39:08 +0200 | [diff] [blame] | 406 | |
| 407 | ## |
Markus Armbruster | 32cfefb | 2024-09-04 13:18:26 +0200 | [diff] [blame] | 408 | # @S390CpuPolarization: |
Pierre Morel | f4f54b5 | 2023-10-16 20:39:08 +0200 | [diff] [blame] | 409 | # |
| 410 | # An enumeration of CPU polarization that can be assumed by a virtual |
| 411 | # S390 CPU |
| 412 | # |
| 413 | # Since: 8.2 |
| 414 | ## |
Markus Armbruster | 32cfefb | 2024-09-04 13:18:26 +0200 | [diff] [blame] | 415 | { 'enum': 'S390CpuPolarization', |
Pierre Morel | f4f54b5 | 2023-10-16 20:39:08 +0200 | [diff] [blame] | 416 | 'data': [ 'horizontal', 'vertical' ], |
| 417 | 'if': 'TARGET_S390X' |
| 418 | } |
Pierre Morel | a457c2a | 2023-10-16 20:39:13 +0200 | [diff] [blame] | 419 | |
| 420 | ## |
| 421 | # @set-cpu-topology: |
| 422 | # |
Markus Armbruster | 209e64d | 2024-03-22 15:09:08 +0100 | [diff] [blame] | 423 | # Modify the topology by moving the CPU inside the topology tree, or |
| 424 | # by changing a modifier attribute of a CPU. Absent values will not |
| 425 | # be modified. |
Pierre Morel | a457c2a | 2023-10-16 20:39:13 +0200 | [diff] [blame] | 426 | # |
| 427 | # @core-id: the vCPU ID to be moved |
| 428 | # |
| 429 | # @socket-id: destination socket to move the vCPU to |
| 430 | # |
| 431 | # @book-id: destination book to move the vCPU to |
| 432 | # |
| 433 | # @drawer-id: destination drawer to move the vCPU to |
| 434 | # |
| 435 | # @entitlement: entitlement to set |
| 436 | # |
Markus Armbruster | 209e64d | 2024-03-22 15:09:08 +0100 | [diff] [blame] | 437 | # @dedicated: whether the provisioning of real to virtual CPU is |
| 438 | # dedicated |
Pierre Morel | a457c2a | 2023-10-16 20:39:13 +0200 | [diff] [blame] | 439 | # |
| 440 | # Features: |
| 441 | # |
| 442 | # @unstable: This command is experimental. |
| 443 | # |
Pierre Morel | a457c2a | 2023-10-16 20:39:13 +0200 | [diff] [blame] | 444 | # Since: 8.2 |
| 445 | ## |
| 446 | { 'command': 'set-cpu-topology', |
| 447 | 'data': { |
| 448 | 'core-id': 'uint16', |
| 449 | '*socket-id': 'uint16', |
| 450 | '*book-id': 'uint16', |
| 451 | '*drawer-id': 'uint16', |
Markus Armbruster | 32cfefb | 2024-09-04 13:18:26 +0200 | [diff] [blame] | 452 | '*entitlement': 'S390CpuEntitlement', |
Pierre Morel | a457c2a | 2023-10-16 20:39:13 +0200 | [diff] [blame] | 453 | '*dedicated': 'bool' |
| 454 | }, |
| 455 | 'features': [ 'unstable' ], |
| 456 | 'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] } |
| 457 | } |
Pierre Morel | 1cfe52b | 2023-10-16 20:39:16 +0200 | [diff] [blame] | 458 | |
| 459 | ## |
| 460 | # @CPU_POLARIZATION_CHANGE: |
| 461 | # |
| 462 | # Emitted when the guest asks to change the polarization. |
| 463 | # |
| 464 | # The guest can tell the host (via the PTF instruction) whether the |
Markus Armbruster | 209e64d | 2024-03-22 15:09:08 +0100 | [diff] [blame] | 465 | # CPUs should be provisioned using horizontal or vertical |
| 466 | # polarization. |
Pierre Morel | 1cfe52b | 2023-10-16 20:39:16 +0200 | [diff] [blame] | 467 | # |
Markus Armbruster | 209e64d | 2024-03-22 15:09:08 +0100 | [diff] [blame] | 468 | # On horizontal polarization the host is expected to provision all |
| 469 | # vCPUs equally. |
Pierre Morel | 1cfe52b | 2023-10-16 20:39:16 +0200 | [diff] [blame] | 470 | # |
Markus Armbruster | 209e64d | 2024-03-22 15:09:08 +0100 | [diff] [blame] | 471 | # On vertical polarization the host can provision each vCPU |
| 472 | # differently. The guest will get information on the details of the |
| 473 | # provisioning the next time it uses the STSI(15) instruction. |
Pierre Morel | 1cfe52b | 2023-10-16 20:39:16 +0200 | [diff] [blame] | 474 | # |
| 475 | # @polarization: polarization specified by the guest |
| 476 | # |
| 477 | # Features: |
| 478 | # |
| 479 | # @unstable: This event is experimental. |
| 480 | # |
| 481 | # Since: 8.2 |
| 482 | # |
John Snow | 14b48aa | 2024-07-16 22:13:08 -0400 | [diff] [blame] | 483 | # .. qmp-example:: |
Pierre Morel | 1cfe52b | 2023-10-16 20:39:16 +0200 | [diff] [blame] | 484 | # |
Markus Armbruster | d23055b | 2024-02-16 15:58:34 +0100 | [diff] [blame] | 485 | # <- { "event": "CPU_POLARIZATION_CHANGE", |
| 486 | # "data": { "polarization": "horizontal" }, |
| 487 | # "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } |
Pierre Morel | 1cfe52b | 2023-10-16 20:39:16 +0200 | [diff] [blame] | 488 | ## |
| 489 | { 'event': 'CPU_POLARIZATION_CHANGE', |
Markus Armbruster | 32cfefb | 2024-09-04 13:18:26 +0200 | [diff] [blame] | 490 | 'data': { 'polarization': 'S390CpuPolarization' }, |
Pierre Morel | 1cfe52b | 2023-10-16 20:39:16 +0200 | [diff] [blame] | 491 | 'features': [ 'unstable' ], |
| 492 | 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } |
| 493 | } |
Pierre Morel | 154893a | 2023-10-16 20:39:17 +0200 | [diff] [blame] | 494 | |
| 495 | ## |
| 496 | # @CpuPolarizationInfo: |
| 497 | # |
| 498 | # The result of a CPU polarization query. |
| 499 | # |
| 500 | # @polarization: the CPU polarization |
| 501 | # |
| 502 | # Since: 8.2 |
| 503 | ## |
| 504 | { 'struct': 'CpuPolarizationInfo', |
Markus Armbruster | 32cfefb | 2024-09-04 13:18:26 +0200 | [diff] [blame] | 505 | 'data': { 'polarization': 'S390CpuPolarization' }, |
Pierre Morel | 154893a | 2023-10-16 20:39:17 +0200 | [diff] [blame] | 506 | 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } |
| 507 | } |
| 508 | |
| 509 | ## |
| 510 | # @query-s390x-cpu-polarization: |
| 511 | # |
| 512 | # Features: |
| 513 | # |
| 514 | # @unstable: This command is experimental. |
| 515 | # |
| 516 | # Returns: the machine's CPU polarization |
| 517 | # |
| 518 | # Since: 8.2 |
| 519 | ## |
| 520 | { 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo', |
| 521 | 'features': [ 'unstable' ], |
| 522 | 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } |
| 523 | } |