qualcomm/qbox
Loading...
Searching...
No Matches
libqemu-plugin.h
1/*
2 * This file is part of libqbox
3 * Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: BSD-3-Clause-Clear
6 *
7 * Bridges QEMU's C plugin callbacks into the owning C++ plugin instance.
8 *
9 * Every QEMU plugin callback carries a `void* userdata`, which we set to the
10 * plugin's `PluginHandle*`. A subclass registers a capture-less lambda directly
11 * with the plugin API (passing `handle_as_userdata()`) and, inside the lambda,
12 * calls `dispatch_userdata()` to recover the `LibQemuPlugin*` and run its
13 * logic. Dispatch is a single path with zero lookup.
14 *
15 * The PluginHandle is heap-allocated and intentionally leaked at plugin
16 * destruction so that any callback QEMU still has registered finds
17 * `alive == false` and returns early instead of dereferencing a freed
18 * plugin object. Every dispatch bumps the same `m_handle->refcount`, which
19 * `shutdown_bridge` drains to serialize destruction with in-flight
20 * callbacks.
21 */
22
23#ifndef _LIBQBOX_COMPONENTS_LIBQEMU_PLUGIN_H
24#define _LIBQBOX_COMPONENTS_LIBQEMU_PLUGIN_H
25
26#include <systemc>
27
28#include <cciutils.h>
29#include <libqemu-cxx/libqemu-cxx.h>
30
31#include <scp/report.h>
32#include <cci_configuration>
33
34#include <atomic>
35#include <thread>
36
37constexpr double NSEC_IN_ONE_SEC = 1e9;
38
39class LibQemuPlugin;
40
49 LibQemuPlugin* self{ nullptr }; // valid while @c alive == true
50 std::atomic<bool> alive{ true }; // false once shutdown_bridge() returns
51 std::atomic<int> refcount{ 0 }; // in-flight bridge callbacks
52};
53
57class LibQemuPlugin : public sc_core::sc_module
58{
59 SCP_LOGGER();
60
61protected:
62 cci::cci_param<uint64_t> m_id; // unique plugin id
63 qemu::LibQemu& m_inst;
64
65 // Leaked at destruction so stale callbacks find @c alive==false.
66 PluginHandle* m_handle;
67
68public:
69 LibQemuPlugin(const sc_core::sc_module_name& nm, qemu::LibQemu& inst)
70 : sc_module(nm), m_inst(inst), m_id("id", 0, "qemu plugin id"), m_handle(new PluginHandle())
71 {
72 m_handle->self = this;
73 }
74
75 virtual ~LibQemuPlugin() { shutdown_bridge(); }
76
77 // Push the `-plugin <path>,key=<id>` argument to libqemu's command line.
78 // Called from the subclass after QemuInstance has finished pushing its
79 // own libqbox arguments.
80 void push_plugin_args(const std::string& plugin_path)
81 {
82 SCP_DEBUG(())("push_plugin_args, key: {} ", m_id.name());
83 SCP_DEBUG(())("push_plugin_args, plugin_path: {} ", plugin_path);
84 std::stringstream opts;
85 opts << plugin_path;
86 opts << ",key=" << m_id.name();
87 m_inst.push_qemu_arg("-plugin");
88 m_inst.push_qemu_arg(opts.str().c_str());
89 }
90
99 {
100 if (!m_handle->alive.exchange(false, std::memory_order_seq_cst)) {
101 return;
102 }
103 while (m_handle->refcount.load(std::memory_order_acquire) > 0) {
104 std::this_thread::yield();
105 }
106 }
107
108 // Pass this as @c userdata when registering any plugin callback.
109 void* handle_as_userdata() const { return m_handle; }
110
126 template <typename Body>
127 static void dispatch_userdata(void* userdata, Body body)
128 {
129 auto* h = static_cast<PluginHandle*>(userdata);
130 if (!h || !h->alive.load(std::memory_order_acquire)) return;
131 h->refcount.fetch_add(1, std::memory_order_seq_cst);
132 if (h->alive.load(std::memory_order_seq_cst)) {
133 body(h->self);
134 }
135 h->refcount.fetch_sub(1, std::memory_order_seq_cst);
136 }
137};
138
139#endif // _LIBQBOX_COMPONENTS_LIBQEMU_PLUGIN_H
Base class for QBox C++ plugins that bridge QEMU plugin callbacks.
Definition libqemu-plugin.h:58
static void dispatch_userdata(void *userdata, Body body)
Run body on the live plugin instance, holding a refcount for the duration. No-op when the handle is n...
Definition libqemu-plugin.h:127
void shutdown_bridge()
Stop bridge dispatch and drain in-flight callbacks.
Definition libqemu-plugin.h:98
Definition libqemu-cxx.h:95
Stable userdata passed to every plugin callback.
Definition libqemu-plugin.h:48