Skip to main content
summaryrefslogtreecommitdiffstats
blob: 9fedc3c033236ef8948c566f7dd6ad315b0d5725 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
/*******************************************************************************
 * Copyright (c) 2007, 2010 Wind River Systems, Inc. and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * and Eclipse Distribution License v1.0 which accompany this distribution.
 * The Eclipse Public License is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 * You may elect to redistribute this code under either of these licenses.
 *
 * Contributors:
 *     Wind River Systems - initial API and implementation
 *******************************************************************************/

/*
 * This module implements Breakpoints service.
 * The service maintains a list of breakpoints.
 * Each breakpoint consists of one or more conditions that determine
 * when a program's execution should be interrupted.
 */

#ifndef D_breakpoints
#define D_breakpoints

#include <tcf/framework/context.h>
#include <tcf/framework/protocol.h>

typedef struct BreakpointInfo BreakpointInfo;
typedef struct BreakpointAttribute BreakpointAttribute;

struct BreakpointAttribute {
    BreakpointAttribute * next;
    char * name;        /* Attribute name */
    char * value;       /* Attribute value as JSON string */
};

#if SERVICE_Breakpoints

/*
 * Breakpoint attribute names.
 * Clients may define additional attributes.
 */
#define BREAKPOINT_ID               "ID"
#define BREAKPOINT_ENABLED          "Enabled"
#define BREAKPOINT_TYPE             "BreakpointType"
#define BREAKPOINT_CONTEXTNAMES     "ContextNames"
#define BREAKPOINT_CONTEXTIDS       "ContextIds"
#define BREAKPOINT_EXECUTABLEPATHS  "ExecPaths"
#define BREAKPOINT_LOCATION         "Location"
#define BREAKPOINT_SIZE             "Size"
#define BREAKPOINT_ACCESSMODE       "AccessMode"
#define BREAKPOINT_FILE             "File"
#define BREAKPOINT_LINE             "Line"
#define BREAKPOINT_COLUMN           "Column"
#define BREAKPOINT_PATTERN          "MaskValue"
#define BREAKPOINT_MASK             "Mask"
#define BREAKPOINT_STOP_GROUP       "StopGroup"
#define BREAKPOINT_IGNORECOUNT      "IgnoreCount"
#define BREAKPOINT_TIME             "Time"
#define BREAKPOINT_SCALE            "TimeScale"
#define BREAKPOINT_UNITS            "TimeUnits"
#define BREAKPOINT_CONDITION        "Condition"
#define BREAKPOINT_TEMPORARY        "Temporary"
#define BREAKPOINT_CLIENT_DATA      "ClientData"


/* Breakpoints event listener */
typedef struct BreakpointsEventListener {
    void (*breakpoint_created)(BreakpointInfo *, void *);
    void (*breakpoint_changed)(BreakpointInfo *, void *);
    void (*breakpoint_deleted)(BreakpointInfo *, void *);
    void (*breakpoint_status_changed)(BreakpointInfo *, void *);
} BreakpointsEventListener;

/*
 * Add a listener for Breakpoints service events.
 */
extern void add_breakpoint_event_listener(BreakpointsEventListener * listener, void * args);

/*
 * Remove a listener of Breakpoints service events.
 */
extern void rem_breakpoint_event_listener(BreakpointsEventListener * listener);

/*
 * Iterate all breakpoints known to the Breakpoints service,
 * including breakpoints that are created by other (remote) clients.
 */
typedef void IterateBreakpointsCallBack(BreakpointInfo *, void *);
extern void iterate_breakpoints(IterateBreakpointsCallBack * callback, void * args);

/*
 * Get breakpoint attributes.
 */
extern BreakpointAttribute * get_breakpoint_attributes(BreakpointInfo * bp);

/*
 * Create new breakpoint with given attributes.
 * Attributes must include, at least, BREAKPOINT_ID.
 * If a breakpoint with such ID already exists, it will be modified to match
 * new attributes instead of creating a new one.
 * Caller should allocate attributes using myalloc.h functions.
 * Breakpoints service will free attributes memory using loc_free().
 */
extern BreakpointInfo * create_breakpoint(BreakpointAttribute * attrs);

/*
 * Change breakpoint attributes to given attributes.
 * Caller should allocate attributes using myalloc.h functions.
 * Breakpoints service will free attributes memory using loc_free().
 * The function compares existing attributes with new ones,
 * and calls listeners only if attributes are different.
 */
extern void change_breakpoint_attributes(BreakpointInfo * bp, BreakpointAttribute * attrs);

/*
 * Delete a breakpoint.
 * If other (remote) client also created a breakpoint with same ID,
 * the breakpoint will be deleted when all clients have requested it to be deleted.
 */
extern void delete_breakpoint(BreakpointInfo * bp);

/*
 * Iterate all breakpoints that are linked to context breakpoint 'cb' in the breakpoint address space
 * associated with executable context 'ctx'. Breakpoint address space is the context returned by
 * context_get_group(ctx, CONTEXT_GROUP_BREAKPOINT).
 * Single 'cb' can be linked to multiple breakpoints if those breakpoint locations are evaluated
 * to same address in same address space. Single breakpoint can be linked to multiple CBs if the
 * breakpoint scope spawns multiple address spaces.
 */
typedef void IterateCBLinksCallBack(BreakpointInfo *, void *);
extern void iterate_context_breakpoint_links(Context * ctx, ContextBreakpoint * cb, IterateCBLinksCallBack * callback, void * args);

/*
 * The function is called from context.c every time a context is stopped by a breakpoint.
 * The function evaluates breakpoint condition and calls suspend_debug_context() if the condition is true.
 */
extern void evaluate_breakpoint(Context * ctx);

/*
 * Return NULL-terminated array of breakpoint IDs if the context is stopped by breakpoint.
 * Otherwise return NULL.
 */
extern char ** get_context_breakpoint_ids(Context * ctx);

/*
 * When a context is stopped by breakpoint, it is necessary to disable
 * the breakpoint temporarily before the context can be resumed.
 * This function function removes break instruction, then does single step
 * over breakpoint location, then restores break intruction.
 * Return 0 if it is OK to resume context from current state,
 * return 1 if context needs to step over a breakpoint.
 */
extern int skip_breakpoint(Context * ctx, int single_step);

/* Return 1 if break instruction is planted at given address in the context memory */
extern int is_breakpoint_address(Context * ctx, ContextAddress address);

/* Clone all planted breakpoints when a process forks */
extern void clone_breakpoints_on_process_fork(Context * parent, Context * child);

/* Unplant all breakpoints in a process (e.g. before detaching) */
extern void unplant_breakpoints(Context * ctx);

/*
 * Check if memory data buffer contans planted break instructions and remove them.
 * Return -1 and set errno if the check cannot be done.
 */
extern int check_breakpoints_on_memory_read(Context * ctx, ContextAddress address, void * buf, size_t size);

/*
 * Check if data is about to be written over planted break instructions and adjust the data and breakpoint backing storage
 * Return -1 and set errno if the check cannot be done.
 * Return 0 on success.
 */
extern int check_breakpoints_on_memory_write(Context * ctx, ContextAddress address, void * buf, size_t size);

/* Evenpoint callback. It is called when context is suspended by eventpoint, right before "context_stopped" event */
typedef void EventPointCallBack(Context *, void *);

/* Create, plant and return eventpoint. Eventpoints are breakpoints that are created by agent to control execution of debugee.
 * Eventpoint are not exposed through "Breakpoints" TCF service, they are handled by agent itself. */
extern BreakpointInfo * create_eventpoint(const char * location, Context * ctx, EventPointCallBack * callback, void * callback_args);

/* Unplant and destroy eventpoint */
extern void destroy_eventpoint(BreakpointInfo * eventpoint);

#else /* SERVICE_Breakpoints */

#define skip_breakpoint(ctx, single_step) 0
#define is_breakpoint_address(ctx, address) 0
#define clone_breakpoints_on_process_fork(parent, child) 0
#define unplant_breakpoints(ctx) 0
#define check_breakpoints_on_memory_read(ctx, address, buf, size) 0
#define check_breakpoints_on_memory_write(ctx, address, buf, size) 0
#define create_eventpoint(location, ctx, callback, callback_args) 0

#endif /* SERVICE_Breakpoints */

extern void ini_breakpoints_service(Protocol *, TCFBroadcastGroup *);

#endif /* D_breakpoints */

Back to the top