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
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')
-rw-r--r--python/src/tcf/errors.py138
-rw-r--r--python/src/tcf/peer.py250
-rw-r--r--python/src/tcf/services/contextquery.py102
-rw-r--r--python/src/tcf/services/diagnostics.py599
-rw-r--r--python/src/tcf/services/disassembly.py241
-rw-r--r--python/src/tcf/services/expressions.py592
-rw-r--r--python/src/tcf/services/filesystem.py1398
-rw-r--r--python/src/tcf/services/linenumbers.py111
-rw-r--r--python/src/tcf/services/memory.py551
-rw-r--r--python/src/tcf/services/pathmap.py273
-rw-r--r--python/src/tcf/services/processes.py610
-rw-r--r--python/src/tcf/services/registers.py805
-rw-r--r--python/src/tcf/services/streams.py442
-rw-r--r--python/src/tcf/services/symbols.py1078
-rw-r--r--python/src/tcf/services/sysmonitor.py607
-rw-r--r--python/src/tcf/services/terminals.py422
16 files changed, 5931 insertions, 2288 deletions
diff --git a/python/src/tcf/errors.py b/python/src/tcf/errors.py
index 9085e29b6..d37323c45 100644
--- a/python/src/tcf/errors.py
+++ b/python/src/tcf/errors.py
@@ -14,76 +14,166 @@ import time
import types
# Error report attribute names
-ERROR_CODE = "Code" # integer
-ERROR_TIME = "Time" # integer
-ERROR_SERVICE = "Service" # string
-ERROR_FORMAT = "Format" # string
-ERROR_PARAMS = "Params" # array
-ERROR_SEVERITY = "Severity" # integer
-ERROR_ALT_CODE = "AltCode" # integer
-ERROR_ALT_ORG = "AltOrg" # string
-ERROR_CAUSED_BY = "CausedBy" # object
+
+ERROR_CODE = "Code"
+"""Integer : error code value"""
+
+ERROR_TIME = "Time"
+"""Integer : error time"""
+
+ERROR_SERVICE = "Service"
+"""String : name of the service the error occured in"""
+
+ERROR_FORMAT = "Format"
+"""String : error format"""
+
+ERROR_PARAMS = "Params"
+"""List : a list of parameters for the given error"""
+
+ERROR_SEVERITY = "Severity"
+"""Integer : error severity"""
+
+ERROR_ALT_CODE = "AltCode"
+"""Integer : error alternative code value"""
+
+ERROR_ALT_ORG = "AltOrg"
+"""Integer : error alternative org???"""
+
+ERROR_CAUSED_BY = "CausedBy"
+"""Object : the cause of the error"""
# Error severity codes
SEVERITY_ERROR = 0
+"""Error"""
+
SEVERITY_WARNING = 1
+"""Warning"""
+
SEVERITY_FATAL = 2
+"""Fatal error"""
# Error code ranges
-# Standard TCF code range */
+# Standard TCF code range
CODE_STD_MIN = 0
+"""Minimum error code value"""
CODE_STD_MAX = 0xffff
+"""Maximum error code value"""
-# Service specific codes. Decoding requires service ID. */
+# Service specific codes. Decoding requires service ID.
CODE_SERVICE_SPECIFIC_MIN = 0x10000
+"""Service specific minimum error code value"""
CODE_SERVICE_SPECIFIC_MAX = 0x1ffff
+"""Service specific maximum error code value"""
-# Reserved codes - will never be used by the TCF standard */
+# Reserved codes - will never be used by the TCF standard
CODE_RESERVED_MIN = 0x20000
+"""Service specific reserved minimum error code value"""
CODE_RESERVED_MAX = 0x2ffff
+"""Service specific reserved maximum error code value"""
# Standard TCF error codes
TCF_ERROR_OTHER = 1
+"""Other TCF errors"""
+
TCF_ERROR_JSON_SYNTAX = 2
+"""JSON syntax error"""
+
TCF_ERROR_PROTOCOL = 3
+"""Protocol error"""
+
TCF_ERROR_BUFFER_OVERFLOW = 4
+"""Buffer overflow"""
+
TCF_ERROR_CHANNEL_CLOSED = 5
+"""Channel closed"""
+
TCF_ERROR_COMMAND_CANCELLED = 6
+"""Command canceled"""
+
TCF_ERROR_UNKNOWN_PEER = 7
+"""Unknown peer"""
+
TCF_ERROR_BASE64 = 8
+"""Base64 error"""
+
TCF_ERROR_EOF = 9
+"""End of file"""
+
TCF_ERROR_ALREADY_STOPPED = 10
+"""Already stopped"""
+
TCF_ERROR_ALREADY_EXITED = 11
+"""Already exited"""
+
TCF_ERROR_ALREADY_RUNNING = 12
+"""Already running"""
+
TCF_ERROR_ALREADY_ATTACHED = 13
+"""Already attached"""
+
TCF_ERROR_IS_RUNNING = 14
+"""Is running"""
+
TCF_ERROR_INV_DATA_SIZE = 15
+"""Invalid data size"""
+
TCF_ERROR_INV_CONTEXT = 16
+"""Invalid context"""
+
TCF_ERROR_INV_ADDRESS = 17
+"""Invalid address"""
+
TCF_ERROR_INV_EXPRESSION = 18
+"""Invalid expression"""
+
TCF_ERROR_INV_FORMAT = 19
+"""Invalid format"""
+
TCF_ERROR_INV_NUMBER = 20
+"""Invalid number"""
+
TCF_ERROR_INV_DWARF = 21
+"""Invalid dwarf"""
+
TCF_ERROR_SYM_NOT_FOUND = 22
+"""Symbol not found"""
+
TCF_ERROR_UNSUPPORTED = 23
+"""Unsupported"""
+
TCF_ERROR_INV_DATA_TYPE = 24
+"""Invalid data type"""
+
TCF_ERROR_INV_COMMAND = 25
+"""Invalid command"""
+
TCF_ERROR_INV_TRANSPORT = 26
+"""Invalid transport"""
+
TCF_ERROR_CACHE_MISS = 27
+"""Cache miss"""
+
TCF_ERROR_NOT_ACTIVE = 28
+"""Not active"""
_timestamp_format = "%Y-%m-%d %H:%M:%S"
class ErrorReport(Exception):
+ """TCF error report class.
+
+ :param msg: error report message
+ :param attrs: TCF error report attributes to initialise this error report
+ with. See **ERROR_***.
+ """
def __init__(self, msg, attrs):
super(ErrorReport, self).__init__(msg)
if type(attrs) is types.IntType:
attrs = {
- ERROR_CODE : attrs,
- ERROR_TIME : int(time.time() * 1000),
- ERROR_FORMAT : msg,
- ERROR_SEVERITY : SEVERITY_ERROR
+ ERROR_CODE: attrs,
+ ERROR_TIME: int(time.time() * 1000),
+ ERROR_FORMAT: msg,
+ ERROR_SEVERITY: SEVERITY_ERROR
}
self.attrs = attrs
caused_by = attrs.get(ERROR_CAUSED_BY)
@@ -96,15 +186,31 @@ class ErrorReport(Exception):
self.caused_by = ErrorReport(bf.getvalue(), errMap)
def getErrorCode(self):
+ """Get this exception error code.
+
+ :returns: This error report error code, or **0**
+ """
return self.attrs.get(ERROR_CODE) or 0
def getAltCode(self):
+ """Get this exception alternative error code.
+
+ :returns: This error report alternative error code, or **0**
+ """
return self.attrs.get(ERROR_ALT_CODE) or 0
def getAltOrg(self):
+ """Get this exception alternative org ???
+
+ :returns: This error report alernative org???, or **None**
+ """
return self.attrs.get(ERROR_ALT_ORG)
def getAttributes(self):
+ """Get this error attribute.
+
+ :returns: a :class:`dict` of this error attributes
+ """
return self.attrs
diff --git a/python/src/tcf/peer.py b/python/src/tcf/peer.py
index 03122b1b3..6e24807de 100644
--- a/python/src/tcf/peer.py
+++ b/python/src/tcf/peer.py
@@ -9,19 +9,63 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-Both hosts and targets are represented by objects
-implementing IPeer interface. A peer can act as host or
-target depending on services it implements.
-List of currently known peers can be retrieved by
-calling Locator.getPeers()
+"""Both hosts and targets are represented by objects implementing Peer
+interface.
+
+A peer can act as host or target depending on services it implements. List of
+currently known peers can be retrieved by calling |getPeers|.
A TCF agent houses one or more service managers. A service manager has a one or
more services to expose to the world. The service manager creates one or more
-peers to represent itself, one for every access path the agent is
-reachable by. For example, in agents accessible via TCP/IP, the
-service manger would create a peer for every subnet it wants to participate in.
-All peers of particular service manager represent identical sets of services.
+peers to represent itself, one for every access path the agent is reachable by.
+
+For example, in agents accessible via TCP/IP, the service manager would create
+a peer for every subnet it wants to participate in. All peers of particular
+service manager represent identical sets of services.
+
+.. |getPeers| replace:: :meth:`tcf.services.locator.LocatorService.getPeers`
+.. |invokeAndWait| replace:: :func:`~tcf.protocol.invokeAndWait`
+.. |AssertionError| replace:: :exc:`~exception.AssertionError`
+
+Properties
+----------
++-------------------------+--------------+------------------------------------+
+| Name | Type | Description |
++=========================+==============+====================================+
+| ATTR_ID | |basestring| | Peer unique ID. |
++-------------------------+--------------+------------------------------------+
+| ATTR_SERVICE_MANAGER_ID | |basestring| | Unique ID of service manager that |
+| | | is represented by this peer. |
++-------------------------+--------------+------------------------------------+
+| ATTR_AGENT_ID | |basestring| | Agent unique ID. |
++-------------------------+--------------+------------------------------------+
+| ATTR_NAME | |basestring| | Peer name. |
++-------------------------+--------------+------------------------------------+
+| ATTR_OS_NAME | |basestring| | Name of the peer operating system. |
++-------------------------+--------------+------------------------------------+
+| ATTR_TRANSPORT_NAME | |basestring| | Transport name, for example TCP, |
+| | | SSL ... |
++-------------------------+--------------+------------------------------------+
+| ATTR_PROXY | |bool| | If present, indicates that the peer|
+| | | can forward traffic to other peers.|
++-------------------------+--------------+------------------------------------+
+| ATTR_IP_HOST | |basestring| | Host DNS name or IP address. |
++-------------------------+--------------+------------------------------------+
+| ATTR_IP_ALIASES | |list| | Optional list of host aliases. |
++-------------------------+--------------+------------------------------------+
+| ATTR_IP_ADDRESSES | |list| | Optional list of host addresses. |
++-------------------------+--------------+------------------------------------+
+| ATTR_IP_PORT | |int| | IP port number, must be decimal |
+| | | number. |
++-------------------------+--------------+------------------------------------+
+
+
+Classes
+-------
+Peer
+^^^^
+.. autoclass:: Peer
+ :members:
"""
import os
@@ -29,88 +73,174 @@ import time
from . import protocol, transport, services, channel
from .services import locator
-# Peer unique ID
ATTR_ID = "ID"
-
-# Unique ID of service manager that is represented by this peer
ATTR_SERVICE_MANAGER_ID = "ServiceManagerID"
-
-# Agent unique ID
ATTR_AGENT_ID = "AgentID"
-
-# Peer name
ATTR_NAME = "Name"
-
-# Name of the peer operating system
ATTR_OS_NAME = "OSName"
-
-# Transport name, for example TCP, SSL
ATTR_TRANSPORT_NAME = "TransportName"
-
-# If present, indicates that the peer can forward traffic to other peers
ATTR_PROXY = "Proxy"
-
-# Host DNS name or IP address
ATTR_IP_HOST = "Host"
-
-# Optional list of host aliases
ATTR_IP_ALIASES = "Aliases"
-
-# Optional list of host addresses
ATTR_IP_ADDRESSES = "Addresses"
-
-# IP port number, must be decimal number
ATTR_IP_PORT = "Port"
class Peer(object):
+ """TCF agent peer.
+
+ :param attrs: Peer attributes to initialise this peer with.
+ :type attrs: |dict|
+ """
def __init__(self, attrs):
- self.attrs = attrs
+ self.attrs = attrs or {}
+
+ def __repr__(self):
+ return str(self.__class__.__name__) + '(' + repr(self.attrs) + ')'
+
+ def __str__(self):
+ res = str(self.__class__.__name__) + ' ['
+ res += ATTR_ID + '=' + str(self.attrs.get(ATTR_ID))
+ res += ', ' + ATTR_NAME + '=' + str(self.attrs.get(ATTR_NAME))
+ res += ', ' + ATTR_PROXY + '=' + str(self.attrs.get(ATTR_PROXY))
+ res += ', ' + ATTR_OS_NAME + '=' + str(self.attrs.get(ATTR_OS_NAME))
+ res += ', ' + ATTR_AGENT_ID + '=' + str(self.attrs.get(ATTR_AGENT_ID))
+ res += ', ' + ATTR_IP_ADDRESSES + '=' + \
+ str(self.attrs.get(ATTR_IP_ADDRESSES))
+ res += ', ' + ATTR_IP_ALIASES + '=' + \
+ str(self.attrs.get(ATTR_IP_ALIASES))
+ res += ', ' + ATTR_IP_HOST + '=' + str(self.attrs.get(ATTR_IP_HOST))
+ res += ', ' + ATTR_IP_PORT + '=' + str(self.attrs.get(ATTR_IP_PORT))
+ res += ', ' + ATTR_SERVICE_MANAGER_ID + '=' + \
+ str(self.attrs.get(ATTR_SERVICE_MANAGER_ID))
+ res += ', ' + ATTR_TRANSPORT_NAME + '=' + \
+ str(self.attrs.get(ATTR_TRANSPORT_NAME))
+ res += ']'
+ return res
+
+ def getAddresses(self):
+ """Get this peer IP addresses.
+
+ :returns: A |list| representing this peer possible IP addresses, or an
+ empty list.
+ """
+ return self.attrs.get(ATTR_IP_ADDRESSES, [])
+
+ def getAgentID(self):
+ """Get this peer agent ID.
+
+ :returns: This peer's agent unique ID or an empty string
+
+ :raises: An |AssertionError| if this method is not called from the
+ dispatch thread.
+
+ .. seealso:: |invokeAndWait|
+ """
+ assert protocol.isDispatchThread()
+ return self.attrs.get(ATTR_AGENT_ID, '')
+
+ def getAliases(self):
+ """Get this peer host name aliases.
+
+ :returns: A |list| representing this peer possible host name aliases,
+ or an empty list.
+ """
+ return self.attrs.get(ATTR_IP_ALIASES, [])
def getAttributes(self):
- """@return map of peer attributes"""
+ """Get this peer attributes.
+
+ :returns: A |dict| of this peer attributes.
+ """
return self.attrs
def getID(self):
- """@return peer unique ID, same as getAttributes().get(ATTR_ID)"""
- return self.attrs.get(ATTR_ID)
+ """Get this peer ID.
- def getServiceManagerID(self):
- """@return service manager unique ID, same as
- getAttributes().get(ATTR_SERVICE_MANAGER_ID)"""
- assert protocol.isDispatchThread()
- return self.attrs.get(ATTR_SERVICE_MANAGER_ID)
+ :returns: A |basestring| representing this peer unique ID, or an empty
+ string.
+ """
+ return self.attrs.get(ATTR_ID, '')
- def getAgentID(self):
- """@return agent unique ID, same as
- getAttributes().get(ATTR_AGENT_ID)"""
- assert protocol.isDispatchThread()
- return self.attrs.get(ATTR_AGENT_ID)
+ def getHost(self):
+ """Get this peer host name.
+
+ :returns: A |basestring| representing this peer host name, or an empty
+ string.
+ """
+ return self.attrs.get(ATTR_IP_HOST, '')
def getName(self):
- """@return peer name, same as getAttributes().get(ATTR_NAME)"""
- return self.attrs.get(ATTR_NAME)
+ """Get this peer name.
+
+ :returns: A |basestring| representing this peer name, or an empty
+ string.
+ """
+ return self.attrs.get(ATTR_NAME, '')
def getOSName(self):
- """@return agent OS name, same as getAttributes().get(ATTR_OS_NAME)"""
- return self.attrs.get(ATTR_OS_NAME)
+ """Get this peer's agent OS name.
+
+ :returns: A |basestring| representing this peer agent OS name or an
+ empty string.
+ """
+ return self.attrs.get(ATTR_OS_NAME, '')
+
+ def getPort(self):
+ """Get this peer's communication port.
+
+ :returns: A |basestring| representing this peer communication port
+ number.
+ """
+ return self.attrs.get(ATTR_IP_PORT, '')
+
+ def getServiceManagerID(self):
+ """Get the peer service manager ID.
+
+ :returns: A |basestring| representing this peer's service manager
+ unique ID, or an empty string.
+
+ :raises: An |AssertionError| if this method is not
+ called from the dispatch thread.
+ """
+ assert protocol.isDispatchThread()
+ return self.attrs.get(ATTR_SERVICE_MANAGER_ID, '')
def getTransportName(self):
- """@return transport name, same as
- getAttributes().get(ATTR_TRANSPORT_NAME)"""
- return self.attrs.get(ATTR_TRANSPORT_NAME)
+ """Get this peer's transport name.
+
+ :returns: this peer agent transport name or an empty string
+
+ .. seealso:: |invokeAndWait|
+ """
+ return self.attrs.get(ATTR_TRANSPORT_NAME, '')
+
+ def isProxy(self):
+ """Check if this peer is a proxy.
+
+ :returns: A |bool| stating if this peer is a proxy or not.
+ """
+ return self.attrs.get(ATTR_PROXY, False)
def openChannel(self):
"""Open channel to communicate with this peer.
- Note: the channel is not fully open yet when this method returns.
- Its state is channel.STATE_OPENING.
- Protocol.ChannelOpenListener and IChannel.IChannelListener listeners
- will be called when the channel will change state to open or closed.
- Clients are supposed to register IChannel.IChannelListener right after
- calling openChannel(), or, at least, in same dispatch cycle.
+
+ .. note:: The channel is not fully open yet when this method returns.
+ Its state is channel.STATE_OPENING.
+ Protocol.ChannelOpenListener and channel.ChannelListener
+ listeners will be called when the channel will change state
+ to open or closed. Clients are supposed to register
+ channel.ChannelListener right after calling openChannel(),
+ or, at least, in same dispatch cycle.
+
For example:
- channel = peer.openChannel()
- channel.addChannelListener(...)
+
+ .. code-block:: python
+
+ import tcf.peer as peer
+
+ channel = peer.openChannel()
+ channel.addChannelListener(...)
"""
raise RuntimeError("Abstract method")
diff --git a/python/src/tcf/services/contextquery.py b/python/src/tcf/services/contextquery.py
index cae75e9a1..112a0fc43 100644
--- a/python/src/tcf/services/contextquery.py
+++ b/python/src/tcf/services/contextquery.py
@@ -1,5 +1,5 @@
# *****************************************************************************
-# * Copyright (c) 2012, 2013 Wind River Systems, Inc. and others.
+# * Copyright (c) 2012-2013 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
@@ -9,57 +9,109 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-TCF ContextQuery service interface.
+"""TCF ContextQuery service interface.
+
+.. |getAttrNames| replace:: :meth:`ContextQueryService.getAttrNames`
+.. |query| replace:: :meth:`ContextQueryService.query`
+.. |DoneGetAttrNames| replace:: :class:`DoneGetAttrNames`
+.. |DoneQuery| replace:: :class:`DoneQuery`
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: ContextQueryService
+
+getAttrNames
+^^^^^^^^^^^^
+.. automethod:: ContextQueryService.getAttrNames
+
+getName
+^^^^^^^
+.. automethod:: ContextQueryService.getName
+
+query
+^^^^^
+.. automethod:: ContextQueryService.query
+
+Callback Classes
+----------------
+DoneGetAttrNames
+^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetAttrNames
+ :members:
+
+DoneQuery
+^^^^^^^^^
+.. autoclass:: DoneQuery
+ :members:
"""
from .. import services
-# Service name.
NAME = "ContextQuery"
+"""ContextQuery service name."""
class ContextQueryService(services.Service):
+ """TCF context query service interface."""
+
def getName(self):
+ """Get this service name.
+
+ :returns: A |basestring| representing this service name, which is the
+ value of :const:`NAME`
+ """
return NAME
def query(self, querystr, done):
- """
- @param querystr - context query to be executed.
- @param done - command result call back object.
- @return - pending command handle.
- @see DoneQuery
+ """Get the list of contexts matching a given query.
+
+ :param querystr: Context query to be executed.
+ :type querystr: |basestring|
+ :param done: Command result call back object.
+ :type done: |DoneQuery|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract method")
def getAttrNames(self, done):
- """
- @param done - command result call back object.
- @return - pending command handle.
- @see DoneGetAttrNames
+ """Get the list of Attributes registered with the context query
+ service.
+
+ :param done: Command result call back object.
+ :type done: |DoneGetAttrNames|
+
+ :return: Pending command handle.
"""
raise NotImplementedError("Abstract method")
class DoneQuery(object):
- "Call back interface for 'query' command."
+ "Call back interface for |query| command."
+
def doneQuery(self, token, error, ctxList):
- """
- Called when 'query' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param ctxList - IDs of contexts matching the query.
+ """Called when |query| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param ctxList: IDs of contexts matching the query.
+ :type ctxList: |list|
"""
pass
class DoneGetAttrNames(object):
- "Call back interface for 'getAttrNames' command."
+ "Call back interface for |getAttrNames| command."
+
def doneGetAttrNames(self, token, error, attrNameList):
- """
- Called when 'getAttrNames' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param attrNameList - List of the attributes supported by the agent.
+ """Called when |getAttrNames| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param attrNameList: List of the attributes supported by the agent.
+ :type attrNamesList: |list|
"""
pass
diff --git a/python/src/tcf/services/diagnostics.py b/python/src/tcf/services/diagnostics.py
index 1550a09ce..f8e09000c 100644
--- a/python/src/tcf/services/diagnostics.py
+++ b/python/src/tcf/services/diagnostics.py
@@ -9,60 +9,252 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-This is an optional service that can be implemented by a peer.
+"""This is an optional service that can be implemented by a peer.
+
+.. |cancelTest| replace:: :meth:`DiagnosticsService.cancelTest`
+.. |createTestStreams| replace:: :meth:`DiagnosticsService.createTestStreams`
+.. |disposeTestStream| replace:: :meth:`DiagnosticsService.disposeTestStream`
+.. |echo| replace:: :meth:`DiagnosticsService.echo`
+.. |echoERR| replace:: :meth:`DiagnosticsService.echoERR`
+.. |echoFP| replace:: :meth:`DiagnosticsService.echoFP`
+.. |getSymbol| replace:: :meth:`DiagnosticsService.getSymbol`
+.. |getTestList| replace:: :meth:`DiagnosticsService.getTestList`
+.. |not_impl_co| replace:: :meth:`DiagnosticsService.not_implemented_command`
+.. |runTest| replace:: :meth:`DiagnosticsService.runTest`
+.. |DoneCancelTest| replace:: :class:`DoneCancelTest`
+.. |DoneCreateTestStreams| replace:: :class:`DoneCreateTestStreams`
+.. |DoneDisposeTestStream| replace:: :class:`DoneDisposeTestStream`
+.. |DoneEcho| replace:: :class:`DoneEcho`
+.. |DoneEchoERR| replace:: :class:`DoneEchoERR`
+.. |DoneEchoFP| replace:: :class:`DoneEchoFP`
+.. |DoneGetSymbol| replace:: :class:`DoneGetSymbol`
+.. |DoneGetTestList| replace:: :class:`DoneGetTestList`
+.. |DoneNotImplementedCommand| replace:: :class:`DoneNotImplementedCommand`
+.. |DoneRunTest| replace:: :class:`DoneRunTest`
+.. |Symbol| replace:: :class:`Symbol`
+.. |Symbol.getStorage| replace:: :meth:`Symbol.getStorage`
+.. |Symbol.isCommon| replace:: :meth:`Symbol.isCommon`
+.. |Symbol.isGlobal| replace:: :meth:`Symbol.isGlobal`
+.. |Symbol.isLocal| replace:: :meth:`Symbol.isLocal`
+.. |Symbol.isUndef| replace:: :meth:`Symbol.isUndef`
+
If implemented, the service can be used for testing of the peer and
communication channel functionality and reliability.
+
+Properties
+----------
+Symbol Properties
+^^^^^^^^^^^^^^^^^
+Those are the names of the properties used for |Symbol| object creation.
+
++---------------------+--------------+----------------------------------------+
+| Name | Type | Description |
++=====================+==============+========================================+
+| Symbol.ABSOLUTE | |bool| | States if the symbol address is |
+| | | absolute. |
++---------------------+--------------+----------------------------------------+
+| Symbol.SECTION_NAME | |basestring| | Name of the section the symbol belongs |
+| | | to |
++---------------------+--------------+----------------------------------------+
+| Symbol.STORAGE | |basestring| | Symbol storage type. May be any of the |
+| | | values defined in |
+| | | `Symbol Storage Properties`_. |
++---------------------+--------------+----------------------------------------+
+| Symbol.VALUE | |int| | Value of the symbol (address). |
++---------------------+--------------+----------------------------------------+
+
+Symbol Storage Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^
+All symbol storage properties are of type |basestring|. The symbol storage
+type can be retrieved with the |Symbol.getStorage| method.
+
++-----------------------+-----------------------------------------------------+
+| Name | Description |
++=======================+=====================================================+
+| Symbol.STORAGE_COMMON | Symbol is common. See |Symbol.isCommon|. |
++-----------------------+-----------------------------------------------------+
+| Symbol.STORAGE_GLOBAL | Symbol is global. See |Symbol.isGlobal|. |
++-----------------------+-----------------------------------------------------+
+| Symbol.STORAGE_LOCAL | Symbol is local. See |Symbol.isLocal|. |
++-----------------------+-----------------------------------------------------+
+| Symbol.STORAGE_UNDEF | Symbol is undefined. See |Symbol.isUndef|. |
++-----------------------+-----------------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: DiagnosticsService
+
+cancelTest
+^^^^^^^^^^
+.. automethod:: DiagnosticsService.cancelTest
+
+createTestStreams
+^^^^^^^^^^^^^^^^^
+.. automethod:: DiagnosticsService.createTestStreams
+
+disposeTestStream
+^^^^^^^^^^^^^^^^^
+.. automethod:: DiagnosticsService.disposeTestStream
+
+echo
+^^^^
+.. automethod:: DiagnosticsService.echo
+
+echoERR
+^^^^^^^
+.. automethod:: DiagnosticsService.echoERR
+
+echoFP
+^^^^^^
+.. automethod:: DiagnosticsService.echoFP
+
+getName
+^^^^^^^
+.. automethod:: DiagnosticsService.getName
+
+getSymbol
+^^^^^^^^^
+.. automethod:: DiagnosticsService.getSymbol
+
+getTestList
+^^^^^^^^^^^
+.. automethod:: DiagnosticsService.getTestList
+
+not_implemented_command
+^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: DiagnosticsService.not_implemented_command
+
+runTest
+^^^^^^^
+.. automethod:: DiagnosticsService.runTest
+
+Callback Classes
+----------------
+DoneCancelTest
+^^^^^^^^^^^^^^
+.. autoclass:: DoneCancelTest
+ :members:
+
+DoneCreateTestStreams
+^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneCreateTestStreams
+ :members:
+
+DoneDisposeTestStream
+^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneDisposeTestStream
+ :members:
+
+DoneEcho
+^^^^^^^^
+.. autoclass:: DoneEcho
+ :members:
+
+DoneEchoERR
+^^^^^^^^^^^
+.. autoclass:: DoneEchoERR
+ :members:
+
+DoneEchoFP
+^^^^^^^^^^
+.. autoclass:: DoneEchoFP
+ :members:
+
+DoneGetSymbol
+^^^^^^^^^^^^^
+.. autoclass:: DoneGetSymbol
+ :members:
+
+DoneGetTestList
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetTestList
+ :members:
+
+DoneNotImplementedCommand
+^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneNotImplementedCommand
+ :members:
+
+DoneRunTest
+^^^^^^^^^^^
+.. autoclass:: DoneRunTest
+ :members:
+
+Helper Classes
+--------------
+Symbol
+^^^^^^
+.. autoclass:: Symbol
+ :members:
"""
from .. import services
NAME = "Diagnostics"
+"""Diagnostics service name."""
class DiagnosticsService(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 echo(self, s, done):
- """
- 'echo' command result returns same string that was given as command
- argument.
+ """The |echo| command result returns same string that was given as
+ command argument.
+
The command is used to test communication channel ability to transmit
arbitrary strings in both directions.
- @param s - any string.
- @param done - command result call back object.
- @return - pending command handle.
+
+ :param s: Any string.
+ :type s: |basestring|
+ :param done: Command result call back object.
+ :type done: |DoneEcho|
+
+ :returns: Pending command handle.
"""
return NotImplementedError("Abstract method")
def echoFP(self, n, done):
- """
- 'echoFP' command result returns same floating point number that was
- given as command argument.
+ """The |echoFP| command result returns same floating point number that
+ was given as command argument.
+
The command is used to test communication channel ability to transmit
arbitrary floating point numbers in both directions.
- @param n - any floating point number.
- @param done - command result call back object.
- @return - pending command handle.
+
+ :param n: Any floating point number.
+ :type n: |float|
+ :param done: Command result call back object.
+ :type done: |DoneEchoFP|
+
+ :returns: Pending command handle.
"""
return NotImplementedError("Abstract method")
def echoERR(self, error, done):
- """
- 'echoERR' command result returns same error report that was given as
- command argument.
+ """The |echoERR| command result returns same error report that was
+ given as command argument.
+
The command is used to test remote agent ability to receive and
transmit TCF error reports.
- @param error - an error object.
- @param done - command result call back object.
- @return - pending command handle.
+
+ :param error: An error object.
+ :type error: |Exception|
+ :param done: Command result call back object.
+ :type done: |DoneEchoERR|
+
+ :returns: pending command handle.
"""
return NotImplementedError("Abstract method")
def getTestList(self, done):
- """
- Get list of test names that are implemented by the service.
+ """Get list of test names that are implemented by the service.
+
Clients can request remote peer to run a test from the list.
When started, a test performs a predefined set actions.
Nature of test actions is uniquely identified by test name.
@@ -70,243 +262,354 @@ class DiagnosticsService(services.Service):
remote peer, and it is not part of Diagnostics service specifications.
Clients should not attempt to run a test if they don't recognize the
test name.
- @param done - command result call back object.
- @return - pending command handle.
+
+ :param done: Command result call back object.
+ :type done: |DoneGetTestList|
+
+ :returns: Pending command handle.
"""
return NotImplementedError("Abstract method")
def runTest(self, name, done):
- """
- Run a test. When started, a test performs a predefined set actions.
+ """Run a test.
+
+ When started, a test performs a predefined set actions.
Nature of test actions is uniquely identified by test name.
Running test usually has associated execution context ID.
Depending on the test, the ID can be used with services RunControl
and/or Processes services to control test execution, and to obtain
test results.
- @param name - test name
- @param done - command result call back object.
- @return - pending command handle.
+
+ :param name: Test name. Must be one of the names returned by
+ |getTestList|.
+ :type name: |basestring|
+ :param done: Command result call back object.
+ :type done: |DoneRunTest|
+
+ :returns: Pending command handle.
"""
return NotImplementedError("Abstract method")
def cancelTest(self, context_id, done):
- """
- Cancel execution of a test.
- @param context_id - text execution context ID.
- @param done - command result call back object.
- @return - pending command handle.
+ """Cancel execution of a test.
+
+ :param context_id: Test execution context ID. Must be the TCF ID
+ returned by a |runTest| command.
+ :type context_id: |basestring|
+ :param done: Command result call back object.
+ :type done: |DoneCancelTest|
+
+ :returns: Pending command handle.
"""
return NotImplementedError("Abstract method")
def getSymbol(self, context_id, symbol_name, done):
- """
- Get information about a symbol in text execution context.
- @param context_id
- @param symbol_name
- @param done
- @return
+ """Get information about a symbol in text execution context.
+
+ There is a set of predefined symbols for a diagnostics test. For the
+ opensource agent, those are :
+
+ - ``tcf_test_array``
+ - ``tcf_test_char``
+ - ``tcf_test_func0``
+ - ``tcf_test_func1``
+ - ``tcf_test_func2``
+ - ``tcf_test_func3``
+
+ :param context_id: Test context ID. Must be the TCF ID returned by a
+ |runTest| command.
+ :param symbol_name: Name of the symbol to retrieve.
+ :param done: Command result call back object.
+ :type done: |DoneGetSymbol|
+
+ :returns: A |Symbol| matching *context_id* and *name*.
"""
return NotImplementedError("Abstract method")
def createTestStreams(self, inp_buf_size, out_buf_size, done):
- """
- Create a pair of virtual streams, @see IStreams service.
- Remote ends of the streams are connected, so any data sent into 'inp'
- stream will become for available for reading from 'out' stream.
+ """Create a pair of virtual streams
+
+ Remote ends of the streams are connected, so any data sent into *input*
+ stream will become for available for reading from *output* stream.
The command is used for testing virtual streams.
- @param inp_buf_size - buffer size in bytes of the input stream.
- @param out_buf_size - buffer size in bytes of the output stream.
- @param done - command result call back object.
- @return - pending command handle.
+
+ :param inp_buf_size: Buffer size in bytes of the input stream.
+ :type inp_buf_size: |int|
+ :param out_buf_size: Buffer size in bytes of the output stream.
+ :type out_buf_size: |int|
+ :param done: Command result call back object.
+ :type done: |DoneCreateTestStreams|
+
+ :returns: Pending command handle.
+
+ :seealso: :class:`tcf.services.streams` service.
"""
return NotImplementedError("Abstract method")
def disposeTestStream(self, streamID, done):
- """
- Dispose a virtual stream that was created by 'createTestStreams'
+ """Dispose a virtual stream that was created by |createTestStreams|
command.
- @param streamID - the stream ID.
- @param done - command result call back object.
- @return - pending command handle.
+
+ :param streamID: The stream ID. Must be one of the IDs returned by
+ |createTestStreams|.
+ :type streamID: |basestring|
+ :param done: Command result call back object.
+ :type done: |DoneDisposeTestStream|
+
+ :returns: Pending command handle.
"""
return NotImplementedError("Abstract method")
def not_implemented_command(self, done):
- """
- Send a command that is not implemented by peer.
- Used to test handling of 'N' messages by communication channel.
- @param done - command result call back object.
- @return - pending command handle.
+ """Send a command that is not implemented by peer.
+
+ :param done: Command result call back object
+ :type done: |DoneNotImplementedCommand|
+
+ :returns: Pending command handle.
"""
return NotImplementedError("Abstract method")
class DoneEcho(object):
- """
- Call back interface for 'echo' command.
- """
+ """Call back interface for |echo| command."""
+
def doneEcho(self, token, error, s):
- """
- Called when 'echo' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param s - same string as the command argument.
+ """Called when |echo| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param s: Same string as the command argument.
+ :type s: |basestring|
"""
pass
class DoneEchoFP(object):
- """
- Call back interface for 'echoFP' command.
- """
+ """Call back interface for |echoFP| command."""
+
def doneEchoFP(self, token, error, n):
- """
- Called when 'echoFP' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param n - same number as the command argument.
+ """Called when :meth:`~.DiagnosticsService.echoFP` command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param n: Same number as the command argument.
+ :type n: |int|
"""
pass
class DoneEchoERR(object):
- """
- Call back interface for 'echoERR' command.
- """
+ """Call back interface for |echoERR| command."""
+
def doneEchoERR(self, token, error, error_obj, error_msg):
- """
- Called when 'echoERR' command is done.
- @param token - command handle.
- @param error - communication error report or None.
- @param error_obj - error object, should be equal to the command
- argument.
- @param error_msg - error object converted to a human readable string.
+ """Called when |echoERR| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param error_obj: Error object, should be equal to the command
+ argument.
+ :type error_obj: |Exception|
+ :param error_msg: Error object converted to a human readable string.
+ :type error_msg: |basestring|
"""
pass
class DoneGetTestList(object):
- """
- Call back interface for 'getTestList' command.
- """
+ """Call back interface for |getTestList| command."""
+
def doneGetTestList(self, token, error, testList):
- """
- Called when 'getTestList' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param testList - names of tests that are supported by the peer.
+ """Called when |getTestList| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param testList: Names of tests that are supported by the peer.
+ :type testList: |list|
"""
pass
class DoneRunTest(object):
- """
- Call back interface for 'runTest' command.
- """
+ """Call back interface for |runTest| command."""
+
def doneRunTest(self, token, error, context_id):
- """
- Called when 'runTest' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param context_id - test execution contest ID.
+ """Called when |runTest| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context_id: Test execution contest ID.
+ :type context_id: |basestring|
"""
pass
class DoneCancelTest(object):
- """
- Call back interface for 'cancelTest' command.
- """
+ """Call back interface for |cancelTest| command."""
+
def doneCancelTest(self, token, error):
- """
- Called when 'cancelTest' command is done.
- @param token - command handle.
- @param error - error object or None.
+ """Called when |cancelTest| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class DoneGetSymbol(object):
- """
- Call back interface for 'getSymbol' command.
- """
+ """Call back interface for |getSymbol| command."""
+
def doneGetSymbol(self, token, error, symbol):
- """
- Called when 'getSymbol' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param symbol
+ """Called when |getSymbol| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param symbol: The so-retrieved symbol.
+ :type symbol: |Symbol|
"""
pass
class Symbol(object):
+ """Represents result value of |getSymbol| command.
+
+ :param props: Properties to initialise this symbol with. See
+ `Symbol Properties`_.
+ :type props: |dict|
"""
- Represents result value of 'getSymbol' command.
- """
+
+ ABSOLUTE = 'Abs'
+ SECTION_NAME = 'Section'
+ STORAGE = 'Storage'
+ VALUE = 'Value'
+
+ STORAGE_COMMON = 'COMMON'
+ STORAGE_GLOBAL = 'GLOBAL'
+ STORAGE_LOCAL = 'LOCAL'
+ STORAGE_UNDEF = 'UNDEF'
def __init__(self, props):
self._props = props or {}
+ def __str__(self):
+ return (str(self._props))
+
def getSectionName(self):
- return self._props.get("Section")
+ """Get this symbol section name.
+
+ :returns: A |basestring| representing this symbol section name or
+ **None**.
+ """
+ return self._props.get(self.SECTION_NAME)
+
+ def getStorage(self):
+ """Get this symbol storage type.
+
+ The returned vaue is one of :
+
+ - ``Symbol.STORAGE_COMMON`` (see |Symbol.isCommon|)
+ - ``Symbol.STORAGE_GLOBAL`` (see |Symbol.isGlobal|)
+ - ``Symbol.STORAGE_LOCAL`` (see |Symbol.isLocal|)
+ - ``Symbol.STORAGE_UNDEF`` (see |Symbol.isUndef|)
+ - **None** if unknown
+
+ :returns: A |basestring| representing this symbol storage type or
+ **None**.
+ """
+ return self._props.get(self.STORAGE)
def getValue(self):
- return self._props.get("Value")
+ """Get this symbol value (address).
+
+ :returns: An |int| representing this symbol value (address) or **0**.
+ """
+ return self._props.get(self.VALUE)
def isUndef(self):
- val = self._props.get("Storage")
- return val == "UNDEF"
+ """Check if this symbol storage type is ``UNDEF``.
+
+ :returns: A |bool| stating if this symbol's storage is undefined.
+ """
+ val = self._props.get(self.STORAGE)
+ return val == self.STORAGE_UNDEF
def isCommon(self):
- val = self._props.get("Storage")
- return val == "COMMON"
+ """Check if this symbol storage type is ``COMMON``.
+
+ :returns: A |bool| stating if this symbol's storage is common.
+ """
+ val = self._props.get(self.STORAGE)
+ return val == self.STORAGE_COMMON
def isGlobal(self):
- val = self._props.get("Storage")
- return val == "GLOBAL"
+ """Check if this symbol storage type is ``GLOBAL``.
+
+ :returns: A |bool| stating if this symbol's storage is global.
+ """
+ val = self._props.get(self.STORAGE)
+ return val == self.STORAGE_GLOBAL
def isLocal(self):
- val = self._props.get("Storage")
- return val == "LOCAL"
+ """Check if this symbol storage type is ``LOCAL``.
+
+ :returns: A |bool| stating if this symbol's storage is local.
+ """
+ val = self._props.get(self.STORAGE)
+ return val == self.STORAGE_LOCAL
def isAbs(self):
- return self._props.get("Abs", False)
+ """Check if this symbol is absolute.
+
+ :returns: A |bool| stating if this symbol is absolute.
+ """
+ return self._props.get(self.ABSOLUTE, False)
class DoneCreateTestStreams(object):
- """
- Call back interface for 'createTestStreams' command.
- """
+ """Call back interface for |createTestStreams| command."""
+
def doneCreateTestStreams(self, token, error, inp_id, out_id):
- """
- Called when 'createTestStreams' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param inp_id - the input stream ID.
- @param out_id - the output stream ID.
+ """Called when |createTestStreams| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param inp_id: The input stream ID.
+ :type inp_id: |basestring|
+ :param out_id: The output stream ID.
+ :type out_id: |basestring|
"""
pass
class DoneDisposeTestStream(object):
- """
- Call back interface for 'disposeTestStream' command.
- """
+ """Call back interface for |disposeTestStream| command."""
+
def doneDisposeTestStream(self, token, error):
- """
- Called when 'createTestStreams' command is done.
- @param token - command handle.
- @param error - error object or None.
+ """Called when |createTestStreams| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class DoneNotImplementedCommand(object):
+ """Call back interface for |not_impl_co| command."""
+
def doneNotImplementedCommand(self, token, error):
- """
- Called when 'not_implemented_command' command is done.
- @param token - command handle.
- @param error - error object.
+ """Called when |not_impl_co| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
diff --git a/python/src/tcf/services/disassembly.py b/python/src/tcf/services/disassembly.py
index 2f489fd1d..9a656fe9d 100644
--- a/python/src/tcf/services/disassembly.py
+++ b/python/src/tcf/services/disassembly.py
@@ -9,107 +9,220 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-TCF Disassembly service interface.
+"""TCF Disassembly service interface.
+
+Disassembly Properties
+----------------------
+Properties
+^^^^^^^^^^
++------------------+--------------+-------------------------------------------+
+| Name | Type | Description |
++==================+==============+===========================================+
+| PROP_ISA | |basestring| | The name of the instruction set |
+| | | architecture. |
++------------------+--------------+-------------------------------------------+
+| PROP_OPCODEVALUE | |bool| | If **True**, the instruction code byte |
+| | | values are returned. |
++------------------+--------------+-------------------------------------------+
+| PROP_PSEUDO | |bool| | If **True**, pseudo-instructions are |
+| | | requested. |
++------------------+--------------+-------------------------------------------+
+| PROP_SIMPLIFIED | |bool| | If **True**, simplified mnemonics are |
+| | | specified. |
++------------------+--------------+-------------------------------------------+
+
+Capabilities
+^^^^^^^^^^^^
++------------------------+--------------+-------------------------------------+
+| Name | Type | Description |
++========================+==============+=====================================+
+| CAPABILITY_ISA | |basestring| | The name of the instruction set |
+| | | architecture. |
++------------------------+--------------+-------------------------------------+
+| CAPABILITY_OPCODEVALUE | |bool| | If **True**, the decoded instruction|
+| | | code bytes are retrievable with the |
+| | | OpcodeValue parameter. |
++------------------------+--------------+-------------------------------------+
+| CAPABILITY_PSEUDO | |bool| | If **True**, pseudo-instructions are|
+| | | supported or requested. |
++------------------------+--------------+-------------------------------------+
+| CAPABILITY_SIMPLIFIED | |bool| | If **True**, simplified mnemonics |
+| | | are supported or requested. |
++------------------------+--------------+-------------------------------------+
+
+Fields
+^^^^^^
++---------------------+--------------+----------------------------------------+
+| Name | Type | Description |
++=====================+==============+========================================+
+| FIELD_ADDRESS_SPACE | |int| | Context ID of the address space used |
+| | | with ``FTYPE_ADDRESS`` types. |
++---------------------+--------------+----------------------------------------+
+| FIELD_TEXT | |basestring| | Value of the field for ``FTYPE_STRING``|
+| | | and ``FTYPE_REGISTER`` types. |
++---------------------+--------------+----------------------------------------+
+| FIELD_TYPE | |basestring| | Instruction field properties. The type |
+| | | of the instruction field. See |
+| | | `Field Types`_. |
++---------------------+--------------+----------------------------------------+
+| FIELD_VALUE | |int| | Value of the field for |
+| | | ``FTYPE_ADDRESS``, |
+| | | ``FTYPE_DISPLACEMENT``, or |
+| | | ``FTYPE_IMMEDIATE`` types. |
++---------------------+--------------+----------------------------------------+
+
+Field Types
+^^^^^^^^^^^
++--------------------+--------------------------------------+
+| Name | Description |
++====================+======================================+
+| FTYPE_ADDRESS | Instruction field type Address. |
++--------------------+--------------------------------------+
+| FTYPE_DISPLACEMENT | Instruction field type Displacement. |
++--------------------+--------------------------------------+
+| FTYPE_IMMEDIATE | Instruction field type Immediate. |
++--------------------+--------------------------------------+
+| FTYPE_REGISTER | Instruction field type Register. |
++--------------------+--------------------------------------+
+| FTYPE_STRING | Instruction field type String. |
++--------------------+--------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: DisassemblyService
+
+disassemble
+^^^^^^^^^^^
+.. automethod:: DisassemblyService.disassemble
+
+getCapabilities
+^^^^^^^^^^^^^^^
+.. automethod:: DisassemblyService.getCapabilities
+
+getName
+^^^^^^^
+.. automethod:: DisassemblyService.getName
+
+Callback Classes
+----------------
+DoneDisassemble
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneDisassemble
+ :members:
+
+DoneGetCapabilities
+^^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetCapabilities
+ :members:
+
+Helper Classes
+--------------
+DisassemblyLine
+^^^^^^^^^^^^^^^
+.. autoclass:: DisassemblyLine
+ :members:
"""
from .. import services
NAME = "Disassembly"
+"""Disassembly service name."""
-# The name of the instruction set architecture, String
CAPABILITY_ISA = "ISA"
-
-# If true, simplified mnemonics are supported or requested, Boolean
CAPABILITY_SIMPLIFIED = "Simplified"
-
-# If true, pseudo-instructions are supported or requested, Boolean
CAPABILITY_PSEUDO = "Pseudo"
+CAPABILITY_OPCODEVALUE = "OpcodeValue"
-
-# Instruction field properties
-# The type of the instruction field. See FTYPE_*, String.
FIELD_TYPE = "Type"
-
-# Value of the field for "String" and "Register" types, String.
FIELD_TEXT = "Text"
-
-# Value of the field for "Address," "Displacement," or "Immediate" types,
-# Number.
FIELD_VALUE = "Value"
-
-# Context ID of the address space used with "Address" types, String.
FIELD_ADDRESS_SPACE = "AddressSpace"
# Instruction field types
FTYPE_STRING = "String"
-FTYPE_Register = "Register"
+FTYPE_REGISTER = "Register"
FTYPE_ADDRESS = "Address"
FTYPE_DISPLACEMENT = "Displacement"
FTYPE_IMMEDIATE = "Immediate"
+# disassemble parameters
+PROP_ISA = "ISA"
+PROP_SIMPLIFIED = "Simplified"
+PROP_PSEUDO = "PseudoInstructions"
+PROP_OPCODEVALUE = "OpcodeValue"
+
class DisassemblyService(services.Service):
def getName(self):
+ """Get this service name.
+
+ :returns: The value of string :const:`NAME`
+ """
return NAME
def getCapabilities(self, context_id, done):
- """
- Retrieve disassembly service capabilities a given context-id.
- @param context_id - a context ID, usually one returned by Run Control
+ """Retrieve disassembly service capabilities a given context-id.
+
+ :param context_id: a context ID, usually one returned by Run Control
or Memory services.
- @param done - command result call back object.
- @return - pending command handle.
+ :param done: command result call back object.
+ :type done: :class:`DoneGetCapabilities`
+
+ :returns: pending command handle.
"""
raise NotImplementedError("Abstract method")
def disassemble(self, context_id, addr, size, params, done):
- """
- Disassemble instruction code from a specified range of memory
+ """Disassemble instruction code from a specified range of memory
addresses, in a specified context.
- @param context_id - a context ID, usually one returned by Run Control
+
+ :param context_id: a context ID, usually one returned by Run Control
or Memory services.
- @param addr - address of first instruction to disassemble.
- @param size - size in bytes of the address range.
- @param params - properties to control the disassembly output, an
- element of capabilities array, see getCapabilities.
- @param done - command result call back object.
- @return - pending command handle.
+ :param addr: address of first instruction to disassemble.
+ :param size: size in bytes of the address range.
+ :param params: properties to control the disassembly output, an
+ element of capabilities array, see
+ :meth:`~DisassemblyService.getCapabilities`
+ :param done: command result call back object.
+ :type done: :class:`DoneDisassemble`
+
+ :returns: pending command handle.
"""
class DoneGetCapabilities(object):
- """
- Call back interface for 'getCapabilities' command.
- """
+ """Call back interface for 'getCapabilities' command."""
def doneGetCapabilities(self, token, error, capabilities):
- """
- Called when capabilities retrieval is done.
- @param token - command handle.
- @param error - error object or None.
- @param capabilities - array of capabilities, see CAPABILITY_* for
+ """Called when capabilities retrieval is done.
+
+ :param token: command handle.
+ :param error: error object or None.
+ :param capabilities: array of capabilities, see `Capabilities`_ for
contents of each array element.
"""
pass
class DoneDisassemble(object):
- """
- Call back interface for 'disassemble' command.
- """
+ """Call back interface for 'disassemble' command."""
def doneDisassemble(self, token, error, disassembly):
- """
- Called when disassembling is done.
- @param token - command handle.
- @param error - error object or None.
- @param disassembly - array of disassembly lines.
+ """Called when disassembling is done.
+
+ :param token: command handle.
+ :param error: error object or None.
+ :param disassembly: array of disassembly lines.
"""
pass
class DisassemblyLine(object):
- """
- Represents a single disassembly line.
+ """Represents a single disassembly line.
+
+ :param addr: Address of the disassembled line.
+ :param size: The size (in bytes) of this disassembled line.
+ :param instuction: Disassembled instruction.
+ :param opcode: Instruction opcode (if any)
"""
def __init__(self, addr, size, instruction, opcode=None):
self.addr = addr
@@ -119,29 +232,41 @@ class DisassemblyLine(object):
def getAddress(self):
"""
- @return instruction address.
+ :returns: Instruction address.
"""
return self.addr
def getOpcodeValue(self):
"""
- @return instruction address.
+ :returns: instruction address.
"""
return self.opcode
def getSize(self):
"""
- @return instruction size in bytes.
+ :returns: Instruction size in bytes.
"""
return self.size
def getInstruction(self):
- """
- @return array of instruction fields, each field is a collection of
- field properties, see FIELD_*.
+ """Get disassembled instruction.
+
+ :returns: array of instruction fields, each field is a collection of
+ field properties, see `Fields`_.
"""
return self.instruction
+ def __repr__(self):
+ res = self.__class__.__name__ + '(' + repr(self.addr) + ', ' + \
+ repr(self.size) + ', ' + repr(self.instruction) + ', ' + \
+ repr(self.opcode) + ')'
+ return res
+
def __str__(self):
- instr = "".join(map(str, self.instruction))
- return "[%s %s %s]" % (self.addr, self.size, instr)
+ op = self.opcode
+ oplen = len(op)
+ res = self.__class__.__name__ + ' [address=' + str(self.addr) + \
+ ', size=' + str(self.size) + ', instruction=' + \
+ str(self.instruction) + ', opcode=' + \
+ ' '.join('%02x' % ord(byte) for byte in op[0:oplen]) + ']'
+ return res
diff --git a/python/src/tcf/services/expressions.py b/python/src/tcf/services/expressions.py
index 68c727ece..6d08cf1d0 100644
--- a/python/src/tcf/services/expressions.py
+++ b/python/src/tcf/services/expressions.py
@@ -9,30 +9,206 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-Expressions service allows TCF client to perform expression evaluation on
+"""Expressions service allows TCF client to perform expression evaluation on
remote target.
+
The service can be used to retrieve or modify values of variables or any data
structures in remote target memory.
+
+Expressions Properties
+----------------------
+Context Properties
+^^^^^^^^^^^^^^^^^^
++--------------------+--------------+-----------------------------------------+
+| Name | Type | Description |
++====================+==============+=========================================+
+| PROP_BITS | |int| | Size of expression value in bits. |
++--------------------+--------------+-----------------------------------------+
+| PROP_CAN_ASSIGN | |bool| | **True** if the expression can be |
+| | | assigned a new value. |
++--------------------+--------------+-----------------------------------------+
+| PROP_CLASS | |basestring| | Expression type class. See |
+| | | :class:`~tcf.services.symbols.TypeClass`|
++--------------------+--------------+-----------------------------------------+
+| PROP_EXPRESSION | |basestring| | Expression script. |
++--------------------+--------------+-----------------------------------------+
+| PROP_HAS_FUNC_CALL | |bool| | **True** if the expression contains |
+| | | target function call. |
++--------------------+--------------+-----------------------------------------+
+| PROP_ID | |basestring| | Expression context ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_LANGUAGE | |basestring| | Language of expression script. |
++--------------------+--------------+-----------------------------------------+
+| PROP_PARENT_ID | |basestring| | ID of expression's parent context. |
++--------------------+--------------+-----------------------------------------+
+| PROP_SIZE | |int| | Size in bytes. |
++--------------------+--------------+-----------------------------------------+
+| PROP_SYMBOL_ID | |basestring| | Symbol ID if the expression represents a|
+| | | symbol. |
++--------------------+--------------+-----------------------------------------+
+| PROP_TYPE | |basestring| | Expression type ID. |
++--------------------+--------------+-----------------------------------------+
+
+Value Properties
+^^^^^^^^^^^^^^^^
++----------------+------------------------------------------------------------+
+| Name | Description |
++================+============================================================+
+| VAL_ADDRESS | If the value is located in target memory, the address of |
+| | the value. |
++----------------+------------------------------------------------------------+
+| VAL_BIG_ENDIAN | Expression is big endian. |
++----------------+------------------------------------------------------------+
+| VAL_CLASS | Value type class. See |
+| | :class:`~tcf.services.symbols.TypeClass`. |
++----------------+------------------------------------------------------------+
+| VAL_REGISTER | If the value is located in a register, the register ID |
+| | that holds the value. |
++----------------+------------------------------------------------------------+
+| VAL_SYMBOL | If the value is defined by a symbol, the symbol ID. |
++----------------+------------------------------------------------------------+
+| VAL_TYPE | The symbol type ID of the value. |
++----------------+------------------------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: ExpressionsService
+
+addListener
+^^^^^^^^^^^
+.. automethod:: ExpressionsService.addListener
+
+assign
+^^^^^^
+.. automethod:: ExpressionsService.assign
+
+create
+^^^^^^
+.. automethod:: ExpressionsService.create
+
+dispose
+^^^^^^^
+.. automethod:: ExpressionsService.dispose
+
+evaluate
+^^^^^^^^
+.. automethod:: ExpressionsService.evaluate
+
+getChildren
+^^^^^^^^^^^
+.. automethod:: ExpressionsService.getChildren
+
+getContext
+^^^^^^^^^^
+.. automethod:: ExpressionsService.getContext
+
+getName
+^^^^^^^
+.. automethod:: ExpressionsService.getName
+
+removeListener
+^^^^^^^^^^^^^^
+.. automethod:: ExpressionsService.removeListener
+
+Callback Classes
+----------------
+DoneAssign
+^^^^^^^^^^
+.. autoclass:: DoneAssign
+ :members:
+
+DoneCreate
+^^^^^^^^^^
+.. autoclass:: DoneCreate
+ :members:
+
+DoneDispose
+^^^^^^^^^^^
+.. autoclass:: DoneDispose
+ :members:
+
+DoneEvaluate
+^^^^^^^^^^^^
+.. autoclass:: DoneEvaluate
+ :members:
+
+DoneGetChildren
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetChildren
+ :members:
+
+DoneGetContext
+^^^^^^^^^^^^^^
+.. autoclass:: DoneGetContext
+ :members:
+
+Listener
+--------
+.. autoclass:: ExpressionsListener
+ :members:
+
+Helper Classes
+--------------
+Expression
+^^^^^^^^^^
+.. autoclass:: Expression
+ :members:
+
+Value
+^^^^^
+.. autoclass:: Value
+ :members:
+
"""
from .. import services
+from . import symbols
-# Service name.
NAME = "Expressions"
+"""Expressions service name."""
+
+# Expression context property names.
+
+PROP_ID = "ID"
+PROP_PARENT_ID = "ParentID"
+PROP_SYMBOL_ID = "SymbolID"
+PROP_LANGUAGE = "Language"
+PROP_EXPRESSION = "Expression"
+PROP_BITS = "Bits"
+PROP_SIZE = "Size"
+PROP_TYPE = "Type"
+PROP_CAN_ASSIGN = "CanAssign"
+PROP_HAS_FUNC_CALL = "HasFuncCall"
+PROP_CLASS = "Class" # same as symbols.TypeClass
+
+# Expression value property names.
+
+VAL_CLASS = "Class" # same as symbols.TypeClass
+VAL_TYPE = "Type"
+VAL_SYMBOL = "Symbol"
+VAL_REGISTER = "Register"
+VAL_ADDRESS = "Address"
+VAL_BIG_ENDIAN = "BigEndian"
class Expression(object):
- """
- Expression object represent an expression that can be evaluated by remote
- target.
+ """Expression object represent an expression that can be evaluated by
+ remote target.
+
It has a unique ID and contains all information necessary to compute a
value.
+
The object data usually includes:
- 1. process, thread or stack frame ID that should be used to resolve
- symbol names
- 2. a script that can compute a value, like "x.y + z"
+
+ 1. process, thread or stack frame ID that should be used to resolve
+ symbol names
+ 2. a script that can compute a value, like ``x.y + z``
+
+ :param props: Property dictionnary defining the expression.
+ See `Context Properties`_.
"""
+
def __init__(self, props):
self._props = props or {}
@@ -40,108 +216,114 @@ class Expression(object):
return "[Expression Context %s]" % self._props
def getID(self):
- """
- Get context ID.
- @return context ID.
+ """Get context ID.
+
+ :returns: Context ID.
"""
return self._props.get(PROP_ID)
def getParentID(self):
- """
- Get parent context ID.
- @return parent context ID.
+ """Get parent context ID.
+
+ :returns: Parent context ID.
"""
return self._props.get(PROP_PARENT_ID)
def getLanguage(self):
- """
- Get expression script language ID.
- @return language ID.
+ """Get expression script language ID.
+
+ :returns: Language ID.
"""
return self._props.get(PROP_LANGUAGE)
def getExpression(self):
- """
- Return expression string - the script part of the context.
- @return expression script string
+ """Return expression string - the script part of the context.
+
+ :returns: Expression script string.
"""
return self._props.get(PROP_EXPRESSION)
def getSymbolID(self):
- """
- Return symbol ID if the expression represents a symbol (e.g. local
+ """Return symbol ID if the expression represents a symbol (e.g. local
variable).
- @return symbol ID
+
+ :returns: Symbol ID.
"""
return self._props.get(PROP_SYMBOL_ID)
def getBits(self):
- """
- Get size of expression value in bits.
- Can be 0 if value size is even number of bytes, use getSize() in such
- case.
- @return size in bits.
+ """Get size of expression value in bits.
+
+ Can be **0** if value size is even number of bytes, use :meth:`getSize`
+ in such case.
+
+ :returns: Size in bits.
"""
return self._props.get(PROP_BITS, 0)
def getSize(self):
- """
- Get size in bytes. The size can include extra (unused) bits.
- This is "static" or "declared" size - as determined by expression type.
- @return size in bytes.
+ """Get size in bytes. The size can include extra (unused) bits.
+
+ This is *static* or *declared* size - as determined by expression type.
+
+ :returns: Size in bytes.
"""
return self._props.get(PROP_SIZE, 0)
- def getTypeID(self):
+ def getTypeClass(self):
+ """Get expression type class.
+
+ :returns: type class
+
+ .. seealso: :class:`~tcf.services.symbols.TypeClass`
"""
- Get expression type ID. Symbols service can be used to get type
+ return self._props.get(PROP_CLASS, symbols.TypeClass.unknown)
+
+ def getTypeID(self):
+ """Get expression type ID. Symbols service can be used to get type
properties.
- This is "static" or "declared" type ID, actual type of a value can be
+
+ This is *static* or *declared* type ID, actual type of a value can be
different - if expression language supports dynamic typing.
- @return type ID.
+
+ :returns: Type ID.
+
+ .. seealso:: :mod:`~tcf.services.symbols`
"""
return self._props.get(PROP_TYPE)
def canAssign(self):
- """
- Check if the expression can be assigned a new value.
- @return true if can assign.
+ """Check if the expression can be assigned a new value.
+
+ :returns: **True** if can assign.
"""
return self._props.get(PROP_CAN_ASSIGN)
def hasFuncCall(self):
- """
- Check if the expression contains target function call.
+ """Check if the expression contains target function call.
+
Such expression can resume the target when evaluated.
- @return true if has a function call.
+
+ :returns: **True** if has a function call.
"""
return (self._props.get(PROP_HAS_FUNC_CALL))
def getProperties(self):
- """
- Get complete map of context properties.
- @return map of context properties.
+ """Get complete dictionary of context properties.
+
+ :returns: A |dict| of context properties.
"""
return self._props
-# Expression context property names.
-PROP_ID = "ID"
-PROP_PARENT_ID = "ParentID"
-PROP_SYMBOL_ID = "SymbolID"
-PROP_LANGUAGE = "Language"
-PROP_EXPRESSION = "Expression"
-PROP_BITS = "Bits"
-PROP_SIZE = "Size"
-PROP_TYPE = "Type"
-PROP_CAN_ASSIGN = "CanAssign"
-PROP_HAS_FUNC_CALL = "HasFuncCall"
-
class Value(object):
- """
- Value represents result of expression evaluation.
+ """Value represents result of expression evaluation.
+
Note that same expression can be evaluated multiple times with different
results.
+
+ :param value: Expression value.
+ :param props: Property dictionary defining the value.
"""
def __init__(self, value, props):
@@ -152,93 +334,97 @@ class Value(object):
return "[Expression Value %s %s]" % (self._value, self._props)
def getTypeClass(self):
+ """Get value type class.
+
+ :returns: type class
+
+ .. seealso: :class:`~tcf.services.symbols.TypeClass`
"""
- Get value type class.
- @see symbols.TypeClass
- @return type class
- """
- return self._props.get(VAL_CLASS, 0)
+ return self._props.get(VAL_CLASS, symbols.TypeClass.unknown)
def getTypeID(self):
- """
- Get value type ID. Symbols service can be used to get type properties.
- @return type ID.
+ """Get value type ID. Symbols service can be used to get type
+ properties.
+
+ :returns: Type ID.
"""
return self._props.get(VAL_TYPE)
def isBigEndian(self):
- """
- Check endianness of the values.
+ """Check endianness of the values.
+
Big-endian means decreasing numeric significance with increasing
byte number.
- @return true if big-endian.
+
+ :returns: **True** if big-endian.
"""
- return self._props.get(VAL_BIG_ENDIAN)
+ return self._props.get(VAL_BIG_ENDIAN, False)
def getAddress(self):
- """
- Get the value address if one exists.
- @return The value address or None if none address exists for the value
+ """Get the value address if one exists.
+
+ :returns: The value address or **None** if none address exists for the
+ value.
"""
return self._props.get(VAL_ADDRESS)
def getRegisterID(self):
- """
- Return register ID if the value represents register variable.
- @return register ID or None.
+ """Return register ID if the value represents register variable.
+
+ :returns: Register ID or **None**.
"""
return self._props.get(VAL_REGISTER)
def getSymbolID(self):
- """
- Return symbol ID if the value represents a symbol.
- @return symbol ID or None.
+ """Return symbol ID if the value represents a symbol.
+
+ :returns: Symbol ID or **None** if value is not a symbol.
"""
return self._props.get(VAL_SYMBOL)
def getValue(self):
- """
- Get value as array of bytes.
- @return value as array of bytes.
+ """Get a 'packed binary data' encoded value.
+
+ :returns: value as 'packed binary data'.
+
+ .. seealso:: :mod:`struct`
"""
return self._value
def getProperties(self):
- """
- Get complete map of value properties.
- @return map of value properties.
+ """Get complete dictionary of value properties.
+
+ :returns: A |dict| of value properties.
"""
return self._props
-# Expression value property names.
-VAL_CLASS = "Class"
-VAL_TYPE = "Type"
-VAL_SYMBOL = "Symbol"
-VAL_REGISTER = "Register"
-VAL_ADDRESS = "Address"
-VAL_BIG_ENDIAN = "BigEndian"
-
class ExpressionsService(services.Service):
-
def getName(self):
+ """Get this service name.
+
+ :returns: The value of string :const:`NAME`
+ """
return NAME
def getContext(self, contextID, done):
- """
- Retrieve expression context info for given context ID.
- @see Expression
+ """Retrieve expression context info for given context ID.
+
+ :param contextID: Context ID.
+ :param done: Call back interface called when operation is completed.
+ :type done: :class:`DoneGetContext`
- @param contextID - context ID.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :returns: pending command handle.
+
+ .. seealso:: :class:`Expression`
"""
raise NotImplementedError("Abstract method")
def getChildren(self, parent_context_id, done):
- """
- Retrieve children IDs for given parent ID.
+ """Retrieve children IDs for given parent ID.
+
Meaning of the operation depends on parent kind:
+
1. expression with type of a struct, union, or class - fields
2. expression with type of an enumeration - enumerators
3. expression with type of an array - array elements
@@ -249,170 +435,182 @@ class ExpressionsService(services.Service):
Children list *does not* include IDs of expressions that were created
by clients using "create" command.
- @param parent_context_id - parent context ID.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param parent_context_id: parent context ID.
+ :param done: call back interface called when operation is completed.
+ :type done: :class:`DoneGetChildren`
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract method")
def create(self, parent_id, language, expression, done):
- """
- Create an expression context.
+ """Create an expression context.
+
The context should be disposed after use.
- @param parent_id - a context ID that can be used to resolve symbol
- names.
- @param language - language of expression script, None means default
- language
- @param expression - expression script
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+
+ :param parent_id: A context ID that can be used to resolve symbol
+ names.
+ :param language: Language of expression script, **None** means default
+ language.
+ :param expression: Expression script
+ :param done: Call back interface called when operation is completed.
+ :type done: :class:`DoneCreate`
+
+ :returns: pending command handle.
"""
raise NotImplementedError("Abstract method")
def dispose(self, contextID, done):
- """
- Dispose an expression context that was created by create()
- @param contextID - the expression context ID
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ """Dispose an expression context that was created by
+ :meth:`~ExpressionsService.create`
+
+ :param contextID: The expression context ID.
+ :param done: Call back interface called when operation is completed.
+ :type done: :class:`DoneDispose`
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract method")
def evaluate(self, contextID, done):
- """
- Evaluate value of an expression context.
- @param contextID - the expression context ID
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ """Evaluate value of an expression context.
+
+ :param contextID: The expression context ID
+ :param done: Call back interface called when operation is completed.
+ :type done: :class:`DoneEvaluate`
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract method")
def assign(self, contextID, value, done):
- """
- Assign a value to memory location determined by an expression.
- @param contextID - expression ID.
- @param value - value as an array of bytes.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ """Assign a value to memory location determined by an expression.
+
+ :param contextID: Expression ID.
+ :param value: Value as an array of bytes.
+ :param done: Call back interface called when operation is completed.
+ :type done: :class:`DoneAssign`
+
+ :returns: pending command handle.
"""
raise NotImplementedError("Abstract method")
def addListener(self, listener):
- """
- Add expressions service event listener.
- @param listener - event listener implementation.
+ """Add expressions service event listener.
+
+ :param listener: Event listener implementation.
+ :type listener: :class:`ExpressionsListener`
"""
raise NotImplementedError("Abstract method")
def removeListener(self, listener):
- """
- Remove expressions service event listener.
- @param listener - event listener implementation.
+ """Remove expressions service event listener.
+
+ :param listener: Event listener implementation.
+ :type listener: :class:`ExpressionsListener`
"""
raise NotImplementedError("Abstract method")
class DoneGetContext(object):
- """
- Client call back interface for getContext().
+ """Client call back interface for :meth:`~ExpressionsService.getContext`.
"""
def doneGetContext(self, token, error, context):
- """
- Called when context data retrieval is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param context - context properties.
+ """Called when context data retrieval is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context: Context properties.
"""
pass
class DoneGetChildren(object):
- """
- Client call back interface for getChildren().
+ """Client call back interface for :meth:`~ExpressionsService.getChildren`.
"""
def doneGetChildren(self, token, error, context_ids):
- """
- Called when context list retrieval is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param context_ids - array of available context IDs.
+ """Called when context list retrieval is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context_ids: An iterable of available context IDs.
"""
pass
class DoneCreate(object):
- """
- Client call back interface for create().
+ """Client call back interface for :meth:`~ExpressionsService.create`.
"""
def doneCreate(self, token, error, context):
- """
- Called when context create context command is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param context - context properties.
+ """Called when context create context command is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context: Context properties.
"""
pass
class DoneDispose(object):
- """
- Client call back interface for dispose().
- """
+ """Client call back interface for :meth:`~ExpressionsService.dispose`."""
+
def doneDispose(self, token, error):
- """
- Called when context dispose command is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
+ """Called when context dispose command is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class DoneEvaluate(object):
- """
- Client call back interface for evaluate().
- """
+ """Client call back interface for :meth:`~ExpressionsService.evaluate`."""
+
def doneEvaluate(self, token, error, value):
- """
- Called when context dispose command is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param value - expression evaluation result
+ """Called when context dispose command is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, None if
+ succeeded.
+ :param value: Expression evaluation result. See :class:`Value`.
"""
pass
class DoneAssign(object):
- """
- Client call back interface for assign().
- """
+ """Client call back interface for :meth:`~ExpressionsService.assign`."""
+
def doneAssign(self, token, error):
- """
- Called when assign command is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
+ """Called when assign command is done.
+
+ :param token: Command handle
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class ExpressionsListener(object):
- """
- Registers event listener is notified when registers context hierarchy
+ """Registers event listener is notified when registers context hierarchy
changes, and when a register is modified by the service commands.
"""
+
def valueChanged(self, contextID):
- """
- Called when expression value was changed and clients
- need to update themselves. Clients, at least, should invalidate
- corresponding cached expression 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 "assign" command should be notified.
- @param contextID - expression context ID.
+ """Called when expression value was changed and clients need to update
+ themselves.
+
+ Clients, at least, should invalidate corresponding cached expression
+ data.
+
+ .. note:: 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 :meth:`~ExpressionsService.assign`
+ command should be notified.
+
+ :param contextID: Expression context ID.
"""
pass
diff --git a/python/src/tcf/services/filesystem.py b/python/src/tcf/services/filesystem.py
index b32855536..4b717fff9 100644
--- a/python/src/tcf/services/filesystem.py
+++ b/python/src/tcf/services/filesystem.py
@@ -9,101 +9,443 @@
# * Wind River Systems - initial API and implementation
# ****************************************************************************
-"""
-File System service provides file transfer (and more generally file
-system access) functionality in TCF. The service design is
-derived from SSH File Transfer Protocol specifications.
-
- Request Synchronization and Reordering
-
-The protocol and implementations MUST process requests relating to
-the same file in the order in which they are received. In other
-words, if an application submits multiple requests to the server, the
-results in the responses will be the same as if it had sent the
-requests one at a time and waited for the response in each case. For
-example, the server may process non-overlapping read/write requests
-to the same file in parallel, but overlapping reads and writes cannot
-be reordered or parallelized. However, there are no ordering
-restrictions on the server for processing requests from two different
-file transfer connections. The server may interleave and parallelize
-them at will.
-
-There are no restrictions on the order in which responses to
-outstanding requests are delivered to the client, except that the
-server must ensure fairness in the sense that processing of no
-request will be indefinitely delayed even if the client is sending
-other requests so that there are multiple outstanding requests all
-the time.
-
-There is no limit on the number of outstanding (non-acknowledged)
-requests that the client may send to the server. In practice this is
-limited by the buffering available on the data stream and the queuing
-performed by the server. If the server's queues are full, it should
-not read any more data from the stream, and flow control will prevent
-the client from sending more requests.
-
- File Names
-
-This protocol represents file names as strings. File names are
-assumed to use the slash ('/') character as a directory separator.
-
-File names starting with a slash are "absolute", and are relative to
-the root of the file system. Names starting with any other character
-are relative to the user's default directory (home directory). Client
-can use 'user()' command to retrieve current user home directory.
-
-Servers SHOULD interpret a path name component ".." as referring to
-the parent directory, and "." as referring to the current directory.
-If the server implementation limits access to certain parts of the
-file system, it must be extra careful in parsing file names when
-enforcing such restrictions. There have been numerous reported
-security bugs where a ".." in a path name has allowed access outside
-the intended area.
-
-An empty path name is valid, and it refers to the user's default
-directory (usually the user's home directory).
+"""File System service provides file transfer (and more generally file
+system access) functionality in TCF.
+
+.. |close| replace:: :meth:`~FileSystemService.close`
+.. |copy| replace:: :meth:`~FileSystemService.copy`
+.. |doneRead| replace:: :meth:`~DoneRead.doneRead`
+.. |fstat| replace:: :meth:`~FileSystemService.fstat`
+.. |fsetstat| replace:: :meth:`~FileSystemService.fsetstat`
+.. |lstat| replace:: :meth:`~FileSystemService.lstat`
+.. |mkdir| replace:: :meth:`~FileSystemService.mkdir`
+.. |open| replace:: :meth:`~FileSystemService.open`
+.. |opendir| replace:: :meth:`~FileSystemService.opendir`
+.. |read| replace:: :meth:`~FileSystemService.read`
+.. |readdir| replace:: :meth:`~FileSystemService.readdir`
+.. |readlink| replace:: :meth:`~FileSystemService.readlink`
+.. |realpath| replace:: :meth:`~FileSystemService.realpath`
+.. |remove| replace:: :meth:`~FileSystemService.remove`
+.. |rename| replace:: :meth:`~FileSystemService.rename`
+.. |rmdir| replace:: :meth:`~FileSystemService.rmdir`
+.. |roots| replace:: :meth:`~FileSystemService.roots`
+.. |setstat| replace:: :meth:`~FileSystemService.setstat`
+.. |stat| replace:: :meth:`~FileSystemService.stat`
+.. |symlink| replace:: :meth:`~FileSystemService.symlink`
+.. |user| replace:: :meth:`~FileSystemService.user`
+.. |write| replace:: :meth:`~FileSystemService.write`
+.. |DoneClose| replace:: :class:`DoneClose`
+.. |DoneCopy| replace:: :class:`DoneCopy`
+.. |DoneMkDir| replace:: :class:`DoneMkDir`
+.. |DoneOpen| replace:: :class:`DoneOpen`
+.. |DoneRead| replace:: :class:`DoneRead`
+.. |DoneReadDir| replace:: :class:`DoneReadDir`
+.. |DoneReadLink| replace:: :class:`DoneReadLink`
+.. |DoneRealPath| replace:: :class:`DoneRealPath`
+.. |DoneRemove| replace:: :class:`DoneRemove`
+.. |DoneRename| replace:: :class:`DoneRename`
+.. |DoneRoots| replace:: :class:`DoneRoots`
+.. |DoneSetStat| replace:: :class:`DoneSetStat`
+.. |DoneStat| replace:: :class:`DoneStat`
+.. |DoneSymLink| replace:: :class:`DoneSymLink`
+.. |DoneUser| replace:: :class:`DoneUser`
+.. |DoneWrite| replace:: :class:`DoneWrite`
+.. |FileAttrs| replace:: :class:`FileAttrs`
+.. |FileHandle| replace:: :class:`FileHandle`
+
+The service design is derived from SSH File Transfer Protocol specifications.
+
+Request Synchronization and Reordering
+--------------------------------------
+The protocol and implementations **must** process requests relating to the same
+file in the order in which they are received. In other words, if an
+application submits multiple requests to the server, the results in the
+responses will be the same as if it had sent the requests one at a time and
+waited for the response in each case. For example, the server may process
+non-overlapping read/write requests to the same file in parallel, but
+overlapping reads and writes cannot be reordered or parallelized. However,
+there are no ordering restrictions on the server for processing requests from
+two different file transfer connections. The server may interleave and
+parallelize them at will.
+
+There are no restrictions on the order in which responses to outstanding
+requests are delivered to the client, except that the server must ensure
+fairness in the sense that processing of no request will be indefinitely
+delayed even if the client is sending other requests so that there are multiple
+outstanding requests all the time.
+
+There is no limit on the number of outstanding (non-acknowledged) requests that
+the client may send to the server. In practice this is limited by the
+buffering available on the data stream and the queuing performed by the server.
+If the server's queues are full, it should not read any more data from the
+stream, and flow control will prevent the client from sending more requests.
+
+File Names
+----------
+This protocol represents file names as strings. File names are assumed to use
+the slash (``/``) character as a directory separator.
+
+File names starting with a slash are **absolute**, and are relative to the root
+of the file system. Names starting with any other character are relative to
+the user's default directory (home directory). Client can use
+:meth:`~FileSystemService.user` command to retrieve current user home
+directory.
+
+Servers **should** interpret a path name component ``..`` as referring to the
+parent directory, and ``.`` as referring to the current directory. If the
+server implementation limits access to certain parts of the file system, it
+must be extra careful in parsing file names when enforcing such restrictions.
+There have been numerous reported security bugs where a ``..`` in a path name
+has allowed access outside the intended area.
+
+An empty path name is valid, and it refers to the user's default directory
+(usually the user's home directory).
Otherwise, no syntax is defined for file names by this specification.
-Clients should not make any other assumptions however, they can
-splice path name components returned by readdir() together
-using a slash ('/') as the separator, and that will work as expected.
+
+Clients should not make any other assumptions however, they can splice path
+name components returned by :meth:`~FileSystemService.readdir` together using a
+slash (``/``) as the separator, and that will work as expected.
+
+FileSystem Properties
+---------------------
+Attributes
+^^^^^^^^^^
+Flags to be used together with |FileAttrs|.
+The flags specify which of the fields are present. Those fields for which the
+corresponding flag is not set are not present (not included in the message).
+Aff flags are of type |int|.
+
++------------------+----------------------------------------------------------+
+| Name | Description |
++==================+==========================================================+
+| ATTR_ACMODTIME | The access and modification times of the file are |
+| | present in the |FileAttrs| object. |
++------------------+----------------------------------------------------------+
+| ATTR_PERMISSIONS | The file permissons are present in the |FileAttrs| |
+| | objects. |
++------------------+----------------------------------------------------------+
+| ATTR_SIZE | File size is present in the |FileAttrs| object. |
++------------------+----------------------------------------------------------+
+| ATTR_UIDGID | User ID and Group ID are present in the |FileAttrs| |
+| | object. |
++------------------+----------------------------------------------------------+
+
+Status
+^^^^^^
+Status error codes are of type |int|.
+
++--------------------------+--------------------------------------------------+
+| Name | Description |
++==========================+==================================================+
+| STATUS_EOF | Indicates end-of-file condition for |read|. It |
+| | means that no more data is available in the file,|
+| | and for |readdir| it indicates that no more files|
+| | are contained in the directory. |
++--------------------------+--------------------------------------------------+
+| STATUS_NO_SUCH_FILE | This code is returned when a reference is made to|
+| | a file which should exist but doesn't. |
++--------------------------+--------------------------------------------------+
+| STATUS_PERMISSION_DENIED | This code is returned when the authenticated user|
+| | does not have sufficient permissions to perform |
+| | the operation. |
++--------------------------+--------------------------------------------------+
+
+Permissions
+^^^^^^^^^^^
+File permission is an ored value of the following |int| values:
+
++----------+-------------------------------------------------+
+| Name | Description |
++==========+=================================================+
+| S_IFBLK | Block device. |
++----------+-------------------------------------------------+
+| S_IFCHR | Character device. |
++----------+-------------------------------------------------+
+| S_IFDIR | Directory. |
++----------+-------------------------------------------------+
+| S_IFIFO | Fifo. |
++----------+-------------------------------------------------+
+| S_IFLNK | Symbolic link. |
++----------+-------------------------------------------------+
+| S_IFMT | Bitmask for the file type bitfields. |
++----------+-------------------------------------------------+
+| S_IFREG | Regular file. |
++----------+-------------------------------------------------+
+| S_IFSOCK | Socket. |
++----------+-------------------------------------------------+
+| S_IRGRP | Group has read permission. |
++----------+-------------------------------------------------+
+| S_IROTH | Others have read permission. |
++----------+-------------------------------------------------+
+| S_IRUSR | Owner has read permission. |
++----------+-------------------------------------------------+
+| S_IRWXG | Mask for group permissions. |
++----------+-------------------------------------------------+
+| S_IRWXO | Mask for permissions for others (not in group). |
++----------+-------------------------------------------------+
+| S_IRWXU | Mask for file owner permissions. |
++----------+-------------------------------------------------+
+| S_ISGID | Set GID bit. |
++----------+-------------------------------------------------+
+| S_ISUID | Set UID bit. |
++----------+-------------------------------------------------+
+| S_ISVTX | Sticky bit. |
++----------+-------------------------------------------------+
+| S_IWGRP | Group has write permission. |
++----------+-------------------------------------------------+
+| S_IWOTH | Others have write permission. |
++----------+-------------------------------------------------+
+| S_IWUSR | Owner has write permission. |
++----------+-------------------------------------------------+
+| S_IXGRP | Group has execute permission. |
++----------+-------------------------------------------------+
+| S_IXOTH | Others have execute permission. |
++----------+-------------------------------------------------+
+| S_IXUSR | Owner has execute permission. |
++----------+-------------------------------------------------+
+
+Open Flags
+^^^^^^^^^^
+Flags to be used with the |open| method. All flags are of type |int|.
+
++--------------+--------------------------------------------------------------+
+| Name | Description |
++==============+==============================================================+
+| TCF_O_APPEND | Force all writes to append data at the end of the file. |
+| TCF_O_CREAT | If this flag is specified, then a new file will be created |
+| | if one does not already exist (if **TCF_O_TRUNC** is |
+| | specified, the new file will be truncated to zero length if |
+| | it previously exists). |
++--------------+--------------------------------------------------------------+
+| TCF_O_EXCL | Causes the request to fail if the named file already exists. |
+| | **TCF_O_CREAT** **must** also be specified if this flag is |
+| | used. |
++--------------+--------------------------------------------------------------+
+| TCF_O_READ | Open the file for reading. |
++--------------+--------------------------------------------------------------+
+| TCF_O_TRUNC | Forces an existing file with the same name to be truncated |
+| | to zero length when creating a file by specifying |
+| | **TCF_O_CREAT**. **TCF_O_CREAT** **must** also be specified |
+| | if this flag is used. |
++--------------+--------------------------------------------------------------+
+| TCF_O_WRITE | Open the file for writing. If both this and **TCF_O_READ** |
+| | are specified, the file is opened for both reading and |
+| | writing. |
++--------------+--------------------------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: FileSystemService
+
+close
+^^^^^
+.. automethod:: FileSystemService.close
+
+copy
+^^^^
+.. automethod:: FileSystemService.copy
+
+fsetstat
+^^^^^^^^
+.. automethod:: FileSystemService.fsetstat
+
+fstat
+^^^^^
+.. automethod:: FileSystemService.fstat
+
+getName
+^^^^^^^
+.. automethod:: FileSystemService.getName
+
+lstat
+^^^^^
+.. automethod:: FileSystemService.lstat
+
+mkdir
+^^^^^
+.. automethod:: FileSystemService.mkdir
+
+open
+^^^^
+.. automethod:: FileSystemService.open
+
+opendir
+^^^^^^^
+.. automethod:: FileSystemService.opendir
+
+read
+^^^^
+.. automethod:: FileSystemService.read
+
+readdir
+^^^^^^^
+.. automethod:: FileSystemService.readdir
+
+readlink
+^^^^^^^^
+.. automethod:: FileSystemService.readlink
+
+realpath
+^^^^^^^^
+.. automethod:: FileSystemService.realpath
+
+remove
+^^^^^^
+.. automethod:: FileSystemService.remove
+
+rename
+^^^^^^
+.. automethod:: FileSystemService.rename
+
+rmdir
+^^^^^
+.. automethod:: FileSystemService.rmdir
+
+roots
+^^^^^
+.. automethod:: FileSystemService.roots
+
+setstat
+^^^^^^^
+.. automethod:: FileSystemService.setstat
+
+stat
+^^^^
+.. automethod:: FileSystemService.stat
+
+symlink
+^^^^^^^
+.. automethod:: FileSystemService.symlink
+
+user
+^^^^
+.. automethod:: FileSystemService.user
+
+write
+^^^^^
+.. automethod:: FileSystemService.write
+
+Callback Classes
+----------------
+DoneClose
+^^^^^^^^^
+.. autoclass:: DoneClose
+ :members:
+
+DoneCopy
+^^^^^^^^
+.. autoclass:: DoneCopy
+ :members:
+
+DoneMkDir
+^^^^^^^^^
+.. autoclass:: DoneMkDir
+ :members:
+
+DoneOpen
+^^^^^^^^
+.. autoclass:: DoneOpen
+ :members:
+
+DoneRead
+^^^^^^^^
+.. autoclass:: DoneRead
+ :members:
+
+DoneReadDir
+^^^^^^^^^^^
+.. autoclass:: DoneReadDir
+ :members:
+
+DoneReadLink
+^^^^^^^^^^^^
+.. autoclass:: DoneReadLink
+ :members:
+
+DoneRealPath
+^^^^^^^^^^^^
+.. autoclass:: DoneRealPath
+ :members:
+
+DoneRemove
+^^^^^^^^^^
+.. autoclass:: DoneRemove
+ :members:
+
+DoneRename
+^^^^^^^^^^
+.. autoclass:: DoneRename
+ :members:
+
+DoneRoots
+^^^^^^^^^
+.. autoclass:: DoneRoots
+ :members:
+
+DoneSetStat
+^^^^^^^^^^^
+.. autoclass:: DoneSetStat
+ :members:
+
+DoneStat
+^^^^^^^^
+.. autoclass:: DoneStat
+ :members:
+
+DoneSymLink
+^^^^^^^^^^^
+.. autoclass:: DoneSymLink
+ :members:
+
+DoneUser
+^^^^^^^^
+.. autoclass:: DoneUser
+ :members:
+
+DoneWrite
+^^^^^^^^^
+.. autoclass:: DoneWrite
+ :members:
+
+Helper Classes
+--------------
+DirEntry
+^^^^^^^^
+.. autoclass:: DirEntry
+ :members:
+
+FileAttrs
+^^^^^^^^^
+.. autoclass:: FileAttrs
+ :members:
+
+FileHandle
+^^^^^^^^^^
+.. autoclass:: FileHandle
+ :members:
+
+FileSystemException
+^^^^^^^^^^^^^^^^^^^
+.. autoclass:: FileSystemException
+ :members:
"""
from .. import services
-# Service name.
NAME = "FileSystem"
+"""FileSystem service name."""
# Flags to be used with open() method.
-# Open the file for reading.
TCF_O_READ = 0x00000001
-
-# Open the file for writing. If both this and TCF_O_READ are
-# specified, the file is opened for both reading and writing.
TCF_O_WRITE = 0x00000002
-
-# Force all writes to append data at the end of the file.
TCF_O_APPEND = 0x00000004
-
-# If this flag is specified, then a new file will be created if one
-# does not already exist (if TCF_O_TRUNC is specified, the new file will
-# be truncated to zero length if it previously exists).
TCF_O_CREAT = 0x00000008
-
-# Forces an existing file with the same name to be truncated to zero
-# length when creating a file by specifying TCF_O_CREAT.
-# TCF_O_CREAT MUST also be specified if this flag is used.
TCF_O_TRUNC = 0x00000010
-
-# Causes the request to fail if the named file already exists.
-# TCF_O_CREAT MUST also be specified if this flag is used.
TCF_O_EXCL = 0x00000020
-# Flags to be used together with FileAttrs.
-# The flags specify which of the fields are present. Those fields
-# for which the corresponding flag is not set are not present (not
-# included in the message).
ATTR_SIZE = 0x00000001
ATTR_UIDGID = 0x00000002
ATTR_PERMISSIONS = 0x00000004
@@ -111,27 +453,45 @@ ATTR_ACMODTIME = 0x00000008
class FileAttrs(object):
- """
- FileAttrs is used both when returning file attributes from
- the server and when sending file attributes to the server. When
- sending it to the server, the flags field specifies which attributes
- are included, and the server will use default values for the
- remaining attributes (or will not modify the values of remaining
- attributes). When receiving attributes from the server, the flags
- specify which attributes are included in the returned data. The
- server normally returns all attributes it knows about.
-
- Fields:
- The 'flags' specify which of the fields are present.
- The 'size' field specifies the size of the file in bytes.
- The 'uid' and 'gid' fields contain numeric Unix-like user and group
- identifiers, respectively.
- The 'permissions' field contains a bit mask of file permissions as
- defined by posix [1].
- The 'atime' and 'mtime' contain the access and modification times of
- the files, respectively. They are represented as milliseconds from
- midnight Jan 1, 1970 in UTC.
- attributes - Additional (non-standard) attributes.
+ """FileAttrs is used both when returning file attributes from the server
+ and when sending file attributes to the server.
+
+ When sending it to the server, the flags field specifies which attributes
+ are included, and the server will use default values for the remaining
+ attributes (or will not modify the values of remaining attributes). When
+ receiving attributes from the server, the flags specify which attributes
+ are included in the returned data. The server normally returns all
+ attributes it knows about.
+
+ :param flags: Specifies which of the fields are present. See `Attributes`_.
+ :type flags: |int|
+ :param size: Specifies the size of the file in bytes.
+ :type size: |int|
+ :param uid: Contains numeric Unix-like user identifiers.
+ :type uid: |int|
+ :param gid: Contains numeric Unix-like group identifiers.
+ :type gid: |int|
+ :param permissions: Contains a bit mask of file permissions as defined by
+ posix.
+ :type permissions: |int|
+ :param atime: Contains the access time of the file. It is represented as
+ milliseconds from midnight Jan 1, 1970 in UTC.
+ :type atime: |int|
+ :param mtime: Contains the modification time of the file. It is represented
+ as milliseconds from midnight Jan 1, 1970 in UTC
+ :type mtime: |int|
+ :param attributes: Contains additional (non-standard) attributes.
+ :type attributes: |dict|
+
+ **Fields**
+ - **flags** : Specifies which fields are present (see `Attributes`_).
+ - **size** : File size in bytes.
+ - **uid** : User ID (|int|)
+ - **gid** : Group ID (|int|)
+ - **permissions** : File permissions (see `Permissions`_).
+ - **atime** : Last access time.
+ - **mtime** : Last modification time.
+ - **attributes** : A |dict| of non-standard attributes.
"""
def __init__(self, flags, size, uid, gid, permissions, atime, mtime,
attributes):
@@ -144,73 +504,185 @@ class FileAttrs(object):
self.mtime = mtime
self.attributes = attributes
+ def __repr__(self):
+ """Representation for these file attributes."""
+ res = self.__class__.__name__ + '('
+ res += 'flags=' + str(self.flags)
+ res += ', size=' + str(self.size)
+ res += ', uid=' + str(self.uid)
+ res += ', gid=' + str(self.gid)
+ res += ', permissions=' + str(self.permissions)
+ res += ', atime=' + str(self.atime)
+ res += ', mtime=' + str(self.mtime)
+ res += ', attributes=' + str(self.attributes)
+ res += ')'
+ return res
+
+ def __str__(self):
+ """String representation for these file attributes."""
+ res = self.__class__.__name__ + ' ['
+ flags = []
+
+ if self.flags & ATTR_SIZE:
+ flags.append('ATTR_SIZE')
+ if self.flags & ATTR_UIDGID:
+ flags.append('ATTR_UIDGID')
+ if self.flags & ATTR_PERMISSIONS:
+ flags.append('ATTR_PERMISSIONS')
+ if self.flags & ATTR_ACMODTIME:
+ flags.append('ATTR_ACMODTIME')
+
+ res += 'flags=' + '|'.join(flags)
+
+ if self.flags & ATTR_SIZE:
+ res += ', size=' + str(self.size)
+
+ if self.flags & ATTR_UIDGID:
+ res += ', uid=' + str(self.uid)
+ res += ', gid=' + str(self.gid)
+
+ # Compute the permissions string
+
+ if self.flags & ATTR_PERMISSIONS:
+ perms = []
+ if self.permissions & S_IFMT:
+ perms.append('S_IFMT')
+ if self.permissions & S_IFSOCK:
+ perms.append('S_IFSOCK')
+ if self.permissions & S_IFLNK:
+ perms.append('S_IFLNK')
+ if self.permissions & S_IFREG:
+ perms.append('S_IFREG')
+ if self.permissions & S_IFBLK:
+ perms.append('S_IFBLK')
+ if self.permissions & S_IFDIR:
+ perms.append('S_IFDIR')
+ if self.permissions & S_IFCHR:
+ perms.append('S_IFCHR')
+ if self.permissions & S_IFIFO:
+ perms.append('S_IFIFO')
+ if self.permissions & S_ISUID:
+ perms.append('S_ISUID')
+ if self.permissions & S_ISGID:
+ perms.append('S_ISGID')
+ if self.permissions & S_ISVTX:
+ perms.append('S_ISVTX')
+ if self.permissions & S_IRWXU:
+ perms.append('S_IRWXU')
+ if self.permissions & S_IRUSR:
+ perms.append('S_IRUSR')
+ if self.permissions & S_IWUSR:
+ perms.append('S_IWUSR')
+ if self.permissions & S_IXUSR:
+ perms.append('S_IXUSR')
+ if self.permissions & S_IRWXG:
+ perms.append('S_IRWXG')
+ if self.permissions & S_IRGRP:
+ perms.append('S_IRGRP')
+ if self.permissions & S_IWGRP:
+ perms.append('S_IWGRP')
+ if self.permissions & S_IXGRP:
+ perms.append('S_IXGRP')
+ if self.permissions & S_IRWXO:
+ perms.append('S_IRWXO')
+ if self.permissions & S_IROTH:
+ perms.append('S_IROTH')
+ if self.permissions & S_IWOTH:
+ perms.append('S_IWOTH')
+ if self.permissions & S_IXOTH:
+ perms.append('S_IXOTH')
+
+ res += ', permissions=' + '|'.join(perms)
+
+ if self.flags & ATTR_ACMODTIME:
+ res += ', atime=' + str(self.atime)
+ res += ', mtime=' + str(self.mtime)
+
+ res += ', attributes=' + str(self.attributes)
+ res += ']'
+ return res
+
def isFile(self):
- """
- Determines if the file system object is a file on the remote file
+ """Determines if the file system object is a file on the remote file
system.
- @return True if and only if the object on the remote system can be
- considered to have "contents" that have the potential to be
- read and written as a byte stream.
+ :returns: **True** if and only if the object on the remote system can
+ be considered to have *contents* that have the potential to
+ be read and written as a byte stream.
"""
if (self.flags & ATTR_PERMISSIONS) == 0:
return False
return (self.permissions & S_IFMT) == S_IFREG
def isDirectory(self):
- """
- Determines if the file system object is a directory on the remote file
- system.
+ """Determines if the file system object is a directory on the remote
+ file system.
- @return True if and only if the object on the remote system is a
- directory. That is, it contains entries that can be interpreted
- as other files.
+ :returns: True if and only if the object on the remote system is a
+ directory. That is, it contains entries that can be
+ interpreted as other files.
"""
if (self.flags & ATTR_PERMISSIONS) == 0:
return False
return (self.permissions & S_IFMT) == S_IFDIR
+ def __eq__(self, other):
+ if not isinstance(other, FileAttrs):
+ return False
+ return (self.flags == other.flags and self.size == other.size and \
+ self.uid == other.uid and self.gid == other.gid and \
+ self.permissions == other.permissions and \
+ self.mtime == other.mtime and \
+ self.attributes == other.attributes)
+
+ def __ne__(self, other):
+ return (not self.__eq__(other))
+
+
# The following flags are defined for the 'permissions' field:
-S_IFMT = 0170000 # bitmask for the file type bitfields
-S_IFSOCK = 0140000 # socket
-S_IFLNK = 0120000 # symbolic link
-S_IFREG = 0100000 # regular file
-S_IFBLK = 0060000 # block device
-S_IFDIR = 0040000 # directory
-S_IFCHR = 0020000 # character device
-S_IFIFO = 0010000 # fifo
-S_ISUID = 0004000 # set UID bit
-S_ISGID = 0002000 # set GID bit (see below)
-S_ISVTX = 0001000 # sticky bit (see below)
-S_IRWXU = 00700 # mask for file owner permissions
-S_IRUSR = 00400 # owner has read permission
-S_IWUSR = 00200 # owner has write permission
-S_IXUSR = 00100 # owner has execute permission
-S_IRWXG = 00070 # mask for group permissions
-S_IRGRP = 00040 # group has read permission
-S_IWGRP = 00020 # group has write permission
-S_IXGRP = 00010 # group has execute permission
-S_IRWXO = 00007 # mask for permissions for others (not in group)
-S_IROTH = 00004 # others have read permission
-S_IWOTH = 00002 # others have write permission
-S_IXOTH = 00001 # others have execute permission
+S_IFMT = 0170000
+S_IFSOCK = 0140000
+S_IFLNK = 0120000
+S_IFREG = 0100000
+S_IFBLK = 0060000
+S_IFDIR = 0040000
+S_IFCHR = 0020000
+S_IFIFO = 0010000
+S_ISUID = 0004000
+S_ISGID = 0002000
+S_ISVTX = 0001000
+S_IRWXU = 00700
+S_IRUSR = 00400
+S_IWUSR = 00200
+S_IXUSR = 00100
+S_IRWXG = 00070
+S_IRGRP = 00040
+S_IWGRP = 00020
+S_IXGRP = 00010
+S_IRWXO = 00007
+S_IROTH = 00004
+S_IWOTH = 00002
+S_IXOTH = 00001
class DirEntry(object):
- """
- Directory entry.
- Fields:
- 'filename' is a file name being returned. It is a relative name within
- the directory, without any path components
- 'longname' is an expanded format for the file name, similar to what
- is returned by "ls -l" on Unix systems.
- The format of the 'longname' field is unspecified by this protocol.
- It MUST be suitable for use in the output of a directory listing
- command (in fact, the recommended operation for a directory listing
- command is to simply display this data). However, clients SHOULD NOT
- attempt to parse the longname field for file attributes they SHOULD
- use the attrs field instead.
- 'attrs' is the attributes of the file.
+ """Directory entry.
+
+ :param filename: Is a file name being returned. It is a relative name
+ within the directory, without any path components.
+ :type filename: |basestring|
+ :param longname: Is an expanded format for the file name, similar to what
+ is returned by ``ls -l`` on Unix systems. The format of
+ the *longname* parameter is unspecified by this protocol.
+ It **must** be suitable for use in the output of a
+ directory listing command (in fact, the recommended
+ operation for a directory listing command is to simply
+ display this data). However, clients **should not**
+ attempt to parse the longname field for file attributes
+ they **should** use the *attrs* field instead.
+ :type longname: |basestring|
+ :param attrs: Directory entry attributes.
+ :type attrs: |FileAttrs|
"""
def __init__(self, filename, longname, attrs):
self.filename = filename
@@ -219,37 +691,47 @@ class DirEntry(object):
class FileHandle(object):
+ """TCF filesystem file handle.
+
+ :param service: The TCF file system this service is associated to.
+ :param fileID: The file ID of this file handle.
+ :type fileID: |basestring|
+ """
def __init__(self, service, fileID):
self.service = service
self.id = fileID
+ def getID(self):
+ """Get the ID of this handle.
+
+ :returns: The ID of this file handle
+ """
+ return (self.id)
+
def getService(self):
+ """Get the TCF filesystem service for this handle.
+
+ :returns: The TCF filesystem service this file hanlde is associated to
+ """
return self.service
def __str__(self):
- return "[File Handle '%s'" % self.id
+ return "[File Handle '%s']" % self.id
# Service specific error codes.
-# Indicates end-of-file condition for read() it means that no
-# more data is available in the file, and for readdir() it
-# indicates that no more files are contained in the directory.
STATUS_EOF = 0x10001
-
-# This code is returned when a reference is made to a file which
-# should exist but doesn't.
STATUS_NO_SUCH_FILE = 0x10002
-
-# is returned when the authenticated user does not have sufficient
-# permissions to perform the operation.
STATUS_PERMISSION_DENIED = 0x10003
class FileSystemException(IOError):
- """
- The class to represent File System error reports.
- """
+ """The class to represent File System error reports.
+ :param message_or_exception: A string describing the file system error, or
+ an :exc:`~exceptions.Exception` to
+ initialise this exception with
+ """
def __init__(self, message_or_exception):
if isinstance(message_or_exception, (str, unicode)):
super(FileSystemException, self).__init__(message_or_exception)
@@ -257,387 +739,627 @@ class FileSystemException(IOError):
self.caused_by = message_or_exception
def getStatus(self):
- """
- Get error code. The code can be standard TCF error code or
- one of service specific codes, see STATUS_*.
- @return error code.
+ """Get error code.
+
+ The code can be standard TCF error code or one of service specific
+ codes, see `Status`_.
+
+ :returns: This Exception error code.
"""
raise NotImplementedError("Abstract methods")
class FileSystemService(services.Service):
+ """TCF filesystem service interface"""
def getName(self):
- return NAME
+ """Get this service name.
- def open(self, file_name, flags, attrs, done): # @ReservedAssignment
+ :returns: This service name, which is the value of :const:`NAME`
"""
- Open or create a file on a remote system.
+ return NAME
- @param file_name - specifies the file name. See 'File Names' for more
- information.
- @param flags - is a bit mask of TCF_O_* flags.
- @param attrs - specifies the initial attributes for the file. Default
- values will be used for those attributes that are not
- specified.
- @param done - is call back object.
- @return pending command handle.
+ def open(self, file_name, flags, attrs, done): # @ReservedAssignment
+ """Open or create a file on a remote system.
+
+ :param file_name: Specifies the file name. See **File Names** for more
+ information.
+ :type file_name: |basestring|
+ :param flags: Is a bit mask of `Open Flags`_.
+ :type flags: |int|
+ :param attrs: Specifies the initial attributes for the file. Default
+ values will be used for those attributes that are not
+ specified.
+ :type attrs: |FileAttrs|
+ :param done: Is call back object.
+ :type done: |DoneOpen|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def close(self, handle, done):
- """
- Close a file on a remote system.
+ """Close a file on a remote system.
- @param handle is a handle previously returned in the response to
- open() or opendir().
- @param done is call back object.
- @return pending command handle.
+ :param handle: Is a handle previously returned in the response to
+ |open| or |opendir|.
+ :type handle: |FileHandle|
+ :param done: is call back object.
+ :type done: |DoneClose|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def read(self, handle, offset, length, done):
- """
- Read bytes from an open file.
+ """Read bytes from an open file.
+
In response to this request, the server will read as many bytes as it
- can from the file (up to 'length'), and return them in a byte array.
- If an error occurs or EOF is encountered, the server may return
- fewer bytes then requested. Call back method doneRead() argument
- 'error' will be not None in case of error, and argument 'eof' will be
- True in case of EOF. For normal disk files, it is guaranteed
- that this will read the specified number of bytes, or up to end of file
- or error. For e.g. device files this may return fewer bytes than
- requested.
-
- @param handle - is an open file handle returned by open().
- @param offset - is the offset (in bytes) relative to the beginning of
- the file from where to start reading. If offset < 0
- then reading starts from current position in the file.
- @param length - is the maximum number of bytes to read.
- @param done - is call back object.
- @return pending command handle.
+ can from the file (up to *length*), and return them in a byte array.
+
+ If an error occurs or **EOF** is encountered, the server may return
+ fewer bytes than requested. Call back method |doneRead| argument
+ *error* will not be **None** in case of error, and argument *eof* will
+ be **True** in case of **EOF**.
+
+ For normal disk files, it is guaranteed that this will read the
+ specified number of bytes, or up to end of file or error. For e.g.
+ device files this may return fewer bytes than requested.
+
+ :param handle: Is an open file handle returned by |open|.
+ :type handle: |FileHandle|
+ :param offset: Is the offset (in bytes) relative to the beginning of
+ the file from where to start reading. If offset
+ negative, then reading starts from current position in
+ the file.
+ :type offset: |int|
+ :param length: Is the maximum number of bytes to read.
+ :type length: |int|
+ :param done: Is call back object.
+ :type done: |DoneRead|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def write(self, handle, offset, data, data_pos, data_size, done):
- """
- Write bytes into an open file.
+ """Write bytes into an open file.
+
The write will extend the file if writing beyond the end of the file.
+
It is legal to write way beyond the end of the file the semantics
are to write zeroes from the end of the file to the specified offset
and then the data.
- @param handle is an open file handle returned by open().
- @param offset is the offset (in bytes) relative
- to the beginning of the file from where to start writing.
- If offset < 0 then writing starts from current position in the file.
- @param data is byte array that contains data for writing.
- @param data_pos if offset in 'data' of first byte to write.
- @param data_size is the number of bytes to write.
- @param done is call back object.
- @return pending command handle.
+ :param handle: Is an open file handle returned by |open|.
+ :type handle: |FileHandle|
+ :param offset: The offset (in bytes) relative to the beginning of the
+ file from where to start writing. If offset is negative
+ then writing starts from current position in the file.
+ :type offset: |int|
+ :param data: Byte array that contains data for writing.
+ :type data: |bytearray|
+ :param data_pos: Offset in *data* of first byte to write.
+ :type data_pos: |int|
+ :param data_size: Number of bytes to write.
+ :type data_size: |int|
+ :param done: Call back object.
+ :type done: |DoneWrite|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def stat(self, path, done):
- """
- Retrieve file attributes.
+ """Retrieve file attributes.
+
+ :param path: Specifies the file system object for which status is to be
+ returned.
+ :type path: |basestring|
+ :param done: Call back object.
+ :type done: |DoneStat|
- @param path - specifies the file system object for which
- status is to be returned.
- @param done is call back object.
- @return pending command handle.
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def lstat(self, path, done):
- """
- Retrieve file attributes.
- Unlike 'stat()', 'lstat()' does not follow symbolic links.
+ """Retrieve file attributes.
+
+ Unlike |stat|, |lstat| does not follow symbolic links.
+
+ :param path: Specifies the file system object for which status is to be
+ returned.
+ :type path: |basestring|
+ :param done: Call back object
+ :type done: |DoneStat|
- @param path - specifies the file system object for which
- status is to be returned.
- @param done is call back object.
- @return pending command handle.
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def fstat(self, handle, done):
- """
- Retrieve file attributes for an open file (identified by the file
+ """Retrieve file attributes for an open file (identified by the file
handle).
- @param handle is a file handle returned by 'open()'.
- @param done is call back object.
- @return pending command handle.
+ :param handle: A file handle returned by |open|.
+ :type handle: |FileHandle|
+ :param done: Call back object.
+ :type done: |DoneStat|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def setstat(self, path, attrs, done):
- """
- Set file attributes.
+ """Set file attributes.
+
This request is used for operations such as changing the ownership,
permissions or access times, as well as for truncating a file.
+
An error will be returned if the specified file system object does
not exist or the user does not have sufficient rights to modify the
specified attributes.
- @param path specifies the file system object (e.g. file or directory)
- whose attributes are to be modified.
- @param attrs specifies the modifications to be made to file attributes.
- @param done is call back object.
- @return pending command handle.
+ :param path: Specifies the file system object (e.g. file or directory)
+ whose attributes are to be modified.
+ :type path: |basestring|
+ :param attrs: Modifications to be made to file attributes.
+ :type attrs: |FileAttrs|
+ :param done: Call back object.
+ :type done: |DoneSetStat|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def fsetstat(self, handle, attrs, done):
- """
- Set file attributes for an open file (identified by the file handle).
+ """Set file attributes for an open file (identified by the file
+ handle).
+
This request is used for operations such as changing the ownership,
permissions or access times, as well as for truncating a file.
- @param handle is a file handle returned by 'open()'.
- @param attrs specifies the modifications to be made to file attributes.
- @param done is call back object.
- @return pending command handle.
+ :param handle: is a file handle returned by |open|.
+ :type handle: |FileHandle|
+ :param attrs: Modifications to be made to file attributes.
+ :type attrs: |FileAttrs|
+ :param done: Call back object.
+ :type done: |DoneSetStat|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def opendir(self, path, done):
- """
- The opendir() command opens a directory for reading.
+ """This command opens a directory for reading.
+
Once the directory has been successfully opened, files (and
- directories) contained in it can be listed using readdir() requests.
- When the client no longer wishes to read more names from the
- directory, it SHOULD call close() for the handle. The handle
- should be closed regardless of whether an error has occurred or not.
+ directories) contained in it can be listed using |readdir| requests.
+
+ When the client no longer wishes to read more names from the directory,
+ it **should** call |close| for the handle. The handle should be closed
+ regardless of whether an error has occurred or not.
- @param path - name of the directory to be listed (without any trailing
- slash).
- @param done - result call back object.
- @return pending command handle.
+ :param path: Name of the directory to be listed (without any trailing
+ slash).
+ :type path: |basestring|
+ :param done: Call back object.
+ :type done: |DoneOpen|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def readdir(self, handle, done):
- """
- The files in a directory can be listed using the opendir() and
- readdir() requests. Each readdir() request returns one
- or more file names with full file attributes for each file. The
- client should call readdir() repeatedly until it has found the
- file it is looking for or until the server responds with a
- message indicating an error or end of file. The client should then
- close the handle using the close() request.
- Note: directory entries "." and ".." are NOT included into readdir()
- response.
- @param handle - file handle created by opendir()
- @param done - result call back object.
- @return pending command handle.
+ """The files in a directory can be listed using the |opendir| and
+ |readdir| requests.
+
+ Each |readdir| request returns one or more file names with full file
+ attributes for each file. The client should call |readdir| repeatedly
+ until it has found the file it is looking for or until the server
+ responds with a message indicating an error or end of file. The client
+ should then close the handle using the |close| request.
+
+ .. note:: directory entries ``.`` and ``..`` are **not** included into
+ |readdir| response.
+
+ :param handle: File handle created by |opendir|.
+ :type handle: |FileHandle|
+ :param done: Call back object.
+ :type done: |DoneReadDir|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def mkdir(self, path, attrs, done):
- """
- Create a directory on the server.
+ """Create a directory on the server.
+
+ :param path: Specifies the directory to be created.
+ :type path: |basestring|
+ :param attrs: New directory attributes.
+ :type attrs: |FileAttrs|
+ :param done: Call back object.
+ :type done: |DoneMkDir|
- @param path - specifies the directory to be created.
- @param attrs - new directory attributes.
- @param done - result call back object.
- @return pending command handle.
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def rmdir(self, path, done):
- """
- Remove a directory.
- An error will be returned if no directory
- with the specified path exists, or if the specified directory is not
- empty, or if the path specified a file system object other than a
- directory.
+ """Remove a directory.
+
+ An error will be returned if no directory with the specified path
+ exists, or if the specified directory is not empty, or if the path
+ specified a file system object other than a directory.
+
+ :param path: Specifies the directory to be removed.
+ :type path: |basestring|
+ :param done: Call back object
+ :type done: |DoneRemove|
- @param path - specifies the directory to be removed.
- @param done - result call back object.
- @return pending command handle.
+ :returns: pending command handle
"""
raise NotImplementedError("Abstract methods")
def roots(self, done):
- """
- Retrieve file system roots - top level file system objects.
- UNIX file system can report just one root with path "/". Other types of
- systems can have more the one root. For example, Windows server can
- return multiple roots:
- one per disc (e.g. "/C:/", "/D:/", etc.). Note: even Windows
- implementation of the service must use forward slash as directory
- separator, and must start absolute path with "/". Server should
- implement proper translation of protocol file names to OS native names
- and back.
+ """Retrieve file system roots - top level file system objects.
+
+ UNIX file system can report just one root with path ``/``. Other types
+ of systems can have more the one root. For example, Windows server can
+ return multiple roots: one per disc (e.g. ``/C:/``, ``/D:/``, etc.).
- @param done - result call back object.
- @return pending command handle.
+ .. note:: even Windows implementation of the service must use forward
+ slash as directory separator, and must start absolute path
+ with ``/``. Server should implement proper translation of
+ protocol file names to OS native names and back.
+
+ :param done: Call back object
+ :type done: |DoneRoots|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def remove(self, file_name, done):
- """
- Remove a file or symbolic link.
+ """Remove a file or symbolic link.
+
This request cannot be used to remove directories.
- @param file_name is the name of the file to be removed.
- @param done - result call back object.
- @return pending command handle.
+ :param file_name: The name of the file to be removed.
+ :type file_name: |basestring|
+ :param done: Call back object.
+ :type done: |DoneRemove|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def realpath(self, path, done):
- """
- Canonicalize any given path name to an absolute path.
- This is useful for converting path names containing ".." components or
- relative pathnames without a leading slash into absolute paths.
+ """Canonicalize any given path name to an absolute path.
+
+ This is useful for converting path names containing ``..`` components
+ or relative pathnames without a leading slash into absolute paths.
- @param path specifies the path name to be canonicalized.
- @param done - result call back object.
- @return pending command handle.
+ :param path: The path name to be canonicalized.
+ :type path: |basestring|
+ :param done: Call back object.
+ :type done: |DoneRealPath|
+
+ :returns: pending command handle.
"""
raise NotImplementedError("Abstract methods")
def rename(self, old_path, new_path, done):
- """
- Rename a file.
- It is an error if there already exists a file
- with the name specified by 'new_path'. The server may also fail rename
- requests in other situations, for example if 'old_path' and 'new_path'
- point to different file systems on the server.
+ """Rename a file.
- @param old_path is the name of an existing file or directory.
- @param new_path is the new name for the file or directory.
- @param done - result call back object.
- @return pending command handle.
+ It is an error if there already exists a file with the name specified
+ by *new_path*. The server may also fail rename requests in other
+ situations, for example if *old_path* and *new_path* point to different
+ file systems on the server.
+
+ :param old_path: The name of an existing file or directory.
+ :type old_path: |basestring|
+ :param new_path: The new name for the file or directory.
+ :type new_path: |basestring|
+ :param done: Call back object.
+ :type done: |DoneRename|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def readlink(self, path, done):
- """
- Read the target of a symbolic link.
+ """Read the target of a symbolic link.
+
+ :param path: The path name of the symbolic link to be read.
+ :type path: |basestring|
+ :param done: Call back object.
+ :type done: |DoneReadLink|
- @param path specifies the path name of the symbolic link to be read.
- @param done - result call back object.
- @return pending command handle.
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def symlink(self, link_path, target_path, done):
- """
- Create a symbolic link on the server.
+ """Create a symbolic link on the server.
+
+ :param link_path: The path name of the symbolic link to be created.
+ :type link_path: |basestring|
+ :param target_path: The target of the symbolic link.
+ :type target_path: |basestring|
+ :param done: Call back object.
+ :type done: |DoneSymLink|
- @param link_path - specifies the path name of the symbolic link to be
- created.
- @param target_path - specifies the target of the symbolic link.
- @param done - result call back object.
- @return pending command handle.
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def copy(self, src_path, dst_path, copy_permissions, copy_ownership, done):
- """
- Copy a file on remote system.
-
- @param src_path - specifies the path name of the file to be copied.
- @param dst_path - specifies destination file name.
- @param copy_permissions - if True then copy source file permissions.
- @param copy_ownership - if True then copy source file UID and GID.
- @param done - result call back object.
- @return pending command handle.
+ """Copy a file on remote system.
+
+ :param src_path: The path name of the file to be copied.
+ :type src_path: |basestring|
+ :param dst_path: Destination file name.
+ :type dst_path: |basestring|
+ :param copy_permissions: If **True** then copy source file permissions.
+ :type copy_permissions: |bool|
+ :param copy_ownership: If **True** then copy source file UID and GID.
+ :type copy_ownership: |bool|
+ :param done: Call back object.
+ :type done: |DoneCopy|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
def user(self, done):
- """
- Retrieve information about user account, which is used by server
+ """Retrieve information about user account, which is used by server
to access file system on behalf of the client.
- @param done - result call back object.
- @return pending command handle.
+ :param done: Call back object
+ :type done: |DoneUser|
+
+ :returns: Pending command handle.
"""
raise NotImplementedError("Abstract methods")
class DoneOpen(object):
+ """Client call back interface for |open|."""
+
def doneOpen(self, token, error, handle):
+ """Called when file open is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param handle: Handle of the opened file.
+ :type handle: |FileHandle|
+ """
pass
class DoneClose(object):
+ """Client call back interface for |close|."""
+
def doneClose(self, token, error):
+ """Called when file close is done.
+
+ :param token: Pending command handle
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneRead(object):
+ """Client call back interface for |read|."""
+
def doneRead(self, token, error, data, eof):
+ """Called when file read is done.
+
+ :param token: {ending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param data: data read from file.
+ :type data: |bytearray|
+ :param eof: **True** if end of file is reached by this read action.
+ :type eof: |bool|
+ """
pass
class DoneWrite(object):
+ """Client call back interface for |write|."""
+
def doneWrite(self, token, error):
+ """Called when file write is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneStat(object):
+ """Client call back interface for |stat|, |fstat| or |lstat| methods."""
+
def doneStat(self, token, error, attrs):
+ """Called when file stat is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param attrs: Retrieved file attributes.
+ :type attrs: |FileAttrs|
+ """
pass
class DoneSetStat(object):
+ """Client call back interface for |setstat| or |fsetstat|.
+ """
+
def doneSetStat(self, token, error):
+ """Called when file stat is set.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneReadDir(object):
+ """Client call back interface for |readdir|."""
+
def doneReadDir(self, token, error, entries, eof):
+ """Called when directory read is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param entries: Entries in directory.
+ :type entries: |list|
+ :param eof: **True** if there are no more entries in that directory.
+ :type eof: |bool|
+ """
pass
class DoneMkDir(object):
+ """Client call back interface for |mkdir|."""
+
def doneMkDir(self, token, error):
+ """Called when mkdir command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneRemove(object):
+ """Client call back interface for |remove| or |rmdir|.
+ """
+
def doneRemove(self, token, error):
+ """Called when rmdir or remove command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneRoots(object):
+ """Client call back interface for |roots|."""
+
def doneRoots(self, token, error, entries):
+ """Called when filesystem roots are retrieved.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param entries: A list of roots of the filesystem.
+ :type entries: |list|
+ """
pass
class DoneRealPath(object):
+ """Client call back interface for |realpath|."""
+
def doneRealPath(self, token, error, path):
+ """Called when realpath command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param path: Real path of the input file path.
+ :type path: |basestring|
+ """
pass
class DoneRename(object):
+ """Client call back interface for |rename|."""
+
def doneRename(self, token, error):
+ """Called when rename command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneReadLink(object):
+ """Client call back interface for |readlink|."""
+
def doneReadLink(self, token, error, path):
+ """Called when readlink command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param path: Target path of the input link path.
+ :type path: |basestring|
+ """
pass
class DoneSymLink(object):
+ """Client call back interface for |symlink|."""
+
def doneSymLink(self, token, error):
+ """Called when symlink command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneCopy(object):
+ """Client call back interface for |copy|."""
+
def doneCopy(self, token, error):
+ """Called when copy command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneUser(object):
+ """Client call back interface for |user|."""
+
def doneUser(self, token, error, real_uid, effective_uid, real_gid,
effective_gid, home):
+ """Called when user command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param real_uid: real user ID.
+ :type real_uid: |int|
+ :param effective_uid: effective user ID.
+ :type effective_uid: |int|
+ :param real_gid: user's real group ID.
+ :type real_gid: |int|
+ :param effective_gid: user's effective group ID
+ :type effective_gid: |int|
+ :param home: user's home path.
+ :type home: |basestring|
+ """
pass
diff --git a/python/src/tcf/services/linenumbers.py b/python/src/tcf/services/linenumbers.py
index 9f0011fca..f23612dff 100644
--- a/python/src/tcf/services/linenumbers.py
+++ b/python/src/tcf/services/linenumbers.py
@@ -9,31 +9,71 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-Line numbers service associates locations in the source files with the
+"""Line numbers service associates locations in the source files with the
corresponding machine instruction addresses in the executable object.
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: LineNumbersService
+
+getName
+^^^^^^^
+.. automethod:: LineNumbersService.getName
+
+mapToMemory
+^^^^^^^^^^^
+.. automethod:: LineNumbersService.mapToMemory
+
+mapToSource
+^^^^^^^^^^^
+.. automethod:: LineNumbersService.mapToSource
+
+Callback Classes
+----------------
+DoneMapToMemory
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneMapToMemory
+ :members:
+
+DoneMapToSource
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneMapToSource
+ :members:
+
+Helper Classes
+--------------
+CodeArea
+^^^^^^^^
+.. autoclass:: CodeArea
+ :members:
"""
from .. import services
NAME = "LineNumbers"
+"""LineNumbers service name."""
class CodeArea(object):
- """
- A CodeArea represents a continues area in source text mapped to
+ """A CodeArea represents a continues area in source text mapped to
continues range of code addresses.
+
Line and columns are counted starting from 1.
- File name can be a relative path, in this case the client should
- use the CodeArea directory name as origin for the path.
+
+ File name can be a relative path, in this case the client should use the
+ CodeArea directory name as origin for the path.
+
File and directory names are valid on a host where code was compiled.
+
It is client responsibility to map names to local host file system.
"""
- def __init__(self, directory, fileName, start_line, start_column,
- end_line, end_column, start_address, end_address, isa,
- is_statement, basic_block, prologue_end, epilogue_begin):
+ def __init__(self, directory, file, start_line, # @ReservedAssignment
+ start_column, end_line, end_column, start_address,
+ end_address, isa, is_statement, basic_block, prologue_end,
+ epilogue_begin):
self.directory = directory
- self.file = fileName
+ self.file = file
self.start_line = start_line
self.start_column = start_column
self.end_line = end_line
@@ -133,22 +173,73 @@ class CodeArea(object):
class LineNumbersService(services.Service):
+ """TCF LineNumbers service interface."""
def getName(self):
+ """Get this service name.
+
+ :returns: The value of string :const:`NAME`
+ """
return NAME
def mapToSource(self, context_id, start_address, end_address, done):
+ """Get the line numbers source for a context ID and a memory address.
+
+ :param context_id: ID of the context to get source map for.
+ :type context_id: |basestring|
+ :param start_address: Memory start address to get source map for.
+ :type start_address: |int|
+ :param end_address: Memory end address to get source map for.
+ :type end_address: |int|
+ :param done: Call back interface called when operation is completed
+ :type done: :class:`DoneMapToSource`
+ """
raise NotImplementedError("Abstract method")
def mapToMemory(self, context_id, fileName, line, column, done):
+ """Get the the memory address of a context ID for a given file and line
+ number.
+
+ :param context_id: ID of the context to get source map for.
+ :type context_id: |basestring|
+ :param fileName: Name of the file to map memory for.
+ :type fileName: |basestring|
+ :param line: Source file line to map to a memory address.
+ :type line: |int|
+ :param column: Source file column to map to a memory address.
+ :type column: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: :class:`DoneMapToMemory`
+ """
raise NotImplementedError("Abstract method")
class DoneMapToSource(object):
+ """
+ Client callback interface for :meth:`~LineNumbersService.mapToSource`.
+ """
+
def doneMapToSource(self, token, error, areas):
+ """Called when context data retrieval is done.
+
+ :param token: pending command handle
+ :param error: error description if operation failed, **None** if
+ succeeded.
+ :param areas: A |list| of :class:`CodeArea` objects.
+ """
pass
class DoneMapToMemory(object):
+ """
+ Client callback interface for :meth:`~LineNumbersService.mapToMemory`.
+ """
def doneMapToMemory(self, token, error, areas):
+ """Called when context data retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param areas: A |list| of :class:`CodeArea` objects.
+ """
pass
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
diff --git a/python/src/tcf/services/pathmap.py b/python/src/tcf/services/pathmap.py
index 19d4349e4..b18cfbd76 100644
--- a/python/src/tcf/services/pathmap.py
+++ b/python/src/tcf/services/pathmap.py
@@ -9,46 +9,129 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-PathMap service manages file path translation across systems.
+"""PathMap service manages file path translation across systems.
+
+.. |get| replace:: :meth:`~PathMapService.get`
+.. |set| replace:: :meth:`~PathMapService.set`
+.. |DoneGet| replace:: :class:`DoneGet`
+.. |DoneSet| replace:: :class:`DoneSet`
+.. |PathMapRule| replace:: :class:`PathMapRule`
+.. |PathMapListener| replace:: :class:`PathMapListener`
+
+
+Path Mapping Properties
+-----------------------
+Properties
+^^^^^^^^^^
+All properties are of type |basestring|.
+
++--------------------+--------------------------------------------------------+
+| Name | Description |
++====================+========================================================+
+| PROP_CONTEXT | Symbols context group ID or name. **deprecated** - use |
+| | ``PROP_CONTEXT_QUERY``. |
++--------------------+--------------------------------------------------------+
+| PROP_CONTEXT_QUERY | Contexts query. |
++--------------------+--------------------------------------------------------+
+| PROP_DESTINATION | Destination, or run-time file path. |
++--------------------+--------------------------------------------------------+
+| PROP_HOST | Host name. |
++--------------------+--------------------------------------------------------+
+| PROP_ID | Rule ID. |
++--------------------+--------------------------------------------------------+
+| PROP_PROTOCOL | File access protocol, see `Protocols`_, default is |
+| | ``PROTOCOL_FILE``. |
++--------------------+--------------------------------------------------------+
+| PROP_SOURCE | Source, or compile-time file path. |
++--------------------+--------------------------------------------------------+
+
+Protocols
+^^^^^^^^^
+All protocols are of type |basestring|.
+
++-----------------+-----------------------------------------------------------+
+| Name | Description |
++=================+===========================================================+
+| PROTOCOL_FILE | Regular file access using system calls. |
++-----------------+-----------------------------------------------------------+
+| PROTOCOL_HOST | File should be accessed using File System service on host.|
++-----------------+-----------------------------------------------------------+
+| PROTOCOL_TARGET | File should be accessed using File System service on. |
+| | target. |
++-----------------+-----------------------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: PathMapService
+
+addListener
+^^^^^^^^^^^
+.. automethod:: PathMapService.addListener
+
+get
+^^^
+.. automethod:: PathMapService.get
+
+getName
+^^^^^^^
+.. automethod:: PathMapService.getName
+
+removeListener
+^^^^^^^^^^^^^^
+.. automethod:: PathMapService.removeListener
+
+set
+^^^
+.. automethod:: PathMapService.set
+
+Callback Classes
+----------------
+DoneGet
+^^^^^^^
+.. autoclass:: DoneGet
+ :members:
+
+DoneSet
+^^^^^^^
+.. autoclass:: DoneSet
+ :members:
+
+Listener
+--------
+PathMapListener
+^^^^^^^^^^^^^^^
+.. autoclass:: PathMapListener
+ :members:
+
+Helper Classes
+--------------
+PathMapRule
+^^^^^^^^^^^
+.. autoclass:: PathMapRule
+ :members:
"""
from .. import services
NAME = "PathMap"
+"""PathMap service name."""
# Path mapping rule property names.
-# String, contexts query, see IContextQuery
PROP_CONTEXT_QUERY = "ContextQuery"
-
-# String, destination, or run-time file path
PROP_DESTINATION = "Destination"
-
-# String
PROP_HOST = "Host"
-
-# String, rule ID
PROP_ID = "ID"
-
-# String, file access protocol, see PROTOCOL_*, default is regular file
PROP_PROTOCOL = "Protocol"
-
-# String, source, or compile-time file path
PROP_SOURCE = "Source"
-# Deprecated
-# String, symbols context group ID or name, deprecated - use ContextQuery
+# @deprecated
PROP_CONTEXT = "Context"
# PROP_PROTOCOL values.
-# Regular file access using system calls
PROTOCOL_FILE = "file"
-
-# File should be accessed using File System service on host
PROTOCOL_HOST = "host"
-
-# File should be accessed using File System service on target
PROTOCOL_TARGET = "target"
@@ -61,123 +144,153 @@ class PathMapListener(object):
class PathMapRule(object):
- """
- PathMapRule represents a single file path mapping rule.
+ """PathMapRule represents a single file path mapping rule.
+
+ :param props: The properties to initialise this pathmap rule with. See
+ `Properties`_.
+ :type props: |dict|
"""
def __init__(self, props):
self._props = props or {}
- def __str__(self):
- return str(self._props)
+ def __repr__(self):
+ return self.__class__.__name__ + '(' + str(self._props) + ')'
def __json__(self):
return self._props
def getContextQuery(self):
- """Get context query that defines scope of the mapping rule, see
- also IContextQuery.
- Same as getProperties().get(PROP_CONTEXT_QUERY)
- @return context query expression, or None.
+ """Get context query that defines scope of the mapping rule.
+
+ :returns: This PathMap Rule context query expression, or **None**.
"""
return self._props.get(PROP_CONTEXT_QUERY, None)
def getProperties(self):
- """
- Get rule properties. See PROP_* definitions for property names.
+ """Get rule properties.
+
+ See `Properties`_ definitions for property names.
+
Context properties are read only, clients should not try to modify
them.
- @return Map of rule properties.
+
+ :returns: A |dict| class of this rule's properties.
"""
return self._props
def getID(self):
+ """Get rule unique ID.
+
+ :returns: A |basestring| representing this rule's ID or **None**.
"""
- Get rule unique ID.
- Same as getProperties().get(PROP_ID)
- @return rule ID.
- """
- return self._props.get(PROP_ID)
+ return self._props.get(PROP_ID, None)
def getSource(self):
+ """Get compile-time file path.
+
+ :returns: A |basestring| representing compile-time file path or
+ **None**.
"""
- Get compile-time file path.
- Same as getProperties().get(PROP_SOURCE)
- @return compile-time file path.
- """
- return self._props.get(PROP_SOURCE)
+ return self._props.get(PROP_SOURCE, None)
def getDestination(self):
+ """Get run-time file path.
+
+ :returns: A |basestring| representing run-time file path or **None**.
"""
- Get run-time file path.
- Same as getProperties().get(PROP_DESTINATION)
- @return run-time file path.
- """
- return self._props.get(PROP_DESTINATION)
+ return self._props.get(PROP_DESTINATION, None)
def getHost(self):
+ """Get host name of this rule.
+
+ :returns: A |basestring| representing the host name this rule applies
+ to or **None**.
"""
- Get host name of this rule.
- Same as getProperties().get(PROP_HOST)
- @return host name.
- """
- return self._props.get(PROP_HOST)
+ return self._props.get(PROP_HOST, None)
def getProtocol(self):
+ """Get file access protocol name.
+
+ See `Protocols`_ for path mapping protocol values.
+
+ :returns: A |basestring| representing protocol name or
+ ``PROTOCOL_FILE``.
"""
- Get file access protocol name.
- Same as getProperties().get(PROP_PROTOCOL)
- @return protocol name.
- """
- return self._props.get(PROP_PROTOCOL)
+ return self._props.get(PROP_PROTOCOL, PROTOCOL_FILE)
class PathMapService(services.Service):
+ """TCF PathMap service interface."""
+
+ def addListener(self, listener):
+ """Add a pathmap listener.
+
+ A |PathMapListener| is added to the TCF pathmap service.
+
+ :param listener: Instance of the pathmap listener to add to service.
+ :type listener: |PathMapListener|
+ """
+ return NotImplementedError("Abstract method")
+
def getName(self):
+ """Get this service name.
+
+ :returns: The value of string :const:`NAME`
+ """
return NAME
def get(self, done):
- """
- Retrieve file path mapping rules.
+ """Retrieve file path mapping rules.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGet|
"""
return NotImplementedError("Abstract method")
def set(self, pathMap, done): # @ReservedAssignment
+ """Set file path mapping rules.
+
+ :param pathMap: File path mapping rules.
+ :type pathMap: |PathMapRule|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneSet|
"""
- Set file path mapping rules.
+ return NotImplementedError("Abstract method")
+
+ def removeListener(self, listener):
+ """Remove pathmap event listener.
+
+ The PathMapListener is removed from the TCF pathmap service.
- @param pathMap - file path mapping rules.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param listener: instance of the pathmap listener to remove from
+ service.
+ :type listener: |PathMapListener|
"""
return NotImplementedError("Abstract method")
class DoneGet(object):
- """
- Client call back interface for get().
- """
+ """Client call back interface for |get|."""
def doneGet(self, token, error, pathMap):
- """
- Called when file path mapping retrieval is done.
- @param error - error description if operation failed, None if
- succeeded.
- @param pathMap - file path mapping data.
+ """Called when file path mapping retrieval is done.
+
+ :param token: Command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param pathMap: File path mapping data.
+ :type pathMap: |list| of |PathMapRule|
"""
pass
class DoneSet(object):
- """
- Client call back interface for set().
- """
+ """Client call back interface for |set|."""
+
def doneSet(self, token, error):
- """
- Called when file path mapping transmission is done.
- @param error - error description if operation failed, None if
- succeeded.
- @param map - memory map data.
+ """Called when file path mapping transmission is done.
+
+ :param token: Command handle
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
diff --git a/python/src/tcf/services/processes.py b/python/src/tcf/services/processes.py
index 6ccf86095..c4c6d6881 100644
--- a/python/src/tcf/services/processes.py
+++ b/python/src/tcf/services/processes.py
@@ -9,188 +9,401 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-IProcesses service provides access to the target OS's process
-information, allows to start and terminate a process, and allows
-to attach and detach a process for debugging. Debug services,
-like IMemory and IRunControl, require a process to be attached
-before they can access it.
+"""TCF Processes service interface.
+
+.. |attach| replace:: :meth:`~ProcessContext.attach`
+.. |detach| replace:: :meth:`~ProcessContext.detach`
+.. |getChildren| replace:: :meth:`~ProcessesService.getChildren`
+.. |getContext| replace:: :meth:`~ProcessesService.getContext`
+.. |getEnvironment| replace:: :meth:`~ProcessesService.getEnvironment`
+.. |getSignalList| replace:: :meth:`~ProcessesService.getSignalList`
+.. |getSignalMask| replace:: :meth:`~ProcessesService.getSignalMask`
+.. |setSignalMask| replace:: :meth:`~ProcessesService.setSignalMask`
+.. |signal| replace:: :meth:`~ProcessesService.signal`
+.. |start| replace:: :meth:`~ProcessesService.start`
+.. |terminate| replace:: :meth:`~ProcessContext.terminate`
+.. |Breakpoint| replace:: :class:`~tcf.services.breakpoints.BreakpointsService`
+.. |DoneCommand| replace:: :class:`DoneCommand`
+.. |DoneGetContext| replace:: :class:`DoneGetContext`
+.. |DoneGetChildren| replace:: :class:`DoneGetChildren`
+.. |DoneGetSignalList| replace:: :class:`DoneGetSignalList`
+.. |DoneGetSignalMask| replace:: :class:`DoneGetSignalMask`
+.. |DoneStart| replace:: :class:`DoneStart`
+.. |Memory| replace:: :class:`~tcf.services.memory.MemoryService`
+.. |ProcessContext| replace:: :class:`ProcessContext`
+.. |ProcessesListener| replace:: :class:`ProcessesListener`
+.. |RunControl| replace:: :class:`~tcf.services.runcontrol.RunControlService`
+
+
+Processes service provides access to the target OS's process information,
+allows to start and terminate a process, and allows to attach and detach a
+process for debugging.
+
+Debug services, like |Memory| and |RunControl|, require a process to be
+attached before they can access it.
If a process is started by this service, its standard input/output streams are
available for client to read/write using Streams service. Stream type of such
-streams is set to "Processes".
+streams is set to ``Processes``.
+
+Properties
+----------
+Process Context Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. seealso:: |ProcessContext|
+
++--------------------+--------------+-----------------------------------------+
+| Name | Type | Description |
++====================+==============+=========================================+
+| PROP_ATTACHED | |bool| | Is the context attached ? |
++--------------------+--------------+-----------------------------------------+
+| PROP_CAN_TERMINATE | |bool| | Can terminate the context ? |
++--------------------+--------------+-----------------------------------------+
+| PROP_ID | |basestring| | The TCF context ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_NAME | |basestring| | Process name. Client UI can show this |
+| | | name to a user. |
++--------------------+--------------+-----------------------------------------+
+| PROP_PARENT_ID | |basestring| | The TCF parent context ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_STDERR_ID | |basestring| | Process standard error stream ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_STDIN_ID | |basestring| | Process standard input stream ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_STDOUT_ID | |basestring| | Process standard output stream ID. |
++--------------------+--------------+-----------------------------------------+
+
+Signals Properties
+^^^^^^^^^^^^^^^^^^
+
+.. seealso:: |getSignalList|
+
++-----------------+--------------+--------------------------------------------+
+| Name | Type | Description |
++=================+==============+============================================+
+| SIG_CODE | |int| | Signal code, as defined by OS. |
++-----------------+--------------+--------------------------------------------+
+| SIG_DESCRIPTION | |basestring| | Human readable description of the signal. |
++-----------------+--------------+--------------------------------------------+
+| SIG_INDEX | |int| | Bit position in the signal mask. |
++-----------------+--------------+--------------------------------------------+
+| SIG_NAME | |basestring| | Signal name, for example ``SIGHUP``. |
++-----------------+--------------+--------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: ProcessesService
+
+addListener
+^^^^^^^^^^^
+.. automethod:: ProcessesService.addListener
+
+getChildren
+^^^^^^^^^^^
+.. automethod:: ProcessesService.getChildren
+
+getContext
+^^^^^^^^^^
+.. automethod:: ProcessesService.getContext
+
+getEnvironment
+^^^^^^^^^^^^^^
+.. automethod:: ProcessesService.getEnvironment
+
+getName
+^^^^^^^
+.. automethod:: ProcessesService.getName
+
+getSignalList
+^^^^^^^^^^^^^
+.. automethod:: ProcessesService.getSignalList
+
+getSignalMask
+^^^^^^^^^^^^^
+.. automethod:: ProcessesService.getSignalMask
+
+removeListener
+^^^^^^^^^^^^^^
+.. automethod:: ProcessesService.removeListener
+
+setSignalMask
+^^^^^^^^^^^^^
+.. automethod:: ProcessesService.setSignalMask
+
+signal
+^^^^^^
+.. automethod:: ProcessesService.signal
+
+start
+^^^^^
+.. automethod:: ProcessesService.start
+
+Callback Classes
+----------------
+DoneCommand
+^^^^^^^^^^^
+.. autoclass:: DoneCommand
+ :members:
+
+DoneGetChildren
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetChildren
+ :members:
+
+DoneGetContext
+^^^^^^^^^^^^^^
+.. autoclass:: DoneGetContext
+ :members:
+
+DoneGetEnvironment
+^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetEnvironment
+ :members:
+
+DoneGetSignalList
+^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetSignalList
+ :members:
+
+DoneGetSignalMask
+^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetSignalMask
+ :members:
+
+DoneStart
+^^^^^^^^^
+.. autoclass:: DoneStart
+ :members:
+
+Listener
+--------
+.. autoclass:: ProcessesListener
+ :members:
+ :show-inheritance:
+
+Helper Classes
+--------------
+ProcessContext
+^^^^^^^^^^^^^^
+.. autoclass:: ProcessContext
+ :members:
"""
from .. import services
NAME = "Processes"
+"""Processes service name."""
# Context property names.
-# The TCF context ID
PROP_ID = "ID"
-
-# The TCF parent context ID
PROP_PARENT_ID = "ParentID"
-
-# Is the context attached
PROP_ATTACHED = "Attached"
-
-# Can terminate the context
PROP_CAN_TERMINATE = "CanTerminate"
-
-# Process name. Client UI can show this name to a user
PROP_NAME = "Name"
-
-# Process standard input stream ID
PROP_STDIN_ID = "StdInID"
-
-# Process standard output stream ID
PROP_STDOUT_ID = "StdOutID"
-
-# Process standard error stream ID
PROP_STDERR_ID = "StdErrID"
-
# Signal property names used by "getSignalList" command.
-# Number, bit position in the signal mask
SIG_INDEX = "Index"
-
-# String, signal name, for example "SIGHUP"
SIG_NAME = "Name"
-
-# Number, signal code, as defined by OS
SIG_CODE = "Code"
-
-# String, human readable description of the signal
SIG_DESCRIPTION = "Description"
class ProcessesService(services.Service):
+ """TCF processes service interface."""
+
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.
+ """Retrieve context info for given context ID.
+
A context corresponds to an execution thread, process, address space,
etc.
Context IDs are valid across TCF services, so it is allowed to issue
- getContext() command with a context that was obtained, for example,
- from Memory service.
+ |getContext| command with a context that was obtained, for example,
+ from |Memory| service.
- However, 'Processes.getContext' is supposed to return only process
- specific data, If the ID is not a process ID, 'Processes.getContext'
- may not return any useful information
+ However, |getContext| is supposed to return only process specific data.
+ If the ID is not a process ID, |getContext| may not return any useful
+ information.
- @param contextID - context ID.
- @param done - call back interface called when operation is completed.
+ :param contextID: The TCF ID of the context to get properties for.
+ :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, attached_only, done):
- """
- Retrieve children of given context.
+ """Retrieve children of given context.
+
+ :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
+ |getContext| or |getChildren| commands.
+ :type parent_context_id: |basestring| or **None**
+ :param attached_only: If **True** return only attached process IDs.
+ :type attached_only: |bool|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGetChildren|
- @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 getContext or getChildren commands.
- @param attached_only - if True return only attached process IDs.
- @param done - call back interface called when operation is completed.
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getSignalList(self, context_id, done):
- """
- Get list of signals that can be send to the process.
- @param context_id - process context ID or None.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Get list of signals that can be send to the process.
+
+ :param context_id: Process context ID or ***None***.
+ :type context_id: |basestring| or **None**
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGetSignalList|
+
+ :returns: Pending command handle, can be used to cancel the command.
+
+ .. seealso:: `Signals Properties`_
"""
raise NotImplementedError("Abstract method")
def getSignalMask(self, context_id, done):
- """
- Get process or thread signal mask.
+ """Get process or thread signal mask.
+
Bits in the mask control how signals should be handled by debug agent.
When new context is created it inherits the mask from its parent.
+
If context is not attached the command will return an error.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+
+ :param context_id: TCF ID of the context ot get signal mask for.
+ :type context_id: |basestring|
+ :param done: Call back interface called when operation is completed
+ :type done: |DoneGetSignalMask|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def setSignalMask(self, context_id, dont_stop, dont_pass, done):
- """
- Set process or thread signal mask.
+ """Set process or thread signal mask.
+
Bits in the mask control how signals should be handled by debug agent.
If context is not attached the command will return an error.
- @param dont_stop - bit-set of signals that should not suspend execution
- of the context.
- By default, debugger suspends a context before it receives a signal.
- @param dont_pass - bit-set of signals that should not be delivered to
- the context.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+
+ :param dont_stop: Bit-set of signals that should not suspend execution
+ of the context. By default, debugger suspends a
+ context before it receives a signal.
+ :type dont_stop: |int|
+ :param dont_pass: Bit-set of signals that should not be delivered to
+ the context.
+ :type dont_pass: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def signal(self, context_id, signal, done):
- """
- Send a signal to a process or thread.
- @param context_id - context ID.
- @param signal - signal code.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Send a signal to a process or thread.
+
+ :param context_id: TCF ID of the context to send a signal to.
+ :type context_id: |basestring|
+ :param signal: Signal code.
+ :type signal: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getEnvironment(self, done):
- """
- Get default set of environment variables used to start a new process.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Get default set of environment variables used to start a new
+ process.
+
+ :param done: call back interface called when operation is completed.
+ :type done: :class:`DoneGetEnvironment`
+
+ :returns: pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def start(self, directory, fileName, command_line, environment, attach,
done):
- """
- Start a new process on remote machine.
- @param directory - initial value of working directory for the process.
- @param fileName - process image file.
- @param command_line - command line arguments for the process.
- Note: the service does NOT add image file name as
- first argument for the process. If a client wants
- first parameter to be the file name, it should
- add it itself.
- @param environment - map of environment variables for the process,
- if None then default set of environment variables
- will be used.
- @param attach - if True debugger should be attached to the process.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Start a new process on remote machine.
+
+ :param directory: Initial value of working directory for the process.
+ :type directory: |basestring|
+ :param fileName: Process image file.
+ :type fileName: |basestring|
+ :param command_line: Command line arguments for the process.
+ :note: the service does NOT add image file name as
+ first argument for the process. If a client wants
+ first parameter to be the file name, it should add
+ it itself.
+ :type command_line: |basestring|
+ :param environment: Map of environment variables for the process, if
+ **None** then default set of environment variables
+ will be used.
+ :type environment: |dict| or **None**
+ :param attach: If **True** debugger should be attached to the process.
+ :type attach: |bool|
+ :param done: Call back interface called when operation is completed
+ :type done: |DoneStart|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def addListener(self, listener):
- """
- Add processes service event listener.
- @param listener - event listener implementation.
+ """Add processes service event listener.
+
+ :param listener: Processes event listener implementation to add to
+ service.
+ :type listener: |ProcessesListener|
"""
raise NotImplementedError("Abstract method")
def removeListener(self, listener):
- """
- Remove processes service event listener.
- @param listener - event listener implementation.
+ """Remove processes service event listener.
+
+ :param listener: Processes event listener implementation to remove from
+ service.
+ :type listener: |ProcessesListener|
"""
raise NotImplementedError("Abstract method")
class ProcessContext(object):
+ """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 props: A |dict| of properties to initialise this Process context
+ with. See `Process Context Properties`_
+ :type props: |dict|
+ """
def __init__(self, props):
self._props = props or {}
@@ -198,169 +411,216 @@ class ProcessContext(object):
return "[Processes Context %s]" % self._props
def getProperties(self):
- """
- Get context properties. See PROP_* definitions for property names.
+ """Get context properties.
+
+ See `Process Context 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 Process context ID.
"""
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 Process parent context ID.
"""
return self._props.get(PROP_PARENT_ID)
def getName(self):
- """
- Retrieve human readable context name.
- Same as getProperties().get('Name')
+ """Retrieve human readable context name.
+
+ :returns: A |basestring| representing this Process context name or
+ **None**.
"""
return self._props.get(PROP_NAME)
def isAttached(self):
- """
- Utility method to read context property PROP_ATTACHED.
- Services like RunControl, Memory, Breakpoints work only with
+ """Check if context is attached.
+
+ Services like |RunControl|, |Memory|, |Breakpoint| work only with
attached processes.
- @return value of PROP_ATTACHED.
+
+ :returns: A |bool| stating if this process context is attached or not.
"""
return bool(self._props.get(PROP_ATTACHED))
def canTerminate(self):
- """
- Utility method to read context property PROP_CAN_TERMINATE.
- @return value of PROP_CAN_TERMINATE.
+ """Check if this process can be terminated.
+
+ :returns: A |bool| stating if this process context is terminated or
+ not.
"""
return self._props.get(PROP_CAN_TERMINATE)
def attach(self, done):
- """
- Attach debugger to a process.
- Services like RunControl, Memory, Breakpoints work only with attached
- processes.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Attach debugger to a process.
+
+ Services like |RunControl|, |Memory|, |Breakpoint| work only with
+ attached processes.
+
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def detach(self, done):
- """
- Detach debugger from a process.
+ """Detach debugger from a process.
+
Process execution will continue without debugger supervision.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def terminate(self, done):
- """
- Terminate a process.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Terminate a process.
+
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
class DoneCommand(object):
- """
- Call-back interface to be called when command is complete.
+ """Client callback interface for simple commands like |attach|, |detach|,
+ |terminate|, |setSignalMask| and |signal|.
"""
def doneCommand(self, token, error):
+ """Called when command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneGetContext(object):
- """
- Client call back interface for getContext().
- """
+ """Client callback 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 context data retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context: Retrieved context data.
+ :type context: |ProcessContext|
"""
pass
class DoneGetChildren(object):
- """
- Client call back interface for getChildren().
- """
+ """Client callback 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 context list retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context_ids: List of available context IDs.
+ :type context_ids: |tuple| or |list|
"""
pass
class DoneGetSignalList(object):
- """
- Call-back interface to be called when "getSignalList" command is complete.
+ """Call-back interface to be called when |getSignalList| command is
+ complete.
"""
def doneGetSignalList(self, token, error, signalList):
+ """Called when signal list retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param signalList: The list of signals supported for this process.
+ :type signalList: |tuple| or |list|
+ """
pass
class DoneGetSignalMask(object):
- """
- Call-back interface to be called when "getSignalMask" command is complete.
- """
+ """Client callback interface for |getSignalMask|."""
def doneGetSignalMask(self, token, error, dont_stop, dont_pass, pending):
- """
- @param token - command handle.
- @param dont_stop - bit-set of signals that should suspend execution of
- the context.
- @param dont_pass - bit-set of signals that should not be delivered to
- the context.
- @param pending - bit-set of signals that are generated but not
- delivered yet.
- Note: "pending" is meaningful only if the context is suspended.
+ """Called when context signal mask retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param dont_stop: Bit-set of signals that should suspend execution of
+ the context.
+ :type dont_stop: |int|
+ :param dont_pass: Bit-set of signals that should not be delivered to
+ the context.
+ :type dont_pass: |int|
+ :param pending: Bit-set of signals that are generated but not
+ delivered yet.
+ :type pending: |int|
+
+ .. note:: *pending* is meaningful only if the context is suspended.
"""
pass
class DoneGetEnvironment(object):
- """
- Call-back interface to be called when "getEnvironment" command is complete.
- """
+ """Client callback interface for |getEnvironment|."""
def doneGetEnvironment(self, token, error, environment):
+ """Called when environment retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param environment: A |dict| of context environment variables.
+ :type environment: |dict|
+ """
pass
class DoneStart(object):
- """
- Call-back interface to be called when "start" command is complete.
- """
+ """Client callback interface for |start|."""
def doneStart(self, token, error, process):
+ """Called when process start is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param process: A |ProcessContext| object representing the started
+ process.
+ :type process: |ProcessContext|
+ """
pass
class ProcessesListener(object):
- """
- Process event listener is notified when a process exits.
- Event are reported only for processes that were started by 'start' command.
+ """Process event listener is notified when a process exits.
+
+ Event are reported only for processes that were started by |start| command.
"""
def exited(self, process_id, exit_code):
- """
- Called when a process exits.
- @param process_id - process context ID
- @param exit_code - if >= 0 - the process exit code, if < 0 - process
- was terminated by a signal, the signal
- code = -exit_code.
+ """Called when a process exits.
+
+ :param process_id: TCF process context ID.
+ :type process_id: |basestring|
+ :param exit_code: * If positive, the process exit code.
+ * If negative, process was terminated by a signal,
+ the signal code **-** *exit_code*.
"""
pass
diff --git a/python/src/tcf/services/registers.py b/python/src/tcf/services/registers.py
index e18f87833..91fdb6f10 100644
--- a/python/src/tcf/services/registers.py
+++ b/python/src/tcf/services/registers.py
@@ -9,119 +9,284 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-Registers service provides access to target CPU register values and properties.
+"""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. |
++---------------------+--------------+----------------------------------------+
+
+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."""
-# Context property names.
-# String, ID of the context
-PROP_ID = "ID"
+# Registers Context Properties
-# String, ID of a parent context
+PROP_ID = "ID"
PROP_PARENT_ID = "ParentID"
-
-# String, process ID
PROP_PROCESS_ID = "ProcessID"
-
-# String, context name
PROP_NAME = "Name"
-
-# String, context description
PROP_DESCRIPTION = "Description"
-
-# Number, context size in bytes. Byte arrays in get/set commands should be same
-# size
PROP_SIZE = "Size"
-
-# Boolean, true if context value can be read
PROP_READBLE = "Readable"
-
-# Boolean, true if reading the context (register) destroys its current value
PROP_READ_ONCE = "ReadOnce"
-
-# Boolean, true if context value can be written
PROP_WRITEABLE = "Writeable"
-
-# Boolean, true if register value can not be overwritten - every write counts
PROP_WRITE_ONCE = "WriteOnce"
-
-# Boolean, true if writing the context can change values of other registers
PROP_SIDE_EFFECTS = "SideEffects"
-
-# Boolean, true if the register value can change even when target is stopped
PROP_VOLATILE = "Volatile"
-
-# Boolean, true if the register value is a floating-point value
PROP_FLOAT = "Float"
-
-# Boolean, true if big endian
PROP_BIG_ENDIAN = "BigEndian"
-
-# Boolean, true if the lowest numbered bit should be shown to user as the
-# left-most bit
PROP_LEFT_TO_RIGHT = "LeftToRight"
-
-# Number, bit numbering base (0 or 1) to use when showing bits to user
PROP_FIRST_BIT = "FirstBit"
-
-# Number, if context is a bit field, contains the field bit numbers in the
-# parent context
PROP_BITS = "Bits"
-
-# Array of Map, predefined names (mnemonics) for some of context values
PROP_VALUES = "Values"
-
-# Number, the address of a memory mapped register
PROP_MEMORY_ADDRESS = "MemoryAddress"
-
-# String, the context ID of a memory context in which a memory mapped register
-# is located
PROP_MEMORY_CONTEXT = "MemoryContext"
-
-# Array of String, a list of attribute names which can be searched for starting
-# on this context
PROP_CAN_SEARCH = "CanSearch"
-
-# String, the role the register plays in a program execution
PROP_ROLE = "Role"
-
-# Number, when present describes the offset in the data of the parent register
-# where the value of a field can be found.
PROP_OFFSET = "Offset"
+# Registers Role Properties
-# Values of context property "Role".
-# Program counter. Defines instruction to execute next
ROLE_PC = "PC"
-
-# Register defining the current stack pointer location
ROLE_SP = "SP"
-
-# Register defining the current frame pointer location
ROLE_FP = "FP"
-
-# Register used to store the return address for calls
ROLE_RET = "RET"
-
-# Indicates register or register groups which belong to the core state
ROLE_CORE = "CORE"
-# Search filter properties.
-# The name of the property this filter applies too
-SEARCH_NAME = "Name"
+# Registers Search Properties
-# The value which is searched for
+SEARCH_NAME = "Name"
SEARCH_EQUAL_VALUE = "EqualValue"
class RegistersContext(object):
- """
- RegistersContext objects represent register groups, registers and bit
+ """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 {}
@@ -130,239 +295,292 @@ class RegistersContext(object):
return "[Registers Context %s]" % self._props
def getProperties(self):
- """
- Get context properties. See PROP_* definitions for property names.
+ """Get context properties.
+
+ See `Register Context 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 register context properties.
+
+ .. seealso:: `Register Context Properties`_
"""
return self._props
def getID(self):
- """
- Get Context ID.
- @return context ID.
+ """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.
- @return parent context ID.
+ """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.
- @return process ID.
+ """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.
- @return context name.
+ """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.
- @return context description.
+ """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 then this size, for example in case
+ """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 consist of necessary
+ implementation should add/remove padding that consists of necessary
number of zero bits.
- @return context size in bytes.
+
+ :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.
- @return true if can read value of the context.
+ """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.
- @return true if read-once register.
+ """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.
- @return true if can write value of the context.
+ """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.
- @return true if write-once register.
+ """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.
- @return true if has side effects.
+ """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.
- @return true if the register value can change at any time.
+ """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.
- @return true if a floating-point register.
+ """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.
+ """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.
- @return true if big endian.
+
+ 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
+ """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.
- @return true if the first bit is left-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
+ """If the context has bit field children, bit positions of the fields
can be zero-based or 1-based.
- @return first bit position - 0 or 1.
+
+ :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.
- @return array of bit numbers.
+ """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 its values.
+ """A context can have predefined names (mnemonics) for some of its
+ values.
+
This method returns a list of such named values.
- @return array of named values or None.
+
+ :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.
- @return address.
+ """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
+ """Get the context ID of a memory context in which a memory mapped
register is located.
- @return memory context ID.
+
+ :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
- @return collection of property names.
+ """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.
- @return role name.
+ """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.
- @return Register offset in parent register.
+ """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 object.
- @return - pending command handle.
+ """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 - value to write into the context.
- @param done - call back object.
- @return - pending command handle.
+ """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 in the "CanSearch"
- property.
- @param filterProps - properties bag that defines search filter.
- @param done - call back object.
- @return - pending command handle.
+ """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.
+ """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|
- @param contextID - context ID.
- @param done - call back interface called when operation is completed.
+ :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.
+ """Retrieve contexts available for registers commands.
+
A context corresponds to an execution thread, stack frame, registers
- group, etc.
+ 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
@@ -371,53 +589,77 @@ class RegistersService(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.
+ :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 - array of data locations.
- @param done - call back object.
- @return - pending command handle.
+ """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 - array of data locations.
- @param value - value to write into the context.
- @param done - call back object.
- @return - pending command handle.
+ """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 - event listener implementation.
+ """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 - event listener implementation.
+ """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
+ """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
@@ -425,108 +667,110 @@ class NamedValue(object):
self.description = description
def getValue(self):
- """
- Get value associated with the name.
- @return the value as an array of bytes.
+ """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.
- @return value name.
+ """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.
- @return value description.
+ """Get human readable description of the value.
+
+ :returns: A |basestring| representing this register named value
+ description.
"""
return self.description
class DoneGet(object):
- """
- 'get' command call back interface.
- """
+ """Client call back interface for |get| or |getm|."""
def doneGet(self, token, error, value):
- """
- Called when value retrieval is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param value - context value as array of bytes.
+ """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):
- """
- 'set' command call back interface.
+ """Client call back interface for |set| or |setm|.
"""
def doneSet(self, token, error):
- """
- Called when value setting is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
+ """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):
- """
- 'search' command call back interface.
+ """Client call back interface for |search|.
"""
def doneSearch(self, token, error, paths):
- """
- Called when context search is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
- @param paths - array of paths to each context with properties matching
- the filter
+ """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 - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param context - context data.
+ """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 getChildren().
+ """Client call back interface for :meth:`~RegistersService.getChildren`
"""
def doneGetChildren(self, token, error, context_ids):
- """
- Called when context list retrieval is done.
- @param token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param context_ids - array of available context IDs.
+ """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
+ """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.
+ """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.
@@ -535,31 +779,54 @@ class RegistersListener(object):
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 - register context ID.
+ """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
+ """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):
- # Register context ID
- self.id = contextID
- # offset in the context, in bytes
- self.offs = offs
- # value size in bytes
- self.size = size
+ self._id = contextID
+ self._offs = offs
+ self._size = size
def __iter__(self):
- yield self.id
- yield self.offs
- yield self.size
+ 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
diff --git a/python/src/tcf/services/streams.py b/python/src/tcf/services/streams.py
index 89068a9e3..c8f5d56ea 100644
--- a/python/src/tcf/services/streams.py
+++ b/python/src/tcf/services/streams.py
@@ -9,250 +9,430 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-Streams service is a generic interface to support streaming of data between
+"""Streams service is a generic interface to support streaming of data between
host and remote agents.
+.. |connect| replace:: :meth:`~StreamsService.connect`
+.. |disconnect| replace:: :meth:`~StreamsService.disconnect`
+.. |eos| replace:: :meth:`~StreamsService.eos`
+.. |processes| replace:: :mod:`~tcf.services.processes`
+.. |read| replace:: :meth:`~StreamsService.read`
+.. |subscribe| replace:: :meth:`~StreamsService.subscribe`
+.. |terminals| replace:: :mod:`~tcf.services.terminals`
+.. |unsubscribe| replace:: :meth:`~StreamsService.unsubscribe`
+.. |write| replace:: :meth:`~StreamsService.write`
+.. |DoneConnect| replace:: :class:`DoneConnect`
+.. |DoneDisconnect| replace:: :class:`DoneDisconnect`
+.. |DoneEOS| replace:: :class:`DoneEOS`
+.. |DoneRead| replace:: :class:`DoneRead`
+.. |DoneSubscribe| replace:: :class:`DoneSubscribe`
+.. |DoneUnsubscribe| replace:: :class:`DoneUnsubscribe`
+.. |DoneWrite| replace:: :class:`DoneWrite`
+.. |StreamsListener| replace:: :class:`StreamsListener`
+
The service supports:
- 1. Asynchronous overlapped data streaming: multiple 'read' or 'write' command
+ 1. Asynchronous overlapped data streaming: multiple |read| or |write| command
can be issued at same time, both peers can continue data processing
concurrently with data transmission.
2. Multicast: multiple clients can receive data from same stream.
3. Subscription model: clients are required to expressed interest in
particular streams by subscribing for the service.
4. Flow control: peers can throttle data flow of individual streams by
- delaying 'read' and 'write' commands.
+ delaying |read| and |write| commands.
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: StreamsService
+
+connect
+^^^^^^^
+.. automethod:: StreamsService.connect
+
+disconnect
+^^^^^^^^^^
+.. automethod:: StreamsService.disconnect
+
+eos
+^^^
+.. automethod:: StreamsService.eos
+
+getName
+^^^^^^^
+.. automethod:: StreamsService.getName
+
+read
+^^^^
+.. automethod:: StreamsService.read
+
+subscribe
+^^^^^^^^^
+.. automethod:: StreamsService.subscribe
+
+unsubscribe
+^^^^^^^^^^^
+.. automethod:: StreamsService.unsubscribe
+
+write
+^^^^^
+.. automethod:: StreamsService.write
+
+Callback Classes
+----------------
+DoneConnect
+^^^^^^^^^^^
+.. autoclass:: DoneConnect
+ :members:
+
+DoneDisconnect
+^^^^^^^^^^^^^^
+.. autoclass:: DoneDisconnect
+ :members:
+
+DoneEOS
+^^^^^^^
+.. autoclass:: DoneEOS
+ :members:
+
+DoneRead
+^^^^^^^^
+.. autoclass:: DoneRead
+ :members:
+
+DoneSubscribe
+^^^^^^^^^^^^^
+.. autoclass:: DoneSubscribe
+ :members:
+
+DoneUnsubscribe
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneUnsubscribe
+ :members:
+
+DoneWrite
+^^^^^^^^^
+.. autoclass:: DoneWrite
+ :members:
+
+Listener
+--------
+.. autoclass:: StreamsListener
+ :members:
"""
from .. import services
NAME = "Streams"
+"""Streams service name."""
class StreamsService(services.Service):
+ """TCF Streams service interface."""
+
def getName(self):
+ """Get this service name.
+
+ :returns: A |basestring| representing this service name, which is the
+ value of :const:`NAME`
+ """
return NAME
def subscribe(self, stream_type, listener, done):
- """
- Clients must subscribe for one or more stream types to be able to send
- or receive stream data.
+ """Clients must subscribe for one or more stream types to be able to
+ send or receive stream data.
+
Subscribers receive notifications when a stream of given type is
created or disposed.
- Subscribers are required to respond with 'read' or 'disconnect'
+
+ Subscribers are required to respond with |read| or |disconnect|
commands as necessary.
- @param stream_type - the stream source type.
- @param listener - client implementation of StreamsListener interface.
- @param done - command result call back object.
- @return - pending command handle.
+
+ .. note:: It is up to each service to implement its stream type if
+ required. For opensource services, |processes| uses
+ ``Processes`` for stream type, and |terminals| uses
+ ``Terminals``
+
+ :param stream_type: The stream source type.
+ :type stream_type: |basestring|
+ :param listener: Client implementation of StreamsListener interface.
+ :type listener: |StreamsListener|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneSubscribe|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def unsubscribe(self, stream_type, listener, done):
- """
- Unsubscribe the client from given stream source type.
- @param stream_type - the stream source type.
- @param listener - client implementation of StreamsListener interface.
- @param done - command result call back object.
- @return - pending command handle.
+ """Unsubscribe the client from given stream source type.
+
+ .. note:: It is up to each service to implement its stream type if
+ required. For opensource services, |processes| uses
+ ``Processes`` for stream type, and |terminals| uses
+ ``Terminals``
+
+ :param stream_type: The stream source type.
+ :param listener: Client implementation of StreamsListener interface.
+ :type listener: |StreamsListener|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneUnsubscribe|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def read(self, stream_id, size, done):
- """
- Read data from a stream. If stream buffer is empty, the command will
+ """Read data from a stream. If stream buffer is empty, the command will
wait until data is available.
- Remote peer will continue to process other commands while 'read'
+
+ Remote peer will continue to process other commands while |read|
command is pending.
- Client can send more 'read' commands without waiting for the first
+
+ Client can send more |read| commands without waiting for the first
command to complete.
+
Doing that improves communication channel bandwidth utilization.
- Pending 'read' commands will be executed in same order as issued.
- Client can delay sending of 'read' command if it is not ready to
- receive more data,
- however, delaying for too long can cause stream buffer overflow and
- lost of data.
- @param stream_id - ID of the stream.
- @param size - max number of bytes to read.
- @param done - command result call back object.
- @return - pending command handle.
+ Pending |read| commands will be executed in same order as issued.
+
+ Client can delay sending of |read| command if it is not ready to
+ receive more data, however, delaying for too long can cause stream
+ buffer overflow and lost of data.
+
+ :param stream_id: ID of the stream to read from.
+ :type stream_id: |basestring|
+ :param size: Max number of bytes to read.
+ :type size: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneRead|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def write(self, stream_id, buf, offset, size, done):
- """
- Write data to a stream. If stream buffer is full, the command will wait
- until space is available.
- Remote peer will continue to process other commands while 'write'
+ """Write data to a stream. If stream buffer is full, the command will
+ wait until space is available.
+
+ Remote peer will continue to process other commands while |write|
command is pending.
- Client can send more 'write' commands without waiting for the first
- command to complete.
- Doing that improves communication channel bandwidth utilization.
- Pending 'write' commands will be executed in same order as issued.
- @param stream_id - ID of the stream.
- @param buf - buffer that contains stream data.
- @param offset - byte offset in the buffer.
- @param size - number of bytes to write.
- @param done - command result call back object.
- @return - pending command handle.
+
+ Client can send more |write| commands without waiting for the first
+ command to complete. Doing that improves communication channel
+ bandwidth utilization.
+
+ Pending |write| commands will be executed in same order as issued.
+
+ :param stream_id: ID of the stream to write to.
+ :type stream_id: |basestring|
+ :param buf: Buffer that contains stream data.
+ :type buf: |bytearray|
+ :param offset: Byte offset in the buffer.
+ :type offset: |int|
+ :param size: Number of bytes to write.
+ :type size: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneWrite|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def eos(self, stream_id, done):
- """
- Send End Of Stream marker to a stream. No more writing to the stream is
- allowed after that.
- @param stream_id - ID of the stream.
- @param done - command result call back object.
- @return - pending command handle.
+ """Send End Of Stream marker to a stream.
+
+ No more writing to the stream is allowed after that.
+
+ :param stream_id: ID of the stream to senf EOS to.
+ :type stream_id: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneEOS|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def connect(self, stream_id, done):
- """
- Connect client to a stream.
- Some data might be dropped from the stream by the time "connect"
+ """Connect client to a stream.
+
+ Some data might be dropped from the stream by the time |connect|
command is executed.
+
Client should be able to re-sync with stream data if it wants to read
from such stream.
+
If a client wants to read a stream from the beginning it should use
- "subscribe" command
- instead of "connect".
- @param stream_id - ID of the stream.
- @param done - command result call back object.
- @return - pending command handle.
+ |subscribe| command instead of |connect|.
+
+ :param stream_id: ID of the stream to connect to.
+ :type stream_id: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneConnect|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def disconnect(self, stream_id, done):
- """
- Disconnect client from a stream.
- @param stream_id - ID of the stream.
- @param done - command result call back object.
- @return - pending command handle.
+ """Disconnect client from a stream.
+
+ :param stream_id: ID of the stream to disconnect from.
+ :type stream_id: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneDisconnect|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
class StreamsListener(object):
- """
- Clients can implement StreamsListener interface to be notified
- when a stream is created or disposed. The interface is registered with
- 'subscribe' command.
+ """Clients can implement StreamsListener interface to be notified
+ when a stream is created or disposed.
+
+ The interface is registered with |subscribe| command.
When new stream is created, client must decide if it is interested in that
particular stream instance.
- If not interested, client should send 'disconnect' command to allow remote
+
+ If not interested, client should send |disconnect| command to allow remote
peer to free resources and bandwidth.
- If not disconnected, client is required to send 'read' commands as
+
+ If not disconnected, client is required to send |read| commands as
necessary to prevent stream buffer overflow.
"""
def created(self, stream_type, stream_id, context_id):
- """
- Called when a new stream is created.
- @param stream_type - source type of the stream.
- @param stream_id - ID of the stream.
- @param context_id - a context ID that is associated with the stream,
- or None.
- Exact meaning of the context ID depends on stream type.
- Stream types and context IDs are defined by services that use Streams
- service to transmit data.
+ """Called when a new stream is created.
+
+ .. note:: It is up to each service to implement its stream type if
+ required. For opensource services, |processes| uses
+ ``Processes`` for stream type, and |terminals| uses
+ ``Terminals``
+
+ :param stream_type: Source type of the stream.
+ :type stream_type: |basestring|
+ :param stream_id: ID of the created stream.
+ :type stream_id: |basestring|
+ :param context_id: a context ID that is associated with the stream,
+ or **None**. Exact meaning of the context ID depends
+ on stream type. Stream types and context IDs are
+ defined by services that use Streams service to
+ transmit data
"""
pass
def disposed(self, stream_type, stream_id):
- """
- Called when a stream is disposed.
- @param stream_type - source type of the stream.
- @param stream_id - ID of the stream.
+ """Called when a stream is disposed.
+
+ .. note:: It is up to each service to implement its stream type if
+ required. For opensource services, |processes| uses
+ ``Processes`` for stream type, and |terminals| uses
+ ``Terminals``
+
+ :param stream_type: Source type of the stream.
+ :type stream_type: |basestring|
+ :param stream_id: ID of the disposed stream.
+ :type stream_id: |basestring|
"""
pass
class DoneSubscribe(object):
- """
- Call back interface for 'subscribe' command.
- """
+ """Call back interface for |subscribe| command."""
+
def doneSubscribe(self, token, error):
+ """Called when stream subscription is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneUnsubscribe(object):
- """
- Call back interface for 'unsubscribe' command.
- """
+ """Call back interface for |unsubscribe| command."""
+
def doneUnsubscribe(self, token, error):
+ """Called when stream unsubscription is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneRead(object):
- """
- Call back interface for 'read' command.
- """
+ """Call back interface for |read| command."""
+
def doneRead(self, token, error, lost_size, data, eos):
- """
- Called when 'read' command is done.
- @param token - command handle.
- @param error - error object or None.
- @param lost_size - number of bytes that were lost because of buffer
- overflow. 'lost_size' -1 means unknown number of
- bytes were lost. If both 'lost_size' and
- 'data.length' are non-zero then lost bytes are
- considered located right before read bytes.
- @param data - bytes read from the stream.
- @param eos - true if end of stream was reached.
+ """Called when |read| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param lost_size: Number of bytes that were lost because of buffer
+ overflow. A *lost_size* of **-1** means unknown
+ number of bytes were lost. If both *lost_size* and
+ *data.length* are non-zero then lost bytes are
+ considered located right before read bytes.
+ :type lost_size: |int|
+ :param data: Bytes read from the stream.
+ :type data: |bytearray|
+ :param eos: **True** if end of stream was reached.
+ :type eos: |bool|
"""
pass
class DoneWrite(object):
- """
- Call back interface for 'write' command.
- """
+ """Call back interface for |write| command."""
+
def doneWrite(self, token, error):
- """
- Called when 'write' command is done.
- @param token - command handle.
- @param error - error object or None.
+ """Called when |write| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class DoneEOS(object):
- """
- Call back interface for 'eos' command.
- """
+ """Call back interface for |eos| command."""
+
def doneEOS(self, token, error):
- """
- Called when 'eos' command is done.
- @param token - command handle.
- @param error - error object or None.
+ """Called when |eos| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class DoneConnect(object):
- """
- Call back interface for 'connect' command.
- """
+ """Call back interface for |connect| command."""
+
def doneConnect(self, token, error):
- """
- Called when 'connect' command is done.
- @param token - command handle.
- @param error - error object or None.
+ """Called when |connect| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
class DoneDisconnect(object):
- """
- Call back interface for 'disconnect' command.
- """
+ """Call back interface for |disconnect| command."""
+
def doneDisconnect(self, token, error):
- """
- Called when 'disconnect' command is done.
- @param token - command handle.
- @param error - error object or None.
+ """Called when |disconnect| command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
"""
pass
diff --git a/python/src/tcf/services/symbols.py b/python/src/tcf/services/symbols.py
index 0320e2bd4..8e43cebfc 100644
--- a/python/src/tcf/services/symbols.py
+++ b/python/src/tcf/services/symbols.py
@@ -9,34 +9,497 @@
# * Wind River Systems - initial API and implementation
#******************************************************************************
+"""TCF symbols service interface.
+
+.. |find| replace:: :meth:`~SymbolsService.find`
+.. |findByAddr| replace:: :meth:`~SymbolsService.findByAddr`
+.. |findByName| replace:: :meth:`~SymbolsService.findByName`
+.. |findFrameInfo| replace:: :meth:`~SymbolsService.findFrameInfo`
+.. |findInScope| replace:: :meth:`~SymbolsService.findInScope`
+.. |getArrayType| replace:: :meth:`~SymbolsService.getArrayType`
+.. |getChildren| replace:: :meth:`~SymbolsService.getChildren`
+.. |getContext| replace:: :meth:`~SymbolsService.getContext`
+.. |getFlags| replace:: :meth:`~Symbol.getFlags`
+.. |getID| replace:: :meth:`~Symbol.getID`
+.. |getLocationInfo| replace:: :meth:`~SymbolsService.getLocationInfo`
+.. |getName| replace:: :meth:`~SymbolsService.getName`
+.. |getProperties| replace:: :meth:`~Symbol.getProperties`
+.. |getSymFileInfo| replace:: :meth:`~SymbolsService.getSymFileInfo`
+.. |getUpdatePolicy| replace:: :meth:`~Symbol.getUpdatePolicy`
+.. |DoneFind| replace:: :class:`DoneFind`
+.. |DoneFindFrameInfo| replace:: :class:`DoneFindFrameInfo`
+.. |DoneGetArrayType| replace:: :class:`DoneGetArrayType`
+.. |DoneGetChildren| replace:: :class:`DoneGetChildren`
+.. |DoneGetContext| replace:: :class:`DoneGetContext`
+.. |DoneGetLocationInfo| replace:: :class:`DoneGetLocationInfo`
+.. |DoneGetSymFileInfo| replace:: :class:`DoneGetSymFileInfo`
+.. |DoneList| replace:: :class:`DoneList`
+.. |Symbol.getFlags| replace:: :meth:`Symbol.getFlags`
+.. |Symbol.getProperties| replace:: :meth:`Symbol.getProperties`
+.. |Symbol.getUpdatePolicy| replace:: :meth:`Symbol.getUpdatePolicy`
+.. |Symbol| replace:: :class:`Symbol`
+.. |SymbolClass| replace:: :class:`SymbolClass`
+.. |SymbolsService.list| replace:: :meth:`~SymbolsService.list`
+.. |TypeClass| replace:: :class:`TypeClass`
+
+Properties
+----------
+Symbol Context Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. seealso:: |Symbol|, |Symbol.getProperties|
+
++--------------------+--------------+-----------------------------------------+
+| Name | Type | Description |
++====================+==============+=========================================+
+| PROP_ADDRESS | |int| | Symbol address in symbol's memory |
+| | | space. |
++--------------------+--------------+-----------------------------------------+
+| PROP_BASE_TYPE_ID | |basestring| | ID of the symbol base type. It is |
+| | | possible to get the base type symbols |
+| | | by calling |getContext| on this ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_BIG_ENDIAN | |bool| | **True** if symbol's value is big |
+| | | endian. |
++--------------------+--------------+-----------------------------------------+
+| PROP_CONTAINER_ID | |basestring| | ID of the symbol containing this symbol.|
++--------------------+--------------+-----------------------------------------+
+| PROP_FLAGS | |int| | Symbol flags. See |
+| | | `Symbol Flags Properties`_. |
++--------------------+--------------+-----------------------------------------+
+| PROP_ID | |basestring| | Symbol's unique TCF ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_INDEX_TYPE_ID | |basestring| | Index type ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_LENGTH | |int| | Symbol length (if applicable) |
++--------------------+--------------+-----------------------------------------+
+| PROP_LOWER_BOUND | |int| | Symbol's lower bound in memory. |
++--------------------+--------------+-----------------------------------------+
+| PROP_NAME | |basestring| | Symbol's name. |
++--------------------+--------------+-----------------------------------------+
+| PROP_OFFSET | |int| | Symbol's offset (if any). |
++--------------------+--------------+-----------------------------------------+
+| PROP_OWNER_ID | |basestring| | Symbol's Owner TCF ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_REGISTER | |bool| | **True** if symbol is stored in a |
+| | | register. |
++--------------------+--------------+-----------------------------------------+
+| PROP_SIZE | |int| | Symbol size in bytes. |
++--------------------+--------------+-----------------------------------------+
+| PROP_SYMBOL_CLASS | |int| | Symbol's symbol class (see |
+| | | |SymbolClass|) |
++--------------------+--------------+-----------------------------------------+
+| PROP_TYPE_CLASS | |int| | Symbol's type class (see |TypeClass|) |
++--------------------+--------------+-----------------------------------------+
+| PROP_TYPE_ID | |basestring| | Type TCF ID. |
++--------------------+--------------+-----------------------------------------+
+| PROP_UPDATE_POLICY | |int| | Update policy. See |
+| | | `Symbol Update Policy Properties`_. |
++--------------------+--------------+-----------------------------------------+
+| PROP_UPPER_BOUND | |int| | Symbols' upper bound address. |
++--------------------+--------------+-----------------------------------------+
+| PROP_VALUE | |bytearray| | Symbol value (if any) |
++--------------------+--------------+-----------------------------------------+
+
+Symbol Flags Properties
+^^^^^^^^^^^^^^^^^^^^^^^
+All symbol flags are of type |int|.
+
+.. seealso:: |Symbol.getFlags|
+
++-------------------------+--------------------------------+
+| Name | Description |
++=========================+================================+
+| SYM_FLAG_ARTIFICIAL | Symbol is artificial. |
++-------------------------+--------------------------------+
+| SYM_FLAG_BIG_ENDIAN | Symbol is big endian. |
++-------------------------+--------------------------------+
+| SYM_FLAG_BOOL_TYPE | Symbol is a boolean |
++-------------------------+--------------------------------+
+| SYM_FLAG_CLASS_TYPE | Symbol is a class type symbol. |
++-------------------------+--------------------------------+
+| SYM_FLAG_CONST_TYPE | Symbol is a constant. |
++-------------------------+--------------------------------+
+| SYM_FLAG_ENUM_TYPE | Symbol is an enum. |
++-------------------------+--------------------------------+
+| SYM_FLAG_EXTERNAL | Symbol is external. |
++-------------------------+--------------------------------+
+| SYM_FLAG_INHERITANCE | Symbol is a base class |
++-------------------------+--------------------------------+
+| SYM_FLAG_INTERFACE_TYPE | Symbol is an interface. |
++-------------------------+--------------------------------+
+| SYM_FLAG_LITTLE_ENDIAN | Symbol is little endian. |
++-------------------------+--------------------------------+
+| SYM_FLAG_OPTIONAL | Symbol is optional. |
++-------------------------+--------------------------------+
+| SYM_FLAG_PACKET_TYPE | Symbol is a packet type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_PARAMETER | Symbol is a parameter. |
++-------------------------+--------------------------------+
+| SYM_FLAG_PRIVATE | Symbol is private. |
++-------------------------+--------------------------------+
+| SYM_FLAG_PROTECTED | Symbol is protected. |
++-------------------------+--------------------------------+
+| SYM_FLAG_PUBLIC | Symbol is public. |
++-------------------------+--------------------------------+
+| SYM_FLAG_REFERENCE | Symbol is a reference. |
++-------------------------+--------------------------------+
+| SYM_FLAG_RESTRICT_TYPE | Symbol is of restrict type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_SHARED_TYPE | Symbol is of shared type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_STRUCT_TYPE | Symbol is of structure type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_STRING_TYPE | Symbol is a string type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_SUBRANGE_TYPE | Symbol is of subrange type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_TYPEDEF | Symbol is a typedef. |
++-------------------------+--------------------------------+
+| SYM_FLAG_TYPE_PARAMETER | Symbol is a of parameter type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_UNION_TYPE | Symbol is of union type. |
++-------------------------+--------------------------------+
+| SYM_FLAG_VARARG | Symbol is a variable argument. |
++-------------------------+--------------------------------+
+| SYM_FLAG_VOLATILE_TYPE | Symbol is of volatile type. |
++-------------------------+--------------------------------+
+
+Symbol Update Policy Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+All symbol policy properties are of type |int|.
+
+.. seealso:: |Symbol.getUpdatePolicy|
+
++------------------------------+----------------------------------------------+
+| Name | Description |
++==============================+==============================================+
+| UPDATE_ON_EXE_STATE_CHANGES | Update policy *Memory Map*: symbol properties|
+| | become invalid when memory map changes : |
+| | when modules are loaded or unloaded. Symbol |
+| | OwnerID indicates memory space (process) that|
+| | is invalidation events source. Most static |
+| | variables and types have this update policy. |
++------------------------------+----------------------------------------------+
+| UPDATE_ON_MEMORY_MAP_CHANGES | Update policy *Execution State*: symbol |
+| | properties become invalid when execution |
+| | state changes : a thread is suspended, |
+| | resumed or exited. Symbol OwnerID indicates |
+| | executable context (thread) that is |
+| | invalidation events source. Most stack (auto)|
+| | variables have this update policy. |
++------------------------------+----------------------------------------------+
+
+Symbol Command Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^
+All symbol command properties are of type |int|.
+
+Command codes that are used to calculate frame pointer and register values
+during stack tracing.
+
+.. seealso:: |findFrameInfo|
+
++--------------+--------------------------------------------------------------+
+| Name | Description |
++==============+==============================================================+
+| CMD_ADD | Add two values on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_AND | And two values on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_ARG | Load expression argument to evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_DEREF | **deprecated** : Read memory at address on the top of the |
+| | evaluation stack. |
+| | Command arguments are the value size (Number) and endianness |
+| | (Boolean, false - little-endian, true - big-endian). |
++--------------+--------------------------------------------------------------+
+| CMD_DIV | Divide two values on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_FCALL | Evaluate function call on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_FP | Load frame address to the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_GE | Compare two values on top of the evaluation stack (Greater or|
+| | Equal). |
++--------------+--------------------------------------------------------------+
+| CMD_GT | Compare two values on top of the evaluation stack (Greater) |
++--------------+--------------------------------------------------------------+
+| CMD_LE | Compare two values on top of the evaluation stack (Lighter or|
+| | Equal). |
++--------------+--------------------------------------------------------------+
+| CMD_LOCATION | Evaluate DWARF location expression. Command arguments are |
+| | byte array of DWARF expression instructions and an object |
+| | that contains evaluation parameters. |
++--------------+--------------------------------------------------------------+
+| CMD_LT | Compare two values on top of the evaluation stack (Lighter) |
++--------------+--------------------------------------------------------------+
+| CMD_MUL | Multiply two values on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_NEG | Negate a value on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_NUMBER | Load a number to the evaluation stack. Command argument is |
+| | the number. |
++--------------+--------------------------------------------------------------+
+| CMD_OR | Or two values on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_PIECE | Value on top of the evaluation stack is in pieces. |
++--------------+--------------------------------------------------------------+
+| CMD_REGISTER | **deprecated** : Load a register value to the evaluation |
+| | stack. Command argument is the register ID. |
++--------------+--------------------------------------------------------------+
+| CMD_SHL | Left shift value on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_SHR | Right shift value on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_SUB | Substract two values on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+| CMD_WR_MEM | Value on top of the stack is a Wind River Memory ID ??? |
++--------------+--------------------------------------------------------------+
+| CMD_WR_REG | Value on top of the stack is a Wind River Register ID ??? |
++--------------+--------------------------------------------------------------+
+| CMD_XOR | Xor value on top of the evaluation stack. |
++--------------+--------------------------------------------------------------+
+
+Symbol Location Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. seealso:: |getLocationInfo|
+
++-----------------+--------+--------------------------------------------------+
+| Name | Type | Description |
++=================+========+==================================================+
+| LOC_ARG_CNT | |int| | Number of argument required to execute location |
+| | | instructions. |
++-----------------+--------+--------------------------------------------------+
+| LOC_CODE_ADDR | |int| | Start address of code range where the location |
+| | | info is valid, or **None** if it is valid |
+| | | everywhere. |
++-----------------+--------+--------------------------------------------------+
+| LOC_CODE_SIZE | |int| | Size in bytes of code range where the location |
+| | | info is valid, or **None** if it is valid |
+| | | everywhere. |
++-----------------+--------+--------------------------------------------------+
+| LOC_LENGTH_CMDS | |list| | Instructions to compute dynamic array length |
+| | | location. |
++-----------------+--------+--------------------------------------------------+
+| LOC_VALUE_CMDS | |list| | Instructions to compute object value location, |
+| | | e.g. address, or offset, or register ID, etc... |
++-----------------+--------+--------------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: SymbolsService
+
+find
+^^^^
+.. automethod:: SymbolsService.find
+
+findByAddr
+^^^^^^^^^^
+.. automethod:: SymbolsService.findByAddr
+
+findByName
+^^^^^^^^^^
+.. automethod:: SymbolsService.findByName
+
+findFrameInfo
+^^^^^^^^^^^^^
+.. automethod:: SymbolsService.findFrameInfo
+
+findInScope
+^^^^^^^^^^^
+.. automethod:: SymbolsService.findInScope
+
+getArrayType
+^^^^^^^^^^^^
+.. automethod:: SymbolsService.getArrayType
+
+getChildren
+^^^^^^^^^^^
+.. automethod:: SymbolsService.getChildren
+
+getContext
+^^^^^^^^^^
+.. automethod:: SymbolsService.getContext
+
+getLocationInfo
+^^^^^^^^^^^^^^^
+.. automethod:: SymbolsService.getLocationInfo
+
+getName
+^^^^^^^
+.. automethod:: SymbolsService.getName
+
+getSymFileInfo
+^^^^^^^^^^^^^^
+.. automethod:: SymbolsService.getSymFileInfo
+
+list
+^^^^
+.. automethod:: SymbolsService.list
+
+Callback Classes
+----------------
+DoneFind
+^^^^^^^^
+.. autoclass:: DoneFind
+ :members:
+
+DoneFindFrameInfo
+^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneFindFrameInfo
+ :members:
+
+DoneGetArrayType
+^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetArrayType
+ :members:
+
+DoneGetChildren
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetChildren
+ :members:
+
+DoneGetContext
+^^^^^^^^^^^^^^
+.. autoclass:: DoneGetContext
+ :members:
+
+DoneGetLocationInfo
+^^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetLocationInfo
+ :members:
+
+DoneGetSymFileInfo
+^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetSymFileInfo
+ :members:
+
+DoneList
+^^^^^^^^
+.. autoclass:: DoneList
+ :members:
+
+Helper Classes
+--------------
+Symbol
+^^^^^^
+.. autoclass:: Symbol
+ :members:
+
+SymbolClass
+^^^^^^^^^^^
+.. autoclass:: SymbolClass
+
+TypeClass
+^^^^^^^^^
+.. autoclass:: TypeClass
+"""
+
from .. import services
-# Service name.
NAME = "Symbols"
+"""Symbols service name."""
class SymbolClass:
- unknown = 0 # unknown symbol class
- value = 1 # constant value
- reference = 2 # variable data object
- function = 3 # function body
- type = 4 # a type @ReservedAssignment
- comp_unit = 5 # a compilation unit
- block = 6 # a block of code
- namespace = 7 # a namespace
+ """Symbol class values.
+
+
+ This class allows to bind Symbol's class value to a type.
+
+ .. code-block:: python
+
+ import tcf.services.symbols as tcfsyms
+
+ if symbol.getSymbolClass() is tcfsyms.TypeClass.function:
+ # Print name + address
+ print '{0} : 0x{1:016x}'.format(symbol.getName(),
+ symbol.getAddress())
+
+ Here is the value/class association table:
+
+ +-------+-----------+-----------------------+
+ | Value | Name | Description |
+ +=======+===========+=======================+
+ | **0** | unknown | Unknown symbol class. |
+ +-------+-----------+-----------------------+
+ | **1** | value | Constant value. |
+ +-------+-----------+-----------------------+
+ | **2** | reference | Variable data object. |
+ +-------+-----------+-----------------------+
+ | **3** | function | Function body. |
+ +-------+-----------+-----------------------+
+ | **4** | type | A type. |
+ +-------+-----------+-----------------------+
+ | **5** | comp_unit | A compilation unit. |
+ +-------+-----------+-----------------------+
+ | **6** | block | A block of code. |
+ +-------+-----------+-----------------------+
+ | **7** | namespace | A namespace. |
+ +-------+-----------+-----------------------+
+ """
+ unknown = 0
+ value = 1
+ reference = 2
+ function = 3
+ type = 4 # @ReservedAssignment
+ comp_unit = 5
+ block = 6
+ namespace = 7
class TypeClass:
- unknown = 0 # unknown type class
- cardinal = 1 # unsigned integer
- integer = 2 # signed integer
- real = 3 # float, double
- pointer = 4 # pointer to anything.
- array = 5 # array of anything.
- composite = 6 # struct, union, or class.
- enumeration = 7 # enumeration type.
- function = 8 # function type.
- member_ptr = 9 # a pointer on member type
+ """Type class values.
+
+ This class allows to bind Symbol's type class value to a type.
+
+ .. code-block:: python
+
+ import tcf.services.symbols as tcfsyms
+
+ if symbol.getTypeClass() is tcfsyms.TypeClass.pointer:
+ # print it as a pointer
+ print '{0} : 0x{1:016x}'.format(symbol.getName(),
+ symbol.getAddress())
+
+ Here is the value/type association table:
+
+ +-------+-------------+---------------------------+
+ | Value | Name | Description |
+ +=======+=============+===========================+
+ | **0** | unknown | Unknown type class. |
+ +-------+-------------+---------------------------+
+ | **1** | cardinal | Unsigned integer. |
+ +-------+-------------+---------------------------+
+ | **2** | integer | Signed integer. |
+ +-------+-------------+---------------------------+
+ | **3** | real | Float, double. |
+ +-------+-------------+---------------------------+
+ | **4** | pointer | Pointer to anything. |
+ +-------+-------------+---------------------------+
+ | **5** | array | Array of anything. |
+ +-------+-------------+---------------------------+
+ | **6** | composite | Struct, union, or class. |
+ +-------+-------------+---------------------------+
+ | **7** | enumeration | Enumeration type. |
+ +-------+-------------+---------------------------+
+ | **8** | function | Function type. |
+ +-------+-------------+---------------------------+
+ | **9** | member_ptr | A pointer on member type. |
+ +-------+-------------+---------------------------+
+ """
+ unknown = 0
+ cardinal = 1
+ integer = 2
+ real = 3
+ pointer = 4
+ array = 5
+ composite = 6
+ enumeration = 7
+ function = 8
+ member_ptr = 9
SYM_FLAG_PARAMETER = 0x000001
SYM_FLAG_TYPEDEF = 0x000002
@@ -58,14 +521,16 @@ SYM_FLAG_VARARG = 0x010000
SYM_FLAG_ARTIFICIAL = 0x020000
SYM_FLAG_TYPE_PARAMETER = 0x040000
SYM_FLAG_PRIVATE = 0x080000
-SYM_FLAG_PROTECTED = 0x100000
-SYM_FLAG_PUBLIC = 0x200000
-SYM_FLAG_ENUM_TYPE = 0x400000
-SYM_FLAG_STRUCT_TYPE = 0x800000
+SYM_FLAG_PROTECTED = 0x0100000
+SYM_FLAG_PUBLIC = 0x0200000
+SYM_FLAG_ENUM_TYPE = 0x0400000
+SYM_FLAG_STRUCT_TYPE = 0x0800000
+SYM_FLAG_STRING_TYPE = 0x1000000
+SYM_FLAG_INHERITANCE = 0x2000000
+SYM_FLAG_BOOL_TYPE = 0x4000000
-#
# Symbol context property names.
-#
+
PROP_ID = "ID"
PROP_OWNER_ID = "OwnerID"
PROP_UPDATE_POLICY = "UpdatePolicy"
@@ -87,28 +552,19 @@ PROP_REGISTER = "Register"
PROP_FLAGS = "Flags"
PROP_CONTAINER_ID = "ContainerID"
-#
# Symbol context properties update policies.
-#
-# Update policy "Memory Map": symbol properties become invalid when
-# memory map changes - when modules are loaded or unloaded.
-# Symbol OwnerID indicates memory space (process) that is invalidation events
-# source.
-# Most static variables and types have this update policy.
UPDATE_ON_MEMORY_MAP_CHANGES = 0
-
-# Update policy "Execution State": symbol properties become invalid when
-# execution state changes - a thread is suspended, resumed or exited.
-# Symbol OwnerID indicates executable context (thread) that is invalidation
-# events source.
-# Most stack (auto) variables have this update policy.
UPDATE_ON_EXE_STATE_CHANGES = 1
class Symbol(object):
- """
- Symbol context interface.
+ """Symbol context interface.
+
+ :param props: Properties to create this symbol with.
+ :type props: |dict|
+
+ .. seealso:: `Symbol Context Properties`_
"""
def __init__(self, props):
self._props = props or {}
@@ -117,423 +573,490 @@ class Symbol(object):
return "[Symbol Context %s]" % self._props
def getID(self):
- """
- Get symbol ID.
- @return symbol ID.
+ """Get symbol ID.
+
+ :returns: A |basestring| reprsenting this symbol's unique TCF ID.
"""
return self._props.get(PROP_ID)
def getOwnerID(self):
- """
- Get symbol owner ID.
+ """Get symbol owner ID.
+
The owner can a thread or memory space (process).
+
Certain changes in owner state can invalidate cached symbol properties,
- see getUpdatePolicy() and UPDATE_*.
+ see |getUpdatePolicy| and `Symbol Update Policy Properties`_.
+
+ :returns: A |basestring| representing this symbol's owner ID, or
+ **None** if unknown.
"""
return self._props.get(PROP_OWNER_ID)
def getUpdatePolicy(self):
- """
- Get symbol properties update policy ID.
+ """Get symbol properties update policy ID.
+
Symbol properties can change during program execution.
+
If a client wants to cache symbols, it should invalidate cached data
according to update policies of cached symbols.
- @return symbol update policy ID, see UPDATE_*
+
+ :returns: An |int| representing this symbol update policy, see
+ `Symbol Update Policy Properties`_.
"""
return self._props.get(PROP_UPDATE_POLICY)
def getName(self):
- """
- Get symbol name.
- @return symbol name or None.
+ """Get this symbol name.
+
+ :returns: A |basestring| representing this symbol's name.
"""
return self._props.get(PROP_NAME)
def getSymbolClass(self):
- """
- Get symbol class.
- @return symbol class.
+ """Get symbol class.
+
+ :returns: An |int| representing this symbol's symbol class, or
+ **None** if unknown.
+
+ .. seealso:: |SymbolClass|
"""
return self._props.get(PROP_SYMBOL_CLASS, SymbolClass.unknown)
def getTypeClass(self):
- """
- Get symbol type class.
- @return type class.
+ """Get symbol type class.
+
+ :returns: An |int| representing this symbol's type class, or **None**
+ if unknown.
+
+ .. seealso:: |TypeClass|
"""
return self._props.get(PROP_TYPE_CLASS, TypeClass.unknown)
def getTypeID(self):
- """
- Get type ID.
- If the symbol is a type and not a 'typedef', return same as getID().
- @return type ID.
+ """Get type ID.
+
+ If the symbol is a type and not a ``typedef``, return same as |getID|.
+
+ :returns: A |basestring| representing this symbol's type ID.
"""
return self._props.get(PROP_TYPE_ID)
def getBaseTypeID(self):
- """
- Get base type ID.
- If this symbol is a
- pointer type - return pointed type
- array type - return element type
- function type - return function result type
- class type - return base class
- otherwise return None.
- @return type ID.
+ """Get base type ID.
+
+ :returns: If this symbol is a
+
+ * pointer type - return pointed type
+ * array type - return element type
+ * function type - return function result type
+ * class type - return base class
+ * otherwise - return **None**
"""
return self._props.get(PROP_BASE_TYPE_ID)
def getContainerID(self):
"""Get container type ID.
- If this symbol is a
- field or member - return containing class type;
- member pointer - return containing class type;
- otherwise return None.
- @return type ID.
+
+ :returns: If this symbol is a
+
+ * field or member - return containing class type
+ * member pointer - return containing class type
+ * otherwise - return **None**
"""
return self._props.get(PROP_CONTAINER_ID)
def getIndexTypeID(self):
- """
- Get index type ID.
- If this symbol is a
- array type - return array index type
- otherwise return None.
- @return type ID.
+ """Get index type ID.
+
+ :returns: If this symbol is a
+
+ * array type - return array index type
+ * otherwise - return **None**
"""
return self._props.get(PROP_INDEX_TYPE_ID)
def getSize(self):
- """
- Return value size of the symbol (or type).
- @return size in bytes.
+ """Get value size of the symbol (or type).
+
+ :returns: An |int| representing this symbol's size in bytes.
"""
return self._props.get(PROP_SIZE, 0)
def getLength(self):
- """
- If symbol is an array type - return number of elements.
- @return number of elements.
+ """If symbol is an array type, get its number of elements.
+
+ :returns: An |int| reprsenting the number of elements of this symbol if
+ it is an array.
"""
return self._props.get(PROP_LENGTH, 0)
def getLowerBound(self):
- """
- If symbol is an array type - return array index lower bound.
- @return lower bound.
+ """If symbol is an array type, get array index lower bound.
+
+ :returns: An |int| representing this array lower bound.
"""
return self._props.get(PROP_LOWER_BOUND)
def getUpperBound(self):
- """
- If symbol is an array type - return array index upper bound.
- @return upper bound.
+ """If symbol is an array type, get the array index upper bound.
+
+ :returns: An |int| representing this array upper bound.
"""
return self._props.get(PROP_UPPER_BOUND)
def getOffset(self):
- """
- Return offset from 'this' for member of class, struct or union.
- @return offset in bytes.
+ """Return offset of this symbol for member of class, struct or union.
+
+ :returns: An |int| reprsenting this symbol's offset in bytes or **0**.
"""
return self._props.get(PROP_OFFSET, 0)
def getAddress(self):
- """
- Return address of the symbol.
- @return address or None.
+ """Return address of the symbol.
+
+ :returns: An |int| representing this symbol's address or **None**
"""
return self._props.get(PROP_ADDRESS)
def getValue(self):
- """
- If symbol is a constant object, return its value.
- @return symbol value as array of bytes.
+ """If symbol is a constant object, return its value.
+
+ :returns: A |bytearray| representing this symbol's value.
"""
return self._props.get(PROP_VALUE)
def isBigEndian(self):
- """
- Get symbol values endianness.
- @return true if symbol is big-endian.
+ """Get symbol values endianness.
+
+ :returns: A |bool| set to **True** if this symbol is big-endian
"""
return self._props.get(PROP_BIG_ENDIAN, False)
def getRegisterID(self):
- """
- Return register ID if the symbol represents a register variable.
- @return register ID or None.
+ """Return register ID if the symbol represents a register variable.
+
+ :returns: A |basestring| representing this register ID or **None**.
"""
return self._props.get(PROP_REGISTER)
def getFlags(self):
- """
- Get symbol flags.
- @return Symbol flags (see SYM_FLAG_ values).
+ """Get symbol flags.
+
+ :returns: An |int| representing this symbol flags (see
+ `Symbol Flags Properties`_).
"""
return self._props.get(PROP_FLAGS, 0)
def getProperties(self):
- """
- Get complete map of context properties.
- @return map of context properties.
+ """Get complete map of context properties.
+
+ :returns: A |dict| of the properties describing this symbol.
"""
return self._props
class SymbolsService(services.Service):
+ """TCF Symbols services interface"""
+
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 symbol context info for given symbol ID.
- @see Symbol
+ """Retrieve symbol context info for given symbol ID.
+
+ :param contextID: ID of the symbol to retrieve.
+ :type contextID: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGetContext|
- @param contextID - symbol context ID.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getChildren(self, parent_context_id, done):
- """
- Retrieve children IDs for given parent ID.
+ """Retrieve children IDs for given parent ID.
+
Meaning of the operation depends on parent kind:
- 1. struct, union, or class type - get fields
- 2. enumeration type - get enumerators
- @param parent_context_id - parent symbol context ID.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ * struct, union, or class type - get fields
+ * enumeration type - get enumerators
+
+ :param parent_context_id: Parent symbol context ID.
+ :type parent_context_id: |basestring|
+ :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 find(self, context_id, ip, name, done):
- """
- Search first symbol with given name in given context.
+ """Search first symbol with given name in given context.
+
The context can be memory space, process, thread or stack frame.
- @param context_id - a search scope.
- @param ip - instruction pointer - ignored if context_id is a stack
- frame ID
- @param name - symbol name.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param context_id: A search scope context ID.
+ :type context_id: |basestring|
+ :param ip: instruction pointer - ignored if *context_id* is a stack
+ frame ID.
+ :param ip: |int|
+ :param name: Symbol name to look for.
+ :type name: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneFind|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def findByName(self, context_id, ip, name, done):
- """
- Search symbols with given name in given context.
+ """Search symbols with given name in given context.
+
The context can be memory space, process, thread or stack frame.
- @param context_id - a search scope.
- @param ip - instruction pointer - ignored if context_id is a stack
- frame ID
- @param name - symbol name.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param context_id: A search scope context ID.
+ :type context_id: |basestring|
+ :param ip: instruction pointer - ignored if *context_id* is a stack
+ frame ID.
+ :type ip: |int|
+ :param name: Symbol name to look for.
+ :type name: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneFind|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def findByAddr(self, context_id, addr, done):
- """
- Search symbol with given address in given context.
+ """Search symbol with given address in given context.
+
The context can be memory space, process, thread or stack frame.
- @param context_id - a search scope.
- @param addr - symbol address.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param context_id: A search scope context ID.
+ :type context_id: |basestring|
+ :param addr: Address of the symbol to look for.
+ :type addr: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneFind|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def findInScope(self, context_id, ip, scope_id, name, done):
- """
- Search symbols with given name in given context or in given symbol
+ """Search symbols with given name in given context or in given symbol
scope.
+
The context can be memory space, process, thread or stack frame.
+
The symbol scope can be any symbol.
- If ip is not null, the search of the symbol name is done first in the
- scope defined by @e context_id and @e ip.
+
+ If *ip* is not **None**, the search of the symbol name is done first in
+ the scope defined by *context_id* and *ip*.
+
If the symbol is not found, the supplied scope is then used.
- @param context_id - a search scope.
- @param ip - instruction pointer. Can be null if only @e scope_id
- should be used.
- @param scope_id - symbol context ID.
- @param name - symbol name.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param context_id: A search scope context ID.
+ :type context_id: |basestring|
+ :param ip: instruction pointer. Can be null if only *scope_id* should
+ be used.
+ :type ip: |int| or **None**
+ :param scope_id: Symbol scope context ID.
+ :type scope_id: |basestring|
+ :param name: Symbol name to look for.
+ :type name: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneFind|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def list(self, context_id, done): # @ReservedAssignment
- """
- List all symbols in given context.
+ """List all symbols in given context.
+
The context can be a stack frame.
- @param context_id - a scope.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :param context_id: A scope context ID.
+ :type context_id: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneList|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getArrayType(self, type_id, length, done):
- """
- Create an array type.
+ """Create an array type.
+
+ :param type_id: Symbol ID of the array cell type.
+ :type type_id: |basestring|
+ :param length: length of the array. A length of 0 creates a pointer
+ type.
+ :type length: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGetArrayType|
- @param type_id - symbol ID of the array cell type
- @param length - length of the array. A length of 0 creates a pointer
- type.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def findFrameInfo(self, context_id, address, done):
- """
- Retrieve stack tracing commands for given instruction address in a
+ """Retrieve stack tracing commands for given instruction address in a
context memory.
- @param context_id - exacutable context ID.
- @param address - instruction address.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+
+ :param context_id: Executable context ID.
+ :type context_id: |basestring|
+ :param address: Instruction address.
+ :type address: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneFindFrameInfo|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getLocationInfo(self, symbolID, done):
"""Retrieve symbol location information.
- @param symbol_id - symbol ID.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+
+ :param symbol_id: Symbol ID.
+ :type symbol_id: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGetLocationInfo|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getSymFileInfo(self, contextID, address, done):
"""Get symbol file info for a module that contains given address in a
memory space.
- @param contextID - a memory space (process) ID.
- @param address - an address in the memory space.
- @param done - call back interface called when operation is completed.
- @return - pending command handle.
+
+ :param contextID: A memory space (process) ID.
+ :type contextID: |basestring|
+ :param address: An address in the memory space.
+ :type address: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGetSymFileInfo|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
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 token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param context - context properties.
+ """Called when |getContext| is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context: Retreived symbol context.
+ :type context: |Symbol|
"""
pass
class DoneGetLocationInfo(object):
- """Client call back interface for getLocationInfo()."""
+ """Client call back interface for |getLocationInfo|.
+ """
def doneGetLocationInfo(self, token, error, props):
"""Called when location information retrieval is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
- @param props - symbol location properties, see LOC_ * .
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param props: Symbol location properties, see
+ `Symbol Location Properties`_.
+ :type props: |dict|
"""
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 token - command handle
- @param error - error description if operation failed, None if
- succeeded.
- @param context_ids - array of available 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: List of available context IDs.
+ :type context_ids: |list|
"""
pass
class DoneFind(object):
- """
- Client call back interface for find(), findByName() and findInScope().
+ """Client call back interface for |find|, |findByName| and |findInScope|
+ commands.
"""
def doneFind(self, token, error, symbol_ids):
- """
- Called when symbol search is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
- @param symbol_ids - list of symbol ID.
+ """Called when symbol search is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param symbol_ids: List of symbol ID.
+ :type symbol_ids: |list|
"""
pass
class DoneGetSymFileInfo(object):
- """Client call back interface for getSymFileInfo()."""
+ """Client call back interface for |getSymFileInfo|."""
def doneGetSymFileInfo(self, token, error, props):
"""Called when symbol file information retrieval is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
- @param props - symbol file properties.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param props: Symbol file properties.
+ :type props: |dict|
"""
pass
class DoneList(object):
- """
- Client call back interface for list().
- """
+ """Client call back interface for |list|."""
def doneList(self, token, error, symbol_ids):
+ """Called when symbol list retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param symbol_ids: List of symbol IDs.
+ :type symbol_ids: |list|
"""
- Called when symbol list retrieval is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
- @param symbol_ids - array of symbol IDs.
- """
+ pass
class DoneGetArrayType(object):
- """
- Client call back interface for getArrayType().
- """
+ """Client call back interface for |getArrayType|."""
def doneGetArrayType(self, token, error, type_id):
- """
- Called when array type creation is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
- @param type_id - array type symbol ID
- """
+ """Called when array type creation is done.
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param type_id: Array type symbol ID.
+ :type type_id: |basestring|
+ """
+ pass
-#
# Command codes that are used to calculate frame pointer and register values
# during stack tracing.
-#
-# Load a number to the evaluation stack. Command argument is the number.
CMD_NUMBER = 1
-
-# Load frame address to the evaluation stack.
CMD_FP = 3
-
-# Add two values on top of the evaluation stack
CMD_ADD = 5
-
CMD_SUB = 6
CMD_MUL = 7
CMD_DIV = 8
@@ -547,67 +1070,44 @@ CMD_LE = 15
CMD_LT = 16
CMD_SHL = 17
CMD_SHR = 18
-
-# Load expression argument to evaluation stack.
CMD_ARG = 19
-
-# Evaluate DWARF location expression. Command arguments are byte array of
-# DWARF expression instructions and an object that contains evaluation
-# parameters.
CMD_LOCATION = 20
-
CMD_FCALL = 21
CMD_WR_REG = 22
CMD_WR_MEM = 23
CMD_PIECE = 24
-# deprecated
-# Load a register value to the evaluation stack. Command argument is the
-# register ID.
-CMD_REGISTER = 2
+# Deprecated
-# Read memory at address on the top of the evaluation stack. Command arguments
-# are the value size (Number) and endianness (Boolean, false - little-endian,
-# true - big-endian).
+CMD_REGISTER = 2
CMD_DEREF = 4
# Symbol location properties.
-# Number, start address of code range where the location info is valid, or null
-# if it is valid everywhere
LOC_CODE_ADDR = "CodeAddr"
-
-# Number, size in bytes of code range where the location info is valid, or null
-# if it is valid everywhere
LOC_CODE_SIZE = "CodeSize"
-
-
-# Number, number of argument required to execute location instructions
LOC_ARG_CNT = "ArgCnt"
-
-# List, instructions to compute object value location, e.g. address, or offset,
-# or register ID, etc.
LOC_VALUE_CMDS = "ValueCmds"
-
-# List, instructions to compute dynamic array length location
LOC_LENGTH_CMDS = "LengthCmds"
class DoneFindFrameInfo(object):
- """
- Client call back interface for findFrameInfo().
- """
+ """Client call back interface for |findFrameInfo|."""
def doneFindFrameInfo(self, token, error, address, size, fp_cmds,
reg_cmds):
- """
- Called when stack tracing information retrieval is done.
- @param token - command handle.
- @param error - error description if operation failed, None if
- succeeded.
- @param address - start of instruction address range
- @param size - size of instruction address range
- @param fp_cmds - commands to calculate stack frame pointer
- @param reg_cmds - map register IDs -> commands to calculate register
- values
+ """Called when stack tracing information retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param address: Start of instruction address range.
+ :type address: |int|
+ :param size: Size of instruction address range.
+ :type size: |int|
+ :param fp_cmds: Commands to calculate stack frame pointer.
+ :type fp_cmds: |list|
+ :param reg_cmds: Map register IDs -> commands to calculate register
+ values.
+ :type reg_cmds: |dict|
"""
pass
diff --git a/python/src/tcf/services/sysmonitor.py b/python/src/tcf/services/sysmonitor.py
index ff8b5a865..cedb24bf1 100644
--- a/python/src/tcf/services/sysmonitor.py
+++ b/python/src/tcf/services/sysmonitor.py
@@ -9,187 +9,293 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-This is an optional service that can be implemented by a peer.
+"""This is an optional service that can be implemented by a peer.
+
If implemented, the service can be used for monitoring system activity and
utilization.
+
It provides list of running processes, different process attributes like
-command line, environment, etc.,
-and some resource utilization data. The service can be used by a client to
-provide functionality
-similar to Unix 'top' utility or Windows 'Task Manager'.
+command line, environment, etc., and some resource utilization data.
+
+The service can be used by a client to provide functionality similar to Unix
+**top** utility or Windows **Task Manager**.
+
+.. |getChildren| replace:: :meth:`~SysMonitorService.getChildren`
+.. |getCommandLine| replace:: :meth:`~SysMonitorService.getCommandLine`
+.. |getContext| replace:: :meth:`~SysMonitorService.getContext`
+.. |getEnvironment| replace:: :meth:`~SysMonitorService.getEnvironment`
+.. |getProperties| replace:: :meth:`SysMonitorContext.getProperties`
+.. |DoneGetChildren| replace:: :class:`DoneGetChildren`
+.. |DoneGetCommandLine| replace:: :class:`DoneGetCommandLine`
+.. |DoneGetContext| replace:: :class:`DoneGetContext`
+.. |DoneGetEnvironment| replace:: :class:`DoneGetEnvironment`
+.. |SysMonitorContext| replace:: :class:`SysMonitorContext`
+
+Properties
+----------
+System Monitor Context Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. seealso:: |SysMonitorContext|, |getProperties|
+
++------------------+--------------+-------------------------------------------+
+| Name | Type | Description |
++==================+==============+===========================================+
+| PROP_CMAJFLT | |int| | The number of major faults that the |
+| | | process's waited-for children have made.|
++------------------+--------------+-------------------------------------------+
+| PROP_CMINFLT | |int| | The number of minor faults that the |
+| | | process's waited-for children have made. |
++------------------+--------------+-------------------------------------------+
+| PROP_CNSWAP | |int| | Cumulative NSwap for child processes. |
++------------------+--------------+-------------------------------------------+
+| PROP_CODEEND | |int| | The address below which program text can |
+| | | run. |
++------------------+--------------+-------------------------------------------+
+| PROP_CODESTART | |int| | The address above which program text can |
+| | | run. |
++------------------+--------------+-------------------------------------------+
+| PROP_CSTIME | |int| | The number of jiffies that this process's |
+| | | waited-for children have been scheduled in|
+| | | user mode. |
++------------------+--------------+-------------------------------------------+
+| PROP_CUTIME | |int| | The number of jiffies that this process's |
+| | | waited-for children have been scheduled in|
+| | | user mode. |
++------------------+--------------+-------------------------------------------+
+| PROP_CWD | |basestring| | Current working directory of the process. |
++------------------+--------------+-------------------------------------------+
+| PROP_EXITSIGNAL | |int| | Signal to be sent to parent when this |
+| | | process exits. |
++------------------+--------------+-------------------------------------------+
+| PROP_FILE | |basestring| | Executable file of the process. |
++------------------+--------------+-------------------------------------------+
+| PROP_FLAGS | |int| | The kernel flags word of the process. |
+| | | Details depend on the kernel. |
++------------------+--------------+-------------------------------------------+
+| PROP_GROUPNAME | |basestring| | Group name of the process owner. |
++------------------+--------------+-------------------------------------------+
+| PROP_ID | |basestring| | The TCF context ID. |
++------------------+--------------+-------------------------------------------+
+| PROP_ITREALVALUE | |int| | The time in milliseconds before the next |
+| | | ``SIGALRM`` is sent to the process due |
+| | | to an interval timer. |
++------------------+--------------+-------------------------------------------+
+| PROP_MAJFLT | |int| | The number of major faults the process has|
+| | | made which have required loading a memory |
+| | | page from disk. |
++------------------+--------------+-------------------------------------------+
+| PROP_MINFLT | |int| | The number of minor faults the process has|
+| | | made which have not required loading a |
+| | | memory page from disk. |
++------------------+--------------+-------------------------------------------+
+| PROP_NICE | |int| | The nice value. |
++------------------+--------------+-------------------------------------------+
+| PROP_NSWAP | |int| | Number of pages swapped. |
++------------------+--------------+-------------------------------------------+
+| PROP_PARENTID | |basestring| | The TCF parent context ID. |
++------------------+--------------+-------------------------------------------+
+| PROP_PGRP | |int| | The process group ID of the process. |
++------------------+--------------+-------------------------------------------+
+| PROP_PID | |int| | System process ID. |
++------------------+--------------+-------------------------------------------+
+| PROP_POLICY | |basestring| | Scheduling policy. |
++------------------+--------------+-------------------------------------------+
+| PROP_PPID | |int| | System ID of the parent process. |
++------------------+--------------+-------------------------------------------+
+| PROP_PRIORITY | |int| | The standard nice value. |
++------------------+--------------+-------------------------------------------+
+| PROP_PROCESSOR | |int| | CPU number last executed on. |
++------------------+--------------+-------------------------------------------+
+| PROP_PSIZE | |int| | Memory pages size in bytes. |
++------------------+--------------+-------------------------------------------+
+| PROP_RLIMIT | |int| | Current limit in bytes on the rss of the |
+| | | process. |
++------------------+--------------+-------------------------------------------+
+| PROP_ROOT | |basestring| | The process's root directory (as set by |
+| | | **chroot**). |
++------------------+--------------+-------------------------------------------+
+| PROP_RSS | |int| | Resident Set Size: number of pages the |
+| | | process has in real memory, minus used for|
+| | | administrative purposes. This is just the |
+| | | pages which count towards text, data, or |
+| | | stack space. This does not include pages |
+| | | which have not been demand-loaded in, or |
+| | | which are swapped out. |
++------------------+--------------+-------------------------------------------+
+| PROP_RTPRIORITY | |int| | Real-time scheduling priority. |
++------------------+--------------+-------------------------------------------+
+| PROP_SESSION | |int| | The session ID of the process. |
++------------------+--------------+-------------------------------------------+
+| PROP_SIGBLOCK | |int| | The bitmap of blocked signals. |
++------------------+--------------+-------------------------------------------+
+| PROP_SIGCATCH | |int| | The bitmap of caught signals. |
++------------------+--------------+-------------------------------------------+
+| PROP_SIGIGNORE | |int| | The bitmap of ignored signals. |
++------------------+--------------+-------------------------------------------+
+| PROP_SIGNALS | |int| | The bitmap of pending signals. |
++------------------+--------------+-------------------------------------------+
+| PROP_STACKSTART | |int| | The address of the start of the stack. |
++------------------+--------------+-------------------------------------------+
+| PROP_STARTTIME | |int| | The time in milliseconds the process |
+| | | started after system boot. |
++------------------+--------------+-------------------------------------------+
+| PROP_STATE | |basestring| | One character from the string ``RSDZTW`` |
+| | | where : |
+| | | |
+| | | - **R** is running. |
+| | | - **S** is sleeping in an |
+| | | interruptible wait. |
+| | | - **D** is waiting in uninterruptible |
+| | | disk sleep. |
+| | | - **Z** is zombie. |
+| | | - **T** is traced or stopped (on a |
+| | | signal). |
+| | | - **W** is paging. |
++------------------+--------------+-------------------------------------------+
+| PROP_STIME | |int| | The number of milliseconds that this |
+| | | process has been scheduled in kernel mode.|
++------------------+--------------+-------------------------------------------+
+| PROP_TGID | |int| | The process group ID of the process which |
+| | | currently owns the tty that the process is|
+| | | connected to. |
++------------------+--------------+-------------------------------------------+
+| PROP_TRACERPID | |int| | ID of a process that has attached this |
+| | | process for tracing or debugging. |
++------------------+--------------+-------------------------------------------+
+| PROP_TTY | |int| | The tty the process uses. |
++------------------+--------------+-------------------------------------------+
+| PROP_UGID | |int| | Group ID of the process owner. |
++------------------+--------------+-------------------------------------------+
+| PROP_UID | |int| | User ID of the process owner. |
++------------------+--------------+-------------------------------------------+
+| PROP_USERNAME | |basestring| | User name of the process owner. |
++------------------+--------------+-------------------------------------------+
+| PROP_UTIME | |int| | The number of milliseconds that this |
+| | | process has been scheduled in user mode. |
++------------------+--------------+-------------------------------------------+
+| PROP_VSIZE | |int| | Virtual memory size in bytes. |
++------------------+--------------+-------------------------------------------+
+| PROP_WCHAN | |int| | This is the *channel* in which the process|
+| | | is waiting. It is the address of a system |
+| | | call, and can be looked up in a name list |
+| | | if you need a textual name. |
++------------------+--------------+-------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: SysMonitorService
+
+getChildren
+^^^^^^^^^^^
+.. automethod:: SysMonitorService.getChildren
+
+getCommandLine
+^^^^^^^^^^^^^^
+.. automethod:: SysMonitorService.getCommandLine
+
+getContext
+^^^^^^^^^^
+.. automethod:: SysMonitorService.getContext
+
+getEnvironment
+^^^^^^^^^^^^^^
+.. automethod:: SysMonitorService.getEnvironment
+
+getName
+^^^^^^^
+.. automethod:: SysMonitorService.getName
+
+Callback Classes
+----------------
+DoneGetChildren
+^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetChildren
+ :members:
+
+DoneGetCommandLine
+^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetCommandLine
+ :members:
+
+DoneGetContext
+^^^^^^^^^^^^^^
+.. autoclass:: DoneGetContext
+ :members:
+
+DoneGetEnvironment
+^^^^^^^^^^^^^^^^^^
+.. autoclass:: DoneGetEnvironment
+ :members:
+
+Helper Classes
+--------------
+SysMonitorContext
+^^^^^^^^^^^^^^^^^
+.. autoclass:: SysMonitorContext
+ :members:
"""
from .. import services
NAME = "SysMonitor"
+"""SysMonitor service name."""
# Context property names.
-# The TCF context ID"""
PROP_ID = "ID"
-
-# The TCF parent context ID
PROP_PARENTID = "ParentID"
-
-# Current working directory of the process
PROP_CWD = "CWD"
-
-# The process's root directory (as set by chroot)
PROP_ROOT = "Root"
-
-# User ID of the process owner
PROP_UID = "UID"
-
-# Group ID of the process owner
PROP_UGID = "UGID"
-
-# User name of the process owner
PROP_USERNAME = "UserName"
-
-# Group name of the process owner
PROP_GROUPNAME = "GroupName"
-
-# System process ID
PROP_PID = "PID"
-
-# Executable file of the process
PROP_FILE = "File"
-
-# One character from the string "RSDZTW" where R is running, S is
-# sleeping in an interruptible wait, D is waiting in uninterruptible
-# disk sleep, Z is zombie, T is traced or stopped (on a signal), and W
-# is paging.
PROP_STATE = "State"
-
-# System ID of the parent process
PROP_PPID = "PPID"
-
-# The process group ID of the process
PROP_PGRP = "PGRP"
-
-# The session ID of the process
PROP_SESSION = "Session"
-
-# The tty the process uses
PROP_TTY = "TTY"
-
-# The process group ID of the process which currently owns the tty that
-# the process is connected to.
PROP_TGID = "TGID"
-
-# ID of a process that has attached this process for tracing or debugging
PROP_TRACERPID = "TracerPID"
-
-# The kernel flags word of the process. Details depend on the kernel
PROP_FLAGS = "Flags"
-
-# The number of minor faults the process has made which have not
-# required loading a memory page from disk
PROP_MINFLT = "MinFlt"
-
-# The number of minor faults that the process's waited-for children have
-# made
PROP_CMINFLT = "CMinFlt"
-
-# The number of major faults the process has made which have required
-# loading a memory page from disk
PROP_MAJFLT = "MajFlt"
-
-# The number of major faults that the process's waited-for children
-# have made
PROP_CMAJFLT = "CMajFlt"
-
-# The number of milliseconds that this process has been scheduled in user mode
PROP_UTIME = "UTime"
-
-# The number of milliseconds that this process has been scheduled in kernel
-# mode
PROP_STIME = "STime"
-
-# The number of jiffies that this process's waited-for children have
-# been scheduled in user mode
PROP_CUTIME = "CUTime"
-
-# The number of jiffies that this process's waited-for children have
-# been scheduled in user mode
PROP_CSTIME = "CSTime"
-
-# The standard nice value
PROP_PRIORITY = "Priority"
-
-# The nice value
PROP_NICE = "Nice"
-
-# The time in milliseconds before the next SIGALRM is sent to the process
-# due to an interval timer
PROP_ITREALVALUE = "ITRealValue"
-
-# The time in milliseconds the process started after system boot
PROP_STARTTIME = "StartTime"
-
-# Virtual memory size in bytes
PROP_VSIZE = "VSize"
-
-# Memory pages size in bytes
PROP_PSIZE = "PSize"
-
-# Resident Set Size: number of pages the process has in real memory,
-# minus used for administrative purposes. This is just the pages which
-# count towards text, data, or stack space. This does not include
-# pages which have not been demand-loaded in, or which are swapped out
PROP_RSS = "RSS"
-
-# Current limit in bytes on the rss of the process
PROP_RLIMIT = "RLimit"
-
-# The address above which program text can run
PROP_CODESTART = "CodeStart"
-
-# The address below which program text can run
PROP_CODEEND = "CodeEnd"
-
-# The address of the start of the stack
PROP_STACKSTART = "StackStart"
-
-# The bitmap of pending signals
PROP_SIGNALS = "Signals"
-
-# The bitmap of blocked signals
PROP_SIGBLOCK = "SigBlock"
-
-# The bitmap of ignored signals
PROP_SIGIGNORE = "SigIgnore"
-
-# The bitmap of caught signals
PROP_SIGCATCH = "SigCatch"
-
-# This is the "channel" in which the process is waiting. It is the
-# address of a system call, and can be looked up in a name list if you
-# need a textual name
PROP_WCHAN = "WChan"
-
-# Number of pages swapped
PROP_NSWAP = "NSwap"
-
-# Cumulative NSwap for child processes
PROP_CNSWAP = "CNSwap"
-
-# Signal to be sent to parent when this process exits
PROP_EXITSIGNAL = "ExitSignal"
-
-# CPU number last executed on
PROP_PROCESSOR = "Processor"
-
-# Real-time scheduling priority
PROP_RTPRIORITY = "RTPriority"
-
-# Scheduling policy
PROP_POLICY = "Policy"
class SysMonitorContext(object):
- """
- A context corresponds to an execution thread, process, address space, etc.
+ """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
@@ -197,6 +303,10 @@ class SysMonitorContext(object):
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 props: The properties to initialise this system monitor context
+ with. See `System Monitor Context Properties`_.
+ :type props: |dict|
"""
def __init__(self, props):
self._props = props or {}
@@ -205,209 +315,276 @@ class SysMonitorContext(object):
return "[Sys Monitor Context %s]" % self._props
def getID(self):
+ """Get TCF context ID.
+
+ :returns: A |basestring| representing this context TCF ID.
"""
- Get context ID.
- Same as getProperties().get("ID")
- """
- return self._props.get(PROP_ID)
+ return self._props.get(PROP_ID, '')
def getParentID(self):
+ """Get parent context ID.
+
+ :returns: A |basestring| representing this context parent TCF ID.
"""
- Get parent context ID.
- Same as getProperties().get("ParentID")
- """
- return self._props.get(PROP_PARENTID)
+ return self._props.get(PROP_PARENTID, '')
def getPGRP(self):
- """
- Get process group ID.
- Same as getProperties().get("PGRP")
+ """Get process group ID.
+
+ :returns: An |int| representing this context process group ID, or
+ **-1** if it is not known.
"""
return self._props.get(PROP_PGRP, -1)
def getPID(self):
- """
- Get process ID.
- Same as getProperties().get("PID")
+ """Get process ID.
+
+ :returns: An |int| representing this context process ID, or
+ **-1** if it is not known.
"""
return self._props.get(PROP_PID, -1)
def getPPID(self):
- """
- Get process parent ID.
- Same as getProperties().get("PPID")
+ """Get process parent ID.
+
+ :returns: An |int| representing this context parent process ID, or
+ **-1** if it is not known.
"""
return self._props.get(PROP_PPID, -1)
def getTGID(self):
- """
- Get process TTY group ID.
- Same as getProperties().get("TGID")
+ """Get process TTY group ID.
+
+ :returns: An |int| representing this context process TTY group ID, or
+ **-1** if it is not known.
"""
return self._props.get(PROP_TGID, -1)
def getTracerPID(self):
- """
- Get tracer process ID.
- Same as getProperties().get("TracerPID")
+ """Get tracer process ID.
+
+ :returns: An |int| representing this context tracer process ID, or
+ **-1** if it is not known.
"""
return self._props.get(PROP_TRACERPID, -1)
def getUID(self):
- """
- Get process owner user ID.
- Same as getProperties().get("UID")
+ """Get process owner user ID.
+
+ :returns: An |int| representing this context process owner user ID, or
+ **-1** if it is not known.
"""
return self._props.get(PROP_UID, -1)
def getUserName(self):
+ """Get process owner user name.
+
+ :returns: A |basestring| representing this context process owner user
+ name, or an empty string if it is not known.
"""
- Get process owner user name.
- Same as getProperties().get("UserName")
- """
- return self._props.get(PROP_USERNAME)
+ return self._props.get(PROP_USERNAME, '')
def getUGID(self):
- """
- Get process owner user group ID.
- Same as getProperties().get("UGID")
+ """Get process owner user group ID.
+
+ :returns: An |int| representing this context process owner user group
+ ID, or **-1** if it is not known.
"""
return self._props.get(PROP_UGID, -1)
def getGroupName(self):
+ """Get process owner user group name.
+
+ :returns: A |basestring| representing this context process owner user
+ group name, or an empty string if it is not known.
"""
- Get process owner user group name.
- Same as getProperties().get("GroupName")
- """
- return self._props.get(PROP_GROUPNAME)
+ return self._props.get(PROP_GROUPNAME, '')
def getState(self):
+ """Get process state.
+
+ :returns: A |basestring| representing this context process state, or
+ an empty string if it is not known.
"""
- Get process state.
- Same as getProperties().get("State")
- """
- return self._props.get(PROP_STATE)
+ return self._props.get(PROP_STATE, '')
def getVSize(self):
- """
- Get process virtual memory size in bytes.
- Same as getProperties().get("VSize")
+ """Get process virtual memory size in bytes.
+
+ :returns: An |int| representing this context process virtual memory
+ size in bytes, or **-1** if it is not known.
"""
return self._props.get(PROP_VSIZE, -1)
def getPSize(self):
- """
- Get process virtual memory page size in bytes.
- Same as getProperties().get("PSize")
+ """Get process virtual memory page size in bytes.
+
+ :returns: An |int| representing this context process virtual memory
+ page size in bytes, or **-1** if it is not known.
"""
return self._props.get(PROP_PSIZE, -1)
def getRSS(self):
- """
- Get number of memory pages in process resident set.
- Same as getProperties().get("RSS")
+ """Get number of memory pages in process resident set.
+
+ :returns: An |int| representing this context number of memory pages in
+ process resident set, or **-1** if it is not known.
"""
return self._props.get(PROP_RSS, -1)
def getFile(self):
+ """Get context executable file.
+
+ :returns: A |basestring| representing this context executable file, or
+ an empty string if it is not known.
"""
- Get context executable file.
- Same as getProperties().get("File")
- """
- return self._props.get(PROP_FILE)
+ return self._props.get(PROP_FILE, '')
def getRoot(self):
+ """Get context current file system root.
+
+ :returns: A |basestring| representing this context current file system
+ root, or an empty string if it is not known.
"""
- Get context current file system root.
- Same as getProperties().get("Root")
- """
- return self._props.get(PROP_ROOT)
+ return self._props.get(PROP_ROOT, '')
def getCurrentWorkingDirectory(self):
+ """Get context current working directory.
+
+ :returns: A |basestring| representing this context current working
+ directory, or an empty string if it is not known.
"""
- Get context current working directory.
- Same as getProperties().get("CWD")
- """
- return self._props.get(PROP_CWD)
+ return self._props.get(PROP_CWD, '')
def getProperties(self):
- """
- Get all available context properties.
- @return Map 'property name' -> 'property value'
+ """Get all available context properties.
+
+ :returns: A |dict| of properties definit this system monitor context.
+
+ .. seealso:: `System Monitor Context Properties`_
"""
return self._props
class SysMonitorService(services.Service):
+ """System monitor service interface."""
+
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.
+ """Retrieve context info for given context ID.
+
+ :param contextID: TCF context ID.
+ :type contextID: |basestring|
+ :param done: Callback interface called when operation is completed.
+ :type done: |DoneGetContext|
- @param contextID - context ID.
- @param done - callback interface called when operation is completed.
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getChildren(self, parent_context_id, done):
- """
- Retrieve children of given context.
+ """Retrieve children of given context.
+
+ :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
+ |getContext| or |getChildren| methods.
+ :type parent_context_id: |basestring| or **None**
+ :param done: callback interface called when operation is completed
+ :type done: |DoneGetChildren|
- @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 getContext or getChildren commands.
- @param done - callback interface called when operation is completed.
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getCommandLine(self, contextID, done):
- """
- Get context command line.
+ """Get context command line.
+
+ :param contextID: ID of the context to get command line for.
+ :type contextID: |basestring|
+ :param done: Callback interface called when operation is completed.
+ :type done: |DoneGetCommandLine|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def getEnvironment(self, contextID, done):
- """
- Get context environment variables.
+ """Get context environment variables.
+
+ :param contextID: ID of the context to get environment for.
+ :type contextID: |basestring|
+ :param done: Callback interface called when operation is completed.
+ :type done: |DoneGetEnvironment|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
class DoneGetContext(object):
- """
- Client callback interface for getContext().
- """
+ """Client callback 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 context data retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context: Retrieved context data.
+ :type context: |SysMonitorContext|
"""
pass
class DoneGetChildren(object):
- """
- Client callback interface for getChildren().
- """
+ """Client callback 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 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|
"""
pass
class DoneGetCommandLine(object):
+ """Client callback interface for |getCommandLine|."""
+
def doneGetCommandLine(self, token, error, cmd_line):
+ """Called when command line retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param cmd_line: A list of |basestring| representing this context
+ command line.
+ :type cmd_line: |list|
+ """
pass
class DoneGetEnvironment(object):
+ """Client callback interface for |getEnvironment|."""
+
def doneGetEnvironment(self, token, error, environment):
+ """Called when environment retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param environment: A |dict| of context environment variables.
+ :type environment: |dict|
+ """
pass
diff --git a/python/src/tcf/services/terminals.py b/python/src/tcf/services/terminals.py
index e662fd006..917b16008 100644
--- a/python/src/tcf/services/terminals.py
+++ b/python/src/tcf/services/terminals.py
@@ -9,45 +9,142 @@
# * Wind River Systems - initial API and implementation
# *****************************************************************************
-"""
-ITerminalsService allows to launch a new terminal on the remote target system.
+"""Terminals Service allows to launch a new terminal on the remote target
+system.
+
+.. |addListener| replace:: :meth:`TerminalsService.addListener`
+.. |exit| replace:: :meth:`TerminalsService.exit`
+.. |getContext| replace:: :meth:`TerminalsService.getContext`
+.. |getProperties| replace:: :meth:`TerminalContext.getProperties`
+.. |launch| replace:: :meth:`TerminalsService.launch`
+.. |removeListener| replace:: :meth:`TerminalsService.removeListener`
+.. |setWinSize| replace:: :meth:`TerminalsService.setWinSize`
+.. |memory| replace:: :mod:`tcf.services.memory`
+.. |streams| replace:: :mod:`tcf.services.streams`
+.. |DoneCommand| replace:: :class:`DoneCommand`
+.. |DoneGetContext| replace:: :class:`DoneGetContext`
+.. |DoneLaunch| replace:: :class:`DoneLaunch`
+.. |TerminalContext| replace:: :class:`TerminalContext`
+.. |TerminalsListener| replace:: :class:`TerminalsListener`
+
+Terminals service provides access to the target OS's terminal login, allows to
+start and exit a terminal login, and allows to set the terminal's window size.
+
+If a terminal is launched by this service, its standard input/output streams
+are available for client to read/write using |streams| service. Stream type of
+such streams is set to ``Terminals``.
+
+Properties
+----------
+Terminal Context Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. seealso:: |TerminalContext|, |getProperties|
+
++-----------------+--------------+--------------------------------------------+
+| Name | Type | Description |
++=================+==============+============================================+
+| PROP_ENCODING | |basestring| | Terminal encoding. |
++-----------------+--------------+--------------------------------------------+
+| PROP_HEIGHT | |int| | Window height size. |
++-----------------+--------------+--------------------------------------------+
+| PROP_ID | |basestring| | The TCF context ID. |
++-----------------+--------------+--------------------------------------------+
+| PROP_PROCESS_ID | |int| | The process ID of the login process of the |
+| | | terminal. |
++-----------------+--------------+--------------------------------------------+
+| PROP_PTY_TYPE | |basestring| | The PTY type. |
++-----------------+--------------+--------------------------------------------+
+| PROP_STDERR_ID | |basestring| | Process standard error stream ID. |
++-----------------+--------------+--------------------------------------------+
+| PROP_STDIN_ID | |basestring| | Process standard input stream ID. |
++-----------------+--------------+--------------------------------------------+
+| PROP_STDOUT_ID | |basestring| | Process standard output stream ID. |
++-----------------+--------------+--------------------------------------------+
+| PROP_WIDTH | |int| | Window width size. |
++-----------------+--------------+--------------------------------------------+
+
+Service Methods
+---------------
+.. autodata:: NAME
+.. autoclass:: TerminalsService
+
+addListener
+^^^^^^^^^^^
+.. automethod:: TerminalsService.addListener
+
+exit
+^^^^
+.. automethod:: TerminalsService.exit
+
+getContext
+^^^^^^^^^^
+.. automethod:: TerminalsService.getContext
+
+getName
+^^^^^^^
+.. automethod:: TerminalsService.getName
+
+launch
+^^^^^^
+.. automethod:: TerminalsService.launch
+
+removeListener
+^^^^^^^^^^^^^^
+.. automethod:: TerminalsService.removeListener
+
+setWinSize
+^^^^^^^^^^
+.. automethod:: TerminalsService.setWinSize
+
+Callback Classes
+----------------
+DoneCommand
+^^^^^^^^^^^
+.. autoclass:: DoneCommand
+ :members:
+
+DoneGetContext
+^^^^^^^^^^^^^^
+.. autoclass:: DoneGetContext
+ :members:
+
+DoneLaunch
+^^^^^^^^^^
+.. autoclass:: DoneLaunch
+ :members:
+
+Listener
+--------
+.. autoclass:: TerminalsListener
+ :members:
+
+Helper Classes
+--------------
+TerminalContext
+^^^^^^^^^^^^^^^
+.. autoclass:: TerminalContext
+ :members:
"""
from .. import services
-# This service name, as it appears on the wire - a TCF name of the service.
NAME = "Terminals"
+"""Terminals service name."""
# Context property names.
-# The TCF context ID
PROP_ID = "ID"
-
-# The process ID of the login process of the terminal
PROP_PROCESS_ID = "ProcessID"
-
-# The PTY type
PROP_PTY_TYPE = "PtyType"
-
-# terminal encoding
PROP_ENCODING = "Encoding"
-
-# window width size
PROP_WIDTH = "Width"
-
-# window height size
PROP_HEIGHT = "Height"
-
-# Process standard input stream ID
PROP_STDIN_ID = "StdInID"
-
-# Process standard output stream ID
PROP_STDOUT_ID = "StdOutID"
-
-# Process standard error stream ID
PROP_STDERR_ID = "StdErrID"
class TerminalContext(object):
+ """Terminal context object."""
def __init__(self, props):
self._props = props or {}
@@ -56,196 +153,277 @@ class TerminalContext(object):
return "[Terminals Context %s]" % str(self._props)
def getID(self):
+ """Get context ID.
+
+ :returns: A |basestring| representing the TCF ID of this terminal, or
+ an empty string if it is not known.
"""
- Get context ID.
- Same as getProperties().get("ID")
- """
- return self._props.get(PROP_ID)
+ return self._props.get(PROP_ID, '')
def getProcessID(self):
+ """Get process ID of the login process of the terminal.
+
+ :returns: A |basestring| representing the process ID of this terminal,
+ or an empty string if it is not known.
"""
- Get process ID of the login process of the terminal.
- Same as getProperties().get("ProcessID")
- """
- return self._props.get(PROP_PROCESS_ID)
+ return self._props.get(PROP_PROCESS_ID, '')
def getPtyType(self):
+ """Get terminal PTY type.
+
+ :returns: A |basestring| representing the PTY type of this terminal, or
+ an empty string if it is not known.
"""
- Get terminal type.
- Same as getProperties().get("PtyType")
- """
- return self._props.get(PROP_PTY_TYPE)
+ return self._props.get(PROP_PTY_TYPE, '')
def getEncoding(self):
+ """Get terminal encoding.
+
+ :returns: A |basestring| representing the encoding of this terminal, or
+ an empty string if it is not known.
"""
- Get encoding.
- Same as getProperties().get("Encoding")
- """
- return self._props.get(PROP_ENCODING)
+ return self._props.get(PROP_ENCODING, '')
def getWidth(self):
+ """Get terminal width.
+
+ Terminal width is the number of characters printable on one line in the
+ terminal.
+
+ :returns: An |int| representing the width of this terminal, or **0**
+ if it is not known.
"""
- Get width.
- Same as getProperties().get("Width")
- """
- return self._props.get(PROP_WIDTH)
+ return self._props.get(PROP_WIDTH, 0)
def getHeight(self):
+ """Get Terminal height.
+
+ Terminal height is the number of lines printable in the terminal.
+
+ :returns: An |int| representing the height of this terminal, or **0**
+ if it is not known.
"""
- Get height.
- Same as getProperties().get("Height")
- """
- return self._props.get(PROP_HEIGHT)
+ return self._props.get(PROP_HEIGHT, 0)
def getStdErrID(self):
+ """Get standard error stream ID of the terminal.
+
+ :returns: A |basestring| representing the standard error stream ID of
+ this terminal, or an empty string if it is not known.
"""
- Get standard error stream ID of the terminal.
- Same as getProperties().get("StdErrID")
- """
- return self._props.get(PROP_STDERR_ID)
+ return self._props.get(PROP_STDERR_ID, '')
def getStdInID(self):
+ """Get standard input stream ID of the terminal.
+
+ :returns: A |basestring| representing the standard input stream ID of
+ this terminal, or an empty string if it is not known.
"""
- Get standard input stream ID of the terminal.
- Same as getProperties().get("StdInID")
- """
- return self._props.get(PROP_STDIN_ID)
+ return self._props.get(PROP_STDIN_ID, '')
def getStdOutID(self):
+ """Get standard output stream ID of the terminal.
+
+ :returns: A |basestring| representing the standard output stream ID of
+ this terminal, or an empty string if it is not known.
"""
- Get standard output stream ID of the terminal.
- Same as getProperties().get("StdOutID")
- """
- return self._props.get(PROP_STDOUT_ID)
+ return self._props.get(PROP_STDOUT_ID, '')
def getProperties(self):
- """
- Get all available context properties.
- @return Map 'property name' -> 'property value'
+ """Get all available context properties.
+
+ :returns: A |dict| of properties definit this system monitor context.
+
+ .. seealso:: `Terminal Context Properties`_
"""
return self._props
def exit(self, done): # @ReservedAssignment
- """
- Exit the terminal.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Exit the terminal.
+
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
class TerminalsService(services.Service):
+ """TCF terminals service interface"""
+
def getName(self):
- return NAME
+ """Get this service name.
- def getContext(self, id, done): # @ReservedAssignment
+ :returns: A |basestring| representing this service name, which is the
+ value of :const:`NAME`
"""
- Retrieve context info for given context ID.
+ return NAME
+
+ def getContext(self, contextID, done):
+ """Retrieve context info for given context ID.
+
A context corresponds to an terminal.
+
Context IDs are valid across TCF services, so it is allowed to issue
- 'ITerminals.getContext' command with a context that was obtained,
- for example, from Memory service.
- However, 'ITerminals.getContext' is supposed to return only terminal
- specific data, if the ID is not a terminal ID, 'ITerminals.getContext'
- may not return any useful information
+ |getContext| command with a context that was obtained, for example,
+ from |memory| service.
+
+ However, |getContext| is supposed to return only terminal specific
+ data, if the ID is not a terminal ID,|getContext| may not return any
+ useful information
+
+ :param contextID: TCF ID of the terminal context to get.
+ :type contextID: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneGetContext|
- @param id - context ID.
- @param done - call back interface called when operation is completed.
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
- def launch(self, type, encoding, environment, done): # @ReservedAssignment
- """
- Launch a new terminal to remote machine.
- @param type - requested terminal type for the new terminal.
- @param encoding - requested encoding for the new terminal.
- @param environment - Array of environment variable strings.
- if None then default set of environment variables will be used.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ def launch(self, termType, encoding, environment, done):
+ """Launch a new terminal to remote machine.
+
+ :param termType: Requested terminal type for the new terminal.
+ :type termType: |basestring| or **None**
+ :param encoding: Requested encoding for the new terminal.
+ :type encoding: |basestring| or **None**
+ :param environment: Array of environment variable strings. If **None**
+ then default set of environment variables will be
+ used.
+ :type environment: |dict|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneLaunch|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def setWinSize(self, context_id, newWidth, newHeight, done):
- """
- Set the terminal widows size
- @param context_id - context ID.
- @param signal - signal code.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Set the terminal windows size.
+
+ :param context_id: TCF ID of the terminal to set size for.
+ :type context_id: |basestring|
+ :param newWidth: New terminal width.
+ :type newWidth: |int|
+ :param newHeight: New terminal height.
+ :type newHeight: |int|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def exit(self, context_id, done): # @ReservedAssignment
- """
- Exit a terminal.
- @param context_id - context ID.
- @param done - call back interface called when operation is completed.
- @return pending command handle, can be used to cancel the command.
+ """Exit a terminal.
+
+ :param context_id: TCF ID of the terminal to terminate.
+ :type context_id: |basestring|
+ :param done: Call back interface called when operation is completed.
+ :type done: |DoneCommand|
+
+ :returns: Pending command handle, can be used to cancel the command.
"""
raise NotImplementedError("Abstract method")
def addListener(self, listener):
- """
- Add terminals service event listener.
- @param listener - event listener implementation.
+ """Add terminals service event listener.
+
+ :param listener: Terminal event listener implementation to add to
+ channel.
+ :type listener: |TerminalsListener|
+
+ :returns: **None**, always.
"""
raise NotImplementedError("Abstract method")
def removeListener(self, listener):
- """
- Remove terminals service event listener.
- @param listener - event listener implementation.
+ """Remove terminals service event listener.
+
+ :param listener: Terminal event listener implementation to remove from
+ channel.
+ :type listener: |TerminalsListener|
+
+ :returns: **None**, always.
"""
raise NotImplementedError("Abstract method")
class DoneGetContext(object):
- """
- Client call back interface for getContext().
- """
+ """Client call back interface for |getContext|."""
+
def doneGetContext(self, token, error, context):
- """
- Called when contexts data retrieval is done.
- @param error - error description if operation failed, None if
- succeeded.
- @param context - context data.
+ """Called when contexts data retrieval is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param context: Retrieved context data.
+ :type context: |TerminalContext| or **None**
"""
pass
class DoneCommand(object):
+ """Client call back interface for |exit| or |setWinSize|."""
+
def doneCommand(self, token, error):
+ """Called when command is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ """
pass
class DoneLaunch(object):
- """
- Call-back interface to be called when "start" command is complete.
- """
+ """Client call back interface for |launch|."""
+
def doneLaunch(self, token, error, terminal):
+ """Called when terminal launch is done.
+
+ :param token: Pending command handle.
+ :param error: Error description if operation failed, **None** if
+ succeeded.
+ :param terminal: Started terminal context.
+ :type terminal: |TerminalContext|
+ """
pass
class TerminalsListener(object):
- """
- Process event listener is notified when a terminal exits.
- Event are reported only for terminals that were started by 'launch'
+ """Terminals event listener is notified when a terminal exits or is
+ resized.
+
+ Events are reported only for terminals that were started by |launch|
command.
"""
+
def exited(self, terminal_id, exit_code):
- """
- Called when a terminal exits.
- @param terminal_id - terminal context ID
- @param exit_code - terminal exit code
+ """Called when a terminal exits.
+
+ :param terminal_id: TCF ID of the exited terminal.
+ :type terminal_id: |basestring|
+ :param exit_code: Terminal exit code.
+ :type exit_code: |int|
+
+ :returns: **None**, always.
"""
pass
def winSizeChanged(self, terminal_id, newWidth, newHeight):
- """
- Called when a terminal exits.
- @param terminal_id - terminal context ID
- @param newWidth - new terminal width
- @param newHeight - new terminal height
+ """Called when a terminal has been resized.
+
+ :param terminal_id: TCF ID of the resized terminal.
+ :type terminal_id: |basestring|
+ :param newWidth: New terminal width.
+ :type newWidth: |int|
+ :param newHeight: New terminal height.
+ :type newHeight: |int|
+
+ :returns: **None**, always.
"""
pass

Back to the top