1 2 3 4 5 6 7 8 9 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 208
209