Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: ec0827da3a8a953873df7d7a35e6509ecb1e2d20 (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
# *****************************************************************************
# * Copyright (c) 2011, 2013-2014 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
# *****************************************************************************

"""Memory service provides basic operations to read/write memory on a target.

.. |fill| replace:: :meth:`~MemoryContext.fill`
.. |get| replace:: :meth:`~MemoryContext.get`
.. |getChildren| replace:: :meth:`~MemoryService.getChildren`
.. |getContext| replace:: :meth:`~MemoryService.getContext`
.. |getMessage| replace:: :meth:`~MemoryError.getMessage`
.. |processes| replace:: :mod:`~tcf.services.processes`
.. |set| replace:: :meth:`~MemoryContext.set`
.. |DoneGetChildren| replace:: :class:`DoneGetChildren`
.. |DoneGetContext| replace:: :class:`DoneGetContext`
.. |DoneMemory| replace:: :class:`DoneMemory`
.. |MemoryContext| replace:: :class:`MemoryContext`
.. |MemoryError| replace:: :class:`MemoryError`
.. |MemoryListener| replace:: :class:`MemoryListener`

Memory Properties
-----------------
Properties
^^^^^^^^^^
+-------------------+--------------+------------------------------------------+
| Name              | Type         | Description                              |
+===================+==============+==========================================+
| PROP_ACCESS_TYPES | |list|       | The access types allowed for this        |
|                   |              | context. Target system can support       |
|                   |              | multiple different memory access types,  |
|                   |              | like instruction and data access.        |
|                   |              | Different access types can use different |
|                   |              | logic for address translation and memory |
|                   |              | mapping, so they can end up accessing    |
|                   |              | different data bits, even if address is  |
|                   |              | the same. Each distinct access type      |
|                   |              | should be represented by separate memory |
|                   |              | context. A memory context can represent  |
|                   |              | multiple access types if they are        |
|                   |              | equivalent - all access same memory bits.|
|                   |              | Same data bits can be exposed through    |
|                   |              | multiple memory contexts.                |
|                   |              | See `Access types`_.                     |
+-------------------+--------------+------------------------------------------+
| PROP_ADDRESS_SIZE | |int|        | Size of memory address in bytes.         |
+-------------------+--------------+------------------------------------------+
| PROP_BIG_ENDIAN   | |bool|       | **True** if memory is big-endian.        |
+-------------------+--------------+------------------------------------------+
| PROP_END_BOUND    | |int|        | Highest address (inclusive) which is     |
|                   |              | valid for the context.                   |
+-------------------+--------------+------------------------------------------+
| PROP_ID           | |basestring| | ID of the context.                       |
+-------------------+--------------+------------------------------------------+
| PROP_NAME         | |basestring| | Name of the context, can be used for UI  |
|                   |              | purposes.                                |
+-------------------+--------------+------------------------------------------+
| PROP_PARENT_ID    | |basestring| | ID of a parent context.                  |
+-------------------+--------------+------------------------------------------+
| PROP_PROCESS_ID   | |basestring| | Process ID, see |processes| service.     |
+-------------------+--------------+------------------------------------------+
| PROP_START_BOUND  | |int|        | Lowest address (inclusive) which is      |
|                   |              | valid for the context.                   |
+-------------------+--------------+------------------------------------------+

Access Types
^^^^^^^^^^^^
All access types are of type |basestring|.

+--------------------+--------------------------------------------------------+
| Name               | Description                                            |
+====================+========================================================+
| ACCESS_CACHE       | Context is a cache.                                    |
+--------------------+--------------------------------------------------------+
| ACCESS_DATA        | Context represents data access.                        |
+--------------------+--------------------------------------------------------+
| ACCESS_HYPERVISOR  | Context represents a hypervisor view to memory.        |
+--------------------+--------------------------------------------------------+
| ACCESS_INSTRUCTION | Context represent instructions fetch access.           |
+--------------------+--------------------------------------------------------+
| ACCESS_IO          | Context represents IO peripherals.                     |
+--------------------+--------------------------------------------------------+
| ACCESS_PHYSICAL    | Context uses physical addresses.                       |
+--------------------+--------------------------------------------------------+
| ACCESS_SUPERVISOR  | Context represents a supervisor (e.g. Linux kernel)    |
|                    | view to memory.                                        |
+--------------------+--------------------------------------------------------+
| ACCESS_TLB         | Context is a TLB memory.                               |
+--------------------+--------------------------------------------------------+
| ACCESS_USER        | Context represents a user (e.g. application running    |
|                    | in Linux) view to memory.                              |
+--------------------+--------------------------------------------------------+
| ACCESS_VIRTUAL     | Context uses virtual addresses.                        |
+--------------------+--------------------------------------------------------+

Command Modes
^^^^^^^^^^^^^
All command modes are of type |int|. For the |get|, |fill| or |set| methods,
the possible modes are:

+----------------------+------------------------------------------------------+
| Name                 | Description                                          |
+======================+======================================================+
| MODE_CONTINUEONERROR | Carry on when some of the memory cannot be accessed  |
|                      | and return |MemoryError| at the end if any of the    |
|                      | bytes were not processed correctly.                  |
+----------------------+------------------------------------------------------+
| MODE_VERIFY          | Verify result of memory operations (by reading and   |
|                      | comparing).                                          |
+----------------------+------------------------------------------------------+

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

addListener
^^^^^^^^^^^
.. automethod:: MemoryService.addListener

fill
^^^^
.. automethod:: MemoryContext.fill

get
^^^
.. automethod:: MemoryContext.get

getChildren
^^^^^^^^^^^
.. automethod:: MemoryService.getChildren

getContext
^^^^^^^^^^
.. automethod:: MemoryService.getContext

getName
^^^^^^^
.. automethod:: MemoryService.getName

removeListener
^^^^^^^^^^^^^^
.. automethod:: MemoryService.removeListener

set
^^^
.. automethod:: MemoryContext.set

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

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

DoneMemory
^^^^^^^^^^
.. autoclass:: DoneMemory
    :members:

Listener
--------
MemoryListener
^^^^^^^^^^^^^^
.. autoclass:: MemoryListener
    :members:

Helper classes
--------------
ErrorOffset
^^^^^^^^^^^
.. autoclass:: ErrorOffset
    :members:

MemoryContext
^^^^^^^^^^^^^
.. autoclass:: MemoryContext
    :members:

MemoryError
^^^^^^^^^^^
.. autoclass:: MemoryError
    :members:

"""

from .. import services

NAME = "Memory"
"""Memory service name."""

# Context property names.

PROP_ID = "ID"
PROP_PARENT_ID = "ParentID"
PROP_PROCESS_ID = "ProcessID"
PROP_BIG_ENDIAN = "BigEndian"
PROP_ADDRESS_SIZE = "AddressSize"
PROP_NAME = "Name"
PROP_START_BOUND = "StartBound"
PROP_END_BOUND = "EndBound"
PROP_ACCESS_TYPES = "AccessTypes"

ACCESS_INSTRUCTION = "instruction"
ACCESS_DATA = "data"
ACCESS_IO = "io"
ACCESS_USER = "user"
ACCESS_SUPERVISOR = "supervisor"
ACCESS_HYPERVISOR = "hypervisor"
ACCESS_VIRTUAL = "virtual"
ACCESS_PHYSICAL = "physical"
ACCESS_CACHE = "cache"
ACCESS_TLB = "tlb"

MODE_CONTINUEONERROR = 0x1
MODE_VERIFY = 0x2


class MemoryContext(object):
    """Memory context class.

    :param props: Properties to initialise this memory context with. See
                  `Properties`_.
    :type props: |dict|
    """
    def __init__(self, props):
        self._props = props or {}

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

    def getProperties(self):
        """Get context properties. See `Properties`_ definitions for property
        names.

        Context properties are read only, clients should not try to modify
        them.

        :returns: A |dict| of context properties.
        """
        return self._props

    def getID(self):
        """Retrieve context ID.

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

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

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

    def getProcessID(self):
        """Retrieve context process ID.

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

    def isBigEndian(self):
        """Get memory endianness.

        :returns: A |bool| stating if memory is big-endian.
        """
        return self._props.get(PROP_BIG_ENDIAN, False)

    def getAddressSize(self):
        """Get memory address size.

        :returns: An |int| representing the number of bytes used to store
                  memory address value.
        """
        return self._props.get(PROP_ADDRESS_SIZE, 0)

    def getName(self):
        """Get memory context name.

        The name can be used for UI purposes.

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

    def getStartBound(self):
        """Get lowest address (inclusive) which is valid for the context.

        :returns: An |int| representing the lowest address or **None**.
        """
        return self._props.get(PROP_START_BOUND)

    def getEndBound(self):
        """Get highest address (inclusive) which is valid for the context.

        :returns: An |int| representing the highest address or **None**.
        """
        return self._props.get(PROP_END_BOUND)

    def getAccessTypes(self):
        """Get the access types allowed for this context.

        :returns: A |dict| of access type names or **None**. See
                 `Access Types`_.
        """
        return self._props.get(PROP_ACCESS_TYPES)

    def set(self, addr, ws, buf, offs, sz, mode, done):  # @ReservedAssignment
        """Set target memory.

        If *ws* is 0 it means client does not care about word size.

        :param addr: Address to set for this memory context.
        :type addr: |int|
        :param ws: Word size (alignement) to use for setting memory.
        :type ws: |int|
        :param buf: Data to be written in memory.
        :type buf: |bytearray|
        :param offs: Offset to seek in *buf*.
        :type offs: |int|
        :param sz: Number of bytes to write in memory.
        :type sz: |int|
        :param mode: Memory write mode. See `Command Modes`_.
        :type mode: |int|

        :returns: pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def get(self, addr, word_size, buf, offs, size, mode, done):
        """Read target memory.

        :param addr: Address to get from this memory context.
        :type addr: |int|
        :param ws: word size (alignement) to use for getting memory.
        :type ws: |int|
        :param buf: read data buffer.
        :type buf: |bytearray|
        :param offs: Offset to seek in *buf* to write retrieved data.
        :type offs: |int|
        :param sz: Number of bytes to read in memory.
        :type sz: |int|
        :param mode: Memory read mode. See `Command Modes`_.
        :type mode: |int|

        :returns: pending command handle.
        """
        raise NotImplementedError("Abstract method")

    def fill(self, addr, word_size, value, size, mode, done):
        """Fill target memory with given pattern.

        :param addr: Address to get from this memory context.
        :type addr: |int|
        :param word_size: Word size (alignement) to use for filling memory.
        :type word_size: |int|
        :param buf: Data to be fill memory with.
        :type buf: |bytearray|
        :param offs: Offset to seek in *buf*.
        :type offs: |int|
        :param sz: Number of bytes to write in memory.
        :type sz: |int|
        :param mode: Memory write mode. See `Command Modes`_.
        :type mode: |int|

        :returns: pending command handle.
        """
        raise NotImplementedError("Abstract method")


class DoneMemory(object):
    """Client call back interface for |fill|, |get| and |set| commands."""
    def doneMemory(self, token, error):
        """Called when memory operation command command is done.

        :param token: Command handle.
        :param error: Error object or **None**.
        """
        pass


class MemoryError(Exception):  # @ReservedAssignment
    """Memory errors class.

    Empty class implementing the |Exception| class.
    """
    pass


class ErrorOffset(object):
    """Error offset may be implemented by |MemoryError| object, which is
    returned by |get|, |set| and |fill| commands.

    The command |get|, |set| and |fill| return this exception when memory
    operation failed for some but not all bytes, and **MODE_CONTINUEONERROR**
    has been set in *mode*. (For example, when only part of the request
    translates to valid memory addresses.)

    Method |getMessage| can be used for generalized message of the possible
    reasons of partial memory operation.
    """
    # Error may have per byte information
    BYTE_VALID = 0x00
    BYTE_UNKNOWN = 0x01  # e.g. out of range
    BYTE_INVALID = 0x02
    BYTE_CANNOT_READ = 0x04
    BYTE_CANNOT_WRITE = 0x08

    RANGE_KEY_ADDR = "addr"
    RANGE_KEY_SIZE = "size"
    RANGE_KEY_STAT = "stat"
    RANGE_KEY_MSG = "msg"

    def getStatus(self, offset):
        """Get the error status.

        :param offset: offset to get error status for
        :type offset: |int|

        :returns: The error status for the error which happened at given
                  *offset*.
        """
        raise NotImplementedError("Abstract method")

    def getMessage(self, offset):
        """Get the error message.

        :param offset: Offset to get error message for.
        :type offset: |int|

        :returns: The error message for the error which happened at given
                  *offset*.
        """
        raise NotImplementedError("Abstract method")


class MemoryService(services.Service):
    """TCF memory service interface."""

    def getName(self):
        """Get this service name.

        :returns: The value of string :const:`NAME`
        """
        return NAME

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

        :param contextID: ID of the memory context to get.
        :type contextID: |basestring|
        :param done: Call back interface called when operation is completed.
        :type done: |DoneGetContext|

        :returns: Pending command handle.
        """
        raise NotImplementedError("Abstract method")

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

        A context corresponds to an execution thread, process, address space,
        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** - to
                                  retrieve top level of the hierarchy, or one
                                  of context IDs retrieved by previous
                                  |getChildren| commands.
        :type parent_context_id: |basestring|
        :param done: call back interface called when operation is completed.
        :type done: |DoneGetContext|

        :returns: Pending command handle.
        """
        raise NotImplementedError("Abstract method")

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

        :param listener: Event listener implementation.
        :type listener: |MemoryListener|
        """
        raise NotImplementedError("Abstract method")

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

        :param listener: Event listener implementation.
        :type listener: |MemoryListener|
        """
        raise NotImplementedError("Abstract method")


class MemoryListener(object):
    """Memory event listener is notified when memory context hierarchy changes,
    and when memory is modified by memory service commands.
    """

    def contextAdded(self, contexts):
        """Called when a new memory access context(s) is created.

        :param contexts: A list of |MemoryContext| properties which have been
                         added to memory space.
        :type contexts: |list|
        """
        pass

    def contextChanged(self, contexts):
        """Called when a memory access context(s) properties changed.

        :param contexts: A list of |MemoryContext| properties which have been
                         changed in memory space.
        :type contexts: |list|
        """
        pass

    def contextRemoved(self, context_ids):
        """Called when memory access context(s) is removed.

        :param context_ids: A list of the IDs of memory contexts which have
                            been removed from memory space.
        :type context_ids: |list|
        """
        pass

    def memoryChanged(self, context_id, addr, size):
        """Called when target memory content was changed and clients need to
        update themselves.

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

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

        :param context_id: ID of the changed memory context.
        :type context_id: |basestring|
        :param addr: Address at which memory has been changed. A value of
                     **None** means that this address is unknown.
        :type addr: |int|
        :param size: Size of the changed memory. A value of **None** means that
                     this size is unknown.
        :type size: |int| or **None**
        """
        pass


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

        :param token: Command handle.
        :param error: Error description if operation failed, **None** if
                      succeeded.
        :param context: The so retrieved memory context description.
        :type context: |MemoryContext|
        """
        pass


class DoneGetChildren(object):
    """Client call back interface for |getChildren|."""

    def doneGetChildren(self, token, error, context_ids):
        """Called when memory IDs retrieval is done.

        :param token: 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|
        """
        pass

Back to the top