Re: [Qemu-devel] [PATCH v3 07/50] plugin: add user-facing API

["Alex Bennée" <alex.bennee@linaro.org>]

Pranith Kumar <pranith.foss@gmail.com> writes:

> On Fri, Jun 14, 2019 at 10:24 AM Alex Bennée <alex.bennee@linaro.org> wrote:
>>
>> From: "Emilio G. Cota" <cota@braap.org>
>>
>> Add the API first to ease review.
>>
>> Signed-off-by: Emilio G. Cota <cota@braap.org>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>
>> ---
>> v3
>>   - merge in changes to plugin install/reset/uninstall
>>   - split api file
>> ---
>>  include/qemu/qemu-plugin.h | 339 +++++++++++++++++++++++++++++++++++++
>>  1 file changed, 339 insertions(+)
>>  create mode 100644 include/qemu/qemu-plugin.h
>>
>> diff --git a/include/qemu/qemu-plugin.h b/include/qemu/qemu-plugin.h
>> new file mode 100644
>> index 0000000000..0db1ef9714
>> --- /dev/null
>> +++ b/include/qemu/qemu-plugin.h
>> @@ -0,0 +1,339 @@
>> +/*
>> + * Copyright (C) 2017, Emilio G. Cota <cota@braap.org>
>> + * Copyright (C) 2019, Linaro
>> + *
>> + * License: GNU GPL, version 2 or later.
>> + *   See the COPYING file in the top-level directory.
>> + *
>> + * SPDX-License-Identifier: GPL-2.0-or-later
>> + */
>> +#ifndef QEMU_PLUGIN_API_H
>> +#define QEMU_PLUGIN_API_H
>> +
>> +#include <inttypes.h>
>> +#include <stdbool.h>
>> +
>> +/*
>> + * For best performance, build the plugin with -fvisibility=hidden so that
>> + * QEMU_PLUGIN_LOCAL is implicit. Then, just mark qemu_plugin_install with
>> + * QEMU_PLUGIN_EXPORT. For more info, see
>> + *   https://gcc.gnu.org/wiki/Visibility
>> + */
>> +#if defined _WIN32 || defined __CYGWIN__
>> +  #ifdef BUILDING_DLL
>> +    #define QEMU_PLUGIN_EXPORT __declspec(dllexport)
>> +  #else
>> +    #define QEMU_PLUGIN_EXPORT __declspec(dllimport)
>> +  #endif
>> +  #define QEMU_PLUGIN_LOCAL
>> +#else
>> +  #if __GNUC__ >= 4
>> +    #define QEMU_PLUGIN_EXPORT __attribute__((visibility("default")))
>> +    #define QEMU_PLUGIN_LOCAL  __attribute__((visibility("hidden")))
>> +  #else
>> +    #define QEMU_PLUGIN_EXPORT
>> +    #define QEMU_PLUGIN_LOCAL
>> +  #endif
>> +#endif
>> +
>> +typedef uint64_t qemu_plugin_id_t;
>> +
>> +/**
>> + * qemu_plugin_install() - Install a plugin
>> + * @id: this plugin's opaque ID
>> + * @argc: number of arguments
>> + * @argv: array of arguments (@argc elements)
>> + *
>> + * All plugins must export this symbol.
>> + *
>> + * Note: Calling qemu_plugin_uninstall() from this function is a bug. To raise
>> + * an error during install, return !0.
>> + *
>> + * Note: @argv remains valid throughout the lifetime of the loaded plugin.
>> + */
>> +QEMU_PLUGIN_EXPORT int qemu_plugin_install(qemu_plugin_id_t id, int argc,
>> +                                           char **argv);
>> +
>> +/*
>> + * Prototypes for the various callback styles we will be registering
>> + * in the following functions.
>> + */
>> +typedef void (*qemu_plugin_simple_cb_t)(qemu_plugin_id_t id);
>> +
>> +typedef void (*qemu_plugin_udata_cb_t)(qemu_plugin_id_t id, void *userdata);
>> +
>> +typedef void (*qemu_plugin_vcpu_simple_cb_t)(qemu_plugin_id_t id,
>> +                                             unsigned int vcpu_index);
>> +
>> +typedef void (*qemu_plugin_vcpu_udata_cb_t)(unsigned int vcpu_index,
>> +                                            void *userdata);
>> +
>> +/**
>> + * qemu_plugin_uninstall() - Uninstall a plugin
>> + * @id: this plugin's opaque ID
>> + * @cb: callback to be called once the plugin has been removed
>> + *
>> + * Do NOT assume that the plugin has been uninstalled once this function
>> + * returns. Plugins are uninstalled asynchronously, and therefore the given
>> + * plugin receives callbacks until @cb is called.
>> + *
>> + * Note: Calling this function from qemu_plugin_install() is a bug.
>> + */
>> +void qemu_plugin_uninstall(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb);
>> +
>> +/**
>> + * qemu_plugin_reset() - Reset a plugin
>> + * @id: this plugin's opaque ID
>> + * @cb: callback to be called once the plugin has been reset
>> + *
>> + * Unregisters all callbacks for the plugin given by @id.
>> + *
>> + * Do NOT assume that the plugin has been reset once this function returns.
>> + * Plugins are reset asynchronously, and therefore the given plugin receives
>> + * callbacks until @cb is called.
>> + */
>> +void qemu_plugin_reset(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb);
>> +
>> +/**
>> + * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback
>> + * @id: plugin ID
>> + * @cb: callback function
>> + *
>> + * The @cb function is called every time a vCPU is initialized.
>> + *
>> + * See also: qemu_plugin_register_vcpu_exit_cb()
>> + */
>> +void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id,
>> +                                       qemu_plugin_vcpu_simple_cb_t cb);
>> +
>> +/**
>> + * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback
>> + * @id: plugin ID
>> + * @cb: callback function
>> + *
>> + * The @cb function is called every time a vCPU exits.
>> + *
>> + * See also: qemu_plugin_register_vcpu_init_cb()
>> + */
>> +void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id,
>> +                                       qemu_plugin_vcpu_simple_cb_t cb);
>> +
>> +/**
>> + * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback
>> + * @id: plugin ID
>> + * @cb: callback function
>> + *
>> + * The @cb function is called every time a vCPU idles.
>> + */
>> +void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id,
>> +                                       qemu_plugin_vcpu_simple_cb_t cb);
>> +
>> +/**
>> + * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback
>> + * @id: plugin ID
>> + * @cb: callback function
>> + *
>> + * The @cb function is called every time a vCPU resumes execution.
>> + */
>> +void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id,
>> +                                         qemu_plugin_vcpu_simple_cb_t cb);
>> +
>> +/*
>> + * Opaque types that the plugin is given during the translation and
>> + * instrumentation phase.
>> + */
>> +struct qemu_plugin_tb;
>> +struct qemu_plugin_insn;
>> +
>> +enum qemu_plugin_cb_flags {
>> +    QEMU_PLUGIN_CB_NO_REGS, /* callback does not access the CPU's regs */
>> +    QEMU_PLUGIN_CB_R_REGS,  /* callback reads the CPU's regs */
>> +    QEMU_PLUGIN_CB_RW_REGS, /* callback reads and writes the CPU's regs */
>> +};
>> +
>> +enum qemu_plugin_mem_rw {
>> +    QEMU_PLUGIN_MEM_R = 1,
>> +    QEMU_PLUGIN_MEM_W,
>> +    QEMU_PLUGIN_MEM_RW,
>> +};
>
> Why is this structure different from qemu_plugin_cb_flags? I think
> both of them could use a similar structure. Both of them can have
> (_NO, _R, _W, _RW) I think.

They do refer to semantically different things. The plugin CB flags are
important for ensuring registers are synced or not before the callback.
The memory callbacks flags control where the callbacks are placed with
respect to the access.

>
>> +
>> +/**
>> + * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb
>> + * @id: plugin ID
>> + * @cb: callback function
>> + *
>> + * The @cb function is called every time a translation occurs. The @cb
>> + * function is passed an opaque qemu_plugin_type which is can query
>
> s/is/it/

Fixed.

--
Alex Bennée