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