| Version | Date | Change |
|---|---|---|
| 0.0 | 2012-07-22 | Initial documentation based on source code |
The service provides basic operations to get and set memory mapping on a target. Command and event parameters are encoded as zero terminated JSON strings.
The service uses standard format for error reports, see Error Report Format.
C • <token> • MemoryMap • get • <string: context ID> •
The command retrieves memory maps for given context ID.
Reply:
R • <token> • <error report> • <array of map items> •
<array of map items>
⇒ null
⇒ [ <map items list> ]
<map items list>
⇒ <object: map item properties>
⇒ <map items list> , <object: map item properties>
Predefined memory map properties are:
"ID" : <string>
- Memory region ID.
"ContextQuery" : <string>
- Memory region context query.
"Addr" : <int>
- region address in memory.
"Size" : <int>
- region size.
"Offs" : <int>
- Region offset in the file.
"BSS" : <boolean>
- True if the region represents BSS.
"Flags" : <int>
- Region memory protection flags, see predefined flags.
"FileName" : <string>
- Name of the file.
"SectionName" : <string>
- Name of the object file section.
Predefined flags are:
1
- Read access is allowed.2
- Write access is allowed.4
- Instruction fetch access is allowed.C • <token> • MemoryMap • set • <string: context ID> • <object: map item properties> •
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.
Reply:
R • <token> • <error report> •
MemoryMap service broadcasts notification events when memory map items are changed.
E • MemoryMap • changed • <string: context ID> •
/**
* IMemoryMap service provides information about executable modules (files) mapped (loaded) into target memory.
*/
public interface IMemoryMap extends IService {
static final String NAME = "MemoryMap";
/**
* Memory region property names.
*/
static final String
PROP_ID = "ID", /** String, memory region ID */
PROP_CONTEXT_QUERY = "ContextQuery", /** String, memory region context query, see IContextQuery */
PROP_ADDRESS = "Addr", /** Number, region address in memory */
PROP_SIZE = "Size", /** Number, region size */
PROP_OFFSET = "Offs", /** Number, region offset in the file */
PROP_BSS = "BSS", /** Boolean, true if the region represents BSS */
PROP_FLAGS = "Flags", /** Number, region memory protection flags, see FLAG_* */
PROP_FILE_NAME = "FileName", /** String, name of the file */
PROP_SECTION_NAME = "SectionName"; /** String, name of the object file section */
/**
* Memory region flags.
*/
static final int
FLAG_READ = 1, /** Read access is allowed */
FLAG_WRITE = 2, /** Write access is allowed */
FLAG_EXECUTE = 4; /** Instruction fetch access is allowed */
/**
* Memory region interface.
*/
interface MemoryRegion {
/**
* Get region properties. See PROP_* definitions for property names.
* Properties are read only, clients should not try to modify them.
* @return Map of region properties.
*/
Map getProperties();
/**
* Get memory region address.
* Same as getProperties().get(PROP_ADDRESS)
* @return region address.
*/
Number getAddress();
/**
* Get memory region size.
* Same as getProperties().get(PROP_SIZE)
* @return region size.
*/
Number getSize();
/**
* Get memory region file offset.
* Same as getProperties().get(PROP_OFFSET)
* @return file offset.
*/
Number getOffset();
/**
* 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)
* @return file offset.
*/
boolean isBSS();
/**
* Get memory region flags.
* Same as getProperties().get(PROP_FLAGS)
* @return region flags.
*/
int getFlags();
/**
* Get memory region file name.
* Same as getProperties().get(PROP_FILE_NAME)
* @return file name.
*/
String getFileName();
/**
* Get memory region section name.
* Same as getProperties().get(PROP_SECTION_NAME)
* @return section name.
*/
String getSectionName();
/**
* 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.
* @return context query expression, or null.
*/
String getContextQuery();
}
/**
* Retrieve memory map for given context ID.
*
* @param id – context ID.
* @param done – call back interface called when operation is completed.
* @return – pending command handle.
*/
IToken get(String id, DoneGet done);
/**
* Client call back interface for get().
*/
interface DoneGet {
/**
* Called when memory map data retrieval is done.
* @param error – error description if operation failed, null if succeeded.
* @param map – memory map data.
*/
void doneGet(IToken token, Exception error, MemoryRegion[] map);
}
/**
* 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.
*
* @param id – symbols context group ID or name.
* @param map – memory map data.
* @param done – call back interface called when operation is completed.
* @return – pending command handle.
*/
IToken set(String id, MemoryRegion[] map, DoneSet done);
/**
* Client call back interface for set().
*/
interface DoneSet {
/**
* Called when memory map set command is done.
* @param error – error description if operation failed, null if succeeded.
*/
void doneSet(IToken token, Exception error);
}
/**
* Add memory map event listener.
* @param listener – memory map event listener to add.
*/
void addListener(MemoryMapListener listener);
/**
* Remove memory map event listener.
* @param listener – memory map event listener to remove.
*/
void removeListener(MemoryMapListener listener);
/**
* Service events listener interface.
*/
interface MemoryMapListener {
/**
* Called when context memory map changes.
* @param context_id – context ID.
*/
void changed(String context_id);
}
}