| # -*- 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. |
| |
| ## |
| # @CpuModelInfo: |
| # |
| # Virtual CPU model. |
| # |
| # A CPU model consists of the name of a CPU definition, to which |
| # delta changes are applied (e.g. features added/removed). Most magic values |
| # that an architecture might require should be hidden behind the name. |
| # However, if required, architectures can expose relevant properties. |
| # |
| # @name: the name of the CPU definition the model is based on |
| # @props: a dictionary of QOM properties to be applied |
| # |
| # Since: 2.8 |
| ## |
| { 'struct': 'CpuModelInfo', |
| 'data': { 'name': 'str', |
| '*props': 'any' } } |
| |
| ## |
| # @CpuModelExpansionType: |
| # |
| # An enumeration of CPU model expansion types. |
| # |
| # @static: Expand to a static CPU model, a combination of a static base |
| # model name and property delta changes. As the static base model will |
| # never change, the expanded CPU model will be the same, independent of |
| # QEMU version, machine type, machine options, and accelerator options. |
| # Therefore, the resulting model can be used by tooling without having |
| # to specify a compatibility machine - e.g. when displaying the "host" |
| # model. The @static CPU models are migration-safe. |
| |
| # @full: Expand all properties. The produced model is not guaranteed to be |
| # migration-safe, but allows tooling to get an insight and work with |
| # model details. |
| # |
| # Note: When a non-migration-safe CPU model is expanded in static mode, some |
| # features enabled by the CPU model may be omitted, because they can't be |
| # implemented by a static CPU model definition (e.g. cache info passthrough and |
| # PMU passthrough in x86). If you need an accurate representation of the |
| # features enabled by a non-migration-safe CPU model, use @full. If you need a |
| # static representation that will keep ABI compatibility even when changing QEMU |
| # version or machine-type, use @static (but keep in mind that some features may |
| # be omitted). |
| # |
| # Since: 2.8 |
| ## |
| { 'enum': 'CpuModelExpansionType', |
| 'data': [ 'static', 'full' ] } |
| |
| ## |
| # @CpuModelCompareResult: |
| # |
| # An enumeration of CPU model comparison results. The result is usually |
| # calculated using e.g. CPU features or CPU generations. |
| # |
| # @incompatible: If model A is incompatible to model B, model A is not |
| # guaranteed to run where model B runs and the other way around. |
| # |
| # @identical: If model A is identical to model B, model A is guaranteed to run |
| # where model B runs and the other way around. |
| # |
| # @superset: If model A is a superset of model B, model B is guaranteed to run |
| # where model A runs. There are no guarantees about the other way. |
| # |
| # @subset: If model A is a subset of model B, model A is guaranteed to run |
| # where model B runs. There are no guarantees about the other way. |
| # |
| # Since: 2.8 |
| ## |
| { 'enum': 'CpuModelCompareResult', |
| 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } |
| |
| ## |
| # @CpuModelBaselineInfo: |
| # |
| # The result of a CPU model baseline. |
| # |
| # @model: the baselined CpuModelInfo. |
| # |
| # Since: 2.8 |
| ## |
| { 'struct': 'CpuModelBaselineInfo', |
| 'data': { 'model': 'CpuModelInfo' }, |
| 'if': 'TARGET_S390X' } |
| |
| ## |
| # @CpuModelCompareInfo: |
| # |
| # The result of a CPU model comparison. |
| # |
| # @result: The result of the compare operation. |
| # @responsible-properties: List of properties that led to the comparison result |
| # not being identical. |
| # |
| # @responsible-properties is a list of QOM property names that led to |
| # both CPUs not being detected as identical. For identical models, this |
| # list is empty. |
| # If a QOM property is read-only, that means there's no known way to make the |
| # CPU models identical. If the special property name "type" is included, the |
| # models are by definition not identical and cannot be made identical. |
| # |
| # Since: 2.8 |
| ## |
| { 'struct': 'CpuModelCompareInfo', |
| 'data': { 'result': 'CpuModelCompareResult', |
| 'responsible-properties': ['str'] }, |
| 'if': 'TARGET_S390X' } |
| |
| ## |
| # @query-cpu-model-comparison: |
| # |
| # Compares two CPU models, returning how they compare in a specific |
| # configuration. The results indicates how both models compare regarding |
| # runnability. This result can be used by tooling to make decisions if a |
| # certain CPU model will run in a certain configuration or if a compatible |
| # CPU model has to be created by baselining. |
| # |
| # Usually, a CPU model is compared against the maximum possible CPU model |
| # of a certain configuration (e.g. the "host" model for KVM). If that CPU |
| # model is identical or a subset, it will run in that configuration. |
| # |
| # The result returned by this command may be affected by: |
| # |
| # * QEMU version: CPU models may look different depending on the QEMU version. |
| # (Except for CPU models reported as "static" in query-cpu-definitions.) |
| # * machine-type: CPU model may look different depending on the machine-type. |
| # (Except for CPU models reported as "static" in query-cpu-definitions.) |
| # * machine options (including accelerator): in some architectures, CPU models |
| # may look different depending on machine and accelerator options. (Except for |
| # CPU models reported as "static" in query-cpu-definitions.) |
| # * "-cpu" arguments and global properties: arguments to the -cpu option and |
| # global properties may affect expansion of CPU models. Using |
| # query-cpu-model-expansion while using these is not advised. |
| # |
| # Some architectures may not support comparing CPU models. s390x supports |
| # comparing CPU models. |
| # |
| # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is |
| # not supported, if a model cannot be used, if a model contains |
| # an unknown cpu definition name, unknown properties or properties |
| # with wrong types. |
| # |
| # Note: this command isn't specific to s390x, but is only implemented |
| # on this architecture currently. |
| # |
| # Since: 2.8 |
| ## |
| { 'command': 'query-cpu-model-comparison', |
| 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, |
| 'returns': 'CpuModelCompareInfo', |
| 'if': 'TARGET_S390X' } |
| |
| ## |
| # @query-cpu-model-baseline: |
| # |
| # Baseline two CPU models, creating a compatible third model. The created |
| # model will always be a static, migration-safe CPU model (see "static" |
| # CPU model expansion for details). |
| # |
| # This interface can be used by tooling to create a compatible CPU model out |
| # two CPU models. The created CPU model will be identical to or a subset of |
| # both CPU models when comparing them. Therefore, the created CPU model is |
| # guaranteed to run where the given CPU models run. |
| # |
| # The result returned by this command may be affected by: |
| # |
| # * QEMU version: CPU models may look different depending on the QEMU version. |
| # (Except for CPU models reported as "static" in query-cpu-definitions.) |
| # * machine-type: CPU model may look different depending on the machine-type. |
| # (Except for CPU models reported as "static" in query-cpu-definitions.) |
| # * machine options (including accelerator): in some architectures, CPU models |
| # may look different depending on machine and accelerator options. (Except for |
| # CPU models reported as "static" in query-cpu-definitions.) |
| # * "-cpu" arguments and global properties: arguments to the -cpu option and |
| # global properties may affect expansion of CPU models. Using |
| # query-cpu-model-expansion while using these is not advised. |
| # |
| # Some architectures may not support baselining CPU models. s390x supports |
| # baselining CPU models. |
| # |
| # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is |
| # not supported, if a model cannot be used, if a model contains |
| # an unknown cpu definition name, unknown properties or properties |
| # with wrong types. |
| # |
| # Note: this command isn't specific to s390x, but is only implemented |
| # on this architecture currently. |
| # |
| # Since: 2.8 |
| ## |
| { 'command': 'query-cpu-model-baseline', |
| 'data': { 'modela': 'CpuModelInfo', |
| 'modelb': 'CpuModelInfo' }, |
| 'returns': 'CpuModelBaselineInfo', |
| 'if': 'TARGET_S390X' } |
| |
| ## |
| # @CpuModelExpansionInfo: |
| # |
| # The result of a cpu model expansion. |
| # |
| # @model: the expanded CpuModelInfo. |
| # |
| # Since: 2.8 |
| ## |
| { 'struct': 'CpuModelExpansionInfo', |
| 'data': { 'model': 'CpuModelInfo' }, |
| 'if': { 'any': [ 'TARGET_S390X', |
| 'TARGET_I386', |
| 'TARGET_ARM' ] } } |
| |
| ## |
| # @query-cpu-model-expansion: |
| # |
| # Expands a given CPU model (or a combination of CPU model + additional options) |
| # to different granularities, allowing tooling to get an understanding what a |
| # specific CPU model looks like in QEMU under a certain configuration. |
| # |
| # This interface can be used to query the "host" CPU model. |
| # |
| # The data returned by this command may be affected by: |
| # |
| # * QEMU version: CPU models may look different depending on the QEMU version. |
| # (Except for CPU models reported as "static" in query-cpu-definitions.) |
| # * machine-type: CPU model may look different depending on the machine-type. |
| # (Except for CPU models reported as "static" in query-cpu-definitions.) |
| # * machine options (including accelerator): in some architectures, CPU models |
| # may look different depending on machine and accelerator options. (Except for |
| # CPU models reported as "static" in query-cpu-definitions.) |
| # * "-cpu" arguments and global properties: arguments to the -cpu option and |
| # global properties may affect expansion of CPU models. Using |
| # query-cpu-model-expansion while using these is not advised. |
| # |
| # Some architectures may not support all expansion types. s390x supports |
| # "full" and "static". Arm only supports "full". |
| # |
| # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is |
| # not supported, if the model cannot be expanded, if the model contains |
| # an unknown CPU definition name, unknown properties or properties |
| # with a wrong type. Also returns an error if an expansion type is |
| # not supported. |
| # |
| # Since: 2.8 |
| ## |
| { 'command': 'query-cpu-model-expansion', |
| 'data': { 'type': 'CpuModelExpansionType', |
| 'model': 'CpuModelInfo' }, |
| 'returns': 'CpuModelExpansionInfo', |
| 'if': { 'any': [ 'TARGET_S390X', |
| 'TARGET_I386', |
| 'TARGET_ARM' ] } } |
| |
| ## |
| # @CpuDefinitionInfo: |
| # |
| # Virtual CPU definition. |
| # |
| # @name: the name of the CPU definition |
| # |
| # @migration-safe: whether a CPU definition can be safely used for |
| # migration in combination with a QEMU compatibility machine |
| # when migrating between different QEMU versions and between |
| # hosts with different sets of (hardware or software) |
| # capabilities. If not provided, information is not available |
| # and callers should not assume the CPU definition to be |
| # migration-safe. (since 2.8) |
| # |
| # @static: whether a CPU definition is static and will not change depending on |
| # QEMU version, machine type, machine options and accelerator options. |
| # A static model is always migration-safe. (since 2.8) |
| # |
| # @unavailable-features: List of properties that prevent |
| # the CPU model from running in the current |
| # host. (since 2.8) |
| # @typename: Type name that can be used as argument to @device-list-properties, |
| # to introspect properties configurable using -cpu or -global. |
| # (since 2.9) |
| # |
| # @alias-of: Name of CPU model this model is an alias for. The target of the |
| # CPU model alias may change depending on the machine type. |
| # Management software is supposed to translate CPU model aliases |
| # in the VM configuration, because aliases may stop being |
| # migration-safe in the future (since 4.1) |
| # |
| # @deprecated: If true, this CPU model is deprecated and may be removed in |
| # in some future version of QEMU according to the QEMU deprecation |
| # policy. (since 5.2) |
| # |
| # @unavailable-features is a list of QOM property names that |
| # represent CPU model attributes that prevent the CPU from running. |
| # If the QOM property is read-only, that means there's no known |
| # way to make the CPU model run in the current host. Implementations |
| # that choose not to provide specific information return the |
| # property name "type". |
| # If the property is read-write, it means that it MAY be possible |
| # to run the CPU model in the current host if that property is |
| # changed. Management software can use it as hints to suggest or |
| # choose an alternative for the user, or just to generate meaningful |
| # error messages explaining why the CPU model can't be used. |
| # If @unavailable-features is an empty list, the CPU model is |
| # runnable using the current host and machine-type. |
| # If @unavailable-features is not present, runnability |
| # information for the CPU is not available. |
| # |
| # Since: 1.2 |
| ## |
| { 'struct': 'CpuDefinitionInfo', |
| 'data': { 'name': 'str', |
| '*migration-safe': 'bool', |
| 'static': 'bool', |
| '*unavailable-features': [ 'str' ], |
| 'typename': 'str', |
| '*alias-of' : 'str', |
| 'deprecated' : 'bool' }, |
| 'if': { 'any': [ 'TARGET_PPC', |
| 'TARGET_ARM', |
| 'TARGET_I386', |
| 'TARGET_S390X', |
| 'TARGET_MIPS', |
| 'TARGET_LOONGARCH64' ] } } |
| |
| ## |
| # @query-cpu-definitions: |
| # |
| # Return a list of supported virtual CPU definitions |
| # |
| # Returns: a list of CpuDefinitionInfo |
| # |
| # Since: 1.2 |
| ## |
| { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], |
| 'if': { 'any': [ 'TARGET_PPC', |
| 'TARGET_ARM', |
| 'TARGET_I386', |
| 'TARGET_S390X', |
| 'TARGET_MIPS', |
| 'TARGET_LOONGARCH64' ] } } |