From nobody Tue Apr 30 02:08:29 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1631030288578288.86960786673194; Tue, 7 Sep 2021 08:58:08 -0700 (PDT) Received: from localhost ([::1]:60086 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mNdU7-0002w0-Ds for importer@patchew.org; Tue, 07 Sep 2021 11:58:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53422) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mNdSo-0000xc-SY for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:46 -0400 Received: from mail-ed1-x52f.google.com ([2a00:1450:4864:20::52f]:36786) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mNdSn-00067F-6U for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:46 -0400 Received: by mail-ed1-x52f.google.com with SMTP id u19so14624149edb.3 for ; Tue, 07 Sep 2021 08:56:44 -0700 (PDT) Received: from avogadro.lan ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id h30sm6869669edz.40.2021.09.07.08.56.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Sep 2021 08:56:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=AWzamfV+E41PXw44M8NVUJe8mjyUcRc5MKys0dNFKps=; b=M1cr4dnwaeJ3ZFRm6hpN59HTqCM+UaVwqqqUEotU/hq7EB10VGXbUxB3GfeMw7Kg3P zu9xZkeFbGZum+wC3yTmweMDDMtyO8KuZ6A2J/QBzRRWiVwpShExlIq3S61e4YdFU1Gq ycxgtjCa74cf8Ax9kselxqmrQSVW8Qv2+rqGHJ25ry3tRvphUfNx4ym3Uk0nUWiUzFS+ gSJTcZrOJIUVO1XTUvkDKVVpJOhpy7nVuymcnqKSVJdjt8fST33dOEnyaL8duUaErhx3 k0Kr3Q8gHnQXHzWUCiX5Y0/8hRgN5XWL7rscJwjPCMXloXQSEkswtuTZEM3N/LIhdJpj l49Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=AWzamfV+E41PXw44M8NVUJe8mjyUcRc5MKys0dNFKps=; b=ID6Xo98xHhdMxqvBmjqswrt8I67qD1qMpza2RlT63Yt9xplEZS9pNbsPDTAPYsVJiC 7kgm9LHDVoby0vPruDhKid+hAZZjcj6VTyC0MxDbs+LYAByd3ldKVu2D5L9lUhK7+nR/ LTCKcClL8ja6rXnR/I5toLn3yryAwoyUp6R0ovHUUDPORE3hJ3RMBi2k0h9kSVr+EdKh RH1hH2vhn8Vh377aJkeFuzYxErFIIZXrkjQMxWMM7FxNk6fXnbzXP7MPqLNXDyQkGCn2 VzHsP9BOFslxF7D78a15gkg7gHrfD0K6qseQAn3z4z6iOWkvf/lQOMg1YTAnAcVvVwvk yapQ== X-Gm-Message-State: AOAM533xFee4wE0A9KnWh27urDc4QLJzWHXkZlBaPvIHEZrd0s4a3g0a QnePN7jwzYnLUWMdCbSjsl7StC5sSI0= X-Google-Smtp-Source: ABdhPJzhIQpqueEKuXM6PXkjT/CPYCkVnq+hmAlUdVl+VurUZX6xoq1PRg+sAzxHmWRxpPBKv6IEUQ== X-Received: by 2002:a05:6402:d6b:: with SMTP id ec43mr134547edb.107.1631030203446; Tue, 07 Sep 2021 08:56:43 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 1/5] docs: standardize book titles to === with overline Date: Tue, 7 Sep 2021 17:56:37 +0200 Message-Id: <20210907155641.197844-2-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210907155641.197844-1-pbonzini@redhat.com> References: <20210907155641.197844-1-pbonzini@redhat.com> 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::52f; envelope-from=paolo.bonzini@gmail.com; helo=mail-ed1-x52f.google.com X-Spam_score_int: 4 X-Spam_score: 0.4 X-Spam_bar: / X-Spam_report: (0.4 / 5.0 requ) DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1631030289194100001 Content-Type: text/plain; charset="utf-8" Documents within a Sphinx manual are separate files and therefore can use different conventions for headings. However, keeping some consistency is useful so that included files are easy to get right. This patch uses a standard heading format for book titles, so that it is obvious when a file sits at the top level toctree of a book or man page. The heading is irrelevant for man pages, but keep it consistent as well. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/index.rst | 1 + docs/system/qemu-block-drivers.rst | 1 + docs/system/qemu-cpu-models.rst | 1 + docs/system/qemu-manpage.rst | 5 +++-- docs/tools/qemu-img.rst | 1 + docs/tools/qemu-nbd.rst | 1 + docs/tools/qemu-pr-helper.rst | 1 + docs/tools/qemu-storage-daemon.rst | 1 + docs/tools/qemu-trace-stap.rst | 1 + 9 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 5f7eaaa632..0b9ee9901d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,7 @@ You can adapt this file completely to your liking, but it should at lea= st contain the root `toctree` directive. =20 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D Welcome to QEMU's documentation! =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-dr= ivers.rst index bd99d4fa8e..eb276481d6 100644 --- a/docs/system/qemu-block-drivers.rst +++ b/docs/system/qemu-block-drivers.rst @@ -1,5 +1,6 @@ :orphan: =20 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D QEMU block drivers reference =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.= rst index 53d7538c47..8c51e2bf49 100644 --- a/docs/system/qemu-cpu-models.rst +++ b/docs/system/qemu-cpu-models.rst @@ -1,5 +1,6 @@ :orphan: =20 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D QEMU / KVM CPU model configuration =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst index e9a25d0680..d6f44e265b 100644 --- a/docs/system/qemu-manpage.rst +++ b/docs/system/qemu-manpage.rst @@ -6,8 +6,9 @@ parts of the documentation that go in the manpage as well as the HTML manual. =20 -Title -=3D=3D=3D=3D=3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU User Documentation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Synopsis -------- diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst index b7d602a288..fe6c30d509 100644 --- a/docs/tools/qemu-img.rst +++ b/docs/tools/qemu-img.rst @@ -1,3 +1,4 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D QEMU disk image utility =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/docs/tools/qemu-nbd.rst b/docs/tools/qemu-nbd.rst index ee862fa0bc..e39a9f4b1a 100644 --- a/docs/tools/qemu-nbd.rst +++ b/docs/tools/qemu-nbd.rst @@ -1,3 +1,4 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D QEMU Disk Network Block Device Server =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/docs/tools/qemu-pr-helper.rst b/docs/tools/qemu-pr-helper.rst index ac036180ac..eaebe40da0 100644 --- a/docs/tools/qemu-pr-helper.rst +++ b/docs/tools/qemu-pr-helper.rst @@ -1,3 +1,4 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D QEMU persistent reservation helper =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-d= aemon.rst index 3ec4bdd914..b8ef4486f1 100644 --- a/docs/tools/qemu-storage-daemon.rst +++ b/docs/tools/qemu-storage-daemon.rst @@ -1,3 +1,4 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D QEMU Storage Daemon =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/docs/tools/qemu-trace-stap.rst b/docs/tools/qemu-trace-stap.rst index fb70445c75..d53073b52b 100644 --- a/docs/tools/qemu-trace-stap.rst +++ b/docs/tools/qemu-trace-stap.rst @@ -1,3 +1,4 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D QEMU SystemTap trace tool =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D =20 --=20 2.31.1 From nobody Tue Apr 30 02:08:29 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1631030307964146.86709823619333; Tue, 7 Sep 2021 08:58:27 -0700 (PDT) Received: from localhost ([::1]:60312 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mNdUQ-00034o-Vh for importer@patchew.org; Tue, 07 Sep 2021 11:58:27 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53456) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mNdSq-0000xx-5v for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:48 -0400 Received: from mail-ed1-x52f.google.com ([2a00:1450:4864:20::52f]:39509) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mNdSn-00067t-K9 for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:47 -0400 Received: by mail-ed1-x52f.google.com with SMTP id r7so14591240edd.6 for ; Tue, 07 Sep 2021 08:56:45 -0700 (PDT) Received: from avogadro.lan ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id h30sm6869669edz.40.2021.09.07.08.56.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Sep 2021 08:56:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=VVWgi+atl4jLVLLDOWnirX4uUum7p0X1vILK9y8ze6M=; b=mFDQ6pRmGcg898LG5NdiS4Nqd5FjyeNZNSaFRxBylkjfht2ea6DB+64hWCESPvKZoX pktuLxu8uMc+/RcRFZL1QJeStHeM6KOuJ34jcmetwN55dfmylonltTwARhr//lxFfCxv Ma/k3qGvmZfApX48knYra578inuRpSl+Vf27V3U4Qwvk8DOHYYtjEG7oIQk0WJHLiROQ PLsUfRzkm8zeBud2f6uusdhjV+E7OKrzFnGD+vKFEz7Nk4SYmd9ZBE50yTKnVlDoMdIQ 1R2T3yTNfdxMhWDJ5WvYVsF9aSr/2xkzwBVZqO1Cc3cZcztRkW4WaE70Sxa7iJJAIgNd S7OQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=VVWgi+atl4jLVLLDOWnirX4uUum7p0X1vILK9y8ze6M=; b=HNP/DBqxc1N+bi2HTjiky/B5mG+h6W5pFSsYLVxCF6kPoii3qMw4ofLE0QdCfqIVMb GI2Aq8SJurt3QPFfQzAyZ6HNNLx93FjkGCBd7e0US6jn4dFDXaTAD4N/7xVSL8+jIbW5 pHD3WB07ftaEV4OP8S6t3Nkl3KKqlrDVnrOophKrIVtQxP0sUe5J9LuquXHVIrCILjVX VVFrFKon091GjarshQlq+s6WCTHeMccgumSqq5QqdjodAS/i0dK7M3aygX6qGHsd4Kds vYM3XHVDc9iJyM+DIro5j/WH/sviG11AtSY7pSbZBJB8K85CF64snZE1j/WVrOA2HPho YTGw== X-Gm-Message-State: AOAM532mVjMz1zw+msfzdIR6Jqs/QZL+gO8SzDfz7AiGTtIMGqS7mwNt WfulVNoHKpn/hba1hOPuexggqt2Ir5M= X-Google-Smtp-Source: ABdhPJxQEeAB+7nsew0W4z2rDX1r/XMJrCmiqirxUHUi635OL/PKQmcUPkT/QZlbONKcDtjWhqQMmw== X-Received: by 2002:a05:6402:1907:: with SMTP id e7mr122751edz.201.1631030204082; Tue, 07 Sep 2021 08:56:44 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 2/5] docs: standardize directory index to --- with overline Date: Tue, 7 Sep 2021 17:56:38 +0200 Message-Id: <20210907155641.197844-3-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210907155641.197844-1-pbonzini@redhat.com> References: <20210907155641.197844-1-pbonzini@redhat.com> 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::52f; envelope-from=paolo.bonzini@gmail.com; helo=mail-ed1-x52f.google.com X-Spam_score_int: -14 X-Spam_score: -1.5 X-Spam_bar: - X-Spam_report: (-1.5 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1631030308916100002 Content-Type: text/plain; charset="utf-8" Use a standard heading format for the index.rst file in a directory. Using overlines makes it clear that individual documents can use e.g. =3D=3D=3D for chapter titles and --- for section titles, as suggested in the Linux kernel guidelines[1]. They could do it anyway, because documents included in a toctree are parsed separately and therefore are not tied to the same conventions for headings. However, keeping some consistency is useful since sometimes files are included from multiple places. [1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/about/index.rst | 3 ++- docs/devel/index.rst | 3 ++- docs/interop/index.rst | 3 ++- docs/specs/index.rst | 3 ++- docs/system/index.rst | 3 ++- docs/tools/index.rst | 3 ++- docs/user/index.rst | 3 ++- 7 files changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/about/index.rst b/docs/about/index.rst index beb762aa0a..5bea653c07 100644 --- a/docs/about/index.rst +++ b/docs/about/index.rst @@ -1,5 +1,6 @@ +---------- About QEMU -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +---------- =20 QEMU is a generic and open source machine emulator and virtualizer. =20 diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 5522db7241..f95df10b3e 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -1,5 +1,6 @@ +--------------------- Developer Information -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +--------------------- =20 This section of the manual documents various parts of the internals of QEM= U. You only need to read it if you are interested in reading or diff --git a/docs/interop/index.rst b/docs/interop/index.rst index f9801a9c20..47b9ed82bb 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -1,5 +1,6 @@ +------------------------------------------------ System Emulation Management and Interoperability -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +------------------------------------------------ =20 This section of the manual contains documents and specifications that are useful for making QEMU interoperate with other software. diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 65e9663916..ecc43896bb 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -1,5 +1,6 @@ +---------------------------------------------- System Emulation Guest Hardware Specifications -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +---------------------------------------------- =20 This section of the manual contains specifications of guest hardware that is specific to QEMU. diff --git a/docs/system/index.rst b/docs/system/index.rst index 7b9276c05f..73bbedbc22 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -1,5 +1,6 @@ +---------------- System Emulation -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +---------------- =20 This section of the manual is the overall guide for users using QEMU for full system emulation (as opposed to user-mode emulation). diff --git a/docs/tools/index.rst b/docs/tools/index.rst index ef6041a490..1edd5a8054 100644 --- a/docs/tools/index.rst +++ b/docs/tools/index.rst @@ -1,5 +1,6 @@ +----- Tools -=3D=3D=3D=3D=3D +----- =20 This section of the manual documents QEMU's "tools": its command line utilities and other standalone programs. diff --git a/docs/user/index.rst b/docs/user/index.rst index 9faa4badd7..2c4e29f3db 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -1,5 +1,6 @@ +------------------- User Mode Emulation -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +------------------- =20 This section of the manual is the overall guide for users using QEMU for user-mode emulation. In this mode, QEMU can launch --=20 2.31.1 From nobody Tue Apr 30 02:08:29 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1631030307256834.6873308000147; Tue, 7 Sep 2021 08:58:27 -0700 (PDT) Received: from localhost ([::1]:60210 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mNdUQ-00030t-1F for importer@patchew.org; Tue, 07 Sep 2021 11:58:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53462) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mNdSq-0000yQ-Ef for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:48 -0400 Received: from mail-ed1-x530.google.com ([2a00:1450:4864:20::530]:39510) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mNdSo-00067y-0g for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:48 -0400 Received: by mail-ed1-x530.google.com with SMTP id r7so14591319edd.6 for ; Tue, 07 Sep 2021 08:56:45 -0700 (PDT) Received: from avogadro.lan ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id h30sm6869669edz.40.2021.09.07.08.56.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Sep 2021 08:56:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=DycWxbP0FmToEbAs9ekzWaS53oHorD5ECMYmL+StYRQ=; b=G9qMhjPtL+fQF1LsRLyq3evFJuVecgElxo4miCXRIEEs3Lsa3Zc4vXfG+Df9iQfP/c VzMyr5XGA67c1FAixokQ+6lr75jKvY0VKQTURmDC0xNN1IkNHxyAlg2x6N7NghXtKAm2 Ll11iitJyWI4IGyrVzu4BR7KFvBfcrst7SlOpKGUmNGcGj+VxP74Nt1znn68LzZpbjNV PTUI7tbA22jqPncVI/2RqGP36AXnjoNdzKZZqzOWPdZU4S4v23k1DEHSqlUTbp5xAh/d hQDMOAZdLRLL0Oq4/uV5+y5LSa6cgVVU/L6h6NErDI71a1eGW5xSu09Khy3zSWBAyIZ4 ipRg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=DycWxbP0FmToEbAs9ekzWaS53oHorD5ECMYmL+StYRQ=; b=ounsylSrxFD89K5pxhjnlOdnNRxiV3tbBzGpgXP+lsY/b9gbX+UKhy9PCJnDEUs7nQ dWJvblLK7VP2qZ/6rjazSB0I5yk/jBXkUU7iRC0PoQ4GsXLdxpgV/A9l/N7NNEHUggC3 oH7QCM0G//t24wMID1VAIRgUnRg7jhcbeNSruNKb5hZMhAHCda8/l57dVaWKMXra25YO o0/byB6rwhjDO2Rqj3nfwqmEhmH3CZ/ZVxFncRdN8LNOSBJaThbuvITZGi60WXGSPdJs ylkAF43USOnawUUbLdVGtQonR9VKolVbay04KbsapakWYq6YxtBdO9DcouilVKwb8mdc zM3g== X-Gm-Message-State: AOAM531JfNMrc8OLnz/4leiTIZn6Kq6caKp69Bi2/OUlwzk1diUDKduY svBziQVLa2NBYD3qADrNVV92tQ62ngY= X-Google-Smtp-Source: ABdhPJxVSkmBQDImXqSn1nxPp0md9IEQJI31R+aBO2nglqhjd9Y4PDdaCkjL09DXQReERQ8lsyFVag== X-Received: by 2002:aa7:dc19:: with SMTP id b25mr148939edu.23.1631030204685; Tue, 07 Sep 2021 08:56:44 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 3/5] docs/system: standardize docs/system man page sections to --- with overline Date: Tue, 7 Sep 2021 17:56:39 +0200 Message-Id: <20210907155641.197844-4-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210907155641.197844-1-pbonzini@redhat.com> References: <20210907155641.197844-1-pbonzini@redhat.com> 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::530; envelope-from=paolo.bonzini@gmail.com; helo=mail-ed1-x530.google.com X-Spam_score_int: -14 X-Spam_score: -1.5 X-Spam_bar: - X-Spam_report: (-1.5 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1631030308881100001 Content-Type: text/plain; charset="utf-8" Man pages in docs/system use file inclusion heavily. Use headings with overlines in the main files, so that the same included file work well from both manuals and man pages. This style of heading is a bit more heavy-weight, so it is not used by the other man pages in interop/ and tools/. If in the future they are changed to use include files, for example to avoid having sections named "synopsis" or "description", they can switch to --- with overline as well. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/system/qemu-block-drivers.rst | 3 +++ docs/system/qemu-cpu-models.rst | 9 ++++++--- docs/system/qemu-manpage.rst | 5 +++++ 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-dr= ivers.rst index eb276481d6..c2c0114cec 100644 --- a/docs/system/qemu-block-drivers.rst +++ b/docs/system/qemu-block-drivers.rst @@ -4,16 +4,19 @@ QEMU block drivers reference =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 +-------- Synopsis -------- =20 QEMU block driver reference manual =20 +----------- Description ----------- =20 .. include:: qemu-block-drivers.rst.inc =20 +-------- See also -------- =20 diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.= rst index 8c51e2bf49..5cf6e46f8a 100644 --- a/docs/system/qemu-cpu-models.rst +++ b/docs/system/qemu-cpu-models.rst @@ -4,18 +4,21 @@ QEMU / KVM CPU model configuration =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +-------- Synopsis -'''''''' +-------- =20 QEMU CPU Modelling Infrastructure manual =20 +----------- Description -''''''''''' +----------- =20 .. include:: cpu-models-x86.rst.inc .. include:: cpu-models-mips.rst.inc =20 +-------- See also -'''''''' +-------- =20 The HTML documentation of QEMU for more precise information and Linux user= mode emulator invocation. diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst index d6f44e265b..c47a412758 100644 --- a/docs/system/qemu-manpage.rst +++ b/docs/system/qemu-manpage.rst @@ -10,6 +10,7 @@ QEMU User Documentation =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +-------- Synopsis -------- =20 @@ -17,11 +18,13 @@ Synopsis =20 |qemu_system| [options] [disk_image] =20 +----------- Description ----------- =20 .. include:: target-i386-desc.rst.inc =20 +------- Options ------- =20 @@ -34,11 +37,13 @@ not need a disk image. =20 .. include:: mux-chardev.rst.inc =20 +----- Notes ----- =20 .. include:: device-url-syntax.rst.inc =20 +-------- See also -------- =20 --=20 2.31.1 From nobody Tue Apr 30 02:08:29 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1631030535323626.9970038015975; Tue, 7 Sep 2021 09:02:15 -0700 (PDT) Received: from localhost ([::1]:40384 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mNdY5-0000Do-GG for importer@patchew.org; Tue, 07 Sep 2021 12:02:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53454) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mNdSq-0000xw-3N for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:48 -0400 Received: from mail-ej1-x62c.google.com ([2a00:1450:4864:20::62c]:43695) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mNdSo-00068Z-N2 for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:47 -0400 Received: by mail-ej1-x62c.google.com with SMTP id ia27so20605653ejc.10 for ; Tue, 07 Sep 2021 08:56:46 -0700 (PDT) Received: from avogadro.lan ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id h30sm6869669edz.40.2021.09.07.08.56.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Sep 2021 08:56:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=KrsK8fIxtvUv82ltZLe5fPcFNik8wrG7XHWp+ymcIIU=; b=WgL38ZpMacZWjjBDAQwDqz96H/VL1iCnF7X/JxbSwEKfNRzuNj8SNWfv/GzIhMsDzC hdpu+8cCjWbFGvZVgG2guoxz3JXBIXkIAanrxvktYoGtBCEy18YxqvQrl4ea5RF+NIQP 0NtEJUTN8zwb1ohgkkMZaCxtRWdHf9WZaY4YeCpTOhoUcPzdw5CI6oEV3nbpYuvOD58m 4CxNwLU/oNzNE0UjxqCn1618nv/z9gIzvyPNmc3+HQX+ffO7v/4fHUmPgY/98gRd8odP Ejbnzyi6kAeqowcUFQhr/JsdBlXvTuc0Vwdg1mT8Kz0picugrhHPw6sJktwDwpzOMDKf av4w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=KrsK8fIxtvUv82ltZLe5fPcFNik8wrG7XHWp+ymcIIU=; b=E2SEkpaUUZeY1/LBhE9fbO/efzk4GWjFjD7LQGFr5khMAMEmmpF9/5w/H4FPc1pDSL dgACRNgRPyCuUrHrEi1Z2pnsjtIJAdPfX6xzo+7lmQrnjQAOmFuLB1sEVn+YouCuYIRs 0bDHEVruBIk0DXIyE7eNfPKf1kPVobElwU1uCdVplEQVVdPl/tKOzEyOZridSkZzbUQL kldEe1VJ4K1jYoTcJGPnK3gjnrtT4/0r/HmO12P9MlzFwr/w2YBR6TD7VjoKn5q3HF25 mGwPf9iieM09eDFRmh4pUlYDAFV5EE05rnAi5wwSFDYkN/GkIIYeKUhAtFi+83ibB/zj YgAw== X-Gm-Message-State: AOAM532P5rrXuRgHLhNjvARyngJzHrKjeM5bmikZnT0OkLjX8G2MqTJk +iSx/eKC/ZVAx31CxFF9eCSE7AZW0+o= X-Google-Smtp-Source: ABdhPJxbmkrNOD+DdIXta1AeQapVF5zIKqty/ewY4KKf0DggoEo9avqv7fLlPtocUGT3hHtu9Ifmsw== X-Received: by 2002:a17:906:ae0c:: with SMTP id le12mr19299924ejb.169.1631030205345; Tue, 07 Sep 2021 08:56:45 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 4/5] docs/system: move x86 CPU configuration to a separate document Date: Tue, 7 Sep 2021 17:56:40 +0200 Message-Id: <20210907155641.197844-5-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210907155641.197844-1-pbonzini@redhat.com> References: <20210907155641.197844-1-pbonzini@redhat.com> 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::62c; envelope-from=paolo.bonzini@gmail.com; helo=mail-ej1-x62c.google.com X-Spam_score_int: 4 X-Spam_score: 0.4 X-Spam_bar: / X-Spam_report: (0.4 / 5.0 requ) DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1631030536945100001 Content-Type: text/plain; charset="utf-8" Currently, cpu-models-x86.rst.inc is included in target-i386.rst directly. To make the toctree more homogeneous when adding more documentation, include it through a first-class .rst file. Together with the previous changes to the man page skeletons, this also frees "=3D=3D=3D" for the headings, so that cpu-models-x86.rst.inc need not assume anything about the headings used by target-i386.rst. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/system/cpu-models-x86.rst.inc | 4 ++-- docs/system/i386/cpu.rst | 1 + docs/system/target-i386.rst | 8 +++++++- 3 files changed, 10 insertions(+), 3 deletions(-) create mode 100644 docs/system/i386/cpu.rst diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x8= 6.rst.inc index 9119f5dff5..6e8be7d79b 100644 --- a/docs/system/cpu-models-x86.rst.inc +++ b/docs/system/cpu-models-x86.rst.inc @@ -1,5 +1,5 @@ Recommendations for KVM CPU model configuration on x86 hosts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The information that follows provides recommendations for configuring CPU models on x86 hosts. The goals are to maximise performance, while @@ -368,7 +368,7 @@ featureset, which prevents guests having optimal perfor= mance. =20 =20 Syntax for configuring CPU models -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The examples below illustrate the approach to configuring the various CPU models / features in QEMU and libvirt. diff --git a/docs/system/i386/cpu.rst b/docs/system/i386/cpu.rst new file mode 100644 index 0000000000..738719da9a --- /dev/null +++ b/docs/system/i386/cpu.rst @@ -0,0 +1 @@ +.. include:: ../cpu-models-x86.rst.inc diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst index 22ba5ce2c0..c9720a8cd1 100644 --- a/docs/system/target-i386.rst +++ b/docs/system/target-i386.rst @@ -19,7 +19,13 @@ Board-specific documentation i386/microvm i386/pc =20 -.. include:: cpu-models-x86.rst.inc +Architectural features +~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + i386/cpu =20 .. _pcsys_005freq: =20 --=20 2.31.1 From nobody Tue Apr 30 02:08:29 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1631030666809253.43156550417007; Tue, 7 Sep 2021 09:04:26 -0700 (PDT) Received: from localhost ([::1]:47220 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mNdaC-0004l8-Gv for importer@patchew.org; Tue, 07 Sep 2021 12:04:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53478) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mNdSr-00010W-Hi for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:49 -0400 Received: from mail-ed1-x532.google.com ([2a00:1450:4864:20::532]:43854) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mNdSp-00069F-BU for qemu-devel@nongnu.org; Tue, 07 Sep 2021 11:56:49 -0400 Received: by mail-ed1-x532.google.com with SMTP id dm15so14591837edb.10 for ; Tue, 07 Sep 2021 08:56:46 -0700 (PDT) Received: from avogadro.lan ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id h30sm6869669edz.40.2021.09.07.08.56.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Sep 2021 08:56:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=oCZOq5tuFTyI/MBkuScLf83bwgoXqfElaaOzEZnF48c=; b=ZhVHn+CpXxacS/r0P1rOSGvfG7XqlU6iTdX+bCjNIYtiVSM/b11MQQpAVDMSoulQfr YL/PEkxvBLKdc1LYNrBfRHMHWjrm5A9BiueD2TL+ytA6AzEAdLpZHiAjlW5wy7myzG28 /RSMN5t65UKWmivfXDwoo475pG4WidRRwcRIE1hodmQTIzdvNMd1HFlk/stlkwgkww0n mI8e+Y7zUHaTVKIGIWVuLqm/JxVw2vMUKl5NiPqsKnf61ua8ADRVmruiRc3NAnYdOtdl CYYQDWUs3p2UonYvI1i2VZCYAMH74y5/wo28tr6IFHXMcS0FYiujTxr4Db97Krxd/EQ8 6hVg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=oCZOq5tuFTyI/MBkuScLf83bwgoXqfElaaOzEZnF48c=; b=SvXCSa+n5hxiTZZE7YJmHoxYCb/1gmE8zP5/k0I2mW/3WLR651m8YKLSLBbbMMOOYP Q2rr0/pgQmYH8qLM9+coxKaTdcexcr6pnyAToyeBnT6kaQItkDW0040Uv6838ZLqTibh PIdPft+wAhAcEHc0fHU4v1eybf+PiN2zcfCkSJb7Idal0ysDOV90ibDwDWdtCmkjkX9u FeqUmwDjCDS3GUS5srOV1ZsqCuhWh83HZLIK0jihcFYwEI3NpjI4V1hAozOuaEWaGbCV QNgsETaiQC1ym1LkIfeusr+mS8qVy86KWB7X78Pc3axqKx/0xFNapPoFq4HIVeA6eFZK Ha7A== X-Gm-Message-State: AOAM531OPoq9zx7Bb7TTmEh/lsBXSszQ7ABd88t53kveR6rljLdXdi+3 R7G6UMMqUKhb/U3Ze/osWj/+q0pZ+Fg= X-Google-Smtp-Source: ABdhPJxB0+UQj4cTJcbnh6J4wkm40/wQHEFa3rbyzDMZAotu0RXtKb9d9YdyHSoXXRnJi8mocB5b3A== X-Received: by 2002:a05:6402:4cd:: with SMTP id n13mr127618edw.215.1631030205963; Tue, 07 Sep 2021 08:56:45 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 5/5] docs/system: move SGX documentation within the system docs Date: Tue, 7 Sep 2021 17:56:41 +0200 Message-Id: <20210907155641.197844-6-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210907155641.197844-1-pbonzini@redhat.com> References: <20210907155641.197844-1-pbonzini@redhat.com> 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::532; envelope-from=paolo.bonzini@gmail.com; helo=mail-ed1-x532.google.com X-Spam_score_int: -14 X-Spam_score: -1.5 X-Spam_bar: - X-Spam_report: (-1.5 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1631030668217100001 Content-Type: text/plain; charset="utf-8" Convert to reStructuredText, and adopt the standard =3D=3D=3D --- ~~~ headi= ngs suggested for example by Linux. Signed-off-by: Paolo Bonzini --- docs/{intel-sgx.txt =3D> system/i386/sgx.rst} | 70 ++++++++++----------- docs/system/target-i386.rst | 1 + 2 files changed, 35 insertions(+), 36 deletions(-) rename docs/{intel-sgx.txt =3D> system/i386/sgx.rst} (83%) diff --git a/docs/intel-sgx.txt b/docs/system/i386/sgx.rst similarity index 83% rename from docs/intel-sgx.txt rename to docs/system/i386/sgx.rst index f934d92f37..f103ae2a2f 100644 --- a/docs/intel-sgx.txt +++ b/docs/system/i386/sgx.rst @@ -1,9 +1,8 @@ -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D Software Guard eXtensions (SGX) =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =20 Overview -=3D=3D=3D=3D=3D=3D=3D=3D +-------- =20 Intel Software Guard eXtensions (SGX) is a set of instructions and mechani= sms for memory accesses in order to provide security accesses for sensitive @@ -14,7 +13,7 @@ enclave memory area from any software not resident in the= enclave are prevented, including those from privileged software. =20 Virtual SGX -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +----------- =20 SGX feature is exposed to guest via SGX CPUID. Looking at SGX CPUID, we can report the same CPUID info to guest as on host for most of SGX CPUID. With @@ -25,7 +24,7 @@ The guest's EPC base and size are determined by Qemu, and= KVM needs Qemu to notify such info to it before it can initialize SGX for guest. =20 Virtual EPC ------------ +~~~~~~~~~~~ =20 By default, Qemu does not assign EPC to a VM, i.e. fully enabling SGX in a= VM requires explicit allocation of EPC to the VM. Similar to other specialized @@ -42,7 +41,7 @@ that some kernels may not recognize all EPC sections, e.g= . the Linux SGX driver is hardwired to support only 8 EPC sections. =20 The following Qemu snippet creates two EPC sections, with 64M pre-allocated -to the VM and an additional 28M mapped but not allocated: +to the VM and an additional 28M mapped but not allocated:: =20 -object memory-backend-epc,id=3Dmem1,size=3D64M,prealloc=3Don \ -object memory-backend-epc,id=3Dmem2,size=3D28M \ @@ -61,7 +60,7 @@ To simplify the implementation, EPC is always located abo= ve 4g in the guest physical address space. =20 Migration ---------- +~~~~~~~~~ =20 Qemu/KVM doesn't prevent live migrating SGX VMs, although from hardware's perspective, SGX doesn't support live migration, since both EPC and the SGX @@ -74,7 +73,7 @@ and when enclave fails to unseal sensitive information fr= om outside, it can detect such error and sensitive information can be provisioned to it again. =20 CPUID ------ +~~~~~ =20 Due to its myriad dependencies, SGX is currently not listed as supported in any of Qemu's built-in CPU configuration. To expose SGX (and SGX Launch @@ -86,9 +85,9 @@ All SGX sub-features enumerated through CPUID, e.g. SGX2,= MISCSELECT, ATTRIBUTES, etc... can be restricted via CPUID flags. Be aware that enforc= ing restriction of MISCSELECT, ATTRIBUTES and XFRM requires intercepting ECREA= TE, i.e. may marginally reduce SGX performance in the guest. All SGX sub-featu= res -controlled via -cpu are prefixed with "sgx", e.g.: +controlled via -cpu are prefixed with "sgx", e.g.:: =20 -$ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx + $ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx sgx sgx-debug sgx-encls-c @@ -102,18 +101,16 @@ $ qemu-system-x86_64 -cpu help | xargs printf "%s\n" = | grep sgx sgx2 sgxlc =20 -The following Qemu snippet passes through the host CPU (and host physical -address width) but restricts access to the provision and EINIT token keys: +The following Qemu snippet passes through the host CPU but restricts acces= s to +the provision and EINIT token keys:: =20 - -cpu host,host-phys-bits,-sgx-provisionkey,-sgx-tokenkey - -Note: + -cpu host,-sgx-provisionkey,-sgx-tokenkey =20 SGX sub-features cannot be emulated, i.e. sub-features that are not present in hardware cannot be forced on via '-cpu'. =20 Virtualize SGX Launch Control ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 Qemu SGX support for Launch Control (LC) is passive, in the sense that it does not actively change the LC configuration. Qemu SGX provides the user @@ -127,41 +124,42 @@ for SGX guest by our design. If host is in locked mod= e, we can still allow creating VM with SGX. =20 Feature Control ---------------- +~~~~~~~~~~~~~~~ =20 Qemu SGX updates the `etc/msr_feature_control` fw_cfg entry to set the SGX (bit 18) and SGX LC (bit 17) flags based on their respective CPUID support, i.e. existing guest firmware will automatically set SGX and SGX LC accordi= ngly, assuming said firmware supports fw_cfg.msr_feature_control. =20 -Launch a guest -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Launching a guest +----------------- =20 -To launch a SGX guest -${QEMU} \ - -cpu host,+sgx-provisionkey \ - -object memory-backend-epc,id=3Dmem1,size=3D64M,prealloc=3Don \ - -object memory-backend-epc,id=3Dmem2,size=3D28M \ +To launch a SGX guest: + +.. parsed-literal:: + + |qemu_system_x86| \\ + -cpu host,+sgx-provisionkey \\ + -object memory-backend-epc,id=3Dmem1,size=3D64M,prealloc=3Don \\ + -object memory-backend-epc,id=3Dmem2,size=3D28M \\ -M sgx-epc.0.memdev=3Dmem1,sgx-epc.1.memdev=3Dmem2 =20 Utilizing SGX in the guest requires a kernel/OS with SGX support. +The support can be determined in guest by:: =20 -The support can be determined in guest by: -$ grep sgx /proc/cpuinfo + $ grep sgx /proc/cpuinfo =20 -Check the SGX epc info in the Guest: -$ dmesg | grep sgx -[ 1.242142] sgx: EPC section 0x180000000-0x181bfffff -[ 1.242319] sgx: EPC section 0x181c00000-0x1837fffff +and SGX epc info by:: + + $ dmesg | grep sgx + [ 1.242142] sgx: EPC section 0x180000000-0x181bfffff + [ 1.242319] sgx: EPC section 0x181c00000-0x1837fffff =20 References -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +---------- =20 -SGX Homepage: -https://software.intel.com/sgx +- `SGX Homepage `__ =20 -SGX SDK: -https://github.com/intel/linux-sgx.git +- `SGX SDK `__ =20 -SGX SPEC: -Intel SDM Volume 3 +- SGX specification: Intel SDM Volume 3 diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst index c9720a8cd1..6a86d63863 100644 --- a/docs/system/target-i386.rst +++ b/docs/system/target-i386.rst @@ -26,6 +26,7 @@ Architectural features :maxdepth: 1 =20 i386/cpu + i386/sgx =20 .. _pcsys_005freq: =20 --=20 2.31.1