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        Any scanInstanceView(String modName, String tabName);
   142        
   143        /*!
   144         *  ======== scanModuleView ========
   145         *  Retrieve module-type view for a module.
   146         *
   147         *  @param(modName)  Full module name to return the view for.
   148         *  @param(tabName)  Name of the tab to retreive the view for.
   149         *
   150         *  @(returns)  Module_View structure.
   151         */
   152        Any scanModuleView(String modName, String tabName);
   153        
   154        /*!
   155         *  ======== scanInstanceDataView ========
   156         *
   157         */
   158        InstDataViewArr scanInstanceDataView(String modName, String tabName);
   159    
   160        /*!
   161         *  ======== scanModuleDataView ========
   162         *
   163         */    
   164        ModDataView scanModuleDataView(String modName, String tabName);
   165        
   166        /*!
   167         *  ======== scanRawView ========
   168         *  Retrieve the raw view for a module.
   169         *
   170         *  @param(modName)  Full module name to return the raw view for.
   171         *
   172         *  @(returns) A RawView structure which contains the raw data.
   173         */
   174        RawView scanRawView(String modName);
   175        
   176        /*!
   177         *  ======== scanTreeTableView ========
   178         */
   179        TreeNodeArr scanTreeTableView(String modName, String tabName);
   180        
   181        /*!
   182         *  ======== scanTreeView ========
   183         */
   184        Any scanTreeView(String modName, String tabName);
   185        
   186        /*!
   187         *  ======== scanHandle ========
   188         *  Scan single instance of a module
   189         *
   190         *  Used from a view$init function to scan a single instance of a 
   191         *  different module given that instance's address.
   192         *
   193         *  @param(modName)   Full module name to return the raw view for.
   194         *  @param(instAddr)  Address of instance to scan.
   195         *  @param(tabName)   Name of the tab to retrieve the view for.
   196         *  
   197         *  @a(Returns) An Instance_View object for the requested view.
   198         */
   199        Any scanHandleView(String modName, Ptr instAddr, String tabName);
   200        
   201        /*! 
   202         *  ======== scanObjectView ========
   203         *  Scan view for an embedded object
   204         *
   205         *  Called from a view$init function to retrieve the specified view for
   206         *  an embedded object.
   207         *
   208         *  Since XDC has no way of knowing what embedded objects are present in
   209         *  a system, embedded objects do not appear in the list of a module's 
   210         *  instances until they have been scanned in this way. 
   211         *
   212         *  Calling Program.scanObjectView will not read any additional data from
   213         *  the target, since the state structure was already read as part of 
   214         *  reading it's parent structure.
   215         *
   216         *  @param(modName)  Full module name to return the view for.
   217         *  @param(obj)      Actual object to retrieve the view for.
   218         *  @param(tabName)  Name of the tab to retrieve the view for.
   219         *
   220         *  @a(Returns) An Instance_View object for the requested view.
   221         */
   222        Any scanObjectView(String modName, Any obj, String tabName);
   223        
   224    
   225        /* -------- Fetch Functions -------- */
   226        
   227        /*!
   228         *  ======== fetchStruct ========
   229         *  Retrieve the specified structure from the target
   230         *
   231         *  @param(desc)  Fetch descriptor for the structure, indicating the type
   232         *                of the structure.
   233         *  @param(addr)  Address of the structure to fetch.
   234         *  @param(addrCheck)  Optional, defaults to true. Indicates whether the
   235         *                     memory image should validate the read by comparing
   236         *                     the address to section information.
   237         *
   238         *  @a(Returns)  Returns the requested structure as a javascript object.
   239         */
   240        Any fetchStruct(FetchDesc desc, Ptr addr, Bool addrCheck = true);
   241        
   242        /*!
   243         *  ======== fetchArray ========
   244         *  Retrieve the specified array from the target
   245         *
   246         *  @param(desc)  Fetch descriptor for the array, indicating the type of
   247         *                data in the array.
   248         *  @param(addr)  Address of the array to fetch.
   249         *  @param(length)  The number of arrray elements to fetch.
   250         *  @param(addrCheck)  Optional, defaults to true. Indicates whether the
   251         *                     memory image should validate the read by comparing
   252         *                     the address to section information.
   253         *
   254         *  @a(Returns)  Returns a JavaScript array with the data in it.
   255         */
   256        Any fetchArray(FetchDesc desc, Ptr addr, Int len, Bool addrCheck = true);
   257        
   258        /*!
   259         *  ======== fetchString ========
   260         *  Retrieve a string from the target
   261         *
   262         *  @param(addr)  Address of the string.
   263         *  @param(addrCheck)  Optional, defaults to true. Indicates whether the
   264         *                     memory image should validate the read by comparing
   265         *                     the address to section information.
   266         *
   267         *  @a(Returns)  Requested string.
   268         */
   269        String fetchString(Ptr addr, Bool addrCheck = true);
   270        
   271        /*!
   272         *  ======== fetchStaticString ========
   273         *  Retrieves a static string from the executable.
   274         *
   275         *  This API makes use of an object file reader to improve the string
   276         *  reading performance--it reads the string from the file rather than
   277         *  performing a target memory read. For this reason, it should only be
   278         *  used on static strings and not dynamic ones.
   279         *
   280         *  @param(addr)  Address of the string.
   281         *
   282         *  @a(Returns)  Requested string.
   283         */
   284        String fetchStaticString(Ptr addr);
   285        
   286        /*!
   287         *  ======== getModuleConfig ========
   288         *  Get a module's configuration state
   289         *
   290         *  Returns an object with all of the module configuration values used
   291         *  in configuring the application.
   292         *
   293         *  This object includes the common$ config params.
   294         *
   295         *  @param(modName)  Full module name to get the configs for.
   296         *  
   297         *  @a(Returns)  Object containing all of the module configs and
   298         *               their values.
   299         */
   300        Any getModuleConfig(String modName);
   301        
   302        /*!
   303         *  ======== getPrivateData ========
   304         *  Retrieves module's private ROV data.
   305         *  
   306         *  This API returns an object which can be used to store private data
   307         *  across different ROV API calls. The object is reset at every
   308         *  breakpoint.
   309         *
   310         *  This object is also passed as the context to all view init functions,
   311         *  so it can also be accessed using 'this'. However, the context changes
   312         *  when you call other APIs in your module; that is when you will need
   313         *  this API. It can also be used to support metaonly APIs which are called
   314         *  by other modules.
   315         */
   316        Any getPrivateData(String modName);
   317        
   318        /*!
   319         *  ======== lookupDataSymbol ========
   320         *  Lookup symbolic names for an address
   321         *
   322         *  Uses the ISymbolTable to look up the symbols at the given address.
   323         *
   324         *  This API is separate from lookupFuncName to address paging concerns.
   325         *  Use lookupFuncName to get function names (or any symbols in PROGRAM
   326         *  memory) and use lookupDataSymbol to get data symbols (for symbols in
   327         *  DATA memory).
   328         *
   329         *  @param(addr)  Address of symbols
   330         *
   331         *  @a(Returns)  Array of symbols at the requested address.
   332         */
   333        Any lookupDataSymbol(Int addr);
   334    
   335        /*!
   336         *  ======== lookupFuncName ========
   337         *  Lookup function names for an address.
   338         *
   339         *  Uses the ISymbolTable to look up the symbols at the given address.
   340         *
   341         *  This API is separate from lookupDataSymbol to address paging concerns.
   342         *  Use lookupFuncName to get function names (or any symbols in PROGRAM
   343         *  memory) and use lookupDataSymbol to get data symbols (for symbols in
   344         *  DATA memory).
   345         *
   346         *  @param(addr)  Address of symbols
   347         *
   348         *  @a(Returns)  Array of symbols at the requested address.
   349         */
   350        Any lookupFuncName(Int addr);
   351        
   352        /*!
   353         *  ======== getSymbolValue ========
   354         *  Returns the value for the given symbol.
   355         *
   356         *  Returns -1 if the symbol does not exist.
   357         *
   358         *  @param(symName)  Name of symbol
   359         * 
   360         *  @a(Returns)  Address or value of symbol, or -1 if symbol does not exist
   361         */
   362        Int getSymbolValue(String symName);
   363        
   364        /*!
   365         *  ======== displayError ========
   366         *
   367         */
   368        Void displayError(Any view, String fieldName, String errorMsg); 
   369        
   370        /*!
   371         *  ======== ptrToHex ========
   372         *  Convert pointer representation to hex string
   373         *
   374         *  Convenience function for converting the 'at' symbol representation
   375         *  of a pointer to the form 0x80005846.
   376         */
   377        String ptrToHex(Any ptr);
   378        
   379        /*!
   380         *  ======== getShortName ========
   381         *  Convert canonical instance names to a short name
   382         *
   383         *  Parses the full canonical instance name for the shorter name given 
   384         *  by the user. If there is no shorter name, then it returns an empty
   385         *  string "".
   386         *
   387         *  @param(name)  Full canonical instance name.
   388         *
   389         *  @a(Returns)  The short name, if the user specified one. Empty string
   390         *               otherwise.
   391         */
   392        String getShortName(String name);
   393    
   394        /*!
   395         *  ======== debugPrint ========
   396         *  Print API which will only print the message if debug printing is
   397         *  enabled.
   398         */
   399        Void debugPrint(String msg);
   400        
   401        /*!
   402         *  ======== timestamp ========
   403         *  API for printing timestamp messages for performance analysis.
   404         */
   405        Void timestamp(String msg);
   406           
   407        /*!
   408         *  ======== setTimestampFunc ========
   409         *  Sets API to be used for printing timestamp.
   410         */
   411        Void setTimestampFunc(Any func);
   412        
   413        /*!
   414         *  ======== newViewStruct ========
   415         *  Creates a new instance of the view structure for the specified view.
   416         *
   417         *  This API is called for views where the view structure is not already 
   418         *  passed in as an argument to the view init function.
   419         *
   420         *  It is necessary to instantiate a view structure in this way so that ROV
   421         *  is given an oppportunity to initialize the status-reporting mechanisms
   422         *  of the view structure (to support, e.g., Program.displayError).
   423         */
   424        Any newViewStruct(String modName, String tabName);
   425        
   426        /*!
   427         *  ======== StatusEntry ========
   428         *  Single entry in the ROV status table.
   429         *
   430         *  ROV maintains a table of all errors, warnings, etc. encountered while
   431         *  processing views. This table is cleared on each call to clear cache
   432         *  (e.g., at each breakpoint).
   433         */
   434        metaonly struct StatusEntry {
   435            String mod;
   436            String tab;
   437            String inst;
   438            String field;
   439            String message;
   440        }
   441        
   442        /*!
   443         *  ======== getStatusTable ========
   444         *  Returns the current table of all encountered status messages.
   445         *
   446         *  This table is reset with every call to 'resetMods'. (e.g., at every
   447         *  breakpoint).
   448         */
   449        Any getStatusTable();
   450        
   451        /* -------- Used By ROV -------- */
   452           
   453        /*!
   454         *  @_nodoc  
   455         *  ======== moduleNames ========
   456         *  Array of all the module names in the application.
   457         */
   458        readonly config String moduleNames[length];
   459        
   460        /*!
   461         *  @_nodoc  
   462         *  ======== getModuleDesc ========
   463         *  Used to retrieve the module descriptor object for the requested module.
   464         */
   465        ROVModuleDesc *getModuleDesc(String modName);
   466        
   467        /*!
   468         *  @_nodoc  
   469         *  ======== getViewType ========
   470         *  This is a helper method which returns whether a given tabName is a
   471         *  module-level view, instance-level view, or raw view.
   472         */
   473        String getViewType(String modName, String tabName);
   474    
   475        /*!
   476         *  @_nodoc
   477         *  ======== Tab ========
   478         *  The type is an enum, but we can't use an enum from another module,
   479         *  so just use the String value of the type.
   480         */
   481        metaonly struct Tab {
   482            String name;
   483            String type;
   484        }
   485        
   486        /*!
   487         *  @_nodoc
   488         *  ======== Tabs ========
   489         */
   490        typedef Tab Tabs[];
   491        
   492        /*!
   493         *  @_nodoc  
   494         *  ======== getSupportedTabs ========
   495         *  Returns a string array of the tab names supported by the module.
   496         */
   497        Tabs getSupportedTabs(String modName);
   498    
   499        /*!
   500         *  @_nodoc
   501         *  ======== getAbortFlag ========
   502         *  In CCS, indicates whether the abort flag has been set.
   503         */
   504        Bool getAbortFlag();
   505        
   506        /*!
   507         *  @_nodoc  
   508         *  ======== resetMods ========
   509         *  Used to clear the cache of all scanned data and views. Should be called
   510         *  whenever the target data has changed.
   511         */
   512        Void resetMods();
   513        
   514        /*!
   515         *  @_nodoc
   516         *  ======== moduleIdToName ========
   517         *  Used by xdc.runtime.Log.decode
   518         */
   519        String moduleIdToName(Int mid);
   520        
   521        /*!
   522         *  ======== exToString ========
   523         *  Helper function for formatting exceptions into strings with filename 
   524         *  and line number.
   525         */
   526        String exToString(Any e);
   527        
   528        /*!
   529         *  @_nodoc  
   530         *  ========= ROVModuleDesc ========
   531         *  Structure containing all ROV-related data about an individual module.
   532         *
   533         *  An instance of this structure is created for each module in the system.
   534         *  As various Program.scan APIs are called, this structure is gradually
   535         *  filled in with data.
   536         *
   537         *  The structure's fields:
   538         *    name         The module's name
   539         *    addr         Address of the state object. Redundant with state.$addr,
   540         *                 but available so that address is present even if fetch 
   541         *                 of state fails.
   542         *    loadFailed   Indicates that the 'useModule' call on this module threw
   543         *                 an exception.
   544         *    loadFailedMsg The exception message from the 'useModule' call
   545         *    cfg          Object containing all of the mod's configuration values
   546         *    state        Raw module state object
   547         *    instances    Array of ROVInstanceDesc objects representing the mod's
   548         *                 instances.
   549         *    objects      Array of ROVInstanceDesc objects representing instances 
   550         *                 of the module which are embedded in other objects.
   551         *    viewMap      Contains the module-level views. The key to the map is 
   552         *                 the string tab name for the view, and the value is the 
   553         *                 an instance of Module_View.
   554         *    errorMap     For each view, contains any error that was encountered
   555         *                 in processing the view outside of what was reported by
   556         *                 the module. For example, an unhandled exception from the
   557         *                 view code would be stored here.
   558         */
   559        metaonly struct ROVModuleDesc {
   560            String name;
   561            Any addr;
   562            Bool loadFailed;
   563            String loadFailedMsg;
   564            Any cfg;
   565            Any useMod;
   566            Any viewInfo;
   567            Any state;
   568            
   569            Any staticInstAddrs[];
   570            Any dynInstAddrs[];
   571            Bool readAllAddrs;
   572            
   573            ROVInstanceDesc *instances[];
   574            Any viewMap[string];
   575            String errorMap[string];
   576            
   577            String error; // Deprecated, replaced by errorMap
   578            
   579            Any instMap;
   580            
   581            Any userPrivate;
   582        };
   583        
   584        /*!
   585         *  @_nodoc  
   586         *  ========= ROVInstanceDesc ========
   587         *  Structure containing all ROV-related data about an individual instance.
   588         *
   589         *  The ROVInstanceDesc objects are stored in the 'instances' array of the
   590         *  respective module's ROVModuleDesc structure.
   591         *
   592         *  The structure's fields:
   593         *    state     Raw instance state object
   594         *    addr      Address of the state object. Redundant with state.$addr,
   595         *              but available so that address is present even if fetch of
   596         *              statefails.
   597         *    viewMap   Contains the instance-level views. The key to the map is
   598         *              the string tab name for the view, and the value is the 
   599         *              an instance of Instance_View.
   600         *    errorMap  For each view, contains any error that was encountered
   601         *              in processing the view outside of what was reported by
   602         *              the module. For example, an unhandled exception from the
   603         *              view code would be stored here.
   604         */
   605        metaonly struct ROVInstanceDesc {
   606            Any    state;
   607            Any    addr;
   608            Any    viewMap[string];
   609            String errorMap[string];
   610            
   611            String error; // Deprecated, replaced by errorMap
   612        };
   613    
   614    }
   615    /*
   616     *  @(#) xdc.rov; 1, 0, 1,472; 3-20-2014 17:05:37; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
   617     */
   618