diff options
Diffstat (limited to 'docs/TCF Service - Memory.html')
-rw-r--r-- | docs/TCF Service - Memory.html | 456 |
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><array of error addresses></i> + <font face=Wingdings>Ψ</font> null + <font face=Wingdings>Ψ</font> [ <i><error address list></i> ] + +<i><error address list></i> + <font face=Wingdings>Ψ</font> <i><error address></i> + <font face=Wingdings>Ψ</font> <i><error address list></i> , <i><error address></i> + +<i><error address></i> + <font face=Wingdings>Ψ</font> { "addr" : <i><int: range starting address></i> , "size" : <i><int: range length in bytes></i> , "stat" : <i><int: status code></i> , "msg" : <i><error description></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><token></i> Memory getContext <i><string: context ID></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><token></i> <i><error report></i> <i><context data></i> + +<i><context data></i> + <font face=Wingdings>Ψ</font> null + <font face=Wingdings>Ψ</font> <i><object></i> +</font></b></pre> + +<p>Context data object should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</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><string></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><string></i></font></b></code> + - ID of a parent context. + + <li><code><b><font face="Courier New" size=2 color=#333399>"BigEndian" : <i><boolean></i></font></b></code> + - true if memory is big-endian. + + <li><code><b><font face="Courier New" size=2 color=#333399>"AddressSize" : <i><int></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><token></i> Memory getChildren <i><string: parent context ID></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><token></i> <i><error report></i> <i><array of context IDs></i> <i></i> + +<i><array of context IDs></i> + <font face=Wingdings>Ψ</font> null + <font face=Wingdings>Ψ</font> [ ] + <font face=Wingdings>Ψ</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ψ</font> <i><string: context ID></i> + <font face=Wingdings>Ψ</font> <i><context ID list></i> , <i><string: context ID></i> + +</font></b></pre> + +<h3><a name='CmdSetMemory'>Set Memory</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C <token> Memory set + <i><string: context ID></i> <i><int: address></i> <i><int: word size></i> + <i><int: byte count></i> <i><int: mode></i> <i><string: BASE64 encoded byte array></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><token></i> <i><error report></i> <i><array of error addresses></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 <token> Memory get + <i><string: context ID></i> <i><int: address></i> <i><int: word size></i> + <i><int: byte count></i> <i><int: mode></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><token></i> <i><string: BASE64 encoded byte array></i> <i><error report></i> <i><array of error addresses></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 <token> Memory fill + <i><string: context ID></i> <i><int: address></i> <i><int: word size></i> + <int: byte count> <i><int: mode></i> <i><array: array of pattern bytes></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><token></i> <i><error report></i> <i><array of error addresses></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><array of context data></i> +E Memory contextChanged <i><array of context data></i> +E Memory contextRemoved <i><array of context IDs></i> +E Memory memoryChanged <i><string: context ID></i> <i><array of address ranges></i> + +<i><array of context data></i> <font face="Times New Roman" size=3>- see Get Contexts command.</font> + +<i><array of context IDs></i> + <font face=Wingdings>Ψ</font> [ <i><context ID list></i> ] + +<i><context ID list></i> + <font face=Wingdings>Ψ</font> <i><string: context ID></i> + <font face=Wingdings>Ψ</font> <i><context ID list></i> , <i><string: context ID></i> + +<i><array of address ranges></i> + <font face=Wingdings>Ψ</font> null + <font face=Wingdings>Ψ</font> [ <i><address ranges list></i> ] + +<i><address ranges list></i> + <font face=Wingdings>Ψ</font> <i><address range></i> + <font face=Wingdings>Ψ</font> <i><address ranges list></i> , <i><address range></i> + +<i><address range></i> + <font face=Wingdings>Ψ</font> { "addr" : <i><int: range starting address></i> , "size" : <i><int: range length in bytes></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<String,Object> 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> |