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 interface ILogger {
30
31 /*!
32 * ======== getMetaArgs ========
33 * Returns any meta data needed to support RTA.
34 *
35 * This meta data should be returned in the form of a structure which
36 * can be converted into XML. This data is added to the RTA XML file
37 * during the application's configuration, and can be accessed later
38 * through the xdc.rta.MetaData module.
39 *
40 * The MetaData is returned per instance of the ILogger module. The
41 * instance object is passed to the function as the first argument.
42 *
43 * The second argument is the index of the instance in the list of
44 * the ILogger's static instances.
45 */
46 function getMetaArgs(inst, instNum);
47
48 instance:
49
50 /*!
51 * ======== write4 ========
52 * Process a log event with up to 4 arguments.
53 *
54 * At the time this method is called, `evt` encodes two values: the
55 * module ID of the module that "triggered" a `{@link Log#Event}`
56 * and the `{@link Log#EventId}` of the event. The module ID can
57 * be obtained via `{@link Types#getModuleId}(evt)`
58 * and the event ID can be obtained via
59 * `{@link Types#getEventId}(evt)`.
60 *
61 * The event ID can be used to compare against other known
62 * `Log.Event`s.
63 * @p(code)
64 * if (Log_getEventId(MY_EVENT) == Types_getEventId(evt)) {
65 * :
66 * }
67 * @p
68 *
69 * The event ID value of `0` is used to indicate an event triggered
70 * by a call to one of the `{@link Log#print0 Log_print[0-6]}`
71 * methods. These methods take a
72 * format string rather than a `Log_Event` argument and, as a result,
73 * the event ID encoded in `evt` is `0` and the parameter `a1` is
74 * the format string.
75 *
76 * Non-zero event IDs can also be used to access the `msg` string
77 * associated with the `{@link Log#EventDesc}` that originally
78 * defined the `Log` event.
79 * @p(code)
80 * Types_EventId id = Types_getEventId(evt));
81 * if (id != 0) {
82 * String msg = Text_ropeText(id);
83 * System_aprintf(msg, a1, a2, a3, a4);
84 * }
85 * @p
86 * This works because an event's ID is simply an offset into a table
87 * of characters (maintained by the `{@link Text}` module)
88 * containing the event's msg string.
89 *
90 * @param(evt) event to be logged
91 *
92 * @param(a1) arbitrary argument passed by caller
93 *
94 * This parameter, along with `a2`, `a3`, and `a4` are parameters
95 * that are to be interpreted according to the message format string
96 * associated with `evt`.
97 *
98 * @see Log#Event
99 * @see Log#EventDesc
100 * @see Text#ropeText
101 * @see Types#getEventId
102 */
103 Void write4(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
104
105 /*!
106 * ======== write8 ========
107 * Process a log event with up to 8 arguments.
108 *
109 * Same as `write4` except with 8 arguments rather than 4.
110 *
111 * @see ILogger#write4()
112 */
113 Void write8(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
114 IArg a5, IArg a6, IArg a7, IArg a8);
115 }
116 117 118
119