1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
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 • <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>
|
