From patchwork Tue Jan 16 10:48:09 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: 763021 Delivered-To: patch@linaro.org Received: by 2002:a5d:5903:0:b0:337:62d3:c6d5 with SMTP id v3csp1551183wrd; Tue, 16 Jan 2024 02:50:34 -0800 (PST) X-Google-Smtp-Source: AGHT+IHzg6fLHRfOpjcOq+Hknqsux3nunkWcMZAKiIBCdlU1goyC4KajBhfL/uEP3DCqrjNYlyk2 X-Received: by 2002:a05:6214:2523:b0:681:71a8:53bf with SMTP id gg3-20020a056214252300b0068171a853bfmr546568qvb.115.1705402234631; Tue, 16 Jan 2024 02:50:34 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1705402234; cv=none; d=google.com; s=arc-20160816; b=pceDegbv50llAaB899AvBiMPnJ1Ilev8+etisnkcLpsWR7UF1d6rcechX2FxnVq2OZ yRWMPrvnhjSr+TrlMzzQo7zcIpHcTQituL8R15Pi3FTV2X3geJcx5nIcDb2jUNb0PUT5 RTxyQlvJM6hInuDmllp1qWshrHLrUjbPeI2CNQb6kWkBzq/iugkn6MWuWYMq3Xo7U2fR KeAqo1HKGmwXlUvDDHLx7UA+G7GASfoxl+5G/ZsNuccVBoIkqWKpSNvvHJY9PowJc9X8 DqyZ581yE4Zdc+sgRGqMPhbcmP6/scBG0+rYiF1b6R9zKHY3vpLjIeUXmYprkdNnZmGV 71jg== 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=ayx9buhutuCRzyt+CbdSf6ZgOZM90Qy7hXRs4yl/VKY=; fh=J1mEt/br0T95fqv/QqsgNqYqKUXznBIGHik03n80zmI=; b=eTHT5FAmoHAY8Ae0pH1a66mFZmBvVpk/dyuNV9uv6qtCFBsYeL7Eeb4C+bWLfqd21n K5gyY45sdQ7wi2q++shtKJm3Gj00s6pr6sDCcpzDtDjhXvtLGzyUK5iG8y+1a9kboGoF JEaVD1FWQdTNqX6AmD6PWjtzmc6k6EKgYNgnuwIgqi6p12BGVvhoL6G2/YrGOu+LbdYi ROZ6+7WnrRzMjjIybd4mgf7cuzTFUSCeicNpKYcXl6x+HdncOOUrWyFx+T1GwIBsr52C G/zk5AERQCxZyk8qL1NIajzteMXeNnDpFFArZ+1TQcA9PUaoCvXcVcE8ue7Fbl7Vsxgb +rCA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=pn36d3dx; 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 v7-20020a0c9c07000000b0067f9c41923fsi9587581qve.115.2024.01.16.02.50.34 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Tue, 16 Jan 2024 02:50:34 -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=pn36d3dx; 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 1rPgzm-0002So-Vs; Tue, 16 Jan 2024 05:48:39 -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 1rPgzh-0002PT-J1 for qemu-devel@nongnu.org; Tue, 16 Jan 2024 05:48:33 -0500 Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rPgzb-0007H9-LH for qemu-devel@nongnu.org; Tue, 16 Jan 2024 05:48:33 -0500 Received: by mail-wr1-x429.google.com with SMTP id ffacd0b85a97d-3368b1e056eso8064044f8f.3 for ; Tue, 16 Jan 2024 02:48:27 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1705402106; x=1706006906; 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=ayx9buhutuCRzyt+CbdSf6ZgOZM90Qy7hXRs4yl/VKY=; b=pn36d3dx3yM+gMYSXFdISAojs/q/mypLKb2RwpmnjuI3Xcmsgs5Q1+z6GvKxgdyVUl M8dky1GHK1/d2lo8642P1kEph143o6bW2br/3dyu2dhybSd4artU4bsldyJi7vwAbGyR Q5xfetAAbXItMYKFpAbRHt+Vzaq/6kxVh+Si5tzIFO8fMjuBNeAA72MiVmR4+djKsdXp CjBBQvVrf13/6+/9LcwinBKPBgX7DIHnYqK1iCw81tx54r48Jw1iiL6sjHpooK7qdDHE c4P1H9+ECrfNTGOpsHeiBa5Hc4f3j/q3WLRG0BykMXvP0Z7lFWHvn1KtYlss/igSvkia oMmA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705402106; x=1706006906; 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=ayx9buhutuCRzyt+CbdSf6ZgOZM90Qy7hXRs4yl/VKY=; b=We6ndNE76IUwFopSJC8ldpXfrSePyWDy1W3A0CQoSZtuPkI/1EIYdipAn6HdY+IszX 2O5I3wulo+1aoMvfzstoMa84/yGeFLSosZoIeaaRqpNji1PznlBNmuTSSIpwBmmJbR9c dLRo9kg005T9HAn52TeBoECMFRP1eeDhZAtGjPC9zj09es1frbeED5SmUCFpOwJMmNU/ 3ezLKNoWpHhKrthtHcwUpwIllWUDvBPnJY7VqEBxqYA9tk+KvFkVBlxGwbQ9+/esNhj3 3iArBL+VE1cGMcN7dyk7lN7Jll5jhdiEQGWc6XxJVaUp0Q6EedeeScstUZIlTvtwwnSE Y5ug== X-Gm-Message-State: AOJu0Yx7OMYVKpkKf2QRAogMT2VyOollxink4KWZHDDbvxyxsqIFfsWn ym3B82S4CPclDE11aKX8iqKUfxSL5KLPALqAOfxLZGt8sI8= X-Received: by 2002:adf:e3c4:0:b0:336:8012:5ce with SMTP id k4-20020adfe3c4000000b00336801205cemr3644745wrm.95.1705402106063; Tue, 16 Jan 2024 02:48:26 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id bv27-20020a0560001f1b00b00337b0374a3dsm2373863wrb.57.2024.01.16.02.48.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Jan 2024 02:48:22 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 92D425F936; Tue, 16 Jan 2024 10:48:11 +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 22/22] docs/devel: document some plugin assumptions Date: Tue, 16 Jan 2024 10:48:09 +0000 Message-Id: <20240116104809.250076-23-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240116104809.250076-1-alex.bennee@linaro.org> References: <20240116104809.250076-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x429.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=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. Message-Id: <20240103173349.398526-44-alex.bennee@linaro.org> Reviewed-by: Pierrick Bouvier Signed-off-by: Alex Bennée 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 ---------