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 it's 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 from the C object at the supplied address
350 *
351 * The type of the object is also supplied by the user. There is no
352 * checking whether the object at that address is of the supplied type.
353 * By default, only one instance of the specified type will be fetched
354 * from the address.
355 *
356 * @param(addr) Address of the C object
357 * @param(typeName) Name of the C type read from the address
358 * @param(count) Number of C objects read from the address
359 *
360 * @a(Returns) JavaScript representation of the object at the address
361 */
362 Any fetchFromAddr(Ptr addr, String typename, Int count = 1);
363
364 /*!
365 * ======== fetchVariable ========
366 * Returns a JavaScript object or a scalar that mirrors the content of the
367 * variable.
368 *
369 * This function replicates primitive or aggregate objects from memory,
370 * and returns them as JavaScript objects. If the variable is an array or
371 * a structure, its corresponding JavaScript elements can be accessed as
372 * JavaScript arrays or structures.
373 * Pointers are not followed, but they are represented as hexadecimal
374 * values.
375 *
376 * If the variable is not found in the object file, an exception is raised.
377 *
378 * @param(varName) name of the variable
379 *
380 * @a(Returns) content of the variable
381 */
382 Any fetchVariable(String varName);
383
384 /*!
385 * ======== fetchVariableByPtr ========
386 * Returns a JavaScript representation of a C object or a scalar pointed to
387 * by the supplied pointer variable.
388 *
389 * This API first checks if there is such a variable, and if it is of a
390 * pointer type. If any of these checks fails, 'null' is returned.
391 * Otherwise, the pointer variable is dereferenced, and the memory content
392 * is interpreted as a pointed-to type.
393 */
394 Any fetchVariableByPtr(String varName);
395
396 /*!
397 * ======== createObject ========
398 * Creates a JavaScript object that mirrors an object from memory.
399 *
400 * @param(addr) address of the object in memory
401 * @param(type) type specification for the object from memory
402 * @param(ret) already created object to which a new object is added
403 * @param(name) name for the new object
404 */
405 Void createObject(Ptr addr, Any typespec, Any ret, String name);
406
407 /*!
408 * ======== readMemory ========
409 * Reads a primitive value from memory.
410 *
411 * @param(addr) memory address
412 * @param(size) size in MAUs
413 * @param(enc) encoding (signed or unsigned)
414 */
415 Any readMemory(Ptr addr, UInt size, Int enc);
416
417 /*!
418 * ======== getModuleConfig ========
419 * Get a module's configuration state
420 *
421 * Returns an object with all of the module configuration values used
422 * in configuring the application.
423 *
424 * This object includes the common$ config params.
425 *
426 * @param(modName) Full module name to get the configs for.
427 *
428 * @a(Returns) Object containing all of the module configs and
429 * their values.
430 */
431 Any getModuleConfig(String modName);
432
433 /*!
434 * ======== getPrivateData ========
435 * Retrieves module's private ROV data.
436 *
437 * This API returns an object which can be used to store private data
438 * across different ROV API calls. The object is reset at every
439 * breakpoint.
440 *
441 * This object is also passed as the context to all view init functions,
442 * so it can also be accessed using 'this'. However, the context changes
443 * when you call other APIs in your module; that is when you will need
444 * this API. It can also be used to support metaonly APIs which are called
445 * by other modules.
446 */
447 Any getPrivateData(String modName);
448
449 /*!
450 * ======== lookupDataSymbol ========
451 * Lookup symbolic names for an address
452 *
453 * Uses the ISymbolTable to look up the symbols at the given address.
454 *
455 * This API is separate from lookupFuncName to address paging concerns.
456 * Use lookupFuncName to get function names (or any symbols in PROGRAM
457 * memory) and use lookupDataSymbol to get data symbols (for symbols in
458 * DATA memory).
459 *
460 * @param(addr) Address of symbols
461 *
462 * @a(Returns) Array of symbols at the requested address.
463 */
464 Any lookupDataSymbol(Int addr);
465
466 /*!
467 * ======== lookupFuncName ========
468 * Lookup function names for an address.
469 *
470 * Uses the ISymbolTable to look up the symbols at the given address.
471 *
472 * This API is separate from lookupDataSymbol to address paging concerns.
473 * Use lookupFuncName to get function names (or any symbols in PROGRAM
474 * memory) and use lookupDataSymbol to get data symbols (for symbols in
475 * DATA memory).
476 *
477 * @param(addr) Address of symbols
478 *
479 * @a(Returns) Array of symbols at the requested address.
480 */
481 Any lookupFuncName(Int addr);
482
483 /*!
484 * ======== lookupType ========
485 * Creates a type specification from the Dwarf data.
486 *
487 * @param(type) type name
488 */
489 Any lookupType(String type);
490
491 /*!
492 * ======== lookupTypeByVariable ========
493 * Creates a type specification from the Dwarf data for a variable.
494 *
495 * @param(varName) variable name
496 */
497 Any lookupTypeByVariable(String varName);
498
499 /*!
500 * ======== lookupSymbolValue ========
501 * Returns the value for the given symbol.
502 *
503 * Returns -1 if the symbol does not exist.
504 *
505 * @param(symName) Name of symbol
506 *
507 * @a(Returns) Address or value of symbol, or -1 if symbol does not exist
508 */
509 Int lookupSymbolValue(String symName);
510
511 /*!
512 * ======== getSymbolValue ========
513 * Returns the value for the given symbol.
514 *
515 * Returns -1 if the symbol does not exist.
516 *
517 * @param(symName) Name of symbol
518 *
519 * @a(Returns) Address or value of symbol, or -1 if symbol does not exist
520 */
521 Int getSymbolValue(String symName);
522
523 /*!
524 * ======== displayError ========
525 *
526 */
527 Void displayError(Any view, String fieldName, String errorMsg);
528
529 /*!
530 * ======== ptrToHex ========
531 * Convert pointer representation to hex string
532 *
533 * Convenience function for converting the 'at' symbol representation
534 * of a pointer to the form 0x80005846.
535 */
536 String ptrToHex(Any ptr);
537
538 /*!
539 * ======== getShortName ========
540 * Convert canonical instance names to a short name
541 *
542 * Parses the full canonical instance name for the shorter name given
543 * by the user. If there is no shorter name, then it returns an empty
544 * string "".
545 *
546 * @param(name) Full canonical instance name.
547 *
548 * @a(Returns) The short name, if the user specified one. Empty string
549 * otherwise.
550 */
551 String getShortName(String name);
552
553 /*!
554 * ======== debugPrint ========
555 * Print API which will only print the message if debug printing is
556 * enabled.
557 */
558 Void debugPrint(String msg);
559
560 /*!
561 * ======== timestamp ========
562 * API for printing timestamp messages for performance analysis.
563 */
564 Void timestamp(String msg);
565
566 /*!
567 * ======== setTimestampFunc ========
568 * Sets API to be used for printing timestamp.
569 */
570 Void setTimestampFunc(Any func);
571
572 /*!
573 * ======== newViewStruct ========
574 * Creates a new instance of the view structure for the specified view.
575 *
576 * This API is called for views where the view structure is not already
577 * passed in as an argument to the view init function.
578 *
579 * It is necessary to instantiate a view structure in this way so that ROV
580 * is given an opportunity to initialize the status-reporting mechanisms
581 * of the view structure (to support, e.g., Program.displayError).
582 */
583 Any newViewStruct(String modName, String tabName);
584
585 /*!
586 * ======== StatusEntry ========
587 * Single entry in the ROV status table.
588 *
589 * ROV maintains a table of all errors, warnings, etc. encountered while
590 * processing views. This table is cleared on each call to clear cache
591 * (e.g., at each breakpoint).
592 */
593 metaonly struct StatusEntry {
594 String mod;
595 String tab;
596 String inst;
597 String field;
598 String message;
599 }
600
601 /*!
602 * ======== getStatusTable ========
603 * Returns the current table of all encountered status messages.
604 *
605 * This table is reset with every call to 'resetMods'. (e.g., at every
606 * breakpoint).
607 */
608 Any getStatusTable();
609
610
611
612 /*!
613 * @_nodoc
614 * ======== moduleNames ========
615 * Array of all the module names in the application.
616 */
617 readonly config String moduleNames[length];
618
619 /*!
620 * @_nodoc
621 * ======== getModuleDesc ========
622 * Used to retrieve the module descriptor object for the requested module.
623 */
624 ROVModuleDesc *getModuleDesc(String modName);
625
626 /*!
627 * @_nodoc
628 * ======== getViewType ========
629 * This is a helper method which returns whether a given tabName is a
630 * module-level view, instance-level view, or raw view.
631 */
632 String getViewType(String modName, String tabName);
633
634 /*!
635 * @_nodoc
636 * ======== Tab ========
637 * The type is an enum, but we can't use an enum from another module,
638 * so just use the String value of the type.
639 */
640 metaonly struct Tab {
641 String name;
642 String type;
643 }
644
645 /*!
646 * @_nodoc
647 * ======== Tabs ========
648 */
649 typedef Tab Tabs[];
650
651 /*!
652 * @_nodoc
653 * ======== getSupportedTabs ========
654 * Returns a string array of the tab names supported by the module.
655 */
656 Tabs getSupportedTabs(String modName);
657
658 /*!
659 * @_nodoc
660 * ======== addCMod ========
661 */
662 Void addCMod(Any mod);
663
664 /*!
665 * @_nodoc
666 * ======== getAbortFlag ========
667 * In CCS, indicates whether the abort flag has been set.
668 */
669 Bool getAbortFlag();
670
671 /*!
672 * @_nodoc
673 * ======== resetMods ========
674 * Used to clear the cache of all scanned data and views. Should be called
675 * whenever the target data has changed.
676 */
677 Void resetMods();
678
679 /*!
680 * @_nodoc
681 * ======== setThrowViewErrors ========
682 * Used to enable/disable exceptions when views detect errors
683 */
684 Void setThrowViewErrors(Bool flag);
685
686 /*!
687 * @_nodoc
688 * ======== moduleIdToName ========
689 * Used by xdc.runtime.Log.decode
690 */
691 String moduleIdToName(Int mid);
692
693 /*!
694 * ======== exToString ========
695 * Helper function for formatting exceptions into strings with filename
696 * and line number.
697 */
698 String exToString(Any e);
699
700 /*!
701 * @_nodoc
702 * ========= ROVModuleDesc ========
703 * Structure containing all ROV-related data about an individual module.
704 *
705 * An instance of this structure is created for each module in the system.
706 * As various Program.scan APIs are called, this structure is gradually
707 * filled in with data.
708 *
709 * The structure's fields:
710 * name The module's name
711 * addr Address of the state object. Redundant with state.$addr,
712 * but available so that address is present even if fetch
713 * of state fails.
714 * loadFailed Indicates that the 'useModule' call on this module threw
715 * an exception.
716 * loadFailedMsg The exception message from the 'useModule' call
717 * cfg Object containing all of the mod's configuration values
718 * state Raw module state object
719 * instances Array of ROVInstanceDesc objects representing the mod's
720 * instances.
721 * objects Array of ROVInstanceDesc objects representing instances
722 * of the module which are embedded in other objects.
723 * viewMap Contains the module-level views. The key to the map is
724 * the string tab name for the view, and the value is the
725 * an instance of Module_View.
726 * errorMap For each view, contains any error that was encountered
727 * in processing the view outside of what was reported by
728 * the module. For example, an unhandled exception from the
729 * view code would be stored here.
730 */
731 metaonly struct ROVModuleDesc {
732 String name;
733 Any addr;
734 Bool loadFailed;
735 String loadFailedMsg;
736 Any cfg;
737 Any useMod;
738 Any viewInfo;
739 Any state;
740
741 Any staticInstAddrs[];
742 Any dynInstAddrs[];
743 Bool readAllAddrs;
744
745 ROVInstanceDesc *instances[];
746 Any viewMap[string];
747 String errorMap[string];
748
749 String error;
750
751 Any instMap;
752
753 Any userPrivate;
754 };
755
756 /*!
757 * @_nodoc
758 * ========= ROVInstanceDesc ========
759 * Structure containing all ROV-related data about an individual instance.
760 *
761 * The ROVInstanceDesc objects are stored in the 'instances' array of the
762 * respective module's ROVModuleDesc structure.
763 *
764 * The structure's fields:
765 * state Raw instance state object
766 * addr Address of the state object. Redundant with state.$addr,
767 * but available so that address is present even if fetch of
768 * statefails.
769 * viewMap Contains the instance-level views. The key to the map is
770 * the string tab name for the view, and the value is the
771 * an instance of Instance_View.
772 * errorMap For each view, contains any error that was encountered
773 * in processing the view outside of what was reported by
774 * the module. For example, an unhandled exception from the
775 * view code would be stored here.
776 */
777 metaonly struct ROVInstanceDesc {
778 Any state;
779 Any addr;
780 Any viewMap[string];
781 String errorMap[string];
782
783 String error;
784 };
785
786 }
787 788 789
790