From patchwork Wed Sep 27 15:11:58 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726708 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584565wrm; Wed, 27 Sep 2023 08:13:51 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGcSFq+wtXfGN4Tuy3qkMt9snGXG6MnK4asD0ovR0kKghq6FCCBatOk381wxA1WhVXyx9IU X-Received: by 2002:a05:620a:4252:b0:770:f29f:d6cf with SMTP id w18-20020a05620a425200b00770f29fd6cfmr2535899qko.15.1695827631378; Wed, 27 Sep 2023 08:13:51 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827631; cv=none; d=google.com; s=arc-20160816; b=S/j6876CCn6Bp+ZRPwGdQ3YBnHiyWj+g9nok1t9I5W5h5Qo64aJ3g7hYyRZiarSg4I 9TPVb2F0uoype6LuChp06fLgURx0duGQ2jHsG1S+lKqZnFqq7pvzpWOI5Gr661nj2Mdz //4RVyxWDhdoqLveq1X9j/nH7y6oWj4KPn5FyLTOedJhIR+JvZTv232vQaJb2YANa9Ig B9aqbHspmj+G6dekwSl166SKM5GwiFHLi1N00oi7f5Ujmm/l0U3t+Q3DuKEkTaf4TC26 Xeune12oEXtEkhUvhzRUYOb7XDvg/UdXSe3THOa61vpRx3vcdgMEbAOa1m41drs15gD2 zZow== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=knOoQHNBrJNNAq0xZUah/ix3dH4MX2Wi/EWus+SFSVQ=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=DNPJzmujl0XIL7ICtKMly6ZyRHee9XoPrAZjuoL8MmmnhT/cwxBPNt3PS31pI7D8/1 MsF0HfTdoXJ1Dyvkmesd5fPBPfk3kbOT8XSXPUTsOeT+x09TCqHCstR5AyYcQaKHLD9k JjXDqZsTwIcf+4gN++8JNJpAwDEbooRKDtmtOwCFN9UEKtTZtDb8cBizAxvH2oJyQbHM SuvqawzPlWfIP2g8cBqpLLRjaZHU+mRV2SveiESN5XHPN9pqBI6jbUokOWi+o33ZmawT tlzY6GdR3+gBCMleUSqz5INS8t1/rQqHHc5588AERTEN2Slz44WsZ7yfSVSvZ8oRgJGI Bj9w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=m0LyF9FB; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id r17-20020a05620a299100b00773da2513acsi8440130qkp.446.2023.09.27.08.13.51 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:13:51 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=m0LyF9FB; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD2-0003Aw-Si; Wed, 27 Sep 2023 11:12:16 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD1-00036s-3W for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:15 -0400 Received: from mail-wm1-x329.google.com ([2a00:1450:4864:20::329]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWCw-0005kO-8v for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:14 -0400 Received: by mail-wm1-x329.google.com with SMTP id 5b1f17b1804b1-405417465aaso105017555e9.1 for ; Wed, 27 Sep 2023 08:12:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827528; x=1696432328; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=knOoQHNBrJNNAq0xZUah/ix3dH4MX2Wi/EWus+SFSVQ=; b=m0LyF9FBU5PCxxsHO2896MbdkN54Sxar7/ZSeJ59SkKk8EeoeFvWfeyonEgmXlMjFl HwjnixJts0ICl+JyJhj9fky4uOwOlJsd61r/KE/ACJvjM3hN1VT4pzpokqyiXLIY3aZZ 1DhKjp3Ku04VgbP3ZPAG1fUmd7ug6SdB4JbvJ9KQoTis/X3D2SJMv0bJ2mB+UkuWyR03 a/5n6l0fu6U310PPKnm2ZgV+VFkdZdj4nYcCJlYEX7wotMzzexn7nvX/zRBSER6yURQR GAHe76Bq1uV4RaUDnmzLDLzE0L8WunOunj2g9B51j1pSChuWMQ/tjjZcehq3XRFz7us9 R8nA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827528; x=1696432328; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=knOoQHNBrJNNAq0xZUah/ix3dH4MX2Wi/EWus+SFSVQ=; b=nwjPDBffOTcz6EBfeIORNbOs0/25zX1qtIQjUWfcOtY9MskZXlbF800VqHp68A+K1K VZ3D6EqfNs2wbtQN70cdNQdQfvE+Ej8Ob3M4zMF1fMcJ6EIzLh21zdQAM/tL2uHB+1I/ eLnHV0lwNMSDVNbdwIaUloMsFIdwVaN4kmW4FB2qqzZS4qsOLdYYD14V+/Kafl77hn0A Fg+nAPDQCu5S9jvcnzzXBDW3q2KtwxUKJ6mhazKJjvYHXGVqKwONYm585pqOpV0Hc6U8 zBZr9RDaORsZW3vgpWQAxDyo0S8s1NReod1Z7f+wZaN3ogEkeHZU2Jp3GFwyZcDwWhjU t3rA== X-Gm-Message-State: AOJu0Yy0v3YveOjqswtjcnNgQxfup2MGwvnOC/NfM0eofI4MswHCk+W9 9RL340bsNMn1/gaUW0boNxqb0nTPXOUkq0q1sLw= X-Received: by 2002:a05:600c:22d4:b0:401:c436:8999 with SMTP id 20-20020a05600c22d400b00401c4368999mr2224602wmg.30.1695827527772; Wed, 27 Sep 2023 08:12:07 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.07 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:07 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 1/8] docs/specs/vmw_pvscsi-spec: Convert to rST Date: Wed, 27 Sep 2023 16:11:58 +0100 Message-Id: <20230927151205.70930-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::329; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x329.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert the docs/specs/vmw_pvscsi-spec.txt file to rST format. This conversion includes some minor wordsmithing of the text to fix some grammar nits. Signed-off-by: Peter Maydell Reviewed-by: Thomas Huth --- The number of lines changed for markup formatting was such a large amount of the document that it didn't seem worth breaking out the wording tweaks separately... --- MAINTAINERS | 1 + docs/specs/index.rst | 1 + docs/specs/vmw_pvscsi-spec.rst | 115 +++++++++++++++++++++++++++++++++ docs/specs/vmw_pvscsi-spec.txt | 92 -------------------------- 4 files changed, 117 insertions(+), 92 deletions(-) create mode 100644 docs/specs/vmw_pvscsi-spec.rst delete mode 100644 docs/specs/vmw_pvscsi-spec.txt diff --git a/MAINTAINERS b/MAINTAINERS index 355b1960ce4..e0e23907871 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2283,6 +2283,7 @@ S: Maintained F: hw/net/vmxnet* F: hw/scsi/vmw_pvscsi* F: tests/qtest/vmxnet3-test.c +F: docs/specs/vwm_pvscsi-spec.rst Rocker M: Jiri Pirko diff --git a/docs/specs/index.rst b/docs/specs/index.rst index e58be38c41c..d23efbe2480 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -24,3 +24,4 @@ guest hardware that is specific to QEMU. acpi_erst sev-guest-firmware fw_cfg + vmw_pvscsi-spec diff --git a/docs/specs/vmw_pvscsi-spec.rst b/docs/specs/vmw_pvscsi-spec.rst new file mode 100644 index 00000000000..b6f434a4187 --- /dev/null +++ b/docs/specs/vmw_pvscsi-spec.rst @@ -0,0 +1,115 @@ +============================== +VMWare PVSCSI Device Interface +============================== + +.. + Created by Dmitry Fleytman (dmitry@daynix.com), Daynix Computing LTD. + +This document describes the VMWare PVSCSI device interface specification, +based on the source code of the PVSCSI Linux driver from kernel 3.0.4. + +Overview +======== + +The interface is based on a memory area shared between hypervisor and VM. +The memory area is obtained by driver as a device IO memory resource of +``PVSCSI_MEM_SPACE_SIZE`` length. +The shared memory consists of a registers area and a rings area. +The registers area is used to raise hypervisor interrupts and issue device +commands. The rings area is used to transfer data descriptors and SCSI +commands from VM to hypervisor and to transfer messages produced by +hypervisor to VM. Data itself is transferred via virtual scatter-gather DMA. + +PVSCSI Device Registers +======================= + +The length of the registers area is 1 page +(``PVSCSI_MEM_SPACE_COMMAND_NUM_PAGES``). The structure of the +registers area is described by the ``PVSCSIRegOffset`` enum. There +are registers to issue device commands (with optional short data), +issue device interrupts, and control interrupt masking. + +PVSCSI Device Rings +=================== + +There are three rings in shared memory: + +Request ring (``struct PVSCSIRingReqDesc *req_ring``) + ring for OS to device requests + +Completion ring (``struct PVSCSIRingCmpDesc *cmp_ring``) + ring for device request completions + +Message ring (``struct PVSCSIRingMsgDesc *msg_ring``) + ring for messages from device. This ring is optional and the + guest might not configure it. + +There is a control area (``struct PVSCSIRingsState *rings_state``) +used to control rings operation. + +PVSCSI Device to Host Interrupts +================================ + +The following interrupt types are supported by the PVSCSI device: + +Completion interrupts (completion ring notifications): + +- ``PVSCSI_INTR_CMPL_0`` +- ``PVSCSI_INTR_CMPL_1`` + +Message interrupts (message ring notifications): + +- ``PVSCSI_INTR_MSG_0`` +- ``PVSCSI_INTR_MSG_1`` + +Interrupts are controlled via the ``PVSCSI_REG_OFFSET_INTR_MASK`` +register. If a bit is set it means the interrupt is enabled, and if +it is clear then the interrupt is disabled. + +The interrupt modes supported are legacy, MSI and MSI-X. +In the case of legacy interrupts, the ``PVSCSI_REG_OFFSET_INTR_STATUS`` +register is used to check which interrupt has arrived. Interrupts are +acknowledged when the corresponding bit is written to the interrupt +status register. + +PVSCSI Device Operation Sequences +================================= + +Startup sequence +---------------- + +a. Issue ``PVSCSI_CMD_ADAPTER_RESET`` command +b. Windows driver reads interrupt status register here +c. Issue ``PVSCSI_CMD_SETUP_MSG_RING`` command with no additional data, + check status and disable device messages if error returned + (Omitted if device messages disabled by driver configuration) +d. Issue ``PVSCSI_CMD_SETUP_RINGS`` command, provide rings configuration + as ``struct PVSCSICmdDescSetupRings`` +e. Issue ``PVSCSI_CMD_SETUP_MSG_RING`` command again, provide + rings configuration as ``struct PVSCSICmdDescSetupMsgRing`` +f. Unmask completion and message (if device messages enabled) interrupts + +Shutdown sequence +----------------- + +a. Mask interrupts +b. Flush request ring using ``PVSCSI_REG_OFFSET_KICK_NON_RW_IO`` +c. Issue ``PVSCSI_CMD_ADAPTER_RESET`` command + +Send request +------------ + +a. Fill next free request ring descriptor +b. Issue ``PVSCSI_REG_OFFSET_KICK_RW_IO`` for R/W operations + or ``PVSCSI_REG_OFFSET_KICK_NON_RW_IO`` for other operations + +Abort command +------------- + +a. Issue ``PVSCSI_CMD_ABORT_CMD`` command + +Request completion processing +----------------------------- + +a. Upon completion interrupt arrival process completion + and message (if enabled) rings diff --git a/docs/specs/vmw_pvscsi-spec.txt b/docs/specs/vmw_pvscsi-spec.txt deleted file mode 100644 index 49affb2a423..00000000000 --- a/docs/specs/vmw_pvscsi-spec.txt +++ /dev/null @@ -1,92 +0,0 @@ -General Description -=================== - -This document describes VMWare PVSCSI device interface specification. -Created by Dmitry Fleytman (dmitry@daynix.com), Daynix Computing LTD. -Based on source code of PVSCSI Linux driver from kernel 3.0.4 - -PVSCSI Device Interface Overview -================================ - -The interface is based on memory area shared between hypervisor and VM. -Memory area is obtained by driver as device IO memory resource of -PVSCSI_MEM_SPACE_SIZE length. -The shared memory consists of registers area and rings area. -The registers area is used to raise hypervisor interrupts and issue device -commands. The rings area is used to transfer data descriptors and SCSI -commands from VM to hypervisor and to transfer messages produced by -hypervisor to VM. Data itself is transferred via virtual scatter-gather DMA. - -PVSCSI Device Registers -======================= - -The length of the registers area is 1 page (PVSCSI_MEM_SPACE_COMMAND_NUM_PAGES). -The structure of the registers area is described by the PVSCSIRegOffset enum. -There are registers to issue device command (with optional short data), -issue device interrupt, control interrupts masking. - -PVSCSI Device Rings -=================== - -There are three rings in shared memory: - - 1. Request ring (struct PVSCSIRingReqDesc *req_ring) - - ring for OS to device requests - 2. Completion ring (struct PVSCSIRingCmpDesc *cmp_ring) - - ring for device request completions - 3. Message ring (struct PVSCSIRingMsgDesc *msg_ring) - - ring for messages from device. - This ring is optional and the guest might not configure it. -There is a control area (struct PVSCSIRingsState *rings_state) used to control -rings operation. - -PVSCSI Device to Host Interrupts -================================ -There are following interrupt types supported by PVSCSI device: - 1. Completion interrupts (completion ring notifications): - PVSCSI_INTR_CMPL_0 - PVSCSI_INTR_CMPL_1 - 2. Message interrupts (message ring notifications): - PVSCSI_INTR_MSG_0 - PVSCSI_INTR_MSG_1 - -Interrupts are controlled via PVSCSI_REG_OFFSET_INTR_MASK register -Bit set means interrupt enabled, bit cleared - disabled - -Interrupt modes supported are legacy, MSI and MSI-X -In case of legacy interrupts, register PVSCSI_REG_OFFSET_INTR_STATUS -is used to check which interrupt has arrived. Interrupts are -acknowledged when the corresponding bit is written to the interrupt -status register. - -PVSCSI Device Operation Sequences -================================= - -1. Startup sequence: - a. Issue PVSCSI_CMD_ADAPTER_RESET command; - aa. Windows driver reads interrupt status register here; - b. Issue PVSCSI_CMD_SETUP_MSG_RING command with no additional data, - check status and disable device messages if error returned; - (Omitted if device messages disabled by driver configuration) - c. Issue PVSCSI_CMD_SETUP_RINGS command, provide rings configuration - as struct PVSCSICmdDescSetupRings; - d. Issue PVSCSI_CMD_SETUP_MSG_RING command again, provide - rings configuration as struct PVSCSICmdDescSetupMsgRing; - e. Unmask completion and message (if device messages enabled) interrupts. - -2. Shutdown sequences - a. Mask interrupts; - b. Flush request ring using PVSCSI_REG_OFFSET_KICK_NON_RW_IO; - c. Issue PVSCSI_CMD_ADAPTER_RESET command. - -3. Send request - a. Fill next free request ring descriptor; - b. Issue PVSCSI_REG_OFFSET_KICK_RW_IO for R/W operations; - or PVSCSI_REG_OFFSET_KICK_NON_RW_IO for other operations. - -4. Abort command - a. Issue PVSCSI_CMD_ABORT_CMD command; - -5. Request completion processing - a. Upon completion interrupt arrival process completion - and message (if enabled) rings. From patchwork Wed Sep 27 15:11:59 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726703 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584203wrm; Wed, 27 Sep 2023 08:13:08 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEI42BbltOsKaqjW0WHJdGv6HjHCmxqOHT9LydRJSCmLVWs3fqu3Wt9STu95uXiQEnMhLOM X-Received: by 2002:a0c:e345:0:b0:658:2857:ed69 with SMTP id a5-20020a0ce345000000b006582857ed69mr2229949qvm.1.1695827587804; Wed, 27 Sep 2023 08:13:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827587; cv=none; d=google.com; s=arc-20160816; b=06vFdI5f9YnS79FKiYU3gTqbZmZ6hu6iv2i0DhiWBcoE3MKQtz6UaVxVdwE/xZ5pOR bG/2H7l/36oTklR3u2Yay/JDhk66JoB7H154BOeV91LENNgpQACjYy7nQs1/wY7L+enU dQDhEOZFMg8GizHsQwdfCQglOsHS1XGwP3dknnOByh64y7RINKnbWfUGj6rbUtp3IKIM JvS50nZ7RTBfmO2IPjAXtgFNnPaUUwqD80PFcgasrcVCO3Bp7rfD22X7IQWr/mOKyQfO +FPbcpeI72XvrtUH257ZMFbKXkLhLIlxvfnANYmEX3aTt1rDBMtopwMtRi0k3WBGMurU OqrQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=9LcmYDCPs9a7neLG0AeIOd4rekXRKUZPlGGvZGGI0cQ=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=gNIQ7gycTErXQ24tA/UDIJm/d5NWWsBAnLhcwaLCiml1kVWF7+ScdqaU+ZyWsnG2g5 cTTKyrdjrH5C2iWXl265cGb/I4DaQCjV+iG8pMkkZ1rtiyJwExrKv9lSLZVA+NzmEt5Z MT2xGVnrtfX5dgRYv8KLzFQHcma9+2E79jDXopV3Jnhgex1xeZAUL78FeROMEr0xeVDW oYDGgJwc49L0Ykr07/bRuh2v2m5TNfobeLgXHzTTEmf5XOAfY8xRkeT73wHVI9dJkuOL fJGJrQ2/YN6WW57pDjPDj8qi9ZoC4UaAWkO5aX7ZtzQGcynEzorCd/uh4KPYsfoNvlFV 0g1g== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=r6PMhWnz; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id o12-20020a0cf4cc000000b0065d04f265c0si296802qvm.159.2023.09.27.08.13.07 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:13:07 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=r6PMhWnz; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD5-0003Bd-Vn; Wed, 27 Sep 2023 11:12:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD0-00035b-Ra for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:14 -0400 Received: from mail-wm1-x32b.google.com ([2a00:1450:4864:20::32b]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWCw-0005kW-0E for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:14 -0400 Received: by mail-wm1-x32b.google.com with SMTP id 5b1f17b1804b1-40566f89f6eso84396875e9.3 for ; Wed, 27 Sep 2023 08:12:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827528; x=1696432328; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=9LcmYDCPs9a7neLG0AeIOd4rekXRKUZPlGGvZGGI0cQ=; b=r6PMhWnzBKnR3L1PaDOvJTIqJHKSG2NwXkvAH32jK1Dqgkou4wd6TmWvcLF6Fix/st MofWp1MCxNffKO9E43QHwm0ooZsf1e0TPAqfAAkAxhHVu0E470zdcDka+YZ2RS0InNTB 9OaxVi3U7aLFAMTmIB4aP2d0mNzqo1ild2JjonqBGEn2BPEe+wJA+hyZXAs5sfh5tKl+ vv7mLjkK3ECBe9giOe3VXOIziFJUO4IdGi1DLsl8PTcB34VvbNM+AsLNGUkMcqztvi82 MBXPG7wa9FXAGeFNBz+HB+ntIbO8QGmJXgrYS0CVJjClVTMBy+jcVGH1vc2AHptKVcRG 8BCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827528; x=1696432328; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=9LcmYDCPs9a7neLG0AeIOd4rekXRKUZPlGGvZGGI0cQ=; b=usWz9vbTTVx87Y+Th8iYXmh94jJowc7YCUTkt1XLoeGWWTwTfoc1tDI8/xcXMw4PQp 27/MZSCmWZIwXtWmi0Rccdde7aq4paF9gtZFD9y0o41YhcPZByfJClA9Yt2jrGe4iwTm s9SMFG2hJp5j+p+8dhuDZHcfK0URlLa6F5FyiD0X0Al8MGc8vnyFUySV0OP2f3V+Yh6K N+ZlSS/clgCBeTJHXeJoSbYY8rLYrveHBC4yARbi5cDN+sGGMcBZ4TtQWzgcKfrSX0as JkKmqmOZKg860px5SoH7VZnlRSCZBVA5Gxl3Gu20qvlDvD0M41tGwL1MTFn7CAaRQl9Q GxCg== X-Gm-Message-State: AOJu0YzI5r6wD7x8JeCX6HXcujmuaAe8a4VpqdJJXAqs4wPBAV846gMX f74rF7bAqu6V8mVfBFRQh9knXXBARwmCd8d0oLQ= X-Received: by 2002:a7b:c3d5:0:b0:400:419c:bbde with SMTP id t21-20020a7bc3d5000000b00400419cbbdemr2206108wmj.18.1695827528217; Wed, 27 Sep 2023 08:12:08 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.07 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:08 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 2/8] docs/specs/edu: Convert to rST Date: Wed, 27 Sep 2023 16:11:59 +0100 Message-Id: <20230927151205.70930-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32b; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32b.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert docs/specs/edu.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Thomas Huth --- MAINTAINERS | 1 + docs/specs/{edu.txt => edu.rst} | 84 ++++++++++++++++++++------------- docs/specs/index.rst | 1 + 3 files changed, 54 insertions(+), 32 deletions(-) rename docs/specs/{edu.txt => edu.rst} (64%) diff --git a/MAINTAINERS b/MAINTAINERS index e0e23907871..9e27cad11c3 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1825,6 +1825,7 @@ EDU M: Jiri Slaby S: Maintained F: hw/misc/edu.c +F: docs/specs/edu.rst IDE M: John Snow diff --git a/docs/specs/edu.txt b/docs/specs/edu.rst similarity index 64% rename from docs/specs/edu.txt rename to docs/specs/edu.rst index 08763108099..ae72737dbb4 100644 --- a/docs/specs/edu.txt +++ b/docs/specs/edu.rst @@ -2,9 +2,10 @@ EDU device ========== -Copyright (c) 2014-2015 Jiri Slaby +.. + Copyright (c) 2014-2015 Jiri Slaby -This document is licensed under the GPLv2 (or later). + This document is licensed under the GPLv2 (or later). This is an educational device for writing (kernel) drivers. Its original intention was to support the Linux kernel lectures taught at the Masaryk @@ -15,10 +16,11 @@ The devices behaves very similar to the PCI bridge present in the COMBO6 cards developed under the Liberouter wings. Both PCI device ID and PCI space is inherited from that device. -Command line switches: - -device edu[,dma_mask=mask] +Command line switches +--------------------- - dma_mask makes the virtual device work with DMA addresses with the given +``-device edu[,dma_mask=mask]`` + ``dma_mask`` makes the virtual device work with DMA addresses with the given mask. For educational purposes, the device supports only 28 bits (256 MiB) by default. Students shall set dma_mask for the device in the OS driver properly. @@ -26,7 +28,8 @@ Command line switches: PCI specs --------- -PCI ID: 1234:11e8 +PCI ID: + ``1234:11e8`` PCI Region 0: I/O memory, 1 MB in size. Users are supposed to communicate with the card @@ -35,24 +38,29 @@ PCI Region 0: MMIO area spec -------------- -Only size == 4 accesses are allowed for addresses < 0x80. size == 4 or -size == 8 for the rest. +Only ``size == 4`` accesses are allowed for addresses ``< 0x80``. +``size == 4`` or ``size == 8`` for the rest. -0x00 (RO) : identification (0xRRrr00edu) - RR -- major version - rr -- minor version +0x00 (RO) : identification + Value is in the form ``0xRRrr00edu`` where: + - ``RR`` -- major version + - ``rr`` -- minor version 0x04 (RW) : card liveness check - It is a simple value inversion (~ C operator). + It is a simple value inversion (``~`` C operator). 0x08 (RW) : factorial computation The stored value is taken and factorial of it is put back here. This happens only after factorial bit in the status register (0x20 below) is cleared. -0x20 (RW) : status register, bitwise OR - 0x01 -- computing factorial (RO) - 0x80 -- raise interrupt after finishing factorial computation +0x20 (RW) : status register + Bitwise OR of: + + 0x01 + computing factorial (RO) + 0x80 + raise interrupt after finishing factorial computation 0x24 (RO) : interrupt status register It contains values which raised the interrupt (see interrupt raise @@ -76,13 +84,19 @@ size == 8 for the rest. 0x90 (RW) : DMA transfer count The size of the area to perform the DMA on. -0x98 (RW) : DMA command register, bitwise OR - 0x01 -- start transfer - 0x02 -- direction (0: from RAM to EDU, 1: from EDU to RAM) - 0x04 -- raise interrupt 0x100 after finishing the DMA +0x98 (RW) : DMA command register + Bitwise OR of: + + 0x01 + start transfer + 0x02 + direction (0: from RAM to EDU, 1: from EDU to RAM) + 0x04 + raise interrupt 0x100 after finishing the DMA IRQ controller -------------- + An IRQ is generated when written to the interrupt raise register. The value appears in interrupt status register when the interrupt is raised and has to be written to the interrupt acknowledge register to lower it. @@ -94,22 +108,28 @@ routine. DMA controller -------------- + One has to specify, source, destination, size, and start the transfer. One 4096 bytes long buffer at offset 0x40000 is available in the EDU device. I.e. one can perform DMA to/from this space when programmed properly. Example of transferring a 100 byte block to and from the buffer using a given -PCI address 'addr': -addr -> DMA source address -0x40000 -> DMA destination address -100 -> DMA transfer count -1 -> DMA command register -while (DMA command register & 1) - ; +PCI address ``addr``: -0x40000 -> DMA source address -addr+100 -> DMA destination address -100 -> DMA transfer count -3 -> DMA command register -while (DMA command register & 1) - ; +:: + + addr -> DMA source address + 0x40000 -> DMA destination address + 100 -> DMA transfer count + 1 -> DMA command register + while (DMA command register & 1) + ; + +:: + + 0x40000 -> DMA source address + addr+100 -> DMA destination address + 100 -> DMA transfer count + 3 -> DMA command register + while (DMA command register & 1) + ; diff --git a/docs/specs/index.rst b/docs/specs/index.rst index d23efbe2480..30a0cf3d47e 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -25,3 +25,4 @@ guest hardware that is specific to QEMU. sev-guest-firmware fw_cfg vmw_pvscsi-spec + edu From patchwork Wed Sep 27 15:12:00 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726709 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584575wrm; Wed, 27 Sep 2023 08:13:54 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEXZP7tnJPkDMmeL+7edGE4sCddsPA/YNPpLao1i5kjx5MivA60Tw0ZEUOTCc0WMbReBL3l X-Received: by 2002:a0c:a70a:0:b0:65b:1734:2534 with SMTP id u10-20020a0ca70a000000b0065b17342534mr1895129qva.48.1695827633908; Wed, 27 Sep 2023 08:13:53 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827633; cv=none; d=google.com; s=arc-20160816; b=r2eqF82Q9KP4+bM1y9lhm+77PYckJe0kQTjzVQrhvLq4ro8ygTyJnHtV7SBRFzViXQ F29M6CIXwhtPixzS2fXedR72RNaixs9x9VH+EqyFiv+QWzeKDjiIPiNvWMuKdkwm78Hr gWXbEC1OsIATk7zLFOQEAaPWoTk3meVp3DAUC4f11Hh3KmAF8YFk3Q3p96xVLZFx0Ft2 +7fu3zm9LTAgVTLIahro9TZG7dRQGc4t0B3hcul9MDRwqlxbwuNcyT3cVCacC0CGeuFe KCfkpU5XVItVtgt+G2hL30eQ4xIsa2BYXy2otvwdk4Tu4Vj/MBzlPtgwJkhrPWlOYJLp RoyQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=s5DPTjMu0+4Bk3yruDyc6XSzg1YD1XJ0PlVkpHAUkmA=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=A/J3G5HJ6KuBE59NaccGplV/AUGlNNXvLRo2V5g2xExU2MoUx2GUY25mr1avAfowQm Jlo0F3MZf3vfgGMoIcDRntOD/sy2pRbLfHDODY/xgaymayXHQ6gusBRZu9gDuPd5jSGk LsTFmZV9oVYRTLBfirFIwz/YDMrKnFOJiQ5QpGWjYGg4fZvPLUdNNxNGAo5//mRqy3O2 OjXT7ggEppqFwHbQN60ygxpw0q+gBPnD+FM3oCktIgSeEL+C+j9/i9+Xw41P8Fu+dbOc S1vUFZxJ2xDT6082MQfXvl1YlP+M3qqQV/ecLfB7+Lc8ubnTPwVTkv2VzhJv42Y3L08h Qg5w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=QDa7o6GZ; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id e12-20020a0cf34c000000b0064718f836f6si361080qvm.552.2023.09.27.08.13.53 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:13:53 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=QDa7o6GZ; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD2-0003Ao-Og; Wed, 27 Sep 2023 11:12:16 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD1-00036n-2u for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:15 -0400 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWCw-0005kY-Ab for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:14 -0400 Received: by mail-wm1-x32d.google.com with SMTP id 5b1f17b1804b1-405e48d8cfdso52351675e9.2 for ; Wed, 27 Sep 2023 08:12:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827529; x=1696432329; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=s5DPTjMu0+4Bk3yruDyc6XSzg1YD1XJ0PlVkpHAUkmA=; b=QDa7o6GZxswE6biF+UDJj4YUJQ27CBxzOu4ABNiq9+fMmzouOyObQ4lFiNHXrL02i+ rRh1UdR6Ct80pQhj+UejLPXtyH3XxY2oxQVfR6ASWPBbd1eNHO7cKnmbES5WK6YuGHys MJ7k3llJ0CWFX6t/3cbzN7DruvGlgQF9iSGEQZdZsakJK0rAInYIUVBLAnz7ht3x9QbV N2GqYXyy+IaxLDtYpmxkZxk7Twf+JRcYOdKwSrsBo5EBwfEsQWiwQIrDbzQx8ZUb7PTW RKdakQTHIoq3Nx797MAQlIQCMTGxOve7D0lRqK2K4m08qy1aYhjCy8DZf5TXCOJ1SI6E T28A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827529; x=1696432329; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=s5DPTjMu0+4Bk3yruDyc6XSzg1YD1XJ0PlVkpHAUkmA=; b=AYCnoHyuj2sIJhIsyaahunxrRBZlpA7USHRov3PUIqvkSUFj2JnIE4++xsG7HKdmGd ZhpUsjC5p/aHKy5tTX0x7CZ+RHPw3v+mNq3fP++BX9SsCrUBW147ORUZMEtx5eJoNpHy hjh++JFIW2/cQDZwyscY8u3tgrN8pIhtWiG4U4gLy6OMeYCeMs8tJrimNC6xoogMC1rV 3AHZXyglc+istdh4QrVDMc50isdHSL9MJQNhPGHmZ49PZvjm/225bU3DSRraLXwyMW6f x6SYddGR+k6NsK7QCY6HJ6tD/AUyPqhhgBU60U1DmwBhVqDr5K4IMP/mvthRWrp/rYnI GvsA== X-Gm-Message-State: AOJu0Yz1pww4s4rLF5iy0VUl+P9pDHNGyCRog7juH3YwssLpXTsMElzH wF/hfOsqFg0bko8T6BdRxy2riMrxoSV6ysaifWI= X-Received: by 2002:a7b:c4d9:0:b0:3fb:a102:6d7a with SMTP id g25-20020a7bc4d9000000b003fba1026d7amr2096154wmk.28.1695827528681; Wed, 27 Sep 2023 08:12:08 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.08 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:08 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 3/8] docs/specs/ivshmem-spec: Convert to rST Date: Wed, 27 Sep 2023 16:12:00 +0100 Message-Id: <20230927151205.70930-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32d; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32d.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert docs/specs/ivshmem-spec.txt to rST format. In converting, I have dropped the sections on the device's command line interface and usage, as they are already covered by the user-facing docs in system/devices/ivshmem.rst. I have also removed the reference to Memnic, because the URL is dead and a web search suggests that whatever this was it's pretty much sunk without trace. Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé --- docs/specs/index.rst | 1 + .../{ivshmem-spec.txt => ivshmem-spec.rst} | 63 +++++++------------ docs/specs/pci-ids.rst | 2 +- docs/system/devices/ivshmem.rst | 2 +- 4 files changed, 26 insertions(+), 42 deletions(-) rename docs/specs/{ivshmem-spec.txt => ivshmem-spec.rst} (88%) diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 30a0cf3d47e..e60c8377541 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -26,3 +26,4 @@ guest hardware that is specific to QEMU. fw_cfg vmw_pvscsi-spec edu + ivshmem-spec diff --git a/docs/specs/ivshmem-spec.txt b/docs/specs/ivshmem-spec.rst similarity index 88% rename from docs/specs/ivshmem-spec.txt rename to docs/specs/ivshmem-spec.rst index 1beb3a01ec3..2d8e80055b0 100644 --- a/docs/specs/ivshmem-spec.txt +++ b/docs/specs/ivshmem-spec.rst @@ -1,4 +1,6 @@ -= Device Specification for Inter-VM shared memory device = +====================================================== +Device Specification for Inter-VM shared memory device +====================================================== The Inter-VM shared memory device (ivshmem) is designed to share a memory region between multiple QEMU processes running different guests @@ -12,42 +14,17 @@ can obtain one from an ivshmem server. In the latter case, the device can additionally interrupt its peers, and get interrupted by its peers. +For information on configuring the ivshmem device on the QEMU +command line, see :doc:`../system/devices/ivshmem`. -== Configuring the ivshmem PCI device == - -There are two basic configurations: - -- Just shared memory: - - -device ivshmem-plain,memdev=HMB,... - - This uses host memory backend HMB. It should have option "share" - set. - -- Shared memory plus interrupts: - - -device ivshmem-doorbell,chardev=CHR,vectors=N,... - - An ivshmem server must already be running on the host. The device - connects to the server's UNIX domain socket via character device - CHR. - - Each peer gets assigned a unique ID by the server. IDs must be - between 0 and 65535. - - Interrupts are message-signaled (MSI-X). vectors=N configures the - number of vectors to use. - -For more details on ivshmem device properties, see the QEMU Emulator -user documentation. - - -== The ivshmem PCI device's guest interface == +The ivshmem PCI device's guest interface +======================================== The device has vendor ID 1af4, device ID 1110, revision 1. Before QEMU 2.6.0, it had revision 0. -=== PCI BARs === +PCI BARs +-------- The ivshmem PCI device has two or three BARs: @@ -59,8 +36,7 @@ There are two ways to use this device: - If you only need the shared memory part, BAR2 suffices. This way, you have access to the shared memory in the guest and can use it as - you see fit. Memnic, for example, uses ivshmem this way from guest - user space (see http://dpdk.org/browse/memnic). + you see fit. - If you additionally need the capability for peers to interrupt each other, you need BAR0 and BAR1. You will most likely want to write a @@ -77,10 +53,13 @@ accessing BAR2. Revision 0 of the device is not capable to tell guest software whether it is configured for interrupts. -=== PCI device registers === +PCI device registers +-------------------- BAR 0 contains the following registers: +:: + Offset Size Access On reset Function 0 4 read/write 0 Interrupt Mask bit 0: peer interrupt (rev 0) @@ -145,18 +124,20 @@ With multiple MSI-X vectors, different vectors can be used to indicate different events have occurred. The semantics of interrupt vectors are left to the application. - -== Interrupt infrastructure == +Interrupt infrastructure +======================== When configured for interrupts, the peers share eventfd objects in addition to shared memory. The shared resources are managed by an ivshmem server. -=== The ivshmem server === +The ivshmem server +------------------ The server listens on a UNIX domain socket. For each new client that connects to the server, the server + - picks an ID, - creates eventfd file descriptors for the interrupt vectors, - sends the ID and the file descriptor for the shared memory to the @@ -189,7 +170,8 @@ vectors. A standalone client is in contrib/ivshmem-client/. It can be useful for debugging. -=== The ivshmem Client-Server Protocol === +The ivshmem Client-Server Protocol +---------------------------------- An ivshmem device configured for interrupts connects to an ivshmem server. This section details the protocol between the two. @@ -245,7 +227,8 @@ Known bugs: * The protocol is poorly designed. -=== The ivshmem Client-Client Protocol === +The ivshmem Client-Client Protocol +---------------------------------- An ivshmem device configured for interrupts receives eventfd file descriptors for interrupting peers and getting interrupted by peers diff --git a/docs/specs/pci-ids.rst b/docs/specs/pci-ids.rst index d6707fa069a..c0a3dec2e7a 100644 --- a/docs/specs/pci-ids.rst +++ b/docs/specs/pci-ids.rst @@ -50,7 +50,7 @@ maintained as part of the virtio specification. by QEMU. 1af4:1110 - ivshmem device (shared memory, ``docs/specs/ivshmem-spec.txt``) + ivshmem device (:doc:`ivshmem-spec`) All other device IDs are reserved. diff --git a/docs/system/devices/ivshmem.rst b/docs/system/devices/ivshmem.rst index e7aaf34c200..ce71e256630 100644 --- a/docs/system/devices/ivshmem.rst +++ b/docs/system/devices/ivshmem.rst @@ -33,7 +33,7 @@ syntax when using the shared memory server is: When using the server, the guest will be assigned a VM ID (>=0) that allows guests using the same server to communicate via interrupts. Guests can read their VM ID from a device register (see -ivshmem-spec.txt). +:doc:`../../specs/ivshmem-spec`). Migration with ivshmem ~~~~~~~~~~~~~~~~~~~~~~ From patchwork Wed Sep 27 15:12:01 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726702 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584202wrm; Wed, 27 Sep 2023 08:13:08 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFA2vAyAbUt08XlUwvTpFcYTpWCNBTraH21lnwm1mxQBlNIc3jDE+bgLGb04OtiWzkS60yF X-Received: by 2002:ac8:5fc3:0:b0:410:ca1:62b2 with SMTP id k3-20020ac85fc3000000b004100ca162b2mr2559978qta.60.1695827587818; Wed, 27 Sep 2023 08:13:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827587; cv=none; d=google.com; s=arc-20160816; b=Rl6uNwfEeyGPEuG93hWmEVGkOirSkizOZsf6j5fTrK/7up+ybyFNLm3ziyI7ybu86k tTtWIjuGUGi6kayE1Ok7kFmGsrc3c35qnoB0VAOzcEW0Ap2Td8593Wt2RlFPde/YX0l6 fSY3etjfhNmEcn6xlZ06laqt3m2mGK8OyUbykamg7nSDrun1NwWuRKcCFe5s2ChFpR2f XieOJkBF3FMoS5DFX8SXzrNi8OlEd2Sg4QCEp/HxUCiUN493gAtHnepL5ug4KBdQpav8 8gibqbfe3stqVfJMYVBI9aZvamJwOz1jEzusMjWu2gjy/t8sHjrWPWHrFYwQR1LaYDCt omjw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=cqxGgxmXG6J8W9osNYYxJtFRwXKNwKGrhboUE2fncFA=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=lDX9YNQmTe1vV8apm5hY4OIOYXOciD4RFwcPafVHd7FY+6wBcjhg6mriyZ1qJLIecv ew2WoN2EPC5FvO0KQ7k1okfEF8R0k1oRD02VWXGeQGDxc8NGJAmzY/xrufTNxEytDNd4 7G0SMfIX/fRmyf8gIY8/xOKWwkx+irSkehti0hOP4Exj7FIZokSaDnUn0bZXcqMiGJno mdZ9yHJ0xVXjFa6vcuQ/2JbReqK6Jupxtyazj5oCkCzocf6C+LkUuyzKShxn5QK+9+CZ sLGBPBaPNMjLGUFQgw6ilmb0djsFxSWco2PvyHN/lN2zg3XcLoZjbndE1zoOA7pvfeGs /Q7A== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=ziOQwvxb; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id w20-20020a05622a135400b00417c080666dsi4910837qtk.37.2023.09.27.08.13.07 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:13:07 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=ziOQwvxb; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD5-0003BJ-1l; Wed, 27 Sep 2023 11:12:19 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD1-00037a-9N for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:15 -0400 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWCw-0005kb-CW for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:15 -0400 Received: by mail-wm1-x32d.google.com with SMTP id 5b1f17b1804b1-40537481094so115331425e9.0 for ; Wed, 27 Sep 2023 08:12:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827529; x=1696432329; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=cqxGgxmXG6J8W9osNYYxJtFRwXKNwKGrhboUE2fncFA=; b=ziOQwvxbpEg5DeAdlHNzLwqmn4HGCSamnezW1dIZ6ckkLtOyZmr0VN3sAigNUL/ex/ 9WY6igF18q1/DEdQTB8g94TBHutdJBUHbr6GXuEVSr+kfg4UmE6+CpYHajhF9gki27Hb mBsfr0FS3h1V/J7JpigSP/A4h3rUS5C4Wirq49HZQsWotuyE1S+/1CGdCmwDu70XU9x9 ySbUGmpuESromauH2i1F58G3wJOMhK2nn0uRR/aCIt/TVBqQqHyxu3AFSfsCusye4RWC c5ieJKBoNfanRMa2Zq2aCSgFVeidr2uPsgv7TfUviEBfRh8HZTDDYZOsqyba2Om4IO0P Ks+w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827529; x=1696432329; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=cqxGgxmXG6J8W9osNYYxJtFRwXKNwKGrhboUE2fncFA=; b=CYOlAYe2isjcqTTcnblUstUhvtnUEwd/mJJoIrYi8DMxCyVKpGX9CZH/bnOMISOrt5 z5kdUJsOThLgMmBpsEGMaOXS45CE+BstJ9x3R5+CGXI2g44UAHdzzKfttfGwFqaVB6tU JHojoRcU4FUe37nPVER5NRQBD8btGrykayuKiwDdRd1iysTM8pSrwETsV5E3SyD6wtnZ KWoRfOQYcopyVYjKR241IY2nWGLzfzgt8NpwzS6UY7PmmgSQz1xW8iiEAkTkf968M5Wh MfqKJ99L7VT3YspFkGL67V7/FcVdzMiuBRbX/LBDnnTy6rThLf7EDFyQPO544K6aZpVm YCHQ== X-Gm-Message-State: AOJu0YzPA7OzN43Vadfjr8L1/P+BOiF72abtx7MuNLsoiYwFGfKKGwh9 WA/cp2BWzTEpPYnZutOlQjpHAUB2B9MlJS0obDc= X-Received: by 2002:a05:600c:291:b0:405:959e:dc6f with SMTP id 17-20020a05600c029100b00405959edc6fmr2290569wmk.37.1695827529085; Wed, 27 Sep 2023 08:12:09 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.08 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:08 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 4/8] docs/specs/pvpanic: Convert to rST Date: Wed, 27 Sep 2023 16:12:01 +0100 Message-Id: <20230927151205.70930-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32d; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32d.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert docs/specs/pvpanic.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé --- docs/specs/index.rst | 1 + docs/specs/{pvpanic.txt => pvpanic.rst} | 41 ++++++++++++++++--------- 2 files changed, 28 insertions(+), 14 deletions(-) rename docs/specs/{pvpanic.txt => pvpanic.rst} (64%) diff --git a/docs/specs/index.rst b/docs/specs/index.rst index e60c8377541..52bfab2f68b 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -27,3 +27,4 @@ guest hardware that is specific to QEMU. vmw_pvscsi-spec edu ivshmem-spec + pvpanic diff --git a/docs/specs/pvpanic.txt b/docs/specs/pvpanic.rst similarity index 64% rename from docs/specs/pvpanic.txt rename to docs/specs/pvpanic.rst index 8afcde11cc8..f894bc19555 100644 --- a/docs/specs/pvpanic.txt +++ b/docs/specs/pvpanic.rst @@ -21,18 +21,21 @@ recognize. On write, the bits not recognized by the device are ignored. Software should set only bits both itself and the device recognize. Bit Definition --------------- -bit 0: a guest panic has happened and should be processed by the host -bit 1: a guest panic has happened and will be handled by the guest; - the host should record it or report it, but should not affect - the execution of the guest. +~~~~~~~~~~~~~~ + +bit 0 + a guest panic has happened and should be processed by the host +bit 1 + a guest panic has happened and will be handled by the guest; + the host should record it or report it, but should not affect + the execution of the guest. PCI Interface ------------- The PCI interface is similar to the ISA interface except that it uses an MMIO address space provided by its BAR0, 1 byte long. Any machine with a PCI bus -can enable a pvpanic device by adding '-device pvpanic-pci' to the command +can enable a pvpanic device by adding ``-device pvpanic-pci`` to the command line. ACPI Interface @@ -40,15 +43,25 @@ ACPI Interface pvpanic device is defined with ACPI ID "QEMU0001". Custom methods: -RDPT: To determine whether guest panic notification is supported. -Arguments: None -Return: Returns a byte, with the same semantics as the I/O port - interface. +RDPT +~~~~ -WRPT: To send a guest panic event -Arguments: Arg0 is a byte to be written, with the same semantics as - the I/O interface. -Return: None +To determine whether guest panic notification is supported. + +Arguments + None +Return + Returns a byte, with the same semantics as the I/O port interface. + +WRPT +~~~~ + +To send a guest panic event. + +Arguments + Arg0 is a byte to be written, with the same semantics as the I/O interface. +Return + None The ACPI device will automatically refer to the right port in case it is modified. From patchwork Wed Sep 27 15:12:02 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726707 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584522wrm; Wed, 27 Sep 2023 08:13:44 -0700 (PDT) X-Google-Smtp-Source: AGHT+IH3fdNY5lJcMJKkTsowmXTCVCUtgHLR9K+xzRbKyiVe8uA91+0Dw/Qhb+dQsXrysvb/a+oR X-Received: by 2002:a05:620a:1a08:b0:768:1e00:76c4 with SMTP id bk8-20020a05620a1a0800b007681e0076c4mr2483739qkb.51.1695827624545; Wed, 27 Sep 2023 08:13:44 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827624; cv=none; d=google.com; s=arc-20160816; b=bjsQtwfzZNIfQPt790c3Zt5gd5MJO5H9jcgj6HdY/6RuTl6HfMG4vGP/vFJvTD6P41 j5BIJC3S2lI9JkR8cxUCgqxzHc/ZLA0KvDfekvm7l5lOSBhn/RvmZeTOSOrL8o4ilRF9 8HExFG/KXxi+t7kEOlirejoTzyFCalHuzf9qS8cVB2oMTPt+E1JQOBT5UmZnfjMFLu+j 7Y+pv0yEZ7RZNx42cLwkTXi4/FkTVVLiOTTyX6dO4MgTuGzreiN3L4p0b3I02istXpcG CbaH7HBXx0jhtI1cQpriQn6e3S5rBE3WTFJv2mbriL+DNKwcw3Kq2dFwDgEZ4soNajI5 r37A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=bQLhaSO8bxf2dt7RJ4REkrTORaAg7J28JFhhMvuU+ME=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=hyyPjpCh/BTUBO/VggWeKEYvSu/HZph0HHKjTTBGrgb6X726EBKuKcYs7moKDNR7A9 JIH7mcjBzEkjUImC8xPmFMsiXfSbeOnDfS7xqVtm3DGEwVyj0qPVSHRymIMUU9lfvbKt +URBsXtywZDNMbEwAMueBwvfOWjuwdrDBQUkT6e+QVN4uZtGL1DEA0YSB7LDuwQpFhDQ 79zRXPwiciW5WMxA1bmRrBj597eZjpp9S0rCZ296oJU/DsjzEVkWSS3zmFuZks0inD9r 6pomVpvRgMlc9VtaXOGzXb1uHamTa782Sx8GxuvtowUaz5lhxyppwff0gbBPxPLtQ3Am 4F3A== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=zjExUFH8; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id rg3-20020a05620a8ec300b0076aec4d888asi8404684qkn.617.2023.09.27.08.13.44 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:13:44 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=zjExUFH8; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD6-0003BO-Pm; Wed, 27 Sep 2023 11:12:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD2-000396-4k for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:16 -0400 Received: from mail-wm1-x336.google.com ([2a00:1450:4864:20::336]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWCx-0005kj-HF for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:15 -0400 Received: by mail-wm1-x336.google.com with SMTP id 5b1f17b1804b1-4054496bde3so95800935e9.1 for ; Wed, 27 Sep 2023 08:12:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827529; x=1696432329; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=bQLhaSO8bxf2dt7RJ4REkrTORaAg7J28JFhhMvuU+ME=; b=zjExUFH8r+VayfBpvcjVwQxKl0LMPAncMU6HxrGCXMR4vMkQnV7GZ7brv+yVNtzWnV 154RhT5E5wVNedXO7U4wnaxvWjn9gB8Od8gc8wxzlaBUAEiNZm4sHHpQEWpu8EC1uQ5J 1FlYyexeQHZ1xRWZF6bYU6UJ3fIqjZNNbED2fto3TNgjBMFiCkaMIKJw1/dKXFB4R+Kg pwLSNGnM9QXO6pwOGhO2wDysJNoAIRrbHSWBkjmYITx2pb7Q3xIEl4l3Tlhnc/IkE5jg hnfg0slRUKEhpmjGCHiAGV2hHj8M4lYMtTHgy2/HvzHiXfotQ1PZSPXZJRONxaXCkDN1 rWcg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827529; x=1696432329; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=bQLhaSO8bxf2dt7RJ4REkrTORaAg7J28JFhhMvuU+ME=; b=FV8TLlXuumU9G9r/I2igqeNXtjQzLepjCrrSDMn4FyY4RJ9I8cx29Oj/hy+vd+xw64 lAegvOut4ojZBjZ/bzrRlahw/Dssal0veTVGx3y+v44DYRa3S+8pXNt1JCV69r/LNTBn 21CEJ9JMk9j1uGdx8A/17q75mznN4kJMxBwGtCLl58oF+rdsnT63JF1M73l/bDn1YmDD u0Ky2xX/OJ8lDbAx2HZmuJGNKRKmseLAvEhF1NvLG5m5LjiNYZdzrQKBD8Dmow1Q0q+8 6aHu8ylk0Htw/kLW+69B2ZOJSVBLIE3GK9chT5qhGVHyH/ueKO9gukJVBltowv8incqD CkFw== X-Gm-Message-State: AOJu0Yy2+nOtRs476rUEyL840yy37iO/3A0CuL/Y1zytgJeERUPMpCyV jfsVDI8ibrbCeZfW40SIBsA0Dj6fyfsGABxV+xc= X-Received: by 2002:a5d:444e:0:b0:31f:85d9:1bb0 with SMTP id x14-20020a5d444e000000b0031f85d91bb0mr2161838wrr.35.1695827529625; Wed, 27 Sep 2023 08:12:09 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.09 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:09 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 5/8] docs/specs/standard-vga: Convert to rST Date: Wed, 27 Sep 2023 16:12:02 +0100 Message-Id: <20230927151205.70930-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::336; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x336.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert docs/specs/standard-vga.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé --- docs/specs/index.rst | 1 + docs/specs/standard-vga.rst | 94 +++++++++++++++++++++++++++++++++++++ docs/specs/standard-vga.txt | 81 -------------------------------- hw/display/vga-isa.c | 2 +- hw/display/vga-pci.c | 2 +- 5 files changed, 97 insertions(+), 83 deletions(-) create mode 100644 docs/specs/standard-vga.rst delete mode 100644 docs/specs/standard-vga.txt diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 52bfab2f68b..ee84b8109d6 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -28,3 +28,4 @@ guest hardware that is specific to QEMU. edu ivshmem-spec pvpanic + standard-vga diff --git a/docs/specs/standard-vga.rst b/docs/specs/standard-vga.rst new file mode 100644 index 00000000000..992f429ced1 --- /dev/null +++ b/docs/specs/standard-vga.rst @@ -0,0 +1,94 @@ + +QEMU Standard VGA +================= + +Exists in two variants, for isa and pci. + +command line switches: + +``-vga std`` + picks isa for -M isapc, otherwise pci +``-device VGA`` + pci variant +``-device isa-vga`` + isa variant +``-device secondary-vga`` + legacy-free pci variant + + +PCI spec +-------- + +Applies to the pci variant only for obvious reasons. + +PCI ID + ``1234:1111`` + +PCI Region 0 + Framebuffer memory, 16 MB in size (by default). + Size is tunable via vga_mem_mb property. + +PCI Region 1 + Reserved (so we have the option to make the framebuffer bar 64bit). + +PCI Region 2 + MMIO bar, 4096 bytes in size (QEMU 1.3+) + +PCI ROM Region + Holds the vgabios (QEMU 0.14+). + + +The legacy-free variant has no ROM and has ``PCI_CLASS_DISPLAY_OTHER`` +instead of ``PCI_CLASS_DISPLAY_VGA``. + + +IO ports used +------------- + +Doesn't apply to the legacy-free pci variant, use the MMIO bar instead. + +``03c0 - 03df`` + standard vga ports +``01ce`` + bochs vbe interface index port +``01cf`` + bochs vbe interface data port (x86 only) +``01d0`` + bochs vbe interface data port + + +Memory regions used +------------------- + +``0xe0000000`` + Framebuffer memory, isa variant only. + +The pci variant used to mirror the framebuffer bar here, QEMU 0.14+ +stops doing that (except when in ``-M pc-$old`` compat mode). + + +MMIO area spec +-------------- + +Likewise applies to the pci variant only for obvious reasons. + +``0000 - 03ff`` + edid data blob. +``0400 - 041f`` + vga ioports (``0x3c0`` to ``0x3df``), remapped 1:1. Word access + is supported, bytes are written in little endian order (aka index + port first), so indexed registers can be updated with a single + mmio write (and thus only one vmexit). +``0500 - 0515`` + bochs dispi interface registers, mapped flat without index/data ports. + Use ``(index << 1)`` as offset for (16bit) register access. +``0600 - 0607`` + QEMU extended registers. QEMU 2.2+ only. + The pci revision is 2 (or greater) when these registers are present. + The registers are 32bit. +``0600`` + QEMU extended register region size, in bytes. +``0604`` + framebuffer endianness register. + - ``0xbebebebe`` indicates big endian. + - ``0x1e1e1e1e`` indicates little endian. diff --git a/docs/specs/standard-vga.txt b/docs/specs/standard-vga.txt deleted file mode 100644 index 18f75f1b302..00000000000 --- a/docs/specs/standard-vga.txt +++ /dev/null @@ -1,81 +0,0 @@ - -QEMU Standard VGA -================= - -Exists in two variants, for isa and pci. - -command line switches: - -vga std [ picks isa for -M isapc, otherwise pci ] - -device VGA [ pci variant ] - -device isa-vga [ isa variant ] - -device secondary-vga [ legacy-free pci variant ] - - -PCI spec --------- - -Applies to the pci variant only for obvious reasons. - -PCI ID: 1234:1111 - -PCI Region 0: - Framebuffer memory, 16 MB in size (by default). - Size is tunable via vga_mem_mb property. - -PCI Region 1: - Reserved (so we have the option to make the framebuffer bar 64bit). - -PCI Region 2: - MMIO bar, 4096 bytes in size (qemu 1.3+) - -PCI ROM Region: - Holds the vgabios (qemu 0.14+). - - -The legacy-free variant has no ROM and has PCI_CLASS_DISPLAY_OTHER -instead of PCI_CLASS_DISPLAY_VGA. - - -IO ports used -------------- - -Doesn't apply to the legacy-free pci variant, use the MMIO bar instead. - -03c0 - 03df : standard vga ports -01ce : bochs vbe interface index port -01cf : bochs vbe interface data port (x86 only) -01d0 : bochs vbe interface data port - - -Memory regions used -------------------- - -0xe0000000 : Framebuffer memory, isa variant only. - -The pci variant used to mirror the framebuffer bar here, qemu 0.14+ -stops doing that (except when in -M pc-$old compat mode). - - -MMIO area spec --------------- - -Likewise applies to the pci variant only for obvious reasons. - -0000 - 03ff : edid data blob. -0400 - 041f : vga ioports (0x3c0 -> 0x3df), remapped 1:1. - word access is supported, bytes are written - in little endia order (aka index port first), - so indexed registers can be updated with a - single mmio write (and thus only one vmexit). -0500 - 0515 : bochs dispi interface registers, mapped flat - without index/data ports. Use (index << 1) - as offset for (16bit) register access. - -0600 - 0607 : qemu extended registers. qemu 2.2+ only. - The pci revision is 2 (or greater) when - these registers are present. The registers - are 32bit. - 0600 : qemu extended register region size, in bytes. - 0604 : framebuffer endianness register. - - 0xbebebebe indicates big endian. - - 0x1e1e1e1e indicates little endian. diff --git a/hw/display/vga-isa.c b/hw/display/vga-isa.c index 2a5437d8037..c096ec93e52 100644 --- a/hw/display/vga-isa.c +++ b/hw/display/vga-isa.c @@ -1,7 +1,7 @@ /* * QEMU ISA VGA Emulator. * - * see docs/specs/standard-vga.txt for virtual hardware specs. + * see docs/specs/standard-vga.rst for virtual hardware specs. * * Copyright (c) 2003 Fabrice Bellard * diff --git a/hw/display/vga-pci.c b/hw/display/vga-pci.c index b351b8f299d..e4f45b4476d 100644 --- a/hw/display/vga-pci.c +++ b/hw/display/vga-pci.c @@ -1,7 +1,7 @@ /* * QEMU PCI VGA Emulator. * - * see docs/specs/standard-vga.txt for virtual hardware specs. + * see docs/specs/standard-vga.rst for virtual hardware specs. * * Copyright (c) 2003 Fabrice Bellard * From patchwork Wed Sep 27 15:12:03 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726706 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584355wrm; Wed, 27 Sep 2023 08:13:26 -0700 (PDT) X-Google-Smtp-Source: AGHT+IH5I03ptjxznhp+veDQ9H5Ch0sv3dzQ6XneHku9XUXHobRObEhCo9ScgKKEGkw1TiB++QSH X-Received: by 2002:a05:620a:2491:b0:76f:27af:2798 with SMTP id i17-20020a05620a249100b0076f27af2798mr2889522qkn.61.1695827605795; Wed, 27 Sep 2023 08:13:25 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827605; cv=none; d=google.com; s=arc-20160816; b=hThhJf/zAWR/gpsH/ix9s3NEyfmC2BdS9tOd0g/UPG65S6ux3keACW2bKVht3gvvPi 770OK0fDzroC964hYnI+FRIaWwH/kJi/7ksXYdq9SsmcUURcHA5N5MYSVxtFRYd/kk/o sJILnERmk5iXdAeO5sZB60Ys5MWHFj+6by8RDRejk1+QBH4XIWEwwY1IZdv7RfHJnaNj hZ7y36m4iemTTmTl2CxlDUs9J7xFLPW7zpFOhtKNCCU8vWWLPaW7WFd+IdSWem8oAIyQ m4lDj6gGaWirEf3T6O+fRJqwsZF48jKTnB6THhMN1x/8q2QFe1el7TsYaw/f4RNv7iI0 bFEA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=x3HQwcUCL8u5/m5uygc0R9hkwK38G1dWi3WRd+KuW1o=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=Z5HEImg6YmQEDbNDQS8+MzKbgSEp5oB5aKaZiKEHa8PHzeAlGEEIMb1VfTYzbjajuX 1kDg8lfSxLBrZCLyP+/9D5klb79LYkVgjEhKgC6S7LQ7XrZIHApDCqZWRH83bYwbfBWB LDL0hLcwUKcqnNIdljhbf9R0D6VHpn5ABoerMu8Ft+Jt/nx/ei+RwifBhuRCbQICJ88O XawC0S4sI+bmA35UerERATHgQvcGgImR2hX+9pluhVbzE2NM3BwwxQe3vUv4PmaYvHKi RuNwVUGgqngmWooKe9vVweaok/dwAV5wJG/WsjMMUFFzqavavw5bcGziu6YThH5E1Twj sNYA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=zDGuoYCN; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id l13-20020a05620a28cd00b00773cae5aec9si8494917qkp.159.2023.09.27.08.13.25 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:13:25 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=zDGuoYCN; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD3-0003BE-Vm; Wed, 27 Sep 2023 11:12:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD2-000397-4q for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:16 -0400 Received: from mail-wm1-x333.google.com ([2a00:1450:4864:20::333]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWCx-0005kr-Q0 for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:15 -0400 Received: by mail-wm1-x333.google.com with SMTP id 5b1f17b1804b1-40566f8a093so82705265e9.3 for ; Wed, 27 Sep 2023 08:12:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827530; x=1696432330; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=x3HQwcUCL8u5/m5uygc0R9hkwK38G1dWi3WRd+KuW1o=; b=zDGuoYCNh8EZ2ZswKUu3daRd0RSgVhVZER45gNd8y3Bd6atCOQtl6QLyXzH6KtJU6W yzgbbO9QPQ1+IToIAOUGYI0a3GVdKQ55qVLY9XMLUdGvViSPiB4BLz/OGa8utlF0Ni1O kBs7L6W965Z4Vovu6odmPJsIipQz7ZiEoaMABXiLwWOGvsavBGyLIO10qHu7k5RY2wrm gm1SaSp8CI5XJx8b9SrBd0VAfQeFqVkJKhENsvnDz54NDglfr1S2sLiWJDP5n6rtrz5f 4oaVlNUnrTfjg15pSR1WlMUq/zHExEl5ETwyZzncNUzqlmD8WsEQ39CGmFMOO32X5RTb SjhA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827530; x=1696432330; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=x3HQwcUCL8u5/m5uygc0R9hkwK38G1dWi3WRd+KuW1o=; b=JogpA98dFgzEledozv4/71DzxgJTsF+tKqm9oOBdqOu8IsHL/3G1cR8xe8pSmMO+zV YcqUurG8+DzBruFUy0SQVnJJiFqHhwxjb3WMTVMotNsnDfzeKOZr6tXUb4ZCVjS8b6Xr ltXx1XN36wPkRdFr4Mr8Ddrh8zvudnbccbzZ3Hv7LG/q00jcXcjgVYxTLavD4yTtrMFg WN3GUtF2wGEW91PnmKWB9nYogLdc65hkuzv8TU3JebyyuDm71aUNj4jFRnfHizj30CMv MHcnsDSL/3PDr3EklJ0m/8Ygr5PP0GW8cWVAdqVfawJaJ5hltfy0ZID8VQYk/T8XlM+n bnCA== X-Gm-Message-State: AOJu0YzYUoJSFJHbJIX/fXUts1GvPi1o2bnrLuqsDqrdyLoS1wh1gQLs Bw9DDJ2KLTJCKlpQeSUJiPRUtBYynMbHoJZdFtI= X-Received: by 2002:a5d:6a8a:0:b0:31f:a136:96c6 with SMTP id s10-20020a5d6a8a000000b0031fa13696c6mr2018834wru.42.1695827530240; Wed, 27 Sep 2023 08:12:10 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.09 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:09 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 6/8] docs/specs/virt-ctlr: Convert to rST Date: Wed, 27 Sep 2023 16:12:03 +0100 Message-Id: <20230927151205.70930-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::333; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x333.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert docs/specs/virt-ctlr.txt to rST format. I added the name of the device to give readers a bit more idea of which device we're actually documenting here. Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé --- docs/specs/index.rst | 1 + docs/specs/{virt-ctlr.txt => virt-ctlr.rst} | 12 +++++------- 2 files changed, 6 insertions(+), 7 deletions(-) rename docs/specs/{virt-ctlr.txt => virt-ctlr.rst} (70%) diff --git a/docs/specs/index.rst b/docs/specs/index.rst index ee84b8109d6..8d30968650b 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -29,3 +29,4 @@ guest hardware that is specific to QEMU. ivshmem-spec pvpanic standard-vga + virt-ctlr diff --git a/docs/specs/virt-ctlr.txt b/docs/specs/virt-ctlr.rst similarity index 70% rename from docs/specs/virt-ctlr.txt rename to docs/specs/virt-ctlr.rst index 24d38084f7f..ad3edde82d2 100644 --- a/docs/specs/virt-ctlr.txt +++ b/docs/specs/virt-ctlr.rst @@ -1,9 +1,9 @@ Virtual System Controller ========================= -This device is a simple interface defined for the pure virtual machine with no -hardware reference implementation to allow the guest kernel to send command -to the host hypervisor. +The ``virt-ctrl`` device is a simple interface defined for the pure +virtual machine with no hardware reference implementation to allow the +guest kernel to send command to the host hypervisor. The specification can evolve, the current state is defined as below. @@ -11,14 +11,12 @@ This is a MMIO mapped device using 256 bytes. Two 32bit registers are defined: -1- the features register (read-only, address 0x00) - +the features register (read-only, address 0x00) This register allows the device to report features supported by the controller. The only feature supported for the moment is power control (0x01). -2- the command register (write-only, address 0x04) - +the command register (write-only, address 0x04) This register allows the kernel to send the commands to the hypervisor. The implemented commands are part of the power control feature and are reset (1), halt (2) and panic (3). From patchwork Wed Sep 27 15:12:04 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726710 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584689wrm; Wed, 27 Sep 2023 08:14:05 -0700 (PDT) X-Google-Smtp-Source: AGHT+IHOwhCvuiiA37LxcXyw019js/VouLlb6lZcbv8Akm2uUmk76akPfwF18+16SFeoGDIh345q X-Received: by 2002:a05:620a:462b:b0:76e:e352:667a with SMTP id br43-20020a05620a462b00b0076ee352667amr2731173qkb.35.1695827645526; Wed, 27 Sep 2023 08:14:05 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827645; cv=none; d=google.com; s=arc-20160816; b=zN5ObGxtW1vqJaH2gi8FEnmxDpDneX5Valvp2qQ9TspbwB0CMQVYO6xhUdfkFPj6dM DlMOIbZPo+nUIlYk/PflUyE+FrNTRWBjDAihrvXZAbnJUHgYMCe9clDmfh2rg/niClMq DYui7rIjNIQ59YZJTDytF7nE/AYHFvo9v/v+NXxTwXWHMFInOhCOFkJfnB97+vGCn3N9 XEmUKtl6T5Y0brJZdP3u8TK5Ua34r6e3Mau+orAZHqi0AvSVzTrUE1/vJK1ZbZm7Lnnz p000YT34ECmY1iH0mI2ZVwrT4vZansXIZ5VZGZ6TUsa0EviWRDx+7/XKaXLDMZ0aAPxz oTaw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=UISaehvY3Zuvf6THCkTxk/dIC8QLdbJZ/PWTHGaPP6k=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=Ds4MqPoIt4wH4ODVw/NZU+ik+qAsZc9pnhkl83DVTCcdeCtT+AQCdhl2MXu9WvqBqJ /00szRXZwmMCF6FzoklKjC8PEo2h2vTHiNa/uyuCzXUBIpQ36vurhvaOo7NSiygfgmYS tIN0F3IQRKwi1y+T6XDVqMAzU9g4MzGw3uFyh3iZ6+ZH/dCufxb9yptXdgSKwnnt9awS 68UTDeN9HNQoHiU1zaHh+jdGl7i70j777vTURbQrS1aw9H2sxEK1Ey8aUCd1Cxw9MxR0 dAv3QADd/viNXv9KQe3WISGIIkRwTVLPu37HGlCwlFp2Pi1Yuoaxvp1jqNxQDibFKe5I U2BQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=pUHJlE2c; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id bi27-20020a05620a319b00b00773dc332a78si8480079qkb.420.2023.09.27.08.14.05 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:14:05 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=pUHJlE2c; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD7-0003DF-Ch; Wed, 27 Sep 2023 11:12:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD2-0003AZ-KM for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:16 -0400 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWD0-0005kv-2c for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:16 -0400 Received: by mail-wr1-x42e.google.com with SMTP id ffacd0b85a97d-32320381a07so7121527f8f.0 for ; Wed, 27 Sep 2023 08:12:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827531; x=1696432331; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=UISaehvY3Zuvf6THCkTxk/dIC8QLdbJZ/PWTHGaPP6k=; b=pUHJlE2cK2QWlNpgDLC0VTDF1+JqXFOBCJ5ZeGkQdFYdRWY6Zf4CjxjJLKRh4Z6Mz9 1g56W6hDDJhAaWjWmQQS+5zaZQUd0HEPcXzyblxeqNRW1qINzpQcaoGV4pdd2HxpIXRz ie3hSxo1AnmT31h8QoDhIkumAXQ5Drfcrxcr91i5bht+SDN9RC7CN38WRR/b9mz8cU/I 3xX+CznHj4a5TnjizXq0D+gIoZr6xeraBaNd1y/++mAj5IrJHv2co+kQgkKnB5aeIkJj qmxRqI683mrSat6cWRRWB0K3uglOcYqodGLCjlZXN7Rpu5b0NbnBeIB1rIOPyA2u2LhJ rfHg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827531; x=1696432331; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=UISaehvY3Zuvf6THCkTxk/dIC8QLdbJZ/PWTHGaPP6k=; b=MVE72eLyPWn+RdyrebljlppnI8a3+T8+qMua7qNSCfUPgyTHGm+HknzxfXY1c9V943 9EA96JnYTh6DGlCpG8byvTltHkNhboLBq3eD99Kkn4U99ULzP9LSSRP3VcCADUlWy98L hPMOMeRu7qTRT3PDQdx+y47vkVIS6Y9fLCB29wQctGl2ZvwTjD3DPC/u+R/cHn1mdFbj I/yUsbD5FyZBmzIVzwVy7pIL4zVvhDpkf08W0GSmWG1GIIyNrEJhR81kRUIrl/Se4r/c Ez7n9MlTQVXx+kCHVx+4MJhwSVbf6dn+2g/4ngZrGxOAtFzPrf8qWhrJy3KWSvaY/1BA bPmw== X-Gm-Message-State: AOJu0YyGtfMZjNEAJfzl84FeYzsH3VbjgM+SIz5WhLtJpef83V2pMp+B wZ2xktVVi6h9saNzp5WjHRjkTbcEyVnwPMq16hw= X-Received: by 2002:adf:e3c6:0:b0:321:6dc9:14d4 with SMTP id k6-20020adfe3c6000000b003216dc914d4mr2157913wrm.19.1695827530818; Wed, 27 Sep 2023 08:12:10 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:10 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 7/8] docs/specs/vmcoreinfo: Convert to rST Date: Wed, 27 Sep 2023 16:12:04 +0100 Message-Id: <20230927151205.70930-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42e; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42e.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert docs/specs/vmcoreinfo.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé Acked-by: Marc-André Lureau --- MAINTAINERS | 1 + docs/specs/index.rst | 1 + docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} | 33 ++++++++++--------- 3 files changed, 19 insertions(+), 16 deletions(-) rename docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} (50%) diff --git a/MAINTAINERS b/MAINTAINERS index 9e27cad11c3..23ee617acaf 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2805,6 +2805,7 @@ F: include/sysemu/dump.h F: qapi/dump.json F: scripts/dump-guest-memory.py F: stubs/dump.c +F: docs/specs/vmcoreinfo.rst Error reporting M: Markus Armbruster diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 8d30968650b..7a56ccb2155 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -30,3 +30,4 @@ guest hardware that is specific to QEMU. pvpanic standard-vga virt-ctlr + vmcoreinfo diff --git a/docs/specs/vmcoreinfo.txt b/docs/specs/vmcoreinfo.rst similarity index 50% rename from docs/specs/vmcoreinfo.txt rename to docs/specs/vmcoreinfo.rst index bcbca6fe47c..462b04474d3 100644 --- a/docs/specs/vmcoreinfo.txt +++ b/docs/specs/vmcoreinfo.rst @@ -2,19 +2,19 @@ VMCoreInfo device ================= -The `-device vmcoreinfo` will create a fw_cfg entry for a guest to +The ``-device vmcoreinfo`` will create a ``fw_cfg`` entry for a guest to store dump details. -etc/vmcoreinfo -************** +``etc/vmcoreinfo`` +================== -A guest may use this fw_cfg entry to add information details to qemu +A guest may use this ``fw_cfg`` entry to add information details to qemu dumps. The entry of 16 bytes has the following layout, in little-endian:: -#define VMCOREINFO_FORMAT_NONE 0x0 -#define VMCOREINFO_FORMAT_ELF 0x1 + #define VMCOREINFO_FORMAT_NONE 0x0 + #define VMCOREINFO_FORMAT_ELF 0x1 struct FWCfgVMCoreInfo { uint16_t host_format; /* formats host supports */ @@ -26,17 +26,17 @@ The entry of 16 bytes has the following layout, in little-endian:: Only full write (of 16 bytes) are considered valid for further processing of entry values. -A write of 0 in guest_format will disable further processing of +A write of 0 in ``guest_format`` will disable further processing of vmcoreinfo entry values & content. -You may write a guest_format that is not supported by the host, in +You may write a ``guest_format`` that is not supported by the host, in which case the entry data can be ignored by qemu (but you may still -access it through a debugger, via vmcoreinfo_realize::vmcoreinfo_state). +access it through a debugger, via ``vmcoreinfo_realize::vmcoreinfo_state``). Format & content -**************** +================ -As of qemu 2.11, only VMCOREINFO_FORMAT_ELF is supported. +As of qemu 2.11, only ``VMCOREINFO_FORMAT_ELF`` is supported. The entry gives location and size of an ELF note that is appended in qemu dumps. @@ -44,10 +44,11 @@ qemu dumps. The note format/class must be of the target bitness and the size must be less than 1Mb. -If the ELF note name is "VMCOREINFO", it is expected to be the Linux -vmcoreinfo note (see Documentation/ABI/testing/sysfs-kernel-vmcoreinfo -in Linux source). In this case, qemu dump code will read the content -as a key=value text file, looking for "NUMBER(phys_base)" key +If the ELF note name is ``VMCOREINFO``, it is expected to be the Linux +vmcoreinfo note (see `the kernel documentation for its format +`_). +In this case, qemu dump code will read the content +as a key=value text file, looking for ``NUMBER(phys_base)`` key value. The value is expected to be more accurate than architecture guess of the value. This is useful for KASLR-enabled guest with -ancient tools not handling the VMCOREINFO note. +ancient tools not handling the ``VMCOREINFO`` note. From patchwork Wed Sep 27 15:12:05 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 726705 Delivered-To: patch@linaro.org Received: by 2002:adf:ea87:0:b0:31d:da82:a3b4 with SMTP id s7csp3584277wrm; Wed, 27 Sep 2023 08:13:17 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFNsjIwunxPbPHbtURnKWCYCjgxBs/hfWCbhHS4HOWK9pbkJag3iqAt6eYkiYWajxN1Ba8N X-Received: by 2002:a37:ef14:0:b0:775:66c1:7f9e with SMTP id j20-20020a37ef14000000b0077566c17f9emr2215160qkk.30.1695827597208; Wed, 27 Sep 2023 08:13:17 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1695827597; cv=none; d=google.com; s=arc-20160816; b=HaEnA7ChblNkqk2yJD3lLofesBKfOfZrTAQnXYGvd8Ta9s269GZWNmTz66EksApHiT nj1zWmIA9dTxLkEm9alFnMHNuA2DoNULyWetx6UJlKsRsEWrXF+8/bAtrwsjSGRDAenD FSLRoqyNUrwtRQ4LP0QFistU2PdgfFvqYiu5uv8mAI6PX2cBpo6mByBL/Lf0nyHCavgM WRAjmqUJdCBfcWK3/9bFs0Fx9F7C4/lm6kdxwxWnHZbBlTQbbWW5EMPDQOVxTA7wXfgq tf7YmUNFMuPfULVirnYwtETF4sqG1W1YJ+OH33qU3WsPegJS9jsOMyNNWGXt5vdt03IM IWHg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=Z9WkMIj3HcIjiHcDDWjUWqhyK7F9Xd12Jck0M4I0pb4=; fh=PnYt+qEB9tAfMKoqBm2xjKOFpYyFFGPudh5cVIoieJM=; b=VzX1rnHE/qBNua+UN2TmOq6TRGzPxo3ktfBsXiRYCRDb56KrkaOcWTzNx6o5ImvpI9 R3k91Tcz6WdPfSXAfW1OlT4bMVYlSZ04hCn05JtpI0R8HbcaB0FASo6DQQtciKvwOu+l qzyNUotlpsU3ql2xgPodCo/hzjqCCqMav8TTasHGqsW0Xv+8hEN0Z8eQ+nyBEbQ6kzsT 6fyIR4rvNB3M4rOgDZNL4Hxih3EVVaVFT62/hHx+fyMUpDiSY151q9O1j00trAsqUKmt 5iWu3qz/H1lENkcxs/S46MIVhrSZqcaekEeB+c5a5ykkj0Z680FKaz/tYfAMAjIaO6FV +uLA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=x8fw1Fs7; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id o15-20020a05620a2a0f00b0075daf23cc89si8950246qkp.248.2023.09.27.08.13.17 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 27 Sep 2023 08:13:17 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=x8fw1Fs7; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlWD7-0003DG-TI; Wed, 27 Sep 2023 11:12:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qlWD3-0003B4-E2 for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:17 -0400 Received: from mail-wm1-x335.google.com ([2a00:1450:4864:20::335]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qlWCz-0005l0-5i for qemu-devel@nongnu.org; Wed, 27 Sep 2023 11:12:17 -0400 Received: by mail-wm1-x335.google.com with SMTP id 5b1f17b1804b1-40528376459so115671955e9.3 for ; Wed, 27 Sep 2023 08:12:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1695827531; x=1696432331; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=Z9WkMIj3HcIjiHcDDWjUWqhyK7F9Xd12Jck0M4I0pb4=; b=x8fw1Fs7EV0Q0dHlJH6oNUWJrIXHZbOM3BPWOgjuLy95nZp33EEOfwn/3Ym1VVNKy/ iJ331p9B8VkjttWdeQEMtPgdnGyEZ0qi4+mJ8VYf0iXzn9lamyB2aZW8BJdvIyIk7KKQ KWcnXQEQJoEhbvLpZBuGbiiF+D86vartb8xFj7XN3A1uf3/enxVJs3/7i7z9VRY/V11S uNvOwcL5FexWr6Ic2vVUU7t1F77G5ID3LvRFBMFS7DWNl1zeOJ1N5Kh14j1ugJ/d9kBW uO7hyI538acbmUL0kxF9vgnea5zLs80fR9iRYiLS/BPbFrs8N4OzwWqDT/Yds4Se1je1 8mLw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695827531; x=1696432331; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Z9WkMIj3HcIjiHcDDWjUWqhyK7F9Xd12Jck0M4I0pb4=; b=rGUqSTX23j8fnIMWxM3iLyTeTDqgQALCYfhDyxbqSaeOzIJfyhlPGEmKzHCA07TFrr O71je3fSM+I3J6ZGmeb52yZffiQ3iVKU/mYN30azlh+fq0U6tu4cSARthTVMVg8nOQ/V Gb5mFG5iuVTw9HZJVWqfLtpC2dL8+ugAZYOAilLqhsWzGc4YU6j9U88nVt6jUTKZtPrE Qo5FFhykd/2t//BPJwik2PGIbOyfsgf0sJMh8myqEjQO4XJEDvUJ0ZbBL19fKrPXA0Rv rCnoOEGoT4Al41Wu4i5nv9weq5dV+PdBWRhsY8ln6iQH62yjsIAml6H6lwTy3cGemam4 8IMg== X-Gm-Message-State: AOJu0YzizVeklo9UD76HQC9AX1L2H5x0VuQGEWDrykUPhK9Qh2l51I9s 7tfioPwSZI9brtwbMD2w4BejP0skGuq7lRedlkg= X-Received: by 2002:a05:600c:20d3:b0:405:3dd0:6ee9 with SMTP id y19-20020a05600c20d300b004053dd06ee9mr2296315wmm.34.1695827531320; Wed, 27 Sep 2023 08:12:11 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id n9-20020a1c7209000000b00401bbfb9b2bsm467474wmc.0.2023.09.27.08.12.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Sep 2023 08:12:11 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 8/8] docs/specs/vmgenid: Convert to rST Date: Wed, 27 Sep 2023 16:12:05 +0100 Message-Id: <20230927151205.70930-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230927151205.70930-1-peter.maydell@linaro.org> References: <20230927151205.70930-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::335; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x335.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org Convert docs/specs/vmgenid.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Ani Sinha --- MAINTAINERS | 2 +- docs/specs/index.rst | 1 + docs/specs/vmgenid.rst | 246 +++++++++++++++++++++++++++++++++++++++++ docs/specs/vmgenid.txt | 245 ---------------------------------------- 4 files changed, 248 insertions(+), 246 deletions(-) create mode 100644 docs/specs/vmgenid.rst delete mode 100644 docs/specs/vmgenid.txt diff --git a/MAINTAINERS b/MAINTAINERS index 23ee617acaf..d2338e3beb6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2369,7 +2369,7 @@ S: Orphan R: Ani Sinha F: hw/acpi/vmgenid.c F: include/hw/acpi/vmgenid.h -F: docs/specs/vmgenid.txt +F: docs/specs/vmgenid.rst F: tests/qtest/vmgenid-test.c LED diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 7a56ccb2155..b3f482b0aa5 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -31,3 +31,4 @@ guest hardware that is specific to QEMU. standard-vga virt-ctlr vmcoreinfo + vmgenid diff --git a/docs/specs/vmgenid.rst b/docs/specs/vmgenid.rst new file mode 100644 index 00000000000..9a3cefcd828 --- /dev/null +++ b/docs/specs/vmgenid.rst @@ -0,0 +1,246 @@ +Virtual Machine Generation ID Device +==================================== + +.. + Copyright (C) 2016 Red Hat, Inc. + Copyright (C) 2017 Skyport Systems, Inc. + + This work is licensed under the terms of the GNU GPL, version 2 or later. + See the COPYING file in the top-level directory. + +The VM generation ID (``vmgenid``) device is an emulated device which +exposes a 128-bit, cryptographically random, integer value identifier, +referred to as a Globally Unique Identifier, or GUID. + +This allows management applications (e.g. libvirt) to notify the guest +operating system when the virtual machine is executed with a different +configuration (e.g. snapshot execution or creation from a template). The +guest operating system notices the change, and is then able to react as +appropriate by marking its copies of distributed databases as dirty, +re-initializing its random number generator etc. + + +Requirements +------------ + +These requirements are extracted from the "How to implement virtual machine +generation ID support in a virtualization platform" section of +`the Microsoft Virtual Machine Generation ID specification +`_ dated August 1, 2012. + +- **R1a** The generation ID shall live in an 8-byte aligned buffer. + +- **R1b** The buffer holding the generation ID shall be in guest RAM, + ROM, or device MMIO range. + +- **R1c** The buffer holding the generation ID shall be kept separate from + areas used by the operating system. + +- **R1d** The buffer shall not be covered by an AddressRangeMemory or + AddressRangeACPI entry in the E820 or UEFI memory map. + +- **R1e** The generation ID shall not live in a page frame that could be + mapped with caching disabled. (In other words, regardless of whether the + generation ID lives in RAM, ROM or MMIO, it shall only be mapped as + cacheable.) + +- **R2** to **R5** [These AML requirements are isolated well enough in the + Microsoft specification for us to simply refer to them here.] + +- **R6** The hypervisor shall expose a _HID (hardware identifier) object + in the VMGenId device's scope that is unique to the hypervisor vendor. + + +QEMU Implementation +------------------- + +The above-mentioned specification does not dictate which ACPI descriptor table +will contain the VM Generation ID device. Other implementations (Hyper-V and +Xen) put it in the main descriptor table (Differentiated System Description +Table or DSDT). For ease of debugging and implementation, we have decided to +put it in its own Secondary System Description Table, or SSDT. + +The following is a dump of the contents from a running system:: + + # iasl -p ./SSDT -d /sys/firmware/acpi/tables/SSDT + + Intel ACPI Component Architecture + ASL+ Optimizing Compiler version 20150717-64 + Copyright (c) 2000 - 2015 Intel Corporation + + Reading ACPI table from file /sys/firmware/acpi/tables/SSDT - Length + 00000198 (0x0000C6) + ACPI: SSDT 0x0000000000000000 0000C6 (v01 BOCHS VMGENID 00000001 BXPC 00000001) + Acpi table [SSDT] successfully installed and loaded + Pass 1 parse of [SSDT] + Pass 2 parse of [SSDT] + Parsing Deferred Opcodes (Methods/Buffers/Packages/Regions) + + Parsing completed + Disassembly completed + ASL Output: ./SSDT.dsl - 1631 bytes + # cat SSDT.dsl + /* + * Intel ACPI Component Architecture + * AML/ASL+ Disassembler version 20150717-64 + * Copyright (c) 2000 - 2015 Intel Corporation + * + * Disassembling to symbolic ASL+ operators + * + * Disassembly of /sys/firmware/acpi/tables/SSDT, Sun Feb 5 00:19:37 2017 + * + * Original Table Header: + * Signature "SSDT" + * Length 0x000000CA (202) + * Revision 0x01 + * Checksum 0x4B + * OEM ID "BOCHS " + * OEM Table ID "VMGENID" + * OEM Revision 0x00000001 (1) + * Compiler ID "BXPC" + * Compiler Version 0x00000001 (1) + */ + DefinitionBlock ("/sys/firmware/acpi/tables/SSDT.aml", "SSDT", 1, "BOCHS ", "VMGENID", 0x00000001) + { + Name (VGIA, 0x07FFF000) + Scope (\_SB) + { + Device (VGEN) + { + Name (_HID, "QEMUVGID") // _HID: Hardware ID + Name (_CID, "VM_Gen_Counter") // _CID: Compatible ID + Name (_DDN, "VM_Gen_Counter") // _DDN: DOS Device Name + Method (_STA, 0, NotSerialized) // _STA: Status + { + Local0 = 0x0F + If ((VGIA == Zero)) + { + Local0 = Zero + } + + Return (Local0) + } + + Method (ADDR, 0, NotSerialized) + { + Local0 = Package (0x02) {} + Index (Local0, Zero) = (VGIA + 0x28) + Index (Local0, One) = Zero + Return (Local0) + } + } + } + + Method (\_GPE._E05, 0, NotSerialized) // _Exx: Edge-Triggered GPE + { + Notify (\_SB.VGEN, 0x80) // Status Change + } + } + + +Design Details: +--------------- + +Requirements R1a through R1e dictate that the memory holding the +VM Generation ID must be allocated and owned by the guest firmware, +in this case BIOS or UEFI. However, to be useful, QEMU must be able to +change the contents of the memory at runtime, specifically when starting a +backed-up or snapshotted image. In order to do this, QEMU must know the +address that has been allocated. + +The mechanism chosen for this memory sharing is writable fw_cfg blobs. +These are data object that are visible to both QEMU and guests, and are +addressable as sequential files. + +More information about fw_cfg can be found in :doc:`fw_cfg`. + +Two fw_cfg blobs are used in this case: + +``/etc/vmgenid_guid`` + +- contains the actual VM Generation ID GUID +- read-only to the guest + +``/etc/vmgenid_addr`` + +- contains the address of the downloaded vmgenid blob +- writable by the guest + + +QEMU sends the following commands to the guest at startup: + +1. Allocate memory for vmgenid_guid fw_cfg blob. +2. Write the address of vmgenid_guid into the SSDT (VGIA ACPI variable as + shown above in the iasl dump). Note that this change is not propagated + back to QEMU. +3. Write the address of vmgenid_guid back to QEMU's copy of vmgenid_addr + via the fw_cfg DMA interface. + +After step 3, QEMU is able to update the contents of vmgenid_guid at will. + +Since BIOS or UEFI does not necessarily run when we wish to change the GUID, +the value of VGIA is persisted via the VMState mechanism. + +As spelled out in the specification, any change to the GUID executes an +ACPI notification. The exact handler to use is not specified, so the vmgenid +device uses the first unused one: ``\_GPE._E05``. + + +Endian-ness Considerations: +--------------------------- + +Although not specified in Microsoft's document, it is assumed that the +device is expected to use little-endian format. + +All GUID passed in via command line or monitor are treated as big-endian. +GUID values displayed via monitor are shown in big-endian format. + + +GUID Storage Format: +-------------------- + +In order to implement an OVMF "SDT Header Probe Suppressor", the contents of +the vmgenid_guid fw_cfg blob are not simply a 128-bit GUID. There is also +significant padding in order to align and fill a memory page, as shown in the +following diagram:: + + +----------------------------------+ + | SSDT with OEM Table ID = VMGENID | + +----------------------------------+ + | ... | TOP OF PAGE + | VGIA dword object ---------------|-----> +---------------------------+ + | ... | | fw-allocated array for | + | _STA method referring to VGIA | | "etc/vmgenid_guid" | + | ... | +---------------------------+ + | ADDR method referring to VGIA | | 0: OVMF SDT Header probe | + | ... | | suppressor | + +----------------------------------+ | 36: padding for 8-byte | + | alignment | + | 40: GUID | + | 56: padding to page size | + +---------------------------+ + END OF PAGE + + +Device Usage: +------------- + +The device has one property, which may be only be set using the command line: + +``guid`` + sets the value of the GUID. A special value ``auto`` instructs + QEMU to generate a new random GUID. + +For example:: + + QEMU -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87" + QEMU -device vmgenid,guid=auto + +The property may be queried via QMP/HMP:: + + (QEMU) query-vm-generation-id + {"return": {"guid": "324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"}} + +Setting of this parameter is intentionally left out from the QMP/HMP +interfaces. There are no known use cases for changing the GUID once QEMU is +running, and adding this capability would greatly increase the complexity. diff --git a/docs/specs/vmgenid.txt b/docs/specs/vmgenid.txt deleted file mode 100644 index 80ff69f31cc..00000000000 --- a/docs/specs/vmgenid.txt +++ /dev/null @@ -1,245 +0,0 @@ -VIRTUAL MACHINE GENERATION ID -============================= - -Copyright (C) 2016 Red Hat, Inc. -Copyright (C) 2017 Skyport Systems, Inc. - -This work is licensed under the terms of the GNU GPL, version 2 or later. -See the COPYING file in the top-level directory. - -=== - -The VM generation ID (vmgenid) device is an emulated device which -exposes a 128-bit, cryptographically random, integer value identifier, -referred to as a Globally Unique Identifier, or GUID. - -This allows management applications (e.g. libvirt) to notify the guest -operating system when the virtual machine is executed with a different -configuration (e.g. snapshot execution or creation from a template). The -guest operating system notices the change, and is then able to react as -appropriate by marking its copies of distributed databases as dirty, -re-initializing its random number generator etc. - - -Requirements ------------- - -These requirements are extracted from the "How to implement virtual machine -generation ID support in a virtualization platform" section of the -specification, dated August 1, 2012. - - -The document may be found on the web at: - http://go.microsoft.com/fwlink/?LinkId=260709 - -R1a. The generation ID shall live in an 8-byte aligned buffer. - -R1b. The buffer holding the generation ID shall be in guest RAM, ROM, or device - MMIO range. - -R1c. The buffer holding the generation ID shall be kept separate from areas - used by the operating system. - -R1d. The buffer shall not be covered by an AddressRangeMemory or - AddressRangeACPI entry in the E820 or UEFI memory map. - -R1e. The generation ID shall not live in a page frame that could be mapped with - caching disabled. (In other words, regardless of whether the generation ID - lives in RAM, ROM or MMIO, it shall only be mapped as cacheable.) - -R2 to R5. [These AML requirements are isolated well enough in the Microsoft - specification for us to simply refer to them here.] - -R6. The hypervisor shall expose a _HID (hardware identifier) object in the - VMGenId device's scope that is unique to the hypervisor vendor. - - -QEMU Implementation -------------------- - -The above-mentioned specification does not dictate which ACPI descriptor table -will contain the VM Generation ID device. Other implementations (Hyper-V and -Xen) put it in the main descriptor table (Differentiated System Description -Table or DSDT). For ease of debugging and implementation, we have decided to -put it in its own Secondary System Description Table, or SSDT. - -The following is a dump of the contents from a running system: - -# iasl -p ./SSDT -d /sys/firmware/acpi/tables/SSDT - -Intel ACPI Component Architecture -ASL+ Optimizing Compiler version 20150717-64 -Copyright (c) 2000 - 2015 Intel Corporation - -Reading ACPI table from file /sys/firmware/acpi/tables/SSDT - Length -00000198 (0x0000C6) -ACPI: SSDT 0x0000000000000000 0000C6 (v01 BOCHS VMGENID 00000001 BXPC -00000001) -Acpi table [SSDT] successfully installed and loaded -Pass 1 parse of [SSDT] -Pass 2 parse of [SSDT] -Parsing Deferred Opcodes (Methods/Buffers/Packages/Regions) - -Parsing completed -Disassembly completed -ASL Output: ./SSDT.dsl - 1631 bytes -# cat SSDT.dsl -/* - * Intel ACPI Component Architecture - * AML/ASL+ Disassembler version 20150717-64 - * Copyright (c) 2000 - 2015 Intel Corporation - * - * Disassembling to symbolic ASL+ operators - * - * Disassembly of /sys/firmware/acpi/tables/SSDT, Sun Feb 5 00:19:37 2017 - * - * Original Table Header: - * Signature "SSDT" - * Length 0x000000CA (202) - * Revision 0x01 - * Checksum 0x4B - * OEM ID "BOCHS " - * OEM Table ID "VMGENID" - * OEM Revision 0x00000001 (1) - * Compiler ID "BXPC" - * Compiler Version 0x00000001 (1) - */ -DefinitionBlock ("/sys/firmware/acpi/tables/SSDT.aml", "SSDT", 1, "BOCHS ", -"VMGENID", 0x00000001) -{ - Name (VGIA, 0x07FFF000) - Scope (\_SB) - { - Device (VGEN) - { - Name (_HID, "QEMUVGID") // _HID: Hardware ID - Name (_CID, "VM_Gen_Counter") // _CID: Compatible ID - Name (_DDN, "VM_Gen_Counter") // _DDN: DOS Device Name - Method (_STA, 0, NotSerialized) // _STA: Status - { - Local0 = 0x0F - If ((VGIA == Zero)) - { - Local0 = Zero - } - - Return (Local0) - } - - Method (ADDR, 0, NotSerialized) - { - Local0 = Package (0x02) {} - Index (Local0, Zero) = (VGIA + 0x28) - Index (Local0, One) = Zero - Return (Local0) - } - } - } - - Method (\_GPE._E05, 0, NotSerialized) // _Exx: Edge-Triggered GPE - { - Notify (\_SB.VGEN, 0x80) // Status Change - } -} - - -Design Details: ---------------- - -Requirements R1a through R1e dictate that the memory holding the -VM Generation ID must be allocated and owned by the guest firmware, -in this case BIOS or UEFI. However, to be useful, QEMU must be able to -change the contents of the memory at runtime, specifically when starting a -backed-up or snapshotted image. In order to do this, QEMU must know the -address that has been allocated. - -The mechanism chosen for this memory sharing is writable fw_cfg blobs. -These are data object that are visible to both QEMU and guests, and are -addressable as sequential files. - -More information about fw_cfg can be found in "docs/specs/fw_cfg.txt" - -Two fw_cfg blobs are used in this case: - -/etc/vmgenid_guid - contains the actual VM Generation ID GUID - - read-only to the guest -/etc/vmgenid_addr - contains the address of the downloaded vmgenid blob - - writable by the guest - - -QEMU sends the following commands to the guest at startup: - -1. Allocate memory for vmgenid_guid fw_cfg blob. -2. Write the address of vmgenid_guid into the SSDT (VGIA ACPI variable as - shown above in the iasl dump). Note that this change is not propagated - back to QEMU. -3. Write the address of vmgenid_guid back to QEMU's copy of vmgenid_addr - via the fw_cfg DMA interface. - -After step 3, QEMU is able to update the contents of vmgenid_guid at will. - -Since BIOS or UEFI does not necessarily run when we wish to change the GUID, -the value of VGIA is persisted via the VMState mechanism. - -As spelled out in the specification, any change to the GUID executes an -ACPI notification. The exact handler to use is not specified, so the vmgenid -device uses the first unused one: \_GPE._E05. - - -Endian-ness Considerations: ---------------------------- - -Although not specified in Microsoft's document, it is assumed that the -device is expected to use little-endian format. - -All GUID passed in via command line or monitor are treated as big-endian. -GUID values displayed via monitor are shown in big-endian format. - - -GUID Storage Format: --------------------- - -In order to implement an OVMF "SDT Header Probe Suppressor", the contents of -the vmgenid_guid fw_cfg blob are not simply a 128-bit GUID. There is also -significant padding in order to align and fill a memory page, as shown in the -following diagram: - -+----------------------------------+ -| SSDT with OEM Table ID = VMGENID | -+----------------------------------+ -| ... | TOP OF PAGE -| VGIA dword object ---------------|-----> +---------------------------+ -| ... | | fw-allocated array for | -| _STA method referring to VGIA | | "etc/vmgenid_guid" | -| ... | +---------------------------+ -| ADDR method referring to VGIA | | 0: OVMF SDT Header probe | -| ... | | suppressor | -+----------------------------------+ | 36: padding for 8-byte | - | alignment | - | 40: GUID | - | 56: padding to page size | - +---------------------------+ - END OF PAGE - - -Device Usage: -------------- - -The device has one property, which may be only be set using the command line: - - guid - sets the value of the GUID. A special value "auto" instructs - QEMU to generate a new random GUID. - -For example: - - QEMU -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87" - QEMU -device vmgenid,guid=auto - -The property may be queried via QMP/HMP: - - (QEMU) query-vm-generation-id - {"return": {"guid": "324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"}} - -Setting of this parameter is intentionally left out from the QMP/HMP -interfaces. There are no known use cases for changing the GUID once QEMU is -running, and adding this capability would greatly increase the complexity.