1 /*
2 * Copyright (c) 2008 Texas Instruments. All rights reserved.
3 * This program and the accompanying materials are made available under the
4 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License
5 * v. 1.0 which accompanies this distribution. The Eclipse Public License is
6 * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
7 * Distribution License is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * Contributors:
11 * Texas Instruments - initial implementation
12 * */
13 /*
14 * ======== Log.xdc ========
15 */
16
17 /*!
18 * ======== Log ========
19 * Event logging manager
20 *
21 * RTSC modules and the application code generate `{@link #Event Log_Event}`
22 * events by calling the `Log` module's functions. The `Log` module then
23 * passes those events to an `{@link ILogger}` instance assigned to the event
24 * originating module, specified by that module's configuration parameter
25 * `common$.logger`. `ILogger` instances handle events, usually converting
26 * events to `{@link #EventRec Log_EventRec}` records prior to recording,
27 * transmitting, or displaying them.
28 *
29 * All events generated by a target module are stored and displayed by an
30 * `ILogger`, examples of which are instances of
31 * `{@link LoggerBuf xdc.runtime.LoggerBuf}` or
32 * `{@link LoggerSys xdc.runtime.LoggerSys}`. At runtime, modules
33 * generate events through this module, rather than invoking directly their
34 * `ILogger`s. By doing so, modules can be configured to use different
35 * `ILogger` implementations without any changes to their source code.
36 *
37 * A logger instance can accept `Log` events from any module, but a module
38 * can put `Log` events to only one logger instance. There can be one or
39 * more logger instances in a system. All `Log` calls that are not in a
40 * module are controlled by the module `{@link Main xdc.runtime.Main}`.
41 * For example, top-level application code or any existing sources that
42 * simply call the `Log` or `Assert` methods implicitly use the logger
43 * associated with the `Main` module.
44 *
45 * The generation of a `Log` event is controlled by a module's diagnostics
46 * mask, which is described in details in `{@link Diags}`. Each `Log` event
47 * is associated with a mask. `Log` events are generated only when a
48 * particular bit is set in both the `Log` event mask
49 * and the module's diagnostics mask. For example, a `Log` event mask with
50 * the `{@link Diags#USER1 USER1}` bit set is generated only when the `USER1`
51 * bit is also set in the module's diagnostics mask.
52 *
53 * There are two ways to generate `Log` events:
54 *
55 * @p(blist) 56 * - `{@link #write8 Log_write()}`, which is tailored for module writers
57 * and takes full advantage of the XDC configuration model. For example,
58 * the message string associated with the `Log` event need not be a part of
59 * the final application, significantly reducing the "footprint overhead"
60 * of embedding diagnostics in deployed systems. The `Log_write[0-8]()`
61 * functions allow up to 8 values to be passed to the logger. They expect
62 * the logger to handle any formatting. A `Log` event type allows you to
63 * specify the type of event.
64 * - `{@link #print6 Log_print()}`, which is designed for arbitrary C code.
65 * The `Log_print[0-6]()` functions allow up to 6 values to be passed along
66 * with a printf-like format string to the logger. They handle printf-style
67 * formatting.
68 * @p 69 *
70 * Both functions are controlled by the module's diagnostics mask. Their
71 * storage or output is defined by the logger that is assigned to the
72 * module that calls the `Log` methods or to the
73 * `{@link Main xdc.runtime.Main}` module if the caller is not part of a
74 * module.
75 *
76 * The `Log` function call sites are implemented in such a way that an
77 * optimizer can completely eliminate `Log` code from the program if the
78 * `Log` functions have been permanently disabled at configuration time. If
79 * the `Log` functions are permanently turned on at configuration time,
80 * then the optimizer can eliminate all runtime conditional checking and
81 * simply invoke the `Log` functions directly. Runtime checking is performed
82 * only when the `Log` functions are configured to be runtime modifiable.
83 *
84 * The Log calls can also be completely removed by defining the symbol
85 * `xdc_runtime_Log_DISABLE_ALL`. This can be done on the compile line, e.g.
86 * `-Dxdc_runtime_Log_DISABLE_ALL`. This will completely remove the `Log`
87 * statements from any code compiled with this flag, regardless of the
88 * application's logging configuration or your compiler's optimization
89 * settings.
90 *
91 * It is also possible to remove all logging except for
92 * `{@link #error Log_error}`, `{@link #warning Log_warning}`, or
93 * `{@link #info Log_info}` statements. This is done by first defining
94 * `xdc_runtime_Log_DISABLE_ALL`, followed by defining one or more of the
95 * symbols below to leave that type of logging enabled:
96 * @p(blist) 97 * - `xdc_runtime_Log_ENABLE_ERROR`
98 * - `xdc_runtime_Log_ENABLE_WARNING`
99 * - `xdc_runtime_Log_ENABLE_INFO`
100 * @p 101 * For example, to disable all `Log` statements except for `Log_error`, add
102 * the following to the compile line:
103 * @p(code) 104 * -Dxdc_runtime_Log_DISABLE_ALL -Dxdc_runtime_Log_ENABLE_ERROR
105 * @p 106 *
107 * @a(Examples) 108 * Example 1: The following example defines a `Log` event, uses that `Log`
109 * event in a module, and configures the program to generate the `Log`
110 * event. In this example, both `USER1` and `USER2` bits are set in the
111 * event mask. This means that if either bit is set in the module's
112 * diagnostics mask, then the `Log` event will be generated.
113 *
114 * This is a part of the XDC specification file for the `Mod` module
115 * (Mod.xdc):
116 *
117 * @p(code) 118 * import xdc.runtime.Diags;
119 * import xdc.runtime.Log;
120 *
121 * config Log.Event L_someEvent = {
122 * mask: Diags.USER1 | Diags.USER2,
123 * level: Diags.LEVEL1,
124 * msg: "my log event message, arg1: 0x%x, arg2: 0x%x"
125 * };
126 * @p 127 *
128 * This is a part of the C code implementation of the Mod module:
129 *
130 * @p(code) 131 * #include <xdc/runtime/Log.h>
132 * UInt x, y;
133 *
134 * Log_write2(Mod_L_someEvent, (IArg)x, (IArg)y);
135 * @p 136 *
137 * The following configuration script demonstrates how the application might
138 * control the `Log` statements embedded in the `Mod` module at configuration
139 * time. In this case, the configuration script arranges for the `Log`
140 * statements within the `Mod` module (shown above) to always generate events.
141 * Without these configuration statements, no `Log` events would be generated
142 * by this module.
143 *
144 * This is part of the XDC configuration file for the application:
145 *
146 * @p(code) 147 * var Diags = xdc.useModule('xdc.runtime.Diags');
148 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
149 * var Mod = xdc.useModule('my.pkg.Mod');
150 * Mod.common$.diags_USER1 = Diags.ALWAYS_ON;
151 * Mod.common$.logger = LoggerSys.create();
152 * @p 153 *
154 * @p(html) 155 * <hr />
156 * @p 157 *
158 * Example 2: The following XDC configuration statements turn on enter
159 * and exit logging at configuration time for a module. Without any other
160 * changes in the runtime code, every time a module `Mod`'s function is
161 * being called or exits, an event will be logged.
162 *
163 * @p(code) 164 * var Diags = xdc.useModule('xdc.runtime.Diags');
165 * var Mod = xdc.useModule('my.pkg.Mod');
166 *
167 * Mod.common$.diags_ENTER = Diags.ALWAYS_ON;
168 * Mod.common$.diags_EXIT = Diags.ALWAYS_ON;
169 * @p 170 *
171 * @p(html) 172 * <hr />
173 * @p 174 *
175 * Example 3: The following example configures a module to support enter and
176 * exit logging, but defers the actual activation and deactivation of the
177 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
178 * function for details on specifying the control string.
179 *
180 * This is a part of the XDC configuration file for the application:
181 *
182 * @p(code) 183 * var Diags = xdc.useModule('xdc.runtime.Diags');
184 * var Mod = xdc.useModule('my.pkg.Mod');
185 *
186 * Mod.common$.diags_ENTER = Diags.RUNTIME_OFF;
187 * Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
188 * @p 189 *
190 * This is a part of the C code for the application:
191 *
192 * @p(code) 193 * // turn on enter and exit logging in the module
194 * Diags_setMask("my.pkg.Mod+EX");
195 *
196 * // turn off enter and exit logging in the module
197 * Diags_setMask("my.pkg.Mod-EX");
198 * @p 199 */
200
201 @CustomHeader
202
203 module Log {
204
205 /*!
206 * ======== NUMARGS ========
207 * Maximum number of arguments supported in `Log` events.
208 */
209 const Int NUMARGS = 8;
210
211 /*!
212 * ======== PRINTFID ========
213 * The `EventId` for `Log_print()` events
214 */
215 const EventId PRINTFID = 0;
216
217 /*!
218 * ======== EventDesc ========
219 * `Log` event descriptor
220 *
221 * Each `Log` event is defined by a `Log` event descriptor.
222 *
223 * The `mask` defines which bits in the module's diagnostics mask
224 * enable this `Log` event. Events "posted" via `Log_write` are only
225 * written to the underlying logger if one of the mask's bits matches
226 * the caller's module diagnostics settings (see
227 * `{@link xdc.runtime.Types#common$}`).
228 *
229 * The 'level' defines the event level of the event. While the diags
230 * bits selected in the 'mask' signify the "category" of the event (e.g.
231 * Entry/Exit, Analysis, Info), the 'level' field allows you to assign
232 * a "priority" or "detail level" to the event relative to other events in
233 * that category. There are four event levels defined by
234 * '{@link xdc.runtime.Diags#EventLevel}'.
235 *
236 * Filtering of events by level is handled by the ILogger implementation.
237 * ILogger implementations which also implement the {@link IFilterLogger}
238 * interface support filtering of events based on priority level.
239 *
240 * Specifying an event level is optional. Events that don't specify a
241 * level will receive Diags.LEVEL1 by default, making them the highest
242 * priority and ensuring that they will not inadvertently be filtered out
243 * by level-based filtering.
244 *
245 * The `msg` defines a printf style format string that defines how to
246 * render the arguments passed along the event in a `Log_write` call.
247 * For a description of the allowable format strings see
248 * `{@link #print6}`.
249 *
250 * @see #write8
251 * @see #print6
252 */
253 metaonlystruct EventDesc {
254 Diags.Mask mask; /*! event enable mask */
255 Diags.EventLevel level; /*! event level relative to other events */
256 String msg; /*! event "printf" message format string */
257 };
258
259 /*!
260 * ======== EventRec ========
261 * The target representation of a recorded event
262 *
263 * This structure defines how events are recorded on the target.
264 */
265 struct EventRec {
266 Types.Timestamp64 tstamp; /*! time event was written */
267 Bits32 serial; /*! serial number of event */
268 Types.Event evt; /*! target encoding of an Event */
269 IArg arg[NUMARGS]; /*! arguments passed via Log_write/print */
270 }
271
272 /*!
273 * ======== Event ========
274 * `Log` event type
275 *
276 * An `Event` is represented on the target as a 32-bit value that can
277 * be decoded offline to recover the `Event` information defined in
278 * a corresponding metaonly `EventDesc`. In addition, `Event`s may be
279 * decoded at runtime via methods provided in this module; see
280 * `{@link #getMask}` and `{@link #getEventId}`.
281 *
282 * When an event is "raised" a `{@link Types#Event Types_Event}` is
283 * created which has the same event ID as the `Log_Event` but also
284 * encodes the module ID of the caller. This new event is passed to
285 * the underlying `{@link ILogger}` module along with any arguments
286 * associated with the event.
287 *
288 * @see #getMask
289 * @see #getEventId
290 */
291 @Encoded typedef EventDesc Event;
292
293 /*!
294 * ======== EventId ========
295 * Unique ID embedded in each `{@link #Event}`
296 *
297 * This ID must be used to compare two `Event`s for equality. Event
298 * ids are not guaranteed to remain constant between different
299 * configurations of an application. For example, adding a module
300 * may cause the event ids of another module to change.
301 *
302 * However, event ids declared by a module are guaranteed to be
303 * consecutive values starting from the first declared
304 * `{@link #Event Log_Event}` and increasing to the last declared
305 * event. As a result, clients of a module can efficiently test ranges
306 * of events and modules can add new events, such as internal trace
307 * events, without breaking clients; simply be careful to add new events
308 * after any existing events in you module's `.xdc` specification.
309 *
310 * @see #getEventId
311 * @see #Event
312 */
313 typedef Types.RopeId EventId;
314
315 /*!
316 * ======== L_construct ========
317 * Lifecycle event posted when an instance is constructed
318 */
319 config Log.Event L_construct = {
320 mask: Diags.LIFECYCLE,
321 msg: "<-- construct: %p('%s')"
322 };
323
324 /*!
325 * ======== L_create ========
326 * Lifecycle event posted when an instance is created
327 */
328 config Log.Event L_create = {
329 mask: Diags.LIFECYCLE,
330 msg: "<-- create: %p('%s')"
331 };
332
333 /*!
334 * ======== L_destruct ========
335 * Lifecycle event posted when an instance is destructed
336 */
337 config Log.Event L_destruct = {
338 mask: Diags.LIFECYCLE,
339 msg: "--> destruct: (%p)"
340 };
341
342 /*!
343 * ======== L_delete ========
344 * Lifecycle event posted when an instance is deleted
345 */
346 config Log.Event L_delete = {
347 mask: Diags.LIFECYCLE,
348 msg: "--> delete: (%p)"
349 };
350
351 /*!
352 * ======== L_error ========
353 * Error event posted by Log_errorX API
354 *
355 * This event is marked as a STATUS event and given the priority level
356 * of ERROR.
357 *
358 * This event prints the Log call site (%$F) and a format string (%$S)
359 * which is recursively formatted with any additional arguments.
360 */
361 config Log.Event L_error = {
362 mask: Diags.STATUS,
363 level: Diags.ERROR,
364 msg: "ERROR: %$F%$S"
365 };
366
367 /*!
368 * ======== L_warning ========
369 * Warning event posted by Log_warningX API
370 *
371 * This event is marked as a STATUS event and given the priority level of
372 * WARNING.
373 *
374 * This event prints the Log call site (%$F) and a format string (%$S)
375 * which is recursively formatted with any addition arguments.
376 */
377 config xdc.runtime.Log.Event L_warning = {
378 mask: Diags.STATUS,
379 level: Diags.WARNING,
380 msg: "WARNING: %$F%$S"
381 };
382
383 /*!
384 * ======== L_info ========
385 * Info event posted by Log_infoX API
386 *
387 * This event is marked as an INFO event. The event priority is not
388 * specified in the event definition. Rather, it is specified as an
389 * argument to the Log_infoX APIs.
390 *
391 * This event prints the Log call site (%$F) and a format string (%$S)
392 * which is recursively formatted with any addition arguments.
393 */
394 config xdc.runtime.Log.Event L_info = {
395 mask: Diags.INFO,
396 msg: "%$F%$S"
397 };
398
399 /*!
400 * ======== L_start ========
401 * Benchmark event used to log the start of an operation
402 * @_nodoc 403 *
404 * @a(Example) 405 * The following C code shows how to log a simple
406 * benchmark 'start' event along with a user-specified
407 * format string describing the event.
408 *
409 * @p(code) 410 * #include <xdc/runtime/Log.h>
411 * ...
412 * Log_write2(Log_L_start, (IArg)"My benchmark event", (IArg)myUniqueId);
413 * Log_write2(Log_L_stop, (IArg)"My benchmark event", (IArg)myUniqueId);
414 * @p 415 *
416 * @param(fmt) a constant string that provides format specifiers for
417 * up to 6 additional parameters
418 * @param(id) a unique ID used to match benchmark start and stop
419 * events
420 */
421 config xdc.runtime.Log.Event L_start = {
422 mask: Diags.ANALYSIS,
423 msg: "Start: %$S"};
424
425 /*!
426 * ======== L_stop ========
427 * Benchmark event used to log the end of an operation
428 * @_nodoc 429 *
430 * @a(Example) 431 * The following C code shows how to log a simple
432 * benchmark 'stop' event along with a user-specified
433 * format string describing the event.
434 *
435 * @p(code) 436 * #include <xdc/runtime/Log.h>
437 * ...
438 * Log_write2(Log_L_start, (IArg)"My benchmark event", (IArg)myUniqueId);
439 * Log_write2(Log_L_stop, (IArg)"My benchmark event", (IArg)myUniqueId);
440 * @p 441 *
442 * @param(fmt) a constant string that provides format specifiers for
443 * up to 6 additional parameters
444 * @param(id) a unique ID used to match benchmark start and stop
445 * events
446 */
447 config xdc.runtime.Log.Event L_stop = {
448 mask: Diags.ANALYSIS,
449 msg: "Stop: %$S"};
450
451 /*!
452 * ======== L_startInstance ========
453 * Benchmark event used to log the start of an operation instance
454 * @_nodoc 455 *
456 * Event parameter provides instance data to differentiate
457 * between multiple instances that can run in parallel.
458 *
459 * @a(Example) 460 * The following C code shows how to log a benchmark
461 * 'startInstance' event along with a user-specified
462 * instance identifier and a format string describing the event.
463 *
464 * @p(code) 465 * #include <xdc/runtime/Log.h>
466 * ...
467 * Log_write3(Log_L_startInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
468 * ...
469 * Log_write3(Log_L_stopInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
470 * @p 471 *
472 * @param(fmt) a constant string that provides format specifiers for
473 * up to 6 additional parameters
474 * @param(id) a unique ID used to match benchmark start and stop
475 * events
476 * @param(instId) a unique instance ID that can be used to match
477 * instance events
478 */
479 config xdc.runtime.Log.Event L_startInstance = {
480 mask: Diags.ANALYSIS,
481 msg: "StartInstance: %$S"
482 };
483
484 /*!
485 * ======== L_stopInstance ========
486 * Benchmark event used to log the end of an operation instance
487 * @_nodoc 488 *
489 * Event parameter provides instance data to differentiate
490 * between multiple instances that can run in parallel.
491 *
492 * @a(Example) 493 * The following C code shows how to log a benchmark
494 * 'stopInstance' event along with a user-specified
495 * instance identifier and a format string describing the event.
496 *
497 * @p(code) 498 * #include <xdc/runtime/Log.h>
499 * ...
500 * Log_write3(Log_L_startInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
501 * ...
502 * Log_write3(Log_L_stopInstance, (IArg)"My benchmark event", (IArg)uniqueId, (IArg)instId);
503 * @p 504 *
505 * @param(fmt) a constant string that provides format specifiers for
506 * up to 6 additional parameters
507 * @param(id) a unique ID used to match benchmark start and stop
508 * events
509 * @param(instId) a unique instance ID that can be used to match
510 * instance events
511 */
512 config xdc.runtime.Log.Event L_stopInstance = {
513 mask: Diags.ANALYSIS,
514 msg: "StopInstance: %$S"
515 };
516
517 /*!
518 * ======== getMask ========
519 * Get the `Diags` mask for the specified (encoded) event
520 *
521 * @param(evt) the `Log` event encoding a mask and event ID
522 *
523 * @a(returns) `Diags` mask for the specified event
524 */
525 @Macro Diags.Mask getMask(Event evt);
526
527 /*!
528 * ======== getRope ========
529 * Get RopeId of the Event.msg for the specified (encoded) event
530 * @_nodoc 531 */
532 @Macro Text.RopeId getRope(Event evt);
533
534 /*!
535 * ======== getEventId ========
536 * Get event ID of the specified (encoded) event
537 *
538 * This method is used to compare "known" `Log` events with
539 * "raised" `{@link Types#Event Types_Event}`.
540 *
541 * @param(evt) the `Log` event encoding a mask and event ID
542 *
543 * @a(returns) event ID of the specified event
544 *
545 * @see Types#getEventId
546 */
547 @Macro EventId getEventId(Event evt);
548
549 /*!
550 * ======== print0 ========
551 * Generate a `Log` "print event" with 0 arguments
552 *
553 * @see #print6
554 */
555 @Macro Void print0(Diags.Mask mask, CString fmt);
556
557 /*!
558 * ======== print1 ========
559 * Generate a `Log` "print event" with 1 argument
560 *
561 * @see #print6
562 */
563 @Macro Void print1(Diags.Mask mask, CString fmt, IArg a1);
564
565 /*!
566 * ======== print2 ========
567 * Generate a `Log` "print event" with 2 arguments
568 *
569 * @see #print6
570 */
571 @Macro Void print2(Diags.Mask mask, CString fmt, IArg a1, IArg a2);
572
573 /*!
574 * ======== print3 ========
575 * Generate a `Log` "print event" with 3 arguments
576 *
577 * @see #print6
578 */
579 @Macro Void print3(Diags.Mask mask, CString fmt, IArg a1, IArg a2,
580 IArg a3);
581
582 /*!
583 * ======== print4 ========
584 * Generate a `Log` "print event" with 4 arguments
585 *
586 * @see #print6
587 */
588 @Macro Void print4(Diags.Mask mask, CString fmt, IArg a1, IArg a2,
589 IArg a3, IArg a4);
590
591 /*!
592 * ======== print5 ========
593 * Generate a `Log` "print event" with 5 arguments
594 *
595 * @see #print6
596 */
597 @Macro Void print5(Diags.Mask mask, CString fmt, IArg a1, IArg a2,
598 IArg a3, IArg a4, IArg a5);
599
600 /*!
601 * ======== print6 ========
602 * Generate a `Log` "print event" with 6 arguments
603 *
604 * As a convenience to C (as well as assembly language) programmers,
605 * the `Log` module provides a variation of the ever-popular `printf`
606 * function.
607 * The `print[0-6]` functions generate a `Log` "print event" and route
608 * it to the current module's logger.
609 *
610 * The arguments passed to `print[0-6]` may be characters, integers,
611 * strings, or pointers. However, because the declared type of the
612 * arguments is `{@link xdc IArg}`, all pointer arguments must be cast
613 * to an `IArg` type. `IArg` is an integral type large enough to hold
614 * any pointer or an `int`. So, casting a pointer to an `IArg` does
615 * not cause any loss of information and C's normal integer conversions
616 * make the cast unnecessary for integral arguments.
617 *
618 * The format string can use the following conversion characters.
619 * However, it is important to recall that all arguments referenced by
620 * these conversion characters have been converted to an `IArg`
621 * prior to conversion; so, the use of "length modifiers" should be
622 * avoided.
623 *
624 * @p(code) 625 * Conversion Character Description
626 * ------------------------------------------------
627 * %c Character
628 * %d Signed integer
629 * %u Unsigned integer
630 * %x Unsigned hexadecimal integer
631 * %o Unsigned octal integer
632 * %s Character string
633 * %p Pointer
634 * %f Single precision floating point (float)
635 * @p 636 *
637 * Format strings, while very convenient, are a well known source of
638 * portability problems: each format specification must precisely match
639 * the types of the arguments passed. Underlying "printf" functions use
640 * the format string to determine how far to advance through their
641 * argument list. For targets where pointer types and integers are the
642 * same size there are no problems. However, suppose a target's pointer
643 * type is larger than its integer type. In this case, because integer
644 * arguments are widened to be of type `IArg`, a format specification of
645 * "%d" causes an underlying `printf()` implementation to read the
646 * extended part of the integer argument as part of the next argument(!).
647 *
648 * To get around this problem and still allow the use of "natural"
649 * format specifications (e.g., `%d` and `%x` with optional width
650 * specifications), `{@link System#aprintf()}` is used which assumes
651 * that all arguments have been widened to be of type `IArg`.
652 *
653 * See `{@link System#printf}` for complete details.
654 *
655 * The `%f` format specifier is used to print a single precision float
656 * value. Note that `%f` assumes that sizeof(Float) <= sizeof(IArg).
657 * Most clients that interpret float values expect that they are
658 * represented in IEEE 754 floating point format. Therefore, it is
659 * recommended that the float values be converted into that format prior
660 * to supplying the values to `Log` functions in cases where targets do
661 * not generate the float values in IEEE 754 floating point format by
662 * default.
663 *
664 * The first argument to a `Log_print` call is the diags category to be
665 * associated with the event.
666 *
667 * It is also possible to associate an event level with the event to
668 * enable filtering of events based on event level. Conceptually, it is
669 * best to regard the event level as completely separate from the event's
670 * diags category; however, the priority value actually occupies a part
671 * of the diags mask. For this reason, it is possible to specify an event
672 * level by OR'ing the level with the diags mask. For example, to print
673 * an `Diags_INFO` event of `Diags_LEVEL2`, you'd simply write:
674 * (Diags_INFO | Diags_LEVEL2)
675 *
676 * Specifying an event level is optional. `Log_print` calls which do not
677 * specify a level will receive the highest priority by default.
678 *
679 * @param(mask) enable bits and optional detail level for this event
680 * @param(fmt) a `printf` style format string
681 * @param(a1) value for first format conversion character
682 * @param(a2) value for second format conversion character
683 * @param(a3) value for third format conversion character
684 * @param(a4) value for fourth format conversion character
685 * @param(a5) value for fifth format conversion character
686 * @param(a6) value for sixth format conversion character
687 *
688 * @a(Examples) 689 * The following example demonstrates a typical usage.
690 * @p(code) 691 * String list[];
692 * UInt i;
693 *
694 * Log_print2(Diags_USER2, "list[%u] = %s\n", i, (IArg)list[i]);
695 * @p 696 * Note that the `IArg` cast above is only necessary for pointer
697 * arguments; C's normal parameter conversions implicitly convert
698 * integral arguments.
699 *
700 * To simplify the conversion from `float` arguments to `IArg`,
701 * the standard header `xdc/std.h` provides a macro, named floatToArg(),
702 * to do this conversion in a type safe manner. So, the following
703 * statement will print "`float = 2.3456`":
704 * @p(code) 705 * Log_print1(Diags_USER1, "float = %f", floatToArg(2.34567));
706 * @p 707 *
708 * Note that, if you are formatting events on the target, you must
709 * also add support for floating point to ASCII conversion to
710 * `{@link System#printf}`; for more information, see the
711 * `{@link System#extendedFormats}` reference documenation. For example:
712 * @p(code) 713 * var System = xdc.useModule('xdc.runtime.System');
714 * System.extendedFormats = "%f";
715 * @p 716 */
717 @Macro Void print6(Diags.Mask mask, CString fmt, IArg a1, IArg a2,
718 IArg a3, IArg a4, IArg a5, IArg a6);
719
720 /*!
721 * ======== error0 ========
722 * Generate a `Log` "error event" with 0 arguments
723 *
724 * @see #error5
725 */
726 @Macro Void error0(CString fmt);
727
728 /*!
729 * ======== error1 ========
730 * Generate a `Log` "error event" with 1 argument
731 *
732 * @see #error5
733 */
734 @Macro Void error1(CString fmt, IArg a1);
735
736 /*!
737 * ======== error2 ========
738 * Generate a `Log` "error event" with 2 arguments
739 *
740 * @see #error5
741 */
742 @Macro Void error2(CString fmt, IArg a1, IArg a2);
743
744 /*!
745 * ======== error3 ========
746 * Generate a `Log` "error event" with 3 arguments
747 *
748 * @see #error5
749 */
750 @Macro Void error3(CString fmt, IArg a1, IArg a2, IArg a3);
751
752 /*!
753 * ======== error4 ========
754 * Generate a `Log` "error event" with 4 arguments
755 *
756 * @see #error5
757 */
758 @Macro Void error4(CString fmt, IArg a1, IArg a2, IArg a3,
759 IArg a4);
760
761 /*!
762 * ======== error5 ========
763 * Generate a `Log` "error event" with 5 arguments
764 *
765 * The Log_error APIs are intended to allow users to easily log error
766 * events in their code. Similar to the Log_print APIs, Log_error does not
767 * require that you define an event. You simply pass an informative error
768 * string which can optionally be formatted with additional arguments. The
769 * error is logged with the predefined event {@link #L_error}.
770 *
771 * Log_error prepends a string to the message which identifies it as an
772 * ERROR and specifies the filename and line number of the Log_error call
773 * site. A simple example:
774 *
775 * @p(code) 776 * Log_error0("Invalid argument");
777 * @p 778 * This event will be formatted as (assuming that the above call was line
779 * 35 of "MyCode.c")
780 * @p(code) 781 * ERROR at "MyCode.c", line 35: Invalid argument
782 * @p 783 *
784 * Users may provide additional information in the error event, such as
785 * a predefined error code or details of the error. These additional
786 * values will be used to format the string passed to Log_error.
787 * @see #print6 for information about format strings.
788 *
789 * Log_error does not use a variable length argument list--you must call
790 * the appropriate Log_errorX API based on the number of arguments.
791 *
792 * @param(fmt) a reference to a constant error string / fmt string
793 * @param(a1) value for an additional parameter (e.g. an error code)
794 * @param(a2) value for an additional parameter
795 * @param(a3) value for an additional parameter
796 * @param(a4) value for an additional parameter
797 * @param(a5) value for an additional parameter
798 *
799 * @a(Examples) 800 * The following example demonstrates a typical usage.
801 * @p(code) 802 * Int myArg;
803 *
804 * Log_error1("Invalid argument: %d", myArg);
805 * @p 806 * The above event is formatted as, for example:
807 * @p(code) 808 * ERROR: "MyCode.c", line 35: Invalid argument: -1
809 * @p 810 */
811 @Macro Void error5(CString fmt, IArg a1, IArg a2, IArg a3,
812 IArg a4, IArg a5);
813
814 /*!
815 * ======== warning0 ========
816 * Generate a `Log` "warning event" with 0 arguments
817 *
818 * @see #warning5
819 */
820 @Macro Void warning0(CString fmt);
821
822 /*!
823 * ======== warning1 ========
824 * Generate a `Log` "warning event" with 1 argument
825 *
826 * @see #warning5
827 */
828 @Macro Void warning1(CString fmt, IArg a1);
829
830 /*!
831 * ======== warning2 ========
832 * Generate a `Log` "warning event" with 2 arguments
833 *
834 * @see #warning5
835 */
836 @Macro Void warning2(CString fmt, IArg a1, IArg a2);
837
838 /*!
839 * ======== warning3 ========
840 * Generate a `Log` "warning event" with 3 arguments
841 *
842 * @see #warning5
843 */
844 @Macro Void warning3(CString fmt, IArg a1, IArg a2, IArg a3);
845
846 /*!
847 * ======== warning4 ========
848 * Generate a `Log` "warning event" with 4 arguments
849 *
850 * @see #warning5
851 */
852 @Macro Void warning4(CString fmt, IArg a1, IArg a2, IArg a3,
853 IArg a4);
854
855 /*!
856 * ======== warning5 ========
857 * Generate a `Log` "warning event" with 5 arguments
858 *
859 * The Log_warning APIs provide the same features as the Log_error APIs,
860 * but are used to specifically log "warning" events.
861 * @see #error5
862 *
863 * The Log_warning APIs are equivalent to the Log_error APIs except that
864 * they use the predefined {@link #L_warning} event. Log_warning prepends
865 * a string to the message which identifies it as a WARNING and specifies
866 * the filename and line number of the Log_warning call site.
867 *
868 * @param(fmt) reference to a constant warning string / fmt string
869 * @param(a1) value for an additional parameter (e.g. a warning code)
870 * @param(a2) value for an additional parameter
871 * @param(a3) value for an additional parameter
872 * @param(a4) value for an additional parameter
873 * @param(a5) value for an additional parameter
874 *
875 * @a(Examples) 876 * The following example demonstrates a typical usage.
877 * @p(code) 878 * Int myArg;
879 *
880 * Log_warning1("Value may be too high: %d", myArg);
881 * @p 882 * The above event is formatted as:
883 * @p(code) 884 * WARNING: "MyCode.c", line 50: Value may be too high: 4096
885 * @p 886 */
887 @Macro Void warning5(CString fmt, IArg a1, IArg a2, IArg a3,
888 IArg a4, IArg a5);
889
890 /*!
891 * ======== info0 ========
892 * Generate a `Log` "info event" with 0 arguments
893 *
894 * @see #info5
895 */
896 @Macro Void info0(CString fmt);
897
898 /*!
899 * ======== info1 ========
900 * Generate a `Log` "info event" with 1 argument
901 *
902 * @see #info5
903 */
904 @Macro Void info1(CString fmt, IArg a1);
905
906 /*!
907 * ======== info2 ========
908 * Generate a `Log` "info event" with 2 arguments
909 *
910 * @see #info5
911 */
912 @Macro Void info2(CString fmt, IArg a1, IArg a2);
913
914 /*!
915 * ======== info3 ========
916 * Generate a `Log` "info event" with 3 arguments
917 *
918 * @see #info5
919 */
920 @Macro Void info3(CString fmt, IArg a1, IArg a2, IArg a3);
921
922 /*!
923 * ======== info4 ========
924 * Generate a `Log` "info event" with 4 arguments
925 *
926 * @see #info5
927 */
928 @Macro Void info4(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
929
930 /*!
931 * ======== info5 ========
932 * Generate a `Log` "info event" with 5 arguments
933 *
934 * The Log_info APIs are provided for easily logging generic
935 * "informational" events with call site information. They are similar to
936 * the Log_print APIs in that they do not require you to define an event--
937 * you simply pass an informative printf-style string which can optionally
938 * be formatted with additional arguments. The info record is logged with
939 * the predefined event '{@link #L_info}'.
940 *
941 * The Log_info APIs log the {@link #L_info} event which uses the 'INFO'
942 * diags category. They do not allow you to specify an event priority.
943 *
944 * Log_info prepends the filename and line number of the call site to the
945 * message.
946 *
947 * @param(fmt) reference to a constant event string / fmt string
948 * @param(a1) value for an additional parameter (e.g. an event code)
949 * @param(a2) value for an additional parameter
950 * @param(a3) value for an additional parameter
951 * @param(a4) value for an additional parameter
952 * @param(a5) value for an additional parameter
953 *
954 * @a(Examples) 955 * The following example demonstrates a typical usage.
956 * @p(code) 957 * Int load;
958 *
959 * Log_info1("Current load: %d", load);
960 * @p 961 * The above event is formatted as, for example:
962 * @p(code) 963 * "MyCode.c", line 15: Current load: 25
964 * @p 965 */
966 @Macro Void info5(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4,
967 IArg a5);
968
969 /*!
970 * ======== put0 ========
971 * Unconditionally put the specified Log event with 0 arguments
972 *
973 * @see #put8
974 */
975 @Macro Void put0(Log.Event evt, Types.ModuleId mid);
976
977 /*!
978 * ======== put1 ========
979 * Unconditionally put the specified Log event and 1 argument
980 *
981 * @see #put8
982 */
983 @Macro Void put1(Log.Event evt, Types.ModuleId mid, IArg a1);
984
985 /*!
986 * ======== put2 ========
987 * Unconditionally put the specified Log event and 2 arguments
988 *
989 * @see #put8
990 */
991 @Macro Void put2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
992
993 /*!
994 * ======== put4 ========
995 * Unconditionally put the specified Log event and 4 arguments
996 *
997 * @see #put8
998 */
999 @Macro Void put4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
1000 IArg a3, IArg a4);
1001
1002 /*!
1003 * ======== put8 ========
1004 * Unconditionally put the specified Log event and 8 arguments
1005 *
1006 * This method unconditionally puts the specified `{@link Event}`
1007 * `evt` into the log. The `{@link Types#ModuleId}` `mid` should be the
1008 * module ID of the module which is putting the event.
1009 *
1010 * @param(evt) the Log event to put into the log
1011 * @param(mid) module ID of the module putting the event
1012 * @param(a1) value for first format conversion character
1013 * @param(a2) value for second format conversion character
1014 * @param(a3) value for third format conversion character
1015 * @param(a4) value for fourth format conversion character
1016 * @param(a5) value for fifth format conversion character
1017 * @param(a6) value for sixth format conversion character
1018 * @param(a7) value for seventh format conversion character
1019 * @param(a8) value for eighth format conversion character
1020 */
1021 @Macro Void put8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
1022 IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
1023
1024 /*!
1025 * ======== write0 ========
1026 * Generate a `Log` event with 0 arguments
1027 *
1028 * @see #write8
1029 */
1030 @Macro Void write0(Event evt);
1031
1032 /*!
1033 * ======== write1 ========
1034 * Generate a `Log` event with 1 argument
1035 *
1036 * @see #write8
1037 */
1038 @Macro Void write1(Event evt, IArg a1);
1039
1040 /*!
1041 * ======== write2 ========
1042 * Generate a `Log` event with 2 arguments
1043 *
1044 * @see #write8
1045 */
1046 @Macro Void write2(Event evt, IArg a1, IArg a2);
1047
1048 /*!
1049 * ======== write3 ========
1050 * Generate a `Log` event with 3 arguments
1051 *
1052 * @see #write8
1053 */
1054 @Macro Void write3(Event evt, IArg a1, IArg a2, IArg a3);
1055
1056 /*!
1057 * ======== write4 ========
1058 * Generate a `Log` event with 4 arguments
1059 *
1060 * @see #write8
1061 */
1062 @Macro Void write4(Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
1063
1064 /*!
1065 * ======== write5 ========
1066 * Generate a `Log` event with 5 arguments
1067 *
1068 * @see #write8
1069 */
1070 @Macro Void write5(Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
1071
1072 /*!
1073 * ======== write6 ========
1074 * Generate a `Log` event with 6 arguments
1075 *
1076 * @see #write8
1077 */
1078 @Macro Void write6(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
1079 IArg a5, IArg a6);
1080
1081 /*!
1082 * ======== write7 ========
1083 * Generate a `Log` event with 7 arguments
1084 *
1085 * @see #write8
1086 */
1087 @Macro Void write7(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
1088 IArg a5, IArg a6, IArg a7);
1089
1090 /*!
1091 * ======== write8 ========
1092 * Generate a `Log` event with 8 arguments
1093 *
1094 * If the mask in the specified `Log` event has any bit set which is
1095 * also set in the current module's diagnostics mask, then this call to
1096 * write will "raise" the given `Log` event.
1097 *
1098 * @param(evt) the `Log` event to write
1099 * @param(a1) value for first format conversion character
1100 * @param(a2) value for second format conversion character
1101 * @param(a3) value for third format conversion character
1102 * @param(a4) value for fourth format conversion character
1103 * @param(a5) value for fifth format conversion character
1104 * @param(a6) value for sixth format conversion character
1105 * @param(a7) value for seventh format conversion character
1106 * @param(a8) value for eighth format conversion character
1107 */
1108 @Macro Void write8(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
1109 IArg a5, IArg a6, IArg a7, IArg a8);
1110
1111 /*!
1112 * ======== doPrint ========
1113 * Render an event as text via `{@link System#printf System_printf}`
1114 *
1115 * This method is not gated and may make more than one call to
1116 * `System_printf`. This utility method is typically used within the
1117 * implementation of a logger which initializes
1118 * `{@link #EventRec Log_EventRec}` structures based on `Log` events
1119 * produced by the application.
1120 *
1121 * @param(evRec) a non`NULL` pointer to an initialized `Log_EventRec`
1122 * structure to be formated via
1123 * `{@link System#printf System_printf}`.
1124 */
1125 Void doPrint(EventRec *evRec);
1126
1127 /*!
1128 * @_nodoc 1129 * ======== lookupEventMessage ========
1130 * Returns the format string for the event with the given id.
1131 */
1132 function lookupEventMessage(eventId);
1133
1134 /*!
1135 * @_nodoc 1136 * ======== getTargetArgSize ========
1137 * Returns the target size of a record argument in bytes (not MAUs).
1138 */
1139 function getTargetArgSize();
1140
1141 /*!
1142 * @_nodoc 1143 * ======== lookupEventName ========
1144 */
1145 function lookupEventName(eventId);
1146
1147 /*!
1148 * @_nodoc 1149 * ======== lookupModuleName ========
1150 */
1151 function lookupModuleName(modId);
1152
1153 /*!
1154 * @_nodoc 1155 * ======== getTargetEventRecSize ========
1156 * Returns the record size in bytes (not MAUs).
1157 */
1158 function getTargetEventRecSize();
1159
1160 internal:
1161
1162 /*
1163 * ======== idToInfo ========
1164 * Map event ID strings into a string of the form <eventName>::<eventMsg>
1165 */
1166 metaonlyconfig String idToInfo[string] = [];
1167 }
1168 /*
1169 * @(#) xdc.runtime; 2, 1, 0,421; 6-24-2013 18:59:42; /db/ztree/library/trees/xdc/xdc-z52x/src/packages/
1170 */
1171