From patchwork Tue Feb 27 14:43:34 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: 776260 Delivered-To: patch@linaro.org Received: by 2002:adf:a113:0:b0:33d:f458:43ce with SMTP id o19csp194400wro; Tue, 27 Feb 2024 06:54:06 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCU32jW2LZDJu+vW7RP+ExzjUWfh18sBRB1lu2mMPqR0lKVlNf+8vmPPKyfle8fa5zxqq6JizlQUFYasnv6tNKtv X-Google-Smtp-Source: AGHT+IEcTCh6OD+8qac6FtjSBLaNuj77n3NRgpkbI6E3vhQWm11X5fCdP1UNx1Xicw908gCwNW7n X-Received: by 2002:a81:9bd7:0:b0:608:c73e:cbaa with SMTP id s206-20020a819bd7000000b00608c73ecbaamr2242421ywg.6.1709045646480; Tue, 27 Feb 2024 06:54:06 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709045646; cv=none; d=google.com; s=arc-20160816; b=Hhz28SRvQwJjFkHL8KjCAdXep/a537gQb8XLXiTg+42O3SYKg0kgY0vSfqg8JdOflC ZyXayczTwRGZ3Oi072M+CWIDZQTxm8nVnx0hNwAkO/CljQcZVbaXtTx71tnIbHcggU2y 1B8W8Vi/repSt6o7trE7JlpThG54zqIJxftUHpU8GfTKFZIcrn7hXsoWGoeZnYO4Vtgj QLRGrCeu1eD5qfu6u0z8OaeGiWqx+Ki4ATWfdtlT0kayJn91bC1WaeL95ntzVPxsj9zH RLKTrreyguSxKGr2apCNAmfuaLXIX0KMO5UHdXzj2qtJBe/TgNHwFJUiqNg2t5DcfL/O 5IyQ== 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=42urZuEDMQCp17hh9k6/exkRQrnxeYXQehaPHkChZ3M=; b=a3mFHnVwj1leUW4/CVnBQe8gaykxLesY75CywypzQ5wrK6LUuJRC3MfDZLKz6yVQED ufWfc9KVngM+OcEUS65FQ7l6XihQp8rpDNtdFxGxpQf9aRwX+zk1ARrRw1TaWslz2eV3 x+ravojunoxC+aHlBWGQJYAdTJR444FgN+b2V6cKRuyc6j6yKvhRJZiEytmuMR2Yrqev ytF+iIAMvKXgk+D9CVA2EPg2TccDmMAwWBmUxZdskjgqUQdD2+Zuz0cfOLurQBbhLKiN 9QqHSZgCb6awJglzY2xIkblyu6oPLsK/I6MFSjaLrikluHCd7GzvdJ0t287xf3tICT0M 8wkQ==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=xqkX1NvW; 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 b4-20020ac85404000000b0042e626a8435si7439582qtq.743.2024.02.27.06.54.06 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Tue, 27 Feb 2024 06:54:06 -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=xqkX1NvW; 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 1reypT-0003km-7z; Tue, 27 Feb 2024 09:53:11 -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 1reypK-00030o-WB for qemu-devel@nongnu.org; Tue, 27 Feb 2024 09:53:03 -0500 Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1reypD-0004mo-4V for qemu-devel@nongnu.org; Tue, 27 Feb 2024 09:53:02 -0500 Received: by mail-wr1-x433.google.com with SMTP id ffacd0b85a97d-33aeb088324so2792013f8f.2 for ; Tue, 27 Feb 2024 06:52:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1709045571; x=1709650371; 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=xqkX1NvW/laAo0Kate1dR9vbLT6ho6Ye/MgFXKN5LXL1PRw2ndhPtG9r7T5dzJ6xbS 2FgurRRiTttgJTNsuinc0jDHYLG0zoux+A+usQPZQhii7IeTnkDdERXWLiUS7cM7QwLO 6e8B1ARbZBMNtCS4D/uNt3UUfCgnt5AYhBspraAlhWUX/+GQz6nrEfW8hC9ypJ4v95rj SJwKlvQcoodl7Cd06hnCnlVtUT+TE4UnMFlB86VRBYMZ5enTbHR2+m6B2u1r9teCF5Nm DKm0dTEtjE4UwkbIrtXzGG8+o+ZApgffYbgN17zC8hXlffQgQphQEIFLsOwe9hR4IG40 30sg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709045571; x=1709650371; 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=BLRsJ53WhutuIwhjyKFA6ioRVcp7bjp+N4sC0mX6iiAQabHFhdtdQDR6/24KBhXvD2 72iIquY3W1rDR3Czv+6vrtTEsRKiY3ixplwDr/7miMJTdUcz2P3IJWu3wGTYKeQj5r6V rrvmCZpKk3DfDRTANlsIXIHxNkfrY5L6xvwm7GxUlRU6Wm40XVqg/NqDYetJFYhsEBK6 rpmdHi+UOUbyZ6o5cmIIQr/+KrNEUUCmkXwUkVhlxGSvKOpsYpM8FW2SqCETucV72w+R /uGH/BvtdAF3Fue3M5Zf+1wbdKuH1BbWihZJ3pFw2l4n0TzcYViU1z8ADghTffThjQs1 X11Q== X-Gm-Message-State: AOJu0Yycd/9ox0JmBAzzOL3mVvgUsRpWW9LgyL5MyeTaMYYMqySG9C9Q ax7Cn5UPDQ0RuS60lF7W3kwXyvic6m9J9BIWWB1SgRZt0+F6IliF4yEamNtF6to= X-Received: by 2002:a5d:400c:0:b0:33b:26de:ea with SMTP id n12-20020a5d400c000000b0033b26de00eamr7173413wrp.37.1709045570784; Tue, 27 Feb 2024 06:52:50 -0800 (PST) Received: from draig.lan ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id a10-20020a5d4d4a000000b0033d13530134sm11454355wru.106.2024.02.27.06.52.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Feb 2024 06:52:50 -0800 (PST) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 280B55F92F; Tue, 27 Feb 2024 14:43:38 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: qemu-ppc@nongnu.org, Yoshinori Sato , qemu-arm@nongnu.org, Liu Zhiwei , Michael Rolnik , Yanan Wang , Eduardo Habkost , Wainer dos Santos Moschetta , Beraldo Leal , Cleber Rosa , David Hildenbrand , Paolo Bonzini , Peter Maydell , Song Gao , Daniel Henrique Barboza , Laurent Vivier , Warner Losh , =?utf-8?q?Alex_Benn=C3=A9e?= , Alexandre Iooss , Ilya Leoshkevich , =?utf-8?q?C=C3=A9dric_Le_Goater?= , qemu-s390x@nongnu.org, Kyle Evans , Brad Smith , Nicholas Piggin , "Edgar E. Iglesias" , Pierrick Bouvier , John Snow , Alistair Francis , Richard Henderson , Brian Cain , Thomas Huth , =?utf-8?q?P?= =?utf-8?q?hilippe_Mathieu-Daud=C3=A9?= , qemu-riscv@nongnu.org, Bin Meng , Daniel Henrique Barboza , Weiwei Li , Marcel Apfelbaum , Palmer Dabbelt , Mahmoud Mandour Subject: [PATCH v4 28/29] docs/devel: document some plugin assumptions Date: Tue, 27 Feb 2024 14:43:34 +0000 Message-Id: <20240227144335.1196131-29-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240227144335.1196131-1-alex.bennee@linaro.org> References: <20240227144335.1196131-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::433; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x433.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 ---------