s390-cpu-topology.rst 4.2 KB

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