qemu-plugin.h · samitouri/QOSamiQemu

Code Commits Issues Pulls Sessions CI/CD

master

h 1,370 lines 47.4 KB

Raw

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