From patchwork Fri Feb 23 16:22:01 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: 775146 Delivered-To: patch@linaro.org Received: by 2002:adf:a356:0:b0:33b:4db1:f5b3 with SMTP id d22csp436539wrb; Fri, 23 Feb 2024 08:40:49 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCUkakfRk1T7hpgmpq3zXpWOdJXD6ay6/sbpeb54SRuxiY+NqZQLApJvZFPcD1uAG3Vm1URk/LBq7UwN5yP4jCyX X-Google-Smtp-Source: AGHT+IEAYlUFsbONVHukyJ9l9g8+M/xfuTq8+rO5rk8/Cs9KCyr4eM6To3vEe3U6gFFk6H4TYYaf X-Received: by 2002:ad4:5c6f:0:b0:68f:2c48:d217 with SMTP id i15-20020ad45c6f000000b0068f2c48d217mr388121qvh.59.1708706449733; Fri, 23 Feb 2024 08:40:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1708706449; cv=none; d=google.com; s=arc-20160816; b=EySyNlqG89rWevQiV7hNrNLB/r+In/W7vm9qwT9wbxVMTpX3j7eVOhiLKmBjHFoi3w NXX7FpVJOEmO/fkaVkfvG5+WtL1IfoxMps1hv3JFuP4/wZIg7NUVNLgcF3VG6snWrY+z VQbtU8/h9VBixDB13M0XT6ZQNpm5UeB23YvwCgqCN/v2JH5lx31pPPu4LcmqG1RELDUS A2U2gQtWUZsl3xbplSKVCnmVtxJGQ1q/iQT/bnRFUkCL7R4JMhlhOYSoj2qxxZwGmfmJ R8XPbNI+F85+f0gf2U/131JkevwxLXA/jowpwzZbdNUZcLJTpr3Le2fW9LNH3hO46nfB QJKQ== 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=/YEu+IjZM84YWRDAuPeJeqMoLNTdSzM/iYv/jybOCWk=; b=ubTe5G51fbCaj/2W9JPvs4Pl8aINtFUmd75drX/lRFLLr4TGCe2mLyxLHvSRi16mXt R5mviMeP9qw6xve0fqf9Hg4kbxuI7SssLCoZK/1ok/MVJahRz9sSJtroDHqcEkzT4qTV qQNza0uvFT+LsHZx632W/7QVHOh6ezvPdL3lFBXVjqD5xJHVTM3XIIwYiZ+F1A84murL 4xsMfwdn3KNHfD2tCPpMkgU8Kpsh14PGBzdrdKTB3470vQ+qF32DL6fSvViVxAWBuQY5 4YrKU6wrRzr0Ic4GbBeRJ00vk1qz9kC9wiuoVeuv4S/1816SVHlJDnt0mSNq75h7F9Fj VMkQ==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=vjjV7psm; 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 iw12-20020a0562140f2c00b0068f2b0ee1edsi15501236qvb.265.2024.02.23.08.40.49 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Fri, 23 Feb 2024 08:40: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=vjjV7psm; 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 1rdYZI-0005UI-0N; Fri, 23 Feb 2024 11:38:36 -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 1rdYQU-00064z-Sc for qemu-devel@nongnu.org; Fri, 23 Feb 2024 11:29:31 -0500 Received: from mail-lj1-x234.google.com ([2a00:1450:4864:20::234]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rdYQ3-0007JK-65 for qemu-devel@nongnu.org; Fri, 23 Feb 2024 11:29:26 -0500 Received: by mail-lj1-x234.google.com with SMTP id 38308e7fff4ca-2d269b2ff48so6403631fa.3 for ; Fri, 23 Feb 2024 08:28:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1708705735; x=1709310535; 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=vjjV7psm0ahi2D9CymFO6KnJ9ylP7XpmCPT2m9GU6eHeg3mPTZ0UVmlOO0TlSTPI8N zeMKsWQ/7Q8PsUcq6MUViL8zoZTgPU5ljGdCbInDElidQX/z4ZdgX2vqYgmJQ02g180Y 69r6YO+UVM3RerMdOlOfSpOipfdBgmq2Qx9m2yrvHhYpdEcOlLixNST7KSfWwkEmV7kz fFJ+9tF+4up+fDre1g4xeuRl6E88sM9ktPK8sGPbI5XgY0HVC7meKEn92XitcSigyzXD IfA4ZrcsfYq1bBNKPbsIx11XP8wN1R3Dvpj7bH5e1ZnZDmU3BhWReZHQRbzXLjmY+WEl /w1w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1708705735; x=1709310535; 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=tetnb+1CpSkDDISQVn/Vf9IeUAnmAUFE0AN0eWO6+o8Y4LdbP7HhPJ9LKHXko2fUq0 LdMaUpX0WM3QRWr2ZV9yDFe8efDAQyIutffEJmxiqW9ZkGThmZcL4lkFlHhrrGWRufxD HrFlXYxX5NM9DSKsQ4LKnI9+5ic62NG0lWdDJg2p4cFpT6v/fXMKmE2j/jY38bqJ8fDZ A+DmSUiO+FQrL8zvXnBIOm85RsZNz4Rk6kq9/Yx5dzHJz4Eq95xRsYmGN10f82Mwuwin j/dDAcQvgTRCzSEQsVF8AUYWpaehm++KXWvYgpaXkcRaRJhOZ5F83q01LEVq7e/wWtFD vffw== X-Gm-Message-State: AOJu0Yxgqkn2tWtVqT7H58RbiL3+ulO564okbcWZOHCnFVn9LJlSuET5 WZCoECVN3+XvG/fQuKSfIZO1ZPj82Qc3PTY8FyrYdoPMlFKKChwpqgIS2uG3Wfw= X-Received: by 2002:a2e:820b:0:b0:2d2:3a77:b304 with SMTP id w11-20020a2e820b000000b002d23a77b304mr219062ljg.1.1708705734751; Fri, 23 Feb 2024 08:28:54 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id w21-20020a05600c015500b004128da16dddsm2772246wmm.15.2024.02.23.08.28.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 23 Feb 2024 08:28:52 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id ED5455F93C; Fri, 23 Feb 2024 16:22:04 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Song Gao , qemu-s390x@nongnu.org, Liu Zhiwei , Pierrick Bouvier , Thomas Huth , Daniel Henrique Barboza , Bin Meng , Yanan Wang , Laurent Vivier , qemu-ppc@nongnu.org, David Hildenbrand , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Ilya Leoshkevich , Cleber Rosa , Nicholas Piggin , Marcel Apfelbaum , Eduardo Habkost , Richard Henderson , =?utf-8?q?Philippe_Mathie?= =?utf-8?q?u-Daud=C3=A9?= , Alexandre Iooss , Peter Maydell , =?utf-8?q?Alex_Benn=C3=A9e?= , Daniel Henrique Barboza , qemu-arm@nongnu.org, qemu-riscv@nongnu.org, Palmer Dabbelt , Mahmoud Mandour , John Snow , Weiwei Li , Alistair Francis , Yoshinori Sato , Brian Cain , Paolo Bonzini , "Edgar E. Iglesias" , Michael Rolnik Subject: [PATCH v2 26/27] docs/devel: document some plugin assumptions Date: Fri, 23 Feb 2024 16:22:01 +0000 Message-Id: <20240223162202.1936541-27-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240223162202.1936541-1-alex.bennee@linaro.org> References: <20240223162202.1936541-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::234; envelope-from=alex.bennee@linaro.org; helo=mail-lj1-x234.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 ---------