1 2 3 4 5 6 7 8 9 10 11 12
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 * Events may be defined with a detail level, but the Log interface does not
30 * inherently provide support for filtering of events based on detail level.
31 * Instead, this is left to the ILogger implementation. ILogger
32 * implementations which wish to support filtering based on detail level
33 * should implement the IFilterLogger interface, which extends the ILogger
34 * interface to include APIs for getting and setting the current filter level.
35 */
36 interface ILogger {
37
38 /*!
39 * ======== getMetaArgs ========
40 * Returns any meta data needed to support RTA.
41 *
42 * This meta data should be returned in the form of a structure which
43 * can be converted into XML. This data is added to the RTA XML file
44 * during the application's configuration, and can be accessed later
45 * through the xdc.rta.MetaData module.
46 *
47 * The MetaData is returned per instance of the ILogger module. The
48 * instance object is passed to the function as the first argument.
49 *
50 * The second argument is the index of the instance in the list of
51 * the ILogger's static instances.
52 */
53 function getMetaArgs(inst, instNum);
54
55 instance:
56
57 /*!
58 * ======== enable ========
59 * Enable a log
60 *
61 * @a(returns)
62 * The function returns the state of the log (`TRUE` if enabled,
63 * `FALSE` if disabled) before the call. This return value allows
64 * clients to restore the previous state.
65 * Note: not thread safe.
66 */
67 Bool enable();
68
69 /*!
70 * ======== disable ========
71 * Disable a log
72 *
73 * Events written to a disabled log are silently discarded.
74 *
75 * @a(returns)
76 * The function returns the state of the log (`TRUE` if enabled,
77 * `FALSE` if disabled) before the call. This return value allows
78 * clients to restore the previous state.
79 * Note: not thread safe.
80 */
81 Bool disable();
82
83 /*!
84 * ======== write0 ========
85 * Process a log event with 0 arguments.
86 *
87 * Same as `write4` except with 0 arguments rather than 4.
88 *
89 * @see ILogger#write4()
90 */
91 Void write0(Log.Event evt, Types.ModuleId mid);
92
93 /*!
94 * ======== write1 ========
95 * Process a log event with 1 arguments.
96 *
97 * Same as `write4` except with 1 arguments rather than 4.
98 *
99 * @see ILogger#write4()
100 */
101 Void write1(Log.Event evt, Types.ModuleId mid, IArg a1);
102
103 /*!
104 * ======== write2 ========
105 * Process a log event with 2 arguments.
106 *
107 * Same as `write4` except with 2 arguments rather than 4.
108 *
109 * @see ILogger#write4()
110 */
111 Void write2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
112
113 /*!
114 * ======== write4 ========
115 * Process a log event with up to 4 arguments.
116 *
117 * The `evt` argument is of type Log.Event, which encodes the
118 * `{@link Log#EventId}`, the `{@link Diags#Mask}`, and the
119 * `{@link Diags#EventLevel}` of the event. The event ID can be obtained
120 * via `{@link Types#getEventId}(evt)`, the Diags mask can be obtained via
121 * `{@link Diags#getMask}(evt)`, and the event level can be obtained via
122 * `{@link Diags#getLevel}(evt)`.
123 *
124 * The `modId` argument is the module ID of the module that logged the
125 * event.
126 *
127 * The event information can be used by the logger to handle different
128 * events specially. For example, the event ID can be used to compare
129 * against other known `Log.Event`s.
130 * @p(code)
131 * if (Log_getEventId(MY_EVENT) == Log_getEventId(evt)) {
132 * :
133 * }
134 * @p
135 * The Diags mask and event level can be used for filtering of events
136 * based on event level (see {@link IFilterLogger}), or even routing
137 * events to separate loggers based on diags category (see, for example,
138 * {@link LoggerBuf#statusLogger}).
139 *
140 * The Diags mask and event level are useful for handling the event, but
141 * are generally not recorded by the logger because they are not needed in
142 * decoding and displaying the event. A more suitable value to record is a
143 * `{@link Types#Event}`, which encodes the event ID and module ID. For
144 * example, the `{@link Log#EventRec}` type stores a `{@link Types#Event}`
145 * in its record definition. A `{@link Types#Event}` can be created using
146 * the `{@link Types#makeEvent}` API given the event ID and module ID.
147 *
148 * The event ID value of `0` is used to indicate an event triggered by a
149 * call to one of the `{@link Log#print0 Log_print[0-6]}` methods. These
150 * methods take a format string rather than a `Log_Event` argument and,
151 * as a result, the event ID encoded in `evt` is `0` and the parameter
152 * `a1` is the format string.
153 *
154 * Non-zero event IDs can also be used to access the `msg` string
155 * associated with the `{@link Log#EventDesc}` that originally
156 * defined the `Log` event.
157 * @p(code)
158 * Log_EventId id = Log_getEventId(evt));
159 * if (id != 0) {
160 * String msg = Text_ropeText(id);
161 * System_aprintf(msg, a1, a2, a3, a4);
162 * }
163 * @p
164 * This works because an event's ID is simply an offset into a table
165 * of characters (maintained by the `{@link Text}` module)
166 * containing the event's msg string.
167 *
168 * The arguments a1, a2, etc. are parameters that are to be interpreted
169 * according to the message format string associated with `evt`.
170 *
171 * @param(evt) event to be logged
172 * @param(mid) module ID of the module which logged the event
173 * @param(a1) arbitrary argument passed by caller
174 *
175 * @see Log#Event
176 * @see Log#EventDesc
177 * @see Text#ropeText
178 * @see Log#getEventId
179 */
180 Void write4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
181 IArg a3, IArg a4);
182
183 /*!
184 * ======== write8 ========
185 * Process a log event with up to 8 arguments.
186 *
187 * Same as `write4` except with 8 arguments rather than 4.
188 *
189 * @see ILogger#write4()
190 */
191 Void write8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
192 IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
193 }
194 195 196
197