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