1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
37
38 package ti.uia.sysbios;
39
40 /*!
41 * ======== LoggingSetup ========
42 * Module to aid in configuring SYSBIOS logging using UIA and System Analyzer
43 * @p
44 * The LoggingSetup module automates the process of configuring an application
45 * to use UIA events, and configures SYS/BIOS modules to capture user-specified
46 * information such as CPU Load, Task Load and Task Execution so that it can
47 * be displayed by System Analyzer. It also automates the creation of
48 * infrastructure modules such as loggers, the ServiceManager and RTA modules
49 * to enable the capture and upload of the events over a user-specified transport.
50 * Both JTAG and Non-JTAG transports are supported.
51 * @p
52 * The following configuration script demonstrates the use of the LoggingSetup
53 * module in the XDC configuration file for the application:
54 *
55 * @a(Example)
56 * Example 1: Configuring an application to use the default settings provided
57 * by LoggingSetup. The following default settings are automatically applied:
58 * @p(blist)
59 * - Logging UIA events from user-provided C code. User provided C code is
60 * treated as part of the xdc.runtime.Main module. A circular buffer with
61 * a buffer size of 32 KBytes is enabled by default to support this.
62 * - Event logging is enabled for the SYS/BIOS Load and Task modules in order to
63 * allow System Analyzer to display CPU Load, Task Load, and Task Execution
64 * information. Logging of SWI and HWI events is disabled by default.
65 * In order to optimize event capture and minimize event loss, two loggers
66 * are created: one to store events from the SYS/BIOS Load module
67 * and the other to store events from other SYS/BIOS modules.
68 * - Multicore event correlation is enabled by default. This enables the
69 * LogSync module and creation of a dedicated logger for sync point events
70 * with a circular buffer size of 8 KBytes.
71 * - The Event Upload Mode is configured for NONJTAG_AND_JTAGSTOPMODE. This
72 * allows events to be uploaded in real-time via the Non-JTAG transport
73 * specified by the ti.uia.runtime.ServiceManager module, and also be uploaded
74 * when the target halts via JTAG. If the ServiceManager module is not
75 * used in the application, the transport falls back to JTAGSTOPMODE.
76 * - An Overflow logger will be automatically created to capture events that
77 * occurred while the transport was waiting to upload older events to the host.
78 * The logger's circular buffer size is set to 2K Bytes.
79 * @p
80 * @p(code)
81 * // the Log module provides logging APIs for use by the user's software
82 * var Log = xdc.useModule('xdc.runtime.Log');
83 * // the LoggingSetup module's default settings configure much of the UIA infrastructure.
84 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
85 * @p
86 * @p(html)
87 * <hr />
88 * @p
89 * @a(Example)
90 * Example 2: A number of 'template' applications are available that
91 * provide predefined XDC configuration scripts and C code for use in new
92 * projects. These templates provide good examples of how to configure all
93 * of the various modules that are involved in setting up the UIA infrastructure,
94 * including the LoggingSetup module. The templates can be downloaded from
95 * the System Analyzer Wiki site at
96 * @p(html)
97 * <a href="http://processors.wiki.ti.com/index.php/System_Analyzer">
98 * http://processors.wiki.ti.com/index.php/System_Analyzer</a>
99 * @p
100 * They can also be generated directly by CCS, using the CCS New Project
101 * Wizard. The following steps show how to use CCSv5.0.x to generate a new project
102 * that configure the NDK to provide an Ethernet transport for uploading events
103 * from the target to the host, please perform the following steps in CCS. :
104 * @p(blist)
105 * - File / New / CCS Project : opens the 'New CCS Project' dialog
106 * - <enter a name for the project>
107 * - <select the type of project>
108 * - <accept defaults for Additional Project Settings>
109 * - <configure the project settings for compiler options, etc.>
110 * - For Project Templates, expand the UIA and System Analyzer Examples section
111 * - select evm6472: Stairstep for a single core with UIA to see how
112 * to configure the NDK to use Ethernet as a transport for UIA events and
113 * commands.
114 * - select evm6472: MessageQ (single image for all cores) with UIA
115 * to see how to create a multicore application that uses the same application
116 * software for all cores, and uses IPC to move event data from CPU cores 1-5
117 * to CPU core 0, with CPU core 0 using the NDK for Ethernet communications
118 * with the host.
119 * @p
120 *
121 * @p(html)
122 * <hr />
123 */
124 metaonly module LoggingSetup
125 {
126
127 /*!
128 * ======== UploadMode ========
129 */
130 enum UploadMode {
131 UploadMode_SIMULATOR = 1,
132 UploadMode_PROBEPOINT = 2,
133 UploadMode_JTAGSTOPMODE = 3,
134 UploadMode_JTAGRUNMODE = 4,
135 UploadMode_NONJTAGTRANSPORT = 5,
136 UploadMode_NONJTAG_AND_JTAGSTOPMODE = 6,
137 UploadMode_STREAMER = 7,
138 UploadMode_IDLE = 8,
139 UploadMode_STREAMER2 = 9
140 }
141
142 /*!
143 * ======== loadLogger ========
144 * Logger used for the Load module Log events
145 */
146 config xdc.runtime.ILogger.Handle loadLogger = null;
147
148 /*!
149 * ======== loadLoggerSize ========
150 * Size (in MAUs) of logger used for the Load module Log events.
151 */
152 metaonly config SizeT loadLoggerSize = 512;
153
154 /*!
155 * ======== loadLogging ========
156 * Enable the Load module event logging.
157 *
158 * If this is false, the events will be disabled. Otherwise the events
159 * will be enabled.
160 * Use the {@link #loadLoggingRuntimeControl} parameter
161 * to determine whether the state can be modified during runtime.
162 */
163 metaonly config Bool loadLogging = true;
164
165 /*!
166 * ======== loadLoggingRuntimeControl ========
167 * Specify whether load logging can be enabled / disabled at runtime.
168 *
169 * This determines what diags settings are applied to the module's diags
170 * mask. If 'false', the diags bits will be configured as
171 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
172 * bits will be configured as 'RUNTIME_ON'.
173 *
174 * Use the {@link #loadLogging} parameter
175 * to determine whether the event is ON or OFF. For example, the
176 * following two lines set the Load modules events to
177 * initially be 'ALWAYS_ON'.
178 *
179 * @p(code)
180 * LoggingSetup.loadLogging = true;
181 * LoggingSetup.loadLoggingRuntimeControl = false;
182 * @p
183 */
184 metaonly config Bool loadLoggingRuntimeControl = true;
185
186 /*!
187 * ======== mainLogger ========
188 * Logger used for main and non-XDC modules Log events
189 */
190 config xdc.runtime.ILogger.Handle mainLogger = null;
191
192 /*!
193 * ======== mainLoggerSize ========
194 * Size (in MAUs) of logger used for the main and non-XDC modules Log events
195 */
196 metaonly config SizeT mainLoggerSize = 1024;
197
198 /*!
199 * ======== mainLogging ========
200 * Enable main and non-XDC modules event logging
201 *
202 * If this is false, the events will be disabled. Otherwise the events
203 * will be enabled.
204 * Use the {@link #mainLoggingRuntimeControl} parameter
205 * to determine whether the state can be modified during runtime.
206 */
207 metaonly config Bool mainLogging = true;
208
209 /*!
210 * ======== mainLoggingRuntimeControl ========
211 * Specify whether main logging can be enabled / disabled at runtime.
212 *
213 * This determines what diags settings are applied to the module's diags
214 * mask. If 'false', the diags bits will be configured as
215 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
216 * bits will be configured as 'RUNTIME_ON'.
217 *
218 * Use the {@link #mainLogging} parameter
219 * to determine whether the event is ON or OFF. For example, the
220 * following two lines set the Load modules events to
221 * initially be 'ALWAYS_ON'.
222 *
223 * @p(code)
224 * LoggingSetup.mainLogging = true;
225 * LoggingSetup.mainLoggingRuntimeControl = false;
226 * @p
227 */
228 metaonly config Bool mainLoggingRuntimeControl = true;
229
230 /*!
231 * ======== sysbiosLogger ========
232 * Logger used for SYSBIOS modules Log events
233 */
234 config xdc.runtime.ILogger.Handle sysbiosLogger = null;
235
236 /*!
237 * ======== sysbiosLoggerSize ========
238 * Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events
239 */
240 metaonly config SizeT sysbiosLoggerSize = 1024;
241
242 /*!
243 * ======== sysbiosHwiLogging ========
244 * Enable SYSBIOS Hwi and Clock modules' event logging
245 *
246 * If this is false, the events will be disabled. Otherwise the events
247 * will be enabled.
248 * Use the {@link #sysbiosHwiLoggingRuntimeControl} parameter
249 * to determine whether the state can be modified during runtime.
250 */
251 metaonly config Bool sysbiosHwiLogging = false;
252
253 /*!
254 * ======== sysbiosHwiLoggingRuntimeControl ========
255 * Specify whether Hwi and Clock logging can be enabled / disabled at runtime
256 *
257 * This determines what diags settings are applied to the module's diags
258 * mask. If 'false', the diags bits will be configured as
259 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
260 * bits will be configured as 'RUNTIME_ON'.
261 *
262 * Use the {@link #sysbiosHwiLogging} parameter
263 * to determine whether the event is ON or OFF. For example, the
264 * following two lines set the Load modules events to
265 * initially be 'ALWAYS_ON'.
266 *
267 * @p(code)
268 * LoggingSetup.sysbiosHwiLogging = true;
269 * LoggingSetup.sysbiosHwiLoggingRuntimeControl = false;
270 * @p
271 */
272 metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
273
274 /*!
275 * ======== sysbiosSwiLogging ========
276 * Enable SYSBIOS Swi module's event logging
277 *
278 * If this is false, the events will be disabled. Otherwise the events
279 * will be enabled.
280 * Use the {@link #sysbiosSwiLoggingRuntimeControl} parameter
281 * to determine whether the state can be modified during runtime.
282 */
283 metaonly config Bool sysbiosSwiLogging = false;
284
285 /*!
286 * ======== sysbiosSwiLoggingRuntimeControl ========
287 * Specify whether Swi logging can be enabled / disabled at runtime.
288 *
289 * This determines what diags settings are applied to the module's diags
290 * mask. If 'false', the diags bits will be configured as
291 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
292 * bits will be configured as 'RUNTIME_ON'.
293 *
294 * Use the {@link #sysbiosSwiLogging} parameter
295 * to determine whether the event is ON or OFF. For example, the
296 * following two lines set the Load modules events to
297 * initially be 'ALWAYS_ON'.
298 *
299 * @p(code)
300 * LoggingSetup.sysbiosSwiLogging = true;
301 * LoggingSetup.sysbiosSwiLoggingRuntimeControl = false;
302 * @p
303 */
304 metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
305
306 /*!
307 * ======== sysbiosTaskLogging ========
308 * Enable SYSBIOS Task module's event logging
309 *
310 * If this is false, the events will be disabled. Otherwise the events
311 * will be enabled.
312 * Use the {@link #sysbiosTaskLoggingRuntimeControl} parameter
313 * to determine whether the state can be modified during runtime.
314 */
315 metaonly config Bool sysbiosTaskLogging = true;
316
317 /*!
318 * ======== sysbiosTaskLoggingRuntimeControl ========
319 * Specify whether Task logging can be enabled / disabled at runtime.
320 *
321 * This determines what diags settings are applied to the module's diags
322 * mask. If 'false', the diags bits will be configured as
323 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
324 * bits will be configured as 'RUNTIME_ON'.
325 *
326 * Use the {@link #sysbiosTaskLogging} parameter
327 * to determine whether the event is ON or OFF. For example, the
328 * following two lines set the Load modules events to
329 * initially be 'ALWAYS_ON'.
330 *
331 * @p(code)
332 * LoggingSetup.sysbiosTaskLogging = true;
333 * LoggingSetup.sysbiosTaskLoggingRuntimeControl = false;
334 * @p
335 */
336 metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
337
338 /*!
339 * ======== overflowLoggerSize ========
340 * Size of logger used for overflow events when
341 * uploadMode is either JTAGRUNMODE or NONJTAG_AND_JTAGSTOPMODE
342 */
343 metaonly config SizeT overflowLoggerSize = 1024;
344
345 /*!
346 * ========= eventUploadMode ========
347 * Event upload mode
348 * @p
349 * Upload_SIMULATOR: events are uploaded from the simulator
350 * at the time the event is logged.
351 * @p(blist)
352 * - Upload_PROBEPOINT: events are uploaded at the time the event
353 * is logged. The target is briefly halted while the event is uploaded.
354 * - Upload_JTAGSTOPMODE: events are uploaded over JTAG when the target halts
355 * - Upload_JTAGRUNMODE: events are uploaded via JTAG while the target is running.
356 * - Upload_NONJTAGTRANSPORT: events are uploaded over a non-JTAG transport such
357 * as Ethernet. @see RTA for info on how to use the NDK as a transport.
358 * - Upload_NONJTAG_AND_JTAGSTOPMODE: events are uploaded over a non-JTAG transport.
359 * When the target halts (e.g. due to a breakpoint), any events that have not
360 * been uploaded yet are uploaded via JTAG.
361 * @p
362 *
363 * @a(Example)
364 * The following is an example of the configuration script used
365 * to configure the system to use LoggerCircBuf loggers in order to
366 * stream events from the target to the host while the target is running
367 * over JTAG. (Note that this mode is only supported for CPUs that
368 * support real-time JTAG accesses such as those in the C6X family,
369 * e.g. C64X+ and C66 CPUs)
370 *
371 * @p(code)
372 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
373 * LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_JTAGRUNMODE;
374 *
375 */
376 metaonly config UploadMode eventUploadMode = UploadMode_JTAGSTOPMODE;
377
378 /*!
379 * ======== disableMulticoreEventCorrelation ========
380 * Set to true for single core applications.
381 *
382 * When true the LoggingSetup module will not automatically
383 * include the the LogSync module. The LogSync module is
384 * required in order to enable events from multiple CPU cores
385 * to be correlated with each other.
386 * @see ti.uia.runtime.LogSync
387 *
388 */
389 metaonly config Bool disableMulticoreEventCorrelation = false;
390
391 /*! @_nodoc
392 * ======== createLogger =========
393 * Internal helper function that creates the type of logger
394 * appropriate for the LoggingSetup.uploadMode that has been configured.
395 *
396 * @param(loggerSize): the size of the logger in MAUs
397 * @param(loggerInstanceName): the name to assign to the logger instance
398 * @param (loggerPriority): the IUIATransfer.Priority to assign to the logger instance
399 * @a(return) returns the logger instance that was created
400 */
401 metaonly function createLogger(loggerSize,loggerInstanceName,loggerPriority);
402 }