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: 56 * - removed qemu_plugin_n_vcpus and qemu_plugin_n_max_vcpus 57 * - Remove qemu_plugin_register_vcpu_{tb, insn, mem}_exec_inline. 58 * Those functions are replaced by *_per_vcpu variants, which guarantee 59 * thread-safety for operations. 60 * 61 * version 3: 62 * - modified arguments and return value of qemu_plugin_insn_data to copy 63 * the data into a user-provided buffer instead of returning a pointer 64 * to the data. 65 * 66 * version 4: 67 * - added qemu_plugin_read_memory_vaddr 68 * 69 * version 5: 70 * - added qemu_plugin_write_memory_vaddr 71 * - added qemu_plugin_read_memory_hwaddr 72 * - added qemu_plugin_write_memory_hwaddr 73 * - added qemu_plugin_write_register 74 * - added qemu_plugin_translate_vaddr 75 */ 76 77 extern QEMU_PLUGIN_EXPORT int qemu_plugin_version; 78 79 #define QEMU_PLUGIN_VERSION 5 80 81 /** 82 * struct qemu_info_t - system information for plugins 83 * 84 * This structure provides for some limited information about the 85 * system to allow the plugin to make decisions on how to proceed. For 86 * example it might only be suitable for running on some guest 87 * architectures or when under full system emulation. 88 */ 89 typedef struct qemu_info_t { 90 /** @target_name: string describing architecture */ 91 const char *target_name; 92 /** @version: minimum and current plugin API level */ 93 struct { 94 int min; 95 int cur; 96 } version; 97 /** @system_emulation: is this a full system emulation? */ 98 bool system_emulation; 99 union { 100 /** @system: information relevant to system emulation */ 101 struct { 102 /** @system.smp_vcpus: initial number of vCPUs */ 103 int smp_vcpus; 104 /** @system.max_vcpus: maximum possible number of vCPUs */ 105 int max_vcpus; 106 } system; 107 }; 108 } qemu_info_t; 109 110 /** 111 * qemu_plugin_install() - Install a plugin 112 * @id: this plugin's opaque ID 113 * @info: a block describing some details about the guest 114 * @argc: number of arguments 115 * @argv: array of arguments (@argc elements) 116 * 117 * All plugins must export this symbol which is called when the plugin 118 * is first loaded. Calling qemu_plugin_uninstall() from this function 119 * is a bug. 120 * 121 * Note: @info is only live during the call. Copy any information we 122 * want to keep. @argv remains valid throughout the lifetime of the 123 * loaded plugin. 124 * 125 * Return: 0 on successful loading, !0 for an error. 126 */ 127 QEMU_PLUGIN_EXPORT int qemu_plugin_install(qemu_plugin_id_t id, 128 const qemu_info_t *info, 129 int argc, char **argv); 130 131 /** 132 * typedef qemu_plugin_simple_cb_t - simple callback 133 * @id: the unique qemu_plugin_id_t 134 * 135 * This callback passes no information aside from the unique @id. 136 */ 137 typedef void (*qemu_plugin_simple_cb_t)(qemu_plugin_id_t id); 138 139 /** 140 * typedef qemu_plugin_udata_cb_t - callback with user data 141 * @id: the unique qemu_plugin_id_t 142 * @userdata: a pointer to some user data supplied when the callback 143 * was registered. 144 */ 145 typedef void (*qemu_plugin_udata_cb_t)(qemu_plugin_id_t id, void *userdata); 146 147 /** 148 * typedef qemu_plugin_vcpu_simple_cb_t - vcpu callback 149 * @id: the unique qemu_plugin_id_t 150 * @vcpu_index: the current vcpu context 151 */ 152 typedef void (*qemu_plugin_vcpu_simple_cb_t)(qemu_plugin_id_t id, 153 unsigned int vcpu_index); 154 155 /** 156 * typedef qemu_plugin_vcpu_udata_cb_t - vcpu callback 157 * @vcpu_index: the current vcpu context 158 * @userdata: a pointer to some user data supplied when the callback 159 * was registered. 160 */ 161 typedef void (*qemu_plugin_vcpu_udata_cb_t)(unsigned int vcpu_index, 162 void *userdata); 163 164 /** 165 * qemu_plugin_uninstall() - Uninstall a plugin 166 * @id: this plugin's opaque ID 167 * @cb: callback to be called once the plugin has been removed 168 * 169 * Do NOT assume that the plugin has been uninstalled once this function 170 * returns. Plugins are uninstalled asynchronously, and therefore the given 171 * plugin receives callbacks until @cb is called. 172 * 173 * Note: Calling this function from qemu_plugin_install() is a bug. 174 */ 175 QEMU_PLUGIN_API 176 void qemu_plugin_uninstall(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb); 177 178 /** 179 * qemu_plugin_reset() - Reset a plugin 180 * @id: this plugin's opaque ID 181 * @cb: callback to be called once the plugin has been reset 182 * 183 * Unregisters all callbacks for the plugin given by @id. 184 * 185 * Do NOT assume that the plugin has been reset once this function returns. 186 * Plugins are reset asynchronously, and therefore the given plugin receives 187 * callbacks until @cb is called. 188 */ 189 QEMU_PLUGIN_API 190 void qemu_plugin_reset(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb); 191 192 /** 193 * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback 194 * @id: plugin ID 195 * @cb: callback function 196 * 197 * The @cb function is called every time a vCPU is initialized. 198 * 199 * See also: qemu_plugin_register_vcpu_exit_cb() 200 */ 201 QEMU_PLUGIN_API 202 void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id, 203 qemu_plugin_vcpu_simple_cb_t cb); 204 205 /** 206 * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback 207 * @id: plugin ID 208 * @cb: callback function 209 * 210 * The @cb function is called every time a vCPU exits. 211 * 212 * See also: qemu_plugin_register_vcpu_init_cb() 213 */ 214 QEMU_PLUGIN_API 215 void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id, 216 qemu_plugin_vcpu_simple_cb_t cb); 217 218 /** 219 * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback 220 * @id: plugin ID 221 * @cb: callback function 222 * 223 * The @cb function is called every time a vCPU idles. 224 */ 225 QEMU_PLUGIN_API 226 void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id, 227 qemu_plugin_vcpu_simple_cb_t cb); 228 229 /** 230 * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback 231 * @id: plugin ID 232 * @cb: callback function 233 * 234 * The @cb function is called every time a vCPU resumes execution. 235 */ 236 QEMU_PLUGIN_API 237 void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id, 238 qemu_plugin_vcpu_simple_cb_t cb); 239 240 /** struct qemu_plugin_tb - Opaque handle for a translation block */ 241 struct qemu_plugin_tb; 242 /** struct qemu_plugin_insn - Opaque handle for a translated instruction */ 243 struct qemu_plugin_insn; 244 /** struct qemu_plugin_scoreboard - Opaque handle for a scoreboard */ 245 struct qemu_plugin_scoreboard; 246 247 /** 248 * typedef qemu_plugin_u64 - uint64_t member of an entry in a scoreboard 249 * 250 * This field allows to access a specific uint64_t member in one given entry, 251 * located at a specified offset. Inline operations expect this as entry. 252 */ 253 typedef struct { 254 struct qemu_plugin_scoreboard *score; 255 size_t offset; 256 } qemu_plugin_u64; 257 258 /** 259 * enum qemu_plugin_cb_flags - type of callback 260 * 261 * @QEMU_PLUGIN_CB_NO_REGS: callback does not access the CPU's regs 262 * @QEMU_PLUGIN_CB_R_REGS: callback reads the CPU's regs 263 * @QEMU_PLUGIN_CB_RW_REGS: callback reads and writes the CPU's regs 264 */ 265 enum qemu_plugin_cb_flags { 266 QEMU_PLUGIN_CB_NO_REGS, 267 QEMU_PLUGIN_CB_R_REGS, 268 QEMU_PLUGIN_CB_RW_REGS, 269 }; 270 271 enum qemu_plugin_mem_rw { 272 QEMU_PLUGIN_MEM_R = 1, 273 QEMU_PLUGIN_MEM_W, 274 QEMU_PLUGIN_MEM_RW, 275 }; 276 277 enum qemu_plugin_mem_value_type { 278 QEMU_PLUGIN_MEM_VALUE_U8, 279 QEMU_PLUGIN_MEM_VALUE_U16, 280 QEMU_PLUGIN_MEM_VALUE_U32, 281 QEMU_PLUGIN_MEM_VALUE_U64, 282 QEMU_PLUGIN_MEM_VALUE_U128, 283 }; 284 285 /* typedef qemu_plugin_mem_value - value accessed during a load/store */ 286 typedef struct { 287 enum qemu_plugin_mem_value_type type; 288 union { 289 uint8_t u8; 290 uint16_t u16; 291 uint32_t u32; 292 uint64_t u64; 293 struct { 294 uint64_t low; 295 uint64_t high; 296 } u128; 297 } data; 298 } qemu_plugin_mem_value; 299 300 /** 301 * enum qemu_plugin_cond - condition to enable callback 302 * 303 * @QEMU_PLUGIN_COND_NEVER: false 304 * @QEMU_PLUGIN_COND_ALWAYS: true 305 * @QEMU_PLUGIN_COND_EQ: is equal? 306 * @QEMU_PLUGIN_COND_NE: is not equal? 307 * @QEMU_PLUGIN_COND_LT: is less than? 308 * @QEMU_PLUGIN_COND_LE: is less than or equal? 309 * @QEMU_PLUGIN_COND_GT: is greater than? 310 * @QEMU_PLUGIN_COND_GE: is greater than or equal? 311 */ 312 enum qemu_plugin_cond { 313 QEMU_PLUGIN_COND_NEVER, 314 QEMU_PLUGIN_COND_ALWAYS, 315 QEMU_PLUGIN_COND_EQ, 316 QEMU_PLUGIN_COND_NE, 317 QEMU_PLUGIN_COND_LT, 318 QEMU_PLUGIN_COND_LE, 319 QEMU_PLUGIN_COND_GT, 320 QEMU_PLUGIN_COND_GE, 321 }; 322 323 /** 324 * typedef qemu_plugin_vcpu_tb_trans_cb_t - translation callback 325 * @id: unique plugin id 326 * @tb: opaque handle used for querying and instrumenting a block. 327 */ 328 typedef void (*qemu_plugin_vcpu_tb_trans_cb_t)(qemu_plugin_id_t id, 329 struct qemu_plugin_tb *tb); 330 331 /** 332 * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb 333 * @id: plugin ID 334 * @cb: callback function 335 * 336 * The @cb function is called every time a translation occurs. The @cb 337 * function is passed an opaque qemu_plugin_type which it can query 338 * for additional information including the list of translated 339 * instructions. At this point the plugin can register further 340 * callbacks to be triggered when the block or individual instruction 341 * executes. 342 */ 343 QEMU_PLUGIN_API 344 void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id, 345 qemu_plugin_vcpu_tb_trans_cb_t cb); 346 347 /** 348 * qemu_plugin_register_vcpu_tb_exec_cb() - register execution callback 349 * @tb: the opaque qemu_plugin_tb handle for the translation 350 * @cb: callback function 351 * @flags: does the plugin read or write the CPU's registers? 352 * @userdata: any plugin data to pass to the @cb? 353 * 354 * The @cb function is called every time a translated unit executes. 355 */ 356 QEMU_PLUGIN_API 357 void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb *tb, 358 qemu_plugin_vcpu_udata_cb_t cb, 359 enum qemu_plugin_cb_flags flags, 360 void *userdata); 361 362 /** 363 * qemu_plugin_register_vcpu_tb_exec_cond_cb() - register conditional callback 364 * @tb: the opaque qemu_plugin_tb handle for the translation 365 * @cb: callback function 366 * @cond: condition to enable callback 367 * @entry: first operand for condition 368 * @imm: second operand for condition 369 * @flags: does the plugin read or write the CPU's registers? 370 * @userdata: any plugin data to pass to the @cb? 371 * 372 * The @cb function is called when a translated unit executes if 373 * entry @cond imm is true. 374 * If condition is QEMU_PLUGIN_COND_ALWAYS, condition is never interpreted and 375 * this function is equivalent to qemu_plugin_register_vcpu_tb_exec_cb. 376 * If condition QEMU_PLUGIN_COND_NEVER, condition is never interpreted and 377 * callback is never installed. 378 */ 379 QEMU_PLUGIN_API 380 void qemu_plugin_register_vcpu_tb_exec_cond_cb(struct qemu_plugin_tb *tb, 381 qemu_plugin_vcpu_udata_cb_t cb, 382 enum qemu_plugin_cb_flags flags, 383 enum qemu_plugin_cond cond, 384 qemu_plugin_u64 entry, 385 uint64_t imm, 386 void *userdata); 387 388 /** 389 * enum qemu_plugin_op - describes an inline op 390 * 391 * @QEMU_PLUGIN_INLINE_ADD_U64: add an immediate value uint64_t 392 * @QEMU_PLUGIN_INLINE_STORE_U64: store an immediate value uint64_t 393 */ 394 395 enum qemu_plugin_op { 396 QEMU_PLUGIN_INLINE_ADD_U64, 397 QEMU_PLUGIN_INLINE_STORE_U64, 398 }; 399 400 /** 401 * qemu_plugin_register_vcpu_tb_exec_inline_per_vcpu() - execution inline op 402 * @tb: the opaque qemu_plugin_tb handle for the translation 403 * @op: the type of qemu_plugin_op (e.g. ADD_U64) 404 * @entry: entry to run op 405 * @imm: the op data (e.g. 1) 406 * 407 * Insert an inline op on a given scoreboard entry. 408 */ 409 QEMU_PLUGIN_API 410 void qemu_plugin_register_vcpu_tb_exec_inline_per_vcpu( 411 struct qemu_plugin_tb *tb, 412 enum qemu_plugin_op op, 413 qemu_plugin_u64 entry, 414 uint64_t imm); 415 416 /** 417 * qemu_plugin_register_vcpu_insn_exec_cb() - register insn execution cb 418 * @insn: the opaque qemu_plugin_insn handle for an instruction 419 * @cb: callback function 420 * @flags: does the plugin read or write the CPU's registers? 421 * @userdata: any plugin data to pass to the @cb? 422 * 423 * The @cb function is called every time an instruction is executed 424 */ 425 QEMU_PLUGIN_API 426 void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn *insn, 427 qemu_plugin_vcpu_udata_cb_t cb, 428 enum qemu_plugin_cb_flags flags, 429 void *userdata); 430 431 /** 432 * qemu_plugin_register_vcpu_insn_exec_cond_cb() - conditional insn execution cb 433 * @insn: the opaque qemu_plugin_insn handle for an instruction 434 * @cb: callback function 435 * @flags: does the plugin read or write the CPU's registers? 436 * @cond: condition to enable callback 437 * @entry: first operand for condition 438 * @imm: second operand for condition 439 * @userdata: any plugin data to pass to the @cb? 440 * 441 * The @cb function is called when an instruction executes if 442 * entry @cond imm is true. 443 * If condition is QEMU_PLUGIN_COND_ALWAYS, condition is never interpreted and 444 * this function is equivalent to qemu_plugin_register_vcpu_insn_exec_cb. 445 * If condition QEMU_PLUGIN_COND_NEVER, condition is never interpreted and 446 * callback is never installed. 447 */ 448 QEMU_PLUGIN_API 449 void qemu_plugin_register_vcpu_insn_exec_cond_cb( 450 struct qemu_plugin_insn *insn, 451 qemu_plugin_vcpu_udata_cb_t cb, 452 enum qemu_plugin_cb_flags flags, 453 enum qemu_plugin_cond cond, 454 qemu_plugin_u64 entry, 455 uint64_t imm, 456 void *userdata); 457 458 /** 459 * qemu_plugin_register_vcpu_insn_exec_inline_per_vcpu() - insn exec inline op 460 * @insn: the opaque qemu_plugin_insn handle for an instruction 461 * @op: the type of qemu_plugin_op (e.g. ADD_U64) 462 * @entry: entry to run op 463 * @imm: the op data (e.g. 1) 464 * 465 * Insert an inline op to every time an instruction executes. 466 */ 467 QEMU_PLUGIN_API 468 void qemu_plugin_register_vcpu_insn_exec_inline_per_vcpu( 469 struct qemu_plugin_insn *insn, 470 enum qemu_plugin_op op, 471 qemu_plugin_u64 entry, 472 uint64_t imm); 473 474 /** 475 * qemu_plugin_tb_n_insns() - query helper for number of insns in TB 476 * @tb: opaque handle to TB passed to callback 477 * 478 * Returns: number of instructions in this block 479 */ 480 QEMU_PLUGIN_API 481 size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb *tb); 482 483 /** 484 * qemu_plugin_tb_vaddr() - query helper for vaddr of TB start 485 * @tb: opaque handle to TB passed to callback 486 * 487 * Returns: virtual address of block start 488 */ 489 QEMU_PLUGIN_API 490 uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb *tb); 491 492 /** 493 * qemu_plugin_tb_get_insn() - retrieve handle for instruction 494 * @tb: opaque handle to TB passed to callback 495 * @idx: instruction number, 0 indexed 496 * 497 * The returned handle can be used in follow up helper queries as well 498 * as when instrumenting an instruction. It is only valid for the 499 * lifetime of the callback. 500 * 501 * Returns: opaque handle to instruction 502 */ 503 QEMU_PLUGIN_API 504 struct qemu_plugin_insn * 505 qemu_plugin_tb_get_insn(const struct qemu_plugin_tb *tb, size_t idx); 506 507 /** 508 * qemu_plugin_insn_data() - copy instruction data 509 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 510 * @dest: destination into which data is copied 511 * @len: length of dest 512 * 513 * Returns the number of bytes copied, minimum of @len and insn size. 514 */ 515 QEMU_PLUGIN_API 516 size_t qemu_plugin_insn_data(const struct qemu_plugin_insn *insn, 517 void *dest, size_t len); 518 519 /** 520 * qemu_plugin_insn_size() - return size of instruction 521 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 522 * 523 * Returns: size of instruction in bytes 524 */ 525 QEMU_PLUGIN_API 526 size_t qemu_plugin_insn_size(const struct qemu_plugin_insn *insn); 527 528 /** 529 * qemu_plugin_insn_vaddr() - return vaddr of instruction 530 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 531 * 532 * Returns: virtual address of instruction 533 */ 534 QEMU_PLUGIN_API 535 uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn *insn); 536 537 /** 538 * qemu_plugin_insn_haddr() - return hardware addr of instruction 539 * @insn: opaque instruction handle from qemu_plugin_tb_get_insn() 540 * 541 * Returns: hardware (physical) target address of instruction 542 */ 543 QEMU_PLUGIN_API 544 void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn *insn); 545 546 /** 547 * typedef qemu_plugin_meminfo_t - opaque memory transaction handle 548 * 549 * This can be further queried using the qemu_plugin_mem_* query 550 * functions. 551 */ 552 typedef uint32_t qemu_plugin_meminfo_t; 553 /** struct qemu_plugin_hwaddr - opaque hw address handle */ 554 struct qemu_plugin_hwaddr; 555 556 /** 557 * qemu_plugin_mem_size_shift() - get size of access 558 * @info: opaque memory transaction handle 559 * 560 * Returns: size of access in ^2 (0=byte, 1=16bit, 2=32bit etc...) 561 */ 562 QEMU_PLUGIN_API 563 unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info); 564 /** 565 * qemu_plugin_mem_is_sign_extended() - was the access sign extended 566 * @info: opaque memory transaction handle 567 * 568 * Returns: true if it was, otherwise false 569 */ 570 QEMU_PLUGIN_API 571 bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info); 572 /** 573 * qemu_plugin_mem_is_big_endian() - was the access big endian 574 * @info: opaque memory transaction handle 575 * 576 * Returns: true if it was, otherwise false 577 */ 578 QEMU_PLUGIN_API 579 bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info); 580 /** 581 * qemu_plugin_mem_is_store() - was the access a store 582 * @info: opaque memory transaction handle 583 * 584 * Returns: true if it was, otherwise false 585 */ 586 QEMU_PLUGIN_API 587 bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info); 588 589 /** 590 * qemu_plugin_mem_get_value() - return last value loaded/stored 591 * @info: opaque memory transaction handle 592 * 593 * Returns: memory value 594 */ 595 QEMU_PLUGIN_API 596 qemu_plugin_mem_value qemu_plugin_mem_get_value(qemu_plugin_meminfo_t info); 597 598 /** 599 * qemu_plugin_get_hwaddr() - return handle for memory operation 600 * @info: opaque memory info structure 601 * @vaddr: the virtual address of the memory operation 602 * 603 * For system emulation returns a qemu_plugin_hwaddr handle to query 604 * details about the actual physical address backing the virtual 605 * address. For linux-user guests it just returns NULL. 606 * 607 * This handle is *only* valid for the duration of the callback. Any 608 * information about the handle should be recovered before the 609 * callback returns. 610 */ 611 QEMU_PLUGIN_API 612 struct qemu_plugin_hwaddr *qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info, 613 uint64_t vaddr); 614 615 /* 616 * The following additional queries can be run on the hwaddr structure to 617 * return information about it - namely whether it is for an IO access and the 618 * physical address associated with the access. 619 */ 620 621 /** 622 * qemu_plugin_hwaddr_is_io() - query whether memory operation is IO 623 * @haddr: address handle from qemu_plugin_get_hwaddr() 624 * 625 * Returns true if the handle's memory operation is to memory-mapped IO, or 626 * false if it is to RAM 627 */ 628 QEMU_PLUGIN_API 629 bool qemu_plugin_hwaddr_is_io(const struct qemu_plugin_hwaddr *haddr); 630 631 /** 632 * qemu_plugin_hwaddr_phys_addr() - query physical address for memory operation 633 * @haddr: address handle from qemu_plugin_get_hwaddr() 634 * 635 * Returns the physical address associated with the memory operation 636 * 637 * Note that the returned physical address may not be unique if you are dealing 638 * with multiple address spaces. 639 */ 640 QEMU_PLUGIN_API 641 uint64_t qemu_plugin_hwaddr_phys_addr(const struct qemu_plugin_hwaddr *haddr); 642 643 /* 644 * Returns a string representing the device. The string is valid for 645 * the lifetime of the plugin. 646 */ 647 QEMU_PLUGIN_API 648 const char *qemu_plugin_hwaddr_device_name(const struct qemu_plugin_hwaddr *h); 649 650 /** 651 * typedef qemu_plugin_vcpu_mem_cb_t - memory callback function type 652 * @vcpu_index: the executing vCPU 653 * @info: an opaque handle for further queries about the memory 654 * @vaddr: the virtual address of the transaction 655 * @userdata: any user data attached to the callback 656 */ 657 typedef void (*qemu_plugin_vcpu_mem_cb_t) (unsigned int vcpu_index, 658 qemu_plugin_meminfo_t info, 659 uint64_t vaddr, 660 void *userdata); 661 662 /** 663 * qemu_plugin_register_vcpu_mem_cb() - register memory access callback 664 * @insn: handle for instruction to instrument 665 * @cb: callback of type qemu_plugin_vcpu_mem_cb_t 666 * @flags: (currently unused) callback flags 667 * @rw: monitor reads, writes or both 668 * @userdata: opaque pointer for userdata 669 * 670 * This registers a full callback for every memory access generated by 671 * an instruction. If the instruction doesn't access memory no 672 * callback will be made. 673 * 674 * The callback reports the vCPU the access took place on, the virtual 675 * address of the access and a handle for further queries. The user 676 * can attach some userdata to the callback for additional purposes. 677 * 678 * Other execution threads will continue to execute during the 679 * callback so the plugin is responsible for ensuring it doesn't get 680 * confused by making appropriate use of locking if required. 681 */ 682 QEMU_PLUGIN_API 683 void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn *insn, 684 qemu_plugin_vcpu_mem_cb_t cb, 685 enum qemu_plugin_cb_flags flags, 686 enum qemu_plugin_mem_rw rw, 687 void *userdata); 688 689 /** 690 * qemu_plugin_register_vcpu_mem_inline_per_vcpu() - inline op for mem access 691 * @insn: handle for instruction to instrument 692 * @rw: apply to reads, writes or both 693 * @op: the op, of type qemu_plugin_op 694 * @entry: entry to run op 695 * @imm: immediate data for @op 696 * 697 * This registers a inline op every memory access generated by the 698 * instruction. 699 */ 700 QEMU_PLUGIN_API 701 void qemu_plugin_register_vcpu_mem_inline_per_vcpu( 702 struct qemu_plugin_insn *insn, 703 enum qemu_plugin_mem_rw rw, 704 enum qemu_plugin_op op, 705 qemu_plugin_u64 entry, 706 uint64_t imm); 707 708 /** 709 * qemu_plugin_request_time_control() - request the ability to control time 710 * 711 * This grants the plugin the ability to control system time. Only one 712 * plugin can control time so if multiple plugins request the ability 713 * all but the first will fail. 714 * 715 * Returns an opaque handle or NULL if fails 716 */ 717 QEMU_PLUGIN_API 718 const void *qemu_plugin_request_time_control(void); 719 720 /** 721 * qemu_plugin_update_ns() - update system emulation time 722 * @handle: opaque handle returned by qemu_plugin_request_time_control() 723 * @time: time in nanoseconds 724 * 725 * This allows an appropriately authorised plugin (i.e. holding the 726 * time control handle) to move system time forward to @time. For 727 * user-mode emulation the time is not changed by this as all reported 728 * time comes from the host kernel. 729 * 730 * Start time is 0. 731 */ 732 QEMU_PLUGIN_API 733 void qemu_plugin_update_ns(const void *handle, int64_t time); 734 735 typedef void 736 (*qemu_plugin_vcpu_syscall_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_index, 737 int64_t num, uint64_t a1, uint64_t a2, 738 uint64_t a3, uint64_t a4, uint64_t a5, 739 uint64_t a6, uint64_t a7, uint64_t a8); 740 741 QEMU_PLUGIN_API 742 void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id, 743 qemu_plugin_vcpu_syscall_cb_t cb); 744 745 typedef void 746 (*qemu_plugin_vcpu_syscall_ret_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_idx, 747 int64_t num, int64_t ret); 748 749 QEMU_PLUGIN_API 750 void 751 qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id, 752 qemu_plugin_vcpu_syscall_ret_cb_t cb); 753 754 755 /** 756 * qemu_plugin_insn_disas() - return disassembly string for instruction 757 * @insn: instruction reference 758 * 759 * Returns an allocated string containing the disassembly 760 */ 761 762 QEMU_PLUGIN_API 763 char *qemu_plugin_insn_disas(const struct qemu_plugin_insn *insn); 764 765 /** 766 * qemu_plugin_insn_symbol() - best effort symbol lookup 767 * @insn: instruction reference 768 * 769 * Return a static string referring to the symbol. This is dependent 770 * on the binary QEMU is running having provided a symbol table. 771 */ 772 QEMU_PLUGIN_API 773 const char *qemu_plugin_insn_symbol(const struct qemu_plugin_insn *insn); 774 775 /** 776 * qemu_plugin_vcpu_for_each() - iterate over the existing vCPU 777 * @id: plugin ID 778 * @cb: callback function 779 * 780 * The @cb function is called once for each existing vCPU. 781 * 782 * See also: qemu_plugin_register_vcpu_init_cb() 783 */ 784 QEMU_PLUGIN_API 785 void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id, 786 qemu_plugin_vcpu_simple_cb_t cb); 787 788 QEMU_PLUGIN_API 789 void qemu_plugin_register_flush_cb(qemu_plugin_id_t id, 790 qemu_plugin_simple_cb_t cb); 791 792 /** 793 * qemu_plugin_register_atexit_cb() - register exit callback 794 * @id: plugin ID 795 * @cb: callback 796 * @userdata: user data for callback 797 * 798 * The @cb function is called once execution has finished. Plugins 799 * should be able to free all their resources at this point much like 800 * after a reset/uninstall callback is called. 801 * 802 * In user-mode it is possible a few un-instrumented instructions from 803 * child threads may run before the host kernel reaps the threads. 804 */ 805 QEMU_PLUGIN_API 806 void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id, 807 qemu_plugin_udata_cb_t cb, void *userdata); 808 809 /* returns how many vcpus were started at this point */ 810 QEMU_PLUGIN_API 811 int qemu_plugin_num_vcpus(void); 812 813 /** 814 * qemu_plugin_outs() - output string via QEMU's logging system 815 * @string: a string 816 */ 817 QEMU_PLUGIN_API 818 void qemu_plugin_outs(const char *string); 819 820 /** 821 * qemu_plugin_bool_parse() - parses a boolean argument in the form of 822 * "<argname>=[on|yes|true|off|no|false]" 823 * 824 * @name: argument name, the part before the equals sign 825 * @val: argument value, what's after the equals sign 826 * @ret: output return value 827 * 828 * returns true if the combination @name=@val parses correctly to a boolean 829 * argument, and false otherwise 830 */ 831 QEMU_PLUGIN_API 832 bool qemu_plugin_bool_parse(const char *name, const char *val, bool *ret); 833 834 /** 835 * qemu_plugin_path_to_binary() - path to binary file being executed 836 * 837 * Return a string representing the path to the binary. For user-mode 838 * this is the main executable. For system emulation we currently 839 * return NULL. The user should g_free() the string once no longer 840 * needed. 841 */ 842 QEMU_PLUGIN_API 843 const char *qemu_plugin_path_to_binary(void); 844 845 /** 846 * qemu_plugin_start_code() - returns start of text segment 847 * 848 * Returns the nominal start address of the main text segment in 849 * user-mode. Currently returns 0 for system emulation. 850 */ 851 QEMU_PLUGIN_API 852 uint64_t qemu_plugin_start_code(void); 853 854 /** 855 * qemu_plugin_end_code() - returns end of text segment 856 * 857 * Returns the nominal end address of the main text segment in 858 * user-mode. Currently returns 0 for system emulation. 859 */ 860 QEMU_PLUGIN_API 861 uint64_t qemu_plugin_end_code(void); 862 863 /** 864 * qemu_plugin_entry_code() - returns start address for module 865 * 866 * Returns the nominal entry address of the main text segment in 867 * user-mode. Currently returns 0 for system emulation. 868 */ 869 QEMU_PLUGIN_API 870 uint64_t qemu_plugin_entry_code(void); 871 872 /** struct qemu_plugin_register - Opaque handle for register access */ 873 struct qemu_plugin_register; 874 875 /** 876 * typedef qemu_plugin_reg_descriptor - register descriptions 877 * 878 * @handle: opaque handle for retrieving value with qemu_plugin_read_register or 879 * writing value with qemu_plugin_write_register 880 * @name: register name 881 * @feature: optional feature descriptor, can be NULL 882 */ 883 typedef struct { 884 struct qemu_plugin_register *handle; 885 const char *name; 886 const char *feature; 887 } qemu_plugin_reg_descriptor; 888 889 /** 890 * qemu_plugin_get_registers() - return register list for current vCPU 891 * 892 * Returns a potentially empty GArray of qemu_plugin_reg_descriptor. 893 * Caller frees the array (but not the const strings). 894 * 895 * Should be used from a qemu_plugin_register_vcpu_init_cb() callback 896 * after the vCPU is initialised, i.e. in the vCPU context. 897 */ 898 QEMU_PLUGIN_API 899 GArray *qemu_plugin_get_registers(void); 900 901 /** 902 * qemu_plugin_read_register() - read register for current vCPU 903 * 904 * @handle: a @qemu_plugin_reg_handle handle 905 * @buf: A GByteArray for the data owned by the plugin 906 * 907 * This function is only available in a context that register read access is 908 * explicitly requested via the QEMU_PLUGIN_CB_R_REGS flag, if called inside a 909 * callback that can be registered with a qemu_plugin_cb_flags argument. This 910 * function can also be used in any callback context that does not use a flags 911 * argument, such as in a callback registered with 912 * qemu_plugin_register_vcpu_init_cb(), except for callbacks registered with 913 * qemu_plugin_register_atexit_cb() and qemu_plugin_register_flush_cb(). 914 * 915 * Returns the size of the read register. The content of @buf is in target byte 916 * order. On failure returns -1. 917 */ 918 QEMU_PLUGIN_API 919 int qemu_plugin_read_register(struct qemu_plugin_register *handle, 920 GByteArray *buf); 921 922 /** 923 * qemu_plugin_write_register() - write register for current vCPU 924 * 925 * @handle: a @qemu_plugin_reg_handle handle 926 * @buf: A GByteArray for the data owned by the plugin 927 * 928 * This function is only available in a context that register read access is 929 * explicitly requested via the QEMU_PLUGIN_CB_RW_REGS flag, if called inside a 930 * callback that can be registered with a qemu_plugin_cb_flags argument. This 931 * function can also be used in any callback context that does not use a flags 932 * argument, such as in a callback registered with 933 * qemu_plugin_register_vcpu_init_cb(), except for callbacks registered with 934 * qemu_plugin_register_atexit_cb() and qemu_plugin_register_flush_cb(). 935 * 936 * The size of @buf must be at least the size of the requested register. 937 * Attempting to write a register with @buf smaller than the register size 938 * will result in a crash or other undesired behavior. 939 * 940 * Returns the number of bytes written. On failure returns 0. 941 */ 942 QEMU_PLUGIN_API 943 int qemu_plugin_write_register(struct qemu_plugin_register *handle, 944 GByteArray *buf); 945 946 /** 947 * qemu_plugin_read_memory_vaddr() - read from memory using a virtual address 948 * 949 * @addr: A virtual address to read from 950 * @data: A byte array to store data into 951 * @len: The number of bytes to read, starting from @addr 952 * 953 * @len bytes of data is read starting at @addr and stored into @data. If @data 954 * is not large enough to hold @len bytes, it will be expanded to the necessary 955 * size, reallocating if necessary. @len must be greater than 0. 956 * 957 * This function does not ensure writes are flushed prior to reading, so 958 * callers should take care when calling this function in plugin callbacks to 959 * avoid attempting to read data which may not yet be written and should use 960 * the memory callback API instead. 961 * 962 * Returns true on success and false on failure. 963 */ 964 QEMU_PLUGIN_API 965 bool qemu_plugin_read_memory_vaddr(uint64_t addr, 966 GByteArray *data, size_t len); 967 968 /** 969 * qemu_plugin_write_memory_vaddr() - write to memory using a virtual address 970 * 971 * @addr: A virtual address to write to 972 * @data: A byte array containing the data to write 973 * 974 * The contents of @data will be written to memory starting at the virtual 975 * address @addr. 976 * 977 * This function does not guarantee consistency of writes, nor does it ensure 978 * that pending writes are flushed either before or after the write takes place, 979 * so callers should take care to only call this function in vCPU context (i.e. 980 * in callbacks) and avoid depending on the existence of data written using this 981 * function which may be overwritten afterward. 982 * 983 * Returns true on success and false on failure. 984 */ 985 QEMU_PLUGIN_API 986 bool qemu_plugin_write_memory_vaddr(uint64_t addr, 987 GByteArray *data); 988 989 /** 990 * enum qemu_plugin_hwaddr_operation_result - result of a memory operation 991 * 992 * @QEMU_PLUGIN_HWADDR_OPERATION_OK: hwaddr operation succeeded 993 * @QEMU_PLUGIN_HWADDR_OPERATION_ERROR: unexpected error occurred 994 * @QEMU_PLUGIN_HWADDR_OPERATION_DEVICE_ERROR: error in memory device 995 * @QEMU_PLUGIN_HWADDR_OPERATION_ACCESS_DENIED: permission error 996 * @QEMU_PLUGIN_HWADDR_OPERATION_INVALID_ADDRESS: address was invalid 997 * @QEMU_PLUGIN_HWADDR_OPERATION_INVALID_ADDRESS_SPACE: invalid address space 998 */ 999 enum qemu_plugin_hwaddr_operation_result { 1000 QEMU_PLUGIN_HWADDR_OPERATION_OK, 1001 QEMU_PLUGIN_HWADDR_OPERATION_ERROR, 1002 QEMU_PLUGIN_HWADDR_OPERATION_DEVICE_ERROR, 1003 QEMU_PLUGIN_HWADDR_OPERATION_ACCESS_DENIED, 1004 QEMU_PLUGIN_HWADDR_OPERATION_INVALID_ADDRESS, 1005 QEMU_PLUGIN_HWADDR_OPERATION_INVALID_ADDRESS_SPACE, 1006 }; 1007 1008 /** 1009 * qemu_plugin_read_memory_hwaddr() - read from memory using a hardware address 1010 * 1011 * @addr: The physical address to read from 1012 * @data: A byte array to store data into 1013 * @len: The number of bytes to read, starting from @addr 1014 * 1015 * @len bytes of data is read from the current memory space for the current 1016 * vCPU starting at @addr and stored into @data. If @data is not large enough to 1017 * hold @len bytes, it will be expanded to the necessary size, reallocating if 1018 * necessary. @len must be greater than 0. 1019 * 1020 * This function does not ensure writes are flushed prior to reading, so 1021 * callers should take care when calling this function in plugin callbacks to 1022 * avoid attempting to read data which may not yet be written and should use 1023 * the memory callback API instead. 1024 * 1025 * This function is only valid for softmmu targets. 1026 * 1027 * Returns a qemu_plugin_hwaddr_operation_result indicating the result of the 1028 * operation. 1029 */ 1030 QEMU_PLUGIN_API 1031 enum qemu_plugin_hwaddr_operation_result 1032 qemu_plugin_read_memory_hwaddr(uint64_t addr, GByteArray *data, size_t len); 1033 1034 /** 1035 * qemu_plugin_write_memory_hwaddr() - write to memory using a hardware address 1036 * 1037 * @addr: A physical address to write to 1038 * @data: A byte array containing the data to write 1039 * 1040 * The contents of @data will be written to memory starting at the hardware 1041 * address @addr in the current address space for the current vCPU. 1042 * 1043 * This function does not guarantee consistency of writes, nor does it ensure 1044 * that pending writes are flushed either before or after the write takes place, 1045 * so callers should take care when calling this function in plugin callbacks to 1046 * avoid depending on the existence of data written using this function which 1047 * may be overwritten afterward. In addition, this function requires that the 1048 * pages containing the address are not locked. Practically, this means that you 1049 * should not write instruction memory in a current translation block inside a 1050 * callback registered with qemu_plugin_register_vcpu_tb_trans_cb. 1051 * 1052 * You can, for example, write instruction memory in a current translation block 1053 * in a callback registered with qemu_plugin_register_vcpu_tb_exec_cb, although 1054 * be aware that the write will not be flushed until after the translation block 1055 * has finished executing. In general, this function should be used to write 1056 * data memory or to patch code at a known address, not in a current translation 1057 * block. 1058 * 1059 * This function is only valid for softmmu targets. 1060 * 1061 * Returns a qemu_plugin_hwaddr_operation_result indicating the result of the 1062 * operation. 1063 */ 1064 QEMU_PLUGIN_API 1065 enum qemu_plugin_hwaddr_operation_result 1066 qemu_plugin_write_memory_hwaddr(uint64_t addr, GByteArray *data); 1067 1068 /** 1069 * qemu_plugin_translate_vaddr() - translate virtual address for current vCPU 1070 * 1071 * @vaddr: virtual address to translate 1072 * @hwaddr: pointer to store the physical address 1073 * 1074 * This function is only valid in vCPU context (i.e. in callbacks) and is only 1075 * valid for softmmu targets. 1076 * 1077 * Returns true on success and false on failure. 1078 */ 1079 QEMU_PLUGIN_API 1080 bool qemu_plugin_translate_vaddr(uint64_t vaddr, uint64_t *hwaddr); 1081 1082 /** 1083 * qemu_plugin_scoreboard_new() - alloc a new scoreboard 1084 * 1085 * @element_size: size (in bytes) for one entry 1086 * 1087 * Returns a pointer to a new scoreboard. It must be freed using 1088 * qemu_plugin_scoreboard_free. 1089 */ 1090 QEMU_PLUGIN_API 1091 struct qemu_plugin_scoreboard *qemu_plugin_scoreboard_new(size_t element_size); 1092 1093 /** 1094 * qemu_plugin_scoreboard_free() - free a scoreboard 1095 * @score: scoreboard to free 1096 */ 1097 QEMU_PLUGIN_API 1098 void qemu_plugin_scoreboard_free(struct qemu_plugin_scoreboard *score); 1099 1100 /** 1101 * qemu_plugin_scoreboard_find() - get pointer to an entry of a scoreboard 1102 * @score: scoreboard to query 1103 * @vcpu_index: entry index 1104 * 1105 * Returns address of entry of a scoreboard matching a given vcpu_index. This 1106 * address can be modified later if scoreboard is resized. 1107 */ 1108 QEMU_PLUGIN_API 1109 void *qemu_plugin_scoreboard_find(struct qemu_plugin_scoreboard *score, 1110 unsigned int vcpu_index); 1111 1112 /* Macros to define a qemu_plugin_u64 */ 1113 #define qemu_plugin_scoreboard_u64(score) \ 1114 (qemu_plugin_u64) {score, 0} 1115 #define qemu_plugin_scoreboard_u64_in_struct(score, type, member) \ 1116 (qemu_plugin_u64) {score, offsetof(type, member)} 1117 1118 /** 1119 * qemu_plugin_u64_add() - add a value to a qemu_plugin_u64 for a given vcpu 1120 * @entry: entry to query 1121 * @vcpu_index: entry index 1122 * @added: value to add 1123 */ 1124 QEMU_PLUGIN_API 1125 void qemu_plugin_u64_add(qemu_plugin_u64 entry, unsigned int vcpu_index, 1126 uint64_t added); 1127 1128 /** 1129 * qemu_plugin_u64_get() - get value of a qemu_plugin_u64 for a given vcpu 1130 * @entry: entry to query 1131 * @vcpu_index: entry index 1132 */ 1133 QEMU_PLUGIN_API 1134 uint64_t qemu_plugin_u64_get(qemu_plugin_u64 entry, unsigned int vcpu_index); 1135 1136 /** 1137 * qemu_plugin_u64_set() - set value of a qemu_plugin_u64 for a given vcpu 1138 * @entry: entry to query 1139 * @vcpu_index: entry index 1140 * @val: new value 1141 */ 1142 QEMU_PLUGIN_API 1143 void qemu_plugin_u64_set(qemu_plugin_u64 entry, unsigned int vcpu_index, 1144 uint64_t val); 1145 1146 /** 1147 * qemu_plugin_u64_sum() - return sum of all vcpu entries in a scoreboard 1148 * @entry: entry to sum 1149 */ 1150 QEMU_PLUGIN_API 1151 uint64_t qemu_plugin_u64_sum(qemu_plugin_u64 entry); 1152 1153 #endif /* QEMU_QEMU_PLUGIN_H */ 1154