> From: Peter Maydell [mailto:peter.mayd...@linaro.org] > > This series doesn't seem to add anything to Documentation/ that > describes the API we make available to plugins. I'm a lot more > interested in reviewing the API that will be used by plugins > than I am in the implementation at this stage. Can you provide > a description/documentation of the API for review, please?
Here is the draft: Introduction ============ This document describes an API for creating the QEMU instrumentation plugins. It is based on the following prior sources: - KVM Forum 2017 talk "Instrumenting, Introspection, and Debugging with QEMU" https://www.linux-kvm.org/images/3/3d/Introspect.pdf - Discussion on Lluis Vilanova instrumentation patch series https://lists.gnu.org/archive/html/qemu-devel/2017-09/msg03357.html The aim of the instrumentation is implementing different runtime tracers that can track the executed instructions, memory and hardware operations. Instrumenting the code ====================== Instrumentation subsystem exploits TCG helper mechanism to embed callbacks into the translation blocks. These callbacks may be inserted before the specific instructions, when the plugins require such filtering. Translator uses two functions for embedding the callbacks: - first function checks whether the current instruction should be instrumented - second function embeds the callback for executing the plugin-specific code before that instruction The similar method may be used for memory access instrumentation. QEMU->Plugin API ================ Instrumentation layer passes the requests from the translator to the dynamically loaded plugins. Every plugin may provide the following functions to perform the instrumentation: 1. bool plugin_init(const char *args); Initialization function. May return false if the plugin can't work in the current environment. 2. bool plugin_needs_before_insn(uint64_t pc, void *cpu); Returns true if the plugin needs to instrument the current instruction. It may use the address (pc) for making the decision or the guest CPU state (cpu), which can be passed back to QEMU core API (e.g., for reading the guest memory). This function is called at both translation and execution phases. 3. void plugin_before_insn(uint64_t pc, void *cpu); If the previous function returned true for some instruction, then this function will be called. This process is repeated before every execution of the instruction, if it was instrumented. The similar pair of functions will also be added for the memory operations. Plugin->QEMU API ================ QEMU core exports some functions to let the plugins introspect the guest or perform some interaction with other QEMU services (e.g., logging). API doesn't contain any data structures, because their memory layout depend on the compilation settings. QEMU exports the following functions that may be called from the plugins: 1. void qemulib_log(const char *fmt, ...); Wrapper for qemu_log. 2. int qemulib_read_memory(void *cpu, uint64_t addr, uint8_t *buf, int len); Reads guest memory into the buffer. Wrapper for cpu_memory_rw_debug. 3. int qemulib_read_register(void *cpu, uint8_t *mem_buf, int reg); Uses target gdb interface for accessing the guest registers. 'reg' is the id of the desired register as it is coded by gdb. There also should be a function for flushing the translated blocks to ensure that the instrumentation will occur in the case of changing the internal plugin state.
