QAPI interface for S390 CPU topology

The following sections will explain the QAPI interface for S390 CPU topology with the help of exemplary output. For this, let’s assume that QEMU has been started with the following command, defining 4 CPUs, where CPU[0] is defined by the -smp argument and will have default values:

qemu-system-s390x \
   -enable-kvm \
   -cpu z14,ctop=on \
   -smp 1,drawers=3,books=3,sockets=2,cores=2,maxcpus=36 \
   -device z14-s390x-cpu,core-id=19,entitlement=high \
   -device z14-s390x-cpu,core-id=11,entitlement=low \
   -device z14-s390x-cpu,core-id=12,entitlement=high \
  ...

Additions to query-cpus-fast

The command query-cpus-fast allows querying the topology tree and modifiers for all configured vCPUs.

{ "execute": "query-cpus-fast" }
{
 "return": [
   {
     "dedicated": false,
     "thread-id": 536993,
     "props": {
       "core-id": 0,
       "socket-id": 0,
       "drawer-id": 0,
       "book-id": 0
     },
     "cpu-state": "operating",
     "entitlement": "medium",
     "qom-path": "/machine/unattached/device[0]",
     "cpu-index": 0,
     "target": "s390x"
   },
   {
     "dedicated": false,
     "thread-id": 537003,
     "props": {
       "core-id": 19,
       "socket-id": 1,
       "drawer-id": 0,
       "book-id": 2
     },
     "cpu-state": "operating",
     "entitlement": "high",
     "qom-path": "/machine/peripheral-anon/device[0]",
     "cpu-index": 19,
     "target": "s390x"
   },
   {
     "dedicated": false,
     "thread-id": 537004,
     "props": {
       "core-id": 11,
       "socket-id": 1,
       "drawer-id": 0,
       "book-id": 1
     },
     "cpu-state": "operating",
     "entitlement": "low",
     "qom-path": "/machine/peripheral-anon/device[1]",
     "cpu-index": 11,
     "target": "s390x"
   },
   {
     "dedicated": true,
     "thread-id": 537005,
     "props": {
       "core-id": 12,
       "socket-id": 0,
       "drawer-id": 3,
       "book-id": 2
     },
     "cpu-state": "operating",
     "entitlement": "high",
     "qom-path": "/machine/peripheral-anon/device[2]",
     "cpu-index": 12,
     "target": "s390x"
   }
 ]
}

QAPI command: set-cpu-topology

The command set-cpu-topology allows modifying the topology tree or the topology modifiers of a vCPU in the configuration.

{ "execute": "set-cpu-topology",
  "arguments": {
     "core-id": 11,
     "socket-id": 0,
     "book-id": 0,
     "drawer-id": 0,
     "entitlement": "low",
     "dedicated": false
  }
}
{"return": {}}

The core-id parameter is the only mandatory parameter and every unspecified parameter keeps its previous value.

QAPI event CPU_POLARIZATION_CHANGE

When a guest requests a modification of the polarization, QEMU sends a CPU_POLARIZATION_CHANGE event.

When requesting the change, the guest only specifies horizontal or vertical polarization. It is the job of the entity administrating QEMU to set the dedication and fine grained vertical entitlement in response to this event.

Note that a vertical polarized dedicated vCPU can only have a high entitlement, giving 6 possibilities for vCPU polarization:

• Horizontal

• Horizontal dedicated

• Vertical low

• Vertical medium

• Vertical high

• Vertical high dedicated

Example of the event received when the guest issues the CPU instruction Perform Topology Function PTF(0) to request an horizontal polarization:

{
  "timestamp": {
    "seconds": 1687870305,
    "microseconds": 566299
  },
  "event": "CPU_POLARIZATION_CHANGE",
  "data": {
    "polarization": "horizontal"
  }
}

QAPI query command: query-s390x-cpu-polarization

The query command query-s390x-cpu-polarization returns the current CPU polarization of the machine. In this case the guest previously issued a PTF(1) to request vertical polarization:

{ "execute": "query-s390x-cpu-polarization" }
{
    "return": {
      "polarization": "vertical"
    }
}