From patchwork Mon Feb 26 16:56:45 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: 775882 Delivered-To: patch@linaro.org Received: by 2002:a5d:6103:0:b0:33d:da16:65b6 with SMTP id v3csp431759wrt; Mon, 26 Feb 2024 09:00:13 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCXSXdNRv4z+Ik+mv6XNhKYQph0e+sxOX2l0YSwNS4nciW91bT5N7qUbwjzP4Jabj6nQQo1H1+Tf0szgVtwjwzjL X-Google-Smtp-Source: AGHT+IGV80f5xKh0M19GGvHfrquz60SOlJQtcRI3vV5XTORztcl81iiZfFQ3tTJOh5RB9OVQL75c X-Received: by 2002:a05:6808:1302:b0:3c0:3c06:afd1 with SMTP id y2-20020a056808130200b003c03c06afd1mr8080892oiv.48.1708966813109; Mon, 26 Feb 2024 09:00:13 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1708966813; cv=none; d=google.com; s=arc-20160816; b=lq0nf0CfNfFMpstlYUPRfKdgD1rHhqMt5Nny6iEvx0/KzR1P8yI5mTJ55TjXXbr6fC fAa2jZH6m8kFXZdGWNl/zgI9qQZTLnL8uTf/pBc9M7coqllTxFPlx6ytrg+/toxdnm70 C4iOj9AyJegqXOdmSiggRneJYhh/bqE7SFd6TIq27rYURF8sOYVKmrz1zt+9sitBq3g5 ksC8V83fln9vTYg1Swf2xJjiyMG3oV7Xl6/Wnrd69Opll+VeZuMVS/d3eriYbcgJBKxp qqfZc+wv1YsGsGOgbBcrIGSOPocBgSN3iUjtBigaEHdfKg+41znt23rN/Wy8gLgaoY31 1RCQ== 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=FlRWjczXzB3kjfNm0MZCBQ0e7zrqTwZz0mkKu1n+VQY=; b=yhldqBewPCy811kCZQRaFe3W8e5fr2t+5FP2GqXKbIhtiv4ZSWwyZlJwE2dF68BteL eOjhz/+1gos9HDk2Ia/U0GSBQB1xEO/DvgmiSteQd/AFnS0TWR2zD0riiBmhsPNDYcU8 ae+W0AoEwGw5Nuo+hLdMfcU5Tc6pK3tpD1bx29pYNsaqfSfv9gowIFIPnhW+VILXGUrc os3DfOo6po2dYv738+htjGceL/uE+YleMYpldJ/TfLwpfI5QPv4+Nc1bYZEo/yrTTrvv o82OiZAkSIsO7EDRhgbtf33r+MtK3R3fo+K4wx9/25ZhvZWJyWXkchY9+jMBABi5plyM gITA==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=b2+6ZavM; 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 gy3-20020a056214242300b0068ce33a4d9asi5592484qvb.423.2024.02.26.09.00.12 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 26 Feb 2024 09:00:13 -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=b2+6ZavM; 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 1reeIf-0006Ys-50; Mon, 26 Feb 2024 11:57:57 -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 1reeId-0006WN-Jm for qemu-devel@nongnu.org; Mon, 26 Feb 2024 11:57:55 -0500 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1reeHo-0007kR-7w for qemu-devel@nongnu.org; Mon, 26 Feb 2024 11:57:55 -0500 Received: by mail-wm1-x32d.google.com with SMTP id 5b1f17b1804b1-4129e8bc6c8so16441875e9.2 for ; Mon, 26 Feb 2024 08:57:03 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1708966623; x=1709571423; 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=b2+6ZavMUQq3O3pnfnYXz6m3ZIbvJNDzvbboUhHp1SwnmZMwKL6HznXsf115mThKgr q8eTFNdAw8APhMb9IFRkkk/myyX+sd8+WDJnYtAudrTPWI3Q++NHkmyPkr4tv7jCZM6v QviMcZ31vbzJUmy9aY/psSdToVBwgqDLUojeGGBimsFZgrAi+yKiJLd68rM4Q8Bdgzhw DrieY4xgMjwVpkC+DA6rFm3LyRMZE0HA+MFaSpyWXYamzYZcle5KXR2cYNynxZdGWgaI oNmDh1CiJDEip4DgiI/uk1E24I0x+btZ3rZhW3vtyNtpFglhfdPJI2agorhpklOX6KWy gzjw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1708966623; x=1709571423; 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=JaadSjcUm3APoS2Y8jCAnGqOHYON9tNlEp41/UJNeNNtLEObRgiUMsX9d088StDMUW mdJSF7bD74pHWg0pJoxdQm1xBqrnpA4qSbJfZhAUtPSvEkZDYDc3N/ymL8W1FICqQgDq HEhMQjlxBHgfDNjwFjZ/xQ6gBpWRiYuCx3CEl8mBEQs1POXqj6ALXI2dQMKDVsv0784j oC/M7cnPIGHI01+gPy2s6BiwgJaKf1DLk8s00RYWZd2DJ3mLdxU4kQY6R1MgIeIl+6Md Didva5fuNsY2bubSFpqER3mxdCjrojs2s5M5oTlZR0nkxsc9fpi5r2Nz6WhovLUjPpI7 Ew5w== X-Gm-Message-State: AOJu0YxdNAiUV0GdotPeLoi25vmuiQX07vQyE11GGi4DcKpFaLIRN4lL zy0L4BYW6HPH0xu2NaAdCkBoXY08mstrcsKS7us/pM2yUNYqlq3VkAVtnNWSodc= X-Received: by 2002:a05:600c:4fcb:b0:412:78c8:b31e with SMTP id o11-20020a05600c4fcb00b0041278c8b31emr6351713wmq.2.1708966622896; Mon, 26 Feb 2024 08:57:02 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id t8-20020a05600c198800b00412a218a68fsm5870758wmq.31.2024.02.26.08.56.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 26 Feb 2024 08:56:58 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 381D65F933; Mon, 26 Feb 2024 16:56:49 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Nicholas Piggin , Liu Zhiwei , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Peter Maydell , =?utf-8?q?Alex_Benn=C3=A9e?= , qemu-riscv@nongnu.org, Michael Rolnik , Song Gao , Alexandre Iooss , Marcel Apfelbaum , David Hildenbrand , Pierrick Bouvier , John Snow , Eduardo Habkost , Mahmoud Mandour , qemu-arm@nongnu.org, =?utf-8?q?Phi?= =?utf-8?q?lippe_Mathieu-Daud=C3=A9?= , Paolo Bonzini , Cleber Rosa , qemu-ppc@nongnu.org, Richard Henderson , qemu-s390x@nongnu.org, Daniel Henrique Barboza , Thomas Huth , Yoshinori Sato , Yanan Wang , Brian Cain , Ilya Leoshkevich , Weiwei Li , "Edgar E. Iglesias" , Bin Meng , Laurent Vivier , Palmer Dabbelt , Daniel Henrique Barboza , Alistair Francis Subject: [PATCH v3 26/27] docs/devel: document some plugin assumptions Date: Mon, 26 Feb 2024 16:56:45 +0000 Message-Id: <20240226165646.425600-27-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240226165646.425600-1-alex.bennee@linaro.org> References: <20240226165646.425600-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32d; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32d.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 ---------