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 * @a(Examples) 85 * Example 1: The following example defines a `Log` event, uses that `Log`
86 * event in a module, and configures the program to generate the `Log`
87 * event. In this example, both `USER1` and `USER2` bits are set in the
88 * event mask. This means that if either bit is set in the module's
89 * diagnostics mask, then the `Log` event will be generated.
90 *
91 * This is a part of the XDC specification file for the `Mod` module
92 * (Mod.xdc):
93 *
94 * @p(code) 95 * import xdc.runtime.Diags;
96 * import xdc.runtime.Log;
97 *
98 * config Log.Event L_someEvent = {
99 * mask: Diags.USER1 | Diags.USER2,
100 * level: Diags.LEVEL1,
101 * msg: "my log event message, arg1: 0x%x, arg2: 0x%x"
102 * };
103 * @p 104 *
105 * This is a part of the C code implementation of the Mod module:
106 *
107 * @p(code) 108 * #include <xdc/runtime/Log.h>
109 * UInt x, y;
110 *
111 * Log_write2(Mod_L_someEvent, (IArg)x, (IArg)y);
112 * @p 113 *
114 * The following configuration script demonstrates how the application might
115 * control the `Log` statements embedded in the `Mod` module at configuration
116 * time. In this case, the configuration script arranges for the `Log`
117 * statements within the `Mod` module (shown above) to always generate events.
118 * Without these configuration statements, no `Log` events would be generated
119 * by this module.
120 *
121 * This is part of the XDC configuration file for the application:
122 *
123 * @p(code) 124 * var Diags = xdc.useModule('xdc.runtime.Diags');
125 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
126 * var Mod = xdc.useModule('my.pkg.Mod');
127 * Mod.common$.diags_USER1 = Diags.ALWAYS_ON;
128 * Mod.common$.logger = LoggerSys.create();
129 * @p 130 *
131 * @p(html) 132 * <hr />
133 * @p 134 *
135 * Example 2: The following XDC configuration statements turn on enter
136 * and exit logging at configuration time for a module. Without any other
137 * changes in the runtime code, every time a module `Mod`'s function is
138 * being called or exits, an event will be logged.
139 *
140 * @p(code) 141 * var Diags = xdc.useModule('xdc.runtime.Diags');
142 * var Mod = xdc.useModule('my.pkg.Mod');
143 *
144 * Mod.common$.diags_ENTER = Diags.ALWAYS_ON;
145 * Mod.common$.diags_EXIT = Diags.ALWAYS_ON;
146 * @p 147 *
148 * @p(html) 149 * <hr />
150 * @p 151 *
152 * Example 3: The following example configures a module to support enter and
153 * exit logging, but defers the actual activation and deactivation of the
154 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
155 * function for details on specifying the control string.
156 *
157 * This is a part of the XDC configuration file for the application:
158 *
159 * @p(code) 160 * var Diags = xdc.useModule('xdc.runtime.Diags');
161 * var Mod = xdc.useModule('my.pkg.Mod');
162 *
163 * Mod.common$.diags_ENTER = Diags.RUNTIME_OFF;
164 * Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
165 * @p 166 *
167 * This is a part of the C code for the application:
168 *
169 * @p(code) 170 * // turn on enter and exit logging in the module
171 * Diags_setMask("my.pkg.Mod+EX");
172 *
173 * // turn off enter and exit logging in the module
174 * Diags_setMask("my.pkg.Mod-EX");
175 * @p 176 */
177
178 @CustomHeader
179
180 module Log {
181
182 /*!
183 * ======== NUMARGS ========
184 * Maximum number of arguments supported in `Log` events.
185 */
186 const Int NUMARGS = 8;
187
188 /*!
189 * ======== PRINTFID ========
190 * The `EventId` for `Log_print()` events
191 */
192 const EventId PRINTFID = 0;
193
194 /*!
195 * ======== EventDesc ========
196 * `Log` event descriptor
197 *
198 * Each `Log` event is defined by a `Log` event descriptor.
199 *
200 * The `mask` defines which bits in the module's diagnostics mask
201 * enable this `Log` event. Events "posted" via `Log_write` are only
202 * written to the underlying logger if one of the mask's bits matches
203 * the caller's module diagnostics settings (see
204 * `{@link xdc.runtime.Types#common$}`).
205 *
206 * The 'level' defines the event level of the event. While the diags
207 * bits selected in the 'mask' signify the "category" of the event (e.g.
208 * Entry/Exit, Analysis, Info), the 'level' field allows you to assign
209 * a "priority" or "detail level" to the event relative to other events in
210 * that category. There are four event levels defined by
211 * '{@link xdc.runtime.Diags#EventLevel}'.
212 *
213 * Filtering of events by level is handled by the ILogger implementation.
214 * ILogger implementations which also implement the {@link IFilterLogger}
215 * interface support filtering of events based on priority level.
216 *
217 * Specifying an event level is optional. Events that don't specify a
218 * level will receive Diags.LEVEL1 by default, making them the highest
219 * priority and ensuring that they will not inadvertently be filtered out
220 * by level-based filtering.
221 *
222 * The `msg` defines a printf style format string that defines how to
223 * render the arguments passed along the event in a `Log_write` call.
224 * For a description of the allowable format strings see
225 * `{@link #print6}`.
226 *
227 * @see #write8
228 * @see #print6
229 */
230 metaonlystruct EventDesc {
231 Diags.Mask mask; /*! event enable mask */
232 Diags.EventLevel level; /*! event level relative to other events */
233 String msg; /*! event "printf" message format string */
234 };
235
236 /*!
237 * ======== EventRec ========
238 * The target representation of a recorded event
239 *
240 * This structure defines how events are recorded on the target.
241 */
242 struct EventRec {
243 Types.Timestamp64 tstamp; /*! time event was written */
244 Bits32 serial; /*! serial number of event */
245 Types.Event evt; /*! target encoding of an Event */
246 IArg arg[NUMARGS]; /*! arguments passed via Log_write/print */
247 }
248
249 /*!
250 * ======== Event ========
251 * `Log` event type
252 *
253 * An `Event` is represented on the target as a 32-bit value that can
254 * be decoded offline to recover the `Event` information defined in
255 * a corresponding metaonly `EventDesc`. In addition, `Event`s may be
256 * decoded at runtime via methods provided in this module; see
257 * `{@link #getMask}` and `{@link #getEventId}`.
258 *
259 * When an event is "raised" a `{@link Types#Event Types_Event}` is
260 * created which has the same event ID as the `Log_Event` but also
261 * encodes the module ID of the caller. This new event is passed to
262 * the underlying `{@link ILogger}` module along with any arguments
263 * associated with the event.
264 *
265 * @see #getMask
266 * @see #getEventId
267 */
268 @Encoded typedef EventDesc Event;
269
270 /*!
271 * ======== EventId ========
272 * Unique ID embedded in each `{@link #Event}`
273 *
274 * This ID must be used to compare two `Event`s for equality. Event
275 * ids are not guaranteed to remain constant between different
276 * configurations of an application. For example, adding a module
277 * may cause the event ids of another module to change.
278 *
279 * However, event ids declared by a module are guaranteed to be
280 * consecutive values starting from the first declared
281 * `{@link #Event Log_Event}` and increasing to the last declared
282 * event. As a result, clients of a module can efficiently test ranges
283 * of events and modules can add new events, such as internal trace
284 * events, without breaking clients; simply be careful to add new events
285 * after any existing events in you module's `.xdc` specification.
286 *
287 * @see #getEventId
288 * @see #Event
289 */
290 typedef Types.RopeId EventId;
291
292 /*!
293 * ======== L_construct ========
294 * Lifecycle event posted when an instance is constructed
295 */
296 config Log.Event L_construct = {
297 mask: Diags.LIFECYCLE,
298 msg: "<-- construct: %p('%s')"
299 };
300
301 /*!
302 * ======== L_create ========
303 * Lifecycle event posted when an instance is created
304 */
305 config Log.Event L_create = {
306 mask: Diags.LIFECYCLE,
307 msg: "<-- create: %p('%s')"
308 };
309
310 /*!
311 * ======== L_destruct ========
312 * Lifecycle event posted when an instance is destructed
313 */
314 config Log.Event L_destruct = {
315 mask: Diags.LIFECYCLE,
316 msg: "--> destruct: (%p)"
317 };
318
319 /*!
320 * ======== L_delete ========
321 * Lifecycle event posted when an instance is deleted
322 */
323 config Log.Event L_delete = {
324 mask: Diags.LIFECYCLE,
325 msg: "--> delete: (%p)"
326 };
327
328 /*!
329 * ======== L_error ========
330 * Error event posted by Log_errorX API
331 *
332 * This event is marked as a STATUS event and given the priority level
333 * of ERROR.
334 *
335 * This event prints the Log call site (%$F) and a format string (%$S)
336 * which is recursively formatted with any addition arguments.
337 */
338 config Log.Event L_error = {
339 mask: Diags.STATUS,
340 level: Diags.ERROR,
341 msg: "ERROR: %$F%$S"
342 };
343
344 /*!
345 * ======== L_warning ========
346 * Warning event posted by Log_warningX API
347 *
348 * This event is marked as a STATUS event and given the priority level of
349 * WARNING.
350 *
351 * This event prints the Log call site (%$F) and a format string (%$S)
352 * which is recursively formatted with any addition arguments.
353 */
354 config xdc.runtime.Log.Event L_warning = {
355 mask: Diags.STATUS,
356 level: Diags.WARNING,
357 msg: "WARNING: %$F%$S"
358 };
359
360 /*!
361 * ======== L_info ========
362 * Info event posted by Log_infoX API
363 *
364 * This event is marked as an INFO event. The event priority is not
365 * specified in the event definition. Rather, it is specified as an
366 * argument to the Log_infoX APIs.
367 *
368 * This event prints the Log call site (%$F) and a format string (%$S)
369 * which is recursively formatted with any addition arguments.
370 */
371 config xdc.runtime.Log.Event L_info = {
372 mask: Diags.INFO,
373 msg: "%$F%$S"
374 };
375
376 /*!
377 * ======== getMask ========
378 * Get the `Diags` mask for the specified (encoded) event
379 *
380 * @param(evt) the `Log` event encoding a mask and event ID
381 *
382 * @a(returns) `Diags` mask for the specified event
383 */
384 @Macro Diags.Mask getMask(Event evt);
385
386 /*!
387 * ======== getRope ========
388 * Get RopeId of the Event.msg for the specified (encoded) event
389 * @_nodoc 390 */
391 @Macro Text.RopeId getRope(Event evt);
392
393 /*!
394 * ======== getEventId ========
395 * Get event ID of the specified (encoded) event
396 *
397 * This method is used to compare "known" `Log` events with
398 * "raised" `{@link Types#Event Types_Event}`.
399 *
400 * @param(evt) the `Log` event encoding a mask and event ID
401 *
402 * @a(returns) event ID of the specified event
403 *
404 * @see Types#getEventId
405 */
406 @Macro EventId getEventId(Event evt);
407
408 /*!
409 * ======== print0 ========
410 * Generate a `Log` "print event" with 0 arguments
411 *
412 * @see #print6
413 */
414 @Macro Void print0(Diags.Mask mask, String fmt);
415
416 /*!
417 * ======== print1 ========
418 * Generate a `Log` "print event" with 1 argument
419 *
420 * @see #print6
421 */
422 @Macro Void print1(Diags.Mask mask, String fmt, IArg a1);
423
424 /*!
425 * ======== print2 ========
426 * Generate a `Log` "print event" with 2 arguments
427 *
428 * @see #print6
429 */
430 @Macro Void print2(Diags.Mask mask, String fmt, IArg a1, IArg a2);
431
432 /*!
433 * ======== print3 ========
434 * Generate a `Log` "print event" with 3 arguments
435 *
436 * @see #print6
437 */
438 @Macro Void print3(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3);
439
440 /*!
441 * ======== print4 ========
442 * Generate a `Log` "print event" with 4 arguments
443 *
444 * @see #print6
445 */
446 @Macro Void print4(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3,
447 IArg a4);
448
449 /*!
450 * ======== print5 ========
451 * Generate a `Log` "print event" with 5 arguments
452 *
453 * @see #print6
454 */
455 @Macro Void print5(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3,
456 IArg a4, IArg a5);
457
458 /*!
459 * ======== print6 ========
460 * Generate a `Log` "print event" with 6 arguments
461 *
462 * As a convenience to C (as well as assembly language) programmers,
463 * the `Log` module provides a variation of the ever-popular `printf`
464 * function.
465 * The `print[0-6]` functions generate a `Log` "print event" and route
466 * it to the current module's logger.
467 *
468 * The arguments passed to `print[0-6]` may be characters, integers,
469 * strings, or pointers. However, because the declared type of the
470 * arguments is `{@link xdc IArg}`, all pointer arguments must be cast
471 * to an `IArg` type. `IArg` is an integral type large enough to hold
472 * any pointer or an `int`. So, casting a pointer to an `IArg` does
473 * not cause any loss of information and C's normal integer conversions
474 * make the cast unnecessary for integral arguments.
475 *
476 * The format string can use the following conversion characters.
477 * However, it is important to recall that all arguments referenced by
478 * these conversion characters have been converted to an `IArg`
479 * prior to conversion; so, the use of "length modifiers" should be
480 * avoided.
481 *
482 * @p(code) 483 * Conversion Character Description
484 * ------------------------------------------------
485 * %c Character
486 * %d Signed integer
487 * %u Unsigned integer
488 * %x Unsigned hexadecimal integer
489 * %o Unsigned octal integer
490 * %s Character string
491 * %p Pointer
492 * %f Single precision floating point (float)
493 * @p 494 *
495 * Format strings, while very convenient, are a well known source of
496 * portability problems: each format specification must precisely match
497 * the types of the arguments passed. Underlying "printf" functions use
498 * the format string to determine how far to advance through their
499 * argument list. For targets where pointer types and integers are the
500 * same size there are no problems. However, suppose a target's pointer
501 * type is larger than its integer type. In this case, because integer
502 * arguments are widened to be of type `IArg`, a format specification of
503 * "%d" causes an underlying `printf()` implementation to read the
504 * extended part of the integer argument as part of the next argument(!).
505 *
506 * To get around this problem and still allow the use of "natural"
507 * format specifications (e.g., `%d` and `%x` with optional width
508 * specifications), `{@link System#aprintf()}` is used which assumes
509 * that all arguments have been widened to be of type `IArg`.
510 *
511 * See `{@link System#printf}` for complete details.
512 *
513 * The `%f` format specifier is used to print a single precision float
514 * value. Note that `%f` assumes that sizeof(Float) <= sizeof(IArg).
515 * Most clients that interpret float values except that they are
516 * represented in IEEE 754 floating point format. Therefore, it is
517 * recommended that the float values are converted into that format prior
518 * to supplying the values to `Log` functions in cases where targets do
519 * not generate the float values in IEEE 754 floating point format by
520 * default.
521 *
522 * The first argument to a Log_print call is the diags category to be
523 * associated with the event.
524 *
525 * It is also possible to associate an event level with the event to
526 * enable filtering of events based on event level. Conceptually, it is
527 * best to regard the event level as completely separate from the event's
528 * diags category; however, the priority value actually occupies a part
529 * of the diags mask. For this reason, it is possible to specify an event
530 * level by ORing the level with the diags mask. For example, to print
531 * an INFO event of LEVEL2, you'd simply write:
532 * (Diags.INFO | Diags.LEVEL2)
533 *
534 * Specifying an event level is optional. Log_print calls which do not
535 * specify a level will receive the highest priority by default.
536 *
537 * @param(mask) enable bits and optional detail level for this event
538 * @param(fmt) a `printf` style format string
539 * @param(a1) value for first format conversion character
540 * @param(a2) value for second format conversion character
541 * @param(a3) value for third format conversion character
542 * @param(a4) value for fourth format conversion character
543 * @param(a5) value for fifth format conversion character
544 * @param(a6) value for sixth format conversion character
545 *
546 * @a(Examples) 547 * The following example demonstrates a typical usage.
548 * @p(code) 549 * String list[];
550 * UInt i;
551 *
552 * Log_print2(Diags_USER2, "list[%u] = %s\n", i, (IArg)list[i]);
553 * @p 554 * Note that the `IArg` cast above is only necessary for pointer
555 * arguments; C's normal parameter conversions implicitly convert
556 * integral arguments.
557 */
558 @Macro Void print6(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3,
559 IArg a4, IArg a5, IArg a6);
560
561 /*!
562 * ======== error0 ========
563 * Generate a `Log` "error event" with 0 arguments
564 *
565 * @see #error5
566 */
567 @Macro Void error0(String fmt);
568
569 /*!
570 * ======== error1 ========
571 * Generate a `Log` "error event" with 1 argument
572 *
573 * @see #error5
574 */
575 @Macro Void error1(String fmt, IArg a1);
576
577 /*!
578 * ======== error2 ========
579 * Generate a `Log` "error event" with 2 arguments
580 *
581 * @see #error5
582 */
583 @Macro Void error2(String fmt, IArg a1, IArg a2);
584
585 /*!
586 * ======== error3 ========
587 * Generate a `Log` "error event" with 3 arguments
588 *
589 * @see #error5
590 */
591 @Macro Void error3(String fmt, IArg a1, IArg a2, IArg a3);
592
593 /*!
594 * ======== error4 ========
595 * Generate a `Log` "error event" with 4 arguments
596 *
597 * @see #error5
598 */
599 @Macro Void error4(String fmt, IArg a1, IArg a2, IArg a3,
600 IArg a4);
601
602 /*!
603 * ======== error5 ========
604 * Generate a `Log` "error event" with 5 arguments
605 *
606 * The Log_error APIs are intended to allow users to easily log error
607 * events in their code. Similar to the Log_print APIs, Log_error does not
608 * require that you define an event. You simply pass an informative error
609 * string which can optionally be formatted with additional arguments. The
610 * error is logged with the predefined event {@link #L_error}.
611 *
612 * Log_error prepends a string to the message which identifies it as an
613 * ERROR and specifies the filename and line number of the Log_error call
614 * site. A simple example:
615 *
616 * @p(code) 617 * Log_error0("Invalid argument");
618 * @p 619 * This event will be formatted as (assuming that the above call was line
620 * 35 of "MyCode.c")
621 * @p(code) 622 * ERROR at "MyCode.c", line 35: Invalid argument
623 * @p 624 *
625 * Users may provide additional information in the error event, such as
626 * a predefined error code or details of the error. These additional
627 * values will be used to format the string passed to Log_error.
628 * @see #print6 for information about format strings.
629 *
630 * Log_error does not use a variable length argument list--you must call
631 * the appropriate Log_errorX API based on the number of arguments.
632 *
633 * @param(fmt) a reference to a constant error string / fmt string
634 * @param(a1) value for an additional parameter (e.g. an error code)
635 * @param(a2) value for an additional parameter
636 * @param(a3) value for an additional parameter
637 * @param(a4) value for an additional parameter
638 * @param(a5) value for an additional parameter
639 *
640 * @a(Examples) 641 * The following example demonstrates a typical usage.
642 * @p(code) 643 * Int myArg;
644 *
645 * Log_error1("Invalid argument: %d", myArg);
646 * @p 647 * The above event is formatted as, for example:
648 * @p(code) 649 * ERROR: "MyCode.c", line 35: Invalid argument: -1
650 * @p 651 */
652 @Macro Void error5(String fmt, IArg a1, IArg a2, IArg a3,
653 IArg a4, IArg a5);
654
655 /*!
656 * ======== warning0 ========
657 * Generate a `Log` "warning event" with 0 arguments
658 *
659 * @see #warning5
660 */
661 @Macro Void warning0(String fmt);
662
663 /*!
664 * ======== warning1 ========
665 * Generate a `Log` "warning event" with 1 argument
666 *
667 * @see #warning5
668 */
669 @Macro Void warning1(String fmt, IArg a1);
670
671 /*!
672 * ======== warning2 ========
673 * Generate a `Log` "warning event" with 2 arguments
674 *
675 * @see #warning5
676 */
677 @Macro Void warning2(String fmt, IArg a1, IArg a2);
678
679 /*!
680 * ======== warning3 ========
681 * Generate a `Log` "warning event" with 3 arguments
682 *
683 * @see #warning5
684 */
685 @Macro Void warning3(String fmt, IArg a1, IArg a2, IArg a3);
686
687 /*!
688 * ======== warning4 ========
689 * Generate a `Log` "warning event" with 4 arguments
690 *
691 * @see #warning5
692 */
693 @Macro Void warning4(String fmt, IArg a1, IArg a2, IArg a3,
694 IArg a4);
695
696 /*!
697 * ======== warning5 ========
698 * Generate a `Log` "warning event" with 5 arguments
699 *
700 * The Log_warning APIs provide the same features as the Log_error APIs,
701 * but are used to specifically log "warning" events.
702 * @see #error5
703 *
704 * The Log_warning APIs are equivalent to the Log_error APIs except that
705 * they use the predefined {@link #L_warning} event. Log_warning prepends
706 * a string to the message which identifies it as a WARNING and specifies
707 * the filename and line number of the Log_warning call site.
708 *
709 * @param(fmt) reference to a constant warning string / fmt string
710 * @param(a1) value for an additional parameter (e.g. a warning code)
711 * @param(a2) value for an additional parameter
712 * @param(a3) value for an additional parameter
713 * @param(a4) value for an additional parameter
714 * @param(a5) value for an additional parameter
715 *
716 * @a(Examples) 717 * The following example demonstrates a typical usage.
718 * @p(code) 719 * Int myArg;
720 *
721 * Log_warning1("Value may be too high: %d", myArg);
722 * @p 723 * The above event is formatted as:
724 * @p(code) 725 * WARNING: "MyCode.c", line 50: Value may be too high: 4096
726 * @p 727 */
728 @Macro Void warning5(String fmt, IArg a1, IArg a2, IArg a3,
729 IArg a4, IArg a5);
730
731 /*!
732 * ======== info0 ========
733 * Generate a `Log` "info event" with 0 arguments
734 *
735 * @see #info5
736 */
737 @Macro Void info0(String fmt);
738
739 /*!
740 * ======== info1 ========
741 * Generate a `Log` "info event" with 1 argument
742 *
743 * @see #info5
744 */
745 @Macro Void info1(String fmt, IArg a1);
746
747 /*!
748 * ======== info2 ========
749 * Generate a `Log` "info event" with 2 arguments
750 *
751 * @see #info5
752 */
753 @Macro Void info2(String fmt, IArg a1, IArg a2);
754
755 /*!
756 * ======== info3 ========
757 * Generate a `Log` "info event" with 3 arguments
758 *
759 * @see #info5
760 */
761 @Macro Void info3(String fmt, IArg a1, IArg a2, IArg a3);
762
763 /*!
764 * ======== info4 ========
765 * Generate a `Log` "info event" with 4 arguments
766 *
767 * @see #info5
768 */
769 @Macro Void info4(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
770
771 /*!
772 * ======== info5 ========
773 * Generate a `Log` "info event" with 5 arguments
774 *
775 * The Log_info APIs are provided for easily logging generic
776 * "informational" events with call site information. They are similar to
777 * the Log_print APIs in that they do not require you to define an event--
778 * you simply pass an informative printf-style string which can optionally
779 * be formatted with additional arguments. The info record is logged with
780 * the predefined event '{@link #L_info}'.
781 *
782 * The Log_info APIs log the {@link #L_info} event which uses the 'INFO'
783 * diags category. They do not allow you to specify an event priority.
784 *
785 * Log_info prepends the filename and line number of the call site to the
786 * message.
787 *
788 * @param(fmt) reference to a constant event string / fmt string
789 * @param(a1) value for an additional parameter (e.g. an event code)
790 * @param(a2) value for an additional parameter
791 * @param(a3) value for an additional parameter
792 * @param(a4) value for an additional parameter
793 * @param(a5) value for an additional parameter
794 *
795 * @a(Examples) 796 * The following example demonstrates a typical usage.
797 * @p(code) 798 * Int load;
799 *
800 * Log_info1("Current load: %d", load);
801 * @p 802 * The above event is formatted as, for example:
803 * @p(code) 804 * "MyCode.c", line 15: Current load: 25
805 * @p 806 */
807 @Macro Void info5(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
808
809 /*!
810 * ======== put0 ========
811 * Unconditionally put the specified Log event with 0 arguments
812 *
813 * @see #put4
814 */
815 @Macro Void put0(Log.Event evt, Types.ModuleId mid);
816
817 /*!
818 * ======== put1 ========
819 * Unconditionally put the specified Log event and 1 argument
820 *
821 * @see #put4
822 */
823 @Macro Void put1(Log.Event evt, Types.ModuleId mid, IArg a1);
824
825 /*!
826 * ======== put2 ========
827 * Unconditionally put the specified Log event and 2 arguments
828 *
829 * @see #put4
830 */
831 @Macro Void put2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
832
833 /*!
834 * ======== put4 ========
835 * Unconditionally put the specified Log event
836 *
837 * This method unconditionally puts the specified `{@link Event}`
838 * `evt` into the log. The `{@link Types#ModuleId}` `mid` should be the
839 * module ID of the module which is putting the event.
840 *
841 * @param(evt) the Log event to put into the log
842 * @param(mid) module ID of the module putting the event
843 * @param(a1) value for first format conversion character
844 * @param(a2) value for second format conversion character
845 * @param(a3) value for third format conversion character
846 * @param(a4) value for fourth format conversion character
847 *
848 * @see #put8
849 */
850 @Macro Void put4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
851 IArg a3, IArg a4);
852
853 /*!
854 * ======== put8 ========
855 * Unconditionally put the specified Log event and 8 arguments
856 *
857 * @see #put4
858 */
859 @Macro Void put8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
860 IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
861
862 /*!
863 * ======== write0 ========
864 * Generate a `Log` event with 0 arguments
865 *
866 * @see #write8
867 */
868 @Macro Void write0(Event evt);
869
870 /*!
871 * ======== write1 ========
872 * Generate a `Log` event with 1 argument
873 *
874 * @see #write8
875 */
876 @Macro Void write1(Event evt, IArg a1);
877
878 /*!
879 * ======== write2 ========
880 * Generate a `Log` event with 2 arguments
881 *
882 * @see #write8
883 */
884 @Macro Void write2(Event evt, IArg a1, IArg a2);
885
886 /*!
887 * ======== write3 ========
888 * Generate a `Log` event with 3 arguments
889 *
890 * @see #write8
891 */
892 @Macro Void write3(Event evt, IArg a1, IArg a2, IArg a3);
893
894 /*!
895 * ======== write4 ========
896 * Generate a `Log` event with 4 arguments
897 *
898 * @see #write8
899 */
900 @Macro Void write4(Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
901
902 /*!
903 * ======== write5 ========
904 * Generate a `Log` event with 5 arguments
905 *
906 * @see #write8
907 */
908 @Macro Void write5(Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
909
910 /*!
911 * ======== write6 ========
912 * Generate a `Log` event with 6 arguments
913 *
914 * @see #write8
915 */
916 @Macro Void write6(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
917 IArg a5, IArg a6);
918
919 /*!
920 * ======== write7 ========
921 * Generate a `Log` event with 7 arguments
922 *
923 * @see #write8
924 */
925 @Macro Void write7(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
926 IArg a5, IArg a6, IArg a7);
927
928 /*!
929 * ======== write8 ========
930 * Generate a `Log` event with 8 arguments
931 *
932 * If the mask in the specified `Log` event has any bit set which is
933 * also set in the current module's diagnostics mask, then this call to
934 * write will "raise" the given `Log` event.
935 *
936 * @param(evt) the `Log` event to write
937 * @param(a1) value for first format conversion character
938 * @param(a2) value for second format conversion character
939 * @param(a3) value for third format conversion character
940 * @param(a4) value for fourth format conversion character
941 * @param(a5) value for fifth format conversion character
942 * @param(a6) value for sixth format conversion character
943 * @param(a7) value for seventh format conversion character
944 * @param(a8) value for eighth format conversion character
945 */
946 @Macro Void write8(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
947 IArg a5, IArg a6, IArg a7, IArg a8);
948
949 /*!
950 * ======== doPrint ========
951 * Render an event as text via `{@link System#printf System_printf}`
952 *
953 * This method is not gated and may make more than one call to
954 * `System_printf`. This utility method is typically used within the
955 * implementation of a logger which initializes
956 * `{@link #EventRec Log_EventRec}` structures based on `Log` events
957 * produced by the application.
958 *
959 * @param(evRec) a non`NULL` pointer to an initialized `Log_EventRec`
960 * structure to be formated via
961 * `{@link System#printf System_printf}`.
962 */
963 Void doPrint(EventRec *evRec);
964
965 /*!
966 * @_nodoc 967 * ======== lookupEventMessage ========
968 * Returns the format string for the event with the given id.
969 */
970 function lookupEventMessage(eventId);
971
972 /*!
973 * @_nodoc 974 * ======== getTargetArgSize ========
975 * Returns the target size of a record argument in bytes (not MAUs).
976 */
977 function getTargetArgSize();
978
979 /*!
980 * @_nodoc 981 * ======== lookupEventName ========
982 */
983 function lookupEventName(eventId);
984
985 /*!
986 * @_nodoc 987 * ======== lookupModuleName ========
988 */
989 function lookupModuleName(modId);
990
991 /*!
992 * @_nodoc 993 * ======== getTargetEventRecSize ========
994 * Returns the record size in bytes (not MAUs).
995 */
996 function getTargetEventRecSize();
997
998 internal:
999
1000 /*
1001 * ======== idToInfo ========
1002 * Map event ID strings into a string of the form <eventName>::<eventMsg>
1003 */
1004 metaonlyconfig String idToInfo[string] = [];
1005
1006 }
1007 /*
1008 * @(#) xdc.runtime; 2, 1, 0,279; 5-27-2010 16:42:30; /db/ztree/library/trees/xdc/xdc-v38x/src/packages/
1009 */
1010