add docs for the ROV Model module + add a method to retrieve startup files used
diff --git a/src/packages/xdc/rov/Model.xdc b/src/packages/xdc/rov/Model.xdc
index 299c5be..a8f4e8f 100644
--- a/src/packages/xdc/rov/Model.xdc
+++ b/src/packages/xdc/rov/Model.xdc
@@ -40,34 +40,43 @@
*
* 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.rov.Recap module.
+ * located using the xdc.rta.Recap module.
*
- * @param(vers) Model.start will throw an exception if the version
+ * 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(executable) The path to the executable file
+ * @param(sym) an object that implements the xdc.rov.ISymbolTable
+ * interface used to read symbols defined by the
+ * executable
*
- * @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(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
+ * @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.
@@ -86,31 +95,111 @@
/*!
* ======== 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();
}
diff --git a/src/packages/xdc/rov/Model.xs b/src/packages/xdc/rov/Model.xs
index 64bfb88..c71ed0d 100644
--- a/src/packages/xdc/rov/Model.xs
+++ b/src/packages/xdc/rov/Model.xs
@@ -13,6 +13,8 @@
* ======== Model.xs ========
*/
+/* global print, Packages Program, xdc */
+
var noRuntime = false; /* keeps track if no RTSC runtime */
var cmodules = {}; /* map of C modules with ROV code */
@@ -26,10 +28,10 @@
/* Check Model compatibility. */
if (!(vers == 4 && this.vers == 5) && vers != this.vers) {
- Program.debugPrint("Incompatible version of ROV Model. Model version " +
- this.vers + ", client version " + vers + ".");
- throw (new Error("Incompatible version of ROV Model. Model version " +
- this.vers + ", client version " + vers + "."));
+ Program.debugPrint("Incompatible version of ROV Model. Model version "
+ + this.vers + ", client version " + vers + ".");
+ throw (new Error("Incompatible version of ROV Model. Model version "
+ + this.vers + ", client version " + vers + "."));
}
/* Store off the objects passed in */
@@ -39,11 +41,13 @@
if (recap != null) {
this.$private.recap = recap;
}
+ this.$private.files = [executable];
xdc.useModule('xdc.rov.support.ScalarStructs');
/* Read the ROV config file and/or sysconfig ROV file */
- readConfig(executable);
+ var files = readConfig(executable);
+ this.$private.files.concat(files);
/* Store off the list of all modules in the recap file */
var mnames = [];
@@ -222,8 +226,9 @@
* ======== initOFReader ========
* A private function that creates and initializes the object file reader.
*
- * Model.private.$recap must be already defined. It is not enforced in the code
- * because this can only be invoked from within this module.
+ * Model.private.$recap must be already defined. It is not enforced in the
+ * code because this can only be invoked from within this module.
+ *
* The StringReader should be initialized first; if anything goes wrong
* creating the object file reader, we fall back on the string reader.
*/
@@ -253,6 +258,7 @@
*/
binaryParser = "xdc.targets.omf.Elf";
}
+
/* Parse the package name from the class name so we can load it. */
var parserPackage =
binaryParser.substring(0, binaryParser.lastIndexOf('.'));
@@ -260,7 +266,7 @@
/* Load the parser's package */
xdc.loadPackage(parserPackage);
- /* Get the parser class */
+ /* Get the parser's Java class */
var binaryParserClass = Packages[binaryParser];
/* Create an instance of the ofReader */
@@ -281,8 +287,8 @@
* StringReader instead.
*/
catch (e) {
- print("Caught an exception while initializing the object " +
- "file reader:\n" + e);
+ print("Caught an exception while initializing the object "
+ + "file reader:\n" + e);
ofReader = Model.$private.strReader;
}
}
@@ -291,8 +297,8 @@
* string reader.
*/
else {
- print("The target does not specify an object file reader; using the " +
- "dynamic string reader instead.");
+ print("The target does not specify an object file reader; using the "
+ + "dynamic string reader instead.");
ofReader = Model.$private.strReader;
}
@@ -475,8 +481,6 @@
/*
* ======== getModuleList ========
- * This function returns a JavaScript object representing the package
- * hierarchy and the modules, including the views they support.
*/
function getModuleList()
{
@@ -562,7 +566,15 @@
return (pkgName);
}
-/*!
+/*
+ * ======== getStartFileList ========
+ */
+function getStartFileList()
+{
+ return (this.$private.files);
+}
+
+/*
* ======== setICallStackInst ========
* Called only during Model initialization
*
@@ -625,9 +637,11 @@
*/
function readConfig(executable)
{
+ var files = [];
var sysConfig = locateSysconfigFile(executable);
if (sysConfig != "") {
var sconfig = xdc.loadCapsule(sysConfig);
+ files.push(sconfig.$path);
var list = sconfig.crovFiles;
for (var k = 0; k < list.length; k++) {
var modCaps = {};
@@ -662,6 +676,7 @@
if (rovConfig != "") {
//try {
var config = xdc.loadCapsule(rovConfig);
+ files.push(sconfig.$path);
/* This code reads an array of declared constructed objects from
* a ROV configuration file with the .rov.js extension.
* Example:
@@ -738,6 +753,7 @@
Program.debugPrint("Cannot load " + rovConfig);
//}
}
+ return (files);
}
/*
