docs/devel/s390-cpu-topology.rst

   1 QAPI interface for S390 CPU topology
   2 ====================================
   3
   4 The following sections will explain the QAPI interface for S390 CPU topology
   5 with the help of exemplary output.
   6 For this, let's assume that QEMU has been started with the following
   7 command, defining 4 CPUs, where CPU[0] is defined by the -smp argument and will
   8 have default values:
   9
  10 .. code-block:: bash
  11
  12  qemu-system-s390x \
  13     -enable-kvm \
  14     -cpu z14,ctop=on \
  15     -smp 1,drawers=3,books=3,sockets=2,cores=2,maxcpus=36 \
  16     -device z14-s390x-cpu,core-id=19,entitlement=high \
  17     -device z14-s390x-cpu,core-id=11,entitlement=low \
  18     -device z14-s390x-cpu,core-id=12,entitlement=high \
  19    ...
  20
  21 Additions to query-cpus-fast
  22 ----------------------------
  23
  24 The command query-cpus-fast allows querying the topology tree and
  25 modifiers for all configured vCPUs.
  26
  27 .. code-block:: QMP
  28
  29  { "execute": "query-cpus-fast" }
  30  {
  31   "return": [
  32     {
  33       "dedicated": false,
  34       "thread-id": 536993,
  35       "props": {
  36         "core-id": 0,
  37         "socket-id": 0,
  38         "drawer-id": 0,
  39         "book-id": 0
  40       },
  41       "cpu-state": "operating",
  42       "entitlement": "medium",
  43       "qom-path": "/machine/unattached/device[0]",
  44       "cpu-index": 0,
  45       "target": "s390x"
  46     },
  47     {
  48       "dedicated": false,
  49       "thread-id": 537003,
  50       "props": {
  51         "core-id": 19,
  52         "socket-id": 1,
  53         "drawer-id": 0,
  54         "book-id": 2
  55       },
  56       "cpu-state": "operating",
  57       "entitlement": "high",
  58       "qom-path": "/machine/peripheral-anon/device[0]",
  59       "cpu-index": 19,
  60       "target": "s390x"
  61     },
  62     {
  63       "dedicated": false,
  64       "thread-id": 537004,
  65       "props": {
  66         "core-id": 11,
  67         "socket-id": 1,
  68         "drawer-id": 0,
  69         "book-id": 1
  70       },
  71       "cpu-state": "operating",
  72       "entitlement": "low",
  73       "qom-path": "/machine/peripheral-anon/device[1]",
  74       "cpu-index": 11,
  75       "target": "s390x"
  76     },
  77     {
  78       "dedicated": true,
  79       "thread-id": 537005,
  80       "props": {
  81         "core-id": 12,
  82         "socket-id": 0,
  83         "drawer-id": 3,
  84         "book-id": 2
  85       },
  86       "cpu-state": "operating",
  87       "entitlement": "high",
  88       "qom-path": "/machine/peripheral-anon/device[2]",
  89       "cpu-index": 12,
  90       "target": "s390x"
  91     }
  92   ]
  93  }
  94
  95
  96 QAPI command: set-cpu-topology
  97 ------------------------------
  98
  99 The command set-cpu-topology allows modifying the topology tree
 100 or the topology modifiers of a vCPU in the configuration.
 101
 102 .. code-block:: QMP
 103
 104     { "execute": "set-cpu-topology",
 105       "arguments": {
 106          "core-id": 11,
 107          "socket-id": 0,
 108          "book-id": 0,
 109          "drawer-id": 0,
 110          "entitlement": "low",
 111          "dedicated": false
 112       }
 113     }
 114     {"return": {}}
 115
 116 The core-id parameter is the only mandatory parameter and every
 117 unspecified parameter keeps its previous value.
 118
 119 QAPI event CPU_POLARIZATION_CHANGE
 120 ----------------------------------
 121
 122 When a guest requests a modification of the polarization,
 123 QEMU sends a CPU_POLARIZATION_CHANGE event.
 124
 125 When requesting the change, the guest only specifies horizontal or
 126 vertical polarization.
 127 It is the job of the entity administrating QEMU to set the dedication and fine
 128 grained vertical entitlement in response to this event.
 129
 130 Note that a vertical polarized dedicated vCPU can only have a high
 131 entitlement, giving 6 possibilities for vCPU polarization:
 132
 133 - Horizontal
 134 - Horizontal dedicated
 135 - Vertical low
 136 - Vertical medium
 137 - Vertical high
 138 - Vertical high dedicated
 139
 140 Example of the event received when the guest issues the CPU instruction
 141 Perform Topology Function PTF(0) to request an horizontal polarization:
 142
 143 .. code-block:: QMP
 144
 145   {
 146     "timestamp": {
 147       "seconds": 1687870305,
 148       "microseconds": 566299
 149     },
 150     "event": "CPU_POLARIZATION_CHANGE",
 151     "data": {
 152       "polarization": "horizontal"
 153     }
 154   }
 155
 156 QAPI query command: query-s390x-cpu-polarization
 157 ------------------------------------------------
 158
 159 The query command query-s390x-cpu-polarization returns the current
 160 CPU polarization of the machine.
 161 In this case the guest previously issued a PTF(1) to request vertical polarization:
 162
 163 .. code-block:: QMP
 164
 165     { "execute": "query-s390x-cpu-polarization" }
 166     {
 167         "return": {
 168           "polarization": "vertical"
 169         }
 170     }