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