From patchwork Thu Sep 30 13:32:44 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 1534842 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20210112 header.b=FP8m6tuN; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HKvkX70cFz9sRf for ; Thu, 30 Sep 2021 23:49:56 +1000 (AEST) Received: from localhost ([::1]:43554 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVwRe-0004PV-Pe for incoming@patchwork.ozlabs.org; Thu, 30 Sep 2021 09:49:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36436) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVwBO-00086O-1x for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:11 -0400 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:36844) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVwBL-0005DK-Fy for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:05 -0400 Received: by mail-wr1-x42f.google.com with SMTP id h15so8490526wrc.3 for ; Thu, 30 Sep 2021 06:33:01 -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=JqmlKLizONgEjnZPec0fBTavTsjsC4JPAMjk8DVQkD4=; b=FP8m6tuNWkZ2fZZvaBSI+T2m0Gj0i8oXKLmMKcaoVf+QgoW64zEhPw/yaKPBhdevAW eXjAg6pe5vb+N50B8YkoPjf5b+axgQjt/EY/I6wB9k1iN70tur6IgfRezu9sjE59tRF7 eEG9cDrFh0ywG/sjPHxNFG+l813TQjS5WyC9bw+4zgOCeSlp4JvbCMq4wm7C0e3oyL8u xyN7ohPcZ8VORij4CcHNm8k3miMLl1jth2KPev0au3ciYsI4EM4Z0Rh866ytzaiDCZ2n IFpZNtbGc5n8ZCR+NilNQVGuzLX+sEAH8idBWCbQTu6BxlMIotaJvDiG8hhGTkaeWlNb qL0g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=JqmlKLizONgEjnZPec0fBTavTsjsC4JPAMjk8DVQkD4=; b=FUA0376zSokDlvMd9PqaCuizVlqI1Os8/oKhaEIc5n7CQ+3Fl96Resp/2u3Rk65DSQ d0MtvmU31r9gU23vTyQ6BkN5pVluC3+kOQYqjIa1Q+CNek2BHHbHzksEP2bMHBc2gWg7 NNNQOzqzNbfBNqBl6GGm5Vq//M5jBUAUyMO5tSp1sye0EG7v44Is1s232OZd+qLyUEJs ifK/WwmrL3FICkhIRhxhr8by0E9pxzSwSyt36RJNEh2L4vpYw/iAbSEw3JFsE+bBmxTH UN/cMzS8scRH2o5zIVXWhxoHHc/znG+yfF5JuL67vngLbXvzzGrZ3ZA+gm+8JP4hpsYB HmHg== X-Gm-Message-State: AOAM5300AD/ktaok+oQGGv/N1NXl1P6UpNtJGtjDk39B9BSQxthVH3MR j1HCkaN+70xPj5kBR8FXHy0vZlCDgps= X-Google-Smtp-Source: ABdhPJy2l5nbFCFJtTPW+Tm1m38HvuHtlYm5MZkhmhb4SrLi4l6MJlvIr117KNxSX5qyChudX5pKkg== X-Received: by 2002:a5d:6292:: with SMTP id k18mr6276234wru.110.1633008779878; Thu, 30 Sep 2021 06:32:59 -0700 (PDT) Received: from localhost.localdomain ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id c4sm3037168wrt.23.2021.09.30.06.32.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 06:32:59 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 1/7] docs: name included files ".rst.inc" Date: Thu, 30 Sep 2021 15:32:44 +0200 Message-Id: <20210930133250.181156-2-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210930133250.181156-1-pbonzini@redhat.com> References: <20210930133250.181156-1-pbonzini@redhat.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42f; envelope-from=paolo.bonzini@gmail.com; helo=mail-wr1-x42f.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.249, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Signed-off-by: Paolo Bonzini --- docs/devel/{ci-definitions.rst => ci-definitions.rst.inc} | 0 docs/devel/{ci-jobs.rst => ci-jobs.rst.inc} | 0 docs/devel/{ci-runners.rst => ci-runners.rst.inc} | 0 docs/devel/ci.rst | 6 +++--- 4 files changed, 3 insertions(+), 3 deletions(-) rename docs/devel/{ci-definitions.rst => ci-definitions.rst.inc} (100%) rename docs/devel/{ci-jobs.rst => ci-jobs.rst.inc} (100%) rename docs/devel/{ci-runners.rst => ci-runners.rst.inc} (100%) diff --git a/docs/devel/ci-definitions.rst b/docs/devel/ci-definitions.rst.inc similarity index 100% rename from docs/devel/ci-definitions.rst rename to docs/devel/ci-definitions.rst.inc diff --git a/docs/devel/ci-jobs.rst b/docs/devel/ci-jobs.rst.inc similarity index 100% rename from docs/devel/ci-jobs.rst rename to docs/devel/ci-jobs.rst.inc diff --git a/docs/devel/ci-runners.rst b/docs/devel/ci-runners.rst.inc similarity index 100% rename from docs/devel/ci-runners.rst rename to docs/devel/ci-runners.rst.inc diff --git a/docs/devel/ci.rst b/docs/devel/ci.rst index 8d95247188..d106610096 100644 --- a/docs/devel/ci.rst +++ b/docs/devel/ci.rst @@ -8,6 +8,6 @@ found at:: https://wiki.qemu.org/Testing/CI -.. include:: ci-definitions.rst -.. include:: ci-jobs.rst -.. include:: ci-runners.rst +.. include:: ci-definitions.rst.inc +.. include:: ci-jobs.rst.inc +.. include:: ci-runners.rst.inc From patchwork Thu Sep 30 13:32:45 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 1534839 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20210112 header.b=TcgTnnA4; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HKvf15NgKz9sRf for ; Thu, 30 Sep 2021 23:46:01 +1000 (AEST) Received: from localhost ([::1]:35366 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVwNr-00076X-Fl for incoming@patchwork.ozlabs.org; Thu, 30 Sep 2021 09:45:59 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36420) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVwBM-00084Y-5c for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:04 -0400 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]:55260) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVwBJ-0005DR-Sr for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:03 -0400 Received: by mail-wm1-x32f.google.com with SMTP id s24so4691648wmh.4 for ; Thu, 30 Sep 2021 06:33:01 -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=ZldbnCdugQGK5VNaU/g/0ED4l/N93hoQAw50o2LtEUM=; b=TcgTnnA4pJecOJ/1BIZ5q4h7ySFF54iIpsvkDpol6iiDJaXFp9Mq4J9F33kaH4EANh qzwVWKJU0mGPHaem9N06Xk33VB8gPCiwsAAc62/vVYpm5JOWGifbRdNtsECIl8iIcv+X usnnFi6MT8WazKr0PTfAxoEzFx9g/SHcFG/Onb6smOxBHkclf7B/cKi2Tf+NcGLmhclu oQAnCihG2bKzZ4zPDlo/PuXcZWFawJQd1IlmoB8sKtUAfqa2ViBbJ+u5KkBUY2ifV25o LmTeBXf5ENFTNFHqJ73jJWu+sWfTSYnyAwGqVUqloUYTUdlEFz5ZSl/3FooHyITzPZC6 Dr+A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=ZldbnCdugQGK5VNaU/g/0ED4l/N93hoQAw50o2LtEUM=; b=e51WFCZ3h8zjGiDVcKN0rIj/iUDDWj5ix/QBMTlCgSGzHJT8L9TQa9zv6gPh4TpF7v HdtOR+dWAlj9FtI/zIKYluzD4ph24/mZFrXOxR3VPd2zFh0fvgEuPxbRQ3pFMghl1W89 BRFb935Jtiszqv1OitANTvOGE/KlWWmL4q7itfPemrLJbuw+G6zDB0VrHXCCLK3dXbhR z2OixBZKFzdsR3a55cQVwuNYKkh5+ROPU2pahT715m+l/sXW3WYNu+DLihS1wwMEF0x8 vVaqJevvL+XW4b6cUwULLhuLIakPh66i/RhKyN36HahdfWYbo/YIlqyE7vqGy6WRE0tT gbAg== X-Gm-Message-State: AOAM533hJZOQSJKsHxpqG/Kz4nXJkNvhM6SZ7qzUsCL1kBEpvO2OxXqF cF6cQmtiqbnym0PkRzZVogm23jkxVoo= X-Google-Smtp-Source: ABdhPJx39LKVnwzcnFRRJYbGdXfKS58ZyJXKgA5i3L7MF9yPFcCklrxg6ioOVesX3XGF9iqfMu+Pog== X-Received: by 2002:a7b:c048:: with SMTP id u8mr5289674wmc.113.1633008780458; Thu, 30 Sep 2021 06:33:00 -0700 (PDT) Received: from localhost.localdomain ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id c4sm3037168wrt.23.2021.09.30.06.32.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 06:33:00 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 2/7] docs: move notes inside the body of the document Date: Thu, 30 Sep 2021 15:32:45 +0200 Message-Id: <20210930133250.181156-3-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210930133250.181156-1-pbonzini@redhat.com> References: <20210930133250.181156-1-pbonzini@redhat.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32f; envelope-from=paolo.bonzini@gmail.com; helo=mail-wm1-x32f.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.249, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Make all documents start with a heading. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/devel/multi-process.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/devel/multi-process.rst b/docs/devel/multi-process.rst index 69699329d6..e5758a79ab 100644 --- a/docs/devel/multi-process.rst +++ b/docs/devel/multi-process.rst @@ -1,15 +1,17 @@ -This is the design document for multi-process QEMU. It does not -necessarily reflect the status of the current implementation, which -may lack features or be considerably different from what is described -in this document. This document is still useful as a description of -the goals and general direction of this feature. - -Please refer to the following wiki for latest details: -https://wiki.qemu.org/Features/MultiProcessQEMU - Multi-process QEMU =================== +.. note:: + + This is the design document for multi-process QEMU. It does not + necessarily reflect the status of the current implementation, which + may lack features or be considerably different from what is described + in this document. This document is still useful as a description of + the goals and general direction of this feature. + + Please refer to the following wiki for latest details: + https://wiki.qemu.org/Features/MultiProcessQEMU + QEMU is often used as the hypervisor for virtual machines running in the Oracle cloud. Since one of the advantages of cloud computing is the ability to run many VMs from different tenants in the same cloud From patchwork Thu Sep 30 13:32:46 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 1534841 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20210112 header.b=MuqEC7AD; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HKvjW71Bqz9sRf for ; Thu, 30 Sep 2021 23:49:02 +1000 (AEST) Received: from localhost ([::1]:42212 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVwQl-0003Tb-9D for incoming@patchwork.ozlabs.org; Thu, 30 Sep 2021 09:48:59 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36434) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVwBO-00086M-1t for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:11 -0400 Received: from mail-wm1-x336.google.com ([2a00:1450:4864:20::336]:53176) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVwBK-0005E3-BH for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:04 -0400 Received: by mail-wm1-x336.google.com with SMTP id b192so4698852wmb.2 for ; Thu, 30 Sep 2021 06:33:01 -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=BBHBXq8Ru5s+ypJN2TXJKrG3+TagSinMXkrtblxPDYw=; b=MuqEC7ADWIydIie9+zHF4BxmwZBBaFTDUNZckPxCGh0GlkefILwa/TSktcrlaAItNZ IwbfDmesFqWZ6lBhMqwsQMR5hBCsKlrnGCj0LQqatz8f2olNHlcvX3oK8V8AMJqRSHJF 6GZX1DB5kXzXUi1NNRcIOkTRfBw81aX3vb8nEWLKq/RjYhtA0rHlUYTOIdWU/oajOf6f 63tLRSsmFMchxHSlBcndf+LhQpc7IKKbyijgkYG1ftbKJKvL2OO4z65Cp/aRaU2GOQGR UoR/ljfjXrmhNenCG+CBPaXmaKZN3eZu7aVrEjQLZhkIazlaX1/17rndeGFudtqOACjL eLiw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=BBHBXq8Ru5s+ypJN2TXJKrG3+TagSinMXkrtblxPDYw=; b=r+rD30xYNDrgmkwIHcgx4qCEfqCFpxDMwDyFbDhoTDb2ActlJSr1Jiz6yr1WyjWIBG LthqLFKP0+9Ck0TzSF2cLNYgUqX1GopT2rOXcwgKvy95MkCkDJsY5tgjbdypNw/Plkuu B7W7LePgMh906LGwvaoTNdKRmggMm/uv+8QFZFo8E4YTna1mvN+VdhXybS2FJkgczeUd in/fAIDe4Ld0sv/Y5uTMXJciDfZQFpf80v4JOV6zcieQychKRpg9lycRF5G3AsFvFBwI GNSdbXPEGV9SQ8fhlytCU7S8OxOyU0R9nNBeC+9mb4wOQ4JppinpF43AylRj6Bpj3gvg 39cQ== X-Gm-Message-State: AOAM531FmVQjCVdEXdkl8iiWMULtXeU3UbQLmP13u4g28ZHeCirB20A/ crrhTHgZn8LlRaIUuMvxBEnYbc6hf2Q= X-Google-Smtp-Source: ABdhPJyZfSuEDy+wSUNhmIYQKlS55IPE/kQk6CBr+E+pHRsRghBdpa3s/7GxkkGn3Tu/GB1+GskUIw== X-Received: by 2002:a1c:1f0d:: with SMTP id f13mr5414527wmf.25.1633008781053; Thu, 30 Sep 2021 06:33:01 -0700 (PDT) Received: from localhost.localdomain ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id c4sm3037168wrt.23.2021.09.30.06.33.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 06:33:00 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 3/7] docs: put "make" information together in build-system.rst Date: Thu, 30 Sep 2021 15:32:46 +0200 Message-Id: <20210930133250.181156-4-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210930133250.181156-1-pbonzini@redhat.com> References: <20210930133250.181156-1-pbonzini@redhat.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::336; envelope-from=paolo.bonzini@gmail.com; helo=mail-wm1-x336.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.249, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/devel/build-system.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst index 3baec158f2..0f636d620e 100644 --- a/docs/devel/build-system.rst +++ b/docs/devel/build-system.rst @@ -380,6 +380,16 @@ phony target, while benchmarks are run with ``make bench``. Meson test suites such as ``unit`` can be ran with ``make check-unit`` too. It is also possible to run tests defined in meson.build with ``meson test``. +Useful make targets +------------------- + +``help`` + Print a help message for the most common build targets. + +``print-VAR`` + Print the value of the variable VAR. Useful for debugging the build + system. + Important files for the build system ==================================== @@ -473,14 +483,3 @@ Built by Makefile: meson.build. The rules are produced from Meson's JSON description of tests (obtained with "meson introspect --tests") through the script scripts/mtest2make.py. - - -Useful make targets -------------------- - -``help`` - Print a help message for the most common build targets. - -``print-VAR`` - Print the value of the variable VAR. Useful for debugging the build - system. From patchwork Thu Sep 30 13:32:47 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 1534845 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20210112 header.b=cQ1kXmCt; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HKvnr4gP6z9sRf for ; Thu, 30 Sep 2021 23:52:48 +1000 (AEST) Received: from localhost ([::1]:52024 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVwUQ-0001pJ-GC for incoming@patchwork.ozlabs.org; Thu, 30 Sep 2021 09:52:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36504) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVwBT-00086z-OY for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:13 -0400 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]:37628) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVwBN-0005GO-Rp for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:09 -0400 Received: by mail-wr1-x42e.google.com with SMTP id q2so227344wrc.4 for ; Thu, 30 Sep 2021 06:33:04 -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=U/L6oYH7LKQQ6EnSN+snPuNSEleo9MpfTkX3cojlfU4=; b=cQ1kXmCtAckj1CorKSXve3pQL1S/3kOLYpv/ta0Atq/cEohU0jM1/9u0glAIPQXbhr vkrxD/YyMu4qqON3wNnv/WHI1Gu3lGab2g58hV47zhjCLNyrtsnqL9lhFQ2AZhJWnRg3 NK8PqBlVn1XxR+qay8azct8CFvBCFXtS0a+JDnfeIuMuOJMf/jhsrXnp6S7fJJNGxsEc qzwihL+gTCE1XNv9+xSUIgrbcHo8/DuOJkszxukaKxWtVrlO6KwHxLTJRkm5qCBLhwOH Tkd6IJJ6mmAKG4SJi+1isSRDVnbW3sq49o0DL9+zWW5/vGe4m2V8ZVSv+7yZHORdDz8b xTvg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=U/L6oYH7LKQQ6EnSN+snPuNSEleo9MpfTkX3cojlfU4=; b=7IZdt6bAMX3oueGdr8/pI4pz54nuUm8ZOHJKohSTJO1SlfNgT8awsNvDcSmMho2Hgv tEu3Jke46yv2TakicnkIxY6Zl8vrpcLk2ghB9VVaTxUjXGcjBjqhNidqi5JaVYffEt7Q UydoRMcL277A9HmH+uvnwm1SNwmy8bJyg58zfFqwytXSYmP77hHcxzqb2mAMv6Wskvuv Q+GuOqbcoKH/qjLLepj8WO/FLiLWKKAYK+DqTFYu46EiLeEA1SSySsoMS5nkuUjHHDbh BO64kkw41Ve97A6W2K0xZ0C8a62X/GNWlRtqyqjODxRDhfe77fqYPNhs0cLXSMloRpjH vP5A== X-Gm-Message-State: AOAM533bSOikmWQOi4dmxoUgIeUzSTadBxrWDoh84PILGUA/Ft/sWtqF ccqqAeVMvnH+pIlgk/aLOXsXXlK2YP8= X-Google-Smtp-Source: ABdhPJxnyuDvPiAtLUWKmbjKD7XIj6Yg0GjJYQQV57P9pYz7MyGdpRo3gVxzI96X8PjHX+eSZilFwA== X-Received: by 2002:a5d:61c1:: with SMTP id q1mr6026148wrv.154.1633008781762; Thu, 30 Sep 2021 06:33:01 -0700 (PDT) Received: from localhost.localdomain ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id c4sm3037168wrt.23.2021.09.30.06.33.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 06:33:01 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 4/7] docs: reorganize qgraph.rst Date: Thu, 30 Sep 2021 15:32:47 +0200 Message-Id: <20210930133250.181156-5-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210930133250.181156-1-pbonzini@redhat.com> References: <20210930133250.181156-1-pbonzini@redhat.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42e; envelope-from=paolo.bonzini@gmail.com; helo=mail-wr1-x42e.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.249, 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, WEIRD_QUOTING=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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Clean up the heading levels to use === --- ~~~, and move the command line building near to the other execution steps. Signed-off-by: Paolo Bonzini --- docs/devel/qgraph.rst | 132 +++++++++++++++++++++--------------------- 1 file changed, 67 insertions(+), 65 deletions(-) diff --git a/docs/devel/qgraph.rst b/docs/devel/qgraph.rst index c2882c3a33..db44d71002 100644 --- a/docs/devel/qgraph.rst +++ b/docs/devel/qgraph.rst @@ -1,8 +1,7 @@ .. _qgraph: -======================================== Qtest Driver Framework -======================================== +====================== In order to test a specific driver, plain libqos tests need to take care of booting QEMU with the right machine and devices. @@ -31,13 +30,15 @@ so the sdhci-test should only care of linking its qgraph node with that interface. In this way, if the command line of a sdhci driver is changed, only the respective qgraph driver node has to be adjusted. +QGraph concepts +--------------- + The graph is composed by nodes that represent machines, drivers, tests and edges that define the relationships between them (``CONSUMES``, ``PRODUCES``, and ``CONTAINS``). - Nodes -^^^^^^ +~~~~~ A node can be of four types: @@ -64,7 +65,7 @@ Notes for the nodes: drivers name, otherwise they won't be discovered Edges -^^^^^^ +~~~~~ An edge relation between two nodes (drivers or machines) ``X`` and ``Y`` can be: @@ -73,7 +74,7 @@ An edge relation between two nodes (drivers or machines) ``X`` and ``Y`` can be: - ``X CONTAINS Y``: ``Y`` is part of ``X`` component Execution steps -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ The basic framework steps are the following: @@ -92,8 +93,64 @@ The basic framework steps are the following: Depending on the QEMU binary used, only some drivers/machines will be available and only test that are reached by them will be executed. +Command line +~~~~~~~~~~~~ + +Command line is built by using node names and optional arguments +passed by the user when building the edges. + +There are three types of command line arguments: + +- ``in node`` : created from the node name. For example, machines will + have ``-M `` to its command line, while devices + ``-device ``. It is automatically done by the framework. +- ``after node`` : added as additional argument to the node name. + This argument is added optionally when creating edges, + by setting the parameter ``after_cmd_line`` and + ``extra_edge_opts`` in ``QOSGraphEdgeOptions``. + The framework automatically adds + a comma before ``extra_edge_opts``, + because it is going to add attributes + after the destination node pointed by + the edge containing these options, and automatically + adds a space before ``after_cmd_line``, because it + adds an additional device, not an attribute. +- ``before node`` : added as additional argument to the node name. + This argument is added optionally when creating edges, + by setting the parameter ``before_cmd_line`` in + ``QOSGraphEdgeOptions``. This attribute + is going to add attributes before the destination node + pointed by the edge containing these options. It is + helpful to commands that are not node-representable, + such as ``-fdsev`` or ``-netdev``. + +While adding command line in edges is always used, not all nodes names are +used in every path walk: this is because the contained or produced ones +are already added by QEMU, so only nodes that "consumes" will be used to +build the command line. Also, nodes that will have ``{ "abstract" : true }`` +as QMP attribute will loose their command line, since they are not proper +devices to be added in QEMU. + +Example:: + + QOSGraphEdgeOptions opts = { + .before_cmd_line = "-drive id=drv0,if=none,file=null-co://," + "file.read-zeroes=on,format=raw", + .after_cmd_line = "-device scsi-hd,bus=vs0.0,drive=drv0", + + opts.extra_device_opts = "id=vs0"; + }; + + qos_node_create_driver("virtio-scsi-device", + virtio_scsi_device_create); + qos_node_consumes("virtio-scsi-device", "virtio-bus", &opts); + +Will produce the following command line: +``-drive id=drv0,if=none,file=null-co://, -device virtio-scsi-device,id=vs0 -device scsi-hd,bus=vs0.0,drive=drv0`` + Troubleshooting unavailable tests -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If there is no path from an available machine to a test then that test will be unavailable and won't execute. This can happen if a test or driver did not set up its qgraph node correctly. It can also happen if the necessary machine type @@ -151,7 +208,7 @@ Typically this is because the QEMU binary lacks support for the necessary machine type or device. Creating a new driver and its interface -""""""""""""""""""""""""""""""""""""""""" +--------------------------------------- Here we continue the ``sdhci`` use case, with the following scenario: @@ -489,7 +546,7 @@ or inverting the consumes edge in consumed_by:: arm/raspi2b --contains--> generic-sdhci Adding a new test -""""""""""""""""" +----------------- Given the above setup, adding a new test is very simple. ``sdhci-test``, taken from ``tests/qtest/sdhci-test.c``:: @@ -565,62 +622,7 @@ and for the binary ``QTEST_QEMU_BINARY=./qemu-system-arm``: Additional examples are also in ``test-qgraph.c`` -Command line: -"""""""""""""" - -Command line is built by using node names and optional arguments -passed by the user when building the edges. - -There are three types of command line arguments: - -- ``in node`` : created from the node name. For example, machines will - have ``-M `` to its command line, while devices - ``-device ``. It is automatically done by the framework. -- ``after node`` : added as additional argument to the node name. - This argument is added optionally when creating edges, - by setting the parameter ``after_cmd_line`` and - ``extra_edge_opts`` in ``QOSGraphEdgeOptions``. - The framework automatically adds - a comma before ``extra_edge_opts``, - because it is going to add attributes - after the destination node pointed by - the edge containing these options, and automatically - adds a space before ``after_cmd_line``, because it - adds an additional device, not an attribute. -- ``before node`` : added as additional argument to the node name. - This argument is added optionally when creating edges, - by setting the parameter ``before_cmd_line`` in - ``QOSGraphEdgeOptions``. This attribute - is going to add attributes before the destination node - pointed by the edge containing these options. It is - helpful to commands that are not node-representable, - such as ``-fdsev`` or ``-netdev``. - -While adding command line in edges is always used, not all nodes names are -used in every path walk: this is because the contained or produced ones -are already added by QEMU, so only nodes that "consumes" will be used to -build the command line. Also, nodes that will have ``{ "abstract" : true }`` -as QMP attribute will loose their command line, since they are not proper -devices to be added in QEMU. - -Example:: - - QOSGraphEdgeOptions opts = { - .before_cmd_line = "-drive id=drv0,if=none,file=null-co://," - "file.read-zeroes=on,format=raw", - .after_cmd_line = "-device scsi-hd,bus=vs0.0,drive=drv0", - - opts.extra_device_opts = "id=vs0"; - }; - - qos_node_create_driver("virtio-scsi-device", - virtio_scsi_device_create); - qos_node_consumes("virtio-scsi-device", "virtio-bus", &opts); - -Will produce the following command line: -``-drive id=drv0,if=none,file=null-co://, -device virtio-scsi-device,id=vs0 -device scsi-hd,bus=vs0.0,drive=drv0`` - Qgraph API reference -^^^^^^^^^^^^^^^^^^^^ +-------------------- .. kernel-doc:: tests/qtest/libqos/qgraph.h From patchwork Thu Sep 30 13:32:48 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 1534843 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20210112 header.b=o4U/lHwn; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HKvnJ6Ypxz9sRf for ; Thu, 30 Sep 2021 23:52:20 +1000 (AEST) Received: from localhost ([::1]:50302 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVwTy-0000gC-Bz for incoming@patchwork.ozlabs.org; Thu, 30 Sep 2021 09:52:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36506) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVwBT-000871-Oh for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:13 -0400 Received: from mail-wm1-x334.google.com ([2a00:1450:4864:20::334]:34373) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVwBN-0005Gn-Rr for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:09 -0400 Received: by mail-wm1-x334.google.com with SMTP id r11-20020a1c440b000000b0030cf0f01fbaso1759047wma.1 for ; Thu, 30 Sep 2021 06:33:05 -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=AAgn6t8BFR6iF2TZbkeoJibo9UfjeR26tU1KTpgZjKE=; b=o4U/lHwnq2koDr8AqXbQmwI+sBPniHwSLtrmj4SmxgLF60Bsc6BaIs2jqbSb5Df1lG gdcixVpblEIbbx8Dqz1ILPhl0ajfhr6zEiTxHElhRogFoHQIyK8hrDCGGr5auEj/onxZ vWoL9MjKtq2iQYAyenemmut2QkjycUvRK4wLazBXhHsL08mY27qGIic7l/B4Bp8dzA79 GSo291/ZKVdSODs2S42spYEzNx0Qw1Ci039/XsBnr7wFiw6PeeZ7+Y/yGl3fA93CJIZn JgVxt7d949cBNlDCLbI9nydjZvC3dfA1Wh3RG5Ctliu7HgEjyRQY/UAyL4gC6j+OW4wM ngsg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=AAgn6t8BFR6iF2TZbkeoJibo9UfjeR26tU1KTpgZjKE=; b=ocfzMDg8Feldp28Wn/U6k1qGxo6W4gj8FA76tuhWru/UKSA3S9pwzVRzhx6Zsp015p ShzHjYW3q1xjYS0RDo3nLP1q6DowmMM+DN/FfPZy/6P83weih6xGQVq0oBy8hnEMIVPU 0H9MvIJie14WQP0IczrD1FW1V4dr8ybIcAWzvVdkxRpPVjX4RQ7VKPx7spNs9zeq4N9g qHS2Aa7lInzWT3pQGAUcE7qXMfS7SjjHyPw6xolzHYfplFZw79Q1RJLnfsMzVcEbMi45 t8BjKx7aZDnuG8ojQPETmEFCU9MDPZCvVm5EK2OsOXmTML6+BPqVDL7HPqt4seDw3zlu Fk4g== X-Gm-Message-State: AOAM531UOUfmUtuHafC6SNMCUoxquZvya5n1BjrlqrmamGjUZqVOXhqC vhfeQavFq7Fg3cC/gWzq8ZSIOYadrwk= X-Google-Smtp-Source: ABdhPJxWsuWzq0pQrg7li2pgzoji0tQdKEmBPX0J60PA2A92pzuZ7KYwI1QoLExvuLJptyT9Por0zA== X-Received: by 2002:a1c:4e19:: with SMTP id g25mr5277003wmh.67.1633008784173; Thu, 30 Sep 2021 06:33:04 -0700 (PDT) Received: from localhost.localdomain ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id c4sm3037168wrt.23.2021.09.30.06.33.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 06:33:03 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 5/7] docs: reorganize tcg-plugins.rst Date: Thu, 30 Sep 2021 15:32:48 +0200 Message-Id: <20210930133250.181156-6-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210930133250.181156-1-pbonzini@redhat.com> References: <20210930133250.181156-1-pbonzini@redhat.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::334; envelope-from=paolo.bonzini@gmail.com; helo=mail-wm1-x334.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.249, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Clean up the heading levels to use === --- ~~~, and create a new "writing plugins" section. Signed-off-by: Paolo Bonzini --- docs/devel/tcg-plugins.rst | 117 ++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 59 deletions(-) diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index dac5101a3c..842ae01a4c 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -3,7 +3,6 @@ Copyright (c) 2019, Linaro Limited Written by Emilio Cota and Alex Bennée -================ QEMU TCG Plugins ================ @@ -16,60 +15,8 @@ only monitor it passively. However they can do this down to an individual instruction granularity including potentially subscribing to all load and store operations. -API Stability -============= - -This is a new feature for QEMU and it does allow people to develop -out-of-tree plugins that can be dynamically linked into a running QEMU -process. However the project reserves the right to change or break the -API should it need to do so. The best way to avoid this is to submit -your plugin upstream so they can be updated if/when the API changes. - -API versioning --------------- - -All plugins need to declare a symbol which exports the plugin API -version they were built against. This can be done simply by:: - - QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION; - -The core code will refuse to load a plugin that doesn't export a -``qemu_plugin_version`` symbol or if plugin version is outside of QEMU's -supported range of API versions. - -Additionally the ``qemu_info_t`` structure which is passed to the -``qemu_plugin_install`` method of a plugin will detail the minimum and -current API versions supported by QEMU. The API version will be -incremented if new APIs are added. The minimum API version will be -incremented if existing APIs are changed or removed. - -Exposure of QEMU internals --------------------------- - -The plugin architecture actively avoids leaking implementation details -about how QEMU's translation works to the plugins. While there are -conceptions such as translation time and translation blocks the -details are opaque to plugins. The plugin is able to query select -details of instructions and system configuration only through the -exported *qemu_plugin* functions. - -Query Handle Lifetime ---------------------- - -Each callback provides an opaque anonymous information handle which -can usually be further queried to find out information about a -translation, instruction or operation. The handles themselves are only -valid during the lifetime of the callback so it is important that any -information that is needed is extracted during the callback and saved -by the plugin. - -API -=== - -.. kernel-doc:: include/qemu/qemu-plugin.h - Usage -===== +----- Any QEMU binary with TCG support has plugins enabled by default. Earlier releases needed to be explicitly enabled with:: @@ -87,8 +34,45 @@ Arguments are plugin specific and can be used to modify their behaviour. In this case the howvec plugin is being asked to use inline ops to count and break down the hint instructions by type. -Plugin Life cycle -================= +Writing plugins +--------------- + +API versioning +~~~~~~~~~~~~~~ + +This is a new feature for QEMU and it does allow people to develop +out-of-tree plugins that can be dynamically linked into a running QEMU +process. However the project reserves the right to change or break the +API should it need to do so. The best way to avoid this is to submit +your plugin upstream so they can be updated if/when the API changes. + +All plugins need to declare a symbol which exports the plugin API +version they were built against. This can be done simply by:: + + QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION; + +The core code will refuse to load a plugin that doesn't export a +``qemu_plugin_version`` symbol or if plugin version is outside of QEMU's +supported range of API versions. + +Additionally the ``qemu_info_t`` structure which is passed to the +``qemu_plugin_install`` method of a plugin will detail the minimum and +current API versions supported by QEMU. The API version will be +incremented if new APIs are added. The minimum API version will be +incremented if existing APIs are changed or removed. + +Lifetime of the query handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each callback provides an opaque anonymous information handle which +can usually be further queried to find out information about a +translation, instruction or operation. The handles themselves are only +valid during the lifetime of the callback so it is important that any +information that is needed is extracted during the callback and saved +by the plugin. + +Plugin life cycle +~~~~~~~~~~~~~~~~~ First the plugin is loaded and the public qemu_plugin_install function is called. The plugin will then register callbacks for various plugin @@ -111,11 +95,26 @@ callback which can then ensure atomicity itself. Finally when QEMU exits all the registered *atexit* callbacks are invoked. +Exposure of QEMU internals +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The plugin architecture actively avoids leaking implementation details +about how QEMU's translation works to the plugins. While there are +conceptions such as translation time and translation blocks the +details are opaque to plugins. The plugin is able to query select +details of instructions and system configuration only through the +exported *qemu_plugin* functions. + +API +~~~ + +.. kernel-doc:: include/qemu/qemu-plugin.h + Internals -========= +--------- Locking -------- +~~~~~~~ We have to ensure we cannot deadlock, particularly under MTTCG. For this we acquire a lock when called from plugin code. We also keep the @@ -142,7 +141,7 @@ requested. The plugin isn't completely uninstalled until the safe work has executed while all vCPUs are quiescent. Example Plugins -=============== +--------------- There are a number of plugins included with QEMU and you are encouraged to contribute your own plugins plugins upstream. There is a From patchwork Thu Sep 30 13:32:49 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 1534846 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20210112 header.b=dYtIks6I; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HKvrV1DTtz9sRf for ; Thu, 30 Sep 2021 23:55:04 +1000 (AEST) Received: from localhost ([::1]:57440 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVwWb-0005Si-8J for incoming@patchwork.ozlabs.org; Thu, 30 Sep 2021 09:55:01 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36616) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVwBc-0008LS-5o for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:20 -0400 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]:33489) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVwBP-0005Gx-Ms for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:19 -0400 Received: by mail-wr1-x432.google.com with SMTP id m22so4650712wrb.0 for ; Thu, 30 Sep 2021 06:33:05 -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=wGiJds0yYJhr+Mh+DFZjaEyEQDl2dwE5RZtIXSszFmI=; b=dYtIks6I21dRxe4WfC6o9I0N+38JtZvwi6632kzaAzLMwH6K6Ynj1i8jFOeCAgyyg/ zz9NB10rbmhipQBS3P7+c4Twyb7xBr+K5l1vcI6MPJaJDSHb0K7gRphPxraWFMUbJZyG tFSSZgBL0Akjt5gflz3bYZPFPLfSNljzk4dwfVHm3LxvTXRl6WoMYZosSOcf+8QFUKVc 3jgMzVCagOc3eqDvT4R6F3DZD+BeuA9seEFp8I/ZdcmbKsclDW+ysEPvoFtf4N8rqUk+ DeCtZ83rZL555f6r35sbg7watBGnbyMJc9GEfrOzD8mrS6dfMsHLs5DB0hIgwYcofJwH hrRw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=wGiJds0yYJhr+Mh+DFZjaEyEQDl2dwE5RZtIXSszFmI=; b=Ko7+4no7dMA2fc1ELuPDIcMsI9pJ/jFqWlxeIiSZL14FTNoikcilFlsSjooV+vcZtc OZdnOBWD06TKBFmpcD/NGTPzxC1pa+sal/GmnUiEs3ibt1JUZd/G5iDaMxoQ4WURIvUV 94I4OSQt1owaQWFDpDQK+HK52oTZnGGAY7kdojZ/pkqfwrSXcpv5LJcSuElywgllFcFr PgJU7zKrETDlhTA3wtg6Rwp43nPVEnm8585tNDt9uZrY3JlIZx7vHP5s4PhVexHXGG3/ XTaY0/dNbYGYri6kYwY18gl5jV1Vr2Isc0k9BzWOLDlK2oor2ESOj9ijIfoC7hFvUA/q 7G/A== X-Gm-Message-State: AOAM533MvLdu5zsZPxCO42WEFbrFR0lL3ATzApXnxTx4+Ukv4uQ9qSyD vDR3z+HI6MM3UfopgYzn6KPRRW281IY= X-Google-Smtp-Source: ABdhPJxz6xuDAyhuY82HXNCWHrBL5nZeIue6wfccLMBJW2Y8H4aMwJ2T2fkyhd9oaldO456Wo79XQw== X-Received: by 2002:adf:ecd2:: with SMTP id s18mr6198279wro.99.1633008784830; Thu, 30 Sep 2021 06:33:04 -0700 (PDT) Received: from localhost.localdomain ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id c4sm3037168wrt.23.2021.09.30.06.33.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 06:33:04 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 6/7] docs: move gcov section at the end of testing.rst Date: Thu, 30 Sep 2021 15:32:49 +0200 Message-Id: <20210930133250.181156-7-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210930133250.181156-1-pbonzini@redhat.com> References: <20210930133250.181156-1-pbonzini@redhat.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::432; envelope-from=paolo.bonzini@gmail.com; helo=mail-wr1-x432.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.249, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" gcov testing applies to all tests, not just make check. Move it out of the make check section. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/devel/testing.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 4a0abbf23d..200ce46c63 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -114,25 +114,6 @@ check-block are in the "auto" group). See the "QEMU iotests" section below for more information. -GCC gcov support ----------------- - -``gcov`` is a GCC tool to analyze the testing coverage by -instrumenting the tested code. To use it, configure QEMU with -``--enable-gcov`` option and build. Then run ``make check`` as usual. - -If you want to gather coverage information on a single test the ``make -clean-gcda`` target can be used to delete any existing coverage -information before running a single test. - -You can generate a HTML coverage report by executing ``make -coverage-html`` which will create -``meson-logs/coveragereport/index.html``. - -Further analysis can be conducted by running the ``gcov`` command -directly on the various .gcda output files. Please read the ``gcov`` -documentation for more information. - QEMU iotests ============ @@ -1233,3 +1214,22 @@ exercise as many corner cases as possible. It is a useful test suite to run to exercise QEMU's linux-user code:: https://linux-test-project.github.io/ + +GCC gcov support +================ + +``gcov`` is a GCC tool to analyze the testing coverage by +instrumenting the tested code. To use it, configure QEMU with +``--enable-gcov`` option and build. Then run the tests as usual. + +If you want to gather coverage information on a single test the ``make +clean-gcda`` target can be used to delete any existing coverage +information before running a single test. + +You can generate a HTML coverage report by executing ``make +coverage-html`` which will create +``meson-logs/coveragereport/index.html``. + +Further analysis can be conducted by running the ``gcov`` command +directly on the various .gcda output files. Please read the ``gcov`` +documentation for more information. From patchwork Thu Sep 30 13:32:50 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 1534835 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20210112 header.b=cb2Of3q2; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HKvZk5w1wz9sRf for ; Thu, 30 Sep 2021 23:43:10 +1000 (AEST) Received: from localhost ([::1]:54594 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVwL6-0000p5-Je for incoming@patchwork.ozlabs.org; Thu, 30 Sep 2021 09:43:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36562) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVwBX-0008AW-NE for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:15 -0400 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]:41570) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVwBT-0005JW-Fs for qemu-devel@nongnu.org; Thu, 30 Sep 2021 09:33:14 -0400 Received: by mail-wm1-x32d.google.com with SMTP id g19-20020a1c9d13000000b003075062d4daso4384209wme.0 for ; Thu, 30 Sep 2021 06:33:08 -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=WIMLHBiyDPK1hazF+HIFOa18J+vh2aSGumNwFu7JSos=; b=cb2Of3q2Ymlr6RggMNA273N5e7609BIDJDE1RTfcpWIBRVExwESymk8We28yYIZevI +3JHkIzTr9YKmclPkVNZwqiuKcoRpT2AphBHpRAXtYlT4NMZuQVaWYcACCp7vCliXyKJ 6VxYGu9WUK+88Hhqew0hobnH9Y1RJWjlPS3wkcWqh4RsK0e32AjGFqxjVFSxm45VNqUs zOp8jlmdaNLP52YY9U8DmeLyBx21BI3wree1nYPzIQ0JuHM8cEpQL57BmqVZ238ycwWR mf6yCzQ+we6FNvhb0OKLqGbKQufBE4mMvX7E9cCaRokgvA2tdl6GrzrzbGg0cjKfI9og meqw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=WIMLHBiyDPK1hazF+HIFOa18J+vh2aSGumNwFu7JSos=; b=vgc9JnDEco+4ybS4E8HOFTA6J0SpcH69FbduduaUYFElEMwzbTddSM/IMtlGr3+U93 FAOb/KTLKn0pxorXRRTrylYlD88scJEOkV6+DIwSC1yCBf/7T0P2QrXQ2pRko6K++0Ke ofJaWjJ3kMlEVQCHS/CcsTimW9u9DzsVidyE3fIj2sziONDfT1NQU8q4zyUC3Y0ylov0 P4YsdtwjFhfDDI2ZdvWF7hJ4xNT24TXXJRlEl/+duPFiMTaZFa4Y+vOSc2s3AOyE/1dh oGuN6TkS2AzUD9n/VSVtIAsl3zPdqAx7xbyPrhwQGlOyB7dhMleEK4Sj7P5VrSeYj74Q u7WA== X-Gm-Message-State: AOAM532COCfPvY8bGydUilgpi4nnCW4bAeuv8CjxWdDD8oYcNlWX7RAH oH1wVEPHTx/sckMg/zWyRXQY2//tbx8= X-Google-Smtp-Source: ABdhPJyk6yI7Nd8ekk9/k5rQiBMd6UQiT+oAw4RtMkzxBh2TD9b346PbnuOsE1r4XHtOjILt7OlMPw== X-Received: by 2002:a7b:c842:: with SMTP id c2mr15904189wml.93.1633008785506; Thu, 30 Sep 2021 06:33:05 -0700 (PDT) Received: from localhost.localdomain ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id c4sm3037168wrt.23.2021.09.30.06.33.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 06:33:05 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 7/7] docs: reorganize testing.rst Date: Thu, 30 Sep 2021 15:32:50 +0200 Message-Id: <20210930133250.181156-8-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210930133250.181156-1-pbonzini@redhat.com> References: <20210930133250.181156-1-pbonzini@redhat.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32d; envelope-from=paolo.bonzini@gmail.com; helo=mail-wm1-x32d.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.249, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Clean up the heading levels to use === --- ~~~ ^^^ '''. Reorganize the outline for the Avocado part, and always include headings for the class names. Signed-off-by: Paolo Bonzini --- docs/devel/testing.rst | 146 +++++++++++++++++++++-------------------- 1 file changed, 76 insertions(+), 70 deletions(-) diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 200ce46c63..8df38f751d 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -1,11 +1,10 @@ -=============== Testing in QEMU =============== This document describes the testing infrastructure in QEMU. Testing with "make check" -========================= +------------------------- The "make check" testing family includes most of the C based tests in QEMU. For a quick help, run ``make check-help`` from the source tree. @@ -24,7 +23,7 @@ expect the executables to exist and will fail with obscure messages if they cannot find them. Unit tests ----------- +~~~~~~~~~~ Unit tests, which can be invoked with ``make check-unit``, are simple C tests that typically link to individual QEMU object files and exercise them by @@ -67,7 +66,7 @@ and copy the actual command line which executes the unit test, then run it from the command line. QTest ------ +~~~~~ QTest is a device emulation testing framework. It can be very useful to test device models; it could also control certain aspects of QEMU (such as virtual @@ -81,7 +80,7 @@ QTest cases can be executed with make check-qtest QAPI schema tests ------------------ +~~~~~~~~~~~~~~~~~ The QAPI schema tests validate the QAPI parser used by QMP, by feeding predefined input to the parser and comparing the result with the reference @@ -108,14 +107,14 @@ parser (either fixing a bug or extending/modifying the syntax). To do this: ``qapi-schema += foo.json`` check-block ------------ +~~~~~~~~~~~ ``make check-block`` runs a subset of the block layer iotests (the tests that are in the "auto" group). See the "QEMU iotests" section below for more information. QEMU iotests -============ +------------ QEMU iotests, under the directory ``tests/qemu-iotests``, is the testing framework widely used to test block layer related features. It is higher level @@ -152,7 +151,7 @@ More options are supported by the ``./check`` script, run ``./check -h`` for help. Writing a new test case ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ Consider writing a tests case when you are making any changes to the block layer. An iotest case is usually the choice for that. There are already many @@ -206,7 +205,8 @@ test failure. If using such devices are explicitly desired, consider adding ``locking=off`` option to disable image locking. Debugging a test case ------------------------ +~~~~~~~~~~~~~~~~~~~~~ + The following options to the ``check`` script can be useful when debugging a failing test: @@ -235,7 +235,7 @@ a failing test: ``$TEST_DIR/qemu-machine-``. Test case groups ----------------- +~~~~~~~~~~~~~~~~ "Tests may belong to one or more test groups, which are defined in the form of a comment in the test source file. By convention, test groups are listed @@ -285,10 +285,10 @@ Note that the following group names have a special meaning: .. _container-ref: Container based tests -===================== +--------------------- Introduction ------------- +~~~~~~~~~~~~ The container testing framework in QEMU utilizes public images to build and test QEMU in predefined and widely accessible Linux @@ -303,7 +303,7 @@ The container images are also used to augment the generation of tests for testing TCG. See :ref:`checktcg-ref` for more details. Docker Prerequisites --------------------- +~~~~~~~~~~~~~~~~~~~~ Install "docker" with the system package manager and start the Docker service on your development machine, then make sure you have the privilege to run @@ -334,7 +334,7 @@ exploit the whole host with Docker bind mounting or other privileged operations. So only do it on development machines. Podman Prerequisites --------------------- +~~~~~~~~~~~~~~~~~~~~ Install "podman" with the system package manager. @@ -346,7 +346,7 @@ Install "podman" with the system package manager. The last command should print an empty table, to verify the system is ready. Quickstart ----------- +~~~~~~~~~~ From source tree, type ``make docker-help`` to see the help. Testing can be started without configuring or building QEMU (``configure`` and @@ -362,7 +362,7 @@ is downloaded and initialized automatically), in which the ``test-build`` job is executed. Registry --------- +~~~~~~~~ The QEMU project has a container registry hosted by GitLab at ``registry.gitlab.com/qemu-project/qemu`` which will automatically be @@ -376,7 +376,7 @@ locally by using the ``NOCACHE`` build option: make docker-image-debian10 NOCACHE=1 Images ------- +~~~~~~ Along with many other images, the ``centos8`` image is defined in a Dockerfile in ``tests/docker/dockerfiles/``, called ``centos8.docker``. ``make docker-help`` @@ -391,7 +391,7 @@ mainly used to do necessary host side setup. One such setup is ``binfmt_misc``, for example, to make qemu-user powered cross build containers work. Tests ------ +~~~~~ Different tests are added to cover various configurations to build and test QEMU. Docker tests are the executables under ``tests/docker`` named @@ -402,7 +402,7 @@ source and build it. The full list of tests is printed in the ``make docker-help`` help. Debugging a Docker test failure -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When CI tasks, maintainers or yourself report a Docker test failure, follow the below steps to debug it: @@ -419,7 +419,7 @@ below steps to debug it: the prompt for debug. Options -------- +~~~~~~~ Various options can be used to affect how Docker tests are done. The full list is in the ``make docker`` help text. The frequently used ones are: @@ -433,7 +433,7 @@ list is in the ``make docker`` help text. The frequently used ones are: failure" section. Thread Sanitizer -================ +---------------- Thread Sanitizer (TSan) is a tool which can detect data races. QEMU supports building and testing with this tool. @@ -443,7 +443,7 @@ For more information on TSan: https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual Thread Sanitizer in Docker ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ TSan is currently supported in the ubuntu2004 docker. The test-tsan test will build using TSan and then run make check. @@ -458,7 +458,7 @@ We recommend using DEBUG=1 to allow launching the test from inside the docker, and to allow review of the warnings generated by TSan. Building and Testing with TSan ------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible to build and test with TSan, with a few additional steps. These steps are normally done automatically in the docker. @@ -497,7 +497,7 @@ This allows for running the test and then checking the warnings afterwards. If you want TSan to stop and exit with error on warnings, use exitcode=66. TSan Suppressions ------------------ +~~~~~~~~~~~~~~~~~ Keep in mind that for any data race warning, although there might be a data race detected by TSan, there might be no actual bug here. TSan provides several different mechanisms for suppressing warnings. In general it is recommended @@ -523,7 +523,7 @@ More information on the file format can be found here under "Blacklist Format": https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags TSan Annotations ----------------- +~~~~~~~~~~~~~~~~ include/qemu/tsan.h defines annotations. See this file for more descriptions of the annotations themselves. Annotations can be used to suppress TSan warnings or give TSan more information so that it can detect proper @@ -540,14 +540,14 @@ The full set of annotations can be found here: https://github.com/llvm/llvm-project/blob/master/compiler-rt/lib/tsan/rtl/tsan_interface_ann.cpp VM testing -========== +---------- This test suite contains scripts that bootstrap various guest images that have necessary packages to build QEMU. The basic usage is documented in ``Makefile`` help which is displayed with ``make vm-help``. Quickstart ----------- +~~~~~~~~~~ Run ``make vm-help`` to list available make targets. Invoke a specific make command to run build test in an image. For example, ``make vm-build-freebsd`` @@ -562,7 +562,7 @@ concerned about attackers taking control of the guest and potentially exploiting a QEMU security bug to compromise the host. QEMU binaries -------------- +~~~~~~~~~~~~~ By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there isn't one, or if it is older than 2.10, the test won't work. In this case, @@ -571,20 +571,20 @@ provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``. Likewise the path to qemu-img can be set in QEMU_IMG environment variable. Make jobs ---------- +~~~~~~~~~ The ``-j$X`` option in the make command line is not propagated into the VM, specify ``J=$X`` to control the make jobs in the guest. Debugging ---------- +~~~~~~~~~ Add ``DEBUG=1`` and/or ``V=1`` to the make command to allow interactive debugging and verbose output. If this is not enough, see the next section. ``V=1`` will be propagated down into the make jobs in the guest. Manual invocation ------------------ +~~~~~~~~~~~~~~~~~ Each guest script is an executable script with the same command line options. For example to work with the netbsd guest, use ``$QEMU_SRC/tests/vm/netbsd``: @@ -608,7 +608,7 @@ For example to work with the netbsd guest, use ``$QEMU_SRC/tests/vm/netbsd``: $ ./netbsd --interactive --image /var/tmp/netbsd.img sh Adding new guests ------------------ +~~~~~~~~~~~~~~~~~ Please look at existing guest scripts for how to add new guests. @@ -641,7 +641,7 @@ the script's ``main()``. recommended. Image fuzzer testing -==================== +-------------------- An image fuzzer was added to exercise format drivers. Currently only qcow2 is supported. To start the fuzzer, run @@ -654,7 +654,7 @@ Alternatively, some command different from "qemu-img info" can be tested, by changing the ``-c`` option. Acceptance tests using the Avocado Framework -============================================ +-------------------------------------------- The ``tests/acceptance`` directory hosts functional tests, also known as acceptance level tests. They're usually higher level tests, and @@ -693,7 +693,7 @@ Tests based on ``avocado_qemu.Test`` can easily: - http://avocado-framework.readthedocs.io/en/latest/api/utils/avocado.utils.html Running tests -------------- +~~~~~~~~~~~~~ You can run the acceptance tests simply by executing: @@ -722,7 +722,7 @@ may be invoked by running: tests/venv/bin/avocado run $OPTION1 $OPTION2 tests/acceptance/ Manual Installation -------------------- +~~~~~~~~~~~~~~~~~~~ To manually install Avocado and its dependencies, run: @@ -735,7 +735,7 @@ Alternatively, follow the instructions on this link: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/installing.html Overview --------- +~~~~~~~~ The ``tests/acceptance/avocado_qemu`` directory provides the ``avocado_qemu`` Python module, containing the ``avocado_qemu.Test`` @@ -771,7 +771,7 @@ in the current directory, tagged as "quick", run: avocado run -t quick . The ``avocado_qemu.Test`` base test class ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``avocado_qemu.Test`` class has a number of characteristics that are worth being mentioned right away. @@ -821,7 +821,7 @@ At test "tear down", ``avocado_qemu.Test`` handles all the QEMUMachines shutdown. The ``avocado_qemu.LinuxTest`` base test class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``avocado_qemu.LinuxTest`` is further specialization of the ``avocado_qemu.Test`` class, so it contains all the characteristics of @@ -864,7 +864,7 @@ execution of a QEMU binary, giving its users: a more succinct and intuitive way QEMU binary selection -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ The QEMU binary used for the ``self.vm`` QEMUMachine instance will primarily depend on the value of the ``qemu_bin`` parameter. If it's @@ -885,20 +885,23 @@ The resulting ``qemu_bin`` value will be preserved in the ``avocado_qemu.Test`` as an attribute with the same name. Attribute reference -------------------- +~~~~~~~~~~~~~~~~~~~ + +Test +^^^^ Besides the attributes and methods that are part of the base ``avocado.Test`` class, the following attributes are available on any ``avocado_qemu.Test`` instance. vm -~~ +'' A QEMUMachine instance, initially configured according to the given ``qemu_bin`` parameter. arch -~~~~ +'''' The architecture can be used on different levels of the stack, e.g. by the framework or by the test itself. At the framework level, it will @@ -915,7 +918,7 @@ name. If one is not given explicitly, it will either be set to ``:avocado: tags=arch:VALUE`` tag, it will be set to ``VALUE``. cpu -~~~ +''' The cpu model that will be set to all QEMUMachine instances created by the test. @@ -926,7 +929,7 @@ name. If one is not given explicitly, it will either be set to ``:avocado: tags=cpu:VALUE`` tag, it will be set to ``VALUE``. machine -~~~~~~~ +''''''' The machine type that will be set to all QEMUMachine instances created by the test. @@ -937,20 +940,20 @@ name. If one is not given explicitly, it will either be set to ``:avocado: tags=machine:VALUE`` tag, it will be set to ``VALUE``. qemu_bin -~~~~~~~~ +'''''''' The preserved value of the ``qemu_bin`` parameter or the result of the dynamic probe for a QEMU binary in the current working directory or source tree. LinuxTest -~~~~~~~~~ +^^^^^^^^^ Besides the attributes present on the ``avocado_qemu.Test`` base class, the ``avocado_qemu.LinuxTest`` adds the following attributes: distro -...... +'''''' The name of the Linux distribution used as the guest image for the test. The name should match the **Provider** column on the list @@ -959,7 +962,7 @@ of images supported by the avocado.utils.vmimage library: https://avocado-framework.readthedocs.io/en/latest/guides/writer/libs/vmimage.html#supported-images distro_version -.............. +'''''''''''''' The version of the Linux distribution as the guest image for the test. The name should match the **Version** column on the list @@ -968,7 +971,7 @@ of images supported by the avocado.utils.vmimage library: https://avocado-framework.readthedocs.io/en/latest/guides/writer/libs/vmimage.html#supported-images distro_checksum -............... +''''''''''''''' The sha256 hash of the guest image file used for the test. @@ -977,7 +980,7 @@ same name), no validation on the integrity of the image will be performed. Parameter reference -------------------- +~~~~~~~~~~~~~~~~~~~ To understand how Avocado parameters are accessed by tests, and how they can be passed to tests, please refer to:: @@ -991,8 +994,11 @@ like the following: PARAMS (key=qemu_bin, path=*, default=./qemu-system-x86_64) => './qemu-system-x86_64 +Test +^^^^ + arch -~~~~ +'''' The architecture that will influence the selection of a QEMU binary (when one is not explicitly given). @@ -1005,31 +1011,30 @@ This parameter has a direct relation with the ``arch`` attribute. If not given, it will default to None. cpu -~~~ +''' The cpu model that will be set to all QEMUMachine instances created by the test. machine -~~~~~~~ +''''''' The machine type that will be set to all QEMUMachine instances created by the test. - qemu_bin -~~~~~~~~ +'''''''' The exact QEMU binary to be used on QEMUMachine. LinuxTest -~~~~~~~~~ +^^^^^^^^^ Besides the parameters present on the ``avocado_qemu.Test`` base class, the ``avocado_qemu.LinuxTest`` adds the following parameters: distro -...... +'''''' The name of the Linux distribution used as the guest image for the test. The name should match the **Provider** column on the list @@ -1038,7 +1043,7 @@ of images supported by the avocado.utils.vmimage library: https://avocado-framework.readthedocs.io/en/latest/guides/writer/libs/vmimage.html#supported-images distro_version -.............. +'''''''''''''' The version of the Linux distribution as the guest image for the test. The name should match the **Version** column on the list @@ -1047,7 +1052,7 @@ of images supported by the avocado.utils.vmimage library: https://avocado-framework.readthedocs.io/en/latest/guides/writer/libs/vmimage.html#supported-images distro_checksum -............... +''''''''''''''' The sha256 hash of the guest image file used for the test. @@ -1055,7 +1060,8 @@ If this value is not set in the code or by this parameter no validation on the integrity of the image will be performed. Skipping tests --------------- +~~~~~~~~~~~~~~ + The Avocado framework provides Python decorators which allow for easily skip tests running under certain conditions. For example, on the lack of a binary on the test system or when the running environment is a CI system. For further @@ -1070,7 +1076,7 @@ environment variables became a kind of standard way to enable/disable tests. Here is a list of the most used variables: AVOCADO_ALLOW_LARGE_STORAGE -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Tests which are going to fetch or produce assets considered *large* are not going to run unless that ``AVOCADO_ALLOW_LARGE_STORAGE=1`` is exported on the environment. @@ -1079,7 +1085,7 @@ The definition of *large* is a bit arbitrary here, but it usually means an asset which occupies at least 1GB of size on disk when uncompressed. AVOCADO_ALLOW_UNTRUSTED_CODE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are tests which will boot a kernel image or firmware that can be considered not safe to run on the developer's workstation, thus they are skipped by default. The definition of *not safe* is also arbitrary but @@ -1090,7 +1096,7 @@ You should export ``AVOCADO_ALLOW_UNTRUSTED_CODE=1`` on the environment in order to allow tests which make use of those kind of assets. AVOCADO_TIMEOUT_EXPECTED -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ The Avocado framework has a timeout mechanism which interrupts tests to avoid the test suite of getting stuck. The timeout value can be set via test parameter or property defined in the test class, for further details:: @@ -1104,7 +1110,7 @@ compiled with debug flags. Therefore, the ``AVOCADO_TIMEOUT_EXPECTED`` variable has been used to determine whether those tests should run or not. GITLAB_CI -~~~~~~~~~ +^^^^^^^^^ A number of tests are flagged to not run on the GitLab CI. Usually because they proved to the flaky or there are constraints on the CI environment which would make them fail. If you encounter a similar situation then use that @@ -1117,7 +1123,7 @@ variable as shown on the code snippet below to skip the test: do_something() Uninstalling Avocado --------------------- +~~~~~~~~~~~~~~~~~~~~ If you've followed the manual installation instructions above, you can easily uninstall Avocado. Start by listing the packages you have @@ -1135,7 +1141,7 @@ Avocado is installed will be cleaned up as part of ``make check-clean``. .. _checktcg-ref: Testing with "make check-tcg" -============================= +----------------------------- The check-tcg tests are intended for simple smoke tests of both linux-user and softmmu TCG functionality. However to build test @@ -1168,7 +1174,7 @@ itself. See :ref:`container-ref` for more details. Running subset of tests ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ You can build the tests for one architecture:: @@ -1182,7 +1188,7 @@ Adding ``V=1`` to the invocation will show the details of how to invoke QEMU for the test which is useful for debugging tests. TCG test dependencies ---------------------- +~~~~~~~~~~~~~~~~~~~~~ The TCG tests are deliberately very light on dependencies and are either totally bare with minimal gcc lib support (for softmmu tests) @@ -1216,7 +1222,7 @@ to run to exercise QEMU's linux-user code:: https://linux-test-project.github.io/ GCC gcov support -================ +---------------- ``gcov`` is a GCC tool to analyze the testing coverage by instrumenting the tested code. To use it, configure QEMU with