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