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 import xdc.rov.ViewInfo;
40
41 /*!
42 * UIA Frame Context Instrumentation
43 *
44 * The UIAFrameCtx module defines context change events
45 * and methods that allow tooling to identify frame context
46 * switches and to enable frame-aware filtering, trace and
47 * analysis.
48 *
49 * It inherits IUIACtx, which defines a function pointer to
50 * an isLoggingEnabled function which, if configured to point to
51 * a function, will evaluate the function prior to logging the context
52 * change event and will determine whether to log the event based on the
53 * return value of the function. If the function is not configured,
54 * logging will be conditional upon ti_uia_runtime_CtxFilter_module->mIsLoggingEnabled.
55 *
56 * The generation of UIAFrameCtx events is also controlled by a module's diagnostics
57 * mask, which is described in details in `{@link xdc.runtime.Diags}`.
58 * UIAFrameCtx` events are generated only when the Diags.ANALYSIS bit is set
59 * in the module's diagnostics mask.
60 *
61 * The following configuration script demonstrates how the application might
62 * control the logging of ANALYSIS events embedded in the `Mod` module at configuration
63 * time. In this case, the configuration script arranges for the `Log`
64 * statements within modules to always generate ANALYSIS events.
65 * Without these configuration statements, no ANALYSIS events would be generated
66 * by any modules.
67 *
68 * @a(Examples)
69 * Example 1: This is part of the XDC configuration file for the application:
70 *
71 * @p(code)
72 * var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
73 * var Diags = xdc.useModule('xdc.runtime.Diags');
74 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
75 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
76 * var logger = LoggerSys.create();
77 *
78 * Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
79 * Defaults.common$.logger = logger;
80 * @p
81 *
82 * @p(html)
83 * <hr />
84 * @p
85 *
86 * Example 2: The following example configures a module to support logging
87 * of ANALYSIS events, but defers the actual activation and deactivation of the
88 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
89 * function for details on specifying the control string.
90 *
91 * This is a part of the XDC configuration file for the application:
92 *
93 * @p(code)
94 * var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
95 * var Diags = xdc.useModule('xdc.runtime.Diags');
96 * var Mod = xdc.useModule('my.pkg.Mod');
97 *
98 * Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
99 * @p
100 *
101 * This is a part of the C code for the application:
102 *
103 * @p(code)
104 * // turn on logging of ANALYSIS events in the module
105 * Diags_setMask("my.pkg.Mod+Z");
106 *
107 * // turn off logging of ANALYSIS events in the module
108 * Diags_setMask("my.pkg.Mod-Z");
109 * @p
110 */
111
112 @CustomHeader
113 module UIAFrameCtx inherits IUIACtx {
114
115 /*!
116 * @_nodoc
117 * ======== ModuleView ========
118 */
119 metaonly struct ModuleView {
120 UInt mLastValue;
121 UInt mEnableOnValue;
122 }
123
124 /*!
125 * @_nodoc
126 * ======== rovViewInfo ========
127 */
128 @Facet
129 metaonly config ViewInfo.Instance rovViewInfo =
130 ViewInfo.create({
131 viewMap: [['Module', {type: ViewInfo.MODULE,
132 viewInitFxn: 'viewInitModule',
133 structName: 'ModuleView'}
134 ]]
135 });
136
137 /*!
138 * ======== ctxChg ========
139 * Frame Context Change event
140 *
141 * Used to log the start of a new frame
142 * If ti_uia_events_UIAFrameCtx_isLoggingEnabledFxn is not NULL
143 * it is called and its return value determines whether logging is enabled or not.
144 *
145 * @a(Example)
146 * The following C code shows how to log a Context Change
147 * event that identifies a new Frame ID
148 *
149 * @p(code)
150 * #include <ti/uia/runtime/LogCtxChg.h>
151 * ...
152 * Void processFrame(Int frameId){
153 * ...
154 * LogCtxChg_frame("New Frame ID=0x%x",frameId);
155 * ...
156 * }
157 * @p
158 * This event prints the Log call site (%$F) and a format string (%$S)
159 * which is recursively formatted with any addition arguments.
160 * The following text is an example of what will be displayed for the event:
161 * @p(code)
162 * "Frame Ctx Change at Line 123 in demo.c [Prev. Frame ID=0x1234] New Frame ID=0x1235"
163 *
164 * @param(fmt) a constant string that describes the context change and provides a format specifier for newFrameId
165 * @param(newFrameId) an integer which uniquely identifies the new context
166 */
167 config xdc.runtime.Log.Event ctxChg = {
168 mask: Diags.ANALYSIS,
169 msg: "Frame Ctx Change at %$F [prev. Frame ID=0x%x] %$S"};
170
171 /*!
172 * ======== metaEventFrameCtxChg ========
173 * Metadata description of the Frame Context Change event
174 *
175 * @_nodoc
176 */
177 metaonly config DvtTypes.MetaEventDescriptor metaEventFrameCtxChg = {
178 versionId: "2.0",
179 analysisType: DvtTypes.DvtAnalysisType_CONTEXTCHANGE,
180 displayText: "Frame Ctx Change",
181 tooltipText: "Frame ID Context Change",
182 numParameters: 5,
183 paramInfo: [
184 { name: '__FILE__',
185 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
186 dataTypeName: 'String',
187 units: 'none',
188 isHidden: false
189 },
190 { name: '__LINE__',
191 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
192 dataTypeName: 'Int',
193 units: 'none',
194 isHidden: false
195 },
196 { name: 'Prev. Frame ID',
197 dataDesc: DvtTypes.DvtDataDesc_FRAMEID,
198 dataTypeName: 'Int',
199 units: 'none',
200 isHidden: false
201 },
202 { name: 'fmt',
203 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
204 dataTypeName: 'String',
205 units: 'none',
206 isHidden: false
207 },
208 { name: 'New Frame ID',
209 dataDesc: DvtTypes.DvtDataDesc_FRAMEID,
210 dataTypeName: 'Int',
211 units: 'none',
212 isHidden: false
213 }]
214
215 };
216 /*!
217 * ======== getCtxId ========
218 * Get the ID for the current frame
219 *
220 * @a(returns)
221 * returns the frame ID logged by the last call to UIAFrameCtx_logCtxChg.
222 */
223 @DirectCall
224 UInt getCtxId();
225
226 /*!
227 * ======== getEnableOnValue ========
228 * Get the EnableOn value
229 *
230 * @a(returns) returns the App ID value that logging will be enabled for.
231 */
232 @DirectCall
233 UInt getEnableOnValue();
234
235 /*!
236 * ======== setEnableOnValue ========
237 * Set the EnableOn value
238 *
239 * @param(value) the CtxId value that logging will be enabled for.
240 */
241 @DirectCall
242 Void setEnableOnValue(UInt value);
243
244 /*!
245 * ======== isLoggingEnabled ========
246 * returns true if the new context matches the value to enable logging with.
247 *
248 * Default implementation of the IUIACtx_IsLoggingEnabledFxn for user context.
249 * To enable context-aware filtering, in the .cfg script assign
250 * UIAFrameCtx_isLoggingEnabledFxn = '&UIAFrameCtx_isLoggingEnabled'
251 * or assign your own implementation of this function.
252 *
253 * @param(newFrameId) the new frame ID
254 * @a(returns) true if logging is enabled
255 */
256 @DirectCall
257 Bool isLoggingEnabled(UInt newFrameId);
258
259 /*!
260 * ======== setOldValue =========
261 * sets the ti_uia_events_UIAFrameCtx_gLastValue to the new value and returns the old value before it was updated.
262 *
263 * @param(newValue) the new value to save in the global variable
264 * @a(return0 the original value of the global variable before it was updated.
265 */
266 @DirectCall
267 UInt setOldValue(UInt newValue);
268
269 internal:
270
271 struct Module_State {
272 UInt mLastValue;
273 UInt mEnableOnValue;
274 };
275 }