Commit 7f7b4e7a authored by Markus Armbruster's avatar Markus Armbruster
Browse files

qapi: Split machine-target.json off target.json and misc.json 



Move commands query-cpu-definitions, query-cpu-model-baseline,
query-cpu-model-comparison, and query-cpu-model-expansion with their
types from target.json to machine-target.json.  Also move types
CpuModelInfo, CpuModelExpansionType, and CpuModelCompareResult from
misc.json there.  Add machine-target.json to MAINTAINERS section
"Machine core".

Cc: Eduardo Habkost <ehabkost@redhat.com>
Cc: Marcel Apfelbaum <marcel.apfelbaum@gmail.com>
Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
Message-Id: <20190619201050.19040-13-armbru@redhat.com>
Reviewed-by: default avatarDaniel P. Berrangé <berrange@redhat.com>
[Commit message typo fixed]
parent 55225c85

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -1270,6 +1270,7 @@ F: hw/core/null-machine.c 
F: hw/core/numa.c

F: hw/cpu/cluster.c

F: qapi/machine.json

F: qapi/machine-target.json

F: qom/cpu.c

F: include/hw/boards.h

F: include/hw/cpu/cluster.h

qapi/Makefile.objs

+1 −1
Original line number Diff line number Diff line
@@ -9,7 +9,7 @@ QAPI_COMMON_MODULES = audio authz block-core block char common crypto 
QAPI_COMMON_MODULES += introspect job machine migration misc net

QAPI_COMMON_MODULES += qdev qom rdma rocker run-state sockets tpm

QAPI_COMMON_MODULES += trace transaction ui

QAPI_TARGET_MODULES = target

QAPI_TARGET_MODULES = machine-target target

QAPI_MODULES = $(QAPI_COMMON_MODULES) $(QAPI_TARGET_MODULES)



util-obj-y += qapi-builtin-types.o

qapi/machine-target.json

0 → 100644
+318 −0
Original line number Diff line number Diff line 
# -*- Mode: 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.0

##

{ '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.0

##

{ '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.0

##

{ 'enum': 'CpuModelCompareResult',

  'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }



##

# @CpuModelBaselineInfo:

#

# The result of a CPU model baseline.

#

# @model: the baselined CpuModelInfo.

#

# Since: 2.8.0

##

{ 'struct': 'CpuModelBaselineInfo',

  'data': { 'model': 'CpuModelInfo' },

  'if': 'defined(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.0

##

{ 'struct': 'CpuModelCompareInfo',

  'data': { 'result': 'CpuModelCompareResult',

            'responsible-properties': ['str'] },

  'if': 'defined(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.0

##

{ 'command': 'query-cpu-model-comparison',

  'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },

  'returns': 'CpuModelCompareInfo',

  'if': 'defined(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.0

##

{ 'command': 'query-cpu-model-baseline',

  'data': { 'modela': 'CpuModelInfo',

            'modelb': 'CpuModelInfo' },

  'returns': 'CpuModelBaselineInfo',

  'if': 'defined(TARGET_S390X)' }



##

# @CpuModelExpansionInfo:

#

# The result of a cpu model expansion.

#

# @model: the expanded CpuModelInfo.

#

# Since: 2.8.0

##

{ 'struct': 'CpuModelExpansionInfo',

  'data': { 'model': 'CpuModelInfo' },

  'if': 'defined(TARGET_S390X) || defined(TARGET_I386)' }



##

# @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".

#

# 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.0

##

{ 'command': 'query-cpu-model-expansion',

  'data': { 'type': 'CpuModelExpansionType',

            'model': 'CpuModelInfo' },

  'returns': 'CpuModelExpansionInfo',

  'if': 'defined(TARGET_S390X) || defined(TARGET_I386)' }



##

# @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)

#

# @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.0

##

{ 'struct': 'CpuDefinitionInfo',

  'data': { 'name': 'str',

            '*migration-safe': 'bool',

            'static': 'bool',

            '*unavailable-features': [ 'str' ],

            'typename': 'str' },

  'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }



##

# @query-cpu-definitions:

#

# Return a list of supported virtual CPU definitions

#

# Returns: a list of CpuDefInfo

#

# Since: 1.2.0

##

{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],

  'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }

qapi/misc.json

+0 −74
Original line number Diff line number Diff line
@@ -1387,80 +1387,6 @@ 
{ 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }





##

# @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.0

##

{ '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.0

##

{ '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.0

##

{ 'enum': 'CpuModelCompareResult',

  'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }



##

# @AddfdInfo:

#

qapi/qapi-schema.json

+1 −0
Original line number Diff line number Diff line
@@ -100,6 +100,7 @@ 
{ 'include': 'qom.json' }

{ 'include': 'qdev.json' }

{ 'include': 'machine.json' }

{ 'include': 'machine-target.json' }

{ 'include': 'misc.json' }

{ 'include': 'target.json' }

{ 'include': 'audio.json' }