Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 807ee6cca1dbb1f96c3e6b997119dcb05a7905e3 (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
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
#******************************************************************************
# * Copyright (c) 2011 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
# * which accompanies this distribution, and is available at
# * http://www.eclipse.org/legal/epl-v10.html
# *
# * Contributors:
# *     Wind River Systems - initial API and implementation
#******************************************************************************

from tcf import services

# Service name.
NAME = "Symbols"

class SymbolClass:
    unknown = 0                # unknown symbol class
    value = 1                  # constant value
    reference = 2              # variable data object
    function = 3               # function body
    type = 4                   # a type

class TypeClass:
    unknown = 0                # unknown type class
    cardinal = 1               # unsigned integer
    integer = 2                # signed integer
    real = 3                   # float, double
    pointer = 4                # pointer to anything.
    array = 5                  # array of anything.
    composite = 6              # struct, union, or class.
    enumeration = 7            # enumeration type.
    function = 8               # function type.

#
# Symbol context property names.
#
PROP_ID = "ID"
PROP_OWNER_ID = "OwnerID"
PROP_UPDATE_POLICY = "UpdatePolicy"
PROP_NAME = "Name"
PROP_SYMBOL_CLASS = "Class"
PROP_TYPE_CLASS = "TypeClass"
PROP_TYPE_ID = "TypeID"
PROP_BASE_TYPE_ID = "BaseTypeID"
PROP_INDEX_TYPE_ID = "IndexTypeID"
PROP_SIZE = "Size"
PROP_LENGTH = "Length"
PROP_LOWER_BOUND = "LowerBound"
PROP_UPPER_BOUND = "UpperBound"
PROP_OFFSET = "Offset"
PROP_ADDRESS = "Address"
PROP_VALUE = "Value"
PROP_BIG_ENDIAN = "BigEndian"
PROP_REGISTER = "Register"

#
# Symbol context properties update policies.
#

# Update policy "Memory Map": symbol properties become invalid when
# memory map changes - when modules are loaded or unloaded.
# Symbol OwnerID indicates memory space (process) that is invalidation events source.
# Most static variables and types have this update policy.
UPDATE_ON_MEMORY_MAP_CHANGES = 0

# Update policy "Execution State": symbol properties become invalid when
# execution state changes - a thread is suspended, resumed or exited.
# Symbol OwnerID indicates executable context (thread) that is invalidation events source.
# Most stack (auto) variables have this update policy.
UPDATE_ON_EXE_STATE_CHANGES = 1


class Symbol(object):
    """
    Symbol context interface.
    """
    def __init__(self, props):
        self._props = props or {}

    def __str__(self):
        return "[Symbol Context %s]" % self._props

    def getID(self):
        """
        Get symbol ID.
        @return symbol ID.
        """
        return self._props.get(PROP_ID)

    def getOwnerID(self):
        """
        Get symbol owner ID.
        The owner can a thread or memory space (process).
        Certain changes in owner state can invalidate cached symbol properties,
        see getUpdatePolicy() and UPDATE_*.
        """
        return self._props.get(PROP_OWNER_ID)

    def getUpdatePolicy(self):
        """
        Get symbol properties update policy ID.
        Symbol properties can change during program execution.
        If a client wants to cache symbols, it should invalidate cached data
        according to update policies of cached symbols.
        @return symbol update policy ID, see UPDATE_*
        """
        return self._props.get(PROP_UPDATE_POLICY)

    def getName(self):
        """
        Get symbol name.
        @return symbol name or null.
        """
        return self._props.get(PROP_NAME)

    def getSymbolClass(self):
        """
        Get symbol class.
        @return symbol class.
        """
        return self._props.get(PROP_SYMBOL_CLASS)

    def getTypeClass(self):
        """
        Get symbol type class.
        @return type class.
        """
        return self._props.get(PROP_TYPE_CLASS)

    def getTypeID(self):
        """
        Get type ID.
        If the symbol is a type and not a 'typedef', return same as getID().
        @return type ID.
        """
        return self._props.get(PROP_TYPE_ID)

    def getBaseTypeID(self):
        """
        Get base type ID.
        If this symbol is a
          pointer type - return pointed type
          array type - return element type
          function type - return function result type
          class type - return base class
        otherwise return null.
        @return type ID.
        """
        return self._props.get(PROP_BASE_TYPE_ID)

    def getIndexTypeID(self):
        """
        Get index type ID.
        If this symbol is a
          array type - return array index type
        otherwise return null.
        @return type ID.
        """
        return self._props.get(PROP_INDEX_TYPE_ID)

    def getSize(self):
        """
        Return value size of the symbol (or type).
        @return size in bytes.
        """
        return self._props.get(PROP_SIZE, 0)

    def getLength(self):
        """
        If symbol is an array type - return number of elements.
        @return number of elements.
        """
        return self._props.get(PROP_LENGTH, 0)

    def getLowerBound(self):
        """
        If symbol is an array type - return array index lower bound.
        @return lower bound.
        """
        return self._props.get(PROP_LOWER_BOUND)

    def getUpperBound(self):
        """
        If symbol is an array type - return array index upper bound.
        @return upper bound.
        """
        return self._props.get(PROP_UPPER_BOUND)

    def getOffset(self):
        """
        Return offset from 'this' for member of class, struct or union.
        @return offset in bytes.
        """
        return self._props.get(PROP_OFFSET, 0)

    def getAddress(self):
        """
        Return address of the symbol.
        @return address or null.
        """
        return self._props.get(PROP_ADDRESS)

    def getValue(self):
        """
        If symbol is a constant object, return its value.
        @return symbol value as array of bytes.
        """
        return self._props.get(PROP_VALUE)

    def isBigEndian(self):
        """
        Get symbol values endianness.
        @return true if symbol is big-endian.
        """
        return self._props.get(PROP_BIG_ENDIAN, False)

    def getRegisterID(self):
        """
        Return register ID if the symbol represents a register variable.
        @return register ID or null.
        """
        return self._props.get(PROP_REGISTER)

    def getProperties(self):
        """
        Get complete map of context properties.
        @return map of context properties.
        """
        return self._props

class SymbolsService(services.Service):
    def getName(self):
        return NAME

    def getContext(self, id, done):
        """
        Retrieve symbol context info for given symbol ID.
        @see Symbol

        @param id - symbol context ID.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def getChildren(self, parent_context_id, done):
        """
        Retrieve children IDs for given parent ID.
        Meaning of the operation depends on parent kind:
        1. struct, union, or class type - get fields
        2. enumeration type - get enumerators

        @param parent_context_id - parent symbol context ID.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def find(self, context_id, ip, name, done):
        """
        Search symbol with given name in given context.
        The context can be memory space, process, thread or stack frame.

        @param context_id - a search scope.
        @param ip - instruction pointer - ignored if context_id is a stack frame ID
        @param name - symbol name.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def findByAddr(self, context_id, addr, done):
        """
        Search symbol with given address in given context.
        The context can be memory space, process, thread or stack frame.

        @param context_id - a search scope.
        @param addr - symbol address.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def list(self, context_id, done):
        """
        List all symbols in given context.
        The context can be a stack frame.

        @param context_id - a scope.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def findFrameInfo(self, context_id, address, done):
        """
        Retrieve stack tracing commands for given instruction address in a context memory.
        @param context_id - exacutable context ID.
        @param address - instruction address.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

class DoneGetContext(object):
    """
    Client call back interface for getContext().
    """
    def doneGetContext(self, token, error, context):
        """
        Called when context data retrieval is done.
        @param token - command handle
        @param error - error description if operation failed, null if succeeded.
        @param context - context properties.
        """
        pass

class DoneGetChildren(object):
    """
    Client call back interface for getChildren().
    """
    def doneGetChildren(self, token, error, context_ids):
        """
        Called when context list retrieval is done.
        @param token - command handle
        @param error - error description if operation failed, null if succeeded.
        @param context_ids - array of available context IDs.
        """
        pass

class DoneFind(object):
    """
    Client call back interface for find().
    """
    def doneFind(self, token, error, symbol_id):
        """
        Called when symbol search is done.
        @param token - command handle.
        @param error - error description if operation failed, null if succeeded.
        @param symbol_id - symbol ID.
        """
        pass

class DoneList(object):
    """
    Client call back interface for list().
    """
    def doneList(self, token, error, symbol_ids):
        """
        Called when symbol list retrieval is done.
        @param token - command handle.
        @param error - error description if operation failed, null if succeeded.
        @param symbol_ids - array of symbol IDs.
        """


#
# Command codes that are used to calculate frame pointer and register values during stack tracing.
#

# Load a number to the evaluation stack. Command argument is the number.
CMD_NUMBER      = 1

# Load a register value to the evaluation stack. Command argument is the register ID.
CMD_REGISTER    = 2

# Load frame address to the evaluation stack.
CMD_FP          = 3

# Read memory at address on the top of the evaluation stack. Command arguments are
# the value size (Number) and endianness (Boolean, false - little-endian, true - big-endian).
CMD_DEREF       = 4

# Add two values on top of the evaluation stack
CMD_ADD         = 5

class DoneFindFrameInfo(object):
    """
    Client call back interface for findFrameInfo().
    """
    def doneFindFrameInfo(self, token, error, address, size, fp_cmds, reg_cmds):
        """
        Called when stack tracing information retrieval is done.
        @param token - command handle.
        @param error - error description if operation failed, null if succeeded.
        @param address - start of instruction address range
        @param size - size of instruction address range
        @param fp_cmds - commands to calculate stack frame pointer
        @param reg_cmds - map register IDs -> commands to calculate register values
        """
        pass

Back to the top