From nobody Thu May 9 21:12:23 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1682006661; cv=none; d=zohomail.com; s=zohoarc; b=Ahzg9xqKad230W925S1VbpuUE1scpOvMAOGf+VbkmXIQ27iIR4ammYHVRI9zEmez3hlBnVCgr+MXt/e+nKKtvY2lzQH6NUwQyaeE3IbVLkGNHJDdG8N3tyyKuaqkkm9Kcze1nZdEbvz6c7w/kvH2NuINcMbgBL75XsuTGMIIQSo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682006661; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=4KtWjk1YyPAFh2YYAWYSn8+5K1aVdmzHriMxzP/WY2c=; b=YfLaBU6BbwQIcJOApDPV9tVdNaQwzzZgJZvdX8BKEGIlqxl5YFvZd5gPTEuPHvIHd4aeq2ZY1QU9vn8BqRkkwqTFft36RNJZb+1gMNOUdECZiwWQ2WrUBaqpHM1e0vpB906Q/hOxOFh/tqmaTpc6BH18wHA2uGsOdEjENmHEEXQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682006661088128.6362489245073; Thu, 20 Apr 2023 09:04:21 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ppWl3-00019W-IA; Thu, 20 Apr 2023 12:03:41 -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 1ppWl2-00018G-0I for qemu-devel@nongnu.org; Thu, 20 Apr 2023 12:03:40 -0400 Received: from mail-wm1-x32a.google.com ([2a00:1450:4864:20::32a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ppWkz-0002XG-Sm for qemu-devel@nongnu.org; Thu, 20 Apr 2023 12:03:39 -0400 Received: by mail-wm1-x32a.google.com with SMTP id 5b1f17b1804b1-3f17eb6b10fso5396845e9.3 for ; Thu, 20 Apr 2023 09:03:37 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id t15-20020adfe44f000000b002f00793bd7asm2310713wrm.27.2023.04.20.09.03.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Apr 2023 09:03:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1682006616; x=1684598616; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=4KtWjk1YyPAFh2YYAWYSn8+5K1aVdmzHriMxzP/WY2c=; b=iOtpz8HLtECW2CT06kHZQa2LzJD3zv3c80JbLbDZQE4fCRSuaVng2didrcgzde0Y0Q r8721XymBq3VgHY+OMSUaRYIGvycHc5bXFuU7sv+Ja8ZpC6QDJV7iN4qjU2sO3P9k0LL xSDhDtUtN5RG5tjWGk8GgZ0ID1+4NrDh+5QFVCkc1BWiwSuA/TrlsjD/L+MSoGAu/5R1 yDOIIfQ06nm3kX6onv5t9wDqjGz+Oaza5oVENZ+K8SwEEyJKttmwsppwua1UmmHDeqJa 8nxLC0rHTtapuufWgS/p837hhEU65dsj/vNcL1XM//Ce4HOnPhk73EX/FqmzEzNQTrSO GkJA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682006616; x=1684598616; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=4KtWjk1YyPAFh2YYAWYSn8+5K1aVdmzHriMxzP/WY2c=; b=IReYIQZlEa35drBBchxhH7FDPxN5xn8JwoleAjCQQKliqVnyarvQ11WTZsiKtzwCAY TR63usSMjiCtoAhyC+hfsvwgODru+skj5fsjzWXn3QfdVkJeerxlOSZMyFKkaxkXaYfQ mLOtT3zShvFwaxW5sqHz7YYM76Rqywl6ZmAwNlLWG8NviJCA4SmbVcEWWk6EudsIDL3E 5SRhIvGzP6aSEw5JrWHK6H3l8jTag0YwB5dW2kVPbD35debDbGQ++hzB+O9Q8k5cIk9v G29L/+/2lyNfCY9/nCPJ/15SwICHt8/wUTrMginQoxD2gRYBStidr7WaAqgDCh9YoXYa M9iA== X-Gm-Message-State: AAQBX9fMG+VYuDdmVbU8X8Gd0ck0irJ9+4hmfJ14YNf4haZWku9gSAu0 IqGPalfzHzHs/owfAvSblBzhToHLNqmhBueV03I= X-Google-Smtp-Source: AKy350YAqY+IjnaLl0AmoFJGI9Im1+zXnP/sOYKnY3DTHPLSRR8ih3qM2jjaJLp1cRLOw22o1eSA9A== X-Received: by 2002:a5d:508c:0:b0:2f4:bc68:3493 with SMTP id a12-20020a5d508c000000b002f4bc683493mr1814035wrt.34.1682006616267; Thu, 20 Apr 2023 09:03:36 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Marcel Apfelbaum Subject: [PATCH 1/3] docs/specs/pci-ids: Convert from txt to rST Date: Thu, 20 Apr 2023 17:03:32 +0100 Message-Id: <20230420160334.1048224-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230420160334.1048224-1-peter.maydell@linaro.org> References: <20230420160334.1048224-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32a; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32a.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, T_SCC_BODY_TEXT_LINE=-0.01 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1682006686695100001 Content-Type: text/plain; charset="utf-8" Convert the pci-ids document from plain text to reStructuredText. I opted to use definition-lists here because rST tables are super-clunky, and actually formatting these as tables didn't seem necessary. Signed-off-by: Peter Maydell --- docs/specs/index.rst | 1 + docs/specs/pci-ids.rst | 98 ++++++++++++++++++++++++++++++++++++++++++ docs/specs/pci-ids.txt | 70 ------------------------------ 3 files changed, 99 insertions(+), 70 deletions(-) create mode 100644 docs/specs/pci-ids.rst delete mode 100644 docs/specs/pci-ids.txt diff --git a/docs/specs/index.rst b/docs/specs/index.rst index a58d9311cb3..8aa0fcb77a9 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -8,6 +8,7 @@ guest hardware that is specific to QEMU. .. toctree:: :maxdepth: 2 =20 + pci-ids ppc-xive ppc-spapr-xive ppc-spapr-numa diff --git a/docs/specs/pci-ids.rst b/docs/specs/pci-ids.rst new file mode 100644 index 00000000000..e1cf022006b --- /dev/null +++ b/docs/specs/pci-ids.rst @@ -0,0 +1,98 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +PCI IDs for QEMU +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Red Hat, Inc. donates a part of its device ID range to QEMU, to be used for +virtual devices. The vendor IDs are 1af4 (formerly Qumranet ID) and 1b36. + +Contact Gerd Hoffmann to get a device ID assigned +for your devices. + +1af4 vendor ID +-------------- + +The 1000 -> 10ff device ID range is used as follows for virtio-pci devices. +Note that this allocation is separate from the virtio device IDs, which are +maintained as part of the virtio specification. + +1af4:1000 + network device (legacy) +1af4:1001 + block device (legacy) +1af4:1002 + balloon device (legacy) +1af4:1003 + console device (legacy) +1af4:1004 + SCSI host bus adapter device (legacy) +1af4:1005 + entropy generator device (legacy) +1af4:1009 + 9p filesystem device (legacy) +1af4:1012 + vsock device (bug compatibility) + +1af4:1040 to 1af4:10ef + ID range for modern virtio devices. The PCI device + ID is calculated from the virtio device ID by adding the + 0x1040 offset. The virtio IDs are defined in the virtio + specification. The Linux kernel has a header file with + defines for all virtio IDs (``linux/virtio_ids.h``); QEMU has a + copy in ``include/standard-headers/``. + +1af4:10f0 to 1a4f:10ff + Available for experimental usage without registration. Must get + official ID when the code leaves the test lab (i.e. when seeking + upstream merge or shipping a distro/product) to avoid conflicts. + +1af4:1100 + Used as PCI Subsystem ID for existing hardware devices emulated + by QEMU. + +1af4:1110 + ivshmem device (shared memory, ``docs/specs/ivshmem-spec.txt``) + +All other device IDs are reserved. + +1b36 vendor ID +-------------- + +The 0000 -> 00ff device ID range is used as follows for QEMU-specific +PCI devices (other than virtio): + +1b36:0001 + PCI-PCI bridge +1b36:0002 + PCI serial port (16550A) adapter (``docs/specs/pci-serial.txt``) +1b36:0003 + PCI Dual-port 16550A adapter (``docs/specs/pci-serial.txt``) +1b36:0004 + PCI Quad-port 16550A adapter (``docs/specs/pci-serial.txt``) +1b36:0005 + PCI test device (``docs/specs/pci-testdev.txt``) +1b36:0006 + PCI Rocker Ethernet switch device +1b36:0007 + PCI SD Card Host Controller Interface (SDHCI) +1b36:0008 + PCIe host bridge +1b36:0009 + PCI Expander Bridge (-device pxb) +1b36:000a + PCI-PCI bridge (multiseat) +1b36:000b + PCIe Expander Bridge (-device pxb-pcie) +1b36:000d + PCI xhci usb host adapter +1b36:000f + mdpy (mdev sample device), ``linux/samples/vfio-mdev/mdpy.c`` +1b36:0010 + PCIe NVMe device (``-device nvme``) +1b36:0011 + PCI PVPanic device (``-device pvpanic-pci``) +1b36:0012 + PCI ACPI ERST device (``-device acpi-erst``) + +All these devices are documented in :doc:`index`. + +The 0100 device ID is used for the QXL video card device. diff --git a/docs/specs/pci-ids.txt b/docs/specs/pci-ids.txt deleted file mode 100644 index e463c4cb3a2..00000000000 --- a/docs/specs/pci-ids.txt +++ /dev/null @@ -1,70 +0,0 @@ - -PCI IDs for qemu -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Red Hat, Inc. donates a part of its device ID range to qemu, to be used for -virtual devices. The vendor IDs are 1af4 (formerly Qumranet ID) and 1b36. - -Contact Gerd Hoffmann to get a device ID assigned -for your devices. - -1af4 vendor ID --------------- - -The 1000 -> 10ff device ID range is used as follows for virtio-pci devices. -Note that this allocation separate from the virtio device IDs, which are -maintained as part of the virtio specification. - -1af4:1000 network device (legacy) -1af4:1001 block device (legacy) -1af4:1002 balloon device (legacy) -1af4:1003 console device (legacy) -1af4:1004 SCSI host bus adapter device (legacy) -1af4:1005 entropy generator device (legacy) -1af4:1009 9p filesystem device (legacy) -1af4:1012 vsock device (bug compatibility) - -1af4:1040 Start of ID range for modern virtio devices. The PCI device - to ID is calculated from the virtio device ID by adding the -1af4:10ef 0x1040 offset. The virtio IDs are defined in the virtio - specification. The Linux kernel has a header file with - defines for all virtio IDs (linux/virtio_ids.h), qemu has a - copy in include/standard-headers/. - -1af4:10f0 Available for experimental usage without registration. Must get - to official ID when the code leaves the test lab (i.e. when seeking -1af4:10ff upstream merge or shipping a distro/product) to avoid conflicts. - -1af4:1100 Used as PCI Subsystem ID for existing hardware devices emulated - by qemu. - -1af4:1110 ivshmem device (shared memory, docs/specs/ivshmem-spec.txt) - -All other device IDs are reserved. - -1b36 vendor ID --------------- - -The 0000 -> 00ff device ID range is used as follows for QEMU-specific -PCI devices (other than virtio): - -1b36:0001 PCI-PCI bridge -1b36:0002 PCI serial port (16550A) adapter (docs/specs/pci-serial.txt) -1b36:0003 PCI Dual-port 16550A adapter (docs/specs/pci-serial.txt) -1b36:0004 PCI Quad-port 16550A adapter (docs/specs/pci-serial.txt) -1b36:0005 PCI test device (docs/specs/pci-testdev.txt) -1b36:0006 PCI Rocker Ethernet switch device -1b36:0007 PCI SD Card Host Controller Interface (SDHCI) -1b36:0008 PCIe host bridge -1b36:0009 PCI Expander Bridge (-device pxb) -1b36:000a PCI-PCI bridge (multiseat) -1b36:000b PCIe Expander Bridge (-device pxb-pcie) -1b36:000d PCI xhci usb host adapter -1b36:000f mdpy (mdev sample device), linux/samples/vfio-mdev/mdpy.c -1b36:0010 PCIe NVMe device (-device nvme) -1b36:0011 PCI PVPanic device (-device pvpanic-pci) -1b36:0012 PCI ACPI ERST device (-device acpi-erst) - -All these devices are documented in docs/specs. - -The 0100 device ID is used for the QXL video card device. --=20 2.34.1 From nobody Thu May 9 21:12:23 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1682006662; cv=none; d=zohomail.com; s=zohoarc; b=Et5XxjyHO74rFTBQxhSZUlaAH0FmUtoMily0kwVxjR+MPHIYJxGDtRXHyKPvrzSDPIlMKZO67/ooUAg8u7v+Lq1bX6uHcqy47IWIEzWNpte6AX6QXbjkBYSg9jbaW467/fmjoPkJnjVrfYWMBB+h86e/Yu2ZIa3eqOYyUN8ZHNc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682006662; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=MvM/dGz9lk9l3Z7mH1Ow8yocGvGE3ke4HNmnP6n7qD0=; b=EVacdapMEZwN6L3yK7pZlcOU0lirlnxJPt+8lYDKswLy2WZ6c5WIPpmwbwV/h+56HZtIoM7A7avSoRGpm1zSBZpq2x+fiad9l0L6UrG6J7mWa+Mb2//Xa17aCCh4+9mZ9hDNJ5S0i27STSaOYLKvv+muoSvWs+DGhX2OO1Ywuz8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682006662489718.9478019351468; Thu, 20 Apr 2023 09:04:22 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ppWl4-0001AM-Qd; Thu, 20 Apr 2023 12:03:42 -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 1ppWl3-00018z-3Y for qemu-devel@nongnu.org; Thu, 20 Apr 2023 12:03:41 -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 1ppWl1-0002XR-8I for qemu-devel@nongnu.org; Thu, 20 Apr 2023 12:03:40 -0400 Received: by mail-wr1-x42e.google.com with SMTP id ffacd0b85a97d-2f95231618aso495538f8f.1 for ; Thu, 20 Apr 2023 09:03:38 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id t15-20020adfe44f000000b002f00793bd7asm2310713wrm.27.2023.04.20.09.03.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Apr 2023 09:03:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1682006617; x=1684598617; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=MvM/dGz9lk9l3Z7mH1Ow8yocGvGE3ke4HNmnP6n7qD0=; b=j77yUYzNmzuxcicwzeO+lU9uTowRkH3meZXipMxBNQ6JsG8/gVUbYx5LHI4Ffncxa7 V1GSpKdCcpv34Y8r5EqwJbk0hcjoGxucVjOqHffuY0EVbXcZdXzBeKL0H4W/09Julk2T wyNmeY+Z/Z4GIGzEDHGT1JnFJCsu0mQCxQ9ACcdKWXWnIQcITHigKA0yFWQ7mzkp8Poe lC/Wmi4XEfXpTp1mHoGs2N0okkN6VnnMX4Xy07HPVeJ0jw81qmrykUG/JZeMM75yt0JY C2m9VmSNHXk2HCu4QAGMy8ijEz6OLR3+UfouzHdJ/4WGkrmoBg3oFC+qLvRrCX5YaEDj Yv4A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682006617; x=1684598617; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=MvM/dGz9lk9l3Z7mH1Ow8yocGvGE3ke4HNmnP6n7qD0=; b=b7nkPkGeG2C8YkA7g5L/66pYkjDWHjdV62Qq9IWI8jikBbm1Nwg6o/xgqRzc0KpD8j WP0U+R0GQ6SAiyBVAN+dhsXCtgr9fha4upfr1AUHuoC2VeHtSHwc33QHPhhbzOyVhbtO THcBLJ7a9GIYdOoEQiNs2bHkkDo3iJpHFHqd9I/MIEiYhcFFK4+1LNXE1vXhCj8d5qEV zOQ7LxSWuxvYjU5Sfvo6QtD17k/OvKPAGE2ispXU1x+aevRCR0fCwTsHz5jeGhRVeg4k fA0n71nlttci9UJ8REB6vUZ50CIf0i9v5taB1uQgkrjZljaRTifN0lodBV+c0WjAWDz3 5qUQ== X-Gm-Message-State: AAQBX9dV37g0gFEJ94/4pwNmeud7wWL7IhmiHA1/DEWBL4uUYWGZYGFZ Q3Mcn7g6qkexoXmHElKJ8luuFQ5VSw4FOKLp8X8= X-Google-Smtp-Source: AKy350YY1J4Z5kJpnPG6vvCQqVmLgx+FxuE8gnzR3Vkedz9r5yxJLTUHWrXjTVIGZfECq4gzQkkaEw== X-Received: by 2002:a5d:4385:0:b0:2d2:29a4:4457 with SMTP id i5-20020a5d4385000000b002d229a44457mr1560972wrq.13.1682006616814; Thu, 20 Apr 2023 09:03:36 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Marcel Apfelbaum Subject: [PATCH 2/3] docs/specs: Convert pci-serial.txt to rst Date: Thu, 20 Apr 2023 17:03:33 +0100 Message-Id: <20230420160334.1048224-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230420160334.1048224-1-peter.maydell@linaro.org> References: <20230420160334.1048224-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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, T_SCC_BODY_TEXT_LINE=-0.01 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1682006683315100001 Content-Type: text/plain; charset="utf-8" Convert pci-serial.txt to reStructuredText. This includes some wordsmithing, and the correction of the docs to note that the Windows inf file includes 2x and 4x support (as it has done since commit dc9528fdf9f61 in 2014). Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- docs/specs/index.rst | 1 + docs/specs/pci-ids.rst | 6 +++--- docs/specs/pci-serial.rst | 37 +++++++++++++++++++++++++++++++++++++ docs/specs/pci-serial.txt | 34 ---------------------------------- hw/char/serial-pci-multi.c | 2 +- hw/char/serial-pci.c | 2 +- 6 files changed, 43 insertions(+), 39 deletions(-) create mode 100644 docs/specs/pci-serial.rst delete mode 100644 docs/specs/pci-serial.txt diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 8aa0fcb77a9..dfa136073c7 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -9,6 +9,7 @@ guest hardware that is specific to QEMU. :maxdepth: 2 =20 pci-ids + pci-serial ppc-xive ppc-spapr-xive ppc-spapr-numa diff --git a/docs/specs/pci-ids.rst b/docs/specs/pci-ids.rst index e1cf022006b..7bc7168fb6a 100644 --- a/docs/specs/pci-ids.rst +++ b/docs/specs/pci-ids.rst @@ -63,11 +63,11 @@ PCI devices (other than virtio): 1b36:0001 PCI-PCI bridge 1b36:0002 - PCI serial port (16550A) adapter (``docs/specs/pci-serial.txt``) + PCI serial port (16550A) adapter (:doc:`pci-serial`) 1b36:0003 - PCI Dual-port 16550A adapter (``docs/specs/pci-serial.txt``) + PCI Dual-port 16550A adapter (:doc:`pci-serial`) 1b36:0004 - PCI Quad-port 16550A adapter (``docs/specs/pci-serial.txt``) + PCI Quad-port 16550A adapter (:doc:`pci-serial`) 1b36:0005 PCI test device (``docs/specs/pci-testdev.txt``) 1b36:0006 diff --git a/docs/specs/pci-serial.rst b/docs/specs/pci-serial.rst new file mode 100644 index 00000000000..8d916a36697 --- /dev/null +++ b/docs/specs/pci-serial.rst @@ -0,0 +1,37 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU PCI serial devices +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +QEMU implements some PCI serial devices which are simple PCI +wrappers around one or more 16550 UARTs. + +There is one single-port variant and two multiport-variants. Linux +guests work out-of-the box with all cards. There is a Windows inf file +(``docs/qemupciserial.inf``) to set up the cards in Windows guests. + + +Single-port card +---------------- + +Name: + ``pci-serial`` +PCI ID: + 1b36:0002 +PCI Region 0: + IO bar, 8 bytes long, with the 16550 UART mapped to it. +Interrupt: + Wired to pin A. + + +Multiport cards +--------------- + +Name: + ``pci-serial-2x``, ``pci-serial-4x`` +PCI ID: + 1b36:0003 (``-2x``) and 1b36:0004 (``-4x``) +PCI Region 0: + IO bar, with two or four 16550 UARTs mapped after each other. + The first is at offset 0, the second at offset 8, and so on. +Interrupt: + Wired to pin A. diff --git a/docs/specs/pci-serial.txt b/docs/specs/pci-serial.txt deleted file mode 100644 index 66c761f2b40..00000000000 --- a/docs/specs/pci-serial.txt +++ /dev/null @@ -1,34 +0,0 @@ - -QEMU pci serial devices -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -There is one single-port variant and two muliport-variants. Linux -guests out-of-the box with all cards. There is a Windows inf file -(docs/qemupciserial.inf) to setup the single-port card in Windows -guests. - - -single-port card ----------------- - -Name: pci-serial -PCI ID: 1b36:0002 - -PCI Region 0: - IO bar, 8 bytes long, with the 16550 uart mapped to it. - Interrupt is wired to pin A. - - -multiport cards ---------------- - -Name: pci-serial-2x -PCI ID: 1b36:0003 - -Name: pci-serial-4x -PCI ID: 1b36:0004 - -PCI Region 0: - IO bar, with two/four 16550 uart mapped after each other. - The first is at offset 0, second at offset 8, ... - Interrupt is wired to pin A. diff --git a/hw/char/serial-pci-multi.c b/hw/char/serial-pci-multi.c index f18b8dcce5f..5d65c534cb5 100644 --- a/hw/char/serial-pci-multi.c +++ b/hw/char/serial-pci-multi.c @@ -25,7 +25,7 @@ * THE SOFTWARE. */ =20 -/* see docs/specs/pci-serial.txt */ +/* see docs/specs/pci-serial.rst */ =20 #include "qemu/osdep.h" #include "qapi/error.h" diff --git a/hw/char/serial-pci.c b/hw/char/serial-pci.c index 801b769abab..087da3059a4 100644 --- a/hw/char/serial-pci.c +++ b/hw/char/serial-pci.c @@ -23,7 +23,7 @@ * THE SOFTWARE. */ =20 -/* see docs/specs/pci-serial.txt */ +/* see docs/specs/pci-serial.rst */ =20 #include "qemu/osdep.h" #include "qapi/error.h" --=20 2.34.1 From nobody Thu May 9 21:12:23 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1682006662; cv=none; d=zohomail.com; s=zohoarc; b=NoJ4HzmJw1ieBerjc1FkndyQBFOmmEcHbN/q7S1UleYVQX8xdB/K+UUNcOlL2EuWyJtaZ2PN4DoTIYqHyR+Rd0tkD3qEbMi2ZjcNe9N798poObT3XrviyYjf+oJ1Ui5wRktsoZBAQ/NeKcTThZvbBBeh3POzGAZa5KwUmazI5pQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682006662; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=97h3guJIF7ej//rRX4s5bfA+m2o4sn5HcBcQsWFToTE=; b=oFym1g5psatXrfHoSN11ZLeGkNIvZEGnQjCUMVXyS0aUGhMXAI6XW+vuFcRvKCwq36OIX+sB98TXYf5EXJTcZUMBHGo7MO7YqIdVOeeMg94L8CWqPugaFIwGpntivXND4PzVW+GEddYbBQbbCpkKjFYpLMaMdamY6aEAOvKs0bs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682006662502738.6314646621132; Thu, 20 Apr 2023 09:04:22 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ppWl4-00019x-6j; Thu, 20 Apr 2023 12:03:42 -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 1ppWl3-00018w-0l for qemu-devel@nongnu.org; Thu, 20 Apr 2023 12:03:41 -0400 Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ppWl1-0002XZ-0g for qemu-devel@nongnu.org; Thu, 20 Apr 2023 12:03:40 -0400 Received: by mail-wr1-x433.google.com with SMTP id ffacd0b85a97d-2f833bda191so473986f8f.1 for ; Thu, 20 Apr 2023 09:03:38 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id t15-20020adfe44f000000b002f00793bd7asm2310713wrm.27.2023.04.20.09.03.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Apr 2023 09:03:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1682006617; x=1684598617; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=97h3guJIF7ej//rRX4s5bfA+m2o4sn5HcBcQsWFToTE=; b=yowsJcbM9cG8yr+51147wWkK+SWlZrnFSBBv+GqP+4TjLLzls1OIl0vLxRIhlTk3Gi jTmT3NYZwekqRJif6ioSH7tnB50YZiwSEhKRKdF3wO2ysXuNfP6abJTH1r8+Zz4xAzaw 7CsS0PbQ0lvEZhzjWCgbhWSzBLZphC6z0PNbuRL9P2LQgEZ6SpBqFulvjPDAVSJ1oVmz cdil3AGNTftBuHHRetLv/Zf8tltFXQDbXK2kW4Sxd6OTzlXMb/l18Gf1TqCdf8Lov1T/ UgF9FIQV0R0PGDYcQ/iIGkzZs9pgLF1PTfFKELJonolAnD19DoVbvhtB9S4Uy97aYzVk HTvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682006617; x=1684598617; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=97h3guJIF7ej//rRX4s5bfA+m2o4sn5HcBcQsWFToTE=; b=GaKenN1oDNKaUPBUWkJ9Xgy1++bNfjGPKD7bajSeIT2gmzHZFkRy078hLhFVGkmHyG /J7EmjEF0IQyd2YcgY4d9VLGBMlHMX7MK4dS0r8ITVPfqehG9hMoHVAaBee6bnPrOowQ P4/hmM970+prvhGXjzs8/yA8VS1qd2Ed5ZcZ3veidMbC0YNRgG5pxSg9grSYyYLNFuGK 98aWPkH4925rQ497Eay6yauef5UmheSHKSoLRNGGrhWP8Sa6MU9X24BqdR/FKIci6TjR GOBeHvAg0uSvp6SZnlP2YIMruhcn3BwcORwIkAqne6igzPRSLwfP0N/A+kjABUABdEoM aVHg== X-Gm-Message-State: AAQBX9filWRdijsQhKAJ4nYoAMXqKFOq7s15sfMwxFd6+enIF1DBb9cn x0LrZgAdFTN8I4Ko4YcpBln6YwTablg4MOy+T+o= X-Google-Smtp-Source: AKy350Y35ewhu7duLFQQlmYC2uOZSeTlcHwtUdOhwdfesOSqxCef6Msg2v1MoSIDSR42qiZlijfLqw== X-Received: by 2002:a5d:460c:0:b0:2f5:fbe5:bb1c with SMTP id t12-20020a5d460c000000b002f5fbe5bb1cmr1638312wrq.63.1682006617287; Thu, 20 Apr 2023 09:03:37 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Marcel Apfelbaum Subject: [PATCH 3/3] docs/specs: Convert pci-testdev.txt to rst Date: Thu, 20 Apr 2023 17:03:34 +0100 Message-Id: <20230420160334.1048224-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230420160334.1048224-1-peter.maydell@linaro.org> References: <20230420160334.1048224-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::433; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x433.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, T_SCC_BODY_TEXT_LINE=-0.01 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1682006664706100003 Content-Type: text/plain; charset="utf-8" Convert pci-testdev.txt to reStructuredText. Includes some minor wordsmithing. Signed-off-by: Peter Maydell --- docs/specs/index.rst | 1 + docs/specs/pci-ids.rst | 2 +- docs/specs/pci-testdev.rst | 39 ++++++++++++++++++++++++++++++++++++++ docs/specs/pci-testdev.txt | 31 ------------------------------ 4 files changed, 41 insertions(+), 32 deletions(-) create mode 100644 docs/specs/pci-testdev.rst delete mode 100644 docs/specs/pci-testdev.txt diff --git a/docs/specs/index.rst b/docs/specs/index.rst index dfa136073c7..e58be38c41c 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -10,6 +10,7 @@ guest hardware that is specific to QEMU. =20 pci-ids pci-serial + pci-testdev ppc-xive ppc-spapr-xive ppc-spapr-numa diff --git a/docs/specs/pci-ids.rst b/docs/specs/pci-ids.rst index 7bc7168fb6a..e302bea484e 100644 --- a/docs/specs/pci-ids.rst +++ b/docs/specs/pci-ids.rst @@ -69,7 +69,7 @@ PCI devices (other than virtio): 1b36:0004 PCI Quad-port 16550A adapter (:doc:`pci-serial`) 1b36:0005 - PCI test device (``docs/specs/pci-testdev.txt``) + PCI test device (:doc:`pci-testdev`) 1b36:0006 PCI Rocker Ethernet switch device 1b36:0007 diff --git a/docs/specs/pci-testdev.rst b/docs/specs/pci-testdev.rst new file mode 100644 index 00000000000..4b6d36543b7 --- /dev/null +++ b/docs/specs/pci-testdev.rst @@ -0,0 +1,39 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU PCI test device +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``pci-testdev`` is a device used for testing low level IO. + +The device implements up to three BARs: BAR0, BAR1 and BAR2. +Each of BAR 0+1 can be memory or IO. Guests must detect +BAR types and act accordingly. + +BAR 0+1 size is up to 4K bytes each. +BAR 0+1 starts with the following header: + +.. code-block:: c + + typedef struct PCITestDevHdr { + uint8_t test; /* write-only, starts a given test number */ + uint8_t width_type; /* + * read-only, type and width of access for a gi= ven test. + * 1,2,4 for byte,word or long write. + * any other value if test not supported on thi= s BAR + */ + uint8_t pad0[2]; + uint32_t offset; /* read-only, offset in this BAR for a given te= st */ + uint32_t data; /* read-only, data to use for a given test */ + uint32_t count; /* for debugging. number of writes detected. */ + uint8_t name[]; /* for debugging. 0-terminated ASCII string. */ + } PCITestDevHdr; + +All registers are little endian. + +The device is expected to always implement tests 0 to N on each BAR, and t= o add new +tests with higher numbers. In this way a guest can scan test numbers unti= l it +detects an access type that it does not support on this BAR, then stop. + +BAR2 is a 64bit memory BAR, without backing storage. It is disabled +by default and can be enabled using the ``membar=3D`` property. This +can be used to test whether guests handle PCI BARs of a specific +(possibly quite large) size correctly. diff --git a/docs/specs/pci-testdev.txt b/docs/specs/pci-testdev.txt deleted file mode 100644 index 4280a1e73c5..00000000000 --- a/docs/specs/pci-testdev.txt +++ /dev/null @@ -1,31 +0,0 @@ -pci-test is a device used for testing low level IO - -device implements up to three BARs: BAR0, BAR1 and BAR2. -Each of BAR 0+1 can be memory or IO. Guests must detect -BAR types and act accordingly. - -BAR 0+1 size is up to 4K bytes each. -BAR 0+1 starts with the following header: - -typedef struct PCITestDevHdr { - uint8_t test; <- write-only, starts a given test number - uint8_t width_type; <- read-only, type and width of access for a given= test. - 1,2,4 for byte,word or long write. - any other value if test not supported on this B= AR - uint8_t pad0[2]; - uint32_t offset; <- read-only, offset in this BAR for a given test - uint32_t data; <- read-only, data to use for a given test - uint32_t count; <- for debugging. number of writes detected. - uint8_t name[]; <- for debugging. 0-terminated ASCII string. -} PCITestDevHdr; - -All registers are little endian. - -device is expected to always implement tests 0 to N on each BAR, and to ad= d new -tests with higher numbers. In this way a guest can scan test numbers unti= l it -detects an access type that it does not support on this BAR, then stop. - -BAR2 is a 64bit memory bar, without backing storage. It is disabled -by default and can be enabled using the membar=3D property. This -can be used to test whether guests handle pci bars of a specific -(possibly quite large) size correctly. --=20 2.34.1