1 /* --COPYRIGHT--,ESD
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 * --/COPYRIGHT--*/
13 /*!
14 * ======== ILogger ========
15 * Interface to service Log events
16 *
17 * A logger is responsible for recording, transmitting, or otherwise
18 * handling `{@link Log#EventDesc Log Events}` generated by clients of the
19 * `{@link Log}` module. The `Log` module uses modules that implement the
20 * `ILogger` interface to record the log events. Most application code will
21 * use the `Log` module instead of directly calling the specific `ILogger`
22 * module implementation.
23 *
24 * All logger implementations must inherit from this interface. The
25 * derived implementations must implement the functions defined in this
26 * interface but may also add additional configuration parameters and
27 * functions.
28 */
29 interface ILogger {
30
31 instance:
32
33 /*!
34 * ======== write4 ========
35 * Process a log event with up to 4 arguments.
36 *
37 * At the time this method is called, `evt` encodes two values: the
38 * module ID of the module that "triggered" a `{@link Log#Event}`
39 * and the `{@link Log#EventId}` of the event. The module ID can
40 * be obtained via `{@link Types#getModuleId}(evt)`
41 * and the event ID can be obtained via
42 * `{@link Types#getEventId}(evt)`.
43 *
44 * The event ID can be used to compare against other known
45 * `Log.Event`s.
46 * @p(code) 47 * if (Log_getEventId(MY_EVENT) == Types_getEventId(evt)) {
48 * :
49 * }
50 * @p 51 *
52 * The event ID value of `0` is used to indicate an event triggered
53 * by a call to one of the `{@link Log#print0 Log_print[0-6]}`
54 * methods. These methods take a
55 * format string rather than a `Log_Event` argument and, as a result,
56 * the event ID encoded in `evt` is `0` and the parameter `a1` is
57 * the format string.
58 *
59 * Non-zero event IDs can also be used to access the `msg` string
60 * associated with the `{@link Log#EventDesc}` that originally
61 * defined the `Log` event.
62 * @p(code) 63 * Types_EventId id = Types_getEventId(evt));
64 * if (id != 0) {
65 * String msg = Text_ropeText(id);
66 * System_aprintf(msg, a1, a2, a3, a4);
67 * }
68 * @p 69 * This works because an event's ID is simply an offset into a table
70 * of characters (maintained by the `{@link Text}` module)
71 * containing the event's msg string.
72 *
73 * @param(evt) event to be logged
74 *
75 * @param(a1) arbitrary argument passed by caller
76 *
77 * This parameter, along with `a2`, `a3`, and `a4` are parameters
78 * that are to be interpreted according to the message format string
79 * associated with `evt`.
80 *
81 * @see Log#Event
82 * @see Log#EventDesc
83 * @see Text#ropeText
84 * @see Types#getEventId
85 */
86 Void write4(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
87
88 /*!
89 * ======== write8 ========
90 * Process a log event with up to 8 arguments.
91 *
92 * Same as `write4` except with 8 arguments rather than 4.
93 *
94 * @see ILogger#write4()
95 */
96 Void write8(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
97 IArg a5, IArg a6, IArg a7, IArg a8);
98 }
99 /*
100 * @(#) xdc.runtime; 2, 0, 0, 0,214; 7-29-2009 14:53:43; /db/ztree/library/trees/xdc-t56x/src/packages/
101 */
102