Skip to main content
summaryrefslogtreecommitdiffstats
blob: 63ff07638797dd2d8ce24933f472ee7e9e8481e5 (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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
/*******************************************************************************
 * Copyright (c) 2007, 2015 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
 *******************************************************************************/

/*
 * Symbols service.
 */

#ifndef D_symbols
#define D_symbols

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

/*
 * Symbol information can change at any time as result of target background activities.
 * Clients should not cache symbol information, and should not retain the information
 * longer than one dispatch cycle.
 */

typedef struct Symbol Symbol;
typedef struct FunctionCallInfo FunctionCallInfo;

#define SYM_CLASS_UNKNOWN       0
#define SYM_CLASS_VALUE         1   /* Symbol represents a constant value */
#define SYM_CLASS_REFERENCE     2   /* Symbol is an address of an object (variable) in memory */
#define SYM_CLASS_FUNCTION      3   /* Symbol is an address of a function */
#define SYM_CLASS_TYPE          4   /* Symbol represents a type declaration */
#define SYM_CLASS_COMP_UNIT     5   /* Symbol represents a compilation unit */
#define SYM_CLASS_BLOCK         6   /* Symbol represents a block of code */
#define SYM_CLASS_NAMESPACE     7   /* Symbol represents a namespace */
#define SYM_CLASS_VARIANT_PART  8   /* Symbol represents a variant part of a structure */
#define SYM_CLASS_VARIANT       9   /* Symbol represents a member of a variant part of a structure */

#define TYPE_CLASS_UNKNOWN      0
#define TYPE_CLASS_CARDINAL     1
#define TYPE_CLASS_INTEGER      2
#define TYPE_CLASS_REAL         3
#define TYPE_CLASS_POINTER      4
#define TYPE_CLASS_ARRAY        5
#define TYPE_CLASS_COMPOSITE    6
#define TYPE_CLASS_ENUMERATION  7
#define TYPE_CLASS_FUNCTION     8
#define TYPE_CLASS_MEMBER_PTR   9
#define TYPE_CLASS_COMPLEX      10

typedef uint32_t SYM_FLAGS;

#define SYM_FLAG_PARAMETER      0x00000001
#define SYM_FLAG_TYPEDEF        0x00000002
#define SYM_FLAG_CONST_TYPE     0x00000004
#define SYM_FLAG_PACKET_TYPE    0x00000008
#define SYM_FLAG_SUBRANGE_TYPE  0x00000010
#define SYM_FLAG_VOLATILE_TYPE  0x00000020
#define SYM_FLAG_RESTRICT_TYPE  0x00000040
#define SYM_FLAG_UNION_TYPE     0x00000080
#define SYM_FLAG_CLASS_TYPE     0x00000100
#define SYM_FLAG_INTERFACE_TYPE 0x00000200
#define SYM_FLAG_SHARED_TYPE    0x00000400
#define SYM_FLAG_REFERENCE      0x00000800
#define SYM_FLAG_BIG_ENDIAN     0x00001000
#define SYM_FLAG_LITTLE_ENDIAN  0x00002000
#define SYM_FLAG_OPTIONAL       0x00004000
#define SYM_FLAG_EXTERNAL       0x00008000
#define SYM_FLAG_VARARG         0x00010000
#define SYM_FLAG_ARTIFICIAL     0x00020000
#define SYM_FLAG_TYPE_PARAMETER 0x00040000
#define SYM_FLAG_PRIVATE        0x00080000
#define SYM_FLAG_PROTECTED      0x00100000
#define SYM_FLAG_PUBLIC         0x00200000
#define SYM_FLAG_ENUM_TYPE      0x00400000
#define SYM_FLAG_STRUCT_TYPE    0x00800000
#define SYM_FLAG_STRING_TYPE    0x01000000
#define SYM_FLAG_INHERITANCE    0x02000000
#define SYM_FLAG_BOOL_TYPE      0x04000000
#define SYM_FLAG_INDIRECT       0x08000000
#define SYM_FLAG_RVALUE         0x10000000

/* Additional (uncommon) symbol properties */
typedef struct SymbolProperties {
    int binary_scale;   /* The exponent of the base two scale factor to be applied to an instance of the type */
    int decimal_scale;  /* The exponent of the base ten scale factor to be applied to an instance of the type */
} SymbolProperties;

/* Symbol properties update policies */
#define UPDATE_ON_MEMORY_MAP_CHANGES 0
#define UPDATE_ON_EXE_STATE_CHANGES  1

typedef void EnumerateSymbolsCallBack(void *, Symbol *);

#if ENABLE_DebugContext

typedef struct LocationCommands {
    LocationExpressionCommand * cmds;
    unsigned cnt;
    unsigned max;
} LocationCommands;

typedef struct DiscriminantRange {
    int64_t x;
    int64_t y;
} DiscriminantRange;

typedef struct LocationInfo {
    ContextAddress code_addr;
    ContextAddress code_size;
    int big_endian;
    unsigned args_cnt;
    LocationCommands value_cmds;
    DiscriminantRange * discr_lst;
    unsigned discr_cnt;
} LocationInfo;

/* Stack tracing command sequence */
typedef struct StackFrameRegisterLocation {
    RegisterDefinition * reg;
    unsigned cmds_cnt;
    unsigned cmds_max;
    LocationExpressionCommand cmds[1];
} StackFrameRegisterLocation;

typedef struct StackFrameInlinedSubroutine {
    const char * func_id;
    CodeArea area;
} StackFrameInlinedSubroutine;

/* Complete stack tracing info for a range of instruction addresses */
typedef struct StackTracingInfo {
    ContextAddress addr;
    ContextAddress size;
    StackFrameRegisterLocation * fp;
    StackFrameRegisterLocation ** regs;
    int reg_cnt;
    StackFrameInlinedSubroutine ** subs;
    int sub_cnt;
} StackTracingInfo;

#endif

#if ENABLE_Symbols

/*
 * Find symbol information for given symbol name in given context.
 * On error, returns -1 and sets errno.
 * On success returns 0.
 */
extern int find_symbol_by_name(Context * ctx, int frame, ContextAddress ip, const char * name, Symbol ** sym);

/*
 * Find symbol information for given symbol name in given context and visibility scope.
 * On error, returns -1 and sets errno.
 * On success returns 0.
 */
extern int find_symbol_in_scope(Context * ctx, int frame, ContextAddress ip, Symbol * scope, const char * name, Symbol ** sym);

/*
 * Find symbol information for given address in given context.
 * On error, returns -1 and sets errno.
 * On success returns 0.
 */
extern int find_symbol_by_addr(Context * ctx, int frame, ContextAddress addr, Symbol ** sym);

/*
 * find_symbol_* functions return first symbol that matches the search criteria.
 * Clients can use find_next_symbol() to get the rest of matching symbols,
 * for example, to get all symbols for overloaded functions.
 */
extern int find_next_symbol(Symbol ** sym);

/*
 * Enumerate symbols in given context.
 * If frame >= 0 enumerates local symbols and function arguments.
 * If frame < 0 enumerates global symbols.
 * On error returns -1 and sets errno.
 * On success returns 0.
 */
extern int enumerate_symbols(Context * ctx, int frame, EnumerateSymbolsCallBack *, void * args);

/*
 * Get (relatively) permanent symbol ID that can be used across dispatch cycles.
 */
extern const char * symbol2id(const Symbol * sym);

/*
 * Find symbol by symbol ID.
 * On error, returns -1 and sets errno.
 * On success returns 0.
 */
extern int id2symbol(const char * id, Symbol ** sym);

/*************** Functions for retrieving symbol properties ***************************************/
/*
 * Each function retrieves one particular attribute of an object or type.
 * On error returns -1 and sets errno.
 * On success returns 0.
 */

/* Get symbol class */
extern int get_symbol_class(const Symbol * sym, int * symbol_class);

/* Get symbol type.
 * If the symbol is a modified type, like "volatile int", return original (unmodified) type.
 * If the symbol is unmodified type, return the symbol itself. */
extern int get_symbol_type(const Symbol * sym, Symbol ** type);

/* Get type class, see TYPE_CLASS_* */
extern int get_symbol_type_class(const Symbol * sym, int * type_class);

/* Get symbol owner ID and update policy ID.
 * Symbol owner can be memory space or executable context.
 * Certain changes in owner state can invalidate cached symbol properties.
 * Update policy ID selects a specific set of rules that a client should follow
 * if it wants to cache symbol properties.
 * The string returned shall not be modified by the client,
 * and it may be overwritten by a subsequent calls to symbol functions */
extern int get_symbol_update_policy(const Symbol * sym, char ** parent_id, int * policy);

/* Get symbol name.
 * The string returned shall not be modified by the client,
 * and it may be overwritten by a subsequent calls to symbol functions */
extern int get_symbol_name(const Symbol * sym, char ** name);

/* Get value size of the type, in bytes */
extern int get_symbol_size(const Symbol * sym, ContextAddress * size);

/* Get base type: pointer or member pointer - pointed object type,
 * array - elements type, function - result type */
extern int get_symbol_base_type(const Symbol * sym, Symbol ** base_type);

/* Get array index type */
extern int get_symbol_index_type(const Symbol * sym, Symbol ** index_type);

/* Get containing type: field (member) or member pointer - parent structure */
extern int get_symbol_container(const Symbol * sym, Symbol ** container);

/* Get array length (number of elements) */
extern int get_symbol_length(const Symbol * sym, ContextAddress * length);

/* Get array index lower bound (index of first element) */
extern int get_symbol_lower_bound(const Symbol * sym, int64_t * value);

/* Get children IDs of a type (struct, union, class, function and enum).
 * The array returned is allocated by tmp_alloc() */
extern int get_symbol_children(const Symbol * sym, Symbol *** children, int * count);

/* Get offset in parent type (fields) */
extern int get_symbol_offset(const Symbol * sym, ContextAddress * offset);

/* Get value (constant objects and enums).
 * The array returned shall not be modified by the client,
 * and it may be overwritten by a subsequent calls to symbol functions */
extern int get_symbol_value(const Symbol * sym, void ** value, size_t * size, int * big_endian);

/* Get address (variables) */
extern int get_symbol_address(const Symbol * sym, ContextAddress * address);

/* Get register if the symbol is a register variable */
extern int get_symbol_register(const Symbol * sym, Context ** ctx, int * frame, RegisterDefinition ** reg);

/* Get symbol flags, see SYM_FLAG_* */
extern int get_symbol_flags(const Symbol * sym, SYM_FLAGS * flags);

/* Get additional symbol properties, see SymbolProperties */
extern int get_symbol_props(const Symbol * sym, SymbolProperties * props);

/* Get symbol stack frame */
extern int get_symbol_frame(const Symbol * sym, Context ** ctx, int * frame);

/* Get a type that represents an array of elements of given base type.
 * If 'length' is zero, returned type represents pointer to given type */
extern int get_array_symbol(const Symbol * sym, ContextAddress length, Symbol ** ptr);

/*************************************************************************************************/

/*
 * Check if given address is inside a PLT section, then return run-time address of the section.
 * Return 0 and set errno in case of an error.
 * If not a PLT address, return 0;
 */
extern ContextAddress is_plt_section(Context * ctx, ContextAddress addr);

/*
 * Get instruction set architecture name for given address in a context memory.
 * 'range_addr' and 'range_size' are assigned an address range of same ISA.
 * Return -1 and set errno in case of an error.
 * Return 0 on success.
 */
extern int get_context_isa(Context * ctx, ContextAddress addr, const char ** isa,
        ContextAddress * range_addr, ContextAddress * range_size);

/*
 * Get object location information
 * Return -1 and set errno in case of an error.
 * Return 0 on success.
 */
extern int get_location_info(const Symbol * sym, LocationInfo ** info);

/*
 * Get information about function call injection.
 * Return -1 and set errno in case of an error.
 * Return 0 on success.
 */
extern int get_funccall_info(const Symbol * func,
        const Symbol ** args, unsigned args_cnt, FunctionCallInfo ** info);

/*
 * For given context and instruction address,
 * search for stack tracing information.
 * Return -1 and set errno in case of an error.
 * Return 0 on success.
 * Set 'info' to NULL if no stack tracing information found for the address.
 */
extern int get_stack_tracing_info(Context * ctx, ContextAddress addr, StackTracingInfo ** info);

/*
 * Get name of a symbol file that is used for a given module.
 */
extern const char * get_symbol_file_name(Context * ctx, MemoryRegion * module);

/*
 * Initialize symbol service.
 */
extern void ini_symbols_service(Protocol * proto);
extern void ini_symbols_lib(void);

#endif /* ENABLE_Symbols */

#endif /* D_symbols */

Back to the top