Skip to main content
aboutsummaryrefslogtreecommitdiffstats
path: root/python
diff options
context:
space:
mode:
authorFrederic Leger2014-03-13 12:30:09 -0400
committerFrederic Leger2014-03-13 12:30:09 -0400
commitd477eaa124f7753cd831a812855d31ba1bb61ac2 (patch)
tree4ebb190cd2f4a7c0d974cd2bc9d3752237f18a45 /python
parent6eeeb4d3c9b6bfb4763e2fde59394c0baa283293 (diff)
downloadorg.eclipse.tcf-d477eaa124f7753cd831a812855d31ba1bb61ac2.tar.gz
org.eclipse.tcf-d477eaa124f7753cd831a812855d31ba1bb61ac2.tar.xz
org.eclipse.tcf-d477eaa124f7753cd831a812855d31ba1bb61ac2.zip
Python - memory map service update.
The memorymap service can now be documented using sphinx. The __contains__() method has been added to the MemoryRegion class so that one can do something like : if address in memoryregion: # do that
Diffstat (limited to 'python')
-rw-r--r--python/src/tcf/services/memorymap.py371
1 files changed, 274 insertions, 97 deletions
diff --git a/python/src/tcf/services/memorymap.py b/python/src/tcf/services/memorymap.py
index de5e72b19..dab1138ea 100644
--- a/python/src/tcf/services/memorymap.py
+++ b/python/src/tcf/services/memorymap.py
@@ -9,119 +9,248 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-MemoryMap service provides information about executable modules (files) mapped
-(loaded) into target memory.
+"""MemoryMap service provides information about executable modules (files)
+mapped (loaded) into target memory.
+
+.. |contextquery| replace:: :mod:`~tcf.services.contextquery`
+.. |get| replace:: :meth:`~MemoryMapService.get`
+.. |set| replace:: :meth:`~MemoryMapService.set`
+.. |DoneGet| replace:: :class:`DoneGet`
+.. |DoneSet| replace:: :class:`DoneSet`
+.. |MemoryMapListener| replace:: :class:`MemoryMapListener`
+.. |MemoryRegion| replace:: :class:`MemoryRegion`
+
+
+Memory Map Properties
+---------------------
+Properties
+^^^^^^^^^^
++--------------------+--------------+-----------------------------------------+
+| Name | Type | Description |
++====================+==============+=========================================+
+| PROP_ADDRESS | |int| | Region address in memory. |
++--------------------+--------------+-----------------------------------------+
+| PROP_BSS | |bool| | **True** if the region represents BSS. |
++--------------------+--------------+-----------------------------------------+
+| PROP_CONTEXT_QUERY | |basestring| | Memory region context query. |
++--------------------+--------------+-----------------------------------------+
+| PROP_FILE_NAME | |basestring| | Name of the file. |
++--------------------+--------------+-----------------------------------------+
+| PROP_FLAGS | |int| | Region memory protection flags, see |
+| | | `Flags`_. |
++--------------------+--------------+-----------------------------------------+
+| PROP_ID | |basestring| | Memory region ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_OFFSET | |int| | Region offset in the file. |
++--------------------+--------------+-----------------------------------------+
+| PROP_SECTION_NAME | |basestring| | Name of the object file section. |
++--------------------+--------------+-----------------------------------------+
+| PROP_SIZE | |int| | Region size. |
++--------------------+--------------+-----------------------------------------+
+
+Flags
+^^^^^
+All flags are of type |int|.
+
++--------------+--------------------------------------------------------------+
+| Name | Description |
++==============+==============================================================+
+| FLAG_EXECUTE | Instruction fetch access is allowed. |
++--------------+--------------------------------------------------------------+
+| FLAG_READ | Read access is allowed. |
++--------------+--------------------------------------------------------------+
+| FLAG_WRITE | Write access is allowed. |
++--------------+--------------------------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: MemoryMapService
+
+addListener
+^^^^^^^^^^^
+.. automethod:: MemoryMapService.addListener
+
+get
+^^^
+.. automethod:: MemoryMapService.get
+
+getName
+^^^^^^^
+.. automethod:: MemoryMapService.getName
+
+removeListener
+^^^^^^^^^^^^^^
+.. automethod:: MemoryMapService.removeListener
+
+set
+^^^
+.. automethod:: MemoryMapService.set
+
+Callback Classes
+----------------
+DoneGet
+^^^^^^^
+.. autoclass:: DoneGet
+ :members:
+
+DoneSet
+^^^^^^^
+.. autoclass:: DoneSet
+ :members:
+
+Listener
+--------
+MemoryMapListener
+^^^^^^^^^^^^^^^^^
+.. autoclass:: MemoryMapListener
+ :members:
+
+Helper Classes
+--------------
+MemoryRegion
+^^^^^^^^^^^^
+.. autoclass:: MemoryRegion
+ :members:
"""
from .. import services
NAME = "MemoryMap"
-
+"""MemoryMap service name."""
# Memory region property names.
-# Number, region address in memory
-PROP_ADDRESS = "Addr"
-# String, memory region context query, see IContextQuery
+PROP_ADDRESS = "Addr"
PROP_CONTEXT_QUERY = "ContextQuery"
-
-# String, memory region ID
PROP_ID = "ID"
-
-# Number, region size
PROP_SIZE = "Size"
-
-# Number, region offset in the file
PROP_OFFSET = "Offs"
-
-# Boolean, true if the region represents BSS
PROP_BSS = "BSS"
-
-# Number, region memory protection flags, see FLAG_*
PROP_FLAGS = "Flags"
-
-# String, name of the file
PROP_FILE_NAME = "FileName"
-
-# String, name of the object file section
PROP_SECTION_NAME = "SectionName"
# Memory region flags.
-# Read access is allowed
FLAG_READ = 1
-
-# Write access is allowed
FLAG_WRITE = 2
-
-# Instruction fetch access is allowed
FLAG_EXECUTE = 4
class MemoryRegion(object):
- """Memory region object."""
+ """Memory region object.
+
+ It is possible to check that an address belongs to a memory map with
+ code like:
+
+ .. code-block:: python
+
+ # <address> is an integer, <region> is a MemoryRegion object
+
+ if address in region:
+ print address
+ :param props: Properties to initialise memory region with. See
+ `Properties`_.
+ :type props: |dict|
+ """
def __init__(self, props):
- self._props = props
+ self._props = props or {}
- def getProperties(self):
+ def __contains__(self, address):
+ """Check if *address* belongs to this memory region.
+
+ :param address: The address to check.
+ :type addess: |int|
+
+ :returns: A |bool| set to **True** if *address* belongs to this memory
+ region, **False** else.
"""
- Get region properties. See PROP_* definitions for property names.
+ rAddr = self.getAddress()
+ rOffs = self.getOffset()
+ rSize = self.getSize()
+ if address >= rAddr + rOffs and address < rAddr + rOffs + rSize:
+ return True
+ return False
+
+ def getProperties(self):
+ """Get region properties.
+
+ See `Properties`_ definitions for property names.
Properties are read only, clients should not try to modify them.
- @return Map of region properties.
+
+ :returns: A |dict| of memory region properties.
"""
- self._props
+ return (self._props)
def getAddress(self):
+ """Get memory region address.
+
+ :returns: An |int| representing the memory region address.
"""
- Get memory region address.
- @return region address.
- """
- return self._props.get(PROP_ADDRESS)
+ return self._props.get(PROP_ADDRESS, 0)
def getContextQuery(self):
- """Get context query that defines scope of the region, see also
- ContextQuery service.
- Same as getProperties().get(PROP_CONTEXT_QUERY)
+ """Get context query that defines scope of the region.
+
Only user-defined regions can have a context query property.
- @return context query expression, or None.
+
+ :returns: A context query expression, or **None**.
+
+ .. seealso:: |contextquery|
"""
return self._props.get(PROP_CONTEXT_QUERY, None)
def getSize(self):
+ """Get memory region size.
+
+ :returns: An |int| representing the memory region size.
"""
- Get memory region size.
- @return region size.
- """
- return self._props.get(PROP_SIZE)
+ return self._props.get(PROP_SIZE, 0)
def getOffset(self):
+ """Get memory region file offset.
+
+ :returns: An |int| representing the memory region file offset.
"""
- Get memory region file offset.
- @return file offset.
- """
- return self._props.get(PROP_OFFSET)
+ return self._props.get(PROP_OFFSET, 0)
def getFlags(self):
- """
- Get memory region flags.
- @return region flags.
+ """Get memory region flags.
+
+ See `Flags`_.
+
+ :returns: An |int| representing the memory region flags.
"""
return self._props.get(PROP_FLAGS, 0)
def getFileName(self):
+ """Get memory region file name.
+
+ :returns: A |basestring| representing the memory region file name.
"""
- Get memory region file name.
- @return file name.
+ return self._props.get(PROP_FILE_NAME, '')
+
+ def getID(self):
+ """Get memory region ID.
+
+ :returns: A |basestring| representing this memory region ID.
"""
- return self._props.get(PROP_FILE_NAME)
+ return self._props.get(PROP_ID, '')
def getSectionName(self):
+ """Get memory region section name.
+
+ :returns: A |basestring| representing this memory region section name.
"""
- Get memory region section name.
- @return section name.
+ return self._props.get(PROP_SECTION_NAME, '')
+
+ def isBss(self):
+ """Check if this memory region represents a BSS section.
+
+ :returns: A |bool| stating if this region is a BSS section
"""
- return self._props.get(PROP_SECTION_NAME)
+ return (self._props.get(PROP_BSS, False))
def __json__(self):
# This makes it serializable using JSON serializer
@@ -129,84 +258,132 @@ class MemoryRegion(object):
def __repr__(self):
return "MemoryRegion(%s)" % str(self._props)
- __str__ = __repr__
+
+ def __str__(self):
+ """String representation of this Instruction Set Architecture."""
+ res = self.__class__.__name__ + '['
+ res += PROP_FILE_NAME + '=' + str(self._props.get(PROP_FILE_NAME))
+ res += ', ' + PROP_ID + '=' + str(self._props.get(PROP_ID))
+ addr = self._props.get(PROP_ADDRESS)
+ if isinstance(addr, int):
+ res += ', ' + PROP_ADDRESS + '=0x{0:08x}'.format(addr)
+ elif isinstance(addr, long):
+ res += ', ' + PROP_ADDRESS + '=0x{0:016x}'.format(addr)
+ else:
+ res += ', ' + PROP_ADDRESS + '=' + str(addr)
+ res += ', ' + PROP_SIZE + '=' + str(self._props.get(PROP_SIZE))
+ offset = self._props.get(PROP_OFFSET)
+ if isinstance(offset, int):
+ res += ', ' + PROP_OFFSET + '=0x{0:x}'.format(offset)
+ else:
+ res += ', ' + PROP_OFFSET + '=' + str(offset)
+ res += ', ' + PROP_SECTION_NAME + '=' + \
+ str(self._props.get(PROP_SECTION_NAME))
+ res += ', ' + PROP_FLAGS + '='
+ flags = self._props.get(PROP_FLAGS)
+ if isinstance(flags, int):
+ if flags & FLAG_READ:
+ res += 'r'
+ else:
+ res += '-'
+ if flags & FLAG_WRITE:
+ res += 'w'
+ else:
+ res += '-'
+ if flags & FLAG_EXECUTE:
+ res += 'x'
+ else:
+ res += '-'
+ else:
+ res += '---'
+ res += ', ' + PROP_BSS + '=' + str(self._props.get(PROP_BSS) or False)
+ res += ']'
+ return res
class MemoryMapService(services.Service):
def getName(self):
+ """Get this service name.
+
+ :returns: The value of string :const:`NAME`
+ """
return NAME
def get(self, contextID, done):
- """
- Retrieve memory map for given context ID.
+ """Retrieve memory map for given context ID.
- @param contextID - context ID.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param contextID: The context ID of the memory map to retrieve.
+ :type contextID: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGet|
"""
return NotImplementedError("Abstract method")
def set(self, contextID, memoryMap, done): # @ReservedAssignment
- """
- Set memory map for given context ID.
-
- @param contextID - context ID.
- @param memoryMap - memory map data.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ """Set memory map for given context ID.
+
+ :param contextID: The context ID of the memory map to set.
+ :type contextID: |basestring|
+ :param memoryMap: The list of |MemoryRegion| to set.
+ :type memoryMap: |list|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneSet|
"""
return NotImplementedError("Abstract method")
def addListener(self, listener):
- """
- Add memory map event listener.
- @param listener - memory map event listener to add.
+ """Add memory map event listener.
+
+ :param listener: The Memory map event listener to add
+ :type listener: |MemoryMapListener|
"""
return NotImplementedError("Abstract method")
def removeListener(self, listener):
- """
- Remove memory map event listener.
- @param listener - memory map event listener to remove.
+ """Remove memory map event listener.
+
+ :param listener: The memory map event listener to remove.
+ :type listener: |MemoryMapListener|
"""
return NotImplementedError("Abstract method")
class DoneGet(object):
- """
- Client call back interface for get().
- """
+ """Client call back interface for |get| method."""
+
def doneGet(self, token, error, memoryMap):
- """
- Called when memory map data retrieval is done.
- @param error - error description if operation failed, None if
- succeeded.
- @param memoryMap - memory map data.
+ """Called when memory map data retrieval is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param memoryMap: A list of |MemoryRegion| data.
+ :type memoryMap: |list|
"""
pass
class DoneSet(object):
- """
- Client call back interface for set().
- """
+ """Client call back interface for |set| method."""
+
def doneSet(self, token, error):
- """
- Called when memory map set command is done.
- @param error - error description if operation failed, None if
- succeeded.
+ """Called when memory map set command is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class MemoryMapListener(object):
- """
- Service events listener interface.
- """
+ """Service events listener interface."""
+
def changed(self, context_id):
- """
- Called when context memory map changes.
- @param context_id - context ID.
+ """Called when context memory map changes.
+
+ :param context_id: Changed context ID.
+ :type context_id: |basestring|
"""
pass

Back to the top