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 * @a(Throws) Throws an exception in the event that a memory read of
142 * the specified instance view fails, the specified `tabName`
143 * isn't recognized, the specified `modName` doesn't support
144 * instances, or the module `modName` is not configured into
145 * the current program.
146 */
147 Any scanInstanceView(String modName, String tabName);
148
149 /*!
150 * ======== scanModuleView ========
151 * Retrieve module-type view for a module.
152 *
153 * @param(modName) Full module name to return the view for.
154 * @param(tabName) Name of the tab to retreive the view for.
155 *
156 * @(Returns) Module_View structure.
157 *
158 * @a(Throws) Throws an exception in the event that a memory read of
159 * the specified module view fails, the specified `tabName`
160 * isn't recognized, or the module `modName` is not
161 * configured into the current program.
162 */
163 Any scanModuleView(String modName, String tabName);
164
165 /*!
166 * ======== scanInstanceDataView ========
167 * Retrieve a module's specified INSTANCE_DATA type view
168 *
169 * @a(Throws) Throws an exception in the event that a memory read of
170 * the module's Raw view or any instance fails, the specified
171 * `tabName` isn't recognized, the specified `modName`
172 * doesn't support instances, or the module `modName` is not
173 * configured into the current program.
174 */
175 InstDataViewArr scanInstanceDataView(String modName, String tabName);
176
177 /*!
178 * ======== scanModuleDataView ========
179 * Retrieve a module's specified MODULE_DATA type view
180 *
181 * @a(Throws) Throws an exception in the event that a memory read of
182 * the specified module view fails, the specified `tabName`
183 * isn't recognized, or the module `modName` is not
184 * configured into the current program.
185 */
186 ModDataView scanModuleDataView(String modName, String tabName);
187
188 /*!
189 * ======== scanRawView ========
190 * Retrieve the raw view for a module.
191 *
192 * @param(modName) Full module name to return the raw view for.
193 *
194 * @(Returns) A RawView structure which contains the raw data.
195 *
196 * @a(Throws) Throws an exception in the event that a memory read of
197 * the specified instance view fails, the specified `tabName`
198 * isn't recognized, the specified `modName` doesn't support
199 * instances, or the module `modName` is not configured into
200 * the current program.
201 *
202 * @a(Throws) Throws an exception in the event that a memory read of
203 * the module's Raw view fails, or the module `modName` is
204 * not configured into the current program.
205 */
206 RawView scanRawView(String modName);
207
208 /*!
209 * ======== scanTreeTableView ========
210 */
211 TreeNodeArr scanTreeTableView(String modName, String tabName);
212
213 /*!
214 * ======== scanTreeView ========
215 */
216 Any scanTreeView(String modName, String tabName);
217
218 /*!
219 * ======== scanHandle ========
220 * Scan single instance of a module
221 *
222 * Used from a view$init function to scan a single instance of a
223 * different module given that instance's address.
224 *
225 * @param(modName) Full module name to return the raw view for.
226 * @param(instAddr) Address of instance to scan.
227 * @param(tabName) Name of the tab to retrieve the view for.
228 *
229 * @a(Returns) An Instance_View object for the requested view.
230 *
231 * @a(Throws) Throws an exception in the event that a memory read of
232 * the specified instance view fails, the specified `tabName`
233 * isn't recognized, the specified `modName` doesn't support
234 * instances, or the module `modName` is not configured into
235 * the current program.
236 */
237 Any scanHandleView(String modName, Ptr instAddr, String tabName);
238
239 /*!
240 * ======== scanObjectView ========
241 * Scan view for an embedded object
242 *
243 * Called from a view$init function to retrieve the specified view for
244 * an embedded object.
245 *
246 * Since XDC has no way of knowing what embedded objects are present in
247 * a system, embedded objects do not appear in the list of a module's
248 * instances until they have been scanned in this way.
249 *
250 * Calling Program.scanObjectView will not read any additional data from
251 * the target, since the state structure was already read as part of
252 * reading it's parent structure.
253 *
254 * @param(modName) Full module name to return the view for.
255 * @param(obj) Actual object to retrieve the view for.
256 * @param(tabName) Name of the tab to retrieve the view for.
257 *
258 * @a(Returns) An Instance_View object for the requested view.
259 *
260 * @a(Throws) Throws an exception in the event that the specified
261 * `tabName` isn't recognized, the specified `modName`
262 * doesn't support instances, or the module `modName` is not
263 * configured into the current program.
264 */
265 Any scanObjectView(String modName, Any obj, String tabName);
266
267
268
269
270 /*!
271 * ======== fetchStruct ========
272 * Retrieve the specified structure from the target
273 *
274 * @param(desc) Fetch descriptor for the structure, indicating the type
275 * of the structure.
276 * @param(addr) Address of the structure to fetch.
277 * @param(addrCheck) Optional, defaults to true. Indicates whether the
278 * memory image should validate the read by comparing
279 * the address to section information.
280 *
281 * @a(Returns) Returns the requested structure as a javascript object.
282 *
283 * @a(Throws) Throws an exception in the event that `addr` is not in
284 * the program's memory map or some error occurs that
285 * prevents memory from being read.
286 */
287 Any fetchStruct(FetchDesc desc, Ptr addr, Bool addrCheck = true);
288
289 /*!
290 * ======== fetchArray ========
291 * Retrieve the specified array from the target
292 *
293 * @param(desc) Fetch descriptor for the array, indicating the type of
294 * data in the array.
295 * @param(addr) Address of the array to fetch.
296 * @param(len) The number of arrray elements to fetch.
297 * @param(addrCheck) Optional, defaults to true. Indicates whether the
298 * memory image should validate the read by comparing
299 * the address to section information.
300 *
301 * @a(Returns) Returns a JavaScript array with the data in it.
302 *
303 * @a(Throws) Throws an exception in the event that `addr` is not in
304 * the program's memory map, some error occurs that
305 * prevents memory from being read, or if `len` = 0.
306 */
307 Any fetchArray(FetchDesc desc, Ptr addr, Int len, Bool addrCheck = true);
308
309 /*!
310 * ======== fetchString ========
311 * Retrieve a string from the target
312 *
313 * @param(addr) Address of the string.
314 * @param(addrCheck) Optional, defaults to true. Indicates whether the
315 * memory image should validate the read by comparing
316 * the address to section information.
317 *
318 * @a(Returns) Requested string.
319 *
320 * @a(Throws) Throws an exception in the event that `addr` is not in
321 * the program's memory map or some error occurs that
322 * prevents memory from being read.
323 */
324 String fetchString(Ptr addr, Bool addrCheck = true);
325
326 /*!
327 * ======== fetchStaticString ========
328 * Retrieves a static string from the executable.
329 *
330 * This API makes use of an object file reader to improve the string
331 * reading performance--it reads the string from the file rather than
332 * performing a target memory read. For this reason, it should only be
333 * used on static strings and not dynamic ones.
334 *
335 * @param(addr) Address of the string
336 *
337 * @a(Returns) Requested string or `null` if it can't be found.
338 */
339 String fetchStaticString(Ptr addr);
340
341 /*!
342 * ======== getModuleConfig ========
343 * Get a module's configuration state
344 *
345 * Returns an object with all of the module configuration values used
346 * in configuring the application.
347 *
348 * This object includes the common$ config params.
349 *
350 * @param(modName) Full module name to get the configs for.
351 *
352 * @a(Returns) Object containing all of the module configs and
353 * their values.
354 */
355 Any getModuleConfig(String modName);
356
357 /*!
358 * ======== getPrivateData ========
359 * Retrieves module's private ROV data.
360 *
361 * This API returns an object which can be used to store private data
362 * across different ROV API calls. The object is reset at every
363 * breakpoint.
364 *
365 * This object is also passed as the context to all view init functions,
366 * so it can also be accessed using 'this'. However, the context changes
367 * when you call other APIs in your module; that is when you will need
368 * this API. It can also be used to support metaonly APIs which are called
369 * by other modules.
370 */
371 Any getPrivateData(String modName);
372
373 /*!
374 * ======== lookupDataSymbol ========
375 * Lookup symbolic names for an address
376 *
377 * Uses the ISymbolTable to look up the symbols at the given address.
378 *
379 * This API is separate from lookupFuncName to address paging concerns.
380 * Use lookupFuncName to get function names (or any symbols in PROGRAM
381 * memory) and use lookupDataSymbol to get data symbols (for symbols in
382 * DATA memory).
383 *
384 * @param(addr) Address of symbols
385 *
386 * @a(Returns) Array of symbols at the requested address.
387 */
388 Any lookupDataSymbol(Int addr);
389
390 /*!
391 * ======== lookupFuncName ========
392 * Lookup function names for an address.
393 *
394 * Uses the ISymbolTable to look up the symbols at the given address.
395 *
396 * This API is separate from lookupDataSymbol to address paging concerns.
397 * Use lookupFuncName to get function names (or any symbols in PROGRAM
398 * memory) and use lookupDataSymbol to get data symbols (for symbols in
399 * DATA memory).
400 *
401 * @param(addr) Address of symbols
402 *
403 * @a(Returns) Array of symbols at the requested address.
404 */
405 Any lookupFuncName(Int addr);
406
407 /*!
408 * ======== getSymbolValue ========
409 * Returns the value for the given symbol.
410 *
411 * Returns -1 if the symbol does not exist.
412 *
413 * @param(symName) Name of symbol
414 *
415 * @a(Returns) Address or value of symbol, or -1 if symbol does not exist
416 */
417 Int getSymbolValue(String symName);
418
419 /*!
420 * ======== displayError ========
421 *
422 */
423 Void displayError(Any view, String fieldName, String errorMsg);
424
425 /*!
426 * ======== ptrToHex ========
427 * Convert pointer representation to hex string
428 *
429 * Convenience function for converting the 'at' symbol representation
430 * of a pointer to the form 0x80005846.
431 */
432 String ptrToHex(Any ptr);
433
434 /*!
435 * ======== getShortName ========
436 * Convert canonical instance names to a short name
437 *
438 * Parses the full canonical instance name for the shorter name given
439 * by the user. If there is no shorter name, then it returns an empty
440 * string "".
441 *
442 * @param(name) Full canonical instance name.
443 *
444 * @a(Returns) The short name, if the user specified one. Empty string
445 * otherwise.
446 */
447 String getShortName(String name);
448
449 /*!
450 * ======== debugPrint ========
451 * Print API which will only print the message if debug printing is
452 * enabled.
453 */
454 Void debugPrint(String msg);
455
456 /*!
457 * ======== timestamp ========
458 * API for printing timestamp messages for performance analysis.
459 */
460 Void timestamp(String msg);
461
462 /*!
463 * ======== setTimestampFunc ========
464 * Sets API to be used for printing timestamp.
465 */
466 Void setTimestampFunc(Any func);
467
468 /*!
469 * ======== newViewStruct ========
470 * Creates a new instance of the view structure for the specified view.
471 *
472 * This API is called for views where the view structure is not already
473 * passed in as an argument to the view init function.
474 *
475 * It is necessary to instantiate a view structure in this way so that ROV
476 * is given an opportunity to initialize the status-reporting mechanisms
477 * of the view structure (to support, e.g., Program.displayError).
478 */
479 Any newViewStruct(String modName, String tabName);
480
481 /*!
482 * ======== StatusEntry ========
483 * Single entry in the ROV status table.
484 *
485 * ROV maintains a table of all errors, warnings, etc. encountered while
486 * processing views. This table is cleared on each call to clear cache
487 * (e.g., at each breakpoint).
488 */
489 metaonly struct StatusEntry {
490 String mod;
491 String tab;
492 String inst;
493 String field;
494 String message;
495 }
496
497 /*!
498 * ======== getStatusTable ========
499 * Returns the current table of all encountered status messages.
500 *
501 * This table is reset with every call to 'resetMods'. (e.g., at every
502 * breakpoint).
503 */
504 Any getStatusTable();
505
506
507
508 /*!
509 * @_nodoc
510 * ======== moduleNames ========
511 * Array of all the module names in the application.
512 */
513 readonly config String moduleNames[length];
514
515 /*!
516 * @_nodoc
517 * ======== getModuleDesc ========
518 * Used to retrieve the module descriptor object for the requested module.
519 */
520 ROVModuleDesc *getModuleDesc(String modName);
521
522 /*!
523 * @_nodoc
524 * ======== getViewType ========
525 * This is a helper method which returns whether a given tabName is a
526 * module-level view, instance-level view, or raw view.
527 */
528 String getViewType(String modName, String tabName);
529
530 /*!
531 * @_nodoc
532 * ======== Tab ========
533 * The type is an enum, but we can't use an enum from another module,
534 * so just use the String value of the type.
535 */
536 metaonly struct Tab {
537 String name;
538 String type;
539 }
540
541 /*!
542 * @_nodoc
543 * ======== Tabs ========
544 */
545 typedef Tab Tabs[];
546
547 /*!
548 * @_nodoc
549 * ======== getSupportedTabs ========
550 * Returns a string array of the tab names supported by the module.
551 */
552 Tabs getSupportedTabs(String modName);
553
554 /*!
555 * @_nodoc
556 * ======== getAbortFlag ========
557 * In CCS, indicates whether the abort flag has been set.
558 */
559 Bool getAbortFlag();
560
561 /*!
562 * @_nodoc
563 * ======== resetMods ========
564 * Used to clear the cache of all scanned data and views. Should be called
565 * whenever the target data has changed.
566 */
567 Void resetMods();
568
569 /*!
570 * @_nodoc
571 * ======== setThrowViewErrors ========
572 * Used to enable/disable exceptions when views detect errors
573 */
574 Void setThrowViewErrors(Bool flag);
575
576 /*!
577 * @_nodoc
578 * ======== moduleIdToName ========
579 * Used by xdc.runtime.Log.decode
580 */
581 String moduleIdToName(Int mid);
582
583 /*!
584 * ======== exToString ========
585 * Helper function for formatting exceptions into strings with filename
586 * and line number.
587 */
588 String exToString(Any e);
589
590 /*!
591 * @_nodoc
592 * ========= ROVModuleDesc ========
593 * Structure containing all ROV-related data about an individual module.
594 *
595 * An instance of this structure is created for each module in the system.
596 * As various Program.scan APIs are called, this structure is gradually
597 * filled in with data.
598 *
599 * The structure's fields:
600 * name The module's name
601 * addr Address of the state object. Redundant with state.$addr,
602 * but available so that address is present even if fetch
603 * of state fails.
604 * loadFailed Indicates that the 'useModule' call on this module threw
605 * an exception.
606 * loadFailedMsg The exception message from the 'useModule' call
607 * cfg Object containing all of the mod's configuration values
608 * state Raw module state object
609 * instances Array of ROVInstanceDesc objects representing the mod's
610 * instances.
611 * objects Array of ROVInstanceDesc objects representing instances
612 * of the module which are embedded in other objects.
613 * viewMap Contains the module-level views. The key to the map is
614 * the string tab name for the view, and the value is the
615 * an instance of Module_View.
616 * errorMap For each view, contains any error that was encountered
617 * in processing the view outside of what was reported by
618 * the module. For example, an unhandled exception from the
619 * view code would be stored here.
620 */
621 metaonly struct ROVModuleDesc {
622 String name;
623 Any addr;
624 Bool loadFailed;
625 String loadFailedMsg;
626 Any cfg;
627 Any useMod;
628 Any viewInfo;
629 Any state;
630
631 Any staticInstAddrs[];
632 Any dynInstAddrs[];
633 Bool readAllAddrs;
634
635 ROVInstanceDesc *instances[];
636 Any viewMap[string];
637 String errorMap[string];
638
639 String error;
640
641 Any instMap;
642
643 Any userPrivate;
644 };
645
646 /*!
647 * @_nodoc
648 * ========= ROVInstanceDesc ========
649 * Structure containing all ROV-related data about an individual instance.
650 *
651 * The ROVInstanceDesc objects are stored in the 'instances' array of the
652 * respective module's ROVModuleDesc structure.
653 *
654 * The structure's fields:
655 * state Raw instance state object
656 * addr Address of the state object. Redundant with state.$addr,
657 * but available so that address is present even if fetch of
658 * statefails.
659 * viewMap Contains the instance-level views. The key to the map is
660 * the string tab name for the view, and the value is the
661 * an instance of Instance_View.
662 * errorMap For each view, contains any error that was encountered
663 * in processing the view outside of what was reported by
664 * the module. For example, an unhandled exception from the
665 * view code would be stored here.
666 */
667 metaonly struct ROVInstanceDesc {
668 Any state;
669 Any addr;
670 Any viewMap[string];
671 String errorMap[string];
672
673 String error;
674 };
675
676 }
677 678 679
680