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 of
61 * size {@link #mainLoggerSize} Bytes is enabled by default to support
62 * this.
63 * - Event logging is enabled for the SYS/BIOS Load and Task modules in order
64 * to allow System Analyzer to display CPU Load, Task Load, and Task Execution
65 * information. Logging of SWI and HWI events is disabled by default.
66 * In order to optimize event capture and minimize event loss, two loggers
67 * are created: one to store events from the SYS/BIOS Load module
68 * and the other to store events from other SYS/BIOS modules.
69 * - Multicore event correlation is enabled by default. This enables the
70 * {@link ti.uia.runtime.LogSync LogSync} module and creation of a dedicated
71 * logger for sync point events with a default circular buffer size of
72 * {@link ti.uia.runtime.LogSync#defaultSyncLoggerSize LogSync.defaultSyncLoggerSize} Bytes.
73 * - The Event Upload Mode is configured for UploadMode_JTAGSTOPMODE. This
74 * allows events to be uploaded when the target halts via JTAG.
75 * @p
76 * @p(code)
77 * // the Log module provides logging APIs for use by the user's software
78 * var Log = xdc.useModule('xdc.runtime.Log');
79 * // the LoggingSetup module's default settings configure much of the UIA infrastructure.
80 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
81 * @p
82 * @p(html)
83 * <hr />
84 * @p
85 * @a(Example)
86 * Example 2: A number of 'template' applications come with the UIA product, that
87 * provide predefined XDC configuration scripts and C code for use in new
88 * projects. These templates provide good examples of how to configure
89 * the various modules that are involved in setting up the UIA infrastructure,
90 * including the LoggingSetup module.
91 * They can also be generated directly by CCS, using the CCS TI Resource
92 * Explorer. The following steps show how to use CCSv5.x.x to generate a
93 * new project that configures the NDK to provide an Ethernet transport for
94 * uploading events from the target to the host. :
95 * @p(blist)
96 * - View / TI Resource Explorer : Opens the TI Resource Explorer.
97 * - Expand the System Analyzer (UIA Target) section
98 * - Expand the C6000, C64xx Multicore DSP, and EVMC6472 sections.
99 * - Expand the Single-core Examples and select Stairstep Ethernet.
100 * - Import the Stairstep Ethernet example into CCS.
101 * - Open the configuration file to see how LoggingSetup is configured
102 * with the NDK to use Ethernet as a transport for UIA events and
103 * commands.
104 */
105 metaonly module LoggingSetup
106 {
107
108 /*!
109 * ======== UploadMode ========
110 * Modes for uploading events to the host.
111 *
112 * By default, events are uploaded using the JTAG connection in
113 * stop-mode. Events are uploaded over JTAG when the target halts. This
114 * mode requires that JTAG connections are supported by the target.
115 * If you want to use Ethernet, probe points, a simulator, or some other
116 * method for uploading events, you can specify one of those upload
117 * methods by configuring the {@link #eventUploadMode} parameter.
118 * For example, you could use the following if you were running a
119 * simulator:
120 * @p(code)
121 * var LoggingSetup =
122 * xdc.useModule('ti.uia.sysbios.LoggingSetup');
123 * LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_SIMULATOR;
124 * @p
125 *
126 * @c(UploadMode_SIMULATOR)
127 * Simulator. Events are uploaded when logged. The target is briefly
128 * halted when the event is uploaded. This is equivalent to using
129 * UploadMode_PROBEPOINT.
130 *
131 * @c(UploadMode_PROBEPOINT)
132 * Probepoint. Events are uploaded over JTAG when logged. The target is briefly
133 * halted when the event is uploaded. This mode can also be used
134 * with a simulator.
135 *
136 * @c(UploadMode_JTAGSTOPMODE)
137 * Events are uploaded over JTAG when the target halts. This mode can
138 * also be used with a simulator.
139 *
140 * @c(UploadMode_JTAGRUNMODE)
141 * Events are Uploaded over JTAG while the target is running. This mode is
142 * supported for C6x devices only.
143 *
144 * @c(UploadMode_NONJTAGTRANSPORT)
145 * Events are uploaded over the non-JTAG transport specified by the
146 * {@link ti.uia.runtime.ServiceMgr#transportType ServiceMgr.transportType}
147 * parameter while the target is running.
148 *
149 * @c(UploadMode_NONJTAG_AND_JTAGSTOPMODE)
150 * Events are uploaded over a non-JTAG transport specified by the
151 * {@link ti.uia.runtime.ServiceMgr#transportType ServiceMgr.transportType}
152 * parameter while the target is running. When the target is halted,
153 * events are uploaded over JTAG.
154 *
155 * @c(UploadMode_STREAMER)
156 * Events are logged to a {@link LoggerStreamer} logger.
157 * The application must manage the buffers sent to the host.
158 *
159 * @c(UploadMode_STREAMER2)
160 * Events are logged to {@link LoggerStreamer2} loggers.
161 * The application must manage the buffers sent to the host.
162 *
163 * @c(UploadMode_IDLE)
164 * Events are logged to the {@link LoggerIdle} buffer, and uploaded in
165 * the idle loop. The user must specify the
166 * {@link LoggerIdle#transportType} and provide the
167 * {@link LoggerIdle#transportFxn}.
168 */
169 enum UploadMode {
170 UploadMode_SIMULATOR = 1, /*! Simulator. */
171 UploadMode_PROBEPOINT = 2, /*! Probepoint. */
172 UploadMode_JTAGSTOPMODE = 3, /*! JTAG Stop Mode. */
173 UploadMode_JTAGRUNMODE = 4, /*! JTAG Run Mode (C6x only). */
174 UploadMode_NONJTAGTRANSPORT = 5, /*! Non-JTAG transport */
175 UploadMode_NONJTAG_AND_JTAGSTOPMODE = 6, /*! Non-JTAG transport and
176 * JTAG Stop Mode. */
177 UploadMode_STREAMER = 7, /*! LoggerStreamer */
178 UploadMode_IDLE = 8, /*! Upload in Idle loop */
179 UploadMode_STREAMER2 = 9 /*! LoggerStreamer2 */
180 }
181
182 /*!
183 * ======== loadLogger ========
184 * Logger used for the Load module Log events
185 */
186 config xdc.runtime.ILogger.Handle loadLogger = null;
187
188 /*!
189 * ======== loadLoggerSize ========
190 * Size (in MAUs) of logger used for the Load module Log events.
191 */
192 metaonly config SizeT loadLoggerSize = 512;
193
194 /*!
195 * ======== loadLogging ========
196 * Enable the Load module event logging.
197 *
198 * If this is false, the events will be disabled. Otherwise the events
199 * will be enabled.
200 * Use the {@link #loadLoggingRuntimeControl} parameter
201 * to determine whether the state can be modified during runtime.
202 */
203 metaonly config Bool loadLogging = true;
204
205 /*!
206 * ======== loadLoggingRuntimeControl ========
207 * Specify whether load logging can be enabled / disabled at runtime.
208 *
209 * This determines what diags settings are applied to the module's diags
210 * mask. If 'false', the diags bits will be configured as
211 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
212 * bits will be configured as 'RUNTIME_ON'.
213 *
214 * Use the {@link #loadLogging} parameter
215 * to determine whether the event is ON or OFF. For example, the
216 * following two lines set the Load module's events to 'ALWAYS_ON'.
217 *
218 * @p(code)
219 * LoggingSetup.loadLogging = true;
220 * LoggingSetup.loadLoggingRuntimeControl = false;
221 * @p
222 */
223 metaonly config Bool loadLoggingRuntimeControl = true;
224
225 /*!
226 * ======== mainLogger ========
227 * Logger used for main and non-XDC modules Log events
228 */
229 config xdc.runtime.ILogger.Handle mainLogger = null;
230
231 /*!
232 * ======== mainLoggerSize ========
233 * Size (in MAUs) of logger used for the main and non-XDC modules Log events
234 */
235 metaonly config SizeT mainLoggerSize = 1024;
236
237 /*!
238 * ======== mainLogging ========
239 * Enable main and non-XDC modules event logging
240 *
241 * If this is false, the events will be disabled. Otherwise the events
242 * will be enabled. Use the {@link #mainLoggingRuntimeControl} parameter
243 * to determine whether the state can be modified during runtime.
244 *
245 * The table below shows the initial values of the
246 * xdc.runtime.Main Diags mask settings, based on mainLogging and
247 * mainLoggingRuntimeControl configuration. These settins only
248 * apply to Diags masks that have not been set in the application's
249 * configuration file. For example, this configuration code would
250 * cause xdc.runtime.Main's USER1 Diags mask to be unaffected by
251 * the settings of mainLogging and mainLoggingRuntimeControl:
252 *
253 * @p(code)
254 * Diags.setMaskMeta('xdc.runtime.Main', Diags.USER1, Diags.RUNTIME_ON);
255 * @p
256 *
257 * @p(html)
258 * <h3> Diags Mask Settings for xdc.runtime.Main </h3>
259 * <table border="1" cellpadding="3">
260 * <colgroup span="1"></colgroup> <colgroup span="5" align="center">
261 * </colgroup>
262 * <tr><th colspan="2" rowspan="2"> </th><th colspan="2"> mainLoggingRuntimeControl </th></tr>
263 * <tr><th> true </th><th> false </th></tr>
264 * <tr><th rowspan="2"> mainLogging </th><th> true </th><td> RUNTIME_ON</td>
265 * <td> ALWAYS_ON </td></tr>
266 * <tr><th> false </th><td> RUNTIME_OFF </td> <td> ALWAYS_OFF </td></tr>
267 * </table>
268 */
269 metaonly config Bool mainLogging = true;
270
271 /*!
272 * ======== mainLoggingRuntimeControl ========
273 * Specify whether main logging can be enabled / disabled at runtime.
274 *
275 * This determines what diags settings are applied to the module's diags
276 * mask. If 'false' and {@link #mainLogging} is true, the diags bits will be configured as
277 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
278 * bits will be configured as 'RUNTIME_ON'.
279 *
280 * Use the {@link #mainLogging} parameter
281 * to determine whether the event is ON or OFF. For example, the
282 * following two lines set the xdc.runtime.Main events to
283 * initially be 'RUNTIME_ON'.
284 *
285 * @p(code)
286 * LoggingSetup.mainLogging = true;
287 * LoggingSetup.mainLoggingRuntimeControl = true;
288 * @p
289 */
290 metaonly config Bool mainLoggingRuntimeControl = true;
291
292 /*!
293 * ======== sysbiosLogger ========
294 * Logger used for SYSBIOS modules Log events
295 */
296 config xdc.runtime.ILogger.Handle sysbiosLogger = null;
297
298 /*!
299 * ======== sysbiosLoggerSize ========
300 * Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events
301 */
302 metaonly config SizeT sysbiosLoggerSize = 1024;
303
304 /*!
305 * ======== sysbiosHwiLogging ========
306 * Enable SYSBIOS Hwi and Clock modules' event logging
307 *
308 * If this is false, the events will be disabled. Otherwise the events
309 * will be enabled.
310 * Use the {@link #sysbiosHwiLoggingRuntimeControl} parameter
311 * to determine whether the state can be modified during runtime.
312 */
313 metaonly config Bool sysbiosHwiLogging = false;
314
315 /*!
316 * ======== sysbiosHwiLoggingRuntimeControl ========
317 * Specify whether Hwi and Clock logging can be enabled / disabled at runtime
318 *
319 * This determines what diags settings are applied to the module's diags
320 * mask. If 'false', the diags bits will be configured as
321 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
322 * bits will be configured as 'RUNTIME_ON'.
323 *
324 * Use the {@link #sysbiosHwiLogging} parameter
325 * to determine whether the event is ON or OFF. For example, the
326 * following two lines set the Hwi module's events to 'ALWAYS_ON'.
327 *
328 * @p(code)
329 * LoggingSetup.sysbiosHwiLogging = true;
330 * LoggingSetup.sysbiosHwiLoggingRuntimeControl = false;
331 * @p
332 */
333 metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
334
335 /*!
336 * ======== sysbiosSwiLogging ========
337 * Enable SYSBIOS Swi module's event logging
338 *
339 * If this is false, the events will be disabled. Otherwise the events
340 * will be enabled.
341 * Use the {@link #sysbiosSwiLoggingRuntimeControl} parameter
342 * to determine whether the state can be modified during runtime.
343 */
344 metaonly config Bool sysbiosSwiLogging = false;
345
346 /*!
347 * ======== sysbiosSwiLoggingRuntimeControl ========
348 * Specify whether Swi logging can be enabled / disabled at runtime.
349 *
350 * This determines what diags settings are applied to the module's diags
351 * mask. If 'false', the diags bits will be configured as
352 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
353 * bits will be configured as 'RUNTIME_ON'.
354 *
355 * Use the {@link #sysbiosSwiLogging} parameter
356 * to determine whether the event is ON or OFF. For example, the
357 * following two lines initialize the Swi module's events to
358 * 'RUNTIME_OFF'.
359 *
360 * @p(code)
361 * LoggingSetup.sysbiosSwiLogging = false;
362 * LoggingSetup.sysbiosSwiLoggingRuntimeControl = true;
363 * @p
364 */
365 metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
366
367 /*!
368 * ======== sysbiosTaskLogging ========
369 * Enable SYSBIOS Task module's event logging
370 *
371 * If this is false, the events will be disabled. Otherwise the events
372 * will be enabled.
373 * Use the {@link #sysbiosTaskLoggingRuntimeControl} parameter
374 * to determine whether the state can be modified during runtime.
375 */
376 metaonly config Bool sysbiosTaskLogging = true;
377
378 /*!
379 * ======== sysbiosTaskLoggingRuntimeControl ========
380 * Specify whether Task logging can be enabled / disabled at runtime.
381 *
382 * This determines what diags settings are applied to the module's diags
383 * mask. If 'false', the diags bits will be configured as
384 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
385 * bits will be configured as 'RUNTIME_ON'.
386 *
387 * Use the {@link #sysbiosTaskLogging} parameter
388 * to determine whether the event is ON or OFF. For example, the
389 * following two lines initialize the Task module's events to
390 * 'ALWAYS_ON'.
391 *
392 * @p(code)
393 * LoggingSetup.sysbiosTaskLogging = true;
394 * LoggingSetup.sysbiosTaskLoggingRuntimeControl = false;
395 * @p
396 */
397 metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
398
399 /*!
400 * ======== overflowLoggerSize ========
401 * Size of logger used for overflow events when
402 * uploadMode is either JTAGRUNMODE or NONJTAG_AND_JTAGSTOPMODE
403 */
404 metaonly config SizeT overflowLoggerSize = 1024;
405
406 /*!
407 * ========= eventUploadMode ========
408 * Event upload mode
409 *
410 * See {@link LoggingSetup#UploadMode} for a description of the the
411 * different event upload modes.
412 *
413 * @a(Example)
414 * This script configures the system to stream events from the
415 * target to the host over JTAG while the target is running.
416 * (Note that this mode is only supported for CPUs that
417 * support real-time JTAG accesses such as those in the C6X family,
418 * e.g. C64X+ and C66 CPUs)
419 *
420 * @p(code)
421 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
422 * LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_JTAGRUNMODE;
423 *
424 */
425 metaonly config UploadMode eventUploadMode = UploadMode_JTAGSTOPMODE;
426
427 /*!
428 * ======== disableMulticoreEventCorrelation ========
429 * Set to true for single core applications.
430 *
431 * When set to true, the LoggingSetup module will not automatically
432 * include the LogSync module. The LogSync module is
433 * required in order to enable events from multiple CPU cores
434 * to be correlated with each other.
435 * @see ti.uia.runtime.LogSync
436 *
437 */
438 metaonly config Bool disableMulticoreEventCorrelation = false;
439
440 /*! @_nodoc
441 * ======== createLogger =========
442 * Internal helper function that creates the type of logger
443 * appropriate for the LoggingSetup.uploadMode that has been configured.
444 *
445 * @param(loggerSize): the size of the logger in MAUs
446 * @param(loggerInstanceName): the name to assign to the logger instance
447 * @param (loggerPriority): the IUIATransfer.Priority to assign to the logger instance
448 * @a(return) returns the logger instance that was created
449 */
450 metaonly function createLogger(loggerSize,loggerInstanceName,loggerPriority);
451 }