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 11 #ifndef QEMU_QEMU_PLUGIN_H 12 #define QEMU_QEMU_PLUGIN_H 13 14 #include <glib.h> 15 #include <inttypes.h> 16 #include <stdbool.h> 17 #include <stddef.h> 18 19 /* 20 * For best performance, build the plugin with -fvisibility=hidden so that 21 * QEMU_PLUGIN_LOCAL is implicit. Then, just mark qemu_plugin_install with 22 * QEMU_PLUGIN_EXPORT. For more info, see 23 * https://gcc.gnu.org/wiki/Visibility 24 */ 25 #if defined _WIN32 || defined __CYGWIN__ 26 #ifdef CONFIG_PLUGIN 27 #define QEMU_PLUGIN_EXPORT __declspec(dllimport) 28 #define QEMU_PLUGIN_API __declspec(dllexport) 29 #else 30 #define QEMU_PLUGIN_EXPORT __declspec(dllexport) 31 #define QEMU_PLUGIN_API __declspec(dllimport) 32 #endif 33 #define QEMU_PLUGIN_LOCAL 34 #else 35 #define QEMU_PLUGIN_EXPORT __attribute__((visibility("default"))) 36 #define QEMU_PLUGIN_LOCAL __attribute__((visibility("hidden"))) 37 #define QEMU_PLUGIN_API 38 #endif 39 40 /** 41 * typedef qemu_plugin_id_t - Unique plugin ID 42 */ 43 typedef uint64_t qemu_plugin_id_t; 44 45 /* 46 * Versioning plugins: 47 * 48 * The plugin API will pass a minimum and current API version that 49 * QEMU currently supports. The minimum API will be incremented if an 50 * API needs to be deprecated. 51 * 52 * The plugins export the API they were built against by exposing the 53 * symbol qemu_plugin_version which can be checked. 54 * 55 * version 2: removed qemu_plugin_n_vcpus and qemu_plugin_n_max_vcpus 56 */ 57 58 extern QEMU_PLUGIN_EXPORT int qemu_plugin_version; 59 60 #define QEMU_PLUGIN_VERSION 2 61 62 /** 63 * struct qemu_info_t - system information for plugins 64 * 65 * This structure provides for some limited information about the 66 * system to allow the plugin to make decisions on how to proceed. For 67 * example it might only be suitable for running on some guest 68 * architectures or when under full system emulation. 69 */ 70 typedef struct qemu_info_t { 71 /** @target_name: string describing architecture */ 72 const char *target_name; 73 /** @version: minimum and current plugin API level */ 74 struct { 75 int min; 76 int cur; 77 } version; 78 /** @system_emulation: is this a full system emulation? */ 79 bool system_emulation; 80 union { 81 /** @system: information relevant to system emulation */ 82 struct { 83 /** @system.smp_vcpus: initial number of vCPUs */ 84 int smp_vcpus; 85 /** @system.max_vcpus: maximum possible number of vCPUs */ 86 int max_vcpus; 87 } system; 88 }; 89 } qemu_info_t; 90 91 /** 92 * qemu_plugin_install() - Install a plugin 93 * @id: this plugin's opaque ID 94 * @info: a block describing some details about the guest 95 * @argc: number of arguments 96 * @argv: array of arguments (@argc elements) 97 * 98 * All plugins must export this symbol which is called when the plugin 99 * is first loaded. Calling qemu_plugin_uninstall() from this function 100 * is a bug. 101 * 102 * Note: @info is only live during the call. Copy any information we 103 * want to keep. @argv remains valid throughout the lifetime of the 104 * loaded plugin. 105 * 106 * Return: 0 on successful loading, !0 for an error. 107 */ 108 QEMU_PLUGIN_EXPORT int qemu_plugin_install(qemu_plugin_id_t id, 109 const qemu_info_t *info, 110 int argc, char **argv); 111 112 /** 113 * typedef qemu_plugin_simple_cb_t - simple callback 114 * @id: the unique qemu_plugin_id_t 115 * 116 * This callback passes no information aside from the unique @id. 117 */ 118 typedef void (*qemu_plugin_simple_cb_t)(qemu_plugin_id_t id); 119 120 /** 121 * typedef qemu_plugin_udata_cb_t - callback with user data 122 * @id: the unique qemu_plugin_id_t 123 * @userdata: a pointer to some user data supplied when the callback 124 * was registered. 125 */ 126 typedef void (*qemu_plugin_udata_cb_t)(qemu_plugin_id_t id, void *userdata); 127 128 /** 129 * typedef qemu_plugin_vcpu_simple_cb_t - vcpu callback 130 * @id: the unique qemu_plugin_id_t 131 * @vcpu_index: the current vcpu context 132 */ 133 typedef void (*qemu_plugin_vcpu_simple_cb_t)(qemu_plugin_id_t id, 134 unsigned int vcpu_index); 135 136 /** 137 * typedef qemu_plugin_vcpu_udata_cb_t - vcpu callback 138 * @vcpu_index: the current vcpu context 139 * @userdata: a pointer to some user data supplied when the callback 140 * was registered. 141 */ 142 typedef void (*qemu_plugin_vcpu_udata_cb_t)(unsigned int vcpu_index, 143 void *userdata); 144 145 /** 146 * qemu_plugin_uninstall() - Uninstall a plugin 147 * @id: this plugin's opaque ID 148 * @cb: callback to be called once the plugin has been removed 149 * 150 * Do NOT assume that the plugin has been uninstalled once this function 151 * returns. Plugins are uninstalled asynchronously, and therefore the given 152 * plugin receives callbacks until @cb is called. 153 * 154 * Note: Calling this function from qemu_plugin_install() is a bug. 155 */ 156 QEMU_PLUGIN_API 157 void qemu_plugin_uninstall(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb); 158 159 /** 160 * qemu_plugin_reset() - Reset a plugin 161 * @id: this plugin's opaque ID 162 * @cb: callback to be called once the plugin has been reset 163 * 164 * Unregisters all callbacks for the plugin given by @id. 165 * 166 * Do NOT assume that the plugin has been reset once this function returns. 167 * Plugins are reset asynchronously, and therefore the given plugin receives 168 * callbacks until @cb is called. 169 */ 170 QEMU_PLUGIN_API 171 void qemu_plugin_reset(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb); 172 173 /** 174 * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback 175 * @id: plugin ID 176 * @cb: callback function 177 * 178 * The @cb function is called every time a vCPU is initialized. 179 * 180 * See also: qemu_plugin_register_vcpu_exit_cb() 181 */ 182 QEMU_PLUGIN_API 183 void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id, 184 qemu_plugin_vcpu_simple_cb_t cb); 185 186 /** 187 * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback 188 * @id: plugin ID 189 * @cb: callback function 190 * 191 * The @cb function is called every time a vCPU exits. 192 * 193 * See also: qemu_plugin_register_vcpu_init_cb() 194 */ 195 QEMU_PLUGIN_API 196 void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id, 197 qemu_plugin_vcpu_simple_cb_t cb); 198 199 /** 200 * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback 201 * @id: plugin ID 202 * @cb: callback function 203 * 204 * The @cb function is called every time a vCPU idles. 205 */ 206 QEMU_PLUGIN_API 207 void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id, 208 qemu_plugin_vcpu_simple_cb_t cb); 209 210 /** 211 * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback 212 * @id: plugin ID 213 * @cb: callback function 214 * 215 * The @cb function is called every time a vCPU resumes execution. 216 */ 217 QEMU_PLUGIN_API 218 void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id, 219 qemu_plugin_vcpu_simple_cb_t cb); 220 221 /** struct qemu_plugin_tb - Opaque handle for a translation block */ 222 struct qemu_plugin_tb; 223 /** struct qemu_plugin_insn - Opaque handle for a translated instruction */ 224 struct qemu_plugin_insn; 225 226 /** 227 * enum qemu_plugin_cb_flags - type of callback 228 * 229 * @QEMU_PLUGIN_CB_NO_REGS: callback does not access the CPU's regs 230 * @QEMU_PLUGIN_CB_R_REGS: callback reads the CPU's regs 231 * @QEMU_PLUGIN_CB_RW_REGS: callback reads and writes the CPU's regs 232 * 233 * Note: currently QEMU_PLUGIN_CB_RW_REGS is unused, plugins cannot change 234 * system register state. 235 */ 236 enum qemu_plugin_cb_flags { 237 QEMU_PLUGIN_CB_NO_REGS, 238 QEMU_PLUGIN_CB_R_REGS, 239 QEMU_PLUGIN_CB_RW_REGS, 240 }; 241 242 enum qemu_plugin_mem_rw { 243 QEMU_PLUGIN_MEM_R = 1, 244 QEMU_PLUGIN_MEM_W, 245 QEMU_PLUGIN_MEM_RW, 246 }; 247 248 /** 249 * typedef qemu_plugin_vcpu_tb_trans_cb_t - translation callback 250 * @id: unique plugin id 251 * @tb: opaque handle used for querying and instrumenting a block. 252 */ 253 typedef void (*qemu_plugin_vcpu_tb_trans_cb_t)(qemu_plugin_id_t id, 254 struct qemu_plugin_tb *tb); 255 256 /** 257 * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb 258 * @id: plugin ID 259 * @cb: callback function 260 * 261 * The @cb function is called every time a translation occurs. The @cb 262 * function is passed an opaque qemu_plugin_type which it can query 263 * for additional information including the list of translated 264 * instructions. At this point the plugin can register further 265 * callbacks to be triggered when the block or individual instruction 266 * executes. 267 */ 268 QEMU_PLUGIN_API 269 void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id, 270 qemu_plugin_vcpu_tb_trans_cb_t cb); 271 272 /** 273 * qemu_plugin_register_vcpu_tb_exec_cb() - register execution callback 274 * @tb: the opaque qemu_plugin_tb handle for the translation 275 * @cb: callback function 276 * @flags: does the plugin read or write the CPU's registers? 277 * @userdata: any plugin data to pass to the @cb? 278 * 279 * The @cb function is called every time a translated unit executes. 280 */ 281 QEMU_PLUGIN_API 282 void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb *tb, 283 qemu_plugin_vcpu_udata_cb_t cb, 284 enum qemu_plugin_cb_flags flags, 285 void *userdata); 286 287 /** 288 * enum qemu_plugin_op - describes an inline op 289 * 290 * @QEMU_PLUGIN_INLINE_ADD_U64: add an immediate value uint64_t 291 * 292 * Note: currently only a single inline op is supported. 293 */ 294 295 enum qemu_plugin_op { 296 QEMU_PLUGIN_INLINE_ADD_U64, 297 }; 298 299 /** 300 * qemu_plugin_register_vcpu_tb_exec_inline() - execution inline op 301 * @tb: the opaque qemu_plugin_tb handle for the translation 302 * @op: the type of qemu_plugin_op (e.g. ADD_U64) 303 * @ptr: the target memory location for the op 304 * @imm: the op data (e.g. 1) 305 * 306 * Insert an inline op to every time a translated unit executes. 307 * Useful if you just want to increment a single counter somewhere in 308 * memory. 309 * 310 * Note: ops are not atomic so in multi-threaded/multi-smp situations 311 * you will get inexact results. 312 */ 313 QEMU_PLUGIN_API 314 void qemu_plugin_register_vcpu_tb_exec_inline(struct qemu_plugin_tb *tb, 315 enum qemu_plugin_op op, 316 void *ptr, uint64_t imm); 317 318 /** 319 * qemu_plugin_register_vcpu_insn_exec_cb() - register insn execution cb 320 * @insn: the opaque qemu_plugin_insn handle for an instruction 321 * @cb: callback function 322 * @flags: does the plugin read or write the CPU's registers? 323 * @userdata: any plugin data to pass to the @cb? 324 * 325 * The @cb function is called every time an instruction is executed 326 */ 327 QEMU_PLUGIN_API 328 void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn *insn, 329 qemu_plugin_vcpu_udata_cb_t cb, 330 enum qemu_plugin_cb_flags flags, 331 void *userdata); 332 333 /** 334 * qemu_plugin_register_vcpu_insn_exec_inline() - insn execution inline op 335 * @insn: the opaque qemu_plugin_insn handle for an instruction 336 * @op: the type of qemu_plugin_op (e.g. ADD_U64) 337 * @ptr: the target memory location for the op 338 * @imm: the op data (e.g. 1) 339 * 340 * Insert an inline op to every time an instruction executes. Useful 341 * if you just want to increment a single counter somewhere in memory. 342 */ 343 QEMU_PLUGIN_API 344 void qemu_plugin_register_vcpu_insn_exec_inline(struct qemu_plugin_insn *insn, 345 enum qemu_plugin_op op, 346 void *ptr, uint64_t imm); 347 348 /** 349 * qemu_plugin_tb_n_insns() - query helper for number of insns in TB 350 * @tb: opaque handle to TB passed to callback 351 * 352 * Returns: number of instructions in this block 353 */ 354 QEMU_PLUGIN_API 355 size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb *tb); 356 357 /** 358 * qemu_plugin_tb_vaddr() - query helper for vaddr of TB start 359 * @tb: opaque handle to TB passed to callback 360 * 361 * Returns: virtual address of block start 362 */ 363 QEMU_PLUGIN_API 364 uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb *tb); 365 366 /** 367 * qemu_plugin_tb_get_insn() - retrieve handle for instruction 368 * @tb: opaque handle to TB passed to callback 369 * @idx: instruction number, 0 indexed 370 * 371 * The returned handle can be used in follow up helper queries as well 372 * as when instrumenting an instruction. It is only valid for the 373 * lifetime of the callback. 374 * 375 * Returns: opaque handle to instruction 376 */ 377 QEMU_PLUGIN_API 378 struct qemu_plugin_insn * 379 qemu_plugin_tb_get_insn(const struct qemu_plugin_tb *tb, size_t idx); 380 381 /** 382 * qemu_plugin_insn_data() - return ptr to instruction data 383 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 384 * 385 * Note: data is only valid for duration of callback. See 386 * qemu_plugin_insn_size() to calculate size of stream. 387 * 388 * Returns: pointer to a stream of bytes containing the value of this 389 * instructions opcode. 390 */ 391 QEMU_PLUGIN_API 392 const void *qemu_plugin_insn_data(const struct qemu_plugin_insn *insn); 393 394 /** 395 * qemu_plugin_insn_size() - return size of instruction 396 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 397 * 398 * Returns: size of instruction in bytes 399 */ 400 QEMU_PLUGIN_API 401 size_t qemu_plugin_insn_size(const struct qemu_plugin_insn *insn); 402 403 /** 404 * qemu_plugin_insn_vaddr() - return vaddr of instruction 405 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 406 * 407 * Returns: virtual address of instruction 408 */ 409 QEMU_PLUGIN_API 410 uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn *insn); 411 412 /** 413 * qemu_plugin_insn_haddr() - return hardware addr of instruction 414 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 415 * 416 * Returns: hardware (physical) target address of instruction 417 */ 418 QEMU_PLUGIN_API 419 void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn *insn); 420 421 /** 422 * typedef qemu_plugin_meminfo_t - opaque memory transaction handle 423 * 424 * This can be further queried using the qemu_plugin_mem_* query 425 * functions. 426 */ 427 typedef uint32_t qemu_plugin_meminfo_t; 428 /** struct qemu_plugin_hwaddr - opaque hw address handle */ 429 struct qemu_plugin_hwaddr; 430 431 /** 432 * qemu_plugin_mem_size_shift() - get size of access 433 * @info: opaque memory transaction handle 434 * 435 * Returns: size of access in ^2 (0=byte, 1=16bit, 2=32bit etc...) 436 */ 437 QEMU_PLUGIN_API 438 unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info); 439 /** 440 * qemu_plugin_mem_is_sign_extended() - was the access sign extended 441 * @info: opaque memory transaction handle 442 * 443 * Returns: true if it was, otherwise false 444 */ 445 QEMU_PLUGIN_API 446 bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info); 447 /** 448 * qemu_plugin_mem_is_big_endian() - was the access big endian 449 * @info: opaque memory transaction handle 450 * 451 * Returns: true if it was, otherwise false 452 */ 453 QEMU_PLUGIN_API 454 bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info); 455 /** 456 * qemu_plugin_mem_is_store() - was the access a store 457 * @info: opaque memory transaction handle 458 * 459 * Returns: true if it was, otherwise false 460 */ 461 QEMU_PLUGIN_API 462 bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info); 463 464 /** 465 * qemu_plugin_get_hwaddr() - return handle for memory operation 466 * @info: opaque memory info structure 467 * @vaddr: the virtual address of the memory operation 468 * 469 * For system emulation returns a qemu_plugin_hwaddr handle to query 470 * details about the actual physical address backing the virtual 471 * address. For linux-user guests it just returns NULL. 472 * 473 * This handle is *only* valid for the duration of the callback. Any 474 * information about the handle should be recovered before the 475 * callback returns. 476 */ 477 QEMU_PLUGIN_API 478 struct qemu_plugin_hwaddr *qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info, 479 uint64_t vaddr); 480 481 /* 482 * The following additional queries can be run on the hwaddr structure to 483 * return information about it - namely whether it is for an IO access and the 484 * physical address associated with the access. 485 */ 486 487 /** 488 * qemu_plugin_hwaddr_is_io() - query whether memory operation is IO 489 * @haddr: address handle from qemu_plugin_get_hwaddr() 490 * 491 * Returns true if the handle's memory operation is to memory-mapped IO, or 492 * false if it is to RAM 493 */ 494 QEMU_PLUGIN_API 495 bool qemu_plugin_hwaddr_is_io(const struct qemu_plugin_hwaddr *haddr); 496 497 /** 498 * qemu_plugin_hwaddr_phys_addr() - query physical address for memory operation 499 * @haddr: address handle from qemu_plugin_get_hwaddr() 500 * 501 * Returns the physical address associated with the memory operation 502 * 503 * Note that the returned physical address may not be unique if you are dealing 504 * with multiple address spaces. 505 */ 506 QEMU_PLUGIN_API 507 uint64_t qemu_plugin_hwaddr_phys_addr(const struct qemu_plugin_hwaddr *haddr); 508 509 /* 510 * Returns a string representing the device. The string is valid for 511 * the lifetime of the plugin. 512 */ 513 QEMU_PLUGIN_API 514 const char *qemu_plugin_hwaddr_device_name(const struct qemu_plugin_hwaddr *h); 515 516 /** 517 * typedef qemu_plugin_vcpu_mem_cb_t - memory callback function type 518 * @vcpu_index: the executing vCPU 519 * @info: an opaque handle for further queries about the memory 520 * @vaddr: the virtual address of the transaction 521 * @userdata: any user data attached to the callback 522 */ 523 typedef void (*qemu_plugin_vcpu_mem_cb_t) (unsigned int vcpu_index, 524 qemu_plugin_meminfo_t info, 525 uint64_t vaddr, 526 void *userdata); 527 528 /** 529 * qemu_plugin_register_vcpu_mem_cb() - register memory access callback 530 * @insn: handle for instruction to instrument 531 * @cb: callback of type qemu_plugin_vcpu_mem_cb_t 532 * @flags: (currently unused) callback flags 533 * @rw: monitor reads, writes or both 534 * @userdata: opaque pointer for userdata 535 * 536 * This registers a full callback for every memory access generated by 537 * an instruction. If the instruction doesn't access memory no 538 * callback will be made. 539 * 540 * The callback reports the vCPU the access took place on, the virtual 541 * address of the access and a handle for further queries. The user 542 * can attach some userdata to the callback for additional purposes. 543 * 544 * Other execution threads will continue to execute during the 545 * callback so the plugin is responsible for ensuring it doesn't get 546 * confused by making appropriate use of locking if required. 547 */ 548 QEMU_PLUGIN_API 549 void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn *insn, 550 qemu_plugin_vcpu_mem_cb_t cb, 551 enum qemu_plugin_cb_flags flags, 552 enum qemu_plugin_mem_rw rw, 553 void *userdata); 554 555 /** 556 * qemu_plugin_register_vcpu_mem_inline() - register an inline op to any memory access 557 * @insn: handle for instruction to instrument 558 * @rw: apply to reads, writes or both 559 * @op: the op, of type qemu_plugin_op 560 * @ptr: pointer memory for the op 561 * @imm: immediate data for @op 562 * 563 * This registers a inline op every memory access generated by the 564 * instruction. This provides for a lightweight but not thread-safe 565 * way of counting the number of operations done. 566 */ 567 QEMU_PLUGIN_API 568 void qemu_plugin_register_vcpu_mem_inline(struct qemu_plugin_insn *insn, 569 enum qemu_plugin_mem_rw rw, 570 enum qemu_plugin_op op, void *ptr, 571 uint64_t imm); 572 573 574 575 typedef void 576 (*qemu_plugin_vcpu_syscall_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_index, 577 int64_t num, uint64_t a1, uint64_t a2, 578 uint64_t a3, uint64_t a4, uint64_t a5, 579 uint64_t a6, uint64_t a7, uint64_t a8); 580 581 QEMU_PLUGIN_API 582 void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id, 583 qemu_plugin_vcpu_syscall_cb_t cb); 584 585 typedef void 586 (*qemu_plugin_vcpu_syscall_ret_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_idx, 587 int64_t num, int64_t ret); 588 589 QEMU_PLUGIN_API 590 void 591 qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id, 592 qemu_plugin_vcpu_syscall_ret_cb_t cb); 593 594 595 /** 596 * qemu_plugin_insn_disas() - return disassembly string for instruction 597 * @insn: instruction reference 598 * 599 * Returns an allocated string containing the disassembly 600 */ 601 602 QEMU_PLUGIN_API 603 char *qemu_plugin_insn_disas(const struct qemu_plugin_insn *insn); 604 605 /** 606 * qemu_plugin_insn_symbol() - best effort symbol lookup 607 * @insn: instruction reference 608 * 609 * Return a static string referring to the symbol. This is dependent 610 * on the binary QEMU is running having provided a symbol table. 611 */ 612 QEMU_PLUGIN_API 613 const char *qemu_plugin_insn_symbol(const struct qemu_plugin_insn *insn); 614 615 /** 616 * qemu_plugin_vcpu_for_each() - iterate over the existing vCPU 617 * @id: plugin ID 618 * @cb: callback function 619 * 620 * The @cb function is called once for each existing vCPU. 621 * 622 * See also: qemu_plugin_register_vcpu_init_cb() 623 */ 624 QEMU_PLUGIN_API 625 void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id, 626 qemu_plugin_vcpu_simple_cb_t cb); 627 628 QEMU_PLUGIN_API 629 void qemu_plugin_register_flush_cb(qemu_plugin_id_t id, 630 qemu_plugin_simple_cb_t cb); 631 632 /** 633 * qemu_plugin_register_atexit_cb() - register exit callback 634 * @id: plugin ID 635 * @cb: callback 636 * @userdata: user data for callback 637 * 638 * The @cb function is called once execution has finished. Plugins 639 * should be able to free all their resources at this point much like 640 * after a reset/uninstall callback is called. 641 * 642 * In user-mode it is possible a few un-instrumented instructions from 643 * child threads may run before the host kernel reaps the threads. 644 */ 645 QEMU_PLUGIN_API 646 void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id, 647 qemu_plugin_udata_cb_t cb, void *userdata); 648 649 /* returns how many vcpus were started at this point */ 650 int qemu_plugin_num_vcpus(void); 651 652 /** 653 * qemu_plugin_outs() - output string via QEMU's logging system 654 * @string: a string 655 */ 656 QEMU_PLUGIN_API 657 void qemu_plugin_outs(const char *string); 658 659 /** 660 * qemu_plugin_bool_parse() - parses a boolean argument in the form of 661 * "<argname>=[on|yes|true|off|no|false]" 662 * 663 * @name: argument name, the part before the equals sign 664 * @val: argument value, what's after the equals sign 665 * @ret: output return value 666 * 667 * returns true if the combination @name=@val parses correctly to a boolean 668 * argument, and false otherwise 669 */ 670 QEMU_PLUGIN_API 671 bool qemu_plugin_bool_parse(const char *name, const char *val, bool *ret); 672 673 /** 674 * qemu_plugin_path_to_binary() - path to binary file being executed 675 * 676 * Return a string representing the path to the binary. For user-mode 677 * this is the main executable. For system emulation we currently 678 * return NULL. The user should g_free() the string once no longer 679 * needed. 680 */ 681 QEMU_PLUGIN_API 682 const char *qemu_plugin_path_to_binary(void); 683 684 /** 685 * qemu_plugin_start_code() - returns start of text segment 686 * 687 * Returns the nominal start address of the main text segment in 688 * user-mode. Currently returns 0 for system emulation. 689 */ 690 QEMU_PLUGIN_API 691 uint64_t qemu_plugin_start_code(void); 692 693 /** 694 * qemu_plugin_end_code() - returns end of text segment 695 * 696 * Returns the nominal end address of the main text segment in 697 * user-mode. Currently returns 0 for system emulation. 698 */ 699 QEMU_PLUGIN_API 700 uint64_t qemu_plugin_end_code(void); 701 702 /** 703 * qemu_plugin_entry_code() - returns start address for module 704 * 705 * Returns the nominal entry address of the main text segment in 706 * user-mode. Currently returns 0 for system emulation. 707 */ 708 QEMU_PLUGIN_API 709 uint64_t qemu_plugin_entry_code(void); 710 711 /** struct qemu_plugin_register - Opaque handle for register access */ 712 struct qemu_plugin_register; 713 714 /** 715 * typedef qemu_plugin_reg_descriptor - register descriptions 716 * 717 * @handle: opaque handle for retrieving value with qemu_plugin_read_register 718 * @name: register name 719 * @feature: optional feature descriptor, can be NULL 720 */ 721 typedef struct { 722 struct qemu_plugin_register *handle; 723 const char *name; 724 const char *feature; 725 } qemu_plugin_reg_descriptor; 726 727 /** 728 * qemu_plugin_get_registers() - return register list for current vCPU 729 * 730 * Returns a potentially empty GArray of qemu_plugin_reg_descriptor. 731 * Caller frees the array (but not the const strings). 732 * 733 * Should be used from a qemu_plugin_register_vcpu_init_cb() callback 734 * after the vCPU is initialised, i.e. in the vCPU context. 735 */ 736 QEMU_PLUGIN_API 737 GArray *qemu_plugin_get_registers(void); 738 739 /** 740 * qemu_plugin_read_register() - read register for current vCPU 741 * 742 * @handle: a @qemu_plugin_reg_handle handle 743 * @buf: A GByteArray for the data owned by the plugin 744 * 745 * This function is only available in a context that register read access is 746 * explicitly requested via the QEMU_PLUGIN_CB_R_REGS flag. 747 * 748 * Returns the size of the read register. The content of @buf is in target byte 749 * order. On failure returns -1. 750 */ 751 QEMU_PLUGIN_API 752 int qemu_plugin_read_register(struct qemu_plugin_register *handle, 753 GByteArray *buf); 754 755 756 #endif /* QEMU_QEMU_PLUGIN_H */ 757