1 2 3 4 5 6 7 8 9 10 11
12
13 /*!
14 * ======== Program ========
15 * Root object for the ROV model
16 *
17 * This module is the main access point for all ROV operations.
18 * The Program APIs are used to retrieve the views for the
19 * requested modules.
20 */
21 metaonly module Program {
22
23 /*!
24 * ======== FetchDesc ========
25 * Description of data to fetch
26 *
27 * A FetchDesc object is required as the first argument of the
28 * `{@link #fetchStruct}` and `{@link #fetchArray}` methods.
29 * The FetchDesc tells ROV the type of the data to be
30 * fetched so it knows how much data to read and how to decode it.
31 *
32 * Every reference-type field in a state structure has a FetchDesc
33 * generated for it, with the name `<field name>$fetchDesc`.
34 *
35 * For example, the instance structure
36 * @p(code)
37 * struct Instance_State {
38 * Char stack[];
39 * ];
40 * @p
41 * will have defined `obj.stack$fetchDesc`, which can be used to fetch
42 * the array:
43 * @p(code)
44 * var data = Program.fetchArray(obj.stack$fetchDesc, obj.stack, len);
45 * @p
46 *
47 * @field(type) the fully qualified name of a specified type; i.e.,
48 * a type declared in some .xdc file. For example,
49 * "xdc.runtime.Types.Timestamp64".
50 * @field(isScalar) if fetching an array, are the elements of the array
51 * really just one of the "scalar structs" defined by
52 * xdc.rov.support.ScalarStructs.
53 *
54 * @see #fetchStruct
55 * @see #fetchArray
56 */
57 metaonly struct FetchDesc {
58 String type;
59 Bool isScalar;
60 }
61
62 /*!
63 * ======== InstDataView ========
64 * Instance view data returned from a scan
65 *
66 * @see #scanInstanceDataView
67 */
68 metaonly struct InstDataView {
69 String label;
70 Any elements[];
71 }
72
73 /*!
74 * ======== InstDataViewArr ========
75 * Array of all instance view data objects
76 *
77 * @see #scanInstanceDataView
78 */
79 typedef InstDataView InstDataViewArr[];
80
81 /*!
82 * ======== ModDataView ========
83 * Module view data returned from a scan
84 *
85 * @see #scanModuleDataView
86 */
87 metaonly struct ModDataView {
88 Any elements[];
89 }
90
91 /*!
92 * ======== TreeNode ========
93 * Node for a generic "tree table" view
94 *
95 * @see #scanTreeTableView
96 * @see ViewInfo#TREE_TABLE
97 */
98 metaonly struct TreeNode {
99 String label;
100 TreeNode children[];
101 Any properties[];
102 }
103
104 /*!
105 * ======== TreeNodeArr ========
106 * Array of tree table nodes
107 *
108 * @see #scanTreeTableView
109 * @see ViewInfo#TREE_TABLE
110 */
111 typedef TreeNode TreeNodeArr[];
112
113 /*!
114 * ========= RawView ========
115 * Raw module view
116 *
117 * This is the structure returned by the `{@link scanRawView}` method.
118 * It contains the module's state, the instance states, and the module
119 * configuration fields and values.
120 */
121 metaonly struct RawView {
122 Any modState;
123 Any instStates[];
124 Any modCfg;
125 }
126
127
128
129 /*!
130 * ======== scanInstanceView ========
131 * Retrieve the instance-type views for a module
132 *
133 * Returns an array of Instance_View structures, each structure
134 * representing an instance of the module.
135 *
136 * @param(modName) Full module name to return the views for.
137 * @param(tabName) Name of the tab to retrieve the views for.
138 *
139 * @a(Returns) Array of Instance_View structures, one for each isntance.
140 */
141 Any scanInstanceView(String modName, String tabName);
142
143 /*!
144 * ======== scanModuleView ========
145 * Retrieve module-type view for a module.
146 *
147 * @param(modName) Full module name to return the view for.
148 * @param(tabName) Name of the tab to retreive the view for.
149 *
150 * @(returns) Module_View structure.
151 */
152 Any scanModuleView(String modName, String tabName);
153
154 /*!
155 * ======== scanInstanceDataView ========
156 *
157 */
158 InstDataViewArr scanInstanceDataView(String modName, String tabName);
159
160 /*!
161 * ======== scanModuleDataView ========
162 *
163 */
164 ModDataView scanModuleDataView(String modName, String tabName);
165
166 /*!
167 * ======== scanRawView ========
168 * Retrieve the raw view for a module.
169 *
170 * @param(modName) Full module name to return the raw view for.
171 *
172 * @(returns) A RawView structure which contains the raw data.
173 */
174 RawView scanRawView(String modName);
175
176 /*!
177 * ======== scanTreeTableView ========
178 */
179 TreeNodeArr scanTreeTableView(String modName, String tabName);
180
181 /*!
182 * ======== scanTreeView ========
183 */
184 Any scanTreeView(String modName, String tabName);
185
186 /*!
187 * ======== scanHandle ========
188 * Scan single instance of a module
189 *
190 * Used from a view$init function to scan a single instance of a
191 * different module given that instance's address.
192 *
193 * @param(modName) Full module name to return the raw view for.
194 * @param(instAddr) Address of instance to scan.
195 * @param(tabName) Name of the tab to retrieve the view for.
196 *
197 * @a(Returns) An Instance_View object for the requested view.
198 */
199 Any scanHandleView(String modName, Ptr instAddr, String tabName);
200
201 /*!
202 * ======== scanObjectView ========
203 * Scan view for an embedded object
204 *
205 * Called from a view$init function to retrieve the specified view for
206 * an embedded object.
207 *
208 * Since XDC has no way of knowing what embedded objects are present in
209 * a system, embedded objects do not appear in the list of a module's
210 * instances until they have been scanned in this way.
211 *
212 * Calling Program.scanObjectView will not read any additional data from
213 * the target, since the state structure was already read as part of
214 * reading it's parent structure.
215 *
216 * @param(modName) Full module name to return the view for.
217 * @param(obj) Actual object to retrieve the view for.
218 * @param(tabName) Name of the tab to retrieve the view for.
219 *
220 * @a(Returns) An Instance_View object for the requested view.
221 */
222 Any scanObjectView(String modName, Any obj, String tabName);
223
224
225
226
227 /*!
228 * ======== fetchStruct ========
229 * Retrieve the specified structure from the target
230 *
231 * @param(desc) Fetch descriptor for the structure, indicating the type
232 * of the structure.
233 * @param(addr) Address of the structure to fetch.
234 * @param(addrCheck) Optional, defaults to true. Indicates whether the
235 * memory image should validate the read by comparing
236 * the address to section information.
237 *
238 * @a(Returns) Returns the requested structure as a javascript object.
239 */
240 Any fetchStruct(FetchDesc desc, Ptr addr, Bool addrCheck = true);
241
242 /*!
243 * ======== fetchArray ========
244 * Retrieve the specified array from the target
245 *
246 * @param(desc) Fetch descriptor for the array, indicating the type of
247 * data in the array.
248 * @param(addr) Address of the array to fetch.
249 * @param(length) The number of arrray elements to fetch.
250 * @param(addrCheck) Optional, defaults to true. Indicates whether the
251 * memory image should validate the read by comparing
252 * the address to section information.
253 *
254 * @a(Returns) Returns a JavaScript array with the data in it.
255 */
256 Any fetchArray(FetchDesc desc, Ptr addr, Int len, Bool addrCheck = true);
257
258 /*!
259 * ======== fetchString ========
260 * Retrieve a string from the target
261 *
262 * @param(addr) Address of the string.
263 * @param(addrCheck) Optional, defaults to true. Indicates whether the
264 * memory image should validate the read by comparing
265 * the address to section information.
266 *
267 * @a(Returns) Requested string.
268 */
269 String fetchString(Ptr addr, Bool addrCheck = true);
270
271 /*!
272 * ======== fetchStaticString ========
273 * Retrieves a static string from the executable.
274 *
275 * This API makes use of an object file reader to improve the string
276 * reading performance--it reads the string from the file rather than
277 * performing a target memory read. For this reason, it should only be
278 * used on static strings and not dynamic ones.
279 *
280 * @param(addr) Address of the string.
281 *
282 * @a(Returns) Requested string.
283 */
284 String fetchStaticString(Ptr addr);
285
286 /*!
287 * ======== getModuleConfig ========
288 * Get a module's configuration state
289 *
290 * Returns an object with all of the module configuration values used
291 * in configuring the application.
292 *
293 * This object includes the common$ config params.
294 *
295 * @param(modName) Full module name to get the configs for.
296 *
297 * @a(Returns) Object containing all of the module configs and
298 * their values.
299 */
300 Any getModuleConfig(String modName);
301
302 /*!
303 * ======== getPrivateData ========
304 * Retrieves module's private ROV data.
305 *
306 * This API returns an object which can be used to store private data
307 * across different ROV API calls. The object is reset at every
308 * breakpoint.
309 *
310 * This object is also passed as the context to all view init functions,
311 * so it can also be accessed using 'this'. However, the context changes
312 * when you call other APIs in your module; that is when you will need
313 * this API. It can also be used to support metaonly APIs which are called
314 * by other modules.
315 */
316 Any getPrivateData(String modName);
317
318 /*!
319 * ======== lookupDataSymbol ========
320 * Lookup symbolic names for an address
321 *
322 * Uses the ISymbolTable to look up the symbols at the given address.
323 *
324 * This API is separate from lookupFuncName to address paging concerns.
325 * Use lookupFuncName to get function names (or any symbols in PROGRAM
326 * memory) and use lookupDataSymbol to get data symbols (for symbols in
327 * DATA memory).
328 *
329 * @param(addr) Address of symbols
330 *
331 * @a(Returns) Array of symbols at the requested address.
332 */
333 Any lookupDataSymbol(Int addr);
334
335 /*!
336 * ======== lookupFuncName ========
337 * Lookup function names for an address.
338 *
339 * Uses the ISymbolTable to look up the symbols at the given address.
340 *
341 * This API is separate from lookupDataSymbol to address paging concerns.
342 * Use lookupFuncName to get function names (or any symbols in PROGRAM
343 * memory) and use lookupDataSymbol to get data symbols (for symbols in
344 * DATA memory).
345 *
346 * @param(addr) Address of symbols
347 *
348 * @a(Returns) Array of symbols at the requested address.
349 */
350 Any lookupFuncName(Int addr);
351
352 /*!
353 * ======== getSymbolValue ========
354 * Returns the value for the given symbol.
355 *
356 * Returns -1 if the symbol does not exist.
357 *
358 * @param(symName) Name of symbol
359 *
360 * @a(Returns) Address or value of symbol, or -1 if symbol does not exist
361 */
362 Int getSymbolValue(String symName);
363
364 /*!
365 * ======== displayError ========
366 *
367 */
368 Void displayError(Any view, String fieldName, String errorMsg);
369
370 /*!
371 * ======== ptrToHex ========
372 * Convert pointer representation to hex string
373 *
374 * Convenience function for converting the 'at' symbol representation
375 * of a pointer to the form 0x80005846.
376 */
377 String ptrToHex(Any ptr);
378
379 /*!
380 * ======== getShortName ========
381 * Convert canonical instance names to a short name
382 *
383 * Parses the full canonical instance name for the shorter name given
384 * by the user. If there is no shorter name, then it returns an empty
385 * string "".
386 *
387 * @param(name) Full canonical instance name.
388 *
389 * @a(Returns) The short name, if the user specified one. Empty string
390 * otherwise.
391 */
392 String getShortName(String name);
393
394 /*!
395 * ======== debugPrint ========
396 * Print API which will only print the message if debug printing is
397 * enabled.
398 */
399 Void debugPrint(String msg);
400
401 /*!
402 * ======== timestamp ========
403 * API for printing timestamp messages for performance analysis.
404 */
405 Void timestamp(String msg);
406
407 /*!
408 * ======== setTimestampFunc ========
409 * Sets API to be used for printing timestamp.
410 */
411 Void setTimestampFunc(Any func);
412
413 /*!
414 * ======== newViewStruct ========
415 * Creates a new instance of the view structure for the specified view.
416 *
417 * This API is called for views where the view structure is not already
418 * passed in as an argument to the view init function.
419 *
420 * It is necessary to instantiate a view structure in this way so that ROV
421 * is given an oppportunity to initialize the status-reporting mechanisms
422 * of the view structure (to support, e.g., Program.displayError).
423 */
424 Any newViewStruct(String modName, String tabName);
425
426 /*!
427 * ======== StatusEntry ========
428 * Single entry in the ROV status table.
429 *
430 * ROV maintains a table of all errors, warnings, etc. encountered while
431 * processing views. This table is cleared on each call to clear cache
432 * (e.g., at each breakpoint).
433 */
434 metaonly struct StatusEntry {
435 String mod;
436 String tab;
437 String inst;
438 String field;
439 String message;
440 }
441
442 /*!
443 * ======== getStatusTable ========
444 * Returns the current table of all encountered status messages.
445 *
446 * This table is reset with every call to 'resetMods'. (e.g., at every
447 * breakpoint).
448 */
449 Any getStatusTable();
450
451
452
453 /*!
454 * @_nodoc
455 * ======== moduleNames ========
456 * Array of all the module names in the application.
457 */
458 readonly config String moduleNames[length];
459
460 /*!
461 * @_nodoc
462 * ======== getModuleDesc ========
463 * Used to retrieve the module descriptor object for the requested module.
464 */
465 ROVModuleDesc *getModuleDesc(String modName);
466
467 /*!
468 * @_nodoc
469 * ======== getViewType ========
470 * This is a helper method which returns whether a given tabName is a
471 * module-level view, instance-level view, or raw view.
472 */
473 String getViewType(String modName, String tabName);
474
475 /*!
476 * @_nodoc
477 * ======== Tab ========
478 * The type is an enum, but we can't use an enum from another module,
479 * so just use the String value of the type.
480 */
481 metaonly struct Tab {
482 String name;
483 String type;
484 }
485
486 /*!
487 * @_nodoc
488 * ======== Tabs ========
489 */
490 typedef Tab Tabs[];
491
492 /*!
493 * @_nodoc
494 * ======== getSupportedTabs ========
495 * Returns a string array of the tab names supported by the module.
496 */
497 Tabs getSupportedTabs(String modName);
498
499 /*!
500 * @_nodoc
501 * ======== getAbortFlag ========
502 * In CCS, indicates whether the abort flag has been set.
503 */
504 Bool getAbortFlag();
505
506 /*!
507 * @_nodoc
508 * ======== resetMods ========
509 * Used to clear the cache of all scanned data and views. Should be called
510 * whenever the target data has changed.
511 */
512 Void resetMods();
513
514 /*!
515 * @_nodoc
516 * ======== moduleIdToName ========
517 * Used by xdc.runtime.Log.decode
518 */
519 String moduleIdToName(Int mid);
520
521 /*!
522 * ======== exToString ========
523 * Helper function for formatting exceptions into strings with filename
524 * and line number.
525 */
526 String exToString(Any e);
527
528 /*!
529 * @_nodoc
530 * ========= ROVModuleDesc ========
531 * Structure containing all ROV-related data about an individual module.
532 *
533 * An instance of this structure is created for each module in the system.
534 * As various Program.scan APIs are called, this structure is gradually
535 * filled in with data.
536 *
537 * The structure's fields:
538 * name The module's name
539 * addr Address of the state object. Redundant with state.$addr,
540 * but available so that address is present even if fetch
541 * of state fails.
542 * loadFailed Indicates that the 'useModule' call on this module threw
543 * an exception.
544 * loadFailedMsg The exception message from the 'useModule' call
545 * cfg Object containing all of the mod's configuration values
546 * state Raw module state object
547 * instances Array of ROVInstanceDesc objects representing the mod's
548 * instances.
549 * objects Array of ROVInstanceDesc objects representing instances
550 * of the module which are embedded in other objects.
551 * viewMap Contains the module-level views. The key to the map is
552 * the string tab name for the view, and the value is the
553 * an instance of Module_View.
554 * errorMap For each view, contains any error that was encountered
555 * in processing the view outside of what was reported by
556 * the module. For example, an unhandled exception from the
557 * view code would be stored here.
558 */
559 metaonly struct ROVModuleDesc {
560 String name;
561 Any addr;
562 Bool loadFailed;
563 String loadFailedMsg;
564 Any cfg;
565 Any useMod;
566 Any viewInfo;
567 Any state;
568
569 Any staticInstAddrs[];
570 Any dynInstAddrs[];
571 Bool readAllAddrs;
572
573 ROVInstanceDesc *instances[];
574 Any viewMap[string];
575 String errorMap[string];
576
577 String error;
578
579 Any instMap;
580
581 Any userPrivate;
582 };
583
584 /*!
585 * @_nodoc
586 * ========= ROVInstanceDesc ========
587 * Structure containing all ROV-related data about an individual instance.
588 *
589 * The ROVInstanceDesc objects are stored in the 'instances' array of the
590 * respective module's ROVModuleDesc structure.
591 *
592 * The structure's fields:
593 * state Raw instance state object
594 * addr Address of the state object. Redundant with state.$addr,
595 * but available so that address is present even if fetch of
596 * statefails.
597 * viewMap Contains the instance-level views. The key to the map is
598 * the string tab name for the view, and the value is the
599 * an instance of Instance_View.
600 * errorMap For each view, contains any error that was encountered
601 * in processing the view outside of what was reported by
602 * the module. For example, an unhandled exception from the
603 * view code would be stored here.
604 */
605 metaonly struct ROVInstanceDesc {
606 Any state;
607 Any addr;
608 Any viewMap[string];
609 String errorMap[string];
610
611 String error;
612 };
613
614 }
615 616 617
618