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