# -*- 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. { 'include': 'machine-common.json' } ## # @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 # # @deprecated-props: a list of properties that are flagged as deprecated # by the CPU vendor. These props are a subset of the full model's # definition list of properties. (since 9.1) # # Since: 2.8 ## { 'struct': 'CpuModelInfo', 'data': { 'name': 'str', '*props': 'any', '*deprecated-props': ['str'] } } ## # @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, @modela and @modelb, 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. # # @modela: description of the first CPU model to compare, referred to as # "model A" in CpuModelCompareResult # # @modelb: description of the second CPU model to compare, referred to as # "model B" in CpuModelCompareResult # # Returns: a CpuModelCompareInfo describing how both CPU models # compare # # Errors: # - 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, @modela and @modelb, 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. # # @modela: description of the first CPU model to baseline # # @modelb: description of the second CPU model to baseline # # Returns: a CpuModelBaselineInfo describing the baselined CPU model # # Errors: # - 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', 'TARGET_LOONGARCH64', 'TARGET_RISCV' ] } } ## # @query-cpu-model-expansion: # # Expands a given CPU model, @model, (or a combination of CPU model + # additional options) to different granularities, specified by # @type, 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". # # @model: description of the CPU model to expand # # @type: expansion type, specifying how to expand the CPU model # # Returns: a CpuModelExpansionInfo describing the expanded CPU model # # Errors: # - 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 # - 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', 'TARGET_LOONGARCH64', 'TARGET_RISCV' ] } } ## # @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', 'TARGET_RISCV' ] } } ## # @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', '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' } ## # @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. # # 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' ] } } ## # @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' ] } } ## # @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' ] } }