From nobody Tue Nov 5 07:52:06 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=mit.edu ARC-Seal: i=1; a=rsa-sha256; t=1670967713; cv=none; d=zohomail.com; s=zohoarc; b=X3xqaMwUySMl4RgORMwfIaXwCRZRNM2+nLbqMfqQXYbaoj4SHtnYE19pFKCiWPpSuVEvDdYQuPLVVnIx5e45XX9RJCS8eWVncmPTOAN+xeW1f/+J9GAJ/C+0l27hhPbVFzHGOKfZ564mSQ8sFK7JmXeAk3tiKeIr/q5o2UNNwYg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1670967713; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=qhmHsNmAxlc9cgZSHsaFvxxQAkUFKHHtR2wF32S33cU=; b=RT5mBW9e4/iX94gkI0CD4SHRLhziB0nOxAGYeKhfbuA6qCnLw0OllcknfSrdH5dvbmRakiA84J0WscEgXqEZ5wiBczy8M7EdAYwpI95fGmLgU6rU5Xhnx7wV85rN3RRIGfjcI1BrEK4M6FI71KzlJT/9DSR06tleFD2vqpWa32k= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1670967713928442.90026639166615; Tue, 13 Dec 2022 13:41:53 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1p5Czl-0000Nt-En; Tue, 13 Dec 2022 16:39:25 -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 1p5Cza-0000I5-6b for qemu-devel@nongnu.org; Tue, 13 Dec 2022 16:39:14 -0500 Received: from outgoing-auth-1.mit.edu ([18.9.28.11] helo=outgoing.mit.edu) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1p5CzX-0007fj-JD for qemu-devel@nongnu.org; Tue, 13 Dec 2022 16:39:13 -0500 Received: from panda194.. ([18.4.85.108]) (authenticated bits=0) (User authenticated as fasano@ATHENA.MIT.EDU) by outgoing.mit.edu (8.14.7/8.12.4) with ESMTP id 2BDLcaP8030603 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 13 Dec 2022 16:39:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mit.edu; s=outgoing; t=1670967543; bh=qhmHsNmAxlc9cgZSHsaFvxxQAkUFKHHtR2wF32S33cU=; h=From:To:Cc:Subject:Date:In-Reply-To:References; b=LJuy556R0K7ZVisHDE4AFZ1HpKCxWhDfhINd5ytr/I4D19jqTldCyYO/oJJPs1Dne jRfaZ0bFTRuafpF/dGMFmxSRMCW4gbbTHdKz9RY2JlCjBLlKJQ7WKagjJ1ULIBGrBx VgBoB1pT2G3h8JRTdWf6CQFEQwQVzqAvMPxwAKZen29JzvFgYsUwEJSIDDgi9SqY0r kxxPYEey8AQHomPFdJlaez9TQ8lSZVLUi4WMwxsay5ZFu1+mPTMWlNYlgABV5oKFq+ X90GiSNgu7z3ACeG/1BLXRQ/h7uHvU7a7a+z22IXRWicNBYjpJXM1wePoCu6vIQOKO c6ae/kv0K94fQ== From: Andrew Fasano To: qemu-devel@nongnu.org Cc: elysia.witham@ll.mit.edu, alex.bennee@linaro.org, erdnaxe@crans.org, ma.mandourr@gmail.com, Andrew Fasano Subject: [PATCH 1/8] docs/devel: describe QPP API Date: Tue, 13 Dec 2022 16:37:50 -0500 Message-Id: <20221213213757.4123265-2-fasano@mit.edu> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221213213757.4123265-1-fasano@mit.edu> References: <20221213213757.4123265-1-fasano@mit.edu> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=18.9.28.11; envelope-from=fasano@mit.edu; helo=outgoing.mit.edu X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @mit.edu) X-ZM-MESSAGEID: 1670967714565100001 Content-Type: text/plain; charset="utf-8" From: Elysia Witham The new QPP API allows plugin-to-plugin interaction for creating and using callbacks as well as importing and exporting functions. The new test plugins qpp_srv and qpp_client demonstrate how plugins use the new API. Signed-off-by: Elysia Witham Signed-off-by: Andrew Fasano Reviewed-by: Alex Benn=C3=A9e --- docs/devel/tcg-plugins.rst | 91 +++++++++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index 9740a70406..70ac09b96b 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -281,6 +281,14 @@ run:: 160 1 0 135 1 0 =20 +- tests/plugins/qpp_srv.c & tests/plugins/qpp_client.c + +These plugins demonstrate QPP interactions. The qpp_srv plugin defines +a few exported functions and its own callback which are then imported and +used by the qpp_client plugin. The qpp_client plugin registers its own +function to run on qpp_srv's defined callback. The tests for these plugins +are modified as both plugins must be loaded in order to work. + - contrib/plugins/hotblocks.c =20 The hotblocks plugin allows you to examine the where hot paths of @@ -573,6 +581,88 @@ The plugin has a number of arguments, all of them are = optional: configuration arguments implies ``l2=3Don``. (default: N =3D 2097152 (2MB), B =3D 64, A =3D 16) =20 +Plugin-to-Plugin Interactions +----------------------------- + +Plugins may interact with other plugins through the QEMU Plugin-to-Plugin +("QPP") API by including ```` in addition to ````. +This API supports direct function calls between plugins. An inter-plugin +callback system is supported within the core code as long as +``qemu_plugin_version >=3D 2``. + +Plugin names +~~~~~~~~~~~~ +Plugin names must be exported as ``qemu_plugin_name`` to use the QPP API i= n the same way +``qemu_plugin_version`` is exported. This name can then be used by other p= lugins +to import functions and use callbacks belonging to that plugin. + +Plugin dependencies +~~~~~~~~~~~~~~~~~~~ +For a plugin to use another plugin's functions or callbacks it must declar= e that +dependency through exporting ``qemu_plugin_uses`` which is a string array = containing +names of plugins used by that plugin. Those plugins must be loaded first. = Note that this +array must be null terminated, e.g. ``{plugin_a, NULL}``. + +QPP function calls +~~~~~~~~~~~~~~~~~~ +When a plugin (e.g., ``plugin_a``) wishes to make some of its functions (e= .g., +``func_1``) available to other plugins, it must: + +1. Mark the function definition with the ``QEMU_PLUGIN_EXPORT`` macro. For +example : ``QEMU_PLUGIN_EXPORT int func_1(int x) {...}`` +2. Provide prototypes for exported functions in a header file using the ma= cro +``QPP_FUN_PROTOTYPE`` with arguments of the plugin's name, the function's +return type, the function's name, and any arguments the function takes. For +example: ``QPP_FUN_PROTOTYPE(my_plugin, int, do_add, int);``. +3. Import this header from the plugin. + +When other plugins wish to use the functions exported by ``plugin_a``, they +must: + +1. Import the header file with the function prototype(s). +2. Call the function when desired by combining the target plugin name, an + underscore, and the target function name with ``_qpp`` on the end, + e.g., ``plugin_a_func_1_qpp()``. + +QPP callbacks +~~~~~~~~~~~~~ + +The QPP API also allows a plugin to define callback events and for other p= lugins +to request to be notified whenever these events happens. The plugin that d= efines +the callback is responsible for triggering the callback when it so wishes.= Other +plugins that wish to be notified on these events must define a function of= an +appropriate type and register it to run on this event. +In particular, these plugins must: + + +When a plugin (e.g., ``plugin_a``) wishes to define a callback (an event t= hat +other plugins can request to be notified about), it must: + +1. Define the callback using the ``qemu_plugin_create_callback`` function = which + takes two arguments: the unique ``qemu_plugin_id_t id`` and the callbac= k name. +2. Call ``qemu_plugin_run_callback`` at appropriate places in the code to = call registered + callback functions. It takes four arguments: the unique ``qemu_plugin_i= d_t id``, + the callback name, and the callback arguments which are standardized to= be + ``gpointer evdata, gpointer udata``. The callback arguments point to tw= o structs + which are defined by the plugin and can vary based on the use case of t= he callback. + +When other plugins wish to register a function to run on such an event, th= ey +must: + +1. Define a function that matches the ``cb_func_t`` type: + ``typedef void (*cb_func_t) (gpointer evdata, gpointer udata)``. +2. Register this function to be run on the plugin defined callback using + ``qemu_plugin_reg_callback``. This function takes three arguments: the = name of the + plugin which defines the callback, the callback name, and a ``cb_func_t= `` function + pointer. + +When other plugins wish to unregister a function which is registered to ru= n on a plugin +defined event callback, they must: + +1. Call ``qemu_plugin_unreg_callback``. This function takes the same argum= ents as + ``qemu_plugin_reg_callback``. It will return true if it successfully fi= nds and + unregisters the function. + API --- =20 @@ -581,4 +671,3 @@ The following API is generated from the inline document= ation in include the full kernel-doc annotations. =20 .. kernel-doc:: include/qemu/qemu-plugin.h - --=20 2.34.1