1    /* 
     2     *  Copyright (c) 2008-2020 Texas Instruments Incorporated
     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     *  ======== Model ========
    15     *  The ROV Model is the core of ROV. The Model must be started in order to
    16     *  retrieve ROV views for any modules.
    17     *
    18     *  The Model has a compatibility key. Any changes or additions to the public
    19     *  interfaces of the ROV core will result in a bump of the model version
    20     *  number.
    21     */
    22    metaonly module Model {
    23    
    24        /*!
    25         *  ======== vers ========
    26         *  ROV API version number
    27         *
    28         *  Model.start will throw an exception if the version parameter does not
    29         *  equal the Model's current version. The version number is changed based
    30         *  on modifications to the public APIs (in xdc.rov.Program) that would
    31         *  potentially break compatibility with clients.
    32         *
    33         *  This allows the Model to verify compatibility with its client.
    34         */
    35        config Int vers = 5;
    36    
    37        /*!
    38         *  ======== start ========
    39         *  Start the ROV Model
    40         *
    41         *  The ROV Model requires instances of an ISymbolTable, an IMemoryImage,
    42         *  and an ICallBack. It also requires the ROV recap file, which can be
    43         *  located using the xdc.rta.Recap module.
    44         *
    45         *  ROV tools initialize the ROV model as follows:
    46         *  @p(nlist)
    47         *      - `recap = getRecap(exec)`
    48         *      - `getIOFReaderInst()` (optional)
    49         *      - `start(..., exec, ..., recap, ...)`
    50         *      - `setICallStackInst()` (optional)
    51         *  @p
    52         *
    53         *  @param(vers)  Model.start will throw an exception if the version
    54         *                parameter does not equal the Model's current
    55         *                `{@link #vers version}`.
    56         *
    57         *  @param(executable) The path to the executable file
    58         *
    59         *  @param(recap) Capsule of the ROV recap file. Retrieve this with
    60         *                `xdc.loadCapsule(recapFilePath)`.
    61         *
    62         *  @param(sym)   an object that implements the xdc.rov.ISymbolTable
    63         *                interface used to read symbols defined by the
    64         *                executable
    65         *
    66         *  @param(mem)   an object that implements the `xdc.rov.IMemoryImage`
    67         *                interface used to read target memory
    68         *
    69         *  @param(callBack) an object that implements the `xdc.rov.ICallback`
    70         *                   interface used to report progress status
    71         */
    72        Void start(Int vers, String executable, Any recap,
    73                   ISymbolTable.Instance sym, Any mem, ICallBack.Instance callBack);
    74    
    75        /*!
    76         *  ======== getICallStackInst ========
    77         *  Called by clients to get the optional call stack parser.
    78         *
    79         *  @a(returns)
    80         *  Returns `null` in the event that there is no call stack parser; i.e.,
    81         *  there is no implementation of this functionality in the current
    82         *  `{@link Model}` context.
    83         */
    84        ICallStack.Instance getICallStackInst();
    85    
    86        /*!
    87         *  ======== setICallStackInst ========
    88         *  Called only during Model initialization
    89         *
    90         *  This method is called to "bind" an optional stack call stack parser
    91         *  and is called by the same client that calls
    92         * `{@link #start Model.start()}`.
    93         */
    94        void setICallStackInst(ICallStack.Instance cs);
    95    
    96        /*!
    97         *  ======== getISymbolTableInst ========
    98         *  Get the symbol table reader use in the model
    99         *
   100         *  This function must be called after `start()`.
   101         *
   102         *  @a(returns)
   103         *  Returns the `ISymbolTable` instance that is used by ROV to lookup
   104         *  symbolic names for addresses or values of named symbols.
   105         */
   106        ISymbolTable.Instance getISymbolTableInst();
   107    
   108        /*!
   109         *  ======== getMemoryImageInst ========
   110         *  Get the memory reader of a started ROV model
   111         *
   112         *  This function must be called after `start()`.
   113         *
   114         *  @a(returns)
   115         *  Returns the `IMemoryImage` instance used by ROV to read target memory.
   116         */
   117        function getMemoryImageInst();
   118    
   119        /*!
   120         *  ======== getICallBackInst ========
   121         *  Get the progress update callback of a started ROV model
   122         *
   123         *  This function must be called after `start()`.
   124         *
   125         *  @a(returns)
   126         *  Returns the `ICallback` instance that is used by ROV to report
   127         *  progress during startup of the ROV model.
   128         */
   129        ICallBack.Instance getICallBackInst();
   130    
   131        /*!
   132         *  ======== getIOFReaderInst ========
   133         *  Returns a Java-based object file reader specific to the executable
   134         *
   135         *  This function is an internal function used to obtain
   136         *  the underlying OMF reader that is typically used to implement
   137         *  `ISymbolTable`.
   138         *
   139         *  Note: this function must be called AFTER either `getRecap()`
   140         *  or `start()`
   141         *
   142         *  The OMF reader is used by ROV tools extract target information
   143         *  from executable; normally this information is specified by the
   144         *  RTSC config recap file but, if it's absent, it may be possible
   145         *  to get the information from the executable itself.  It is also
   146         *  used to perform advanced symbol table management; e.g., adding
   147         *  additional symbols from object files representing code in a
   148         *  device's ROM.
   149         *
   150         *  @a(returns)
   151         *  Returns a reference to an internal executable-specific Object
   152         *  Module Format (OMF) reader.
   153         */
   154        function getIOFReaderInst();
   155    
   156        /*!
   157         *  ======== getModuleList ========
   158         *  Get all modules configured for the executable used to start ROV
   159         *
   160         *  @a(returns)
   161         *  This function returns a JavaScript object representing the package
   162         *  hierarchy and the modules, including the views they support.
   163         */
   164        Any getModuleList();
   165    
   166        /*!
   167         *  ======== getRecap ========
   168         *  Finds and loads the recap file associated with a specified executable
   169         *
   170         *  The recap file is a serialization of the executable's
   171         *  configuration created implicitly by the RTSC configuration
   172         *  tool.
   173         *
   174         *  This function finds that file and loads the recap file via
   175         *  `xdc.loadCapsule()`.  In addition, using the target information
   176         *  contained in the recap file, this function initializes an
   177         *  appropriate binary Object mMdule Format (OMF) reader which is
   178         *  used by some ROV tools to provide enhanced functionality; e.g.,
   179         *  support for multiple symbol table files.
   180         *
   181         *  @param(execPath) full path to the executable
   182         *
   183         *  @a(returns)
   184         *  The return value is the capsule returned by `xdc.loadCapsule()`
   185         *  after loading the recap file.
   186         */
   187        function getRecap(execPath);
   188    
   189        /*!
   190         *  ======== getStartFileList ========
   191         *  Get an array of all input files used to startup the model
   192         *
   193         *  This function is used to generate a list of all files
   194         *  needed to re-create the ROV model outside any IDE.
   195         *
   196         *  Note: this list does NOT include files referenced by these startup
   197         *  files.  All referenced files are found along the package path which
   198         *  must be separately specified.
   199         *
   200         *  @a(returns)
   201         *  Returns an array of absolute paths of files read during the startup
   202         *  of the ROV model.
   203         */
   204        Any getStartFileList();
   205    }
   206    /*
   207     *  @(#) xdc.rov; 1, 0, 1,0; 10-3-2020 15:24:48; /db/ztree/library/trees/xdc/xdc-K04/src/packages/
   208     */
   209