aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChristophe Augier2012-07-22 13:59:49 (EDT)
committerEugene Tarassov2012-07-25 01:13:48 (EDT)
commitb089ed580637f6a807206411ba25d86d3d1d91ae (patch)
treea0e971613380abae08865ee9605eb51a1836f549
parent8d5acd2d4d08e5699c9daf8827263224a6bf7eea (diff)
downloadorg.eclipse.tcf-b089ed580637f6a807206411ba25d86d3d1d91ae.zip
org.eclipse.tcf-b089ed580637f6a807206411ba25d86d3d1d91ae.tar.gz
org.eclipse.tcf-b089ed580637f6a807206411ba25d86d3d1d91ae.tar.bz2
Documentation: add Memory Map service specification
-rw-r--r--docs/TCF Service - Memory Map.html309
1 files changed, 309 insertions, 0 deletions
diff --git a/docs/TCF Service - Memory Map.html b/docs/TCF Service - Memory Map.html
new file mode 100644
index 0000000..78cc8f0
--- /dev/null
+++ b/docs/TCF Service - Memory Map.html
@@ -0,0 +1,309 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Target Communication Framework Services - Memory Map</title>
+</head>
+
+<body lang='EN-US'>
+
+<h1>Target Communication Framework Services - Memory Map</h1>
+
+<ul>
+ <li><a href='#VersionHistory'>Version History</a>
+ <li><a href='#Overview'>Overview</a>
+ <li><a href='#Cmds'>Commands</a>
+ <ul>
+ <li><a href='#CmdGet'>Get</a>
+ <li><a href='#CmdSet'>Set</a>
+ </ul>
+ <li><a href='#Events'>Events</a>
+ <li><a href='#API'>API</a>
+</ul>
+
+<h1>Memory Service</h1>
+
+<h2><a name='VersionHistory'>Version History</a></h2>
+
+<table border=1 cellpadding=8>
+ <tr>
+ <th>Version
+ <th>Date
+ <th>Change
+ <tr>
+ <td>0.0
+ <td>2012-07-22
+ <td>Initial documentation based on source code
+</table>
+
+<h2><a name='Overview'>Overview</a></h2>
+
+<p>The service provides basic operations to get and set memory mapping on a
+target. Command and event parameters are encoded as zero terminated <a
+href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+
+<p>The service uses standard format for error reports,
+see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+
+<h2><a name='Cmds'>Commands</a></h2>
+
+<h3><a name='CmdGet'>Get</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; MemoryMap &bull; get &bull; <i>&lt;string: context ID&gt;</i> &bull;
+</font></b></pre>
+
+<p>The command retrieves memory maps for given context ID.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull; <i>&lt;array of map items&gt;</i> &bull;
+
+<i>&lt;array of map items&gt;</i>
+ &rArr; null
+ &rArr; [ <i>&lt;map items list&gt;</i> ]
+
+<i>&lt;map items list&gt;</i>
+ &rArr; <i>&lt;object: map item properties&gt;</i>
+ &rArr; <i>&lt;map items list&gt;</i> , <i>&lt;object: map item properties&gt;</i>
+</font></b></pre>
+
+<p>Predefined memory map properties are:</p>
+<ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
+ - Memory region ID.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ContextQuery" : <i>&lt;string&gt;</i></font></b></code>
+ - Memory region context query.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Addr" : <i>&lt;int&gt;</i></font></b></code>
+ - region address in memory.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Size" : <i>&lt;int&gt;</i></font></b></code>
+ - region size.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Offs" : <i>&lt;int&gt;</i></font></b></code>
+ - Region offset in the file.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"BSS" : <i>&lt;boolean&gt;</i></font></b></code>
+ - True if the region represents BSS.
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Flags" : <i>&lt;int&gt;</i></font></b></code>
+ - Region memory protection flags, see predefined flags.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"FileName" : <i>&lt;string&gt;</i></font></b></code>
+ - Name of the file.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"SectionName" : <i>&lt;string&gt;</i></font></b></code>
+ - Name of the object file section.
+
+ <p>Predefined flags are:</p>
+ <ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>1</font></b></code>
+ - Read access is allowed.</li>
+ <li><code><b><font face="Courier New" size=2 color=#333399>2</font></b></code>
+ - Write access is allowed.</li>
+ <li><code><b><font face="Courier New" size=2 color=#333399>4</font></b></code>
+ - Instruction fetch access is allowed.</li>
+ </ul>
+</ul>
+
+<h3><a name='CmdSet'>Set</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; MemoryMap &bull; set &bull; <i>&lt;string: context ID&gt;</i> &bull; <i>&lt;object: map item properties&gt;</i> &bull;
+</font></b></pre>
+
+<p>The command sets a memory mapping for context specified by context ID. Map item object uses the same properties as defined in the get command.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull;
+</font></b></pre>
+
+<h2><a name='Events'>Events</a></h2>
+
+<p>MemoryMap service broadcasts notification events when memory map items are changed.</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+E &bull; MemoryMap &bull; changed &bull; <i>&lt;string: context ID&gt;</i> &bull;
+</font></b></pre>
+
+<h2><a name='API'>API</a></h2>
+
+<pre>
+<font color=#3F5FBF>/**
+ * IMemoryMap service provides information about executable modules (files) mapped (loaded) into target memory.
+ */</font>
+<font color=#7F0055>public interface</font> IMemoryMap <font color=#7F0055>extends</font> IService {
+
+ <font color=#7F0055>static final</font> String NAME = "MemoryMap";
+
+ <font color=#3F5FBF>/**
+ * Memory region property names.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ PROP_ID = "ID", <font color=#3F5FBF>/** String, memory region ID */</font>
+ PROP_CONTEXT_QUERY = "ContextQuery", <font color=#3F5FBF>/** String, memory region context query, see IContextQuery */</font>
+ PROP_ADDRESS = "Addr", <font color=#3F5FBF>/** Number, region address in memory */</font>
+ PROP_SIZE = "Size", <font color=#3F5FBF>/** Number, region size */</font>
+ PROP_OFFSET = "Offs", <font color=#3F5FBF>/** Number, region offset in the file */</font>
+ PROP_BSS = "BSS", <font color=#3F5FBF>/** Boolean, true if the region represents BSS */</font>
+ PROP_FLAGS = "Flags", <font color=#3F5FBF>/** Number, region memory protection flags, see FLAG_* */</font>
+ PROP_FILE_NAME = "FileName", <font color=#3F5FBF>/** String, name of the file */</font>
+ PROP_SECTION_NAME = "SectionName"; <font color=#3F5FBF>/** String, name of the object file section */</font>
+
+ <font color=#3F5FBF>/**
+ * Memory region flags.
+ */</font>
+ <font color=#7F0055>static final</font> int
+ FLAG_READ = 1, <font color=#3F5FBF>/** Read access is allowed */</font>
+ FLAG_WRITE = 2, <font color=#3F5FBF>/** Write access is allowed */</font>
+ FLAG_EXECUTE = 4; <font color=#3F5FBF>/** Instruction fetch access is allowed */</font>
+
+ <font color=#3F5FBF>/**
+ * Memory region interface.
+ */</font>
+ <font color=#7F0055>interface</font> MemoryRegion {
+
+ <font color=#3F5FBF>/**
+ * Get region properties. See PROP_* definitions for property names.
+ * Properties are read only, clients should not try to modify them.
+ * <font color=#7F9FBF>@return</font> Map of region properties.
+ */</font>
+ Map<String,Object> getProperties();
+
+ <font color=#3F5FBF>/**
+ * Get memory region address.
+ * Same as getProperties().get(PROP_ADDRESS)
+ * <font color=#7F9FBF>@return</font> region address.
+ */</font>
+ Number getAddress();
+
+ <font color=#3F5FBF>/**
+ * Get memory region size.
+ * Same as getProperties().get(PROP_SIZE)
+ * <font color=#7F9FBF>@return</font> region size.
+ */</font>
+ Number getSize();
+
+ <font color=#3F5FBF>/**
+ * Get memory region file offset.
+ * Same as getProperties().get(PROP_OFFSET)
+ * <font color=#7F9FBF>@return</font> file offset.
+ */</font>
+ Number getOffset();
+
+ <font color=#3F5FBF>/**
+ * Check if the region represents BSS - data segment containing
+ * statically-allocated variables represented solely by zero-valued bits initially.
+ * Memory for BSS segments is not backed by a file contents.
+ * Same as getProperties().get(PROP_BSS)
+ * <font color=#7F9FBF>@return</font> file offset.
+ */</font>
+ boolean isBSS();
+
+ <font color=#3F5FBF>/**
+ * Get memory region flags.
+ * Same as getProperties().get(PROP_FLAGS)
+ * <font color=#7F9FBF>@return</font> region flags.
+ */</font>
+ int getFlags();
+
+ <font color=#3F5FBF>/**
+ * Get memory region file name.
+ * Same as getProperties().get(PROP_FILE_NAME)
+ * <font color=#7F9FBF>@return</font> file name.
+ */</font>
+ String getFileName();
+
+ <font color=#3F5FBF>/**
+ * Get memory region section name.
+ * Same as getProperties().get(PROP_SECTION_NAME)
+ * <font color=#7F9FBF>@return</font> section name.
+ */</font>
+ String getSectionName();
+
+ <font color=#3F5FBF>/**
+ * Get context query that defines scope of the region, see also IContextQuery.
+ * Same as getProperties().get(PROP_CONTEXT_QUERY)
+ * Only user-defined regions can have a context query property.
+ * <font color=#7F9FBF>@return</font> context query expression, or null.
+ */</font>
+ String getContextQuery();
+ }
+
+ <font color=#3F5FBF>/**
+ * Retrieve memory map for given context ID.
+ *
+ * <font color=#7F9FBF>@param</font> id &ndash; context ID.
+ * <font color=#7F9FBF>@param</font> done &ndash; call back interface called when operation is completed.
+ * <font color=#7F9FBF>@return</font> &ndash; pending command handle.
+ */</font>
+ IToken get(String id, DoneGet done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for get().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGet {
+ /**
+ * Called when memory map data retrieval is done.
+ * <font color=#7F9FBF>@param</font> error &ndash; error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> map &ndash; memory map data.
+ */</font>
+ <font color=#7F0055>void</font> doneGet(IToken token, Exception error, MemoryRegion[] map);
+ }
+
+ <font color=#3F5FBF>/**
+ * Set memory map for given context.
+ * 'id' can be null, in such case scope of each memory region is
+ * defined by its ContextQuery property.
+ *
+ * Using non-null 'id' is deprecated - use ContextQuery instead.
+ *
+ * <font color=#7F9FBF>@param</font> id &ndash; symbols context group ID or name.
+ * <font color=#7F9FBF>@param</font> map &ndash; memory map data.
+ * <font color=#7F9FBF>@param</font> done &ndash; call back interface called when operation is completed.
+ * <font color=#7F9FBF>@return</font> &ndash; pending command handle.
+ */</font>
+ IToken set(String id, MemoryRegion[] map, DoneSet done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for set().
+ */</font>
+ <font color=#7F0055>interface</font> DoneSet {
+ /**
+ * Called when memory map set command is done.
+ * <font color=#7F9FBF>@param</font> error &ndash; error description if operation failed, null if succeeded.
+ */</font>
+ <font color=#7F0055>void</font> doneSet(IToken token, Exception error);
+ }
+
+ <font color=#3F5FBF>/**
+ * Add memory map event listener.
+ * <font color=#7F9FBF>@param</font> listener &ndash; memory map event listener to add.
+ */</font>
+ <font color=#7F0055>void</font> addListener(MemoryMapListener listener);
+
+ <font color=#3F5FBF>/**
+ * Remove memory map event listener.
+ * <font color=#7F9FBF>@param</font> listener &ndash; memory map event listener to remove.
+ */</font>
+ <font color=#7F0055>void</font> removeListener(MemoryMapListener listener);
+
+ <font color=#3F5FBF>/**
+ * Service events listener interface.
+ */</font>
+ <font color=#7F0055>interface</font> MemoryMapListener {
+
+ <font color=#3F5FBF>/**
+ * Called when context memory map changes.
+ * <font color=#7F9FBF>@param</font> context_id &ndash; context ID.
+ */</font>
+ <font color=#7F0055>void</font> changed(String context_id);
+ }
+}
+</pre>
+
+</body>
+</html>