1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32
33 34 35
36 import xdc.runtime.Types;
37 import xdc.runtime.Diags;
38 import ti.uia.events.IUIACtx;
39
40 /*!
41 * UIA Application Context Instrumentation
42 *
43 * The UIAAppCtx module defines context change events
44 * and methods that allow tooling to identify application context
45 * switches and to enable application-aware filtering, trace and
46 * analysis.
47 *
48 * It inherits IUIACtx, which defines a function pointer to
49 * an isLoggingEnabled function which, if configured to point to
50 * a function, will evaluate the function prior to logging the context
51 * change event and will determine whether to log the event based on the
52 * return value of the function. If the function is not configured,
53 * logging will be conditional upon ti_uia_runtime_CtxFilter_gIsLoggingEnabled.
54 *
55 * The generation of UIAAppCtx events is also controlled by a module's diagnostics
56 * mask, which is described in details in `{@link xdc.runtime.Diags}`.
57 * `UIAAppCtx` events are generated only when the Diags.ANALYSIS bit is set
58 * in the module's diagnostics mask.
59 *
60 * The following configuration script demonstrates how the application might
61 * control the logging of ANALYSIS events embedded in the `Mod` module at configuration
62 * time. In this case, the configuration script arranges for the `Log`
63 * statements within modules to always generate ANALYSIS events.
64 * Without these configuration statements, no ANALYSIS events would be generated
65 * by any modules.
66 *
67 * @a(Examples)
68 * Example 1: This is part of the XDC configuration file for the application:
69 *
70 * @p(code)
71 * var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
72 * var Diags = xdc.useModule('xdc.runtime.Diags');
73 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
74 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
75 * var logger = LoggerSys.create();
76 *
77 * Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
78 * Defaults.common$.logger = logger;
79 * @p
80 *
81 * @p(html)
82 * <hr />
83 * @p
84 *
85 * Example 2: The following example configures a module to support logging
86 * of ANALYSIS events, but defers the actual activation and deactivation of the
87 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
88 * function for details on specifying the control string.
89 *
90 * This is a part of the XDC configuration file for the application:
91 *
92 * @p(code)
93 * var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
94 * var Diags = xdc.useModule('xdc.runtime.Diags');
95 * var Mod = xdc.useModule('my.pkg.Mod');
96 *
97 * Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
98 * @p
99 *
100 * This is a part of the C code for the application:
101 *
102 * @p(code)
103 * // turn on logging of ANALYSIS events in the module
104 * Diags_setMask("my.pkg.Mod+Z");
105 *
106 * // turn off logging of ANALYSIS events in the module
107 * Diags_setMask("my.pkg.Mod-Z");
108 * @p
109 */
110 @CustomHeader
111 module UIAAppCtx inherits IUIACtx {
112
113 /*!
114 * ======== ctxChg ========
115 * Application ID Context Change event
116 *
117 * Used to log switching to a new application.
118 * Note that this event should not be referenced directly by user code - it is used
119 * internally by the LogCtxChg_app function, which logs the previous app Id automatically.
120 *
121 * @a(Example)
122 * The following C code shows how to log a Context Change
123 * event that identifies a newly loaded application ID
124 *
125 * @p(code)
126 * #include <ti/uia/runtime/LogCtxChg.h>
127 * ...
128 * Void loadApplication(Int newAppId){
129 * ...
130 * LogCtxChg_app("New AppID=0x%x",newAppId);
131 * ...
132 * }
133 * @p
134 * This event prints the Log call site (%$F) and a format string (%$S)
135 * which is recursively formatted with any addition arguments.
136 * The following text is an example of what will be displayed for the event:
137 * @p(code)
138 * "AppID Ctx Change at Line 123 in appLoader.c [Prev. AppID = 0x1234] New AppID=0x1235"
139 *
140 * @param(fmt) a constant string that describes the context change and provides a format specifier for newAppId
141 * @param(newAppId) an integer which uniquely identifies the new application context
142 */
143 config xdc.runtime.Log.Event ctxChg = {
144 mask: Diags.ANALYSIS,
145 msg: "AppID Ctx Change at %$F [Prev. AppID=0x%x] %$S"};
146
147 /*!
148 * ======== metaEventAppCtxChg ========
149 * Metadata description of the Application Context Change event
150 *
151 * @_nodoc
152 */
153 metaonly config DvtTypes.MetaEventDescriptor metaEventAppCtxChg = {
154 versionId: "2.0",
155 analysisType: DvtTypes.DvtAnalysisType_CONTEXTCHANGE,
156 displayText: "AppID Ctx Change",
157 tooltipText: "Application ID Context Change",
158 numParameters: 5,
159 paramInfo: [
160 { name: '__FILE__',
161 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
162 dataTypeName: 'String',
163 units: 'none',
164 isHidden: false
165 },
166 { name: '__LINE__',
167 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
168 dataTypeName: 'Int',
169 units: 'none',
170 isHidden: false
171 },
172 { name: 'Prev. App ID',
173 dataDesc: DvtTypes.DvtDataDesc_APPID,
174 dataTypeName: 'Int',
175 units: 'none',
176 isHidden: false
177 },
178 { name: 'fmt',
179 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
180 dataTypeName: 'String',
181 units: 'none',
182 isHidden: false
183 },
184 { name: 'New App ID',
185 dataDesc: DvtTypes.DvtDataDesc_APPID,
186 dataTypeName: 'Int',
187 units: 'none',
188 isHidden: false
189 }]
190
191 };
192
193 /*!
194 * ======== getCtxId ========
195 * Get the ID for the current channel
196 *
197 * @a(returns)
198 * returns the thread ID logged by the last call to UIAAppCtx_logCtxChg.
199 */
200 @Macro Int getCtxId();
201
202 /*!
203 * ======== isLoggingEnabled ========
204 * returns true if the new context matches the value to enable logging with.
205 *
206 * Default implementation of the IUIACtx_IsLoggingEnabledFxn for user context.
207 * To enable context-aware filtering, assign UIAAppCtx_isLoggingEnabledFxn = &UIAAppCtx_isLoggingEnabled
208 * in the config script or programmatically, or assign your own implementation of this
209 * function.
210 * @param(newChanId) the new channel ID
211 * @a(returns) true if logging is enabled
212 */
213 @DirectCall
214 Bool isLoggingEnabled(UInt newAppId);
215
216 /*!
217 * ======== setOldValue =========
218 * sets the ti_uia_events_UIAAppCtx_gLastValue to the new value and returns the old value before it was updated.
219 *
220 * @param(newValue) the new value to save in the global variable
221 * @a(return0 the original value of the global variable before it was updated.
222 */
223 @DirectCall
224 UInt setOldValue(UInt newValue);
225 }