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 /*!
127 * ======== UploadMode ========
128 */
129 enum UploadMode {
130 UploadMode_SIMULATOR = 1,
131 UploadMode_PROBEPOINT = 2,
132 UploadMode_JTAGSTOPMODE = 3,
133 UploadMode_JTAGRUNMODE = 4,
134 UploadMode_NONJTAGTRANSPORT = 5,
135 UploadMode_NONJTAG_AND_JTAGSTOPMODE = 6,
136 UploadMode_STREAMER = 7,
137 UploadMode_IDLE = 8
138 }
139
140 /*!
141 * ======== loadLogger ========
142 * Logger used for the Load module Log events
143 */
144 config xdc.runtime.ILogger.Handle loadLogger = null;
145
146 /*!
147 * ======== loadLoggerSize ========
148 * Size (in MAUs) of logger used for the Load module Log events.
149 */
150 metaonly config SizeT loadLoggerSize = 512;
151
152 /*!
153 * ======== loadLogging ========
154 * Enable the Load module event logging.
155 *
156 * If this is false, the events will be disabled. Otherwise the events
157 * will be enabled.
158 * Use the {@link #loadLoggingRuntimeControl} parameter
159 * to determine whether the state can be modified during runtime.
160 */
161 metaonly config Bool loadLogging = true;
162
163 /*!
164 * ======== loadLoggingRuntimeControl ========
165 * Specify whether load logging can be enabled / disabled at runtime.
166 *
167 * This determines what diags settings are applied to the module's diags
168 * mask. If 'false', the diags bits will be configured as
169 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
170 * bits will be configured as 'RUNTIME_ON'.
171 *
172 * Use the {@link #loadLogging} parameter
173 * to determine whether the event is ON or OFF. For example, the
174 * following two lines set the Load modules events to
175 * initially be 'ALWAYS_ON'.
176 *
177 * @p(code)
178 * LoggingSetup.loadLogging = true;
179 * LoggingSetup.loadLoggingRuntimeControl = false;
180 * @p
181 */
182 metaonly config Bool loadLoggingRuntimeControl = true;
183
184 /*!
185 * ======== mainLogger ========
186 * Logger used for main and non-XDC modules Log events
187 */
188 config xdc.runtime.ILogger.Handle mainLogger = null;
189
190 /*!
191 * ======== mainLoggerSize ========
192 * Size (in MAUs) of logger used for the main and non-XDC modules Log events
193 */
194 metaonly config SizeT mainLoggerSize = 1024;
195
196 /*!
197 * ======== mainLogging ========
198 * Enable main and non-XDC modules event logging
199 *
200 * If this is false, the events will be disabled. Otherwise the events
201 * will be enabled.
202 * Use the {@link #mainLoggingRuntimeControl} parameter
203 * to determine whether the state can be modified during runtime.
204 */
205 metaonly config Bool mainLogging = true;
206
207 /*!
208 * ======== mainLoggingRuntimeControl ========
209 * Specify whether main logging can be enabled / disabled at runtime.
210 *
211 * This determines what diags settings are applied to the module's diags
212 * mask. If 'false', the diags bits will be configured as
213 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
214 * bits will be configured as 'RUNTIME_ON'.
215 *
216 * Use the {@link #mainLogging} parameter
217 * to determine whether the event is ON or OFF. For example, the
218 * following two lines set the Load modules events to
219 * initially be 'ALWAYS_ON'.
220 *
221 * @p(code)
222 * LoggingSetup.mainLogging = true;
223 * LoggingSetup.mainLoggingRuntimeControl = false;
224 * @p
225 */
226 metaonly config Bool mainLoggingRuntimeControl = true;
227
228 /*!
229 * ======== sysbiosLogger ========
230 * Logger used for SYSBIOS modules Log events
231 */
232 config xdc.runtime.ILogger.Handle sysbiosLogger = null;
233
234 /*!
235 * ======== sysbiosLoggerSize ========
236 * Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events
237 */
238 metaonly config SizeT sysbiosLoggerSize = 1024;
239
240 /*!
241 * ======== sysbiosHwiLogging ========
242 * Enable SYSBIOS Hwi and Clock modules' event logging
243 *
244 * If this is false, the events will be disabled. Otherwise the events
245 * will be enabled.
246 * Use the {@link #sysbiosHwiLoggingRuntimeControl} parameter
247 * to determine whether the state can be modified during runtime.
248 */
249 metaonly config Bool sysbiosHwiLogging = false;
250
251 /*!
252 * ======== sysbiosHwiLoggingRuntimeControl ========
253 * Specify whether Hwi and Clock logging can be enabled / disabled at runtime
254 *
255 * This determines what diags settings are applied to the module's diags
256 * mask. If 'false', the diags bits will be configured as
257 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
258 * bits will be configured as 'RUNTIME_ON'.
259 *
260 * Use the {@link #sysbiosHwiLogging} parameter
261 * to determine whether the event is ON or OFF. For example, the
262 * following two lines set the Load modules events to
263 * initially be 'ALWAYS_ON'.
264 *
265 * @p(code)
266 * LoggingSetup.sysbiosHwiLogging = true;
267 * LoggingSetup.sysbiosHwiLoggingRuntimeControl = false;
268 * @p
269 */
270 metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
271
272 /*!
273 * ======== sysbiosSwiLogging ========
274 * Enable SYSBIOS Swi module's event logging
275 *
276 * If this is false, the events will be disabled. Otherwise the events
277 * will be enabled.
278 * Use the {@link #sysbiosSwiLoggingRuntimeControl} parameter
279 * to determine whether the state can be modified during runtime.
280 */
281 metaonly config Bool sysbiosSwiLogging = false;
282
283 /*!
284 * ======== sysbiosSwiLoggingRuntimeControl ========
285 * Specify whether Swi logging can be enabled / disabled at runtime.
286 *
287 * This determines what diags settings are applied to the module's diags
288 * mask. If 'false', the diags bits will be configured as
289 * ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
290 * bits will be configured as 'RUNTIME_ON'.
291 *
292 * Use the {@link #sysbiosSwiLogging} parameter
293 * to determine whether the event is ON or OFF. For example, the
294 * following two lines set the Load modules events to
295 * initially be 'ALWAYS_ON'.
296 *
297 * @p(code)
298 * LoggingSetup.sysbiosSwiLogging = true;
299 * LoggingSetup.sysbiosSwiLoggingRuntimeControl = false;
300 * @p
301 */
302 metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
303
304 /*!
305 * ======== sysbiosTaskLogging ========
306 * Enable SYSBIOS Task module's event logging
307 *
308 * If this is false, the events will be disabled. Otherwise the events
309 * will be enabled.
310 * Use the {@link #sysbiosTaskLoggingRuntimeControl} parameter
311 * to determine whether the state can be modified during runtime.
312 */
313 metaonly config Bool sysbiosTaskLogging = true;
314
315 /*!
316 * ======== sysbiosTaskLoggingRuntimeControl ========
317 * Specify whether Task 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 #sysbiosTaskLogging} parameter
325 * to determine whether the event is ON or OFF. For example, the
326 * following two lines set the Load modules events to
327 * initially be 'ALWAYS_ON'.
328 *
329 * @p(code)
330 * LoggingSetup.sysbiosTaskLogging = true;
331 * LoggingSetup.sysbiosTaskLoggingRuntimeControl = false;
332 * @p
333 */
334 metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
335
336 /*!
337 * ======== overflowLoggerSize ========
338 * Size of logger used for overflow events when
339 * uploadMode is either JTAGRUNMODE or NONJTAG_AND_JTAGSTOPMODE
340 */
341 metaonly config SizeT overflowLoggerSize = 1024;
342
343 /*!
344 * ========= eventUploadMode ========
345 * Event upload mode
346 * @p
347 * Upload_SIMULATOR: events are uploaded from the simulator
348 * at the time the event is logged.
349 * @p(blist)
350 * - Upload_PROBEPOINT: events are uploaded at the time the event
351 * is logged. The target is briefly halted while the event is uploaded.
352 * - Upload_JTAGSTOPMODE: events are uploaded over JTAG when the target halts
353 * - Upload_JTAGRUNMODE: events are uploaded via JTAG while the target is running.
354 * - Upload_NONJTAGTRANSPORT: events are uploaded over a non-JTAG transport such
355 * as Ethernet. @see RTA for info on how to use the NDK as a transport.
356 * - Upload_NONJTAG_AND_JTAGSTOPMODE: events are uploaded over a non-JTAG transport.
357 * When the target halts (e.g. due to a breakpoint), any events that have not
358 * been uploaded yet are uploaded via JTAG.
359 * @p
360 *
361 * @a(Example)
362 * The following is an example of the configuration script used
363 * to configure the system to use LoggerCircBuf loggers in order to
364 * stream events from the target to the host while the target is running
365 * over JTAG. (Note that this mode is only supported for CPUs that
366 * support real-time JTAG accesses such as those in the C6X family,
367 * e.g. C64X+ and C66 CPUs)
368 *
369 * @p(code)
370 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
371 * LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_JTAGRUNMODE;
372 *
373 */
374 metaonly config UploadMode eventUploadMode = UploadMode_JTAGSTOPMODE;
375
376 /*!
377 * ======== disableMulticoreEventCorrelation ========
378 * Set to true for single core applications.
379 *
380 * When true the LoggingSetup module will not automatically
381 * include the the LogSync module. The LogSync module is
382 * required in order to enable events from multiple CPU cores
383 * to be correlated with each other.
384 * @see ti.uia.runtime.LogSync
385 *
386 */
387 metaonly config Bool disableMulticoreEventCorrelation = false;
388
389 /*! @_nodoc
390 * ======== createLogger =========
391 * Internal helper function that creates the type of logger
392 * appropriate for the LoggingSetup.uploadMode that has been configured.
393 *
394 * @param(loggerSize): the size of the logger in MAUs
395 * @param(loggerInstanceName): the name to assign to the logger instance
396 * @param (loggerPriority): the IUIATransfer.Priority to assign to the logger instance
397 * @a(return) returns the logger instance that was created
398 */
399 metaonly function createLogger(loggerSize,loggerInstanceName,loggerPriority);
400 }
401
402 403 404 405 406
407