Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/1850824/?format=api
{ "id": 1850824, "url": "http://patchwork.ozlabs.org/api/patches/1850824/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20231018130716.286638-15-thuth@redhat.com/", "project": { "id": 14, "url": "http://patchwork.ozlabs.org/api/projects/14/?format=api", "name": "QEMU Development", "link_name": "qemu-devel", "list_id": "qemu-devel.nongnu.org", "list_email": "qemu-devel@nongnu.org", "web_url": "", "scm_url": "", "webscm_url": "", "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<20231018130716.286638-15-thuth@redhat.com>", "list_archive_url": null, "date": "2023-10-18T13:07:05", "name": "[PULL,14/25] docs/s390x/cpu topology: document s390x cpu topology", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "6f63021302db4ba89476382369962ab9f3e9b91e", "submitter": { "id": 66152, "url": "http://patchwork.ozlabs.org/api/people/66152/?format=api", "name": "Thomas Huth", "email": "thuth@redhat.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20231018130716.286638-15-thuth@redhat.com/mbox/", "series": [ { "id": 378180, "url": "http://patchwork.ozlabs.org/api/series/378180/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/list/?series=378180", "date": "2023-10-18T13:06:52", "name": "[PULL,01/25] qapi: machine.json: change docs regarding CPU topology", "version": 1, "mbox": "http://patchwork.ozlabs.org/series/378180/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/1850824/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/1850824/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@legolas.ozlabs.org", "Authentication-Results": [ "legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=gQTbAs4x;\n\tdkim-atps=neutral", "legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)" ], "Received": [ "from lists.gnu.org (lists.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4S9WYc29L5z20Pd\n\tfor <incoming@patchwork.ozlabs.org>; Thu, 19 Oct 2023 00:15:32 +1100 (AEDT)", "from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from <qemu-devel-bounces@nongnu.org>)\n\tid 1qt6IG-0006kY-3B; Wed, 18 Oct 2023 09:09:00 -0400", "from eggs.gnu.org ([2001:470:142:3::10])\n by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from <thuth@redhat.com>) id 1qt6Ha-0004pX-IA\n for qemu-devel@nongnu.org; Wed, 18 Oct 2023 09:08:20 -0400", "from us-smtp-delivery-124.mimecast.com ([170.10.129.124])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from <thuth@redhat.com>) id 1qt6HW-00084a-BF\n for qemu-devel@nongnu.org; Wed, 18 Oct 2023 09:08:17 -0400", "from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com\n [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS\n (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id\n us-mta-479-DAR-SPHWO6WT5C5KZyXXBw-1; Wed, 18 Oct 2023 09:07:56 -0400", "from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com\n [10.11.54.4])\n (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))\n (No client certificate requested)\n by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EB18685A58C;\n Wed, 18 Oct 2023 13:07:42 +0000 (UTC)", "from thuth-p1g4.redhat.com (unknown [10.39.192.109])\n by smtp.corp.redhat.com (Postfix) with ESMTP id A1ED520268C8;\n Wed, 18 Oct 2023 13:07:41 +0000 (UTC)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1697634493;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:cc:mime-version:mime-version:\n content-transfer-encoding:content-transfer-encoding:\n in-reply-to:in-reply-to:references:references;\n bh=k4taefV76TunAA0qwymOAdI8JoajvVPkEpE8hFW9JmM=;\n b=gQTbAs4xRaIcTlie6/r5mwB45j0r/CdoxOho+FZhG6N9RVOUaxVvd0fkR73jorJTuW8qHm\n hGcwQG7eCweBO0ryFKo3LIvANcYv3BeU3pnCueL6RG280GFTqA0s20h4gV2CGDfbNVXtvv\n d1T385rKE3EZl+w5vXi0UzbkHh0CM8s=", "X-MC-Unique": "DAR-SPHWO6WT5C5KZyXXBw-1", "From": "Thomas Huth <thuth@redhat.com>", "To": "qemu-devel@nongnu.org", "Cc": "Stefan Hajnoczi <stefanha@redhat.com>, qemu-s390x@nongnu.org,\n Nina Schoetterl-Glausch <nsg@linux.ibm.com>", "Subject": "[PULL 14/25] docs/s390x/cpu topology: document s390x cpu topology", "Date": "Wed, 18 Oct 2023 15:07:05 +0200", "Message-ID": "<20231018130716.286638-15-thuth@redhat.com>", "In-Reply-To": "<20231018130716.286638-1-thuth@redhat.com>", "References": "<20231018130716.286638-1-thuth@redhat.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-Scanned-By": "MIMEDefang 3.4.1 on 10.11.54.4", "Received-SPF": "pass client-ip=170.10.129.124; envelope-from=thuth@redhat.com;\n helo=us-smtp-delivery-124.mimecast.com", "X-Spam_score_int": "-20", "X-Spam_score": "-2.1", "X-Spam_bar": "--", "X-Spam_report": "(-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001,\n DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,\n RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001,\n SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no", "X-Spam_action": "no action", "X-BeenThere": "qemu-devel@nongnu.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<qemu-devel.nongnu.org>", "List-Unsubscribe": "<https://lists.nongnu.org/mailman/options/qemu-devel>,\n <mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>", "List-Archive": "<https://lists.nongnu.org/archive/html/qemu-devel>", "List-Post": "<mailto:qemu-devel@nongnu.org>", "List-Help": "<mailto:qemu-devel-request@nongnu.org?subject=help>", "List-Subscribe": "<https://lists.nongnu.org/mailman/listinfo/qemu-devel>,\n <mailto:qemu-devel-request@nongnu.org?subject=subscribe>", "Errors-To": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org", "Sender": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org" }, "content": "From: Pierre Morel <pmorel@linux.ibm.com>\n\nAdd some basic examples for the definition of cpu topology\nin s390x.\n\nSigned-off-by: Pierre Morel <pmorel@linux.ibm.com>\nCo-developed-by: Nina Schoetterl-Glausch <nsg@linux.ibm.com>\nReviewed-by: Thomas Huth <thuth@redhat.com>\nSigned-off-by: Nina Schoetterl-Glausch <nsg@linux.ibm.com>\nMessage-ID: <20231016183925.2384704-15-nsg@linux.ibm.com>\nSigned-off-by: Thomas Huth <thuth@redhat.com>\n---\n MAINTAINERS | 2 +\n docs/devel/index-internals.rst | 1 +\n docs/devel/s390-cpu-topology.rst | 170 ++++++++++++++++++++\n docs/system/s390x/cpu-topology.rst | 244 +++++++++++++++++++++++++++++\n docs/system/target-s390x.rst | 1 +\n qapi/machine.json | 2 +\n 6 files changed, 420 insertions(+)\n create mode 100644 docs/devel/s390-cpu-topology.rst\n create mode 100644 docs/system/s390x/cpu-topology.rst", "diff": "diff --git a/MAINTAINERS b/MAINTAINERS\nindex cfc37e9af7..de8d9f5104 100644\n--- a/MAINTAINERS\n+++ b/MAINTAINERS\n@@ -1716,6 +1716,8 @@ S: Supported\n F: include/hw/s390x/cpu-topology.h\n F: hw/s390x/cpu-topology.c\n F: target/s390x/kvm/stsi-topology.c\n+F: docs/devel/s390-cpu-topology.rst\n+F: docs/system/s390x/cpu-topology.rst\n \n X86 Machines\n ------------\ndiff --git a/docs/devel/index-internals.rst b/docs/devel/index-internals.rst\nindex e1a93df263..6f81df92bc 100644\n--- a/docs/devel/index-internals.rst\n+++ b/docs/devel/index-internals.rst\n@@ -14,6 +14,7 @@ Details about QEMU's various subsystems including how to add features to them.\n migration\n multi-process\n reset\n+ s390-cpu-topology\n s390-dasd-ipl\n tracing\n vfio-migration\ndiff --git a/docs/devel/s390-cpu-topology.rst b/docs/devel/s390-cpu-topology.rst\nnew file mode 100644\nindex 0000000000..9eab28d5e5\n--- /dev/null\n+++ b/docs/devel/s390-cpu-topology.rst\n@@ -0,0 +1,170 @@\n+QAPI interface for S390 CPU topology\n+====================================\n+\n+The following sections will explain the QAPI interface for S390 CPU topology\n+with the help of exemplary output.\n+For this, let's assume that QEMU has been started with the following\n+command, defining 4 CPUs, where CPU[0] is defined by the -smp argument and will\n+have default values:\n+\n+.. code-block:: bash\n+\n+ qemu-system-s390x \\\n+ -enable-kvm \\\n+ -cpu z14,ctop=on \\\n+ -smp 1,drawers=3,books=3,sockets=2,cores=2,maxcpus=36 \\\n+ -device z14-s390x-cpu,core-id=19,entitlement=high \\\n+ -device z14-s390x-cpu,core-id=11,entitlement=low \\\n+ -device z14-s390x-cpu,core-id=112,entitlement=high \\\n+ ...\n+\n+Additions to query-cpus-fast\n+----------------------------\n+\n+The command query-cpus-fast allows querying the topology tree and\n+modifiers for all configured vCPUs.\n+\n+.. code-block:: QMP\n+\n+ { \"execute\": \"query-cpus-fast\" }\n+ {\n+ \"return\": [\n+ {\n+ \"dedicated\": false,\n+ \"thread-id\": 536993,\n+ \"props\": {\n+ \"core-id\": 0,\n+ \"socket-id\": 0,\n+ \"drawer-id\": 0,\n+ \"book-id\": 0\n+ },\n+ \"cpu-state\": \"operating\",\n+ \"entitlement\": \"medium\",\n+ \"qom-path\": \"/machine/unattached/device[0]\",\n+ \"cpu-index\": 0,\n+ \"target\": \"s390x\"\n+ },\n+ {\n+ \"dedicated\": false,\n+ \"thread-id\": 537003,\n+ \"props\": {\n+ \"core-id\": 19,\n+ \"socket-id\": 1,\n+ \"drawer-id\": 0,\n+ \"book-id\": 2\n+ },\n+ \"cpu-state\": \"operating\",\n+ \"entitlement\": \"high\",\n+ \"qom-path\": \"/machine/peripheral-anon/device[0]\",\n+ \"cpu-index\": 19,\n+ \"target\": \"s390x\"\n+ },\n+ {\n+ \"dedicated\": false,\n+ \"thread-id\": 537004,\n+ \"props\": {\n+ \"core-id\": 11,\n+ \"socket-id\": 1,\n+ \"drawer-id\": 0,\n+ \"book-id\": 1\n+ },\n+ \"cpu-state\": \"operating\",\n+ \"entitlement\": \"low\",\n+ \"qom-path\": \"/machine/peripheral-anon/device[1]\",\n+ \"cpu-index\": 11,\n+ \"target\": \"s390x\"\n+ },\n+ {\n+ \"dedicated\": true,\n+ \"thread-id\": 537005,\n+ \"props\": {\n+ \"core-id\": 112,\n+ \"socket-id\": 0,\n+ \"drawer-id\": 3,\n+ \"book-id\": 2\n+ },\n+ \"cpu-state\": \"operating\",\n+ \"entitlement\": \"high\",\n+ \"qom-path\": \"/machine/peripheral-anon/device[2]\",\n+ \"cpu-index\": 112,\n+ \"target\": \"s390x\"\n+ }\n+ ]\n+ }\n+\n+\n+QAPI command: set-cpu-topology\n+------------------------------\n+\n+The command set-cpu-topology allows modifying the topology tree\n+or the topology modifiers of a vCPU in the configuration.\n+\n+.. code-block:: QMP\n+\n+ { \"execute\": \"set-cpu-topology\",\n+ \"arguments\": {\n+ \"core-id\": 11,\n+ \"socket-id\": 0,\n+ \"book-id\": 0,\n+ \"drawer-id\": 0,\n+ \"entitlement\": \"low\",\n+ \"dedicated\": false\n+ }\n+ }\n+ {\"return\": {}}\n+\n+The core-id parameter is the only mandatory parameter and every\n+unspecified parameter keeps its previous value.\n+\n+QAPI event CPU_POLARIZATION_CHANGE\n+----------------------------------\n+\n+When a guest requests a modification of the polarization,\n+QEMU sends a CPU_POLARIZATION_CHANGE event.\n+\n+When requesting the change, the guest only specifies horizontal or\n+vertical polarization.\n+It is the job of the entity administrating QEMU to set the dedication and fine\n+grained vertical entitlement in response to this event.\n+\n+Note that a vertical polarized dedicated vCPU can only have a high\n+entitlement, giving 6 possibilities for vCPU polarization:\n+\n+- Horizontal\n+- Horizontal dedicated\n+- Vertical low\n+- Vertical medium\n+- Vertical high\n+- Vertical high dedicated\n+\n+Example of the event received when the guest issues the CPU instruction\n+Perform Topology Function PTF(0) to request an horizontal polarization:\n+\n+.. code-block:: QMP\n+\n+ {\n+ \"timestamp\": {\n+ \"seconds\": 1687870305,\n+ \"microseconds\": 566299\n+ },\n+ \"event\": \"CPU_POLARIZATION_CHANGE\",\n+ \"data\": {\n+ \"polarization\": \"horizontal\"\n+ }\n+ }\n+\n+QAPI query command: query-s390x-cpu-polarization\n+------------------------------------------------\n+\n+The query command query-s390x-cpu-polarization returns the current\n+CPU polarization of the machine.\n+In this case the guest previously issued a PTF(1) to request vertical polarization:\n+\n+.. code-block:: QMP\n+\n+ { \"execute\": \"query-s390x-cpu-polarization\" }\n+ {\n+ \"return\": {\n+ \"polarization\": \"vertical\"\n+ }\n+ }\ndiff --git a/docs/system/s390x/cpu-topology.rst b/docs/system/s390x/cpu-topology.rst\nnew file mode 100644\nindex 0000000000..5133fdc362\n--- /dev/null\n+++ b/docs/system/s390x/cpu-topology.rst\n@@ -0,0 +1,244 @@\n+.. _cpu-topology-s390x:\n+\n+CPU topology on s390x\n+=====================\n+\n+Since QEMU 8.2, CPU topology on s390x provides up to 3 levels of\n+topology containers: drawers, books and sockets. They define a\n+tree-shaped hierarchy.\n+\n+The socket container has one or more CPU entries.\n+Each of these CPU entries consists of a bitmap and three CPU attributes:\n+\n+- CPU type\n+- entitlement\n+- dedication\n+\n+Each bit set in the bitmap correspond to a core-id of a vCPU with matching\n+attributes.\n+\n+This documentation provides general information on S390 CPU topology,\n+how to enable it and explains the new CPU attributes.\n+For information on how to modify the S390 CPU topology and how to\n+monitor polarization changes, see ``docs/devel/s390-cpu-topology.rst``.\n+\n+Prerequisites\n+-------------\n+\n+To use the CPU topology, you need to run with KVM on a s390x host that\n+uses the Linux kernel v6.0 or newer (which provide the so-called\n+``KVM_CAP_S390_CPU_TOPOLOGY`` capability that allows QEMU to signal the\n+CPU topology facility via the so-called STFLE bit 11 to the VM).\n+\n+Enabling CPU topology\n+---------------------\n+\n+Currently, CPU topology is only enabled in the host model by default.\n+\n+Enabling CPU topology in a CPU model is done by setting the CPU flag\n+``ctop`` to ``on`` as in:\n+\n+.. code-block:: bash\n+\n+ -cpu gen16b,ctop=on\n+\n+Having the topology disabled by default allows migration between\n+old and new QEMU without adding new flags.\n+\n+Default topology usage\n+----------------------\n+\n+The CPU topology can be specified on the QEMU command line\n+with the ``-smp`` or the ``-device`` QEMU command arguments.\n+\n+Note also that since 7.2 threads are no longer supported in the topology\n+and the ``-smp`` command line argument accepts only ``threads=1``.\n+\n+If none of the containers attributes (drawers, books, sockets) are\n+specified for the ``-smp`` flag, the number of these containers\n+is 1.\n+\n+Thus the following two options will result in the same topology:\n+\n+.. code-block:: bash\n+\n+ -smp cpus=5,drawer=1,books=1,sockets=8,cores=4,maxcpus=32\n+\n+and\n+\n+.. code-block:: bash\n+\n+ -smp cpus=5,sockets=8,cores=4,maxcpus=32\n+\n+When a CPU is defined by the ``-smp`` command argument, its position\n+inside the topology is calculated by adding the CPUs to the topology\n+based on the core-id starting with core-0 at position 0 of socket-0,\n+book-0, drawer-0 and filling all CPUs of socket-0 before filling socket-1\n+of book-0 and so on up to the last socket of the last book of the last\n+drawer.\n+\n+When a CPU is defined by the ``-device`` command argument, the\n+tree topology attributes must all be defined or all not defined.\n+\n+.. code-block:: bash\n+\n+ -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=1\n+\n+or\n+\n+.. code-block:: bash\n+\n+ -device gen16b-s390x-cpu,core-id=1,dedicated=true\n+\n+If none of the tree attributes (drawer, book, sockets), are specified\n+for the ``-device`` argument, like for all CPUs defined with the ``-smp``\n+command argument the topology tree attributes will be set by simply\n+adding the CPUs to the topology based on the core-id.\n+\n+QEMU will not try to resolve collisions and will report an error if the\n+CPU topology defined explicitly or implicitly on a ``-device``\n+argument collides with the definition of a CPU implicitly defined\n+on the ``-smp`` argument.\n+\n+When the topology modifier attributes are not defined for the\n+``-device`` command argument they takes following default values:\n+\n+- dedicated: ``false``\n+- entitlement: ``medium``\n+\n+\n+Hot plug\n+++++++++\n+\n+New CPUs can be plugged using the device_add hmp command as in:\n+\n+.. code-block:: bash\n+\n+ (qemu) device_add gen16b-s390x-cpu,core-id=9\n+\n+The placement of the CPU is derived from the core-id as described above.\n+\n+The topology can of course also be fully defined:\n+\n+.. code-block:: bash\n+\n+ (qemu) device_add gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=1\n+\n+\n+Examples\n+++++++++\n+\n+In the following machine we define 8 sockets with 4 cores each.\n+\n+.. code-block:: bash\n+\n+ $ qemu-system-s390x -m 2G \\\n+ -cpu gen16b,ctop=on \\\n+ -smp cpus=5,sockets=8,cores=4,maxcpus=32 \\\n+ -device host-s390x-cpu,core-id=14 \\\n+\n+A new CPUs can be plugged using the device_add hmp command as before:\n+\n+.. code-block:: bash\n+\n+ (qemu) device_add gen16b-s390x-cpu,core-id=9\n+\n+The core-id defines the placement of the core in the topology by\n+starting with core 0 in socket 0 up to maxcpus.\n+\n+In the example above:\n+\n+* There are 5 CPUs provided to the guest with the ``-smp`` command line\n+ They will take the core-ids 0,1,2,3,4\n+ As we have 4 cores in a socket, we have 4 CPUs provided\n+ to the guest in socket 0, with core-ids 0,1,2,3.\n+ The last CPU, with core-id 4, will be on socket 1.\n+\n+* the core with ID 14 provided by the ``-device`` command line will\n+ be placed in socket 3, with core-id 14\n+\n+* the core with ID 9 provided by the ``device_add`` qmp command will\n+ be placed in socket 2, with core-id 9\n+\n+\n+Polarization, entitlement and dedication\n+----------------------------------------\n+\n+Polarization\n+++++++++++++\n+\n+The polarization affects how the CPUs of a shared host are utilized/distributed\n+among guests.\n+The guest determines the polarization by using the PTF instruction.\n+\n+Polarization defines two models of CPU provisioning: horizontal\n+and vertical.\n+\n+The horizontal polarization is the default model on boot and after\n+subsystem reset. When horizontal polarization is in effect all vCPUs should\n+have about equal resource provisioning.\n+\n+In the vertical polarization model vCPUs are unequal, but overall more resources\n+might be available.\n+The guest can make use of the vCPU entitlement information provided by the host\n+to optimize kernel thread scheduling.\n+\n+A subsystem reset puts all vCPU of the configuration into the\n+horizontal polarization.\n+\n+Entitlement\n++++++++++++\n+\n+The vertical polarization specifies that the guest's vCPU can get\n+different real CPU provisioning:\n+\n+- a vCPU with vertical high entitlement specifies that this\n+ vCPU gets 100% of the real CPU provisioning.\n+\n+- a vCPU with vertical medium entitlement specifies that this\n+ vCPU shares the real CPU with other vCPUs.\n+\n+- a vCPU with vertical low entitlement specifies that this\n+ vCPU only gets real CPU provisioning when no other vCPUs needs it.\n+\n+In the case a vCPU with vertical high entitlement does not use\n+the real CPU, the unused \"slack\" can be dispatched to other vCPU\n+with medium or low entitlement.\n+\n+A vCPU can be \"dedicated\" in which case the vCPU is fully dedicated to a single\n+real CPU.\n+\n+The dedicated bit is an indication of affinity of a vCPU for a real CPU\n+while the entitlement indicates the sharing or exclusivity of use.\n+\n+Defining the topology on the command line\n+-----------------------------------------\n+\n+The topology can entirely be defined using -device cpu statements,\n+with the exception of CPU 0 which must be defined with the -smp\n+argument.\n+\n+For example, here we set the position of the cores 1,2,3 to\n+drawer 1, book 1, socket 2 and cores 0,9 and 14 to drawer 0,\n+book 0, socket 0 without defining entitlement or dedication.\n+Core 4 will be set on its default position on socket 1\n+(since we have 4 core per socket) and we define it as dedicated and\n+with vertical high entitlement.\n+\n+.. code-block:: bash\n+\n+ $ qemu-system-s390x -m 2G \\\n+ -cpu gen16b,ctop=on \\\n+ -smp cpus=1,sockets=8,cores=4,maxcpus=32 \\\n+ \\\n+ -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=1 \\\n+ -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=2 \\\n+ -device gen16b-s390x-cpu,drawer-id=1,book-id=1,socket-id=2,core-id=3 \\\n+ \\\n+ -device gen16b-s390x-cpu,drawer-id=0,book-id=0,socket-id=0,core-id=9 \\\n+ -device gen16b-s390x-cpu,drawer-id=0,book-id=0,socket-id=0,core-id=14 \\\n+ \\\n+ -device gen16b-s390x-cpu,core-id=4,dedicated=on,entitlement=high\n+\n+The entitlement defined for the CPU 4 will only be used after the guest\n+successfully enables vertical polarization by using the PTF instruction.\ndiff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst\nindex f6f11433c7..94c981e732 100644\n--- a/docs/system/target-s390x.rst\n+++ b/docs/system/target-s390x.rst\n@@ -34,3 +34,4 @@ Architectural features\n .. toctree::\n s390x/bootdevices\n s390x/protvirt\n+ s390x/cpu-topology\ndiff --git a/qapi/machine.json b/qapi/machine.json\nindex b4bd26f716..6c9d2f6dcf 100644\n--- a/qapi/machine.json\n+++ b/qapi/machine.json\n@@ -909,6 +909,8 @@\n # Which members are optional and which mandatory depends on the\n # architecture and board.\n #\n+# For s390x see :ref:`cpu-topology-s390x`.\n+#\n # The ids other than the node-id specify the position of the CPU\n # within the CPU topology (as defined by the machine property \"smp\",\n # thus see also type @SMPConfiguration)\n", "prefixes": [ "PULL", "14/25" ] }