Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorFrederic Leger2014-03-13 12:26:07 -0400
committerFrederic Leger2014-03-13 12:26:07 -0400
commitd67e0bec2951e6ef71ea5f35c7a7131b626a0e9d (patch)
tree66bf3419a47797ed516c68b4e692da3a4017e681 /python/src/tcf/services/memory.py
parentfd1994f9f5da5a9ae5d3f286b1385a0c4a993489 (diff)
downloadorg.eclipse.tcf-d67e0bec2951e6ef71ea5f35c7a7131b626a0e9d.tar.gz
org.eclipse.tcf-d67e0bec2951e6ef71ea5f35c7a7131b626a0e9d.tar.xz
org.eclipse.tcf-d67e0bec2951e6ef71ea5f35c7a7131b626a0e9d.zip
Python - services documentation.
Services can now be documented using sphinx.
Diffstat (limited to 'python/src/tcf/services/memory.py')
-rw-r--r--python/src/tcf/services/memory.py551
1 files changed, 396 insertions, 155 deletions
diff --git a/python/src/tcf/services/memory.py b/python/src/tcf/services/memory.py
index f6f8aa640..4157bcde2 100644
--- a/python/src/tcf/services/memory.py
+++ b/python/src/tcf/services/memory.py
@@ -9,95 +9,231 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-Memory service provides basic operations to read/write memory on a target.
+"""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.
-# String, ID of the context, same as getContext command argument
-PROP_ID = "ID"
-# String, ID of a parent context
+PROP_ID = "ID"
PROP_PARENT_ID = "ParentID"
-
-# String, process ID, see Processes service
PROP_PROCESS_ID = "ProcessID"
-
-# Boolean, True if memory is big-endian
PROP_BIG_ENDIAN = "BigEndian"
-
-# Number, size of memory address in bytes
PROP_ADDRESS_SIZE = "AddressSize"
-
-# String, name of the context, can be used for UI purposes
PROP_NAME = "Name"
-
-# Number, lowest address (inclusive) which is valid for the context
PROP_START_BOUND = "StartBound"
-
-# Number, highest address (inclusive) which is valid for the context
PROP_END_BOUND = "EndBound"
-
-# Array of String, the access types allowed for this context
PROP_ACCESS_TYPES = "AccessTypes"
-# Values of "AccessTypes".
-# 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.
-
-# Context represent instructions fetch access
ACCESS_INSTRUCTION = "instruction"
-
-# Context represents data access
ACCESS_DATA = "data"
-
-# Context represents IO peripherals
ACCESS_IO = "io"
-
-# Context represents a user (e.g. application running in Linux) view to memory
ACCESS_USER = "user"
-
-# Context represents a supervisor (e.g. Linux kernel) view to memory
ACCESS_SUPERVISOR = "supervisor"
-
-# Context represents a hypervisor view to memory
ACCESS_HYPERVISOR = "hypervisor"
-
-# Context uses virtual addresses
ACCESS_VIRTUAL = "virtual"
-
-# Context uses physical addresses
ACCESS_PHYSICAL = "physical"
-
-# Context is a cache
ACCESS_CACHE = "cache"
-
-# Context is a TLB memory
ACCESS_TLB = "tlb"
-# Memory access mode:
-# 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_CONTINUEONERROR = 0x1
-
-# Memory access mode:
-# Verify result of memory operations (by reading and comparing).
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 {}
@@ -105,122 +241,179 @@ class MemoryContext(object):
return "[Memory Context %s]" % self._props
def getProperties(self):
- """
- Get context properties. See PROP_* definitions for property names.
+ """Get context properties. See `Properties`_ definitions for property
+ names.
+
Context properties are read only, clients should not try to modify
them.
- @return Map of context properties.
+
+ :returns: A |dict| of context properties.
"""
return self._props
def getID(self):
- """
- Retrieve context ID.
- Same as getProperties().get('ID')
+ """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.
- Same as getProperties().get('ParentID')
+ """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.
- Same as getProperties().get('ProcessID')
+ """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.
- @return True if memory is big-endian.
+ """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.
- @return number of bytes used to store memory address value.
+ """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.
+ """Get memory context name.
+
The name can be used for UI purposes.
- @return context name.
+
+ :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.
- @return lowest address.
+ """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.
- @return highest address.
+ """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.
- @return collection of access type names.
+ """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.
+ """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.
+ """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.
- 'size' is number of bytes to fill.
+ """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 set(), get() and fill() commands.
- """
+ """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):
- """
- ErrorOffset may be implemented by MemoryError object,
- which is returned by get, set and fill commands.
+ """Error offset may be implemented by |MemoryError| object, which is
+ returned by |get|, |set| and |fill| commands.
- get/set/fill () returns this exception when reading failed
- for some but not all bytes, and MODE_CONTINUEONERROR
- has been set in mode. (For example, when only part of the request
+ 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.)
- Exception.getMessage can be used for generalized message of the
- possible reasons of partial memory operation.
+
+ 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
@@ -235,32 +428,56 @@ class ErrorOffset(object):
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.
+ """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|
- @param contextID - context ID.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract method")
def getChildren(self, parent_context_id, done):
- """
- Retrieve contexts available for memory commands.
+ """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
@@ -269,89 +486,113 @@ class MemoryService(services.Service):
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.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :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.
+ """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.
+ """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.
+ """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.
+ """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.
+ """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.
+ """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.
- Not every change is notified - it is not possible,
- only those, which are not caused by normal execution of the debuggee.
- 'addr' and 'size' can be None if unknown.
+ """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().
- """
+ """Client call back interface for |getContext|."""
def doneGetContext(self, token, error, context):
- """
- Called when context data retrieval is done.
- @param error - error description if operation failed, None if
- succeeded.
- @param context - context data.
+ """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().
- """
+ """Client call back interface for |getChildren|."""
+
def doneGetChildren(self, token, error, context_ids):
- """
- Called when context list retrieval is done.
- @param error - error description if operation failed, None if
- succeeded.
- @param context_ids - array of available 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