From patchwork Thu Feb 13 22:51:00 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: 183441 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1082371ile; Thu, 13 Feb 2020 14:57:26 -0800 (PST) X-Google-Smtp-Source: APXvYqzMZ8YN8Cov978J1BawAC66r6vgH5O3DxVeMXRjGRVTLIjTf3EbPNJ+kiTJX0poXJuDXv1b X-Received: by 2002:ad4:46ce:: with SMTP id g14mr13821322qvw.67.1581634646019; Thu, 13 Feb 2020 14:57:26 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581634646; cv=none; d=google.com; s=arc-20160816; b=J8cWPyK71S+vjw9RY+L5+ihacIUUj05vYzuBzJY3LXnhA/xd8Ti3CqtBWypAvBQefm 7ppB6XjH10maT7+Ra2lcAfzJUwFnWis0XljS5yXGhMgOZfm4cUK32mcJqtkNRPQDjUSe ycD/mjMgMDZkdn4hG9Z8khLyz25yovmYVIUJvPc9lw8oB8dhWRJNGBPW2+rEpLqXGcJt /6SeQdZa4qPWMibwIXEE/d99zlWCKX82JhVDIeXa+b4dEWlWTcUYEWvktBy58+EaplP2 kvRbZsrFrsZh5uEZWTgJaPlTg8hG1bNyI4S3oUcTBQzEoqSqlbDeEx4wHh0zc8n7q0LN 5TAw== 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=OUiUz4cDkqZfCBPe3sp/f/ku8PWnAZIMM6hxXI6u3MBeh4ikcyGtfgx3gRM0WaYqlm Oqb+8DziOCYU9LfyBAxJsxlISom/UhitpZHi58WDCtWkg2uuxV5zaId9zy3gQtVkkKnk 6juxdfJAJZwRt09YVzFvGLyedo8xXNlM1dUBu4Bs4YM4xnetw3OyQtv1kSxeWKHKpGCR wj3Xmo6juj3cSrMXbS1dgx7mMFW9+g7/EGRYDl7DQOKjNAbqI9uqnSghaje7gR58bp1T bRZSv8sPTVxKXfeJiNv6Ki6+2sdEQJZvjs/+AUSX5/zv/+FkBNd3dXYO1JXkrHlr7+Se uGdg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=su5TYmbT; 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 k25si1898051qkj.354.2020.02.13.14.57.25 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 13 Feb 2020 14:57:26 -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=su5TYmbT; 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]:60448 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j2NQD-0005oQ-Ig for patch@linaro.org; Thu, 13 Feb 2020 17:57:25 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:39943) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j2NKR-0004z0-3R for qemu-devel@nongnu.org; Thu, 13 Feb 2020 17:51:29 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j2NKP-0003yj-M7 for qemu-devel@nongnu.org; Thu, 13 Feb 2020 17:51:26 -0500 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:55730) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j2NKP-0003wz-G9 for qemu-devel@nongnu.org; Thu, 13 Feb 2020 17:51:25 -0500 Received: by mail-wm1-x344.google.com with SMTP id q9so8048988wmj.5 for ; Thu, 13 Feb 2020 14:51:25 -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=su5TYmbTV8EqVUvI5Rbzg++xTc3zln8HoL8+32e74qkFtxFme3rZfFMUwB/bqqArwH zeQxSZhMgsuIr17uoNkk/20cAJMM6CH5UnQ19MBBZmnDq0Lg3gL+fHJT+75eCJxeFwxO PIhowZcu76IyzM9NsrvaWdy8r27lcM3VBUgUMv3MTHiGHzyFbIyI9WvZjUwlpke7r5jj kWw26qdmvjevrml5wdm8ANmhvBQUNTSxUmuto9Ve7a2aKBMZUDAfUm8VFiKVhi+Tc6WX xdLZOBrFWT/WSC3NUM/8aoiCauYCbOd2v6Rb36iYPohrByQhXtHPFBMl4Bml/qCGlsTh kG0Q== 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=YQH13jI1GsuZPpmKfnem/Ie1yup1PT6ucVWNxRydMH7enAce/oT9drM3qAdbN5PTJc kno/RZaI1Njkt1vAk4U+F6hAQN/C0/LTzOWn0LNczg9ly01/lLir+jmWHcWholtzFQ52 Hm41oIyTtCgkZywS5mrRPsRKQoGdGrckuS2L05t47hPTUyI2jmb9EbP0KpvBtVUjxcb7 ROwA+TSn7Qx93nQJuEOLM0fmJrCubBvwxrtFH3fr4tJcAZiH8cOXxWRTSqbcNHhaUE/G buz81o+TfgmIcDIc/SadOuTH1++ZboiHSsXek50ZSf2zKTgbFw6AWAMY+bAz6n2IsgYb /mSg== X-Gm-Message-State: APjAAAVzUa36OO/SgxQD77HbHs63irtKrJf9oOSYhj1DfknF9pqmhH64 Lki2th2slAeOl8YXV5jlmkHjDg== X-Received: by 2002:a05:600c:2207:: with SMTP id z7mr322928wml.138.1581634284473; Thu, 13 Feb 2020 14:51:24 -0800 (PST) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id l132sm4922715wmf.16.2020.02.13.14.51.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Feb 2020 14:51:20 -0800 (PST) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 7FC8E1FF9A; Thu, 13 Feb 2020 22:51:10 +0000 (GMT) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Subject: [PATCH v2 10/19] docs/devel: document query handle lifetimes Date: Thu, 13 Feb 2020 22:51:00 +0000 Message-Id: <20200213225109.13120-11-alex.bennee@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200213225109.13120-1-alex.bennee@linaro.org> References: <20200213225109.13120-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::344 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 =====