From patchwork Wed Feb 28 11:57:00 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: 776478 Delivered-To: patch@linaro.org Received: by 2002:adf:e94d:0:b0:33d:f458:43ce with SMTP id m13csp253535wrn; Wed, 28 Feb 2024 04:03:49 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCXWgWqgf7wLdtEQaWHcYYXKBo/3FtAZvxGSA4RvyKkmBjhMIDLRYjI+kaTft5HzXvtbeSXSQq9OYdU5CH9kdpAo X-Google-Smtp-Source: AGHT+IHlsMKSa05dCjlhxOEYR7tSXgQ5FY1StbpsCSYu/JytESFqf2FOx/A6QP1F/HnvSzUIZlrm X-Received: by 2002:ac8:5c96:0:b0:42e:aa90:ab6e with SMTP id r22-20020ac85c96000000b0042eaa90ab6emr2470975qta.48.1709121829557; Wed, 28 Feb 2024 04:03:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709121829; cv=none; d=google.com; s=arc-20160816; b=yV4OjNoUf2/kbLzs7O+sMl9a3A7iKKLWO3xDfUe7ffO8wVQYaPBwM69eq+qiOFjGoX RE9QY5juSNDTxH0Xn2FBKkgZiqvlITTuFMvpUJaTN8TuKP3CYuBIDnXcOnw2s2V9aY02 bt1kBc2bjgjT1kyqHRnmncqMjOzRUweXznyWY5//4lLDzQiBD/5U3iWFGa+2ydw0bHme nCqunp108+/JYf3CBd6mEe1CkdhyAysAjZAXx0vFfLsL9+eeJredCdb1BLQRxg/BMmPy zZZI8Sb1twnn5sIbimclgPeVkRvNFNN4EJFdVcJUCEVwKK8wD6tzhw5uTY9znxpwWRrL fHVg== 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=pC0CILfvkT1LAPjD+cy5PSMJ+8YOfVMAkY3CpGh5+Vk=; fh=J1mEt/br0T95fqv/QqsgNqYqKUXznBIGHik03n80zmI=; b=kmMe2RF5iRTCzaU+xwM6JBkdlXfzMfcqaD9MSDkQXLSsamt9YyMIM4KSqExqJTGb1D Y9HCPs8lB/w0JWVpeSIyh/twGm/2PqVg0HOVEEKXeYF7sRhj7QAZgJvz23AJg6pJ5LMt TtKIjuhFj4r/eV3/14pPRvu7nKV5xIBIYePoAt4yl7pI08x1pZmjNVmhjipBIm5JBK8X tcgY+Jm3qt4Nafv3iaOt92EWpKwhvCXi0r5wPGQB8fHZ/qivulnxFYA3SErY0BhM3plh ooY+3u5xCh0YUsDe1ywXTnhTxs11DPZGv20yob0Bholrs87U9UwBAtGjdKtA4tEhpPNs ohpg==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="EzsGqqv/"; 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 p18-20020ae9f312000000b00787187a0b6fsi9567587qkg.692.2024.02.28.04.03.49 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 28 Feb 2024 04:03:49 -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="EzsGqqv/"; 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 1rfIeT-0004nA-Lq; Wed, 28 Feb 2024 07:03:10 -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 1rfIeO-0004dm-Bl for qemu-devel@nongnu.org; Wed, 28 Feb 2024 07:03:04 -0500 Received: from mail-lj1-x232.google.com ([2a00:1450:4864:20::232]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rfIeI-00034h-AZ for qemu-devel@nongnu.org; Wed, 28 Feb 2024 07:03:04 -0500 Received: by mail-lj1-x232.google.com with SMTP id 38308e7fff4ca-2d28387db09so45489231fa.0 for ; Wed, 28 Feb 2024 04:02:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1709121776; x=1709726576; 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=pC0CILfvkT1LAPjD+cy5PSMJ+8YOfVMAkY3CpGh5+Vk=; b=EzsGqqv/OZUmEcdlXjmGNBRONrKIG5AxkP+ZT5wtEROzkND9WnNCuWEMaiYVzpzzsN C7jqBulZ+swpfDZLNtEIJPSY0qLXn5+3OzN2Jo/sQI6DM6fYXCwbbfJHREdAXtqyHwpF O7HdyNrr1x/q3xDc07HMU/Hd0Ith4UfYGGb/Ft/j7kDdBoDzlqODsO0EkwZu13qVkUPM a9jnVslufT/OYIRJNdUeufBAdp87dEwDJlWyqsiVx3iHr3hzO9Vz/OeMmKcOzxLQATNN pJnAoal0tqcuK6PfsoXTwz4EL/Ww7IFa3FNO/GQHi7L4ns6OP4pB/rTQhMEyh7374o7w 8P9w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709121776; x=1709726576; 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=pC0CILfvkT1LAPjD+cy5PSMJ+8YOfVMAkY3CpGh5+Vk=; b=GbxaEl/+tDDIOxK7Pj7vky/0HekHkWTu6YTFIaec+/IRj5mfdP0tIkMvLJiVcUOKZs YuOYbV5m+oUF6bb/DcE8cT0cSJJWYyAEQ0SDZcFhAA+enqNR9GDv718CJ5RPaLZH0I+U PDJCECLeI6zhw9y7H07bMHfRZID9nA9zReXCuDOO/tVj97i92AMRYlrHy/OFWloNuRVv /VnEa5Gthx1bbiLkYKWjoGdnIy8XiuUPjHY3L4fGJmBsboBDLHVCPYhRuHLuClYUGlPr /0Gag2SXL2D8286SvqZNYlYGkMBeRKgDUpHnWSIQ7pvh+UghCMmcx9xCXR/0WAsPfqaF HM+w== X-Gm-Message-State: AOJu0Yxw9DXsuzvSfDNUnVpWTknZrZDcBI/WkDurF3SAYuTG6nMVMlZE E7D6RWvqQhNi70saiqMMCiEk//Mrl+52GwwLTJ5GSOiYCWE65dTS2I8vALtisR4= X-Received: by 2002:a2e:6a06:0:b0:2d1:1ef3:3c84 with SMTP id f6-20020a2e6a06000000b002d11ef33c84mr7438014ljc.28.1709121776728; Wed, 28 Feb 2024 04:02:56 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id az8-20020adfe188000000b0033d7dd27d97sm14421391wrb.45.2024.02.28.04.02.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Feb 2024 04:02:56 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 8E2165F92F; Wed, 28 Feb 2024 11:57:04 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: =?utf-8?q?Alex_Benn=C3=A9e?= , Pierrick Bouvier , Richard Henderson , Paolo Bonzini , Alexandre Iooss , Mahmoud Mandour Subject: [PULL 28/29] docs/devel: document some plugin assumptions Date: Wed, 28 Feb 2024 11:57:00 +0000 Message-Id: <20240228115701.1416107-29-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240228115701.1416107-1-alex.bennee@linaro.org> References: <20240228115701.1416107-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::232; envelope-from=alex.bennee@linaro.org; helo=mail-lj1-x232.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, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_TEMPERROR=0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+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. Reviewed-by: Pierrick Bouvier Signed-off-by: Alex Bennée Message-Id: <20240227144335.1196131-29-alex.bennee@linaro.org> 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 ---------