Re: [RFC PATCH v3 01/11] plugins: add types for callbacks related to certain discontinuities

[Pierrick Bouvier <pierrick.bouvier@linaro.org>]

Hi Julian,

thanks for the update!
Comments below.

On 12/2/24 11:26, Julian Ganz wrote:
> The plugin API allows registration of callbacks for a variety of VCPU
> related events, such as VCPU reset, idle and resume. However, traps of
> any kind, i.e. interrupts or exceptions, were previously not covered.
> These kinds of events are arguably quite significant and usually go hand
> in hand with a PC discontinuity. On most platforms, the discontinuity
> also includes a transition from some "mode" to another. Thus, plugins
> for the analysis of (virtualized) embedded systems may benefit from or
> even require the possiblity to perform work on the occurance of an
> interrupt or exception.
> 
> This change introduces the concept of such a discontinuity event in the
> form of an enumeration. Currently only traps are covered. Specifically
> we (loosely) define interrupts, exceptions and host calls across all
> platforms. In addition, this change introduces a type to use for
> callback functions related to such events. Since possible modes and the
> enumeration of interupts and exceptions vary greatly between different
> architectures, the callback type only receives the VCPU id, the type of
> event as well as the old and new PC.
> ---
>   include/qemu/plugin.h      |  1 +
>   include/qemu/qemu-plugin.h | 43 ++++++++++++++++++++++++++++++++++++++
>   2 files changed, 44 insertions(+)
> 
> diff --git a/include/qemu/plugin.h b/include/qemu/plugin.h
> index 9726a9ebf3..27a176b631 100644
> --- a/include/qemu/plugin.h
> +++ b/include/qemu/plugin.h
> @@ -59,6 +59,7 @@ union qemu_plugin_cb_sig {
>       qemu_plugin_udata_cb_t           udata;
>       qemu_plugin_vcpu_simple_cb_t     vcpu_simple;
>       qemu_plugin_vcpu_udata_cb_t      vcpu_udata;
> +    qemu_plugin_vcpu_discon_cb_t     vcpu_discon;
>       qemu_plugin_vcpu_tb_trans_cb_t   vcpu_tb_trans;
>       qemu_plugin_vcpu_mem_cb_t        vcpu_mem;
>       qemu_plugin_vcpu_syscall_cb_t    vcpu_syscall;
> diff --git a/include/qemu/qemu-plugin.h b/include/qemu/qemu-plugin.h
> index 0fba36ae02..9c67374b7e 100644
> --- a/include/qemu/qemu-plugin.h
> +++ b/include/qemu/qemu-plugin.h
> @@ -154,6 +154,49 @@ typedef void (*qemu_plugin_vcpu_simple_cb_t)(qemu_plugin_id_t id,
>   typedef void (*qemu_plugin_vcpu_udata_cb_t)(unsigned int vcpu_index,
>                                               void *userdata);
>   
> +
> +/**
> + * enum qemu_plugin_discon_type - type of a (potential) PC discontinuity
> + *
> + * @QEMU_PLUGIN_DISCON_INTERRUPT: an interrupt, defined across all architectures
> + *                                as an asynchronous event, usually originating
> + *                                from outside the CPU
> + * @QEMU_PLUGIN_DISCON_EXCEPTION: an exception, defined across all architectures
> + *                                as a synchronous event in response to a
> + *                                specific instruction being executed
> + * @QEMU_PLUGIN_DISCON_HOSTCALL: a host call, functionally a special kind of
> + *                               exception that is not handled by code run by
> + *                               the vCPU but machinery outside the vCPU
> + * @QEMU_PLUGIN_DISCON_ALL: all types of disconinuity events currently covered
> + */
> +enum qemu_plugin_discon_type {
> +    QEMU_PLUGIN_DISCON_INTERRUPT = 1,
> +    QEMU_PLUGIN_DISCON_EXCEPTION = 2,
> +    QEMU_PLUGIN_DISCON_HOSTCALL = 4,
> +    QEMU_PLUGIN_DISCON_ALL = 7
> +};

Matter of style, but would be better to use:

enum qemu_plugin_discon_type {
      QEMU_PLUGIN_DISCON_INTERRUPT = 1 << 0,
      QEMU_PLUGIN_DISCON_EXCEPTION = 1 << 1,
      QEMU_PLUGIN_DISCON_HOSTCALL = 1 << 2,
      QEMU_PLUGIN_DISCON_ALL = -1
};

> +
> +/**
> + * typedef qemu_plugin_vcpu_discon_cb_t - vcpu discontinuity callback
> + * @vcpu_index: the current vcpu context
> + * @type: the type of discontinuity
> + * @from_pc: the source of the discontinuity, e.g. the PC before the
> + *           transition
> + * @to_pc: the PC pointing to the next instruction to be executed
> + *

Missing those parameters when building doc.
include/qemu/qemu-plugin.h:198: warning: Function parameter or member 
'id' not described in 'qemu_plugin_vcpu_discon_cb_t'
include/qemu/qemu-plugin.h:289: warning: Function parameter or member 
'type' not described in 'qemu_plugin_register_vcpu_discon_cb'
2 warnings as Errors

> + * The excact semantics of @from_pc depends on @the type of discontinuity. For
> + * interrupts, @from_pc will point to the next instruction which would have
> + * been executed. For exceptions and host calls, @from_pc will point to the
> + * instruction that caused the exception or issued the host call. Note that
> + * in the case of exceptions, the instruction is not retired and thus not
> + * observable via general instruction exec callbacks. The same may be the case
> + * for some host calls such as hypervisor call "exceptions".
> + */
> +typedef void (*qemu_plugin_vcpu_discon_cb_t)(qemu_plugin_id_t id,
> +                                             unsigned int vcpu_index,
> +                                             enum qemu_plugin_discon_type type,
> +                                             uint64_t from_pc, uint64_t to_pc);
> +
>   /**
>    * qemu_plugin_uninstall() - Uninstall a plugin
>    * @id: this plugin's opaque ID

Overall I'm ok with what it looks like.

However, it seems that your conclusion was we can't always guarantee to 
have from_pc, and I'm not sure that the solution to simply drop it is 
the right one.