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 TI-RTOS logging using UIA and System Analyzer.
43 *
44 * @p
45 * The LoggingSetup module automates the process of configuring an application
46 * to use UIA events, and configures TI-RTOS modules to capture user-specified
47 * information such as CPU Load, Task Load and Task Execution so that it can
48 * be displayed by System Analyzer. It also automates the creation of
49 * infrastructure modules such as loggers, the ServiceManager and RTA modules
50 * to enable the capture and upload of the events over a user-specified
51 * transport.
52 * Both JTAG and Non-JTAG transports are supported.
53 * @p
54 * The following configuration script demonstrates the use of the LoggingSetup
55 * module in the XDC configuration file for the application:
56 *
57 * @a(Example)
58 * Example 1: Configuring an application to use the default settings provided
59 * by LoggingSetup. The following default settings are automatically applied:
60 * @p(blist)
61 * - Logging UIA events from user-provided C code. User provided C code is
62 * treated as part of the xdc.runtime.Main module. A circular buffer of
63 * size {@link #mainLoggerSize} Bytes is enabled by default to support
64 * this.
65 * - Event logging is enabled for the TI-RTOS Load and Task modules in order
66 * to allow System Analyzer to display CPU Load, and Task
67 * Execution information. Logging of SWI and HWI events is disabled by
68 * default. In order to optimize event capture and minimize event loss, three
69 * loggers are created: one to store events from the TI-RTOS Load module
70 * another to store events from other TI-RTOS modules, and the third to store user
71 * Log events.
72 * - The events will be logged to {@link ti.uia.loggers.LoggerStopMode LoggerStopMode}
73 * loggers, and will be uploaded over JTAG when the target halts.
74 * @p
75 * @p(code)
76 * // the Log module provides logging APIs for use by the user's software
77 * var Log = xdc.useModule('xdc.runtime.Log');
78 * // the LoggingSetup module's default settings configure much of the UIA infrastructure.
79 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
80 * @p
81 * @p(html)
82 * <hr />
83 * @p
84 * @a(Example)
85 * Example 2: Use all the default settings of LoggingSetup, except use the
86 * minimal footprint logger, LoggerMin. The following settings will be applied:
87 * @p(blist)
88 * - Logging UIA events from user-provided C code.
89 * - Event logging is enabled for the TI-RTOS Load and Task modules, and
90 * disabled for SWI and HWI.
91 * - The events will be logged via {@link ti.uia.loggers.LoggerMin LoggerMin},
92 * and will be uploaded over JTAG when the target halts.
93 * - All events will be logged into one buffer whose default sise is
94 * {@link ti.uia.loggers.LoggerMin#bufSize}
95 */
96 metaonly module LoggingSetup
97 {
98
99 /*!
100 * ======== enableTaskProfiler ========
101 * Enable System Analyzer's Task Profiler
102 *
103 * Setting enableTaskProfiler to true enables task, hwi and swi
104 * entry and exit logging in order to generate profiling
105 * information
106 */
107 metaonly config Bool enableTaskProfiler = false;
108
109 /*!
110 * ======== enableContextAwareFunctionProfiler ========
111 * Enable System Analyzer's Context Aware Function Profiler
112 *
113 * Setting to true enables function entry and exit logging
114 * in order to generate function profiling information.
115 * This requires that the compiler's function entry and exit
116 * hook functions be enabled.
117 */
118 metaonly config Bool enableContextAwareFunctionProfiler = false;
119
120 /*!
121 * ======== memorySectionName ========
122 * Memory section name for the buffer managed by the static instance
123 * (default is null).
124 *
125 * By default the local 'dataMemory' in the platform is used (typically
126 * SRAM or L2SRAM).
127 * The available memory section names for your device can be determined by
128 * either looking in the MEMORY CONFIGURATION section of the .map file
129 * that is generated when you build your application or from the Platform
130 * file that your application is using.
131 */
132 metaonly config String memorySectionName = null;
133
134 /*!
135 * ======== numCores ========
136 * Number of cores running the same image with an instance in shared
137 * memory.
138 *
139 * A common use case is to have the same binary image (e.g. .out file)
140 * run on multiple cores of a multi-core device. This causes a problem if
141 * the logger's buffers are in shared memory (e.g. DDR). Since the image is
142 * the same for all the cores, each core will attempt to write to the same
143 * buffer in the shared memory. To avoid this, either place the logger's
144 * buffers in non-shared memory, or set the numCores parameter to
145 * the number of cores on the device.
146 *
147 * Note: Use the `{@link #bufSection}` along with the Program.sectMap to
148 * place a logger instance's buffer into specific memory.
149 *
150 * Setting numCores to a value greater than 1 signals the logger to
151 * statically set aside additional memory ((x numCores), allowing each
152 * core to have the logger's configured buffer size amount of memory.
153 *
154 * Warning: Setting this parameter to a value greater than one should only
155 * be done when there is a single image used on multiple cores of a
156 * multi-core device AND the logger instance's buffer is in shared memory.
157 * While functionally it will still work, memory will be wasted if both
158 * these conditions are not met.
159 *
160 * The default is 1, which means do not reserve any additional memory
161 * for the logger.
162 */
163 metaonly config Int numCores = 1;
164
165
166 /*!
167 * ======== cpuId=========
168 * CPU ID to put in the packet header as the endpoint ID.
169 *
170 * Not required for C6X or C7X devices (uses DNUM).
171 */
172 metaonly config Int cpuId = 0;
173
174 175 176 177
178 enum TimestampSize {
179 TimestampSize_AUTO = 0, /*! Use the logger's default timestamp size */
180 TimestampSize_NONE = 1, /*! No timestamps logged with events */
181 TimestampSize_32b = 2, /*! 32-bit timestamps */
182 TimestampSize_64b = 3 /*! 64-bit timestamps */
183 };
184
185 /*!
186 * ======== timestampSize ========
187 * Size of the timestamps logged with the events. Set to TimestampSize_NONE
188 * to disable timestamps.
189 */
190 metaonly config TimestampSize timestampSize = TimestampSize_AUTO;
191
192 /*!
193 * ======== loadLogging ========
194 * Enable CPU load event logging.
195 *
196 * If loadLogging is false, CPU Load events will be disabled, otherwise the events
197 * will be logged.
198 * Use the {@link #loadLoggingRuntimeControl} parameter
199 * to determine whether the state can be modified during runtime.
200 */
201 metaonly config Bool loadLogging = true;
202
203 /*!
204 * ======== loadTaskLogging ========
205 * Enable Task load logging.
206 *
207 * If this is false, the Task load events will be disabled.
208 * Otherwise the events will be enabled.
209 * Use the {@link #loadLoggingRuntimeControl} parameter
210 * to determine whether the state can be modified during runtime.
211 */
212 metaonly config Bool loadTaskLogging = false;
213
214 /*!
215 * ======== loadSwiLogging ========
216 * Enable Software Interrupt (Swi) event logging.
217 *
218 * If this is false, the Swi load events will be disabled.
219 * Otherwise the events will be enabled.
220 * Use the {@link #loadLoggingRuntimeControl} parameter
221 * to determine whether the state can be modified during runtime.
222 */
223 metaonly config Bool loadSwiLogging = false;
224
225 /*!
226 * ======== loadHwiLogging ========
227 * Enable Hardware Interrupt (Hwi) event logging.
228 *
229 * If this is false, the Hwi load events will be disabled.
230 * Otherwise the events will be enabled.
231 * Use the {@link #loadLoggingRuntimeControl} parameter
232 * to determine whether the state can be modified during runtime.
233 */
234 metaonly config Bool loadHwiLogging = false;
235
236 /*!
237 * ======== loadLogger ========
238 * User-created logger used for the Load module Log events
239 *
240 * Leave null to have LoggingSetup automatically create
241 * the loadLogger if required.
242 */
243 config xdc.runtime.ILogger.Handle loadLogger = null;
244
245 /*!
246 * ======== loadLoggerSize ========
247 * Size (in MAUs) of the packet used to upload the Load module Log events.
248 */
249 metaonly config SizeT loadLoggerSize = 512;
250
251 /*!
252 * ======== loadLoggingRuntimeControl ========
253 * Specify whether load logging can be enabled / disabled at runtime.
254 *
255 * This determines what {@link xdc.runtime.Diags Diags} settings are
256 * applied to the module's Diags mask.
257 * If 'false', the Diags bits will be configured as
258 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
259 * bits will be configured as 'RUNTIME_ON'.
260 *
261 * Use the {@link #loadLogging} parameter
262 * to determine whether the event is ON or OFF. For example, the
263 * following two lines set the Load module's events to 'ALWAYS_ON'.
264 *
265 * @p(code)
266 * LoggingSetup.loadLogging = true;
267 * LoggingSetup.loadLoggingRuntimeControl = false;
268 * @p
269 */
270 metaonly config Bool loadLoggingRuntimeControl = false;
271
272 /*!
273 * ======== mainLogging ========
274 * Enable logging of application code.
275 *
276 * If mainLogging is false, application logging will be disabled, otherwise
277 * it will be enabled. Use the {@link #mainLoggingRuntimeControl} parameter
278 * to determine whether the state can be modified during runtime.
279 * Together, these two configuration parameters will be used to
280 * initialize the {@link xdc.runtime.Main} Diags mask.
281 *
282 * The table below shows the initial values of the
283 * xdc.runtime.Main Diags mask settings, based on mainLogging and
284 * mainLoggingRuntimeControl configuration. These settins only
285 * apply to Diags masks that have not been set in the application's
286 * configuration file. For example, this configuration code would
287 * cause xdc.runtime.Main's USER1 Diags mask to be unaffected by
288 * the settings of mainLogging and mainLoggingRuntimeControl:
289 *
290 * @p(code)
291 * Diags.setMaskMeta('xdc.runtime.Main', Diags.USER1, Diags.RUNTIME_ON);
292 * @p
293 *
294 * @p(html)
295 * <h3> Diags Mask Settings for xdc.runtime.Main </h3>
296 * <table border="1" cellpadding="3">
297 * <colgroup span="1"></colgroup> <colgroup span="5" align="center">
298 * </colgroup>
299 * <tr><th colspan="2" rowspan="2"> </th><th colspan="2"> mainLoggingRuntimeControl </th></tr>
300 * <tr><th> true </th><th> false </th></tr>
301 * <tr><th rowspan="2"> mainLogging </th><th> true </th><td> RUNTIME_ON</td>
302 * <td> ALWAYS_ON </td></tr>
303 * <tr><th> false </th><td> RUNTIME_OFF </td> <td> ALWAYS_OFF </td></tr>
304 * </table>
305 */
306 metaonly config Bool mainLogging = true;
307
308 /*!
309 * ======== mainLogger ========
310 * Logger used for application Log events
311 *
312 * Leave null to have LoggingSetup automatically create
313 * the mainLogger if required.
314 */
315 config xdc.runtime.ILogger.Handle mainLogger = null;
316
317 /*!
318 * ======== mainLoggerSize ========
319 * Size (in MAUs) of packet used for application Log
320 * events.
321 */
322 metaonly config SizeT mainLoggerSize = 1024;
323
324 /*!
325 * ======== mainLoggingRuntimeControl ========
326 * Specify whether application logging can be enabled / disabled
327 * at runtime.
328 *
329 * This parameter, together with {@link #mainLogging}, determine the
330 * initial {@link xdc.runtime.Diags} settings applied to
331 * {@link xdc.runtime.Main}.
332 * If 'false' and {@link #mainLogging} is true, the diags bits will
333 * be configured as ALWAYS_ON, meaning they can't be changed at runtime.
334 * If 'true', the bits will be configured as 'RUNTIME_ON'.
335 *
336 * Use the {@link #mainLogging} parameter
337 * to determine whether the event is ON or OFF. For example, the
338 * following two lines set the xdc.runtime.Main events to
339 * initially be 'RUNTIME_ON'.
340 *
341 * @p(code)
342 * LoggingSetup.mainLogging = true;
343 * LoggingSetup.mainLoggingRuntimeControl = true;
344 * @p
345 */
346 metaonly config Bool mainLoggingRuntimeControl = true;
347
348 /*!
349 * ======== sysbiosLogger ========
350 * Logger used for SYSBIOS modules' Log events
351 *
352 * Leave null to have LoggingSetup automatically create
353 * the sysbiosLogger if required.
354 */
355 config xdc.runtime.ILogger.Handle sysbiosLogger = null;
356
357 /*!
358 * ======== sysbiosLoggerSize ========
359 * Size (in MAUs) of the packet used for the TI-RTOS modules' Log events.
360 */
361 metaonly config SizeT sysbiosLoggerSize = 1024;
362
363 /*!
364 * ======== sysbiosTaskLogging ========
365 * Enable the SYSBIOS Task module's event logging.
366 *
367 * If false, Task events will be disabled, otherwise the events
368 * will be enabled.
369 * Use the {@link #sysbiosTaskLoggingRuntimeControl} parameter
370 * to determine whether the state can be modified during runtime.
371 */
372 metaonly config Bool sysbiosTaskLogging = true;
373
374 /*!
375 * ======== sysbiosTaskLoggingRuntimeControl ========
376 * Specify whether Task logging can be enabled / disabled at runtime.
377 *
378 * This parameter, together with {@link #sysbiosTaskLogging}, determine the
379 * initial {@link xdc.runtime.Diags Diags} settings applied to
380 * the Task module. For example, the following two
381 * lines initialize the Task module's events to
382 * 'ALWAYS_ON'.
383 *
384 * @p(code)
385 * LoggingSetup.sysbiosTaskLogging = true;
386 * LoggingSetup.sysbiosTaskLoggingRuntimeControl = false;
387 * @p
388 */
389 metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
390
391 /*!
392 * ======== sysbiosSwiLogging ========
393 * Enable SYSBIOS Swi module's event logging.
394 *
395 * If false, Swi events will be disabled, otherwise the events
396 * will be enabled.
397 * Use the {@link #sysbiosSwiLoggingRuntimeControl} parameter
398 * to determine whether the state can be modified during runtime.
399 */
400 metaonly config Bool sysbiosSwiLogging = false;
401
402 /*!
403 * ======== sysbiosSwiLoggingRuntimeControl ========
404 * Specify whether Swi logging can be enabled / disabled at runtime.
405 *
406 * This parameter, together with {@link #sysbiosSwiLogging}, determine the
407 * initial {@link xdc.runtime.Diags Diags} settings applied to
408 * the SYSBIOS Swi module. For example, the following two
409 * lines initialize the Swi module's events to 'RUNTIME_OFF'.
410 *
411 * @p(code)
412 * LoggingSetup.sysbiosSwiLogging = false;
413 * LoggingSetup.sysbiosSwiLoggingRuntimeControl = true;
414 * @p
415 */
416 metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
417
418 /*!
419 * ======== sysbiosHwiLogging ========
420 * Enable the SYSBIOS Hwi and Clock modules' event logging.
421 *
422 * If false, Hwi and Clock events will be disabled, otherwise the events
423 * will be enabled.
424 * Use the {@link #sysbiosHwiLoggingRuntimeControl} parameter
425 * to determine whether the state can be modified during runtime.
426 */
427 metaonly config Bool sysbiosHwiLogging = false;
428
429 /*!
430 * ======== sysbiosHwiLoggingRuntimeControl ========
431 * Specify whether Hwi and Clock logging can be enabled / disabled at
432 * runtime.
433 *
434 * This parameter, together with {@link #sysbiosHwiLogging}, determine the
435 * initial {@link xdc.runtime.Diags Diags} settings applied to
436 * the SYSBIOS Hwi and Clock modules. For example, the following two
437 * lines set the Hwi and Clock modules' events to 'ALWAYS_ON'.
438 *
439 * @p(code)
440 * LoggingSetup.sysbiosHwiLogging = true;
441 * LoggingSetup.sysbiosHwiLoggingRuntimeControl = false;
442 * @p
443 */
444 metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
445
446 /*!
447 * ======== sysbiosSemaphoreLogging ========
448 * Enable the SYSBIOS Semaphore module's event logging.
449 *
450 * If false, Semaphore events will be disabled, otherwise the events
451 * will be enabled.
452 * Use the {@link #sysbiosSemaphoreLoggingRuntimeControl} parameter
453 * to determine whether the state can be modified during runtime.
454 */
455 metaonly config Bool sysbiosSemaphoreLogging = false;
456
457 /*!
458 * ======== sysbiosSemaphoreLoggingRuntimeControl ========
459 * Specify whether Semaphore logging can be enabled / disabled at runtime.
460 *
461 * This parameter, together with {@link #sysbiosSemaphoreLogging}, determine the
462 * initial {@link xdc.runtime.Diags Diags} settings applied to
463 * the SYSBIOS Semaphore module. For example, the following code
464 * initializes the Semaphore module's events to 'RUNTIME_OFF'.
465 *
466 * @p(code)
467 * LoggingSetup.sysbiosSemaphoreLogging= false;
468 * LoggingSetup.sysbiosSemaphoreLoggingRuntimeControl = true;
469 * @p
470 */
471 metaonly config Bool sysbiosSemaphoreLoggingRuntimeControl = false;
472
473 /*!
474 * ======== profileLogging ========
475 * Enable logging of function profiling events.
476 *
477 * If this is false, the events will be disabled. Otherwise the events
478 * will be enabled.
479 */
480 metaonly config Bool profileLogging = false;
481
482 /*!
483 * ======== countingAndGraphingLogging ========
484 * Enable logging of counting and graphing events.
485 *
486 * If this is false, the events will be disabled. Otherwise the events
487 * will be enabled.
488 */
489 metaonly config Bool countingAndGraphingLogging = false;
490
491 /*!
492 * ======== benchmarkLogging ========
493 * Enable logging of benchmark events.
494 *
495 * If this is false, the events will be disabled. Otherwise the events
496 * will be enabled.
497 */
498 metaonly config Bool benchmarkLogging = false;
499
500 /*!
501 * ======== snapshotLogging ========
502 * Enable logging of snapshot events.
503 *
504 * If this is false, the events will be disabled. Otherwise the events
505 * will be enabled.
506 */
507 metaonly config Bool snapshotLogging = false;
508
509 /*!
510 * @_nodoc
511 * ======== overflowLoggerSize ========
512 * Overflow logger is no longer used.
513 *
514 * Size of logger used for overflow events when
515 * uploadMode is either JTAGRUNMODE or NONJTAG_AND_JTAGSTOPMODE
516 */
517 metaonly config SizeT overflowLoggerSize = 1024;
518
519 /*!
520 * @_nodoc
521 * ======== UploadMode ========
522 * Keep for backwards compatibility with 1.04 LoggingSetup.
523 */
524 enum UploadMode {
525 UploadMode_SIMULATOR = 1,
526 UploadMode_PROBEPOINT = 2,
527 UploadMode_JTAGSTOPMODE = 3,
528 UploadMode_JTAGRUNMODE = 4,
529 UploadMode_NONJTAGTRANSPORT = 5,
530 UploadMode_NONJTAG_AND_JTAGSTOPMODE = 6,
531 UploadMode_STREAMER = 7,
532 UploadMode_IDLE = 8,
533 UploadMode_STREAMER2 = 9
534 };
535
536 /*!
537 * @_nodoc
538 * ========= eventUploadMode ========
539 * Keep for backwards compatibility with 1.04 LoggingSetup.
540 */
541 metaonly config UploadMode eventUploadMode = UploadMode_JTAGSTOPMODE;
542
543 /*!
544 * ======== LoggerType ========
545 * Enum of the type of loggers that can be used.
546 */
547 metaonly enum LoggerType {
548 LoggerType_MIN, /*! LoggerMin - Minimal footprint logger
549 * (JTAG only) */
550 LoggerType_STOPMODE, /*! LoggerStopMode (JTAG only) */
551 LoggerType_JTAGRUNMODE, /*! LoggerRunMode JTAG (c6x only) */
552 LoggerType_RUNMODE, /*! LoggerRunMode ETHERNET upload */
553 LoggerType_IDLE, /*! LoggerIdle - Upload in Idle loop */
554
555 556 557 558 559 560
561 LoggerType_STREAMER2 /*! LoggerStreamer2 - Application manages
562 * logger buffers */
563 };
564
565 /*!
566 * ======== loggerType ========
567 * Configures the type of logger to use.
568 */
569 metaonly config LoggerType loggerType = LoggerType_STOPMODE;
570
571 /*!
572 * ======== multicoreEventCorrelation ========
573 * Set to true for multi-core applications.
574 *
575 * When set to true, the LoggingSetup module will automatically
576 * include the {@link ti.uia.runtime.LogSync LogSync} module. The LogSync module is
577 * required for events from multiple CPU cores to be correlated with each other.
578 * @see ti.uia.runtime.LogSync
579 *
580 */
581 metaonly config Bool multicoreEventCorrelation = false;
582
583 /*!
584 * @_nodoc
585 * ======== disableMulticoreEventCorrelation ========
586 * Keep for backwards compatibility with 1.04 LoggingSetup.
587 */
588 metaonly config Bool disableMulticoreEventCorrelation;
589
590 /*!
591 * ======== maxEventSize ========
592 * For Snapshot events with loggers that support the writeMemoryRange API,
593 * this specifies the maximum event size (in Maus) that
594 * can be written with a single event. Must be less than or equal to
595 * the logger's buffer size - 64.
596 *
597 * The logger's writeMemoryRange API checks to see if the event size required to
598 * write the block of memory is larger than maxEventSize. If so, it will
599 * split the memory range up into a number of smaller blocks and log the
600 * blocks using separate events with a common snapshot ID in order to
601 * allow the events to be collated and the original memory block to be
602 * reconstructed on the host.
603 */
604 config SizeT maxEventSize = 128;
605
606 /*!
607 * ======== syncLoggerSize ========
608 * Size (in MAUs) of the logger used for the {@link ti.uia.runtime.LogSync LogSync}
609 * modules' sync point events.
610 */
611 metaonly config SizeT syncLoggerSize = ti.uia.runtime.LogSync.defaultSyncLoggerSize;
612
613 /*! @_nodoc
614 * ======== createLogger =========
615 * Internal helper function that creates the type of logger
616 * appropriate for the LoggingSetup.uploadMode that has been configured.
617 *
618 * @param(loggerSize): the size of the logger in MAUs
619 * @param(loggerInstanceName): the name to assign to the logger instance
620 * @param (loggerPriority): the IUIATransfer.Priority to assign to the
621 * logger instance
622 *
623 * @a(return) returns the logger instance that was created
624 */
625 metaonly function createLogger(loggerSize, loggerInstanceName,
626 loggerPriority);
627
628 /*! @_nodoc
629 * ======== writeUIAMetaData ========
630 * Writes any UIA metadata required to support the module
631 *
632 * NOTE: This should only be called by ti.uia.runtime.UIAMetaData.xs in
633 * order to ensure that the UIA xml file has been properly opened and is
634 * ready for writing.
635 * @param(indent) the number of spaces to preceed the xml tag with
636 */
637 metaonly function writeUIAMetaData(indent);
638
639 /*! @_nodoc
640 * ======== showMulticoreEventCorrelationOption ========
641 * READ ONLY - used by XGCONF / LoggingSetup.xml
642 */
643 metaonly config Bool showMulticoreEventCorrelationOption = false;
644
645 /*! @_nodoc
646 * ======== isSysbiosLoggerAutoCreated ========
647 * READ ONLY - used by XGCONF / LoggingSetup.xml
648 */
649 metaonly config Bool isSysbiosLoggerAutoCreated = true;
650
651 /*! @_nodoc
652 * ======== isLoadLoggerAutoCreated ========
653 * READ ONLY - used by XGCONF / LoggingSetup.xml
654 */
655 metaonly config Bool isLoadLoggerAutoCreated = true;
656
657 /*! @_nodoc
658 * ======== isMainLoggerAutoCreated ========
659 * READ ONLY - used by XGCONF / LoggingSetup.xml
660 */
661 metaonly config Bool isMainLoggerAutoCreated = true;
662
663 /*! @_nodoc
664 * ======== showNumCoresOption ========
665 * READ ONLY - used by XGCONF / LoggingSetup.xml
666 */
667 metaonly config Bool showNumCoresOption = false;
668 }