|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
|
2 <html> |
|
3 <head> |
|
4 <title>Target Communication Framework Services - Memory</title> |
|
5 </head> |
|
6 |
|
7 <body lang='EN-US'> |
|
8 |
|
9 <h1>Target Communication Framework Services - Memory</h1> |
|
10 |
|
11 <ul> |
|
12 <li><a href='#VersionHistory'>Version History</a> |
|
13 <li><a href='#Overview'>Overview</a> |
|
14 <li><a href='#Cmds'>Commands</a> |
|
15 <ul> |
|
16 <li><a href='#CmdGetContext'>Get Context</a> |
|
17 <li><a href='#CmdGetChildren'>Get Children</a> |
|
18 <li><a href='#CmdSetMemory'>Set Memory</a> |
|
19 <li><a href='#CmdGetMemory'>Get Memory</a> |
|
20 <li><a href='#CmdFillMemory'>Fill Memory</a> |
|
21 </ul> |
|
22 <li><a href='#Events'>Events</a> |
|
23 <li><a href='#API'>API</a> |
|
24 </ul> |
|
25 |
|
26 <h1>Memory Service</h1> |
|
27 |
|
28 <h2><a name='VersionHistory'>Version History</a></h2> |
|
29 |
|
30 <table border=1 cellpadding=8> |
|
31 <tr> |
|
32 <th>Version |
|
33 <th>Date |
|
34 <th>Change |
|
35 <tr> |
|
36 <td>0.1 |
|
37 <td>2008-01-10 |
|
38 <td>Initial contribution |
|
39 <tr> |
|
40 <td>1.0 |
|
41 <td>2008-05-06 |
|
42 <td>Approved |
|
43 <tr> |
|
44 <td>1.1 |
|
45 <td>2009-03-16 |
|
46 <td>Added context properties |
|
47 </table> |
|
48 |
|
49 <h2><a name='Overview'>Overview</a></h2> |
|
50 |
|
51 <p>The service provides basic operations to read/write memory on a target. Command |
|
52 and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> |
|
53 |
|
54 <p>The service uses standard format for error reports, |
|
55 see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> |
|
56 |
|
57 <p>A single memory access can succeed for some addresses and fail for others. In such |
|
58 situation result message can contain partially valid data. Array of error addresses, |
|
59 in addition to error report, describes data validity on per byte basis:</p> |
|
60 |
|
61 <pre><b><font face="Courier New" size=2 color=#333399> |
|
62 <i><array of error addresses></i> |
|
63 ⇒ null |
|
64 ⇒ [ <i><error address list></i> ] |
|
65 |
|
66 <i><error address list></i> |
|
67 ⇒ <i><error address></i> |
|
68 ⇒ <i><error address list></i> , <i><error address></i> |
|
69 |
|
70 <i><error address></i> |
|
71 ⇒ { "addr" : <i><int: range starting address></i> , "size" : <i><int: range length in bytes></i> , "stat" : <i><int: status code></i> , "msg" : <i><object: error description></i> } |
|
72 </font></b></pre> |
|
73 |
|
74 <p>If there is no entry in error addresses array for a data byte, then status of such |
|
75 byte is defined by main error report.</p> |
|
76 |
|
77 <p>Status code is bitwise or of status flags:</p> |
|
78 <dl> |
|
79 <dt><code><b>BYTE_VALID = 0x00</b></code> <dd>no error for this byte |
|
80 <dt><code><b>BYTE_UNKNOWN = 0x01</b></code> <dd>status is unknown |
|
81 <dt><code><b>BYTE_INVALID = 0x02</b></code> <dd>byte value in invalid, error message describes the problem |
|
82 <dt><code><b>BYTE_CANNOT_READ = 0x04</b></code> <dd>cannot read the byte |
|
83 <dt><code><b>BYTE_CANNOT_WRITE = 0x08</b></code> <dd>cannot write the byte |
|
84 </dl> |
|
85 |
|
86 <h2><a name='Cmds'>Commands</a></h2> |
|
87 |
|
88 <h3><a name='CmdGetContext'>Get Context</a></h3> |
|
89 |
|
90 <pre><b><font face="Courier New" size=2 color=#333399> |
|
91 C • <i><token></i> • Memory • getContext • <i><string: context ID></i> • |
|
92 </font></b></pre> |
|
93 |
|
94 <p>The command retrieves context info for given context ID. A context corresponds to an |
|
95 execution thread, process, address space, etc. Exact |
|
96 meaning of a context depends on the target. Target agent should define contexts hierarchy |
|
97 that is:</p> |
|
98 |
|
99 <ul type='disc'> |
|
100 <li>Sufficient to resolve possible ambiguity of a memory address; |
|
101 |
|
102 <li>Adequately reflects target memory management strategy; |
|
103 |
|
104 <li>Intuitive to a user. |
|
105 </ul> |
|
106 |
|
107 <p>For traditional OS, like UNIX, memory access context can be one of:</p> |
|
108 |
|
109 <ul type='disc'> |
|
110 <li>Kernel address space; |
|
111 |
|
112 <li>A process. |
|
113 </ul> |
|
114 |
|
115 <p>Reply:</p> |
|
116 |
|
117 <pre><b><font face="Courier New" size=2 color=#333399> |
|
118 R • <i><token></i> • <i><error report></i> • <i><context data></i> • |
|
119 |
|
120 <i><context data></i> |
|
121 ⇒ null |
|
122 ⇒ <i><object></i> |
|
123 </font></b></pre> |
|
124 |
|
125 <p>Context data object should, at least, contain member |
|
126 <b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b> |
|
127 Context data is expected to be cached by clients. |
|
128 Service sends contextChanged event to notify changes in context data.</p> |
|
129 |
|
130 <p>Predefined memory context properties are:</p> |
|
131 <ul> |
|
132 <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> |
|
133 - ID of the context, same as getContext command argument. |
|
134 |
|
135 <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> |
|
136 - ID of a parent context. |
|
137 |
|
138 <li><code><b><font face="Courier New" size=2 color=#333399>"ProcessID" : <i><string></i></font></b></code> |
|
139 - process ID. |
|
140 |
|
141 <li><code><b><font face="Courier New" size=2 color=#333399>"BigEndian" : <i><boolean></i></font></b></code> |
|
142 - true if memory is big-endian. |
|
143 |
|
144 <li><code><b><font face="Courier New" size=2 color=#333399>"AddressSize" : <i><int></i></font></b></code> |
|
145 - size of memory address in bytes. |
|
146 |
|
147 <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><int></i></font></b></code> |
|
148 - name of the context, can be used for UI purposes. |
|
149 |
|
150 <li><code><b><font face="Courier New" size=2 color=#333399>"StartBound" : <i><int></i></font></b></code> |
|
151 - lowest address (inclusive) which is valid for the context. |
|
152 |
|
153 <li><code><b><font face="Courier New" size=2 color=#333399>"EndBound" : <i><int></i></font></b></code> |
|
154 - highest address (inclusive) which is valid for the context. |
|
155 |
|
156 <li><code><b><font face="Courier New" size=2 color=#333399>"AccessTypes" : <i><array of strings></i></font></b></code> |
|
157 - Defines the access types allowed for this context. |
|
158 <p>Target system can support multiple different memory access types, like instruction and data access. |
|
159 Different access types can use different logic for address translation and memory mapping, so they can |
|
160 end up accessing different data bits, even if address is the same. |
|
161 Each distinct access type should be represented by separate memory context. |
|
162 A memory context can represent multiple access types if they are equivalent - all access same memory bits. |
|
163 Same data bits can be exposed through multiple memory contexts.</p> |
|
164 |
|
165 <p>Predefined access types are:</p> |
|
166 <ul> |
|
167 <li><code><b><font face="Courier New" size=2 color=#333399>"instruction"</font></b></code> |
|
168 - Context represent instructions fetch access. |
|
169 |
|
170 <li><code><b><font face="Courier New" size=2 color=#333399>"data"</font></b></code> |
|
171 - Context represents data access. |
|
172 |
|
173 <li><code><b><font face="Courier New" size=2 color=#333399>"io"</font></b></code> |
|
174 - Context represents IO peripherals. |
|
175 |
|
176 <li><code><b><font face="Courier New" size=2 color=#333399>"user"</font></b></code> |
|
177 - Context represents a user (e.g. application running in Linux) view to memory. |
|
178 |
|
179 <li><code><b><font face="Courier New" size=2 color=#333399>"supervisor"</font></b></code> |
|
180 - Context represents a supervisor (e.g. Linux kernel) view to memory. |
|
181 |
|
182 <li><code><b><font face="Courier New" size=2 color=#333399>"hypervisor"</font></b></code> |
|
183 - Context represents a hypervisor view to memory. |
|
184 |
|
185 <li><code><b><font face="Courier New" size=2 color=#333399>"virtual"</font></b></code> |
|
186 - Context uses virtual addresses. |
|
187 |
|
188 <li><code><b><font face="Courier New" size=2 color=#333399>"physical"</font></b></code> |
|
189 - Context uses physical addresses. |
|
190 |
|
191 <li><code><b><font face="Courier New" size=2 color=#333399>"cache"</font></b></code> |
|
192 - Context is a cache. |
|
193 |
|
194 <li><code><b><font face="Courier New" size=2 color=#333399>"tlb"</font></b></code> |
|
195 - Context is a TLB memory. |
|
196 </ul> |
|
197 </ul> |
|
198 |
|
199 <h3><a name='CmdGetChildren'>Get Children</a></h3> |
|
200 |
|
201 <pre><b><font face="Courier New" size=2 color=#333399> |
|
202 C • <i><token></i> • Memory • getChildren • <i><string: parent context ID></i> • |
|
203 </font></b></pre> |
|
204 |
|
205 <p>The command requests a list of contexts available for memory access commands.</p> |
|
206 |
|
207 <p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one |
|
208 of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. |
|
209 Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to |
|
210 choose layout that is most descriptive for a given target.</p> |
|
211 |
|
212 <p>Reply:</p> |
|
213 |
|
214 <pre><b><font face="Courier New" size=2 color=#333399> |
|
215 R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> •<i></i> |
|
216 |
|
217 <i><array of context IDs></i> |
|
218 ⇒ null |
|
219 ⇒ [ ] |
|
220 ⇒ [ <i><context ID list></i> ] |
|
221 |
|
222 <i><context ID list></i> |
|
223 ⇒ <i><string: context ID></i> |
|
224 ⇒ <i><context ID list></i> , <i><string: context ID></i> |
|
225 |
|
226 </font></b></pre> |
|
227 |
|
228 <h3><a name='CmdSetMemory'>Set Memory</a></h3> |
|
229 |
|
230 <pre><b><font face="Courier New" size=2 color=#333399> |
|
231 C • <token> • Memory • set • |
|
232 <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • |
|
233 <i><int: byte count></i> • <i><int: mode></i> • <i><string: BASE64 encoded byte array></i> • |
|
234 </font></b></pre> |
|
235 |
|
236 <p>Writes data bytes at given address in memory, "word size" bytes at a time. Address |
|
237 should be aligned by "word size". Context ID must be one returned by getContexts. |
|
238 Mode is logical OR of any combination of:</p> |
|
239 |
|
240 <ul type='disc'> |
|
241 <li>0x1 – continue on error (like bus error or page fault) |
|
242 |
|
243 <li>0x2 – verify data after writing by reading back and compare |
|
244 </ul> |
|
245 |
|
246 <p>Result message:</p> |
|
247 |
|
248 <pre><b><font face="Courier New" size=2 color=#333399> |
|
249 R • <i><token></i> • <i><error report></i> • <i><array of error addresses></i> • |
|
250 </font></b></pre> |
|
251 |
|
252 <p>Error report provides integer error code and a short, human readable explanation |
|
253 of error. Error addresses, when present, let client know which bytes of data failed |
|
254 to be written into memory.</p> |
|
255 |
|
256 <h3><a name='CmdGetMemory'>Get Memory</a></h3> |
|
257 |
|
258 <pre><b><font face="Courier New" size=2 color=#333399> |
|
259 C • <token> • Memory • get • |
|
260 <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • |
|
261 <i><int: byte count></i> • <i><int: mode></i> • |
|
262 </font></b></pre> |
|
263 |
|
264 <p>Reads data bytes at given address in memory, "word size" bytes at a time. Address |
|
265 should be aligned by "word size". Context ID must be one returned by getContexts. |
|
266 Mode is logical OR of any combination of:</p> |
|
267 |
|
268 <ul type='disc'> |
|
269 <li>0x1 – continue on error (like bus error or page fault) |
|
270 |
|
271 <li>0x2 – verify data after reading by re-reading and compare |
|
272 </ul> |
|
273 |
|
274 <p>Result message:</p> |
|
275 |
|
276 <pre><b><font face="Courier New" size=2 color=#333399> |
|
277 R • <i><token></i> • <i><string: BASE64 encoded byte array></i> • <i><error report></i> • <i><array of error addresses></i> • |
|
278 </font></b></pre> |
|
279 |
|
280 <p>Error report provides integer error code and a short, human readable explanation |
|
281 of error. Error addresses, when present, let client know which bytes of data failed |
|
282 to be retrieved from memory.</p> |
|
283 |
|
284 <h3><a name='CmdFillMemory'>Fill Memory</a></h3> |
|
285 |
|
286 <pre><b><font face="Courier New" size=2 color=#333399> |
|
287 C • <token> • Memory • fill • |
|
288 <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • |
|
289 <int: byte count> • <i><int: mode></i> • <i><array: array of pattern bytes></i> • |
|
290 </font></b></pre> |
|
291 |
|
292 <p>Writes pattern bytes at given address in memory, "word size" bytes at a time. Address |
|
293 should be aligned by "word size". If "byte count" is bigger then pattern size, then |
|
294 pattern is repeated necessary number of times. Context ID must be one returned by |
|
295 getContexts. Mode is logical OR of any combination of:</p> |
|
296 |
|
297 <ul type='disc'> |
|
298 <li>0x1 – continue on error (like bus error or page fault) |
|
299 |
|
300 <li>0x2 – verify data after writing by reading back and compare |
|
301 </ul> |
|
302 |
|
303 <p>Result message:</p> |
|
304 |
|
305 <pre><b><font face="Courier New" size=2 color=#333399> |
|
306 R • <i><token></i> • <i><error report></i> • <i><array of error addresses></i> • |
|
307 </font></b></pre> |
|
308 |
|
309 <p>Error report provides integer error code and a short, human readable explanation |
|
310 of error. Error addresses, when present, let client know which bytes of data failed |
|
311 to be written into memory.</p> |
|
312 |
|
313 <h2><a name='Events'>Events</a></h2> |
|
314 |
|
315 <p>Memory service broadcasts notification events when memory contexts are added, removed |
|
316 or changed, and when memory content is altered by "set" or "fill" commands.</p> |
|
317 |
|
318 <pre><b><font face="Courier New" size=2 color=#333399> |
|
319 E • Memory • contextAdded • <i><array of context data></i> • |
|
320 E • Memory • contextChanged • <i><array of context data></i> • |
|
321 E • Memory • contextRemoved • <i><array of context IDs></i> • |
|
322 E • Memory • memoryChanged • <i><string: context ID></i> • <i><array of address ranges></i> • |
|
323 |
|
324 <i><array of context data></i> <font face="Times New Roman" size=3>- see Get Contexts command.</font> |
|
325 |
|
326 <i><array of context IDs></i> |
|
327 ⇒ [ <i><context ID list></i> ] |
|
328 |
|
329 <i><context ID list></i> |
|
330 ⇒ <i><string: context ID></i> |
|
331 ⇒ <i><context ID list></i> , <i><string: context ID></i> |
|
332 |
|
333 <i><array of address ranges></i> |
|
334 ⇒ null |
|
335 ⇒ [ <i><address ranges list></i> ] |
|
336 |
|
337 <i><address ranges list></i> |
|
338 ⇒ <i><address range></i> |
|
339 ⇒ <i><address ranges list></i> , <i><address range></i> |
|
340 |
|
341 <i><address range></i> |
|
342 ⇒ { "addr" : <i><int: range starting address></i> , "size" : <i><int: range length in bytes></i> } |
|
343 </font></b></pre> |
|
344 |
|
345 <h2><a name='API'>API</a></h2> |
|
346 |
|
347 <pre> |
|
348 <font color=#3F5FBF>/** |
|
349 * IMemory service provides basic operations to read/write memory on a target. |
|
350 */</font> |
|
351 <font color=#7F0055>public interface</font> Memory <font color=#7F0055>extends</font> Service { |
|
352 |
|
353 <font color=#7F0055>static final</font> String NAME = "Memory"; |
|
354 |
|
355 <font color=#3F5FBF>/** |
|
356 * Context property names. |
|
357 */</font> |
|
358 <font color=#7F0055>static final</font> String |
|
359 PROP_ID = "ID", <font color=#3F5FBF>/** String, ID of the context, same as getContext command argument */</font> |
|
360 PROP_PARENT_ID = "ParentID", <font color=#3F5FBF>/** String, ID of a parent context */</font> |
|
361 PROP_PROCESS_ID = "ProcessID", <font color=#3F5FBF>/** String, process ID, see Processes service */</font> |
|
362 PROP_BIG_ENDIAN = "BigEndian", <font color=#3F5FBF>/** Boolean, true if memory is big-endian */</font> |
|
363 PROP_ADDRESS_SIZE = "AddressSize", <font color=#3F5FBF>/** Number, size of memory address in bytes */</font> |
|
364 PROP_NAME = "Name", <font color=#3F5FBF>/** String, name of the context, can be used for UI purposes */</font> |
|
365 PROP_START_BOUND = "StartBound", <font color=#3F5FBF>/** Number, lowest address (inclusive) which is valid for the context */</font> |
|
366 PROP_END_BOUND = "EndBound", <font color=#3F5FBF>/** Number, highest address (inclusive) which is valid for the context */</font> |
|
367 PROP_ACCESS_TYPES = "AccessTypes"; <font color=#3F5FBF>/** Array of String, the access types allowed for this context */</font> |
|
368 |
|
369 <font color=#3F5FBF>/** |
|
370 * Values of "AccessTypes". |
|
371 * Target system can support multiple different memory access types, like instruction and data access. |
|
372 * Different access types can use different logic for address translation and memory mapping, so they can |
|
373 * end up accessing different data bits, even if address is the same. |
|
374 * Each distinct access type should be represented by separate memory context. |
|
375 * A memory context can represent multiple access types if they are equivalent - all access same memory bits. |
|
376 * Same data bits can be exposed through multiple memory contexts. |
|
377 */</font> |
|
378 <font color=#7F0055>static final</font> String |
|
379 ACCESS_INSTRUCTION = "instruction", <font color=#3F5FBF>/** Context represent instructions fetch access */</font> |
|
380 ACCESS_DATA = "data", <font color=#3F5FBF>/** Context represents data access */</font> |
|
381 ACCESS_IO = "io", <font color=#3F5FBF>/** Context represents IO peripherals */</font> |
|
382 ACCESS_USER = "user", <font color=#3F5FBF>/** Context represents a user (e.g. application running in Linux) view to memory */</font> |
|
383 ACCESS_SUPERVISOR = "supervisor", <font color=#3F5FBF>/** Context represents a supervisor (e.g. Linux kernel) view to memory */</font> |
|
384 ACCESS_HYPERVISOR = "hypervisor", <font color=#3F5FBF>/** Context represents a hypervisor view to memory */</font> |
|
385 ACCESS_VIRTUAL = "virtual", <font color=#3F5FBF>/** Context uses virtual addresses */</font> |
|
386 ACCESS_PHYSICAL = "physical", <font color=#3F5FBF>/** Context uses physical addresses */</font> |
|
387 ACCESS_CACHE = "cache", <font color=#3F5FBF>/** Context is a cache */</font> |
|
388 ACCESS_TLB = "tlb"; <font color=#3F5FBF>/** Context is a TLB memory */</font> |
|
389 |
|
390 <font color=#3F5FBF>/** |
|
391 * Retrieve context info for given context ID. |
|
392 * |
|
393 * <font color=#7F9FBF>@param</font> id – context ID. |
|
394 * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. |
|
395 */</font> |
|
396 IToken getContext(String id, DoneGetContext done); |
|
397 |
|
398 <font color=#3F5FBF>/** |
|
399 * Client callback interface for getContext(). |
|
400 */</font> |
|
401 <font color=#7F0055>interface</font> DoneGetContext { |
|
402 <font color=#3F5FBF>/** |
|
403 * Called when contexts data retrieval is done. |
|
404 * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. |
|
405 * <font color=#7F9FBF>@param</font> context – context data. |
|
406 */</font> |
|
407 <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, MemoryContext context); |
|
408 } |
|
409 |
|
410 <font color=#3F5FBF>/** |
|
411 * Retrieve contexts available for memory commands. |
|
412 * A context corresponds to an execution thread, process, address space, etc. |
|
413 * A context can belong to a parent context. Contexts hierarchy can be simple |
|
414 * plain list or it can form a tree. It is up to target agent developers to choose |
|
415 * layout that is most descriptive for a given target. Context IDs are valid across |
|
416 * all services. In other words, all services access same hierarchy of contexts, |
|
417 * with same IDs, however, each service accesses its own subset of context's |
|
418 * attributes and functionality, which is relevant to that service. |
|
419 * |
|
420 * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – |
|
421 * to retrieve top level of the hierarchy, or one of context IDs retrieved |
|
422 * by previous getContexts commands. |
|
423 * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. |
|
424 */</font> |
|
425 IToken getChildren(String parent_context_id, DoneGetChildren done); |
|
426 |
|
427 <font color=#3F5FBF>/** |
|
428 * Client callback interface for getChildren(). |
|
429 */</font> |
|
430 <font color=#7F0055>interface</font> DoneGetChildren { |
|
431 <font color=#3F5FBF>/** |
|
432 * Called when contexts data retrieval is done. |
|
433 * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. |
|
434 * <font color=#7F9FBF>@param</font> contexts – array of available context IDs. |
|
435 */</font> |
|
436 <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); |
|
437 } |
|
438 |
|
439 <font color=#3F5FBF>/** |
|
440 * Memory access mode: |
|
441 * Carry on when some of the memory cannot be accessed and |
|
442 * return MemoryError at the end if any of the bytes |
|
443 * were not processed correctly. |
|
444 */</font> |
|
445 <font color=#7F0055>final static int</font> MODE_CONTINUEONERROR = 0x1; |
|
446 |
|
447 <font color=#3F5FBF>/** |
|
448 * Memory access mode: |
|
449 * Verify result of memory operations (by reading and comparing). |
|
450 */</font> |
|
451 <font color=#7F0055>final static int</font> MODE_VERIFY = 0x2; |
|
452 |
|
453 <font color=#7F0055>interface</font> MemoryContext { |
|
454 |
|
455 <font color=#3F5FBF>/** |
|
456 * Get context ID. |
|
457 * <font color=#7F9FBF>@return</font> context ID. |
|
458 */</font> |
|
459 String getID(); |
|
460 |
|
461 <font color=#3F5FBF>/** |
|
462 * Get parent context ID. |
|
463 * <font color=#7F9FBF>@return</font> parent ID. |
|
464 */</font> |
|
465 String getParentID(); |
|
466 |
|
467 <font color=#3F5FBF>/** |
|
468 * Get process ID, if applicable. |
|
469 * <font color=#7F9FBF>@return</font> process ID. |
|
470 */</font> |
|
471 String getProcessID(); |
|
472 |
|
473 <font color=#3F5FBF>/** |
|
474 * Get memory endianess. |
|
475 * <font color=#7F9FBF>@return</font> true if memory id big-endian. |
|
476 */</font> |
|
477 boolean isBigEndian(); |
|
478 |
|
479 <font color=#3F5FBF>/** |
|
480 * Get memory address size. |
|
481 * <font color=#7F9FBF>@return</font> number of bytes used to store memory address value. |
|
482 */</font> |
|
483 <font color=#7F0055>int</font> getAddressSize(); |
|
484 |
|
485 <font color=#3F5FBF>/** |
|
486 * Get memory context name. |
|
487 * The name can be used for UI purposes. |
|
488 * <font color=#7F9FBF>@return</font> context name. |
|
489 */</font> |
|
490 String getName(); |
|
491 |
|
492 <font color=#3F5FBF>/** |
|
493 * Get lowest address (inclusive) which is valid for the context. |
|
494 * <font color=#7F9FBF>@return</font> lowest address. |
|
495 */</font> |
|
496 Number getStartBound(); |
|
497 |
|
498 <font color=#3F5FBF>/** |
|
499 * Get highest address (inclusive) which is valid for the context. |
|
500 * <font color=#7F9FBF>@return</font> highest address. |
|
501 */</font> |
|
502 Number getEndBound(); |
|
503 |
|
504 <font color=#3F5FBF>/** |
|
505 * Get the access types allowed for this context. |
|
506 * <font color=#7F9FBF>@return</font> collection of access type names. |
|
507 */</font> |
|
508 Collection<String> getAccessTypes(); |
|
509 |
|
510 <font color=#3F5FBF>/** |
|
511 * Get context properties. |
|
512 * <font color=#7F9FBF>@return</font> all available context properties. |
|
513 */</font> |
|
514 Map<String,Object> getProperties(); |
|
515 |
|
516 <font color=#3F5FBF>/** |
|
517 * Set target memory. |
|
518 * If 'word_size' is 0 it means client does not care about word size. |
|
519 */</font> |
|
520 <font color=#7F0055>void</font> set(long addr, <font color=#7F0055>int</font> word_size, byte[] buf, |
|
521 <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); |
|
522 |
|
523 <font color=#3F5FBF>/** |
|
524 * Read target memory. |
|
525 */</font> |
|
526 <font color=#7F0055>void</font> get(long addr, <font color=#7F0055>int</font> word_size, byte[] buf, |
|
527 <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); |
|
528 |
|
529 <font color=#3F5FBF>/** |
|
530 * Fill target memory with given pattern. |
|
531 * 'size' is number of bytes to fill. |
|
532 */</font> |
|
533 <font color=#7F0055>void</font> fill(long addr, <font color=#7F0055>int</font> word_size, byte[] value, |
|
534 <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); |
|
535 } |
|
536 |
|
537 <font color=#3F5FBF>/** |
|
538 * Client callback interface for set(), get() and fill(). |
|
539 */</font> |
|
540 <font color=#7F0055>interface</font> DoneMemory { |
|
541 <font color=#7F0055>void</font> doneMemory(MemoryError error); |
|
542 } |
|
543 |
|
544 <font color=#7F0055>class</font> MemoryError <font color=#7F0055>extends</font> Exception { |
|
545 } |
|
546 |
|
547 <font color=#3F5FBF>/** |
|
548 * ErrorOffset interface can be implemented by MemoryError object, |
|
549 * which is returned by get, set and fill commands. |
|
550 * |
|
551 * get/set/fill () returns this exception when reading failed |
|
552 * for some but not all bytes, and MODE_CONTINUEONERROR |
|
553 * has been set in mode. (For example, when only part of the request |
|
554 * translates to valid memory addresses.) |
|
555 * Exception.getMessage can be used for generalized message of the |
|
556 * possible reasons of partial memory operation. |
|
557 */</font> |
|
558 <font color=#7F0055>interface</font> ErrorOffset { |
|
559 |
|
560 // Error may have per byte information |
|
561 <font color=#7F0055>final static int</font> |
|
562 BYTE_VALID = 0x00, |
|
563 BYTE_UNKNOWN = 0x01, // e.g. out of range |
|
564 BYTE_INVALID = 0x02, |
|
565 BYTE_CANNOT_READ = 0x04, |
|
566 BYTE_CANNOT_WRITE = 0x08; |
|
567 |
|
568 <font color=#7F0055>int</font> getStatus(<font color=#7F0055>int</font> offset); |
|
569 |
|
570 <font color=#3F5FBF>/** |
|
571 * Returns the detail message string about the |
|
572 * byte associated with specified location. |
|
573 * <font color=#7F9FBF>@return</font> the detail error message string. |
|
574 */</font> |
|
575 String getMessage(<font color=#7F0055>int</font> offset); |
|
576 |
|
577 } |
|
578 |
|
579 <font color=#3F5FBF>/** |
|
580 * Add memory service event listener. |
|
581 * <font color=#7F9FBF>@param</font> listener - event listener implementation. |
|
582 */</font> |
|
583 <font color=#7F0055>void</font> addListener(MemoryListener listener); |
|
584 |
|
585 <font color=#3F5FBF>/** |
|
586 * Remove memory service event listener. |
|
587 * <font color=#7F9FBF>@param</font> listener - event listener implementation. |
|
588 */</font> |
|
589 <font color=#7F0055>void</font> removeListener(MemoryListener listener); |
|
590 |
|
591 <font color=#3F5FBF>/** |
|
592 * Memory event listener is notified when memory context hierarchy |
|
593 * changes, and when memory is modified by memory service commands. |
|
594 */</font> |
|
595 <font color=#7F0055>interface</font> MemoryListener { |
|
596 |
|
597 <font color=#3F5FBF>/** |
|
598 * Called when a new memory access context(s) is created. |
|
599 */</font> |
|
600 <font color=#7F0055>void</font> contextAdded(Context[] contexts); |
|
601 |
|
602 <font color=#3F5FBF>/** |
|
603 * Called when a new memory access context(s) properties changed. |
|
604 */</font> |
|
605 <font color=#7F0055>void</font> contextChanged(Context[] contexts); |
|
606 |
|
607 <font color=#3F5FBF>/** |
|
608 * Called when memory access context(s) is removed. |
|
609 */</font> |
|
610 <font color=#7F0055>void</font> contextRemoved(String[] context_ids); |
|
611 |
|
612 <font color=#3F5FBF>/** |
|
613 * Called when target memory content was changed and clients |
|
614 * need to update themselves. Clients, at least, should invalidate |
|
615 * corresponding cached memory data. |
|
616 * Not every change is notified - it is not possible, |
|
617 * only those, which are not caused by normal execution of the debuggee. |
|
618 * ‘addr’ and ‘size’ can be null if unknown. |
|
619 */</font> |
|
620 <font color=#7F0055>void</font> memoryChanged(String context_id, |
|
621 long[] addr, long[] size); |
|
622 } |
|
623 } |
|
624 </pre> |
|
625 |
|
626 </body> |
|
627 </html> |