From patchwork Tue Feb 25 12:47:01 2020 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: 183839 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1767623ile; Tue, 25 Feb 2020 05:42:29 -0800 (PST) X-Google-Smtp-Source: APXvYqwZjFkeiCmrp6spoY5UVZgDGCBPZn9JoJLTfiry/LUww/707e6ftp88nnoQUgwMu3Du/baA X-Received: by 2002:ad4:58ae:: with SMTP id ea14mr49100321qvb.247.1582638149498; Tue, 25 Feb 2020 05:42:29 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1582638149; cv=none; d=google.com; s=arc-20160816; b=zS9HMq+XwnWWDMU4YLWu4R9mtAtxKQATHprJY8RRosQ2fRoaC937tCXlB+eGeeMTa1 NDdrzYJVcRjH3oiL/jYVwsOZOnf+OA0vZZNRck3PzuVLkcdtRlH++lmECyPlCoV/RZ9Z WmopDqNgnUIvH2fp4VWjUmhHFDmh5yZv5XNxpR5SeK8CPMNvPFsjy4qX28taQbDpX/44 wbnczxIImAWcIGEAMYV8v2/xXBZNAP+PWW1CCA5i2vS+yqX59NuB5np0bGcpAIISjeya Ai3K4Q256PhNsHeGH/Exq/Y9l9M3yDFrK5wIiP0ZNY3PKyJ9lUg/E/iRQ466jKLEcfrd UuNQ== 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=4d2JrUPmJz37MvIYKDE4vOLfs/ja0Fe0BZeISYiAcVI=; b=NysxeF3aCxR3kvc7aLpI6nM0WzophIoAW+3TviYojH3wUDNlKr75OmmoChkh8OE9iG uobcQRSZQiXyLMYyzzAkqoVCkKevVXWs5fdMq96dWKgWGfRghO7C6b317v0uuUl4uler 3qE3RwWUyT76jL/kuPyVDD4/26vluVIA2iiRywaVc4ozK5a6MYDQuN8iYSAuBVYfBDuM GDcpLvQz+PPW0bv15TqFugSLHE/3Py/sJ6It4k9YWPrWsxhakn5kDvbRGQO4dJafQmL7 +VrF5D1Lj+i1O3KPOxki03UP+mc9DNnxpaV+MZ3mWV+JzT0vFWG19AeospSqnkLN+P8v 94wQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=eMi08feM; 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 x15si7172356qtj.91.2020.02.25.05.42.29 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 25 Feb 2020 05:42:29 -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=fail header.i=@linaro.org header.s=google header.b=eMi08feM; 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]:56276 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6aTl-00073b-37 for patch@linaro.org; Tue, 25 Feb 2020 08:42:29 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:59259) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6ZcY-0005bS-C0 for qemu-devel@nongnu.org; Tue, 25 Feb 2020 07:47:31 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6ZcW-0007H6-67 for qemu-devel@nongnu.org; Tue, 25 Feb 2020 07:47:29 -0500 Received: from mail-wm1-x343.google.com ([2a00:1450:4864:20::343]:54050) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6ZcV-0007GX-1U for qemu-devel@nongnu.org; Tue, 25 Feb 2020 07:47:27 -0500 Received: by mail-wm1-x343.google.com with SMTP id t79so1366696wmt.3 for ; Tue, 25 Feb 2020 04:47:26 -0800 (PST) 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=4d2JrUPmJz37MvIYKDE4vOLfs/ja0Fe0BZeISYiAcVI=; b=eMi08feMDeth2FqrHF+Dl21qn7NuBH3xvfxYDGp11sliJn4P91PYlp5bZhvTfWv/yy Z9Qog5qlf9Ewqmdl/JxGBhBGqEwnh2SwCWwQK586MMSDhnVzS8jhAlqgrrUbxfa84JBJ 8zSknaIh6BluoanrXGckIewg3KTDasBmdhaob8jYDnQeObylmuHkQEB4P3DzdzeZCE7S uTUAiXoVluYzGZYo8xEG6Avylyj04lsMy6DtdNdsIRlIuxURs3eSANIMgTox1Iv/XY1Y CheiRAkaMAsbH6BnHMoY0af4lyMEvOgSZIzH7Q96OXGJJuJTWi1DusZm1ul9KNkxmwQV E88w== 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=4d2JrUPmJz37MvIYKDE4vOLfs/ja0Fe0BZeISYiAcVI=; b=gZlgeopA93lIbbS91StA6yWLv/fr+sKB2ExbIvmizsfJpO2fv+CMSe8DEajoQ0Borl VKgzQE/K4lagyBNtKJYly3TSqzKJXd9Oh2ZNyV5UNAMku8toWluo9i/JEWNrIHHPor2r FYnjOpjO9L6HKJI23TsssbfzCBPsVzVn49tumi/0AQTGuuUi4Ld/RD7Z37sM/ZnIZhuC SGpV4aZfcS/kf0L1HIG2yAF8jj1N3sfPMTHhUVmiadnhY8P98NHjb8SzMXjn3Q5EzF/d sYOirWzxMH5kJb8UoNTiJvX411kkUykaHciJQPwOsnh7tpV5PFT2Hma5sYzd9JTqp0wb TIjw== X-Gm-Message-State: APjAAAX3tuddXaeXfdd9lG+iWtZ86K8E8nfzKLFnzHVviRdQ95cEwg7h RC70W5vyPt9z8cYjnYIcAs7/hg== X-Received: by 2002:a7b:ce18:: with SMTP id m24mr5214555wmc.123.1582634845862; Tue, 25 Feb 2020 04:47:25 -0800 (PST) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id s1sm23459047wro.66.2020.02.25.04.47.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 04:47:20 -0800 (PST) Received: from zen.home.arpa (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 2BB131FF9A; Tue, 25 Feb 2020 12:47:11 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Subject: [PATCH v3 10/19] docs/devel: document query handle lifetimes Date: Tue, 25 Feb 2020 12:47:01 +0000 Message-Id: <20200225124710.14152-11-alex.bennee@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225124710.14152-1-alex.bennee@linaro.org> References: <20200225124710.14152-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::343 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: fam@euphon.net, berrange@redhat.com, robert.foley@linaro.org, pbonzini@redhat.com, stefanb@linux.vnet.ibm.com, =?utf-8?q?Alex_Benn?= =?utf-8?b?w6ll?= , richard.henderson@linaro.org, f4bug@amsat.org, robhenry@microsoft.com, marcandre.lureau@redhat.com, aaron@os.amperecomputing.com, cota@braap.org, stefanha@redhat.com, kuhn.chenqun@huawei.com, peter.puhov@linaro.org, aurelien@aurel32.net Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" I forgot to document the lifetime of handles in the developer documentation. Do so now. Signed-off-by: Alex Bennée Reviewed-by: Robert Foley Reviewed-by: Robert Foley --- docs/devel/tcg-plugins.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) -- 2.20.1 diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index 718eef00f22..a05990906cc 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -51,8 +51,17 @@ 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. +exported *qemu_plugin* functions. + +Query Handle Lifetime +--------------------- + +Each callback provides an opaque anonymous information handle which +can usually be further queried to find out information about a +translation, instruction or operation. The handles themselves are only +valid during the lifetime of the callback so it is important that any +information that is needed is extracted during the callback and saved +by the plugin. Usage =====