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