From patchwork Mon Jan 22 14:56:10 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: 764658 Delivered-To: patch@linaro.org Received: by 2002:a05:6000:10c4:b0:337:62d3:c6d5 with SMTP id b4csp1144298wrx; Mon, 22 Jan 2024 07:03:46 -0800 (PST) X-Google-Smtp-Source: AGHT+IFzqzDYWZp2nDlUYSIZU9ELbBYJaxEYt+avqECdFSj3ft8sXuNwMB/QuGV6CywFszZoZW+T X-Received: by 2002:ac8:598f:0:b0:42a:2b87:f244 with SMTP id e15-20020ac8598f000000b0042a2b87f244mr6339469qte.126.1705935826178; Mon, 22 Jan 2024 07:03:46 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1705935826; cv=none; d=google.com; s=arc-20160816; b=Nt8YQD8re7qMpXCAXfhkludCee4AcILsZ3EIEtEdGKyMnqFK/NtgK/UUUcfn90aY/s 6E81ouduqDM1uTdWabhu4TR5INMFkTvHk5hF4w8uO3hxHxsw4yUCZUWt+RymGL3YkQeG 2buHHu9ql50D9m2OYZL5REL6JagJVFWqQ3UkS8St1P80RKnkOEZWL/JhNBNXjTyV2d5L sF23jQxynFzdD23Yg23SYS99XFMe6dB2NmT9W0VMkxMO0W537iZcZrKQxJRelLNaxmag W7YgqStrwDfuMHOZJ2FNDhv02XIyJVTs1LzstGS5rn9NyOEEl9qyL8MmTbLRQQNdTglv FKqA== 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=4hMzVm9ctQM0g8U90EfkWI4+Q0pZXCBWKBvUKLAxYNI=; b=JtuTMw9uadTvJLDiENcUqi7GxdpgrU+YdwDGIpOh3dmO9BIULzfFqg2xsz/qZxCWsN 36SI/nMZd+5o9A4lN3OZoaJC+2JiFY6xy5/eOTRO/HXQjGKMpljF4zbdhD9s/Eu2SBbz LuMnkEphxsMR7AsRs1hGJFRrNRJ7aRbLmPceY6ShPZuwJ52js0FZMIzURjFM2lu1eBwv R2JJObVrpZYQ8WD2Je9QJ08hW4pOWkM4rpZyB5xIKcKqH2d0mLFyCd3inW90qAAVqMrx RAl/mrCMchPM4m/0xTAVkBFS+p6/dOg+E2erkb+uOsBP4CgXWvCJXqQ6Lnf99arhqcA2 rc/A== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=Kpwh4oHN; 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 n10-20020a05622a11ca00b0042a43674994si1373138qtk.524.2024.01.22.07.03.45 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 22 Jan 2024 07:03:46 -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=Kpwh4oHN; 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 1rRvo6-0008PK-AB; Mon, 22 Jan 2024 10:01:50 -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 1rRvnx-0007t1-0y for qemu-devel@nongnu.org; Mon, 22 Jan 2024 10:01:44 -0500 Received: from mail-wm1-x332.google.com ([2a00:1450:4864:20::332]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rRvnn-0001mp-EK for qemu-devel@nongnu.org; Mon, 22 Jan 2024 10:01:40 -0500 Received: by mail-wm1-x332.google.com with SMTP id 5b1f17b1804b1-40eaf973eb4so7691795e9.0 for ; Mon, 22 Jan 2024 07:01:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1705935690; x=1706540490; 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=Kpwh4oHNASl9PIBuLCrEMV4LMj+0Pti7VhW5DD19pr+sKWjyF5w2pF3vzG6xmkQPDA +c1V6Sh6hLC4FKdsuGE93ouFHATtcHyM0nJWV23ew+7S0YrnyL24+U9XvazOLq6C5NW6 fzDwW3yfVHNStTXKkiT0ie5ATbrJ8Y3HJIS4S1NAfI/7tF2wogsOsiuAo96+Fd0dK43x wKZFDPOhldxjzHsibWlPCoAx9u1uCW6qxhQzSKYzS3h8td9Gt6Ok1ImFr5rf/HQqQ5U4 I1okAejqVaglzvg1IWuXyuz4OECrUwoXqtT9DqhoHDI8ReHuzX0DgIC6k2/0WuAGz6Ka PN1w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705935690; x=1706540490; 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=H0eeQaOMlL6Ij/aHJMUDePwgJa+LrESaTb0NlsTfXCH+YR6qr5aXtR5cZAKqAcgzO0 GHd3WFXGofsT4IyMrRj41tpVz9U4Ogz7ycWQdaA+Nlc9kPylopwykFn5eSgPB6rl/VqH H0qjd7cfGgpsaLoOKEckBGu+N2yC+ZMVu5fkzd0i8+rX9BXv0nmA6EVK5btcyixZ1B29 xCFnKilmB+UqI6wQqkPBQzG8QDJ5Mr/oR0k/WeTBK5k6fxBGsuI2XMiWTHIiRgcql1bx 7taGb1cZl3OhOEUpQqpqxTHXQEz+9reU/iw1pbHKj2uxsZ3dsDhRldMq4c1Dgw8I7Yri hcJQ== X-Gm-Message-State: AOJu0Yza8w0tnvJCjgQiS0kDlh4sHOb/C+EJqZr6tmhhc4Qx7igOViOi 7I7vMD5+U7S8M77K+w1dEbgsY4UxapoiWdu0MDPkzl5teCfQkOEVoOSJnmKhdjE= X-Received: by 2002:a05:600c:4f10:b0:40e:b0ec:e98c with SMTP id l16-20020a05600c4f1000b0040eb0ece98cmr456950wmq.139.1705935688372; Mon, 22 Jan 2024 07:01:28 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id t18-20020a05600c199200b0040e5951f199sm39123604wmq.34.2024.01.22.07.01.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 22 Jan 2024 07:01:27 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 3642F5F9D5; Mon, 22 Jan 2024 14:56:13 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Marcel Apfelbaum , "Edgar E. Iglesias" , =?utf-8?q?Philippe_Mathieu-?= =?utf-8?q?Daud=C3=A9?= , Michael Rolnik , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Laurent Vivier , kvm@vger.kernel.org, Yoshinori Sato , Pierrick Bouvier , Palmer Dabbelt , Liu Zhiwei , Laurent Vivier , Yanan Wang , qemu-ppc@nongnu.org, Weiwei Li , qemu-s390x@nongnu.org, =?utf-8?q?Alex_Benn=C3=A9e?= , =?utf-8?q?C=C3=A9dri?= =?utf-8?q?c_Le_Goater?= , Peter Maydell , Alexandre Iooss , John Snow , Mahmoud Mandour , Wainer dos Santos Moschetta , Richard Henderson , Ilya Leoshkevich , Alistair Francis , David Woodhouse , Cleber Rosa , Beraldo Leal , Bin Meng , Nicholas Piggin , Aurelien Jarno , Daniel Henrique Barboza , Daniel Henrique Barboza , Thomas Huth , David Hildenbrand , qemu-riscv@nongnu.org, qemu-arm@nongnu.org, Paolo Bonzini , Song Gao , Eduardo Habkost , Brian Cain , Paul Durrant Subject: [PATCH v3 21/21] docs/devel: document some plugin assumptions Date: Mon, 22 Jan 2024 14:56:10 +0000 Message-Id: <20240122145610.413836-22-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240122145610.413836-1-alex.bennee@linaro.org> References: <20240122145610.413836-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::332; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x332.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 ---------