1 /* 2 * Copyright (C) 2017, Emilio G. Cota <cota@braap.org> 3 * Copyright (C) 2019, Linaro 4 * 5 * License: GNU GPL, version 2 or later. 6 * See the COPYING file in the top-level directory. 7 * 8 * SPDX-License-Identifier: GPL-2.0-or-later 9 */ 10 #ifndef QEMU_PLUGIN_API_H 11 #define QEMU_PLUGIN_API_H 12 13 #include <inttypes.h> 14 #include <stdbool.h> 15 #include <stddef.h> 16 17 /* 18 * For best performance, build the plugin with -fvisibility=hidden so that 19 * QEMU_PLUGIN_LOCAL is implicit. Then, just mark qemu_plugin_install with 20 * QEMU_PLUGIN_EXPORT. For more info, see 21 * https://gcc.gnu.org/wiki/Visibility 22 */ 23 #if defined _WIN32 || defined __CYGWIN__ 24 #ifdef BUILDING_DLL 25 #define QEMU_PLUGIN_EXPORT __declspec(dllexport) 26 #else 27 #define QEMU_PLUGIN_EXPORT __declspec(dllimport) 28 #endif 29 #define QEMU_PLUGIN_LOCAL 30 #else 31 #define QEMU_PLUGIN_EXPORT __attribute__((visibility("default"))) 32 #define QEMU_PLUGIN_LOCAL __attribute__((visibility("hidden"))) 33 #endif 34 35 typedef uint64_t qemu_plugin_id_t; 36 37 /* 38 * Versioning plugins: 39 * 40 * The plugin API will pass a minimum and current API version that 41 * QEMU currently supports. The minimum API will be incremented if an 42 * API needs to be deprecated. 43 * 44 * The plugins export the API they were built against by exposing the 45 * symbol qemu_plugin_version which can be checked. 46 */ 47 48 extern QEMU_PLUGIN_EXPORT int qemu_plugin_version; 49 50 #define QEMU_PLUGIN_VERSION 0 51 52 typedef struct { 53 /* string describing architecture */ 54 const char *target_name; 55 struct { 56 int min; 57 int cur; 58 } version; 59 /* is this a full system emulation? */ 60 bool system_emulation; 61 union { 62 /* 63 * smp_vcpus may change if vCPUs can be hot-plugged, max_vcpus 64 * is the system-wide limit. 65 */ 66 struct { 67 int smp_vcpus; 68 int max_vcpus; 69 } system; 70 }; 71 } qemu_info_t; 72 73 /** 74 * qemu_plugin_install() - Install a plugin 75 * @id: this plugin's opaque ID 76 * @info: a block describing some details about the guest 77 * @argc: number of arguments 78 * @argv: array of arguments (@argc elements) 79 * 80 * All plugins must export this symbol. 81 * 82 * Note: Calling qemu_plugin_uninstall() from this function is a bug. To raise 83 * an error during install, return !0. 84 * 85 * Note: @info is only live during the call. Copy any information we 86 * want to keep. 87 * 88 * Note: @argv remains valid throughout the lifetime of the loaded plugin. 89 */ 90 QEMU_PLUGIN_EXPORT int qemu_plugin_install(qemu_plugin_id_t id, 91 const qemu_info_t *info, 92 int argc, char **argv); 93 94 /* 95 * Prototypes for the various callback styles we will be registering 96 * in the following functions. 97 */ 98 typedef void (*qemu_plugin_simple_cb_t)(qemu_plugin_id_t id); 99 100 typedef void (*qemu_plugin_udata_cb_t)(qemu_plugin_id_t id, void *userdata); 101 102 typedef void (*qemu_plugin_vcpu_simple_cb_t)(qemu_plugin_id_t id, 103 unsigned int vcpu_index); 104 105 typedef void (*qemu_plugin_vcpu_udata_cb_t)(unsigned int vcpu_index, 106 void *userdata); 107 108 /** 109 * qemu_plugin_uninstall() - Uninstall a plugin 110 * @id: this plugin's opaque ID 111 * @cb: callback to be called once the plugin has been removed 112 * 113 * Do NOT assume that the plugin has been uninstalled once this function 114 * returns. Plugins are uninstalled asynchronously, and therefore the given 115 * plugin receives callbacks until @cb is called. 116 * 117 * Note: Calling this function from qemu_plugin_install() is a bug. 118 */ 119 void qemu_plugin_uninstall(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb); 120 121 /** 122 * qemu_plugin_reset() - Reset a plugin 123 * @id: this plugin's opaque ID 124 * @cb: callback to be called once the plugin has been reset 125 * 126 * Unregisters all callbacks for the plugin given by @id. 127 * 128 * Do NOT assume that the plugin has been reset once this function returns. 129 * Plugins are reset asynchronously, and therefore the given plugin receives 130 * callbacks until @cb is called. 131 */ 132 void qemu_plugin_reset(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb); 133 134 /** 135 * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback 136 * @id: plugin ID 137 * @cb: callback function 138 * 139 * The @cb function is called every time a vCPU is initialized. 140 * 141 * See also: qemu_plugin_register_vcpu_exit_cb() 142 */ 143 void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id, 144 qemu_plugin_vcpu_simple_cb_t cb); 145 146 /** 147 * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback 148 * @id: plugin ID 149 * @cb: callback function 150 * 151 * The @cb function is called every time a vCPU exits. 152 * 153 * See also: qemu_plugin_register_vcpu_init_cb() 154 */ 155 void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id, 156 qemu_plugin_vcpu_simple_cb_t cb); 157 158 /** 159 * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback 160 * @id: plugin ID 161 * @cb: callback function 162 * 163 * The @cb function is called every time a vCPU idles. 164 */ 165 void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id, 166 qemu_plugin_vcpu_simple_cb_t cb); 167 168 /** 169 * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback 170 * @id: plugin ID 171 * @cb: callback function 172 * 173 * The @cb function is called every time a vCPU resumes execution. 174 */ 175 void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id, 176 qemu_plugin_vcpu_simple_cb_t cb); 177 178 /* 179 * Opaque types that the plugin is given during the translation and 180 * instrumentation phase. 181 */ 182 struct qemu_plugin_tb; 183 struct qemu_plugin_insn; 184 185 enum qemu_plugin_cb_flags { 186 QEMU_PLUGIN_CB_NO_REGS, /* callback does not access the CPU's regs */ 187 QEMU_PLUGIN_CB_R_REGS, /* callback reads the CPU's regs */ 188 QEMU_PLUGIN_CB_RW_REGS, /* callback reads and writes the CPU's regs */ 189 }; 190 191 enum qemu_plugin_mem_rw { 192 QEMU_PLUGIN_MEM_R = 1, 193 QEMU_PLUGIN_MEM_W, 194 QEMU_PLUGIN_MEM_RW, 195 }; 196 197 /** 198 * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb 199 * @id: plugin ID 200 * @cb: callback function 201 * 202 * The @cb function is called every time a translation occurs. The @cb 203 * function is passed an opaque qemu_plugin_type which it can query 204 * for additional information including the list of translated 205 * instructions. At this point the plugin can register further 206 * callbacks to be triggered when the block or individual instruction 207 * executes. 208 */ 209 typedef void (*qemu_plugin_vcpu_tb_trans_cb_t)(qemu_plugin_id_t id, 210 struct qemu_plugin_tb *tb); 211 212 void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id, 213 qemu_plugin_vcpu_tb_trans_cb_t cb); 214 215 /** 216 * qemu_plugin_register_vcpu_tb_trans_exec_cb() - register execution callback 217 * @tb: the opaque qemu_plugin_tb handle for the translation 218 * @cb: callback function 219 * @flags: does the plugin read or write the CPU's registers? 220 * @userdata: any plugin data to pass to the @cb? 221 * 222 * The @cb function is called every time a translated unit executes. 223 */ 224 void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb *tb, 225 qemu_plugin_vcpu_udata_cb_t cb, 226 enum qemu_plugin_cb_flags flags, 227 void *userdata); 228 229 enum qemu_plugin_op { 230 QEMU_PLUGIN_INLINE_ADD_U64, 231 }; 232 233 /** 234 * qemu_plugin_register_vcpu_tb_trans_exec_inline() - execution inline op 235 * @tb: the opaque qemu_plugin_tb handle for the translation 236 * @op: the type of qemu_plugin_op (e.g. ADD_U64) 237 * @ptr: the target memory location for the op 238 * @imm: the op data (e.g. 1) 239 * 240 * Insert an inline op to every time a translated unit executes. 241 * Useful if you just want to increment a single counter somewhere in 242 * memory. 243 */ 244 void qemu_plugin_register_vcpu_tb_exec_inline(struct qemu_plugin_tb *tb, 245 enum qemu_plugin_op op, 246 void *ptr, uint64_t imm); 247 248 /** 249 * qemu_plugin_register_vcpu_insn_exec_cb() - register insn execution cb 250 * @insn: the opaque qemu_plugin_insn handle for an instruction 251 * @cb: callback function 252 * @flags: does the plugin read or write the CPU's registers? 253 * @userdata: any plugin data to pass to the @cb? 254 * 255 * The @cb function is called every time an instruction is executed 256 */ 257 void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn *insn, 258 qemu_plugin_vcpu_udata_cb_t cb, 259 enum qemu_plugin_cb_flags flags, 260 void *userdata); 261 262 /** 263 * qemu_plugin_register_vcpu_insn_exec_inline() - insn execution inline op 264 * @insn: the opaque qemu_plugin_insn handle for an instruction 265 * @cb: callback function 266 * @op: the type of qemu_plugin_op (e.g. ADD_U64) 267 * @ptr: the target memory location for the op 268 * @imm: the op data (e.g. 1) 269 * 270 * Insert an inline op to every time an instruction executes. Useful 271 * if you just want to increment a single counter somewhere in memory. 272 */ 273 void qemu_plugin_register_vcpu_insn_exec_inline(struct qemu_plugin_insn *insn, 274 enum qemu_plugin_op op, 275 void *ptr, uint64_t imm); 276 277 /* 278 * Helpers to query information about the instructions in a block 279 */ 280 size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb *tb); 281 282 uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb *tb); 283 284 struct qemu_plugin_insn * 285 qemu_plugin_tb_get_insn(const struct qemu_plugin_tb *tb, size_t idx); 286 287 const void *qemu_plugin_insn_data(const struct qemu_plugin_insn *insn); 288 289 size_t qemu_plugin_insn_size(const struct qemu_plugin_insn *insn); 290 291 uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn *insn); 292 void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn *insn); 293 294 /* 295 * Memory Instrumentation 296 * 297 * The anonymous qemu_plugin_meminfo_t and qemu_plugin_hwaddr types 298 * can be used in queries to QEMU to get more information about a 299 * given memory access. 300 */ 301 typedef uint32_t qemu_plugin_meminfo_t; 302 struct qemu_plugin_hwaddr; 303 304 /* meminfo queries */ 305 unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info); 306 bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info); 307 bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info); 308 bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info); 309 310 /* 311 * qemu_plugin_get_hwaddr(): 312 * @vaddr: the virtual address of the memory operation 313 * 314 * For system emulation returns a qemu_plugin_hwaddr handle to query 315 * details about the actual physical address backing the virtual 316 * address. For linux-user guests it just returns NULL. 317 * 318 * This handle is *only* valid for the duration of the callback. Any 319 * information about the handle should be recovered before the 320 * callback returns. 321 */ 322 struct qemu_plugin_hwaddr *qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info, 323 uint64_t vaddr); 324 325 /* 326 * The following additional queries can be run on the hwaddr structure 327 * to return information about it. For non-IO accesses the device 328 * offset will be into the appropriate block of RAM. 329 */ 330 bool qemu_plugin_hwaddr_is_io(const struct qemu_plugin_hwaddr *haddr); 331 uint64_t qemu_plugin_hwaddr_device_offset(const struct qemu_plugin_hwaddr *haddr); 332 333 /* 334 * Returns a string representing the device. The string is valid for 335 * the lifetime of the plugin. 336 */ 337 const char *qemu_plugin_hwaddr_device_name(const struct qemu_plugin_hwaddr *h); 338 339 typedef void 340 (*qemu_plugin_vcpu_mem_cb_t)(unsigned int vcpu_index, 341 qemu_plugin_meminfo_t info, uint64_t vaddr, 342 void *userdata); 343 344 void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn *insn, 345 qemu_plugin_vcpu_mem_cb_t cb, 346 enum qemu_plugin_cb_flags flags, 347 enum qemu_plugin_mem_rw rw, 348 void *userdata); 349 350 void qemu_plugin_register_vcpu_mem_inline(struct qemu_plugin_insn *insn, 351 enum qemu_plugin_mem_rw rw, 352 enum qemu_plugin_op op, void *ptr, 353 uint64_t imm); 354 355 356 357 typedef void 358 (*qemu_plugin_vcpu_syscall_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_index, 359 int64_t num, uint64_t a1, uint64_t a2, 360 uint64_t a3, uint64_t a4, uint64_t a5, 361 uint64_t a6, uint64_t a7, uint64_t a8); 362 363 void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id, 364 qemu_plugin_vcpu_syscall_cb_t cb); 365 366 typedef void 367 (*qemu_plugin_vcpu_syscall_ret_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_idx, 368 int64_t num, int64_t ret); 369 370 void 371 qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id, 372 qemu_plugin_vcpu_syscall_ret_cb_t cb); 373 374 375 /** 376 * qemu_plugin_insn_disas() - return disassembly string for instruction 377 * @insn: instruction reference 378 * 379 * Returns an allocated string containing the disassembly 380 */ 381 382 char *qemu_plugin_insn_disas(const struct qemu_plugin_insn *insn); 383 384 /** 385 * qemu_plugin_vcpu_for_each() - iterate over the existing vCPU 386 * @id: plugin ID 387 * @cb: callback function 388 * 389 * The @cb function is called once for each existing vCPU. 390 * 391 * See also: qemu_plugin_register_vcpu_init_cb() 392 */ 393 void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id, 394 qemu_plugin_vcpu_simple_cb_t cb); 395 396 void qemu_plugin_register_flush_cb(qemu_plugin_id_t id, 397 qemu_plugin_simple_cb_t cb); 398 399 void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id, 400 qemu_plugin_udata_cb_t cb, void *userdata); 401 402 /* returns -1 in user-mode */ 403 int qemu_plugin_n_vcpus(void); 404 405 /* returns -1 in user-mode */ 406 int qemu_plugin_n_max_vcpus(void); 407 408 /** 409 * qemu_plugin_outs() - output string via QEMU's logging system 410 * @string: a string 411 */ 412 void qemu_plugin_outs(const char *string); 413 414 #endif /* QEMU_PLUGIN_API_H */ 415