| /* --COPYRIGHT--,EPL |
| * Copyright (c) 2008-2020 Texas Instruments Incorporated |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * Texas Instruments - initial implementation |
| * |
| * --/COPYRIGHT--*/ |
| |
| /*! |
| * ======== Model ======== |
| * The ROV Model is the core of ROV. The Model must be started in order to |
| * retrieve ROV views for any modules. |
| * |
| * The Model has a compatibility key. Any changes or additions to the public |
| * interfaces of the ROV core will result in a bump of the model version |
| * number. |
| */ |
| metaonly module Model { |
| |
| /*! |
| * ======== vers ======== |
| * ROV API version number |
| * |
| * Model.start will throw an exception if the version parameter does not |
| * equal the Model's current version. The version number is changed based |
| * on modifications to the public APIs (in xdc.rov.Program) that would |
| * potentially break compatibility with clients. |
| * |
| * This allows the Model to verify compatibility with its client. |
| */ |
| config Int vers = 5; |
| |
| /*! |
| * ======== start ======== |
| * Start the ROV Model |
| * |
| * The ROV Model requires instances of an ISymbolTable, an IMemoryImage, |
| * and an ICallBack. It also requires the ROV recap file, which can be |
| * located using the xdc.rta.Recap module. |
| * |
| * ROV tools initialize the ROV model as follows: |
| * @p(nlist) |
| * - `recap = getRecap(exec)` |
| * - `getIOFReaderInst()` (optional) |
| * - `start(..., exec, ..., recap, ...)` |
| * - `setICallStackInst()` (optional) |
| * @p |
| * |
| * @param(vers) Model.start will throw an exception if the version |
| * parameter does not equal the Model's current |
| * `{@link #vers version}`. |
| * |
| * @param(executable) The path to the executable file |
| * |
| * @param(recap) Capsule of the ROV recap file. Retrieve this with |
| * `xdc.loadCapsule(recapFilePath)`. |
| * |
| * @param(sym) an object that implements the xdc.rov.ISymbolTable |
| * interface used to read symbols defined by the |
| * executable |
| * |
| * @param(mem) an object that implements the `xdc.rov.IMemoryImage` |
| * interface used to read target memory |
| * |
| * @param(callBack) an object that implements the `xdc.rov.ICallback` |
| * interface used to report progress status |
| */ |
| Void start(Int vers, String executable, Any recap, |
| ISymbolTable.Instance sym, Any mem, ICallBack.Instance callBack); |
| |
| /*! |
| * ======== getICallStackInst ======== |
| * Called by clients to get the optional call stack parser. |
| * |
| * @a(returns) |
| * Returns `null` in the event that there is no call stack parser; i.e., |
| * there is no implementation of this functionality in the current |
| * `{@link Model}` context. |
| */ |
| ICallStack.Instance getICallStackInst(); |
| |
| /*! |
| * ======== setICallStackInst ======== |
| * Called only during Model initialization |
| * |
| * This method is called to "bind" an optional stack call stack parser |
| * and is called by the same client that calls |
| * `{@link #start Model.start()}`. |
| */ |
| void setICallStackInst(ICallStack.Instance cs); |
| |
| /*! |
| * ======== getISymbolTableInst ======== |
| * Get the symbol table reader use in the model |
| * |
| * This function must be called after `start()`. |
| * |
| * @a(returns) |
| * Returns the `ISymbolTable` instance that is used by ROV to lookup |
| * symbolic names for addresses or values of named symbols. |
| */ |
| ISymbolTable.Instance getISymbolTableInst(); |
| |
| /*! |
| * ======== getMemoryImageInst ======== |
| * Get the memory reader of a started ROV model |
| * |
| * This function must be called after `start()`. |
| * |
| * @a(returns) |
| * Returns the `IMemoryImage` instance used by ROV to read target memory. |
| */ |
| function getMemoryImageInst(); |
| |
| /*! |
| * ======== getICallBackInst ======== |
| * Get the progress update callback of a started ROV model |
| * |
| * This function must be called after `start()`. |
| * |
| * @a(returns) |
| * Returns the `ICallback` instance that is used by ROV to report |
| * progress during startup of the ROV model. |
| */ |
| ICallBack.Instance getICallBackInst(); |
| |
| /*! |
| * ======== getIOFReaderInst ======== |
| * Returns a Java-based object file reader specific to the executable |
| * |
| * This function is an internal function used to obtain |
| * the underlying OMF reader that is typically used to implement |
| * `ISymbolTable`. |
| * |
| * Note: this function must be called AFTER either `getRecap()` |
| * or `start()` |
| * |
| * The OMF reader is used by ROV tools extract target information |
| * from executable; normally this information is specified by the |
| * RTSC config recap file but, if it's absent, it may be possible |
| * to get the information from the executable itself. It is also |
| * used to perform advanced symbol table management; e.g., adding |
| * additional symbols from object files representing code in a |
| * device's ROM. |
| * |
| * @a(returns) |
| * Returns a reference to an internal executable-specific Object |
| * Module Format (OMF) reader. |
| */ |
| function getIOFReaderInst(); |
| |
| /*! |
| * ======== getModuleList ======== |
| * Get all modules configured for the executable used to start ROV |
| * |
| * @a(returns) |
| * This function returns a JavaScript object representing the package |
| * hierarchy and the modules, including the views they support. |
| */ |
| Any getModuleList(); |
| |
| /*! |
| * ======== getRecap ======== |
| * Finds and loads the recap file associated with a specified executable |
| * |
| * The recap file is a serialization of the executable's |
| * configuration created implicitly by the RTSC configuration |
| * tool. |
| * |
| * This function finds that file and loads the recap file via |
| * `xdc.loadCapsule()`. In addition, using the target information |
| * contained in the recap file, this function initializes an |
| * appropriate binary Object mMdule Format (OMF) reader which is |
| * used by some ROV tools to provide enhanced functionality; e.g., |
| * support for multiple symbol table files. |
| * |
| * @param(execPath) full path to the executable |
| * |
| * @a(returns) |
| * The return value is the capsule returned by `xdc.loadCapsule()` |
| * after loading the recap file. |
| */ |
| function getRecap(execPath); |
| |
| /*! |
| * ======== getStartFileList ======== |
| * Get an array of all input files used to startup the model |
| * |
| * This function is used to generate a list of all files |
| * needed to re-create the ROV model outside any IDE. |
| * |
| * Note: this list does NOT include files referenced by these startup |
| * files. All referenced files are found along the package path which |
| * must be separately specified. |
| * |
| * @a(returns) |
| * Returns an array of absolute paths of files read during the startup |
| * of the ROV model. |
| */ |
| Any getStartFileList(); |
| } |