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