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