Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'docs/TCF Service - Memory.html')
-rw-r--r--docs/TCF Service - Memory.html456
1 files changed, 456 insertions, 0 deletions
diff --git a/docs/TCF Service - Memory.html b/docs/TCF Service - Memory.html
new file mode 100644
index 000000000..afca975ea
--- /dev/null
+++ b/docs/TCF Service - Memory.html
@@ -0,0 +1,456 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Target Communication Framework Services - Memory</title>
+</head>
+
+<body lang='EN-US'>
+
+<h1>Target Communication Framework Services - Memory</h1>
+
+<ul>
+ <li><a href='#Cmds'>Commands</a>
+ <ul>
+ <li><a href='#CmdGetContext'>Get Context</a>
+ <li><a href='#CmdGetChildren'>Get Children</a>
+ <li><a href='#CmdSetMemory'>Set Memory</a>
+ <li><a href='#CmdGetMemory'>Get Memory</a>
+ <li><a href='#CmdFillMemory'>Fill Memory</a>
+ </ul>
+ <li><a href='#Events'>Events</a>
+ <li><a href='#API'>API</a>
+</ul>
+
+<h1>Memory Service</h1>
+
+<p>The service provides basic operations to read/write memory 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>
+
+<p>A single memory access can succeed for some addresses and fail for others. In such
+situation result message can contain partially valid data. Array of error addresses,
+in addition to error report, describes data validity on per byte basis:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+<i>&lt;array of error addresses&gt;</i>
+ <font face=Wingdings>Ψ</font> null
+ <font face=Wingdings>Ψ</font> [ <i>&lt;error address list&gt;</i> ]
+
+<i>&lt;error address list&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;error address&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;error address list&gt;</i> , <i>&lt;error address&gt;</i>
+
+<i>&lt;error address&gt;</i>
+ <font face=Wingdings>Ψ</font> { "addr" : <i>&lt;int: range starting address&gt;</i> , "size" : <i>&lt;int: range length in bytes&gt;</i> , "stat" : <i>&lt;int: status code&gt;</i> , "msg" : <i>&lt;error description&gt;</i> }
+</font></b></pre>
+
+<p>If there is no entry in error addresses array for a data byte, then status of such
+byte is defined by main error report.</p>
+
+<p>Status code is bitwise or of status flags:</p>
+<dl>
+ <dt><code><b>BYTE_VALID        = 0x00</b></code> <dd>no error for this byte
+    <dt><code><b>BYTE_UNKNOWN      = 0x01</b></code> <dd>status is unknown
+ <dt><code><b>BYTE_INVALID      = 0x02</b></code> <dd>byte value in invalid, error message describes the problem
+ <dt><code><b>BYTE_CANNOT_READ  = 0x04</b></code> <dd>cannot read the byte
+ <dt><code><b>BYTE_CANNOT_WRITE = 0x08</b></code> <dd>cannot write the byte
+</dl>
+
+<h2><a name='Cmds'>Commands</a></h2>
+
+<h3><a name='CmdGetContext'>Get Context</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C • <i>&lt;token&gt;</i> • Memory • getContext • <i>&lt;string: context ID&gt;</i> •
+</font></b></pre>
+
+<p>The command retrieves context info for given context ID. A context corresponds to an
+execution thread, process, address space, etc. Exact
+meaning of a context depends on the target. Target agent should define contexts hierarchy
+that is:</p>
+
+<ul type='disc'>
+ <li>Sufficient to resolve possible ambiguity of a memory address;
+
+ <li>Adequately reflects target memory management strategy;
+
+ <li>Intuitive to a user.
+</ul>
+
+<p>For traditional OS, like UNIX, memory access context can be one of:</p>
+
+<ul type='disc'>
+ <li>Kernel address space;
+
+ <li>A process.
+</ul>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R • <i>&lt;token&gt;</i> • <i>&lt;error report&gt;</i> • <i>&lt;context data&gt;</i> •
+
+<i>&lt;context data&gt;</i>
+ <font face=Wingdings>Ψ</font> null
+ <font face=Wingdings>Ψ</font> <i>&lt;object&gt;</i>
+</font></b></pre>
+
+<p>Context data object should, at least, contain member
+<b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;.</i></font></b>
+Context data is expected to be cached by clients.
+Service sends contextChanged event to notify changes in context data.</p>
+
+<p>Predefined memory context properties are:</p>
+<ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
+ - ID of the context, same as getContext command argument.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i>&lt;string&gt;</i></font></b></code>
+ - ID of a parent context.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"BigEndian" : <i>&lt;boolean&gt;</i></font></b></code>
+ - true if memory is big-endian.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"AddressSize" : <i>&lt;int&gt;</i></font></b></code>
+ - size of memory address in bytes.
+</ul>
+
+<h3><a name='CmdGetChildren'>Get Children</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C • <i>&lt;token&gt;</i> • Memory • getChildren • <i>&lt;string: parent context ID&gt;</i> •
+</font></b></pre>
+
+<p>The command requests a list of contexts available for memory access commands.</p>
+
+<p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one
+of context IDs retrieved by previous getChildren commands, or it can be obtained from another service.
+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.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R • <i>&lt;token&gt;</i> • <i>&lt;error report&gt;</i> • <i>&lt;array of context IDs&gt;</i> •<i></i>
+
+<i>&lt;array of context IDs&gt;</i>
+ <font face=Wingdings>Ψ</font> null
+ <font face=Wingdings>Ψ</font> [ ]
+ <font face=Wingdings>Ψ</font> [ <i>&lt;context ID list&gt;</i> ]
+
+<i>&lt;context ID list&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;string: context ID&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;context ID list&gt;</i> , <i>&lt;string: context ID&gt;</i>
+
+</font></b></pre>
+
+<h3><a name='CmdSetMemory'>Set Memory</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C • &lt;token&gt; • Memory • set •
+ <i>&lt;string: context ID&gt;</i> • <i>&lt;int: address&gt;</i> • <i>&lt;int: word size&gt;</i> •
+ <i>&lt;int: byte count&gt;</i> • <i>&lt;int: mode&gt;</i> • <i>&lt;string: BASE64 encoded byte array&gt;</i> •
+</font></b></pre>
+
+<p>Writes data bytes at given address in memory, "word size" bytes at a time. Address
+should be aligned by "word size". Context ID must be one returned by getContexts.
+Mode is logical OR of any combination of:</p>
+
+<ul type='disc'>
+ <li>0x1 – continue on error (like bus error or page fault)
+
+ <li>0x2 – verify data after writing by reading back and compare
+</ul>
+
+<p>Result message:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R • <i>&lt;token&gt;</i> • <i>&lt;error report&gt;</i> • <i>&lt;array of error addresses&gt;</i> •
+</font></b></pre>
+
+<p>Error report provides integer error code and a short, human readable explanation
+of error. Error addresses, when present, let client know which bytes of data failed
+to be written into memory.</p>
+
+<h3><a name='CmdGetMemory'>Get Memory</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C • &lt;token&gt; • Memory • get •
+ <i>&lt;string: context ID&gt;</i> • <i>&lt;int: address&gt;</i> • <i>&lt;int: word size&gt;</i> •
+ <i>&lt;int: byte count&gt;</i> • <i>&lt;int: mode&gt;</i> •
+</font></b></pre>
+
+<p>Reads data bytes at given address in memory, "word size" bytes at a time. Address
+should be aligned by "word size". Context ID must be one returned by getContexts.
+Mode is logical OR of any combination of:</p>
+
+<ul type='disc'>
+ <li>0x1 – continue on error (like bus error or page fault)
+
+ <li>0x2 – verify data after reading by re-reading and compare
+</ul>
+
+<p>Result message:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R • <i>&lt;token&gt;</i> • <i>&lt;string: BASE64 encoded byte array&gt;</i> • <i>&lt;error report&gt;</i> • <i>&lt;array of error addresses&gt;</i> •
+</font></b></pre>
+
+<p>Error report provides integer error code and a short, human readable explanation
+of error. Error addresses, when present, let client know which bytes of data failed
+to be retrieved from memory.</p>
+
+<h3><a name='CmdFillMemory'>Fill Memory</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C • &lt;token&gt; • Memory • fill •
+ <i>&lt;string: context ID&gt;</i> • <i>&lt;int: address&gt;</i> • <i>&lt;int: word size&gt;</i> •
+ &lt;int: byte count&gt; • <i>&lt;int: mode&gt;</i> • <i>&lt;array: array of pattern bytes&gt;</i> •
+</font></b></pre>
+
+<p>Writes pattern bytes at given address in memory, "word size" bytes at a time. Address
+should be aligned by "word size". If "byte count" is bigger then pattern size, then
+pattern is repeated necessary number of times. Context ID must be one returned by
+getContexts. Mode is logical OR of any combination of:</p>
+
+<ul type='disc'>
+ <li>0x1 – continue on error (like bus error or page fault)
+
+ <li>0x2 – verify data after writing by reading back and compare
+</ul>
+
+<p>Result message:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R • <i>&lt;token&gt;</i> • <i>&lt;error report&gt;</i> • <i>&lt;array of error addresses&gt;</i> •
+</font></b></pre>
+
+<p>Error report provides integer error code and a short, human readable explanation
+of error. Error addresses, when present, let client know which bytes of data failed
+to be written into memory.</p>
+
+<h2><a name='Events'>Events</a></h2>
+
+<p>Memory service broadcasts notification events when memory contexts are added, removed
+or changed, and when memory content is altered by "set" or "fill" commands.</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+E • Memory • contextAdded • <i>&lt;array of context data&gt;</i> •
+E • Memory • contextChanged • <i>&lt;array of context data&gt;</i> •
+E • Memory • contextRemoved • <i>&lt;array of context IDs&gt;</i> •
+E • Memory • memoryChanged • <i>&lt;string: context ID&gt;</i> • <i>&lt;array of address ranges&gt;</i> •
+
+<i>&lt;array of context data&gt;</i> <font face="Times New Roman" size=3>- see Get Contexts command.</font>
+
+<i>&lt;array of context IDs&gt;</i>
+ <font face=Wingdings>Ψ</font> [ <i>&lt;context ID list&gt;</i> ]
+
+<i>&lt;context ID list&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;string: context ID&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;context ID list&gt;</i> , <i>&lt;string: context ID&gt;</i>
+
+<i>&lt;array of address ranges&gt;</i>
+ <font face=Wingdings>Ψ</font> null
+ <font face=Wingdings>Ψ</font> [ <i>&lt;address ranges list&gt;</i> ]
+
+<i>&lt;address ranges list&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;address range&gt;</i>
+ <font face=Wingdings>Ψ</font> <i>&lt;address ranges list&gt;</i> , <i>&lt;address range&gt;</i>
+
+<i>&lt;address range&gt;</i>
+ <font face=Wingdings>Ψ</font> { "addr" : <i>&lt;int: range starting address&gt;</i> , "size" : <i>&lt;int: range length in bytes&gt;</i> }
+</font></b></pre>
+
+<h2><a name='API'>API</a></h2>
+
+<pre>
+<font color=#3F5FBF>/**
+ * IMemory service provides basic operations to read/write memory on a target.
+ */</font>
+<font color=#7F0055>public interface</font> Memory <font color=#7F0055>extends</font> Service {
+
+ <font color=#7F0055>static final</font> String NAME = "Memory";
+
+ <font color=#3F5FBF>/**
+ * Retrieve context info for given context ID.
+ *
+ * <font color=#7F9FBF>@param</font> id – context ID.
+ * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed.
+     */</font>
+ IToken getContext(String id, DoneGetContext done);
+
+ <font color=#3F5FBF>/**
+ * Client callback interface for getContext().
+     */</font>
+ <font color=#7F0055>interface</font> DoneGetContext {
+ <font color=#3F5FBF>/**
+ * Called when contexts data retrieval is done.
+ * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> context – context data.
+ */</font>
+ <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, MemoryContext context);
+ }
+
+ <font color=#3F5FBF>/**
+ * Retrieve contexts available for memory commands.
+ * A context corresponds to an execution thread, process, address space, etc.
+ * A context can belong to a parent context. Contexts hierarchy can be simple
+ * plain list or it can form a tree. It is up to target agent developers to choose
+ * layout that is most descriptive for a given target. Context IDs are valid across
+ * all services. In other words, all services access same hierarchy of contexts,
+ * with same IDs, however, each service accesses its own subset of context's
+ * attributes and functionality, which is relevant to that service.
+ *
+ * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null –
+ * to retrieve top level of the hierarchy, or one of context IDs retrieved
+ * by previous getContexts commands.
+ * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed.
+ */</font>
+ IToken getChildren(String parent_context_id, DoneGetChildren done);
+
+ <font color=#3F5FBF>/**
+ * Client callback interface for getChildren().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGetChildren {
+ <font color=#3F5FBF>/**
+ * Called when contexts data retrieval is done.
+         * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded.
+         * <font color=#7F9FBF>@param</font> contexts – array of available context IDs.
+ */</font>
+ <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids);
+ }
+
+    <font color=#3F5FBF>/**
+     * 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.
+     */</font>
+    <font color=#7F0055>final static int</font> MODE_CONTINUEONERROR = 0x1;
+
+    <font color=#3F5FBF>/**
+     * Memory access mode:
+     * Verify result of memory operations (by reading and comparing).
+     */</font>
+    <font color=#7F0055>final static int</font> MODE_VERIFY = 0x2;
+
+    <font color=#7F0055>interface</font> MemoryContext {
+
+        <font color=#3F5FBF>/**
+         * Retrieve context ID.
+         * Same as getProperties().get("id")
+         */</font>
+        String getID();
+
+        <font color=#3F5FBF>/**
+         * Return true if the context has children.
+         * Same as getProperties().get("has_children")
+         * Children can be retrieved by getContexts call.
+         */</font>
+        <font color=#7F0055>boolean</font> hasChildren();
+
+        <font color=#3F5FBF>/**
+         * Retrieve context properties.
+         */</font>
+        Map&lt;String,Object&gt; getProperties();
+
+        <font color=#3F5FBF>/**
+         * Set target memory.
+         * If 'word_size' is 0 it means client does not care about word size.
+         */</font>
+        <font color=#7F0055>void</font> set(long addr, <font color=#7F0055>int</font> word_size, byte[] buf,
+                         <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done);
+
+        <font color=#3F5FBF>/**
+         * Read target memory.
+         */</font>
+        <font color=#7F0055>void</font> get(long addr, <font color=#7F0055>int</font> word_size, byte[] buf,
+                         <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done);
+
+        <font color=#3F5FBF>/**
+         * Fill target memory with given pattern.
+         * 'size' is number of bytes to fill.
+         */</font>
+        <font color=#7F0055>void</font> fill(long addr, <font color=#7F0055>int</font> word_size, byte[] value,
+                          <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done);
+   
+        <font color=#3F5FBF>/**
+         * Client callback interface for set(), get() and fill().
+         */</font>
+        <font color=#7F0055>interface</font> DoneMemory {
+            <font color=#7F0055>void</font> doneMemory(MemoryError error);
+        }
+    }
+
+    <font color=#7F0055>class</font> MemoryError <font color=#7F0055>extends</font> Exception {
+    }
+
+    <font color=#3F5FBF>/**
+     * ErrorOffset interface can 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
+     * translates to valid memory addresses.)
+     * Exception.getMessage can be used for generalized message of the
+     * possible reasons of partial memory operation.
+     */</font>
+    <font color=#7F0055>interface</font> ErrorOffset {
+       
+        // Error may have per byte information
+        <font color=#7F0055>final static int</font>
+            BYTE_VALID        = 0x00,
+            BYTE_UNKNOWN      = 0x01, // e.g. out of range
+            BYTE_INVALID      = 0x02,
+            BYTE_CANNOT_READ  = 0x04,
+            BYTE_CANNOT_WRITE = 0x08;
+
+        <font color=#7F0055>int</font> getStatus(<font color=#7F0055>int</font> offset);
+
+        <font color=#3F5FBF>/**
+         * Returns the detail message string about the
+         * byte associated with specified location.
+         * <font color=#7F9FBF>@return</font>  the detail error message string.
+         */</font>
+        String getMessage(<font color=#7F0055>int</font> offset);
+       
+    }
+
+    <font color=#7F0055>void</font> addListener(MemoryListener listener);
+
+    <font color=#7F0055>interface</font> MemoryListener {
+
+        <font color=#3F5FBF>/**
+         * Called when a new memory access context(s) is created.
+         */</font>
+        <font color=#7F0055>void</font> contextAdded(Context[] contexts);
+
+        <font color=#3F5FBF>/**
+         * Called when a new memory access context(s) properties changed.
+         */</font>
+        <font color=#7F0055>void</font> contextChanged(Context[] contexts);
+
+        <font color=#3F5FBF>/**
+         * Called when memory access context(s) is removed.
+         */</font>
+        <font color=#7F0055>void</font> contextRemoved(String[] context_ids);
+
+        <font color=#3F5FBF>/**
+         * 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 null if unknown.
+         */</font>
+        <font color=#7F0055>void</font> memoryChanged(String context_id,
+               long[] addr, long[] size);
+    }
+}
+</pre>
+
+</body>
+</html>

Back to the top