From patchwork Fri Feb 16 16:30:24 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 773362 Delivered-To: patch@linaro.org Received: by 2002:a5d:4943:0:b0:33b:4db1:f5b3 with SMTP id r3csp28033wrs; Fri, 16 Feb 2024 08:39:05 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCUXSINlLnJl4J01mcgktHxJ7GPgrboukccq3X0fxotuiPw//oFX4RvQHHXjBewyFAHOD5wYSsI/ozOTYFMvtj8Q X-Google-Smtp-Source: AGHT+IEznOmkrTyAricXpCDPIAKtgubr0VKTpgOEH1txI8hcyDZQ6MlPqtZn6xMzZRm0PFQeMMbl X-Received: by 2002:ad4:5743:0:b0:68f:280f:14cb with SMTP id q3-20020ad45743000000b0068f280f14cbmr5267110qvx.34.1708101545343; Fri, 16 Feb 2024 08:39:05 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1708101545; cv=none; d=google.com; s=arc-20160816; b=F7W9G0EX5MWZW+j6L9x4yNWuHSx8ZALhlG3C/Fd7nzfaJ1nbrX7lJzC1aHmYdh3AWX Re86qP5+5XB49m/gVUGn5HMpRO308HXvTZXT7S+9MPN4A2OTD7D7G+shQh0IZ0pWWz8u oERO82X0PZI5eABLflB0Gll7GB5saHCkEMVfPHFt43W2DZw97cJH7cou7bjCEWDVcPy7 NyNkFzJKqNvN4BzSrVCUsakXhXIq+aIsAeRmP00DfSnCByIL38E0gv2XNjR+uxsMr8Re 4JzumvOEut3sVbKcfs/xLf2fG3nHeAHnOKCmpC6eMjyt2UPfZm7EC4sdK049gNcHqK4B uLcQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=zMZ+pFdg1P4n/cHnfp4DZXoxUsYEnk+lXnRUtGdShK8=; fh=BiCuxLgE2Qo8NnA5oZWxFqr6rT9EcPosGDdXLEV2jRw=; b=sPgvabEmgYBSfZ1s+Q1RB3p8ysS/Fjh2u3Iq0wyLYW5cWnYt4rz00CR0tkmpDTTdgv +6ANx/CXZfsOg287ECUgx7qXGK2FIPsA9fp9+7+vnbkr8J9M+eQSjrrnlgbLchJ/66ZI UEfTbZr240zd+p0cq0ESP5GgyaMClyy/kxLrSNmCYnNeKEPh2Q7x1Y2VkNP+8WSd9PRH AXvTD1p5sYhrjuah0yHzOsoueyJ649jZ6gjUSqLYNDVURdNvgjLptA2YNSiTe+DI4M1D p2wROJP/jGrnb5Nleb1Mo8UGXsp7WwXYmjSrGfts9eQMu6jfnnx0X/cnGRQS2HK1tSZq +uZg==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="pvBb/hxo"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id r13-20020a056214212d00b0068d03eaab18si115001qvc.404.2024.02.16.08.39.05 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Fri, 16 Feb 2024 08:39:05 -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=pass header.i=@linaro.org header.s=google header.b="pvBb/hxo"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rb1Db-0001Dc-Ey; Fri, 16 Feb 2024 11:37:43 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rb1DX-0001BW-Ag for qemu-devel@nongnu.org; Fri, 16 Feb 2024 11:37:40 -0500 Received: from mail-lj1-x229.google.com ([2a00:1450:4864:20::229]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rb1DT-00042Q-6T for qemu-devel@nongnu.org; Fri, 16 Feb 2024 11:37:38 -0500 Received: by mail-lj1-x229.google.com with SMTP id 38308e7fff4ca-2d0a4e1789cso26317741fa.3 for ; Fri, 16 Feb 2024 08:37:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1708101452; x=1708706252; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=zMZ+pFdg1P4n/cHnfp4DZXoxUsYEnk+lXnRUtGdShK8=; b=pvBb/hxoCHkAAvCXqmkSa0i8ubAqg/YL+N2TO74XCC5A01sh7H4YEbYRVJn5fzH0Yg DJvDtuqqiCeuamroWavYdWhydR3emPvbK35OPjRUNF2psGPWh84Aybo8H0DO9SWt90L9 LsVFv9e2EJzTZ+ckTcv929QOUMUWHyXDYnYZ+qkxIucAfBX3XuhTI6ogTRchOpqEAMhe CHyTvmnhHEAVY++RU+qWdG2K89cNukuvVOOcmDkCCpFOvDUFtLexQ7cmr6DzYViIMznt FjRCPSh9aR7Oyxjyd0mTxGjmTFJCPcdTbTn5h84WiZnKWNkIKooXcTmtH6VGNPdnnW60 ChzQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1708101452; x=1708706252; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=zMZ+pFdg1P4n/cHnfp4DZXoxUsYEnk+lXnRUtGdShK8=; b=IC4JuXNshxiqNc2r9WEdU+/cl5TXec/qMop3gv7QLZSAnMk+reuowtYyMJwRwHjs5A 4QCSCOW44KMZgot8nX9RNjtGyg4SyaQ2bU5+BZDkx03xVzULrePtPUWGleMHN1n5JHl6 mhjr+JbMtnlyKkUnX4TfS8D0rOZcYYajNi94Qi7D8E+8ySCuFk/9QXGgiNDyT6KrwzVx Lomhvy65gt3qMpbOZqKv3739E+XFRMAlu9pKwSHVG6GOvqHfhxnJYZr+ZFAKtZydkbgj Rlghv2VPhhVnaxChL5MeH8wT/2/IaTmxxrX/hPMgh1EWl78kn1e5z/PLc3FxBwRRravj taHA== X-Gm-Message-State: AOJu0YyeVaCZ1zH7QA0lo+Kb1We/Ggmp1CwJ/oOMjxpyCO1R3EKx4+Xm nwrDpfBvIGGHOzNNsCqG9Yf/ds9Oy9LN2IpPmFBr0uZpTtdSRsGU9ALqlEOy1N02f5DINOs2pTV T X-Received: by 2002:a05:651c:2046:b0:2d0:4ef8:347a with SMTP id t6-20020a05651c204600b002d04ef8347amr3340354ljo.18.1708101452538; Fri, 16 Feb 2024 08:37:32 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id i6-20020a05600c354600b004107686650esm2850704wmq.36.2024.02.16.08.37.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 16 Feb 2024 08:37:32 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 857F65F9E8; Fri, 16 Feb 2024 16:30:28 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Yoshinori Sato , David Hildenbrand , Weiwei Li , Richard Henderson , Michael Rolnik , Ilya Leoshkevich , Peter Maydell , qemu-ppc@nongnu.org, Paolo Bonzini , qemu-riscv@nongnu.org, Cleber Rosa , Thomas Huth , Song Gao , qemu-arm@nongnu.org, Pierrick Bouvier , John Snow , =?utf-8?q?Alex_Benn=C3=A9e?= , =?utf-8?q?C=C3=A9dri?= =?utf-8?q?c_Le_Goater?= , Nicholas Piggin , qemu-s390x@nongnu.org, Laurent Vivier , "Edgar E. Iglesias" , Daniel Henrique Barboza , Yanan Wang , Palmer Dabbelt , Marcel Apfelbaum , Brian Cain , Mahmoud Mandour , Alexandre Iooss , Bin Meng , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Daniel Henrique Barboza , Eduardo Habkost , Alistair Francis , Liu Zhiwei Subject: [PATCH 22/23] docs/devel: document some plugin assumptions Date: Fri, 16 Feb 2024 16:30:24 +0000 Message-Id: <20240216163025.424857-23-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240216163025.424857-1-alex.bennee@linaro.org> References: <20240216163025.424857-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::229; envelope-from=alex.bennee@linaro.org; helo=mail-lj1-x229.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org While we attempt to hide implementation details from the plugin we shouldn't be totally obtuse. Let the user know what they can and can't expect with the various instrumentation options. Message-Id: <20240103173349.398526-44-alex.bennee@linaro.org> Reviewed-by: Pierrick Bouvier Signed-off-by: Alex Bennée --- docs/devel/tcg-plugins.rst | 49 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index 535a74684c5..9cc09d8c3da 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -112,6 +112,55 @@ 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. +However the following assumptions can be made: + +Translation Blocks +++++++++++++++++++ + +All code will go through a translation phase although not all +translations will be necessarily be executed. You need to instrument +actual executions to track what is happening. + +It is quite normal to see the same address translated multiple times. +If you want to track the code in system emulation you should examine +the underlying physical address (``qemu_plugin_insn_haddr``) to take +into account the effects of virtual memory although if the system does +paging this will change too. + +Not all instructions in a block will always execute so if its +important to track individual instruction execution you need to +instrument them directly. However asynchronous interrupts will not +change control flow mid-block. + +Instructions +++++++++++++ + +Instruction instrumentation runs before the instruction executes. You +can be can be sure the instruction will be dispatched, but you can't +be sure it will complete. Generally this will be because of a +synchronous exception (e.g. SIGILL) triggered by the instruction +attempting to execute. If you want to be sure you will need to +instrument the next instruction as well. See the ``execlog.c`` plugin +for examples of how to track this and finalise details after execution. + +Memory Accesses ++++++++++++++++ + +Memory callbacks are called after a successful load or store. +Unsuccessful operations (i.e. faults) will not be visible to memory +instrumentation although the execution side effects can be observed +(e.g. entering a exception handler). + +System Idle and Resume States ++++++++++++++++++++++++++++++ + +The ``qemu_plugin_register_vcpu_idle_cb`` and +``qemu_plugin_register_vcpu_resume_cb`` functions can be used to track +when CPUs go into and return from sleep states when waiting for +external I/O. Be aware though that these may occur less frequently +than in real HW due to the inefficiencies of emulation giving less +chance for the CPU to idle. + Internals ---------