Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 38bc956832001e774eac54d5d61e6d716eae8bb5 (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
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
#******************************************************************************
# * Copyright (c) 2011, 2012 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 @ReservedAssignment
    comp_unit = 5              # a compilation unit
    block = 6                  # a block of code
    namespace = 7              # a namespace


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.
    member_ptr = 9             # a pointer on member type

SYM_FLAG_PARAMETER = 0x000001
SYM_FLAG_TYPEDEF = 0x000002
SYM_FLAG_CONST_TYPE = 0x000004
SYM_FLAG_PACKET_TYPE = 0x000008
SYM_FLAG_SUBRANGE_TYPE = 0x000010
SYM_FLAG_VOLATILE_TYPE = 0x000020
SYM_FLAG_RESTRICT_TYPE = 0x000040
SYM_FLAG_UNION_TYPE = 0x000080
SYM_FLAG_CLASS_TYPE = 0x000100
SYM_FLAG_INTERFACE_TYPE = 0x000200
SYM_FLAG_SHARED_TYPE = 0x000400
SYM_FLAG_REFERENCE = 0x000800
SYM_FLAG_BIG_ENDIAN = 0x001000
SYM_FLAG_LITTLE_ENDIAN = 0x002000
SYM_FLAG_OPTIONAL = 0x004000
SYM_FLAG_EXTERNAL = 0x008000
SYM_FLAG_VARARG = 0x010000
SYM_FLAG_ARTIFICIAL = 0x020000
SYM_FLAG_TYPE_PARAMETER = 0x040000
SYM_FLAG_PRIVATE = 0x080000
SYM_FLAG_PROTECTED = 0x100000
SYM_FLAG_PUBLIC = 0x200000
SYM_FLAG_ENUM_TYPE = 0x400000
SYM_FLAG_STRUCT_TYPE = 0x800000

#
# 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"
PROP_FLAGS = "Flags"
PROP_CONTAINER_ID = "ContainerID"

#
# 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 None.
        """
        return self._props.get(PROP_NAME)

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

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

    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 None.
        @return type ID.
        """
        return self._props.get(PROP_BASE_TYPE_ID)

    def getContainerID(self):
        """Get container type ID.
        If this symbol is a
            field or member - return containing class type;
            member pointer - return containing class type;
            otherwise return None.
        @return type ID.
        """
        return self._props.get(PROP_CONTAINER_ID)

    def getIndexTypeID(self):
        """
        Get index type ID.
        If this symbol is a
          array type - return array index type
        otherwise return None.
        @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 None.
        """
        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 None.
        """
        return self._props.get(PROP_REGISTER)

    def getFlags(self):
        """
        Get symbol flags.
        @return Symbol flags (see SYM_FLAG_ values).
        """
        return self._props.get(PROP_FLAGS, 0)

    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, contextID, done):
        """
        Retrieve symbol context info for given symbol ID.
        @see Symbol

        @param contextID - 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 first 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 findByName(self, context_id, ip, name, done):
        """
        Search symbols 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 findInScope(self, context_id, ip, scope_id, name, done):
        """
        Search symbols with given name in given context or in given symbol
        scope.
        The context can be memory space, process, thread or stack frame.
        The symbol scope can be any symbol.
        If ip is not null, the search of the symbol name is done first in the
        scope defined by @e context_id and @e ip.
        If the symbol is not found, the supplied scope is then used.

        @param context_id - a search scope.
        @param ip - instruction pointer. Can be null if only @e scope_id
                    should be used.
        @param scope_id - symbol context ID.
        @param name - symbol name.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def list(self, context_id, done):  # @ReservedAssignment
        """
        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 getArrayType(self, type_id, length, done):
        """
        Create an array type.

        @param type_id - symbol ID of the array cell type
        @param length - length of the array. A length of 0 creates a pointer
                        type.
        @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")

    def getLocationInfo(self, symbolID, done):
        """Retrieve symbol location information.
        @param symbol_id - symbol ID.
        @param done - call back interface called when operation is completed.
        @return - pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def getSymFileInfo(self, contextID, address, done):
        """Get symbol file info for a module that contains given address in a
        memory space.
        @param contextID - a memory space (process) ID.
        @param address - an address in the memory space.
        @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, None if
                       succeeded.
        @param context - context properties.
        """
        pass


class DoneGetLocationInfo(object):
    """Client call back interface for getLocationInfo()."""
    def doneGetLocationInfo(self, token, error, props):
        """Called when location information retrieval is done.
        @param token - command handle.
        @param error - error description if operation failed, None if
                       succeeded.
        @param props - symbol location properties, see LOC_ * .
        """
        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, None if
                       succeeded.
        @param context_ids - array of available context IDs.
        """
        pass


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


class DoneGetSymFileInfo(object):
    """Client call back interface for getSymFileInfo()."""
    def doneGetSymFileInfo(self, token, error, props):
        """Called when symbol file information retrieval is done.
        @param token - command handle.
        @param error - error description if operation failed, None if
                       succeeded.
        @param props - symbol file properties.
        """
        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, None if
                       succeeded.
        @param symbol_ids - array of symbol IDs.
        """


class DoneGetArrayType(object):
    """
    Client call back interface for getArrayType().
    """
    def doneGetArrayType(self, token, error, type_id):
        """
        Called when array type creation is done.
        @param token - command handle.
        @param error - error description if operation failed, None if
                       succeeded.
        @param type_id - array type symbol ID
        """


#
# 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 frame address to the evaluation stack.
CMD_FP = 3

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

CMD_SUB = 6
CMD_MUL = 7
CMD_DIV = 8
CMD_AND = 9
CMD_OR = 10
CMD_XOR = 11
CMD_NEG = 12
CMD_GE = 13
CMD_GT = 14
CMD_LE = 15
CMD_LT = 16
CMD_SHL = 17
CMD_SHR = 18

# Load expression argument to evaluation stack.
CMD_ARG = 19

# Evaluate DWARF location expression. Command arguments are byte array of
# DWARF expression instructions and an object that contains evaluation
# parameters.
CMD_LOCATION = 20

CMD_FCALL = 21
CMD_WR_REG = 22
CMD_WR_MEM = 23
CMD_PIECE = 24

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

# 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

# Symbol location properties.

# Number, start address of code range where the location info is valid, or null
# if it is valid everywhere
LOC_CODE_ADDR = "CodeAddr"

# Number, size in bytes of code range where the location info is valid, or null
# if it is valid everywhere
LOC_CODE_SIZE = "CodeSize"


# Number, number of argument required to execute location instructions
LOC_ARG_CNT = "ArgCnt"

# List, instructions to compute object value location, e.g. address, or offset,
# or register ID, etc.
LOC_VALUE_CMDS = "ValueCmds"

# List, instructions to compute dynamic array length location
LOC_LENGTH_CMDS = "LengthCmds"


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, None 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