From patchwork Thu Oct 17 13:15:26 2019 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: 176606 Delivered-To: patch@linaro.org Received: by 2002:a92:7e96:0:0:0:0:0 with SMTP id q22csp922461ill; Thu, 17 Oct 2019 06:24:34 -0700 (PDT) X-Google-Smtp-Source: APXvYqwGNFZRVarl6fIxl8PsnLYtI4fzP/q6B7FhF1mt+tQ38sALqnXSL3Xb32b50Er7htPkZVoe X-Received: by 2002:ac8:72d4:: with SMTP id o20mr3797435qtp.366.1571318674425; Thu, 17 Oct 2019 06:24:34 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1571318674; cv=none; d=google.com; s=arc-20160816; b=jJTRW3EUv2uQEvztm7wrFOE3Ykx+3NMV7LZxRUUv92gAQauEE9UzxwJhcaZ0amiScK W2FvDz9PjCuivqLpZqhggmXRUPur6K7Vy9H8omnpOfoBn22sJZT7BTvi+aIW1hB222yJ a/VvWa/3IJWgM4KVTd+VhQd6GZlb8uOwfys2QyowW3DhDAr8UGRMKCNnt7uT9kBKBmNK 4f6+TZ0zR00+fjLRPgcZaoEhp2VyiL3mogwKYMqTr8tlk0SmUKDcCnnNrEDox7zJZcO9 cYMqykT+dvVuSyxErgnSB/SBMGFS5MWPwPl07tZx+2/ez6p/H5+omc+Ra4p9eV4vpXj3 Tk7A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc: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:to:from :dkim-signature; bh=Yb3UF5h0z67h7aWNI1Qg9AnW+g8R23U+pnxlZeqlysw=; b=PpIshHFLTGwEjHqf7SVWRmKF+B79qXhz6YDgYCo/3s1Pe7Ar8QTlXyz07LDbaQbwZ6 p+zB5LdEpA3P1lD8Uu/MmSkg7RXE7A1hqQ29xCm+kmjCKspY0hkvrJQSbLU2NTeV4q+v i53G8nZ5QQ2WaoYG4YbhZYthPIRctpolnRZRgqIF5DZFVVmuJOCWecr4I9/1nSHyu5K+ O7MK458AKj9lUa6Hbj0Rkchf9QSXTg2Rpy2tYOd+sYqESUyFmwuZ+MQ1d+h7k7dfdCdc 6R0w1F4FeZuzIqzbM+HFP3G2xMYg4tLhHNqdLFLoJ5WpwSiH1StwFNP4kKWEm/0dJ1kA md0Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=UZXsKnWt; 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=fail (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 i24si2091834qkh.127.2019.10.17.06.24.34 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 17 Oct 2019 06:24:34 -0700 (PDT) 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=fail header.i=@linaro.org header.s=google header.b=UZXsKnWt; 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=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1]:47388 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iL5lZ-0000SB-Eg for patch@linaro.org; Thu, 17 Oct 2019 09:24:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:33896) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iL5dg-000810-BO for qemu-devel@nongnu.org; Thu, 17 Oct 2019 09:16:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iL5de-0005PN-Qr for qemu-devel@nongnu.org; Thu, 17 Oct 2019 09:16:24 -0400 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:44362) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iL5de-0005NW-JO for qemu-devel@nongnu.org; Thu, 17 Oct 2019 09:16:22 -0400 Received: by mail-wr1-x436.google.com with SMTP id z9so2295602wrl.11 for ; Thu, 17 Oct 2019 06:16:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Yb3UF5h0z67h7aWNI1Qg9AnW+g8R23U+pnxlZeqlysw=; b=UZXsKnWtcnkNTzA1iCHj+upMFdVXTtiZOC2PSNjGo8I5no2Z2JLdRnGek9wlxkUWsg MMxhFXe0cVNy2I0tN8hQnAgB29MNGWaWXJUKVgLpF/GnmHQ2d96RkJPYymJXA+B+yL26 uLG6aZJwgZ34TQz9fBEoG+2aVxwLBRa4VrgGhXQogjgZKg5xJhse5wT0bS+eK5zbah98 Isbra3+hjm/pK+n4NNKoEYes5ptttifIMgeFW1b3ru/EagW4DXcQNFRD1XT2kcXdkmSl jxSRMwOxhahETAnMB/QZ7KSDlAFwZERgvvvmRscnzCqHBONKVvp5ECwtCHUOqKPVD74M KYpw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Yb3UF5h0z67h7aWNI1Qg9AnW+g8R23U+pnxlZeqlysw=; b=HcDV5NhJuS8OZAXz13+dXL+ZtuGkTJNxGKY5EHlQOA94s8vDGPFOqVPgRU4Ci126fH R2GVQNwfIcvP2XXaSOa9t8uRYf0IctRxSz01OYmiK6y0jYX5j8vOjQfcoLDDRGwHarle BC4G63xZGDW73ZOTN6MG4OEIW5yq/Q4tEvsFGGbNjS341Ljd+9TklaN7TRLlzP4w5whJ dBkO4YkUDUoG4ZbEK7CvA2Go1eVZXTGv/tSUTtq4V9fIe+T460t7fss0LQ3RHOMJeJyf ECbmMc13/rza5Fo3L4IJECvFNppMr1w1bbM0hfKEfD6oXr+oYJfU7ucggoIrZMbvBsjX M40Q== X-Gm-Message-State: APjAAAUIkX5iWPbLb22q9T6nHQaRULXYHZDj6uWJPJzhx68UefN4e5aZ q3b+DR+MQ4lFWrVimZtXpet5Vg== X-Received: by 2002:a5d:4302:: with SMTP id h2mr3152122wrq.35.1571318181295; Thu, 17 Oct 2019 06:16:21 -0700 (PDT) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id f3sm2016346wrq.53.2019.10.17.06.16.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Oct 2019 06:16:18 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 45C371FF92; Thu, 17 Oct 2019 14:16:16 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Subject: [PATCH v6 05/54] docs/devel: add plugins.rst design document Date: Thu, 17 Oct 2019 14:15:26 +0100 Message-Id: <20191017131615.19660-6-alex.bennee@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20191017131615.19660-1-alex.bennee@linaro.org> References: <20191017131615.19660-1-alex.bennee@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::436 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: robert.foley@futurewei.com, Richard Henderson , peter.puhov@futurewei.com, aaron@os.amperecomputing.com, cota@braap.org, =?utf-8?q?Alex_Benn?= =?utf-8?b?w6ll?= Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" This is mostly extracted from Emilio's more verbose commit comments with some additional verbiage from me. Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson --- v4 - some rewording and tweaks - made non-atomicity of inline ops more explicit - expanded description of plugin unload v5 - more explicit statements: - cannot modify system state, only observer - call to action to upstream plugins --- docs/devel/index.rst | 1 + docs/devel/plugins.rst | 112 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 docs/devel/plugins.rst -- 2.20.1 diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 1ec61fcfed..2ff058bae3 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -22,3 +22,4 @@ Contents: decodetree secure-coding-practices tcg + plugins diff --git a/docs/devel/plugins.rst b/docs/devel/plugins.rst new file mode 100644 index 0000000000..b18fb6729e --- /dev/null +++ b/docs/devel/plugins.rst @@ -0,0 +1,112 @@ +.. + Copyright (C) 2017, Emilio G. Cota + Copyright (c) 2019, Linaro Limited + Written by Emilio Cota and Alex Bennée + +================ +QEMU TCG Plugins +================ + +QEMU TCG plugins provide a way for users to run experiments taking +advantage of the total system control emulation can have over a guest. +It provides a mechanism for plugins to subscribe to events during +translation and execution and optionally callback into the plugin +during these events. TCG plugins are unable to change the system state +only monitor it passively. However they can do this down to an +individual instruction granularity including potentially subscribing +to all load and store operations. + +API Stability +============= + +This is a new feature for QEMU and it does allow people to develop +out-of-tree plugins that can be dynamically linked into a running QEMU +process. However the project reserves the right to change or break the +API should it need to do so. The best way to avoid this is to submit +your plugin upstream so they can be updated if/when the API changes. + + +Exposure of QEMU internals +-------------------------- + +The plugin architecture actively avoids leaking implementation details +about how QEMU's translation works to the plugins. While there are +conceptions such as translation time and translation blocks the +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. The types used to describe +instructions and events are opaque to the plugins themselves. + +Usage +===== + +The QEMU binary needs to be compiled for plugin support: + +:: + configure --enable-plugins + +Once built a program can be run with multiple plugins loaded each with +their own arguments: + +:: + $QEMU $OTHER_QEMU_ARGS \ + -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \ + -plugin tests/plugin/libhotblocks.so + +Arguments are plugin specific and can be used to modify their +behaviour. In this case the howvec plugin is being asked to use inline +ops to count and break down the hint instructions by type. + +Plugin Life cycle +================= + +First the plugin is loaded and the public qemu_plugin_install function +is called. The plugin will then register callbacks for various plugin +events. Generally plugins will register a handler for the *atexit* +if they want to dump a summary of collected information once the +program/system has finished running. + +When a registered event occurs the plugin callback is invoked. The +callbacks may provide additional information. In the case of a +translation event the plugin has an option to enumerate the +instructions in a block of instructions and optionally register +callbacks to some or all instructions when they are executed. + +There is also a facility to add an inline event where code to +increment a counter can be directly inlined with the translation. +Currently only a simple increment is supported. This is not atomic so +can miss counts. If you want absolute precision you should use a +callback which can then ensure atomicity itself. + +Finally when QEMU exits all the registered *atexit* callbacks are +invoked. + +Internals +========= + +Locking +------- + +We have to ensure we cannot deadlock, particularly under MTTCG. For +this we acquire a lock when called from plugin code. We also keep the +list of callbacks under RCU so that we do not have to hold the lock +when calling the callbacks. This is also for performance, since some +callbacks (e.g. memory access callbacks) might be called very +frequently. + + * A consequence of this is that we keep our own list of CPUs, so that + we do not have to worry about locking order wrt cpu_list_lock. + * Use a recursive lock, since we can get registration calls from + callbacks. + +As a result registering/unregistering callbacks is "slow", since it +takes a lock. But this is very infrequent; we want performance when +calling (or not calling) callbacks, not when registering them. Using +RCU is great for this. + +We support the uninstallation of a plugin at any time (e.g. from +plugin callbacks). This allows plugins to remove themselves if they no +longer want to instrument the code. This operation is asynchronous +which means callbacks may still occur after the uninstall operation is +requested. The plugin isn't completely uninstalled until the safe work +has executed while all vCPUs are quiescent.