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 /*!
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 * @(#) xdc.runtime; 2, 0, 0, 0,240; 6-21-2010 15:09:08; /db/ztree/library/trees/xdc/xdc-u19x/src/packages/
118 */
119