From patchwork Wed Feb 26 11:30:25 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 183912 Delivered-To: patch@linaro.org Received: by 2002:ac9:7758:0:0:0:0:0 with SMTP id d24csp2968996ocu; Wed, 26 Feb 2020 03:39:50 -0800 (PST) X-Google-Smtp-Source: APXvYqwDCvhFf6M8L7zw/kzHnnGH5iIojwhx/Xn0TvLu6vKJaPY1xSM+GkioFrssyfKQ+zGjjZBY X-Received: by 2002:ac8:1851:: with SMTP id n17mr4709000qtk.305.1582717190459; Wed, 26 Feb 2020 03:39:50 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1582717190; cv=none; d=google.com; s=arc-20160816; b=dsQ8dMA5dNnw2+i3GNHROid5l2hQXTD6Va3t0Tt2niinMJJtzaKJ1gvJFjIm+ibzji DuwLboDPpYKt+Yl/NaDN1cvQRn6kuY0jmiLkVpUfJJcwRyIro3/vk+PeSus/iW6HQMIs GW3RGQ1gkHBISuO24++q+xeYED/wp/IroJYMi7DCjphrmdpgt04JgrleXmekC5v3zRUU kgNAItsAG2wJ33+wTvSUtNEQgqioIxrhAFoRrv2Nwprt4JPtO8hDV/huzzpzyhPkEhzA nNbNgrnXoZ90j6q1DdWvhuPNrcDzu8QpVCy/VxYibaJfAVJdP2ZWbi7hS/miKBqplJE7 r6fw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc: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=xRK8bFWoSZBwkrBOa3bJQtvJAa0FRzsjPWhzdUOTyc8=; b=HSy6jVT6OTCYt95CaxDnU9TP93Vp6rlJ+BLvBqtBCTQLhtuv4alX2QqUaNcYu3IDkb lUS2QyaDZefrGTGs1GTQsJ7eBW5E8DWx2LCpR/F2LIK2kdTGj2gwHNQv+xRdMRVgpbfK bU6GYPpViIH9hkJC3L6KkDRnEnsFmMbdJo31QEt0pY4KixsRAxllTzdw+5xCOuam/ftN AFsx7bNvUovdmUIV3wN+FFcaOmoWZusH8BmcEBzMcii1VBK/qP73nCvRS6MZ93dvqcji TShtqxLlbonXrjafCpgiLjhKstGWJJx3CXIiGPdItvcdjE8KuaVRipnaOBb/YJ2yUBWn 3ayg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@gmail.com header.s=20161025 header.b=E68GRuC+; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id o11si807998qko.273.2020.02.26.03.39.50 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 26 Feb 2020 03:39:50 -0800 (PST) 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=fail header.i=@gmail.com header.s=20161025 header.b=E68GRuC+; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:42840 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6v2b-0004uu-VL for patch@linaro.org; Wed, 26 Feb 2020 06:39:49 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:52785) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6utu-0000rv-T7 for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:52 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6utp-0006GP-CI for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:50 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:46248) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6utp-0006Bd-4s for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:45 -0500 Received: by mail-wr1-x444.google.com with SMTP id j7so2492959wrp.13 for ; Wed, 26 Feb 2020 03:30:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=xRK8bFWoSZBwkrBOa3bJQtvJAa0FRzsjPWhzdUOTyc8=; b=E68GRuC+SmiF+NHZz0SaJowVi2RNlZjKeMC+bI1roLoonDLvNz5171eG1NNZAr/iGy 5+LeUpy18gBRTWGK1BtGepvkx62Qu8qf92jWR6m/k2WKpVWxYAudUD/ZDq/QH62mCS3P iwuSlPj3KQKD2zpf7LGT3TATSV0psUC59V/sDihN27WGS3XQvgxjkj4OX5HEZIlrPcp0 IO8omzmptPv8k3aWq3lwSpCxkEnRzT/b2WU6/PsyglaLanErLODycF18khxM/59FDlOM zTCHVYHybNPaFgslcga8b10Xs2HthNuD+515wN1ZEiCAlyLWJ+avPUaP1xjj+/nHJyMV C7aQ== 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=xRK8bFWoSZBwkrBOa3bJQtvJAa0FRzsjPWhzdUOTyc8=; b=tkLVdfp+YqPX1f2PkcKMHW4stWgt8EPOzIOGC6p9JTmN5a4AzjWLeqfnq1JBq9/+Ir pTbKDqcgLPdBukdRvXzT/ZxUuZ+iXkBiLvjkDhe/L4epC4LQiAwGFblc6Up9ObFJ5mYM kNh1htPEY+29bbLcZgLUwTkGwAqYFqjSmu3v2eTmCWBh35R0wnaUGOQtkYk62fPwOjpv ancrol6MmF/8nGNP6mTmG3m4DyCRoG89FPG0BzS1ZUFbxDuXMyfIdhEDrOrDj75bOYqo 9Q9vWjVHr1jwByaR/svz4awwXu4zsDxTei6QmmSZv7YN2xW6MCn6AmA8B827j+FBKmjx 86Mw== X-Gm-Message-State: APjAAAXXa145v4U7h/m0YMvPD90IcfVG0a5mgxHKZjZumy0ABsQ/n87v xfkAB06TLBZ/tfrL68L3TnmafwuU X-Received: by 2002:a5d:4b03:: with SMTP id v3mr5341314wrq.178.1582716643671; Wed, 26 Feb 2020 03:30:43 -0800 (PST) Received: from donizetti.lan ([2001:b07:6468:f312:d0d9:ea10:9775:f33f]) by smtp.gmail.com with ESMTPSA id h128sm2628154wmh.33.2020.02.26.03.30.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 26 Feb 2020 03:30:43 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 09/18] qemu-doc: Remove the "CPU emulation" part of the "Implementation notes" Date: Wed, 26 Feb 2020 12:30:25 +0100 Message-Id: <20200226113034.6741-10-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.1 In-Reply-To: <20200226113034.6741-1-pbonzini@redhat.com> References: <20200226113034.6741-1-pbonzini@redhat.com> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 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+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell The "CPU emulation" part of the "Implementation notes" in qemu-tech.texi looks like it is documenting what features of various CPUs we do or don't emulate. However: * it covers only six of our 21 guest architectures * the last time anybody updated it for actual content was in 2011/2012 for Xtensa; the content for the other five architectures is even older, being from 2008 or before! What we have is out of date, misleading and incomplete. Just delete this part of the document rather than trying to convert it to rST. (It would be nice eventually to have documentation of the scope and limitations of our emulation; but we will want to separate out the generic "system emulation" information from the parts that are specific to linux-user anyway, as they will be in different manuals.) Signed-off-by: Peter Maydell Message-Id: <20200225154121.21116-3-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini --- qemu-tech.texi | 153 ------------------------------------------------- 1 file changed, 153 deletions(-) -- 2.21.1 diff --git a/qemu-tech.texi b/qemu-tech.texi index 0380de77b6..35da6a40af 100644 --- a/qemu-tech.texi +++ b/qemu-tech.texi @@ -2,162 +2,9 @@ @appendix Implementation notes @menu -* CPU emulation:: * Managed start up options:: @end menu -@node CPU emulation -@section CPU emulation - -@menu -* x86:: x86 and x86-64 emulation -* ARM:: ARM emulation -* MIPS:: MIPS emulation -* PPC:: PowerPC emulation -* SPARC:: Sparc32 and Sparc64 emulation -* Xtensa:: Xtensa emulation -@end menu - -@node x86 -@subsection x86 and x86-64 emulation - -QEMU x86 target features: - -@itemize - -@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation. -LDT/GDT and IDT are emulated. VM86 mode is also supported to run -DOSEMU. There is some support for MMX/3DNow!, SSE, SSE2, SSE3, SSSE3, -and SSE4 as well as x86-64 SVM. - -@item Support of host page sizes bigger than 4KB in user mode emulation. - -@item QEMU can emulate itself on x86. - -@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}. -It can be used to test other x86 virtual CPUs. - -@end itemize - -Current QEMU limitations: - -@itemize - -@item Limited x86-64 support. - -@item IPC syscalls are missing. - -@item The x86 segment limits and access rights are not tested at every -memory access (yet). Hopefully, very few OSes seem to rely on that for -normal use. - -@end itemize - -@node ARM -@subsection ARM emulation - -@itemize - -@item Full ARM 7 user emulation. - -@item NWFPE FPU support included in user Linux emulation. - -@item Can run most ARM Linux binaries. - -@end itemize - -@node MIPS -@subsection MIPS emulation - -@itemize - -@item The system emulation allows full MIPS32/MIPS64 Release 2 emulation, -including privileged instructions, FPU and MMU, in both little and big -endian modes. - -@item The Linux userland emulation can run many 32 bit MIPS Linux binaries. - -@end itemize - -Current QEMU limitations: - -@itemize - -@item Self-modifying code is not always handled correctly. - -@item 64 bit userland emulation is not implemented. - -@item The system emulation is not complete enough to run real firmware. - -@item The watchpoint debug facility is not implemented. - -@end itemize - -@node PPC -@subsection PowerPC emulation - -@itemize - -@item Full PowerPC 32 bit emulation, including privileged instructions, -FPU and MMU. - -@item Can run most PowerPC Linux binaries. - -@end itemize - -@node SPARC -@subsection Sparc32 and Sparc64 emulation - -@itemize - -@item Full SPARC V8 emulation, including privileged -instructions, FPU and MMU. SPARC V9 emulation includes most privileged -and VIS instructions, FPU and I/D MMU. Alignment is fully enforced. - -@item Can run most 32-bit SPARC Linux binaries, SPARC32PLUS Linux binaries and -some 64-bit SPARC Linux binaries. - -@end itemize - -Current QEMU limitations: - -@itemize - -@item IPC syscalls are missing. - -@item Floating point exception support is buggy. - -@item Atomic instructions are not correctly implemented. - -@item There are still some problems with Sparc64 emulators. - -@end itemize - -@node Xtensa -@subsection Xtensa emulation - -@itemize - -@item Core Xtensa ISA emulation, including most options: code density, -loop, extended L32R, 16- and 32-bit multiplication, 32-bit division, -MAC16, miscellaneous operations, boolean, FP coprocessor, coprocessor -context, debug, multiprocessor synchronization, -conditional store, exceptions, relocatable vectors, unaligned exception, -interrupts (including high priority and timer), hardware alignment, -region protection, region translation, MMU, windowed registers, thread -pointer, processor ID. - -@item Not implemented options: data/instruction cache (including cache -prefetch and locking), XLMI, processor interface. Also options not -covered by the core ISA (e.g. FLIX, wide branches) are not implemented. - -@item Can run most Xtensa Linux binaries. - -@item New core configuration that requires no additional instructions -may be created from overlay with minimal amount of hand-written code. - -@end itemize - @node Managed start up options @section Managed start up options From patchwork Wed Feb 26 11:30:31 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 183911 Delivered-To: patch@linaro.org Received: by 2002:ac9:7758:0:0:0:0:0 with SMTP id d24csp2968773ocu; Wed, 26 Feb 2020 03:39:37 -0800 (PST) X-Google-Smtp-Source: APXvYqy2xpEmp/osOHTZe3qbKTv9xj2L421yeEx6EY2YA/La78HgWzwS49tHw0Kcdj/RMbArMSw3 X-Received: by 2002:a37:dcc1:: with SMTP id v184mr4712844qki.487.1582717177561; Wed, 26 Feb 2020 03:39:37 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1582717177; cv=none; d=google.com; s=arc-20160816; b=ntbyj7LJPJfnmKC5zwRQLshgk4btY4Zb8KiXedFVQCZrRiHTvKUsr9kmbt8URqTHOg 48mEXcHWI1f/vRgti41E/AHLAIocourTwrjIFqqNAQiVJqzpoeT6k2KMZcQ3o/NTapsm hC+4T4Ky8agj/rRjONzdz9sbRWEnTvBlbhEmRaAdnRWDRNwvNSxEghy1+o9g5LPLPk60 zeKN/XQoI2BLhtCcfeki6Jp/rb5OgbWJXTjUVZNAVcE0xZk8QjthWVRs6BPsuN0SLrCk JhkpE4/qq/CWsmlc7b/BvhwRp2b5oFME+ksKKlDcK8NrtxEawKcjPPdkOg+EAL669Sxs Ll8g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc: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=jQCthPnR6y1TZUUgQIYVSn60kzDk9kwVXC4q84W9SeE=; b=rZfVNdtiD+uloEQlgJBxYwxGNcEMstzV+AUm+fKWARRAaBHvrinecZrjNVJVqWHzVi DgFTfPV2WDaNGVcxHY3oyNtA909JkPizIJyg8zvjC5Fdp2W/N1QW6uGCwLp8w3fZdI+b 0F3CAiCM65Bmfwe4EaGwSsz2wkzKetWZJIBqKKFNiDkZHttOKi57gUCYjyNEJ4nkfauK Fvo5JnCauT7sVQ6Ij/V0Dh4oN7bRcfH1r5yJRMzXM4LXmCk1WVOjoY/PqiIhvBycTwQo yt/8+3f8LJaqOFsJbtiTOXH4lJ30yr5T0aMRvWZHUwC8mO75b8SgMq/GVBV6PjiuhdhT 8a1Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@gmail.com header.s=20161025 header.b=MA9H0Evr; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id x2si772618qvo.91.2020.02.26.03.39.37 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 26 Feb 2020 03:39:37 -0800 (PST) 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=fail header.i=@gmail.com header.s=20161025 header.b=MA9H0Evr; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:42834 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6v2P-0004di-1t for patch@linaro.org; Wed, 26 Feb 2020 06:39:37 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:52841) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6utx-0000zM-VG for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:56 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6utw-0006pc-0d for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:53 -0500 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:46474) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6utv-0006l3-Nn for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:51 -0500 Received: by mail-wr1-x436.google.com with SMTP id j7so2493419wrp.13 for ; Wed, 26 Feb 2020 03:30:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=jQCthPnR6y1TZUUgQIYVSn60kzDk9kwVXC4q84W9SeE=; b=MA9H0Evrqm8eXA6q2MF1l0SI8lKcIQ+XmsMFqU4mdcW3eqqMEjufRX+SjgA3rlNmrP FdJeR2J9ZutmG0nsXuAyTJJJ6pbK24hV2oYpSk0zToM7OSURNsjRP4EHQ8qgHFHnV9Mf pLT77cngrGAhR5ewcNP65H2YcLRFnkbbci+5L5fJxFmeqc06c1GyOspk1myvoMN/3g0q /+veChHgJAx4JY4yYTErJ3mIkh/AQaZp0rr1WLcVOq+elxirh6VUiLdSXUL0bP5rX1zI ZFXU0dGCtAVpiAmTKLiNvUildpzJZZyuI3rY2ezgcTvxTL9kHdA4kdPR0zMrwMc/zz6v OkOA== 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=jQCthPnR6y1TZUUgQIYVSn60kzDk9kwVXC4q84W9SeE=; b=Ahp/0Davv6m7tceiRks/P4vyVtwiwPvx/QmmPS6Zv7iy3r0FZgAtStl30QDhd/jMRd ZZyHr9LTzE56hUXPnkbkQ0rYQqF0IDdhPaflN3hhKPzcWeOTtWOfLA+LICKdmH0anwO2 vI8KUiA3/UWGRvaI9MBZSPlGdIu2a/rZzaLhs8iNYlvNDVUzWZwBRhrZL7hgUTlYTqxM uECkQnM+llWQm3laAIaUeBP7co6CDoHj5U4e62WIx5fhedouJH3QsxWnNfRvk7rV+l7V S4fURNBB8hgJb/K/C7j+z3+iHDEq0XuiLOukLeZetV2gRFP1iBgscN8IuQy2FZmGVETb Jqhg== X-Gm-Message-State: APjAAAVVMMODHpiA2jjQxc122L6dLKuWgcJ3KSuKei0IOIphx19ur+G4 fGo+VAEPyG73KloRULfFTrLg10Lo X-Received: by 2002:a5d:66ca:: with SMTP id k10mr4916113wrw.194.1582716650217; Wed, 26 Feb 2020 03:30:50 -0800 (PST) Received: from donizetti.lan ([2001:b07:6468:f312:d0d9:ea10:9775:f33f]) by smtp.gmail.com with ESMTPSA id h128sm2628154wmh.33.2020.02.26.03.30.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 26 Feb 2020 03:30:49 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 15/18] docs/system: Convert security.texi to rST format Date: Wed, 26 Feb 2020 12:30:31 +0100 Message-Id: <20200226113034.6741-16-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.1 In-Reply-To: <20200226113034.6741-1-pbonzini@redhat.com> References: <20200226113034.6741-1-pbonzini@redhat.com> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::436 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+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell security.texi is included from qemu-doc.texi but is not used in the qemu.1 manpage. So we can do a straightforward conversion of the contents, which go into the system manual. Signed-off-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/system/index.rst | 1 + docs/system/security.rst | 173 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 docs/system/security.rst -- 2.21.1 diff --git a/docs/system/index.rst b/docs/system/index.rst index 21b5a18b67..d38addb2a0 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -13,3 +13,4 @@ Contents: .. toctree:: :maxdepth: 2 + security diff --git a/docs/system/security.rst b/docs/system/security.rst new file mode 100644 index 0000000000..f2092c8768 --- /dev/null +++ b/docs/system/security.rst @@ -0,0 +1,173 @@ +Security +======== + +Overview +-------- + +This chapter explains the security requirements that QEMU is designed to meet +and principles for securely deploying QEMU. + +Security Requirements +--------------------- + +QEMU supports many different use cases, some of which have stricter security +requirements than others. The community has agreed on the overall security +requirements that users may depend on. These requirements define what is +considered supported from a security perspective. + +Virtualization Use Case +''''''''''''''''''''''' + +The virtualization use case covers cloud and virtual private server (VPS) +hosting, as well as traditional data center and desktop virtualization. These +use cases rely on hardware virtualization extensions to execute guest code +safely on the physical CPU at close-to-native speed. + +The following entities are untrusted, meaning that they may be buggy or +malicious: + +- Guest +- User-facing interfaces (e.g. VNC, SPICE, WebSocket) +- Network protocols (e.g. NBD, live migration) +- User-supplied files (e.g. disk images, kernels, device trees) +- Passthrough devices (e.g. PCI, USB) + +Bugs affecting these entities are evaluated on whether they can cause damage in +real-world use cases and treated as security bugs if this is the case. + +Non-virtualization Use Case +''''''''''''''''''''''''''' + +The non-virtualization use case covers emulation using the Tiny Code Generator +(TCG). In principle the TCG and device emulation code used in conjunction with +the non-virtualization use case should meet the same security requirements as +the virtualization use case. However, for historical reasons much of the +non-virtualization use case code was not written with these security +requirements in mind. + +Bugs affecting the non-virtualization use case are not considered security +bugs at this time. Users with non-virtualization use cases must not rely on +QEMU to provide guest isolation or any security guarantees. + +Architecture +------------ + +This section describes the design principles that ensure the security +requirements are met. + +Guest Isolation +''''''''''''''' + +Guest isolation is the confinement of guest code to the virtual machine. When +guest code gains control of execution on the host this is called escaping the +virtual machine. Isolation also includes resource limits such as throttling of +CPU, memory, disk, or network. Guests must be unable to exceed their resource +limits. + +QEMU presents an attack surface to the guest in the form of emulated devices. +The guest must not be able to gain control of QEMU. Bugs in emulated devices +could allow malicious guests to gain code execution in QEMU. At this point the +guest has escaped the virtual machine and is able to act in the context of the +QEMU process on the host. + +Guests often interact with other guests and share resources with them. A +malicious guest must not gain control of other guests or access their data. +Disk image files and network traffic must be protected from other guests unless +explicitly shared between them by the user. + +Principle of Least Privilege +'''''''''''''''''''''''''''' + +The principle of least privilege states that each component only has access to +the privileges necessary for its function. In the case of QEMU this means that +each process only has access to resources belonging to the guest. + +The QEMU process should not have access to any resources that are inaccessible +to the guest. This way the guest does not gain anything by escaping into the +QEMU process since it already has access to those same resources from within +the guest. + +Following the principle of least privilege immediately fulfills guest isolation +requirements. For example, guest A only has access to its own disk image file +``a.img`` and not guest B's disk image file ``b.img``. + +In reality certain resources are inaccessible to the guest but must be +available to QEMU to perform its function. For example, host system calls are +necessary for QEMU but are not exposed to guests. A guest that escapes into +the QEMU process can then begin invoking host system calls. + +New features must be designed to follow the principle of least privilege. +Should this not be possible for technical reasons, the security risk must be +clearly documented so users are aware of the trade-off of enabling the feature. + +Isolation mechanisms +'''''''''''''''''''' + +Several isolation mechanisms are available to realize this architecture of +guest isolation and the principle of least privilege. With the exception of +Linux seccomp, these mechanisms are all deployed by management tools that +launch QEMU, such as libvirt. They are also platform-specific so they are only +described briefly for Linux here. + +The fundamental isolation mechanism is that QEMU processes must run as +unprivileged users. Sometimes it seems more convenient to launch QEMU as +root to give it access to host devices (e.g. ``/dev/net/tun``) but this poses a +huge security risk. File descriptor passing can be used to give an otherwise +unprivileged QEMU process access to host devices without running QEMU as root. +It is also possible to launch QEMU as a non-root user and configure UNIX groups +for access to ``/dev/kvm``, ``/dev/net/tun``, and other device nodes. +Some Linux distros already ship with UNIX groups for these devices by default. + +- SELinux and AppArmor make it possible to confine processes beyond the + traditional UNIX process and file permissions model. They restrict the QEMU + process from accessing processes and files on the host system that are not + needed by QEMU. + +- Resource limits and cgroup controllers provide throughput and utilization + limits on key resources such as CPU time, memory, and I/O bandwidth. + +- Linux namespaces can be used to make process, file system, and other system + resources unavailable to QEMU. A namespaced QEMU process is restricted to only + those resources that were granted to it. + +- Linux seccomp is available via the QEMU ``--sandbox`` option. It disables + system calls that are not needed by QEMU, thereby reducing the host kernel + attack surface. + +Sensitive configurations +------------------------ + +There are aspects of QEMU that can have security implications which users & +management applications must be aware of. + +Monitor console (QMP and HMP) +''''''''''''''''''''''''''''' + +The monitor console (whether used with QMP or HMP) provides an interface +to dynamically control many aspects of QEMU's runtime operation. Many of the +commands exposed will instruct QEMU to access content on the host file system +and/or trigger spawning of external processes. + +For example, the ``migrate`` command allows for the spawning of arbitrary +processes for the purpose of tunnelling the migration data stream. The +``blockdev-add`` command instructs QEMU to open arbitrary files, exposing +their content to the guest as a virtual disk. + +Unless QEMU is otherwise confined using technologies such as SELinux, AppArmor, +or Linux namespaces, the monitor console should be considered to have privileges +equivalent to those of the user account QEMU is running under. + +It is further important to consider the security of the character device backend +over which the monitor console is exposed. It needs to have protection against +malicious third parties which might try to make unauthorized connections, or +perform man-in-the-middle attacks. Many of the character device backends do not +satisfy this requirement and so must not be used for the monitor console. + +The general recommendation is that the monitor console should be exposed over +a UNIX domain socket backend to the local host only. Use of the TCP based +character device backend is inappropriate unless configured to use both TLS +encryption and authorization control policy on client connections. + +In summary, the monitor console is considered a privileged control interface to +QEMU and as such should only be made accessible to a trusted management +application or user. From patchwork Wed Feb 26 11:30:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 183910 Delivered-To: patch@linaro.org Received: by 2002:ac9:7758:0:0:0:0:0 with SMTP id d24csp2964576ocu; Wed, 26 Feb 2020 03:35:22 -0800 (PST) X-Google-Smtp-Source: APXvYqznOgepyFzTz5DW/0Sg5R46LP4vNU4bjf0wEMzOd2AzUxg/5LJZ0BWlM0nX7omwHNV9o4R/ X-Received: by 2002:a05:620a:141a:: with SMTP id d26mr5069643qkj.312.1582716922795; Wed, 26 Feb 2020 03:35:22 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1582716922; cv=none; d=google.com; s=arc-20160816; b=uQ0T8rEnjrmteUsM0tqxlHW4PPO4Z5aCI7d72QMV8aTsXy4DcBvaBTJUm+jTTUxtMK LLMKixBuyFieKuDkotSdiMGZiGiS/dFtBh3ydEnlBDxCVYUMb3wXBvRRqPGWMsB//sKP wARzKRo4Pio7i2jfYeU5odTyDg8UpDxYol0IuGxiJk1DweTUiwxgNikFOV0jKlIjKE4w qCMJ2uTTlFwn1+FcJOZjQEnZ+w5kVqcS0TT/5VZncMLQyW5MUEjnmUE/dZjWz8iDsz0R fF+dVZRWm0cSKvqylDwj0gbcmB9p+PiIhyjI74QEyd0oUl008qFMzvas3sk1e1ojPnHh jwtQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc: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=IOCp7//xuJ1gvtqmOaoBWn6mtaBnhkwhAqap6W0CKnQ=; b=Ty/WmKcetw2V96f1BmIwvPh+JkCDMHSu7epe5CA8XXOUXo+mWJlXiNkFvuFuouF2Z3 hLdR2Qc1UoB5QcPlJnsa5wY68ncR4fnz/IRQNKXVo8+xdhWGlcBLwWmsEAWrOsudtf1S I+KhqlGTgJke3i3RyC8xAc2NHLxWXreEQwK7Ph6RuchRZU716OP3sVYwcJYmxkHudG2F jsqNQSEA4fdjGk2Au/2cJNpSXgshlSHWVU0lsX/BDFQnrSEglQWZCkNLvlJ9UI9FkESD OrV+oVLMkGNqNaVhOK/KWlukEuq9psVIyMnjsv0/mpCjcSh16CB0YFRrWkYIl07QR4FO lHmQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@gmail.com header.s=20161025 header.b=IQwhrNJA; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id c10si964566qtn.192.2020.02.26.03.35.22 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 26 Feb 2020 03:35:22 -0800 (PST) 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=fail header.i=@gmail.com header.s=20161025 header.b=IQwhrNJA; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:42770 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6uyI-0007Qa-8q for patch@linaro.org; Wed, 26 Feb 2020 06:35:22 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:52851) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6uty-00010T-Bg for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:55 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6utx-0006v6-2s for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:54 -0500 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:42301) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6utw-0006qU-PY for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:52 -0500 Received: by mail-wr1-x441.google.com with SMTP id p18so2525129wre.9 for ; Wed, 26 Feb 2020 03:30:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=IOCp7//xuJ1gvtqmOaoBWn6mtaBnhkwhAqap6W0CKnQ=; b=IQwhrNJA9jW8yckfcw7zuVAMlRzmkUobteW8Gw7OeYAtg4gV+dI6P7awspIcAT7WWD K9T/KjOQ9/HtwH1Au+qFlJ1BM9BTjkGaeYMzGn/3Nd/Hb6FTk0cHCJjTP6KRqw8ZwluQ 2DmPoT7WGEUkhGzCdjFSjxE3yblPnyWfGBP74/nHfB8UCENVy32J8qqnQAzSKkXUxmYU eYjbAQUudXbey6/hjpMjQrbPS8pDlQtJsRpHb3I3Nx8Ncbxxz96g+M7QQi2MeIEZ2+6S PYGjzn8M2NPomHZej2dYCABy5ifXw+sAYGIFjazLYf2Rr5SWp5FvukWHpi70k59ZP0D2 4TcQ== 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=IOCp7//xuJ1gvtqmOaoBWn6mtaBnhkwhAqap6W0CKnQ=; b=qhhSBHriUB5MQtIwXz7VlD32Q5xfDSz7nhO0tf8pVWM/X3+HaKq2UYQKKxY8LFucBP btKgwUYVPhSvaYtkoDWJ2LwTRgaNunKTg6UF82mqG+Nt/EcI7PNP8LsLoD7V9u4YFvbv wP4DPiKDhzyGFr8Ym5SUpbqVcP1lYuNra8HLd3IX5B3h8Yby1QdaRjf7KMiTuPwKtYZK ekfHphbtkoTFcBxtJZkM+X1rFYjWyCIj887GiI02/9Z8YT3lYkOJHz84tRo1+JauWxmV LvxBJjx8CKJotdnf/8cYNbC/RjpjUytdgTR/x7f68C5zECFS4D8pLr6I6uxNaIfZQLD0 yC9A== X-Gm-Message-State: APjAAAXqkO7tGCCn5l5fmy4wSjsffIjlIlb+rhW5nD7xq/fpDtGrKj3j YOjWY72J+SW+nIpq3oyUBhC4V6N6 X-Received: by 2002:adf:de12:: with SMTP id b18mr2290618wrm.268.1582716651381; Wed, 26 Feb 2020 03:30:51 -0800 (PST) Received: from donizetti.lan ([2001:b07:6468:f312:d0d9:ea10:9775:f33f]) by smtp.gmail.com with ESMTPSA id h128sm2628154wmh.33.2020.02.26.03.30.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 26 Feb 2020 03:30:50 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 16/18] docs/system: convert managed startup to rST. Date: Wed, 26 Feb 2020 12:30:32 +0100 Message-Id: <20200226113034.6741-17-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.1 In-Reply-To: <20200226113034.6741-1-pbonzini@redhat.com> References: <20200226113034.6741-1-pbonzini@redhat.com> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::441 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+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Fix one typo in the process and format more option and command names as literal text, but make no significant changes to the content. Signed-off-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/system/index.rst | 1 + docs/system/managed-startup.rst | 35 +++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 docs/system/managed-startup.rst -- 2.21.1 diff --git a/docs/system/index.rst b/docs/system/index.rst index d38addb2a0..b2263b70d8 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -13,4 +13,5 @@ Contents: .. toctree:: :maxdepth: 2 + managed-startup security diff --git a/docs/system/managed-startup.rst b/docs/system/managed-startup.rst new file mode 100644 index 0000000000..9bcf98ea79 --- /dev/null +++ b/docs/system/managed-startup.rst @@ -0,0 +1,35 @@ +Managed start up options +======================== + +In system mode emulation, it's possible to create a VM in a paused +state using the ``-S`` command line option. In this state the machine +is completely initialized according to command line options and ready +to execute VM code but VCPU threads are not executing any code. The VM +state in this paused state depends on the way QEMU was started. It +could be in: + +- initial state (after reset/power on state) +- with direct kernel loading, the initial state could be amended to execute + code loaded by QEMU in the VM's RAM and with incoming migration +- with incoming migration, initial state will be amended with the migrated + machine state after migration completes + +This paused state is typically used by users to query machine state and/or +additionally configure the machine (by hotplugging devices) in runtime before +allowing VM code to run. + +However, at the ``-S`` pause point, it's impossible to configure options +that affect initial VM creation (like: ``-smp``/``-m``/``-numa`` ...) or +cold plug devices. The experimental ``--preconfig`` command line option +allows pausing QEMU before the initial VM creation, in a "preconfig" state, +where additional queries and configuration can be performed via QMP +before moving on to the resulting configuration startup. In the +preconfig state, QEMU only allows a limited set of commands over the +QMP monitor, where the commands do not depend on an initialized +machine, including but not limited to: + +- ``qmp_capabilities`` +- ``query-qmp-schema`` +- ``query-commands`` +- ``query-status`` +- ``x-exit-preconfig`` From patchwork Wed Feb 26 11:30:33 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 183913 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp3033001ile; Wed, 26 Feb 2020 03:41:56 -0800 (PST) X-Google-Smtp-Source: APXvYqxABAXwaoht0BZqeyDnI9+Jp6HyewuOTgjoSUYXLEkTkxkojE8RDdHfR4sFsQeHAHIOu1Kn X-Received: by 2002:a05:620a:8ca:: with SMTP id z10mr4237616qkz.242.1582717316486; Wed, 26 Feb 2020 03:41:56 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1582717316; cv=none; d=google.com; s=arc-20160816; b=Y0fhcEyqndReGwg+C8H8M6YJ6ldI5MvAbcHfA52Nbj0P7zM8iAlIRk2rVKT0uH4zvh LedDGjajKaPFbXiAuOroOZYARZJj/WyLHEehavI3jAfdorcYNRByDyY/hH8daD9Ffbmk 0zmm5lo+m7K3TSI/Tuwe+dgHHBYUW9uhTK2tCoX5NCqqlLFIJfJawzRy1xCxmTcDXvJJ +6e3pMqYgHOIEU833kzcpucp6EG5TUKoG8c2LYKewuGVZbvfGbVgNhYRK2jf4gmxHNL7 7LNFGIPUcb2NqjJcAUUTMhmXhecR7h26hAglFE943/QdcJHAOaEh7aXODcnZmMDtmGOO UQBQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc: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=DvH/hwbc52f9y/hSLLZgDpNon3UYB/InCyPExjWeA94=; b=RaLWpn/s9C9BwTAF9unhLxSxKPeu/O/uuIkWIMG8mBXcA1iAaCAQ6MEi+xYPUidIPT FUX0VIrhWv8Po8YebchfJKcuIuRvehnAlcAG4RaAz19k0E0u1hvOpd7NU3yh1cIQgj1V wvNsTtIFDytqr4d1164v5fa1Ix+Sez/lRp37FDMxMLDorgTzZ2+OyD6XL1gmkTgUwRE+ F8HVt9d+4rtGFQOnljDbqkjSKu5VPz0encq6nZp37+REm+qSgbbZH7gjfH5a47uHlxFu VzRpp/962FBY4PYG7VRjG8Jngp+reWRPRHWCy3vOv7cuZ5Q31/lP7eiGVXjbQs2qb1fg xorQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@gmail.com header.s=20161025 header.b=LT8gRpUm; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id j18si956495qtk.120.2020.02.26.03.41.56 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 26 Feb 2020 03:41:56 -0800 (PST) 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=fail header.i=@gmail.com header.s=20161025 header.b=LT8gRpUm; 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=fail (p=NONE sp=NONE dis=NONE) header.from=redhat.com Received: from localhost ([::1]:42876 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6v4d-0008W2-Vu for patch@linaro.org; Wed, 26 Feb 2020 06:41:56 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:52914) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6uu2-0001A6-JN for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:31:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6utz-00078m-8y for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:58 -0500 Received: from mail-wm1-x343.google.com ([2a00:1450:4864:20::343]:39362) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6uty-00072i-Tm for qemu-devel@nongnu.org; Wed, 26 Feb 2020 06:30:55 -0500 Received: by mail-wm1-x343.google.com with SMTP id c84so2638034wme.4 for ; Wed, 26 Feb 2020 03:30:54 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=DvH/hwbc52f9y/hSLLZgDpNon3UYB/InCyPExjWeA94=; b=LT8gRpUmRg88IVJWhhL1Ekvg69XTlOQkxT5ktE51ZIX7YO8jqsWEldrruQVmUw59rk zOUGY72ZNl4Cm8sRGhFec+6jP+GIH9H+74PlH9jC/eMoCsZDC2MiRNgPd4YTCGQ08YRw C9iV0NDhNN85R9SwOJZuGpDu/C2pdEF4uc27peJ2UNtIzAQxcSnYUWm5t4hSyuMQ+wru B1u/hkbVZvd1jGwXVGoBBvJI6r0ybT0Wr+AhGCuf43+7DS6exyH0qA46hzbh2s8vEVsY ALMLjMlZdCWa+okBIfFJyvHHScHFfKjOgDFIGog4qPUzWReROuVDr9hpct8wGoj5iY5o 3ycw== 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=DvH/hwbc52f9y/hSLLZgDpNon3UYB/InCyPExjWeA94=; b=S+S6O2FeTy9Ah+p8VfdKJEXY7lxOWXoN3KZNT3pNJ6ZSXB0TAdQ5ry07l8LQXxY4Lc /KzELSS/gaVWM0dij78BFI+P3AGaOGDy2udPFEI6u6j2cEskHBSQwcYASgeTBxIo/RMC 0e9t4d1ByKucA9L8HEHrWlJW8jhSobxV20eOKmiwJkpuKe61XZoqWofw5zG2KUtg7OdZ anPvYA69lWPo9mAnVVNnSAbeME70fzkGUVML0mB5sjFKEfi/eaFOn6xUQ0KUBVmN2QDy jKLwsyPQYrQNu7kmBelkTkv+pvM+K7Y6y6Hln0oOGX2Swc+4DGxrZFFfXWvfnwu1CvHV tUuw== X-Gm-Message-State: APjAAAXWlzn9ywsSFB6ACXnWEVYMU8NE2M3RF8NDsthZHAl3NmMCA6oR wCngWlExp/g0HESEYfoh5RfKznPN X-Received: by 2002:a7b:c957:: with SMTP id i23mr5225493wml.174.1582716652529; Wed, 26 Feb 2020 03:30:52 -0800 (PST) Received: from donizetti.lan ([2001:b07:6468:f312:d0d9:ea10:9775:f33f]) by smtp.gmail.com with ESMTPSA id h128sm2628154wmh.33.2020.02.26.03.30.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 26 Feb 2020 03:30:51 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 17/18] docs/system: convert the documentation of deprecated features to rST. Date: Wed, 26 Feb 2020 12:30:33 +0100 Message-Id: <20200226113034.6741-18-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.1 In-Reply-To: <20200226113034.6741-1-pbonzini@redhat.com> References: <20200226113034.6741-1-pbonzini@redhat.com> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::343 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+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We put the whole of this document into the system manual, though technically a few parts of it apply to qemu-img or qemu-nbd which are otherwise documented in tools/. We only make formatting fixes, except for one use of 'appendix' which we change to 'section' because this isn't an appendix in the Sphinx manual. Signed-off-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/system/deprecated.rst | 446 +++++++++++++++++++++++++++++++++++++ docs/system/index.rst | 1 + 2 files changed, 447 insertions(+) create mode 100644 docs/system/deprecated.rst -- 2.21.1 diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst new file mode 100644 index 0000000000..1eaa559079 --- /dev/null +++ b/docs/system/deprecated.rst @@ -0,0 +1,446 @@ +Deprecated features +=================== + +In general features are intended to be supported indefinitely once +introduced into QEMU. In the event that a feature needs to be removed, +it will be listed in this section. The feature will remain functional +for 2 releases prior to actual removal. Deprecated features may also +generate warnings on the console when QEMU starts up, or if activated +via a monitor command, however, this is not a mandatory requirement. + +Prior to the 2.10.0 release there was no official policy on how +long features would be deprecated prior to their removal, nor +any documented list of which features were deprecated. Thus +any features deprecated prior to 2.10.0 will be treated as if +they were first deprecated in the 2.10.0 release. + +What follows is a list of all features currently marked as +deprecated. + +System emulator command line arguments +-------------------------------------- + +``-machine enforce-config-section=on|off`` (since 3.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``enforce-config-section`` parameter is replaced by the +``-global migration.send-configuration={on|off}`` option. + +``-no-kvm`` (since 1.3.0) +''''''''''''''''''''''''' + +The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``. + +``-usbdevice`` (since 2.10.0) +''''''''''''''''''''''''''''' + +The ``-usbdevice DEV`` argument is now a synonym for setting +the ``-device usb-DEV`` argument instead. The deprecated syntax +would automatically enable USB support on the machine type. +If using the new syntax, USB support must be explicitly +enabled via the ``-machine usb=on`` argument. + +``-drive file=json:{...{'driver':'file'}}`` (since 3.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The 'file' driver for drives is no longer appropriate for character or host +devices and will only accept regular files (S_IFREG). The correct driver +for these file types is 'host_cdrom' or 'host_device' as appropriate. + +``-net ...,name=``\ *name* (since 3.1) +'''''''''''''''''''''''''''''''''''''' + +The ``name`` parameter of the ``-net`` option is a synonym +for the ``id`` parameter, which should now be used instead. + +``-smp`` (invalid topologies) (since 3.1) +''''''''''''''''''''''''''''''''''''''''' + +CPU topology properties should describe whole machine topology including +possible CPUs. + +However, historically it was possible to start QEMU with an incorrect topology +where *n* <= *sockets* * *cores* * *threads* < *maxcpus*, +which could lead to an incorrect topology enumeration by the guest. +Support for invalid topologies will be removed, the user must ensure +topologies described with -smp include all possible cpus, i.e. +*sockets* * *cores* * *threads* = *maxcpus*. + +``-vnc acl`` (since 4.0.0) +'''''''''''''''''''''''''' + +The ``acl`` option to the ``-vnc`` argument has been replaced +by the ``tls-authz`` and ``sasl-authz`` options. + +``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``-audiodev`` argument is now the preferred way to specify audio +backend settings instead of environment variables. To ease migration to +the new format, the ``-audiodev-help`` option can be used to convert +the current values of the environment variables to ``-audiodev`` options. + +Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +When not using the deprecated legacy audio config, each sound card +should specify an ``audiodev=`` property. Additionally, when using +vnc, you should specify an ``audiodev=`` propery if you plan to +transmit audio through the VNC protocol. + +``-mon ...,control=readline,pretty=on|off`` (since 4.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``pretty=on|off`` switch has no effect for HMP monitors, but is +silently ignored. Using the switch with HMP monitors will become an +error in the future. + +``-realtime`` (since 4.1) +''''''''''''''''''''''''' + +The ``-realtime mlock=on|off`` argument has been replaced by the +``-overcommit mem-lock=on|off`` argument. + +``-numa node,mem=``\ *size* (since 4.1) +''''''''''''''''''''''''''''''''''''''' + +The parameter ``mem`` of ``-numa node`` is used to assign a part of +guest RAM to a NUMA node. But when using it, it's impossible to manage specified +RAM chunk on the host side (like bind it to a host node, setting bind policy, ...), +so guest end-ups with the fake NUMA configuration with suboptiomal performance. +However since 2014 there is an alternative way to assign RAM to a NUMA node +using parameter ``memdev``, which does the same as ``mem`` and adds +means to actualy manage node RAM on the host side. Use parameter ``memdev`` +with *memory-backend-ram* backend as an replacement for parameter ``mem`` +to achieve the same fake NUMA effect or a properly configured +*memory-backend-file* backend to actually benefit from NUMA configuration. +In future new machine versions will not accept the option but it will still +work with old machine types. User can check QAPI schema to see if the legacy +option is supported by looking at MachineInfo::numa-mem-supported property. + +``-numa`` node (without memory specified) (since 4.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Splitting RAM by default between NUMA nodes has the same issues as ``mem`` +parameter described above with the difference that the role of the user plays +QEMU using implicit generic or board specific splitting rule. +Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if +it's supported by used machine type) to define mapping explictly instead. + +``-mem-path`` fallback to RAM (since 4.1) +''''''''''''''''''''''''''''''''''''''''' + +Currently if guest RAM allocation from file pointed by ``mem-path`` +fails, QEMU falls back to allocating from RAM, which might result +in unpredictable behavior since the backing file specified by the user +is ignored. In the future, users will be responsible for making sure +the backing storage specified with ``-mem-path`` can actually provide +the guest RAM configured with ``-m`` and QEMU will fail to start up if +RAM allocation is unsuccessful. + +RISC-V ``-bios`` (since 4.1) +'''''''''''''''''''''''''''' + +QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the +RISC-V virt machine and sifive_u machine. + +QEMU 4.1 has no changes to the default behaviour to avoid breakages. This +default will change in a future QEMU release, so please prepare now. All users +of the virt or sifive_u machine must change their command line usage. + +QEMU 4.1 has three options, please migrate to one of these three: + 1. ``-bios none`` - This is the current default behavior if no -bios option + is included. QEMU will not automatically load any firmware. It is up + to the user to load all the images they need. + 2. ``-bios default`` - In a future QEMU release this will become the default + behaviour if no -bios option is specified. This option will load the + default OpenSBI firmware automatically. The firmware is included with + the QEMU release and no user interaction is required. All a user needs + to do is specify the kernel they want to boot with the -kernel option + 3. ``-bios `` - Tells QEMU to load the specified file as the firmwrae. + +``-tb-size`` option (since 5.0) +''''''''''''''''''''''''''''''' + +QEMU 5.0 introduced an alternative syntax to specify the size of the translation +block cache, ``-accel tcg,tb-size=``. The new syntax deprecates the +previously available ``-tb-size`` option. + +``-show-cursor`` option (since 5.0) +''''''''''''''''''''''''''''''''''' + +Use ``-display sdl,show-cursor=on`` or + ``-display gtk,show-cursor=on`` instead. + +QEMU Machine Protocol (QMP) commands +------------------------------------ + +``change`` (since 2.5.0) +'''''''''''''''''''''''' + +Use ``blockdev-change-medium`` or ``change-vnc-password`` instead. + +``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``migrate-set-parameters`` instead. + +``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead. + +``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``status`` field of the ``BlockDirtyInfo`` structure, returned by +the query-block command is deprecated. Two new boolean fields, +``recording`` and ``busy`` effectively replace it. + +``query-block`` result field ``dirty-bitmaps`` (Since 4.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by +the query-block command is itself now deprecated. The ``dirty-bitmaps`` +field of the ``BlockDeviceInfo`` struct should be used instead, which is the +type of the ``inserted`` field in query-block replies, as well as the +type of array items in query-named-block-nodes. + +Since the ``dirty-bitmaps`` field is optionally present in both the old and +new locations, clients must use introspection to learn where to anticipate +the field if/when it does appear in command output. + +``query-cpus`` (since 2.12.0) +''''''''''''''''''''''''''''' + +The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command. + +``query-cpus-fast`` ``arch`` output member (since 3.0.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``arch`` output member of the ``query-cpus-fast`` command is +replaced by the ``target`` output member. + +``cpu-add`` (since 4.0) +''''''''''''''''''''''' + +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See +documentation of ``query-hotpluggable-cpus`` for additional +details. + +``query-events`` (since 4.0) +'''''''''''''''''''''''''''' + +The ``query-events`` command has been superseded by the more powerful +and accurate ``query-qmp-schema`` command. + +chardev client socket with ``wait`` option (since 4.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Character devices creating sockets in client mode should not specify +the 'wait' field, which is only applicable to sockets in server mode + +Human Monitor Protocol (HMP) commands +------------------------------------- + +The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (since 3.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and +'hostfwd_remove' HMP commands has been replaced by ``netdev_id``. + +``cpu-add`` (since 4.0) +''''''''''''''''''''''' + +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See +documentation of ``query-hotpluggable-cpus`` for additional details. + +``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and +``acl_remove`` commands are deprecated with no replacement. Authorization +for VNC should be performed using the pluggable QAuthZ objects. + +Guest Emulator ISAs +------------------- + +RISC-V ISA privledge specification version 1.09.1 (since 4.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The RISC-V ISA privledge specification version 1.09.1 has been deprecated. +QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these +should be used instead of the 1.09.1 version. + +System emulator CPUS +-------------------- + +RISC-V ISA CPUs (since 4.1) +''''''''''''''''''''''''''' + +The RISC-V cpus with the ISA version in the CPU name have been depcreated. The +four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and +``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec`` +option when using the ``rv32`` or ``rv64`` CPUs. + +RISC-V ISA CPUs (since 4.1) +''''''''''''''''''''''''''' + +The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and +``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified +via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs. + +System emulator devices +----------------------- + +``ide-drive`` (since 4.2) +''''''''''''''''''''''''' + +The 'ide-drive' device is deprecated. Users should use 'ide-hd' or +'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed. + +``scsi-disk`` (since 4.2) +''''''''''''''''''''''''' + +The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or +'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed. + +System emulator machines +------------------------ + +mips ``r4k`` platform (since 5.0) +''''''''''''''''''''''''''''''''' + +This machine type is very old and unmaintained. Users should use the ``malta`` +machine type instead. + +``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +These machine types are very old and likely can not be used for live migration +from old QEMU versions anymore. A newer machine type should be used instead. + +``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1) +'''''''''''''''''''''''''''''''''''''''''''''''' + +The version specific Spike machines have been deprecated in favour of the +generic ``spike`` machine. If you need to specify an older version of the RISC-V +spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument. + +Device options +-------------- + +Emulated device options +''''''''''''''''''''''' + +``-device virtio-blk,scsi=on|off`` (since 5.0.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 +and later do not support it because the virtio-scsi device was introduced for +full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. + +Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an +alias. + +Block device options +'''''''''''''''''''' + +``"backing": ""`` (since 2.12.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to prevent QEMU from automatically opening an image's backing +chain, use ``"backing": null`` instead. + +``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Options for ``rbd`` should be specified according to its runtime options, +like other block drivers. Legacy parsing of keyvalue pair encoded +filenames is useful to open images with the old format for backing files; +These image files should be updated to use the current format. + +Example of legacy encoding:: + + json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} + +The above, converted to the current supported format:: + + json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} + +Related binaries +---------------- + +``qemu-img convert -n -o`` (since 4.2.0) +'''''''''''''''''''''''''''''''''''''''' + +All options specified in ``-o`` are image creation options, so +they have no effect when used with ``-n`` to skip image creation. +Silently ignored options can be confusing, so this combination of +options will be made an error in future versions. + +Backwards compatibility +----------------------- + +Runnability guarantee of CPU models (since 4.1.0) +''''''''''''''''''''''''''''''''''''''''''''''''' + +Previous versions of QEMU never changed existing CPU models in +ways that introduced additional host software or hardware +requirements to the VM. This allowed management software to +safely change the machine type of an existing VM without +introducing new requirements ("runnability guarantee"). This +prevented CPU models from being updated to include CPU +vulnerability mitigations, leaving guests vulnerable in the +default configuration. + +The CPU model runnability guarantee won't apply anymore to +existing CPU models. Management software that needs runnability +guarantees must resolve the CPU model aliases using te +``alias-of`` field returned by the ``query-cpu-definitions`` QMP +command. + +While those guarantees are kept, the return value of +``query-cpu-definitions`` will have existing CPU model aliases +point to a version that doesn't break runnability guarantees +(specifically, version 1 of those CPU models). In future QEMU +versions, aliases will point to newer CPU model versions +depending on the machine type, so management software must +resolve CPU model aliases before starting a virtual machine. + + +Recently removed features +========================= + +What follows is a record of recently removed, formerly deprecated +features that serves as a record for users who have encountered +trouble after a recent upgrade. + +QEMU Machine Protocol (QMP) commands +------------------------------------ + +``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The "autoload" parameter has been ignored since 2.12.0. All bitmaps +are automatically loaded from qcow2 images. + +Related binaries +---------------- + +``qemu-nbd --partition`` (removed in 5.0.0) +''''''''''''''''''''''''''''''''''''''''''' + +The ``qemu-nbd --partition $digit`` code (also spelled ``-P``) +could only handle MBR partitions, and never correctly handled logical +partitions beyond partition 5. Exporting a partition can still be +done by utilizing the ``--image-opts`` option with a raw blockdev +using the ``offset`` and ``size`` parameters layered on top of +any other existing blockdev. For example, if partition 1 is 100MiB +long starting at 1MiB, the old command:: + + qemu-nbd -t -P 1 -f qcow2 file.qcow2 + +can be rewritten as:: + + qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2 diff --git a/docs/system/index.rst b/docs/system/index.rst index b2263b70d8..467cda3e72 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -15,3 +15,4 @@ Contents: :maxdepth: 2 managed-startup security + deprecated