target/riscv: vector register gather instruction
[qemu.git] / qapi / machine-target.json
1 # -*- Mode: Python -*-
2 #
3 # This work is licensed under the terms of the GNU GPL, version 2 or later.
4 # See the COPYING file in the top-level directory.
5
6 ##
7 # @CpuModelInfo:
8 #
9 # Virtual CPU model.
10 #
11 # A CPU model consists of the name of a CPU definition, to which
12 # delta changes are applied (e.g. features added/removed). Most magic values
13 # that an architecture might require should be hidden behind the name.
14 # However, if required, architectures can expose relevant properties.
15 #
16 # @name: the name of the CPU definition the model is based on
17 # @props: a dictionary of QOM properties to be applied
18 #
19 # Since: 2.8.0
20 ##
21 { 'struct': 'CpuModelInfo',
22   'data': { 'name': 'str',
23             '*props': 'any' } }
24
25 ##
26 # @CpuModelExpansionType:
27 #
28 # An enumeration of CPU model expansion types.
29 #
30 # @static: Expand to a static CPU model, a combination of a static base
31 #          model name and property delta changes. As the static base model will
32 #          never change, the expanded CPU model will be the same, independent of
33 #          QEMU version, machine type, machine options, and accelerator options.
34 #          Therefore, the resulting model can be used by tooling without having
35 #          to specify a compatibility machine - e.g. when displaying the "host"
36 #          model. The @static CPU models are migration-safe.
37
38 # @full: Expand all properties. The produced model is not guaranteed to be
39 #        migration-safe, but allows tooling to get an insight and work with
40 #        model details.
41 #
42 # Note: When a non-migration-safe CPU model is expanded in static mode, some
43 #       features enabled by the CPU model may be omitted, because they can't be
44 #       implemented by a static CPU model definition (e.g. cache info passthrough and
45 #       PMU passthrough in x86). If you need an accurate representation of the
46 #       features enabled by a non-migration-safe CPU model, use @full. If you need a
47 #       static representation that will keep ABI compatibility even when changing QEMU
48 #       version or machine-type, use @static (but keep in mind that some features may
49 #       be omitted).
50 #
51 # Since: 2.8.0
52 ##
53 { 'enum': 'CpuModelExpansionType',
54   'data': [ 'static', 'full' ] }
55
56
57 ##
58 # @CpuModelCompareResult:
59 #
60 # An enumeration of CPU model comparison results. The result is usually
61 # calculated using e.g. CPU features or CPU generations.
62 #
63 # @incompatible: If model A is incompatible to model B, model A is not
64 #                guaranteed to run where model B runs and the other way around.
65 #
66 # @identical: If model A is identical to model B, model A is guaranteed to run
67 #             where model B runs and the other way around.
68 #
69 # @superset: If model A is a superset of model B, model B is guaranteed to run
70 #            where model A runs. There are no guarantees about the other way.
71 #
72 # @subset: If model A is a subset of model B, model A is guaranteed to run
73 #          where model B runs. There are no guarantees about the other way.
74 #
75 # Since: 2.8.0
76 ##
77 { 'enum': 'CpuModelCompareResult',
78   'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
79
80 ##
81 # @CpuModelBaselineInfo:
82 #
83 # The result of a CPU model baseline.
84 #
85 # @model: the baselined CpuModelInfo.
86 #
87 # Since: 2.8.0
88 ##
89 { 'struct': 'CpuModelBaselineInfo',
90   'data': { 'model': 'CpuModelInfo' },
91   'if': 'defined(TARGET_S390X)' }
92
93 ##
94 # @CpuModelCompareInfo:
95 #
96 # The result of a CPU model comparison.
97 #
98 # @result: The result of the compare operation.
99 # @responsible-properties: List of properties that led to the comparison result
100 #                          not being identical.
101 #
102 # @responsible-properties is a list of QOM property names that led to
103 # both CPUs not being detected as identical. For identical models, this
104 # list is empty.
105 # If a QOM property is read-only, that means there's no known way to make the
106 # CPU models identical. If the special property name "type" is included, the
107 # models are by definition not identical and cannot be made identical.
108 #
109 # Since: 2.8.0
110 ##
111 { 'struct': 'CpuModelCompareInfo',
112   'data': { 'result': 'CpuModelCompareResult',
113             'responsible-properties': ['str'] },
114   'if': 'defined(TARGET_S390X)' }
115
116 ##
117 # @query-cpu-model-comparison:
118 #
119 # Compares two CPU models, returning how they compare in a specific
120 # configuration. The results indicates how both models compare regarding
121 # runnability. This result can be used by tooling to make decisions if a
122 # certain CPU model will run in a certain configuration or if a compatible
123 # CPU model has to be created by baselining.
124 #
125 # Usually, a CPU model is compared against the maximum possible CPU model
126 # of a certain configuration (e.g. the "host" model for KVM). If that CPU
127 # model is identical or a subset, it will run in that configuration.
128 #
129 # The result returned by this command may be affected by:
130 #
131 # * QEMU version: CPU models may look different depending on the QEMU version.
132 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
133 # * machine-type: CPU model may look different depending on the machine-type.
134 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
135 # * machine options (including accelerator): in some architectures, CPU models
136 #   may look different depending on machine and accelerator options. (Except for
137 #   CPU models reported as "static" in query-cpu-definitions.)
138 # * "-cpu" arguments and global properties: arguments to the -cpu option and
139 #   global properties may affect expansion of CPU models. Using
140 #   query-cpu-model-expansion while using these is not advised.
141 #
142 # Some architectures may not support comparing CPU models. s390x supports
143 # comparing CPU models.
144 #
145 # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
146 #          not supported, if a model cannot be used, if a model contains
147 #          an unknown cpu definition name, unknown properties or properties
148 #          with wrong types.
149 #
150 # Note: this command isn't specific to s390x, but is only implemented
151 #       on this architecture currently.
152 #
153 # Since: 2.8.0
154 ##
155 { 'command': 'query-cpu-model-comparison',
156   'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
157   'returns': 'CpuModelCompareInfo',
158   'if': 'defined(TARGET_S390X)' }
159
160 ##
161 # @query-cpu-model-baseline:
162 #
163 # Baseline two CPU models, creating a compatible third model. The created
164 # model will always be a static, migration-safe CPU model (see "static"
165 # CPU model expansion for details).
166 #
167 # This interface can be used by tooling to create a compatible CPU model out
168 # two CPU models. The created CPU model will be identical to or a subset of
169 # both CPU models when comparing them. Therefore, the created CPU model is
170 # guaranteed to run where the given CPU models run.
171 #
172 # The result returned by this command may be affected by:
173 #
174 # * QEMU version: CPU models may look different depending on the QEMU version.
175 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
176 # * machine-type: CPU model may look different depending on the machine-type.
177 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
178 # * machine options (including accelerator): in some architectures, CPU models
179 #   may look different depending on machine and accelerator options. (Except for
180 #   CPU models reported as "static" in query-cpu-definitions.)
181 # * "-cpu" arguments and global properties: arguments to the -cpu option and
182 #   global properties may affect expansion of CPU models. Using
183 #   query-cpu-model-expansion while using these is not advised.
184 #
185 # Some architectures may not support baselining CPU models. s390x supports
186 # baselining CPU models.
187 #
188 # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
189 #          not supported, if a model cannot be used, if a model contains
190 #          an unknown cpu definition name, unknown properties or properties
191 #          with wrong types.
192 #
193 # Note: this command isn't specific to s390x, but is only implemented
194 #       on this architecture currently.
195 #
196 # Since: 2.8.0
197 ##
198 { 'command': 'query-cpu-model-baseline',
199   'data': { 'modela': 'CpuModelInfo',
200             'modelb': 'CpuModelInfo' },
201   'returns': 'CpuModelBaselineInfo',
202   'if': 'defined(TARGET_S390X)' }
203
204 ##
205 # @CpuModelExpansionInfo:
206 #
207 # The result of a cpu model expansion.
208 #
209 # @model: the expanded CpuModelInfo.
210 #
211 # Since: 2.8.0
212 ##
213 { 'struct': 'CpuModelExpansionInfo',
214   'data': { 'model': 'CpuModelInfo' },
215   'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
216
217 ##
218 # @query-cpu-model-expansion:
219 #
220 # Expands a given CPU model (or a combination of CPU model + additional options)
221 # to different granularities, allowing tooling to get an understanding what a
222 # specific CPU model looks like in QEMU under a certain configuration.
223 #
224 # This interface can be used to query the "host" CPU model.
225 #
226 # The data returned by this command may be affected by:
227 #
228 # * QEMU version: CPU models may look different depending on the QEMU version.
229 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
230 # * machine-type: CPU model  may look different depending on the machine-type.
231 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
232 # * machine options (including accelerator): in some architectures, CPU models
233 #   may look different depending on machine and accelerator options. (Except for
234 #   CPU models reported as "static" in query-cpu-definitions.)
235 # * "-cpu" arguments and global properties: arguments to the -cpu option and
236 #   global properties may affect expansion of CPU models. Using
237 #   query-cpu-model-expansion while using these is not advised.
238 #
239 # Some architectures may not support all expansion types. s390x supports
240 # "full" and "static". Arm only supports "full".
241 #
242 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
243 #          not supported, if the model cannot be expanded, if the model contains
244 #          an unknown CPU definition name, unknown properties or properties
245 #          with a wrong type. Also returns an error if an expansion type is
246 #          not supported.
247 #
248 # Since: 2.8.0
249 ##
250 { 'command': 'query-cpu-model-expansion',
251   'data': { 'type': 'CpuModelExpansionType',
252             'model': 'CpuModelInfo' },
253   'returns': 'CpuModelExpansionInfo',
254   'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
255
256 ##
257 # @CpuDefinitionInfo:
258 #
259 # Virtual CPU definition.
260 #
261 # @name: the name of the CPU definition
262 #
263 # @migration-safe: whether a CPU definition can be safely used for
264 #                  migration in combination with a QEMU compatibility machine
265 #                  when migrating between different QEMU versions and between
266 #                  hosts with different sets of (hardware or software)
267 #                  capabilities. If not provided, information is not available
268 #                  and callers should not assume the CPU definition to be
269 #                  migration-safe. (since 2.8)
270 #
271 # @static: whether a CPU definition is static and will not change depending on
272 #          QEMU version, machine type, machine options and accelerator options.
273 #          A static model is always migration-safe. (since 2.8)
274 #
275 # @unavailable-features: List of properties that prevent
276 #                        the CPU model from running in the current
277 #                        host. (since 2.8)
278 # @typename: Type name that can be used as argument to @device-list-properties,
279 #            to introspect properties configurable using -cpu or -global.
280 #            (since 2.9)
281 #
282 # @alias-of: Name of CPU model this model is an alias for.  The target of the
283 #            CPU model alias may change depending on the machine type.
284 #            Management software is supposed to translate CPU model aliases
285 #            in the VM configuration, because aliases may stop being
286 #            migration-safe in the future (since 4.1)
287 #
288 # @unavailable-features is a list of QOM property names that
289 # represent CPU model attributes that prevent the CPU from running.
290 # If the QOM property is read-only, that means there's no known
291 # way to make the CPU model run in the current host. Implementations
292 # that choose not to provide specific information return the
293 # property name "type".
294 # If the property is read-write, it means that it MAY be possible
295 # to run the CPU model in the current host if that property is
296 # changed. Management software can use it as hints to suggest or
297 # choose an alternative for the user, or just to generate meaningful
298 # error messages explaining why the CPU model can't be used.
299 # If @unavailable-features is an empty list, the CPU model is
300 # runnable using the current host and machine-type.
301 # If @unavailable-features is not present, runnability
302 # information for the CPU is not available.
303 #
304 # Since: 1.2.0
305 ##
306 { 'struct': 'CpuDefinitionInfo',
307   'data': { 'name': 'str',
308             '*migration-safe': 'bool',
309             'static': 'bool',
310             '*unavailable-features': [ 'str' ],
311             'typename': 'str',
312             '*alias-of' : 'str' },
313   'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }
314
315 ##
316 # @query-cpu-definitions:
317 #
318 # Return a list of supported virtual CPU definitions
319 #
320 # Returns: a list of CpuDefInfo
321 #
322 # Since: 1.2.0
323 ##
324 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
325   'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }