<!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 • <i><token></i> • MemoryMap • get • <i><string: context ID></i> •
</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 • <i><token></i> • <i><error report></i> • <i><array of map items></i> •
<i><array of map items></i>
⇒ null
⇒ [ <i><map items list></i> ]
<i><map items list></i>
⇒ <i><object: map item properties></i>
⇒ <i><map items list></i> , <i><object: map item properties></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><string></i></font></b></code>
- Memory region ID.
<li><code><b><font face="Courier New" size=2 color=#333399>"ContextQuery" : <i><string></i></font></b></code>
- Memory region context query.
<li><code><b><font face="Courier New" size=2 color=#333399>"Addr" : <i><int></i></font></b></code>
- region address in memory.
<li><code><b><font face="Courier New" size=2 color=#333399>"Size" : <i><int></i></font></b></code>
- region size.
<li><code><b><font face="Courier New" size=2 color=#333399>"Offs" : <i><int></i></font></b></code>
- Region offset in the file.
<li><code><b><font face="Courier New" size=2 color=#333399>"BSS" : <i><boolean></i></font></b></code>
- True if the region represents BSS.
<li><code><b><font face="Courier New" size=2 color=#333399>"Flags" : <i><int></i></font></b></code>
- Region memory protection flags, see predefined flags.
<li><code><b><font face="Courier New" size=2 color=#333399>"FileName" : <i><string></i></font></b></code>
- Name of the file.
<li><code><b><font face="Courier New" size=2 color=#333399>"SectionName" : <i><string></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 • <i><token></i> • MemoryMap • set • <i><string: context ID></i> • <i><object: map item properties></i> •
</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 • <i><token></i> • <i><error report></i> •
</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 • MemoryMap • changed • <i><string: context ID></i> •
</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 – context ID.
* <font color=#7F9FBF>@param</font> done – call back interface called when operation is completed.
* <font color=#7F9FBF>@return</font> – 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 – error description if operation failed, null if succeeded.
* <font color=#7F9FBF>@param</font> map – 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 – symbols context group ID or name.
* <font color=#7F9FBF>@param</font> map – memory map data.
* <font color=#7F9FBF>@param</font> done – call back interface called when operation is completed.
* <font color=#7F9FBF>@return</font> – 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 – 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 – 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 – 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 – context ID.
*/</font>
<font color=#7F0055>void</font> changed(String context_id);
}
}
</pre>
</body>
</html>
