1/* Copyright (C) 2007-2010 The Android Open Source Project 2** 3** This software is licensed under the terms of the GNU General Public 4** License version 2, as published by the Free Software Foundation, and 5** may be copied, distributed, and modified under those terms. 6** 7** This program is distributed in the hope that it will be useful, 8** but WITHOUT ANY WARRANTY; without even the implied warranty of 9** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10** GNU General Public License for more details. 11*/ 12 13/* 14 * Contains declarations of types, constants, and routines used by memory 15 * checking framework. 16 */ 17 18#ifndef QEMU_MEMCHECK_MEMCHECK_H 19#define QEMU_MEMCHECK_MEMCHECK_H 20 21/* This file should compile iff qemu is built with memory checking 22 * configuration turned on. */ 23#ifndef CONFIG_MEMCHECK 24#error CONFIG_MEMCHECK is not defined. 25#endif // CONFIG_MEMCHECK 26 27#include "memcheck_common.h" 28 29#ifdef __cplusplus 30extern "C" { 31#endif 32 33/* Initializes memory access checking framework. 34 * This routine is called from emulator's main routine on condition, 35 * that emulator has been started with -memcheck option. 36 * Param: 37 * tracing_flags - Parameters set for the -memcheck option. These parameters 38 * contain abbreviation for memchecking tracing messages that should be enabled 39 * for the emulator and guest systems. 40 */ 41void memcheck_init(const char* tracing_flags); 42 43// ============================================================================= 44// Handlers for memory allocation events, generated by the guest system. 45// ============================================================================= 46 47/* Libc.so has been initialized by a process in guest's system. 48 * This routine is called in response to TRACE_DEV_REG_LIBC_INIT event that is 49 * fired up by the guest system on /dev/qemu_trace mapped page. 50 * Param: 51 * pid - ID of the process in context of which libc.so has been initialized. 52 */ 53void memcheck_guest_libc_initialized(uint32_t pid); 54 55/* Guest system has allocated memory from heap. 56 * This routine is called in response to TRACE_DEV_REG_MALLOC event that is 57 * fired up by the guest system on /dev/qemu_trace mapped page. 58 * Param: 59 * guest_address - Virtual address of allocation descriptor (MallocDesc) that 60 * contains information about allocated memory block. Note that this 61 * descriptor is located in the guests's user memory. Note also that 62 * emulator reports failure back to the guest by zeroing out libc_pid field 63 * of the structure, addressed by this parameter. 64 */ 65void memcheck_guest_alloc(target_ulong guest_address); 66 67/* Guest system is freeing memory to heap. 68 * This routine is called in response to TRACE_DEV_REG_FREE_PTR event, 69 * fired up by the guest system on /dev/qemu_trace mapped page. 70 * Param: 71 * guest_address - Virtual address of free descriptor (MallocFree) that 72 * contains information about memory block that's being freed. Note that 73 * this descriptor is located in the guests's user memory. Note also that 74 * emulator reports failure back to the guest by zeroing out libc_pid field 75 * of the structure, addressed by this parameter. 76 */ 77void memcheck_guest_free(target_ulong guest_address); 78 79/* Guest system has queried information about an address in its virtual memory. 80 * This routine is called in response to TRACE_DEV_REG_QUERY_MALLOC event, 81 * fired up by the guest system on /dev/qemu_trace mapped page. 82 * Param: 83 * guest_address - Virtual address in the guest's space of the MallocDescQuery 84 * structure, that describes the query and receives the response. Note 85 * that emulator reports failure back to the guest by zeroing out libc_pid 86 * field of the structure, addressed by this parameter. 87 */ 88void memcheck_guest_query_malloc(target_ulong guest_address); 89 90/* Prints a string to emulator's stdout. 91 * This routine is called in response to TRACE_DEV_REG_PRINT_USER_STR event, 92 * fired up by the guest system on /dev/qemu_trace mapped page. 93 * Param: 94 * str - Virtual address in the guest's space of the string to print. 95 */ 96void memcheck_guest_print_str(target_ulong str); 97 98// ============================================================================= 99// Handlers for events, generated by the kernel. 100// ============================================================================= 101 102/* Handles PID initialization event. 103 * This routine is called in response to TRACE_DEV_REG_INIT_PID event, which 104 * indicates that new process has been initialized (but not yet executed). 105 * Param: 106 * pid - ID of the process that is being initialized. This value will also be 107 * used as main thread ID for the intializing process. 108 */ 109void memcheck_init_pid(uint32_t pid); 110 111/* Handles thread switch event. 112 * This routine is called in response to TRACE_DEV_REG_SWITCH event, which 113 * indicates that thread switch occurred in the guest system. 114 * Param: 115 * tid - ID of the thread that becomes active. 116 */ 117void memcheck_switch(uint32_t tid); 118 119/* Handles process forking / new process creation event. 120 * This routine is called in response to TRACE_DEV_REG_FORK event, which 121 * indicates that new process has been forked / created. It's assumed, that 122 * process that is forking new process is the current process. 123 * Param: 124 * tgid - TODO: Clarify that! 125 * new_pid - Process ID that's been assigned to the forked process. 126 */ 127void memcheck_fork(uint32_t tgid, uint32_t new_pid); 128 129/* Handles new thread creation event. 130 * This routine is called in response to TRACE_DEV_REG_CLONE event, which 131 * indicates that new thread has been created in context of the current process. 132 * Param: 133 * tgid - TODO: Clarify that! 134 * new_tid - Thread ID that's been assigned to the new thread. 135 */ 136void memcheck_clone(uint32_t tgid, uint32_t new_tid); 137 138/* Sets process command line. 139 * This routine is called in response to TRACE_DEV_REG_CMDLINE event, which 140 * is used to grab first command line argument, and use it is image path to 141 * the current process. 142 * Param: 143 * cmg_arg - Command line arguments. 144 * cmdlen - Length of the command line arguments string. 145 */ 146void memcheck_set_cmd_line(const char* cmd_arg, unsigned cmdlen); 147 148/* Handles thread / process exiting event. 149 * This routine is called in response to TRACE_DEV_REG_EXIT event, which 150 * indicates that current thread is exiting. We consider that process is 151 * exiting when last thread for that process is exiting. 152 * Param: 153 * exit_code - Thread exit code. 154 */ 155void memcheck_exit(uint32_t exit_code); 156 157/* Handles memory mapping of a module in guest address space. 158 * This routine is called in response to TRACE_DEV_REG_EXECVE_VMSTART, 159 * TRACE_DEV_REG_EXECVE_VMEND, TRACE_DEV_REG_EXECVE_OFFSET, and 160 * TRACE_DEV_REG_MMAP_EXEPATH events, which indicate that a module has been 161 * loaded and mapped on the guest system. 162 * Param: 163 * vstart - Guest address where mapping starts. 164 * vend - Guest address where mapping ends. 165 * exec_offset - Exec offset inside module mapping. 166 * path - Path to the module that has been mapped. 167 */ 168void memcheck_mmap_exepath(target_ulong vstart, 169 target_ulong vend, 170 target_ulong exec_offset, 171 const char* path); 172 173/* Handles memory unmapping of a module in guest address space. 174 * This routine is called in response to TRACE_DEV_REG_UNMAP_START, and 175 * TRACE_DEV_REG_UNMAP_END events, which indicate that a module has been 176 * unmapped on the guest system. 177 * Param: 178 * vstart - Guest address where unmapping starts. 179 * vend - Guest address where unmapping ends. 180 */ 181void memcheck_unmap(target_ulong vstart, target_ulong vend); 182 183/* Global flag, indicating whether or not memchecking has been enabled 184 * for the current emulator session. If set to zero, indicates that memchecking 185 * is not enabled. Value other than zero indicates that memchecking is enabled 186 * for the current emulator session. 187 */ 188extern int memcheck_enabled; 189 190#ifdef __cplusplus 191}; /* end of extern "C" */ 192#endif 193 194#endif // QEMU_MEMCHECK_MEMCHECK_H 195