system/s390x/cpu-topology.rst

1 .. _cpu-topology-s390x:
8 tree-shaped hierarchy.
13 - CPU type
14 - entitlement
15 - dedication
17 Each bit set in the bitmap correspond to a core-id of a vCPU with matching
23 monitor polarization changes, see ``docs/devel/s390-cpu-topology.rst``.
26 -------------
31 The s390x host needs to use a Linux kernel v6.0 or newer (which provides the so-called
33 CPU topology facility via the so-called STFLE bit 11 to the VM).
36 ---------------------
43 .. code-block:: bash
45    -cpu gen16b,ctop=on
51 ----------------------
54 with the ``-smp`` or the ``-device`` QEMU command arguments.
57 and the ``-smp`` command line argument accepts only ``threads=1``.
60 specified for the ``-smp`` flag, the number of these containers
65 .. code-block:: bash
67     -smp cpus=5,drawer=1,books=1,sockets=8,cores=4,maxcpus=32
71 .. code-block:: bash
73     -smp cpus=5,sockets=8,cores=4,maxcpus=32
75 When a CPU is defined by the ``-smp`` command argument, its position
77 based on the core-id starting with core-0 at position 0 of socket-0,
78 book-0, drawer-0 and filling all CPUs of socket-0 before filling socket-1
79 of book-0 and so on up to the last socket of the last book of the last
82 When a CPU is defined by the ``-device`` command argument, the
85 .. code-block:: bash
87     -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=1
91 .. code-block:: bash
93     -device gen16b-s390x-cpu,core-id=1,dedicated=true
96 for the ``-device`` argument, like for all CPUs defined with the ``-smp``
98 adding the CPUs to the topology based on the core-id.
101 CPU topology defined explicitly or implicitly on a ``-device``
103 on the ``-smp`` argument.
106 ``-device`` command argument they takes following default values:
108 - dedicated: ``false``
109 - entitlement: ``medium``
117 .. code-block:: bash
119   (qemu) device_add gen16b-s390x-cpu,core-id=9
121 The placement of the CPU is derived from the core-id as described above.
125 .. code-block:: bash
127     (qemu) device_add gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=1
133 In the following machine we define 8 sockets with 4 cores each.
135 .. code-block:: bash
137   $ qemu-system-s390x -accel kvm -m 2G \
138     -cpu gen16b,ctop=on \
139     -smp cpus=5,sockets=8,cores=4,maxcpus=32 \
140     -device host-s390x-cpu,core-id=14 \
144 .. code-block:: bash
146   (qemu) device_add gen16b-s390x-cpu,core-id=9
148 The core-id defines the placement of the core in the topology by
153 * There are 5 CPUs provided to the guest with the ``-smp`` command line
154   They will take the core-ids 0,1,2,3,4
155   As we have 4 cores in a socket, we have 4 CPUs provided
156   to the guest in socket 0, with core-ids 0,1,2,3.
157   The last CPU, with core-id 4, will be on socket 1.
159 * the core with ID 14 provided by the ``-device`` command line will
160   be placed in socket 3, with core-id 14
163   be placed in socket 2, with core-id 9
167 ----------------------------------------
197 - a vCPU with vertical high entitlement specifies that this
200 - a vCPU with vertical medium entitlement specifies that this
203 - a vCPU with vertical low entitlement specifies that this
217 -----------------------------------------
219 The topology can entirely be defined using -device cpu statements,
220 with the exception of CPU 0 which must be defined with the -smp
223 For example, here we set the position of the cores 1,2,3 to
224 drawer 1, book 1, socket 2 and cores 0,9 and 14 to drawer 0,
226 Core 4 will be set on its default position on socket 1
227 (since we have 4 core per socket) and we define it as dedicated and
230 .. code-block:: bash
232   $ qemu-system-s390x -accel kvm -m 2G \
233     -cpu gen16b,ctop=on \
234     -smp cpus=1,sockets=8,cores=4,maxcpus=32 \
236     -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=1 \
237     -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=2 \
238     -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=3 \
240     -device gen16b-s390x-cpu,drawer-id=0,book-id=0,socket-id=0,core-id=9 \
241     -device gen16b-s390x-cpu,drawer-id=0,book-id=0,socket-id=0,core-id=14 \
243     -device gen16b-s390x-cpu,core-id=4,dedicated=on,entitlement=high
245 The entitlement defined for the CPU 4 will only be used after the guest