1    /* 
     2     *  Copyright (c) 2008 Texas Instruments and others.
     3     *  All rights reserved. This program and the accompanying materials
     4     *  are made available under the terms of the Eclipse Public License v1.0
     5     *  which accompanies this distribution, and is available at
     6     *  http://www.eclipse.org/legal/epl-v10.html
     7     * 
     8     *  Contributors:
     9     *      Texas Instruments - initial implementation
    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        /* -------- Scan Functions -------- */
   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        /* -------- Fetch Functions -------- */
   269        
   270        /*!
   271         *  ======== fetchStruct ========
   272         *  Retrieve the specified structure from the target
   273         *
   274         *  @param(desc) Fetch descriptor for the structure, indicating the type
   275         *               of the structure.
   276         *  @param(addr) Address of the structure to fetch.
   277         *  @param(addrCheck)  Optional, defaults to true. Indicates whether the
   278         *                     memory image should validate the read by comparing
   279         *                     the address to section information.
   280         *
   281         *  @a(Returns)  Returns the requested structure as a javascript object.
   282         *
   283         *  @a(Throws)  Throws an exception in the event that `addr` is not in
   284         *              the program's memory map or some error occurs that
   285         *              prevents memory from being read.
   286         */
   287        Any fetchStruct(FetchDesc desc, Ptr addr, Bool addrCheck = true);
   288        
   289        /*!
   290         *  ======== fetchArray ========
   291         *  Retrieve the specified array from the target
   292         *
   293         *  @param(desc) Fetch descriptor for the array, indicating the type of
   294         *               data in the array.
   295         *  @param(addr) Address of the array to fetch.
   296         *  @param(len)  The number of arrray elements to fetch.
   297         *  @param(addrCheck)  Optional, defaults to true. Indicates whether the
   298         *                     memory image should validate the read by comparing
   299         *                     the address to section information.
   300         *
   301         *  @a(Returns)  Returns a JavaScript array with the data in it.
   302         *
   303         *  @a(Throws)   Throws an exception in the event that `addr` is not in
   304         *               the program's memory map, some error occurs that
   305         *               prevents memory from being read, or if `len` = 0.
   306         */
   307        Any fetchArray(FetchDesc desc, Ptr addr, Int len, Bool addrCheck = true);
   308        
   309        /*!
   310         *  ======== fetchString ========
   311         *  Retrieve a string from the target
   312         *
   313         *  @param(addr) Address of the string.
   314         *  @param(addrCheck)  Optional, defaults to true. Indicates whether the
   315         *                     memory image should validate the read by comparing
   316         *                     the address to section information.
   317         *
   318         *  @a(Returns)  Requested string.
   319         *
   320         *  @a(Throws)   Throws an exception in the event that `addr` is not in
   321         *               the program's memory map or some error occurs that
   322         *               prevents memory from being read.
   323         */
   324        String fetchString(Ptr addr, Bool addrCheck = true);
   325        
   326        /*!
   327         *  ======== fetchStaticString ========
   328         *  Retrieves a static string from the executable.
   329         *
   330         *  This API makes use of an object file reader to improve the string
   331         *  reading performance--it reads the string from the file rather than
   332         *  performing a target memory read. For this reason, it should only be
   333         *  used on static strings and not dynamic ones.
   334         *
   335         *  @param(addr)  Address of the string
   336         *
   337         *  @a(Returns)  Requested string or `null` if it can't be found.
   338         */
   339        String fetchStaticString(Ptr addr);
   340        
   341        /*!
   342         *  ======== getModuleConfig ========
   343         *  Get a module's configuration state
   344         *
   345         *  Returns an object with all of the module configuration values used
   346         *  in configuring the application.
   347         *
   348         *  This object includes the common$ config params.
   349         *
   350         *  @param(modName) Full module name to get the configs for.
   351         *  
   352         *  @a(Returns)     Object containing all of the module configs and
   353         *                  their values.
   354         */
   355        Any getModuleConfig(String modName);
   356        
   357        /*!
   358         *  ======== getPrivateData ========
   359         *  Retrieves module's private ROV data.
   360         *  
   361         *  This API returns an object which can be used to store private data
   362         *  across different ROV API calls. The object is reset at every
   363         *  breakpoint.
   364         *
   365         *  This object is also passed as the context to all view init functions,
   366         *  so it can also be accessed using 'this'. However, the context changes
   367         *  when you call other APIs in your module; that is when you will need
   368         *  this API. It can also be used to support metaonly APIs which are called
   369         *  by other modules.
   370         */
   371        Any getPrivateData(String modName);
   372        
   373        /*!
   374         *  ======== lookupDataSymbol ========
   375         *  Lookup symbolic names for an address
   376         *
   377         *  Uses the ISymbolTable to look up the symbols at the given address.
   378         *
   379         *  This API is separate from lookupFuncName to address paging concerns.
   380         *  Use lookupFuncName to get function names (or any symbols in PROGRAM
   381         *  memory) and use lookupDataSymbol to get data symbols (for symbols in
   382         *  DATA memory).
   383         *
   384         *  @param(addr) Address of symbols
   385         *
   386         *  @a(Returns)  Array of symbols at the requested address.
   387         */
   388        Any lookupDataSymbol(Int addr);
   389    
   390        /*!
   391         *  ======== lookupFuncName ========
   392         *  Lookup function names for an address.
   393         *
   394         *  Uses the ISymbolTable to look up the symbols at the given address.
   395         *
   396         *  This API is separate from lookupDataSymbol to address paging concerns.
   397         *  Use lookupFuncName to get function names (or any symbols in PROGRAM
   398         *  memory) and use lookupDataSymbol to get data symbols (for symbols in
   399         *  DATA memory).
   400         *
   401         *  @param(addr) Address of symbols
   402         *
   403         *  @a(Returns)  Array of symbols at the requested address.
   404         */
   405        Any lookupFuncName(Int addr);
   406        
   407        /*!
   408         *  ======== getSymbolValue ========
   409         *  Returns the value for the given symbol.
   410         *
   411         *  Returns -1 if the symbol does not exist.
   412         *
   413         *  @param(symName) Name of symbol
   414         * 
   415         *  @a(Returns) Address or value of symbol, or -1 if symbol does not exist
   416         */
   417        Int getSymbolValue(String symName);
   418        
   419        /*!
   420         *  ======== displayError ========
   421         *
   422         */
   423        Void displayError(Any view, String fieldName, String errorMsg); 
   424        
   425        /*!
   426         *  ======== ptrToHex ========
   427         *  Convert pointer representation to hex string
   428         *
   429         *  Convenience function for converting the 'at' symbol representation
   430         *  of a pointer to the form 0x80005846.
   431         */
   432        String ptrToHex(Any ptr);
   433        
   434        /*!
   435         *  ======== getShortName ========
   436         *  Convert canonical instance names to a short name
   437         *
   438         *  Parses the full canonical instance name for the shorter name given 
   439         *  by the user. If there is no shorter name, then it returns an empty
   440         *  string "".
   441         *
   442         *  @param(name)  Full canonical instance name.
   443         *
   444         *  @a(Returns)  The short name, if the user specified one. Empty string
   445         *               otherwise.
   446         */
   447        String getShortName(String name);
   448    
   449        /*!
   450         *  ======== debugPrint ========
   451         *  Print API which will only print the message if debug printing is
   452         *  enabled.
   453         */
   454        Void debugPrint(String msg);
   455        
   456        /*!
   457         *  ======== timestamp ========
   458         *  API for printing timestamp messages for performance analysis.
   459         */
   460        Void timestamp(String msg);
   461           
   462        /*!
   463         *  ======== setTimestampFunc ========
   464         *  Sets API to be used for printing timestamp.
   465         */
   466        Void setTimestampFunc(Any func);
   467        
   468        /*!
   469         *  ======== newViewStruct ========
   470         *  Creates a new instance of the view structure for the specified view.
   471         *
   472         *  This API is called for views where the view structure is not already 
   473         *  passed in as an argument to the view init function.
   474         *
   475         *  It is necessary to instantiate a view structure in this way so that ROV
   476         *  is given an opportunity to initialize the status-reporting mechanisms
   477         *  of the view structure (to support, e.g., Program.displayError).
   478         */
   479        Any newViewStruct(String modName, String tabName);
   480        
   481        /*!
   482         *  ======== StatusEntry ========
   483         *  Single entry in the ROV status table.
   484         *
   485         *  ROV maintains a table of all errors, warnings, etc. encountered while
   486         *  processing views. This table is cleared on each call to clear cache
   487         *  (e.g., at each breakpoint).
   488         */
   489        metaonly struct StatusEntry {
   490            String mod;
   491            String tab;
   492            String inst;
   493            String field;
   494            String message;
   495        }
   496        
   497        /*!
   498         *  ======== getStatusTable ========
   499         *  Returns the current table of all encountered status messages.
   500         *
   501         *  This table is reset with every call to 'resetMods'. (e.g., at every
   502         *  breakpoint).
   503         */
   504        Any getStatusTable();
   505        
   506        /* -------- Used By ROV -------- */
   507           
   508        /*!
   509         *  @_nodoc  
   510         *  ======== moduleNames ========
   511         *  Array of all the module names in the application.
   512         */
   513        readonly config String moduleNames[length];
   514        
   515        /*!
   516         *  @_nodoc  
   517         *  ======== getModuleDesc ========
   518         *  Used to retrieve the module descriptor object for the requested module.
   519         */
   520        ROVModuleDesc *getModuleDesc(String modName);
   521        
   522        /*!
   523         *  @_nodoc  
   524         *  ======== getViewType ========
   525         *  This is a helper method which returns whether a given tabName is a
   526         *  module-level view, instance-level view, or raw view.
   527         */
   528        String getViewType(String modName, String tabName);
   529    
   530        /*!
   531         *  @_nodoc
   532         *  ======== Tab ========
   533         *  The type is an enum, but we can't use an enum from another module,
   534         *  so just use the String value of the type.
   535         */
   536        metaonly struct Tab {
   537            String name;
   538            String type;
   539        }
   540        
   541        /*!
   542         *  @_nodoc
   543         *  ======== Tabs ========
   544         */
   545        typedef Tab Tabs[];
   546        
   547        /*!
   548         *  @_nodoc  
   549         *  ======== getSupportedTabs ========
   550         *  Returns a string array of the tab names supported by the module.
   551         */
   552        Tabs getSupportedTabs(String modName);
   553    
   554        /*!
   555         *  @_nodoc
   556         *  ======== getAbortFlag ========
   557         *  In CCS, indicates whether the abort flag has been set.
   558         */
   559        Bool getAbortFlag();
   560        
   561        /*!
   562         *  @_nodoc  
   563         *  ======== resetMods ========
   564         *  Used to clear the cache of all scanned data and views. Should be called
   565         *  whenever the target data has changed.
   566         */
   567        Void resetMods();
   568        
   569        /*!
   570         *  @_nodoc  
   571         *  ======== setThrowViewErrors ========
   572         *  Used to enable/disable exceptions when views detect errors
   573         */
   574        Void setThrowViewErrors(Bool flag);
   575    
   576        /*!
   577         *  @_nodoc
   578         *  ======== moduleIdToName ========
   579         *  Used by xdc.runtime.Log.decode
   580         */
   581        String moduleIdToName(Int mid);
   582        
   583        /*!
   584         *  ======== exToString ========
   585         *  Helper function for formatting exceptions into strings with filename 
   586         *  and line number.
   587         */
   588        String exToString(Any e);
   589        
   590        /*!
   591         *  @_nodoc  
   592         *  ========= ROVModuleDesc ========
   593         *  Structure containing all ROV-related data about an individual module.
   594         *
   595         *  An instance of this structure is created for each module in the system.
   596         *  As various Program.scan APIs are called, this structure is gradually
   597         *  filled in with data.
   598         *
   599         *  The structure's fields:
   600         *    name         The module's name
   601         *    addr         Address of the state object. Redundant with state.$addr,
   602         *                 but available so that address is present even if fetch 
   603         *                 of state fails.
   604         *    loadFailed   Indicates that the 'useModule' call on this module threw
   605         *                 an exception.
   606         *    loadFailedMsg The exception message from the 'useModule' call
   607         *    cfg          Object containing all of the mod's configuration values
   608         *    state        Raw module state object
   609         *    instances    Array of ROVInstanceDesc objects representing the mod's
   610         *                 instances.
   611         *    objects      Array of ROVInstanceDesc objects representing instances 
   612         *                 of the module which are embedded in other objects.
   613         *    viewMap      Contains the module-level views. The key to the map is 
   614         *                 the string tab name for the view, and the value is the 
   615         *                 an instance of Module_View.
   616         *    errorMap     For each view, contains any error that was encountered
   617         *                 in processing the view outside of what was reported by
   618         *                 the module. For example, an unhandled exception from the
   619         *                 view code would be stored here.
   620         */
   621        metaonly struct ROVModuleDesc {
   622            String name;
   623            Any addr;
   624            Bool loadFailed;
   625            String loadFailedMsg;
   626            Any cfg;
   627            Any useMod;
   628            Any viewInfo;
   629            Any state;
   630            
   631            Any staticInstAddrs[];
   632            Any dynInstAddrs[];
   633            Bool readAllAddrs;
   634            
   635            ROVInstanceDesc *instances[];
   636            Any viewMap[string];
   637            String errorMap[string];
   638            
   639            String error; // Deprecated, replaced by errorMap
   640            
   641            Any instMap;
   642            
   643            Any userPrivate;
   644        };
   645        
   646        /*!
   647         *  @_nodoc  
   648         *  ========= ROVInstanceDesc ========
   649         *  Structure containing all ROV-related data about an individual instance.
   650         *
   651         *  The ROVInstanceDesc objects are stored in the 'instances' array of the
   652         *  respective module's ROVModuleDesc structure.
   653         *
   654         *  The structure's fields:
   655         *    state     Raw instance state object
   656         *    addr      Address of the state object. Redundant with state.$addr,
   657         *              but available so that address is present even if fetch of
   658         *              statefails.
   659         *    viewMap   Contains the instance-level views. The key to the map is
   660         *              the string tab name for the view, and the value is the 
   661         *              an instance of Instance_View.
   662         *    errorMap  For each view, contains any error that was encountered
   663         *              in processing the view outside of what was reported by
   664         *              the module. For example, an unhandled exception from the
   665         *              view code would be stored here.
   666         */
   667        metaonly struct ROVInstanceDesc {
   668            Any    state;
   669            Any    addr;
   670            Any    viewMap[string];
   671            String errorMap[string];
   672            
   673            String error; // Deprecated, replaced by errorMap
   674        };
   675    
   676    }
   677    /*
   678     *  @(#) xdc.rov; 1, 0, 1,0; 8-8-2017 17:30:40; /db/ztree/library/trees/xdc/xdc-D20/src/packages/
   679     */
   680