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