xref: /qemu/docs/devel/s390-cpu-topology.rst (revision 5db05230) 
1QAPI interface for S390 CPU topology
2====================================
3
4The following sections will explain the QAPI interface for S390 CPU topology
5with the help of exemplary output.
6For this, let's assume that QEMU has been started with the following
7command, defining 4 CPUs, where CPU[0] is defined by the -smp argument and will
8have 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
21Additions to query-cpus-fast
22----------------------------
23
24The command query-cpus-fast allows querying the topology tree and
25modifiers 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
96QAPI command: set-cpu-topology
97------------------------------
98
99The command set-cpu-topology allows modifying the topology tree
100or 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
116The core-id parameter is the only mandatory parameter and every
117unspecified parameter keeps its previous value.
118
119QAPI event CPU_POLARIZATION_CHANGE
120----------------------------------
121
122When a guest requests a modification of the polarization,
123QEMU sends a CPU_POLARIZATION_CHANGE event.
124
125When requesting the change, the guest only specifies horizontal or
126vertical polarization.
127It is the job of the entity administrating QEMU to set the dedication and fine
128grained vertical entitlement in response to this event.
129
130Note that a vertical polarized dedicated vCPU can only have a high
131entitlement, 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
140Example of the event received when the guest issues the CPU instruction
141Perform 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
156QAPI query command: query-s390x-cpu-polarization
157------------------------------------------------
158
159The query command query-s390x-cpu-polarization returns the current
160CPU polarization of the machine.
161In 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    }
171