From patchwork Wed Jan 3 17:33:49 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: 759650 Delivered-To: patch@linaro.org Received: by 2002:a5d:67c6:0:b0:336:6142:bf13 with SMTP id n6csp6615803wrw; Wed, 3 Jan 2024 09:50:10 -0800 (PST) X-Google-Smtp-Source: AGHT+IE0oMXo1zCzcPmH8OOK9jVkr3IzGh1L23vrnjp155piTAJ0bpq1sD6RJWmD2PBjxV1T8FSX X-Received: by 2002:a05:622a:1c1:b0:428:34a7:4b89 with SMTP id t1-20020a05622a01c100b0042834a74b89mr2130666qtw.14.1704304210262; Wed, 03 Jan 2024 09:50:10 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1704304210; cv=none; d=google.com; s=arc-20160816; b=k0FqhOQBAJhzKIylKCg5++6QzQmQlDH/hpLSsIHE4/fZ4X6IOwbxEJdijONC4yj5UW eriHU0zaa4bVK+F9GUOG4af/z7fz9sRETTdkJMjBAPE0a/OHisXYKwUzsI0NOcA5MwGp Dvvmcn+EEzKpMkFNDYcY4ZV94MWxrntOID6HZ1QxTa8uNZimmTHyvV5l+qDedylWncAj /95zB50uJzDCZIzy8drZplLmN80vmMqCz/bUelljcEjIDv4aLcMsGraKPhjtudOz16c0 ygYIbz2D1QVvC2saHcLbZVqMCCHA+Sk1w34qs1oI0VVP/wqYi4GLBoIPUGnTKzF9RKz2 gRwQ== 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=6SqdFcQlAJfCo/zD79U6TVq3bxpUqFYpwmC4QorajEA=; fh=5s6F1VpUg/LkqHSyTlr7gneXArwgJkl0qAfGr3eFpAs=; b=Log3Og0lTJDldcDCHRIUnICuho5t51dU8PmqWK3OeLo+gkvTDCOYc9IUxwpS4mrRvC spM9NuXkB1D35+peoU3E+iYiaJARhkDr/NdsCcVteX2trLV2NadxYgqsHAKdSA74ZZD8 lHWpjrxLUvpyW0/4eLQp7/Bx34uDTHKV5zILqeWx6lJjHf95t0rnPHLxJSpdGRvDR8Rv vDDefIedEulghDuJzXFLBRXEkEG/vFmhZJt6h4TNVc6Hmy8LsM1CTqyhPSq8BTUWDbT+ RPE9J3eKUgsefFgUVXik8ojLYZAvzqSXbtGIDtUVqvSIIg/fkz4FRxWSneQ1vEWuJgUt RiBA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="M/XA8ZIV"; 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-20020a05622a049200b00423b49a1487si29490256qtx.670.2024.01.03.09.50.10 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 03 Jan 2024 09:50:10 -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="M/XA8ZIV"; 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 1rL5Mj-0000h8-CD; Wed, 03 Jan 2024 12:49:17 -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 1rL5Md-0000KM-QB for qemu-devel@nongnu.org; Wed, 03 Jan 2024 12:49:11 -0500 Received: from mail-wr1-x430.google.com ([2a00:1450:4864:20::430]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rL5Ma-0000IZ-6l for qemu-devel@nongnu.org; Wed, 03 Jan 2024 12:49:11 -0500 Received: by mail-wr1-x430.google.com with SMTP id ffacd0b85a97d-3373a30af67so3036290f8f.0 for ; Wed, 03 Jan 2024 09:49:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1704304146; x=1704908946; 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=6SqdFcQlAJfCo/zD79U6TVq3bxpUqFYpwmC4QorajEA=; b=M/XA8ZIVIl14/b5CEJdCIXEuiu9WWFr7yyJ7VejV+OwPyHgrqOPwxA1yHj5LZFP8U9 vanrbIrQhs1v43XvkERSpOMFFP/aCctmfSMSnrPdyTqhhiHFbNq3vw3o4zxFUW9CN3R/ XAuYWA8WzGjxFXoPKX4AvhkuD74AvrxSiNAxUeDIdTFErja0S2wMNCgg2IaQpibz7F04 quB1X5cQh0j0xk1P9kuito8bXIMTMByW16s+lXoE589hixjIY2489RaDg8n+gA6zOonj BAA07XX+RWqoUgyLleuSO+N8bJcx7R5iG9HLe885GxoxCDfvho/k0LphcmvleZxyTx5h gwxg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704304146; x=1704908946; 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=6SqdFcQlAJfCo/zD79U6TVq3bxpUqFYpwmC4QorajEA=; b=MrvhE3XXhwbGakqMVTdfJDTIYiOA+HBXb1IOQdBQrszS6GT1POr4ZqAn+I5I33Dtac sC6Q/CgZ3ULGpUHLNAcGedvin1MJzryqDIsFTebaW500pb+1ABSXgMrnofLMToWSTgXF uawK6sv7oB/TmxrPqSgAlHbpljqItk0+VZktvPWVhPijaVZTVdEGhpuRDQh+UE/iww5p OW1zubaXEqhs1FkZguRdSviYYtKySc6+goiDmxEMeKhMmy0WLIsR6F5J7vIoCQovOOkH Vk9bgsA4CTRqHssHg/AoA8c4y5IeftH6r6eA+nAwM95wa3jBnJPsjlvj6MCEJrnh0Eas Fynw== X-Gm-Message-State: AOJu0Ywg97ACiTpCJeOHNwrqYgxkJNNEieuGBa8UA+Pc79Jke2suJxZ+ 7N02nmz4pnltK59dzpFCrxo6hZLtKVeLQg== X-Received: by 2002:a5d:47ac:0:b0:337:4a09:b7d8 with SMTP id 12-20020a5d47ac000000b003374a09b7d8mr916886wrb.211.1704304146266; Wed, 03 Jan 2024 09:49:06 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id b15-20020a5d4b8f000000b00336a0c083easm26789106wrt.53.2024.01.03.09.49.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 03 Jan 2024 09:49:05 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id B41EC5F9D8; Wed, 3 Jan 2024 17:33:53 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: qemu-s390x@nongnu.org, qemu-ppc@nongnu.org, Richard Henderson , Song Gao , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , David Hildenbrand , Aurelien Jarno , Yoshinori Sato , Yanan Wang , Bin Meng , Laurent Vivier , Michael Rolnik , Alexandre Iooss , David Woodhouse , Laurent Vivier , Paolo Bonzini , Brian Cain , Daniel Henrique Barboza , Beraldo Leal , Paul Durrant , Mahmoud Mandour , Thomas Huth , Liu Zhiwei , Cleber Rosa , kvm@vger.kernel.org, Peter Maydell , Wainer dos Santos Moschetta , =?utf-8?q?Alex_Benn?= =?utf-8?q?=C3=A9e?= , qemu-arm@nongnu.org, Weiwei Li , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , John Snow , Daniel Henrique Barboza , Nicholas Piggin , Palmer Dabbelt , Marcel Apfelbaum , Ilya Leoshkevich , =?utf-8?q?C=C3=A9dric_Le_Goater?= , "Edgar E. Iglesias" , Eduardo Habkost , Pierrick Bouvier , qemu-riscv@nongnu.org, Alistair Francis Subject: [PATCH v2 43/43] docs/devel: document some plugin assumptions Date: Wed, 3 Jan 2024 17:33:49 +0000 Message-Id: <20240103173349.398526-44-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240103173349.398526-1-alex.bennee@linaro.org> References: <20240103173349.398526-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::430; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x430.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. Signed-off-by: Alex Bennée Reviewed-by: Pierrick Bouvier --- 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 ---------