Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 99ab27c3502e3e9ce791f06507d9a2ec30f2fe11 (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
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
# *****************************************************************************
# * Copyright (c) 2011, 2013-2014, 2016 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
# *****************************************************************************

"""Registers service provides access to target CPU register values and
properties.

.. |canSearch| replace:: :meth:`RegisterContext.canSearch`
.. |get| replace:: :meth:`RegisterContext.get`
.. |getChildren| replace:: :meth:`RegistersService.getChildren`
.. |getContext| replace:: :meth:`RegistersService.getContext`
.. |getFirstBitNumber| replace:: :meth:`RegisterContext.getFirstBitNumber`
.. |getm| replace:: :meth:`RegisterContext.getm`
.. |getRole| replace:: :meth:`RegisterContext.getRole`
.. |search| replace:: :meth:`RegistersService.search`
.. |set| replace:: :meth:`RegisterContext.set`
.. |setm| replace:: :meth:`RegisterContext.setm`
.. |DoneGet| replace:: :class:`DoneGet`
.. |DoneGetChildren| replace:: :class:`DoneGetChildren`
.. |DoneGetContext| replace:: :class:`DoneGetContext`
.. |DoneSearch| replace:: :class:`DoneSearch`
.. |DoneSet| replace:: :class:`DoneSet`
.. |Location| replace:: :class:`Location`
.. |NamedValue| replace:: :class:`NamedValue`
.. |RegistersContext| replace:: :class:`RegistersContext`
.. |RegistersListener| replace:: :class:`RegistersListener`

Properties
----------
Register Context Properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^

See |RegistersContext|

+---------------------+--------------+----------------------------------------+
| Name                | Type         | Description                            |
+=====================+==============+========================================+
| PROP_BIG_ENDIAN     | |bool|       | **True** if big endian.                |
+---------------------+--------------+----------------------------------------+
| PROP_BITS           | |int|        | If context is a bit field, contains the|
|                     |              | field bit numbers in the parent        |
|                     |              | context.                               |
+---------------------+--------------+----------------------------------------+
| PROP_CAN_SEARCH     | |list|       | A list of attribute names which can be |
|                     |              | searched for starting on this context. |
|                     |              | See `Register Search Properties`_.     |
+---------------------+--------------+----------------------------------------+
| PROP_DESCRIPTION    | |basestring| | Context description.                   |
+---------------------+--------------+----------------------------------------+
| PROP_FIRST_BIT      | |int|        | Bit numbering base (0 or 1) to use when|
|                     |              | showing bits to user.                  |
+---------------------+--------------+----------------------------------------+
| PROP_FLOAT          | |bool|       | **True** if the register value is a    |
|                     |              | floating-point value.                  |
+---------------------+--------------+----------------------------------------+
| PROP_ID             | |basestring| | ID of the context.                     |
+---------------------+--------------+----------------------------------------+
| PROP_LEFT_TO_RIGHT  | |bool|       | **True** if the lowest numbered bit    |
|                     |              | should be shown to user as the         |
|                     |              | left-most bit.                         |
+---------------------+--------------+----------------------------------------+
| PROP_MEMORY_ADDRESS | |int|        | The address of a memory mapped         |
|                     |              | register.                              |
+---------------------+--------------+----------------------------------------+
| PROP_MEMORY_CONTEXT | |basestring| | The context ID of a memory context in  |
|                     |              | which a memory mapped register is      |
|                     |              | located.                               |
+---------------------+--------------+----------------------------------------+
| PROP_NAME           | |basestring| | Context name.                          |
+---------------------+--------------+----------------------------------------+
| PROP_OFFSET         | |int|        | When present describes the offset in   |
|                     |              | the data of the parent register where  |
|                     |              | the value of a field can be found.     |
+---------------------+--------------+----------------------------------------+
| PROP_PARENT_ID      | |basestring| | ID of a parent context.                |
+---------------------+--------------+----------------------------------------+
| PROP_PROCESS_ID     | |basestring| | Process ID.                            |
+---------------------+--------------+----------------------------------------+
| PROP_READBLE        | |bool|       | **True** if context value can be read. |
+---------------------+--------------+----------------------------------------+
| PROP_READ_ONCE      | |bool|       | **True** if reading the context        |
|                     |              | (register) destroys its current value. |
+---------------------+--------------+----------------------------------------+
| PROP_ROLE           | |basestring| | The role the register plays in a       |
|                     |              | program execution. See                 |
|                     |              | `Register Role Properties`_.           |
+---------------------+--------------+----------------------------------------+
| PROP_SIDE_EFFECTS   | |bool|       | **True** if writing the context can    |
|                     |              | change values of other registers.      |
+---------------------+--------------+----------------------------------------+
| PROP_SIZE           | |int|        | Context size in bytes. Byte arrays in  |
|                     |              | get/set commands should be same size.  |
+---------------------+--------------+----------------------------------------+
| PROP_VALUES         | |dict|       | Predefined names (mnemonics) for some  |
|                     |              | of context values.                     |
+---------------------+--------------+----------------------------------------+
| PROP_VOLATILE       | |bool|       | **True** if the register value can     |
|                     |              | change even when target is stopped.    |
+---------------------+--------------+----------------------------------------+
| PROP_WRITEABLE      | |bool|       | **True** if context value can be       |
|                     |              | written.                               |
+---------------------+--------------+----------------------------------------+
| PROP_WRITE_ONCE     | |bool|       | **True** if register value can not be  |
|                     |              | overwritten - every write counts.      |
+---------------------+--------------+----------------------------------------+

.. _Tcf-Register-Role-Properties:

Register Role Properties
^^^^^^^^^^^^^^^^^^^^^^^^
All register roles are of type |basestring|.

.. seealso:: |getRole|

+-----------+-----------------------------------------------------------------+
| Name      | Description                                                     |
+===========+=================================================================+
| ROLE_CORE | Indicates register or register groups which belong to the core  |
|           | state.                                                          |
+-----------+-----------------------------------------------------------------+
| ROLE_FP   | Register defining the current frame pointer location.           |
+-----------+-----------------------------------------------------------------+
| ROLE_PC   | Program counter. Defines instruction to execute next.           |
+-----------+-----------------------------------------------------------------+
| ROLE_RET  | Register used to store the return address for calls.            |
+-----------+-----------------------------------------------------------------+
| ROLE_SP   | Register defining the current stack pointer location.           |
+-----------+-----------------------------------------------------------------+

Register Search Properties
^^^^^^^^^^^^^^^^^^^^^^^^^^
All register search properties are of type |basestring|.

.. seealso:: |canSearch|

+--------------------+--------------------------------------------------------+
| Name               | Description                                            |
+====================+========================================================+
| SEARCH_EQUAL_VALUE | The value which is searched for. This should be a      |
|                    | |basestring| of packed binary data. Array size should  |
|                    | match the size of the register.  See |struct| module.  |
+--------------------+--------------------------------------------------------+
| SEARCH_NAME        | The name of the property this filter applies to.       |
+--------------------+--------------------------------------------------------+

Service Methods
---------------
.. autodata:: NAME
.. autoclass:: RegistersService

addListener
^^^^^^^^^^^
.. automethod:: RegistersService.addListener

getChildren
^^^^^^^^^^^
.. automethod:: RegistersService.getChildren

getContext
^^^^^^^^^^
.. automethod:: RegistersService.getContext

getName
^^^^^^^
.. automethod:: RegistersService.getName

getm
^^^^
.. automethod:: RegistersService.getm

removeListener
^^^^^^^^^^^^^^
.. automethod:: RegistersService.removeListener

setm
^^^^
.. automethod:: RegistersService.setm

Callback Classes
----------------
DoneGet
^^^^^^^
.. autoclass:: DoneGet
    :members:

DoneGetChildren
^^^^^^^^^^^^^^^
.. autoclass:: DoneGetChildren
    :members:

DoneGetContext
^^^^^^^^^^^^^^
.. autoclass:: DoneGetContext
    :members:

DoneSearch
^^^^^^^^^^
.. autoclass:: DoneSearch
    :members:

DoneSet
^^^^^^^
.. autoclass:: DoneSet
    :members:

Listener
--------
.. autoclass:: RegistersListener
    :members:

Helper Classes
--------------
Location
^^^^^^^^
.. autoclass:: Location
    :members:

NamedValue
^^^^^^^^^^
.. autoclass:: NamedValue
    :members:

RegistersContext
^^^^^^^^^^^^^^^^
.. autoclass:: RegistersContext
    :members:
"""

from .. import services

NAME = "Registers"
"""Registers service name."""

# Registers Context Properties

PROP_ID = "ID"
PROP_PARENT_ID = "ParentID"
PROP_PROCESS_ID = "ProcessID"
PROP_NAME = "Name"
PROP_DESCRIPTION = "Description"
PROP_SIZE = "Size"
PROP_READBLE = "Readable"
PROP_READ_ONCE = "ReadOnce"
PROP_WRITEABLE = "Writeable"
PROP_WRITE_ONCE = "WriteOnce"
PROP_SIDE_EFFECTS = "SideEffects"
PROP_VOLATILE = "Volatile"
PROP_FLOAT = "Float"
PROP_BIG_ENDIAN = "BigEndian"
PROP_LEFT_TO_RIGHT = "LeftToRight"
PROP_FIRST_BIT = "FirstBit"
PROP_BITS = "Bits"
PROP_VALUES = "Values"
PROP_MEMORY_ADDRESS = "MemoryAddress"
PROP_MEMORY_CONTEXT = "MemoryContext"
PROP_CAN_SEARCH = "CanSearch"
PROP_ROLE = "Role"
PROP_OFFSET = "Offset"

# Registers Role Properties

ROLE_PC = "PC"
ROLE_SP = "SP"
ROLE_FP = "FP"
ROLE_RET = "RET"
ROLE_CORE = "CORE"

# Registers Search Properties

SEARCH_NAME = "Name"
SEARCH_EQUAL_VALUE = "EqualValue"


class RegistersContext(object):
    """RegistersContext objects represent register groups, registers and bit
    fields.

    Register contexts are initialised with the properties described at
    `Register Context Properties`_.

    :param properties: The properties to initialise this register context with.
    :type properties: |dict|

    .. seealso:: `Register Context Properties`_
    """
    def __init__(self, props):
        self._props = props or {}

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

    def getProperties(self):
        """Get context properties.

        See `Register Context Properties`_  definitions for property names.
        Context properties are read only, clients should not try to modify
        them.

        :returns: A |dict| of register context properties.

        .. seealso:: `Register Context Properties`_
        """
        return self._props

    def getID(self):
        """Get register TCF context ID.

        :returns: A |basestring| representing this register context ID.
        """
        return self._props.get(PROP_ID)

    def getParentID(self):
        """Get parent context ID.

        :returns: A |basestring| representing this register parent context ID
                  or **None**.
        """
        return self._props.get(PROP_PARENT_ID)

    def getProcessID(self):
        """Get process ID, if applicable.

        :returns: A |basestring| representing this register context process ID
                  or **None**.
        """
        return self._props.get(PROP_PROCESS_ID)

    def getName(self):
        """Get context (register, register group, bit field) name.

        :returns: A |basestring| representing this register context name or
                  **None**.
        """
        return self._props.get(PROP_NAME)

    def getDescription(self):
        """Get context description.

        :returns: A |basestring| representing this register context
                  description or **None**.
        """
        return self._props.get(PROP_DESCRIPTION)

    def getSize(self):
        """Get context size in bytes.

        Byte arrays in |get|/|set| methods should be same size.

        Hardware register can be smaller than this size, for example in case
        when register size is not an even number of bytes. In such case
        implementation should add/remove padding that consists of necessary
        number of zero bits.

        :returns: An |int| representing this register context size in bytes or
                 **0**.
        """
        return self._props.get(PROP_SIZE, 0)

    def isReadable(self):
        """Check if context value can be read.

        :returns: A |bool| set to **True** if the register context value can be
                  read.
        """
        return self._props.get(PROP_READBLE)

    def isReadOnce(self):
        """Check if reading the context (register) destroys its current value -
         it can be read only once.

        :returns: A |bool| set to **True** if the register context value can be
                  read only once.
        """
        return self._props.get(PROP_READ_ONCE)

    def isWriteable(self):
        """Check if context value can be written.

        :returns: A |bool| set to **True** if the register context value can be
                  written.
        """
        return self._props.get(PROP_WRITEABLE)

    def isWriteOnce(self):
        """Check if register value can not be overwritten - every write counts.

        :returns: A |bool| set to **True** if the register context value can be
                  written only once.
        """
        return self._props.get(PROP_WRITE_ONCE)

    def hasSideEffects(self):
        """Check if writing the context can change values of other registers.

        :returns: A |bool| set to **True** if writting the register context
                  value can change values of other registers.
        """
        return self._props.get(PROP_SIDE_EFFECTS)

    def isVolatile(self):
        """Check if the register value can change even when target is stopped.

        :returns: A |bool| set to **True** if the register value can change at
                  any time.
        """
        return self._props.get(PROP_VOLATILE)

    def isFloat(self):
        """Check if the register value is a floating-point value.

        :returns: A |bool| set to **True** if this register context reprsents a
                  floating-point register.
        """
        return self._props.get(PROP_FLOAT)

    def isBigEndian(self):
        """Check endianness of the context.

        Big endian means decreasing numeric significance with increasing bit
        number.

        The endianness is used to encode and decode values of |get|, |getm|,
        |set| and |setm| commands.

        :returns: A |bool| set to **True** if this register endianness is big.
        """
        return self._props.get(PROP_BIG_ENDIAN)

    def isLeftToRight(self):
        """Check if the lowest numbered bit (i.e. bit #0 or bit #1 depending on
        |getFirstBitNumber| value) should be shown to user as the left-most bit
        or the right-most bit.

        :returns: A |bool| set to **True** if the first bit is left-most bit.
        """
        return self._props.get(PROP_LEFT_TO_RIGHT)

    def getFirstBitNumber(self):
        """If the context has bit field children, bit positions of the fields
        can be zero-based or 1-based.

        :returns: An |int| representing this register first bit position -
                  **0** or **1**.
        """
        return self._props.get(PROP_FIRST_BIT, 0)

    def getBitNumbers(self):
        """If context is a bit field, get the field bit numbers in parent
        context.

        :returns: A |list| of  of bit numbers.
        """
        return self._props.get(PROP_BITS)

    def getNamedValues(self):
        """A context can have predefined names (mnemonics) for some of its
        values.

        This method returns a list of such named values.

        :returns: A |list| of |NamedValue| objects or **None**.
        """
        return self._props.get(PROP_VALUES)

    def getMemoryAddress(self):
        """Get the address of a memory mapped register.

        :returns: An |int| representing this register's memory mapped address
                  or **None**.
        """
        return self._props.get(PROP_MEMORY_ADDRESS)

    def getMemoryContext(self):
        """Get the context ID of a memory context in which a memory mapped
        register is located.

        :returns: A |basestring| representing this register's memory context
                  ID or **None**.
        """
        return self._props.get(PROP_MEMORY_CONTEXT)

    def canSearch(self):
        """Get a list of property names which can be searched for starting on
        this context.

        :returns: A |list| of property names.

        .. seealso:: `Register Search Properties`_
        """
        return self._props.get(PROP_CAN_SEARCH)

    def getRole(self):
        """Get the role the register plays in a program execution.

        :returns: A |basestring| representing this register context role name
                  or **None**.

        .. seealso:: `Register Role Properties`_
        """
        return self._props.get(PROP_ROLE)

    def getOffset(self):
        """Get the offset in the data of the parent register where the value
        of a field can be found.

        :returns: An |int| representing this register offset in parent
                  register or **None**.
        """
        return self._props.get(PROP_OFFSET)

    def get(self, done):
        """Read value of the context.

        :param done: Call back interface called when operation is completed.
        :type done: |DoneGet|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def set(self, value, done):  # @ReservedAssignment
        """Set value of the context.

        :param value: An array of packed binary data. Array size should match
                      the size of the register. See |struct| module.
        :type value: |basestring|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneSet|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def search(self, filterProps, done):
        """Search register contexts that passes given search filter.

        Search is only supported for properties listed by the |canSearch|
        method.

        :param filterProps: Dictionary of properties to search for.
        :type filterProps: |dict|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneSearch|

        :returns: Pending command handle, can be used to cancel the command.

        .. seealso:: `Register Search Properties`_
        """
        raise NotImplementedError("Abstract method")


class RegistersService(services.Service):
    def getName(self):
        """Get this service name.

        :returns: A |basestring| representing this service name, which is the
                  value of :const:`NAME`
        """
        return NAME

    def getContext(self, contextID, done):
        """Retrieve context info for given context ID.

        :param contextID: TCF ID of the register to retrieve.
        :type contextID: |basestring|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneGetContext|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def getChildren(self, parent_context_id, done):
        """Retrieve contexts available for registers commands.

        A context corresponds to an execution thread, stack frame, registers
        group, etc...

        A context can belong to a parent context. Contexts hierarchy can be
        simple plain list or it can form a tree. It is up to target agent
        developers to choose layout that is most descriptive for a given
        target. Context IDs are valid across all services. In other words, all
        services access same hierarchy of contexts, with same IDs, however,
        each service accesses its own subset of context's attributes and
        functionality, which is relevant to that service.

        :param parent_context_id: parent context ID. Can be **None**.
                                  :note: to retrieve top level of the
                                  hierarchy, or one of context IDs retrieved by
                                  previous |getChildren| commands.
        :type parent_context_id: |basestring| or **None**
        :param done: Call back interface called when operation is completed.
        :type done: |DoneGetChildren|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def getm(self, locs, done):
        """Read values of multiple locations in registers.

        :param locs: List of data |Location|.
        :type locs: |list| or |tuple|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneGet|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def setm(self, locs, value, done):
        """Set values of multiple locations in registers.

        :param locs: List of data |Location|.
        :type locs: |list| or |tuple|
        :param value: An array of packed binary data. Array size should match
                      the size of the register. See |struct| module.
        :type value: |basestring|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneSet|

        :returns: Pending command handle, can be used to cancel the command.
        """
        raise NotImplementedError("Abstract method")

    def addListener(self, listener):
        """Add registers service event listener.

        :param listener: Register event listener implementation to add this
                         service.
        :type listener: |RegistersListener|
        """
        raise NotImplementedError("Abstract method")

    def removeListener(self, listener):
        """Remove registers service event listener.

        :param listener: Register event listener implementation to remove from
                         this service.
        :type listener: |RegistersListener|
        """
        raise NotImplementedError("Abstract method")


class NamedValue(object):
    """A register context can have predefined names (mnemonics) for some its
    values.

    NamedValue objects represent such values.

    :param value: A |basestring| of packed binary data. Array size should match
                  the size of the register. See |struct| module.
    :type value: |basestring|
    :param name: Register named value name.
    :type name: |basestring|
    :param description: Register named value description.
    :type description: |basestring|
    """
    def __init__(self, value, name, description):
        self.value = value
        self.name = name
        self.description = description

    def getValue(self):
        """Get value associated with the name.

        :returns: A |basestring| of packed binary data. Array size should match
                  the size of the register. See |struct| module.
        """
        return self.value

    def getName(self):
        """Get name (mnemonic) of the value.

        :returns: A |basestring| representing this register named value name.
        """
        return self.name

    def getDescription(self):
        """Get human readable description of the value.

        :returns: A |basestring| representing this register named value
                  description.
        """
        return self.description


class DoneGet(object):
    """Client call back interface for |get| or |getm|."""
    def doneGet(self, token, error, value):
        """Called when value retrieval is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        :param value: A |basestring| of packed binary data. Array size should
                      match the size of the register. See |struct| module.
        :type value: |basestring|
        """
        pass


class DoneSet(object):
    """Client call back interface for |set| or |setm|.
    """
    def doneSet(self, token, error):
        """Called when value setting is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        """
        pass


class DoneSearch(object):
    """Client call back interface for |search|.
    """
    def doneSearch(self, token, error, paths):
        """Called when context search is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        :param paths: List of paths to each context with properties matching
                      the filter.
        :type paths: |list| or |tuple|
        """
        pass


class DoneGetContext(object):
    """Client call back interface for |getContext|."""
    def doneGetContext(self, token, error, context):
        """Called when context data retrieval is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        :param context: The so retrieved register context.
        :type context: |RegistersContext|
        """
        pass


class DoneGetChildren(object):
    """Client call back interface for :meth:`~RegistersService.getChildren`
    """
    def doneGetChildren(self, token, error, context_ids):
        """Called when context list retrieval is done.

        :param token: Pending command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        :param context_ids: A list of available context IDs.
        :type context_ids: |list| or |tuple|
        """
        pass


class RegistersListener(object):
    """Registers event listener is notified when registers context hierarchy
    changes, and when a register is modified by the service commands.
    """

    def contextChanged(self):
        """Called when register context properties changed.

        Most targets have static set of registers and register properties.
        Such targets never generate this event. However, some targets,
        for example, JTAG probes, allow user to modify register definitions.
        Clients should flush all cached register context data.
        """
        pass

    def registerChanged(self, contextID):
        """Called when register content was changed and clients need to update
        themselves.

        Clients, at least, should invalidate corresponding cached registers
        data.

        Not every change is notified - it is not possible, only those, which
        are not caused by normal execution of the debuggee.

        At least, changes caused by |set| command should be notified.

        :param contextID: ID of the changed register.
        :type contextID: |basestring|
        """
        pass


class Location(object):
    """Class Location represents value location in register context.

    :param contextID: Register context ID.
    :type contextID: |basestring|
    :param offs: Offset in the context, in bytes.
    :type offs: |int|
    :param size: Value size in bytes.
    :type size: |int|
    """
    def __init__(self, contextID, offs, size):
        self._id = contextID
        self._offs = offs
        self._size = size

    def __iter__(self):
        yield self._id
        yield self._offs
        yield self._size

    @property
    def id(self):
        """Register location ID."""
        return self._id

    @property
    def offs(self):
        """Register location offset."""
        return self._offs

    @property
    def size(self):
        """Register location size."""
        return self._size

Back to the top