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 Channel Context Instrumentation
43 *
44 * The UIAChanCtx module defines context change events
45 * and methods that allow tooling to identify channel context
46 * switches and to enable channel-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 UIAChanCtx events is also controlled by a module's diagnostics
57 * mask, which is described in details in `{@link xdc.runtime.Diags}`.
58 * UIAChanCtx` 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 @CustomHeader
112 module UIAChanCtx inherits IUIACtx {
113
114 /*!
115 * @_nodoc
116 * ======== ModuleView ========
117 */
118 metaonly struct ModuleView {
119 UInt mLastValue;
120 UInt mEnableOnValue;
121 }
122
123 /*!
124 * @_nodoc
125 * ======== rovViewInfo ========
126 */
127 @Facet
128 metaonly config ViewInfo.Instance rovViewInfo =
129 ViewInfo.create({
130 viewMap: [['Module', {type: ViewInfo.MODULE,
131 viewInitFxn: 'viewInitModule',
132 structName: 'ModuleView'}
133 ]]
134 });
135
136 /*!
137 * ======== ctxChg ========
138 * Channel Context Change event
139 *
140 * Used to log the start of a new channel
141 * Note that the previous channel Id is logged automatically by the ti_uia_runtime_LogCtxChg_thread
142 * API.
143 *
144 * @a(Example)
145 * The following C code shows how to log a Context Change
146 * event that identifies a new channel ID
147 *
148 * @p(code)
149 * #include <ti/uia/runtime/LogCtxChg.h>
150 * ...
151 * Void processChannel(Int chanId){
152 * ...
153 * LogCtxChg_channel("New chan ID=0x%x",chanId);
154 * ...
155 * }
156 * @p
157 * This event prints the Log call site (%$F) and a format string (%$S)
158 * which is recursively formatted with any addition arguments.
159 * The following text is an example of what will be displayed for the event:
160 * @p(code)
161 * "Channel Ctx Change at Line 123 in demo.c [Prev. chan ID=0x1234] New chan ID=0x1235"
162 *
163 * @param(fmt) a constant string that describes the context change and provides a format specifier for newAppId
164 * @param(newChanId) an integer which uniquely identifies the new context
165 */
166 config xdc.runtime.Log.Event ctxChg = {
167 mask: Diags.ANALYSIS,
168 msg: "Channel Ctx Change at %$F [Prev. chan ID=0x%x] %$S"};
169
170 /*!
171 * ======== metaEventChanCtxChg ========
172 * Metadata description of the Channel Context Change event
173 *
174 * @_nodoc
175 */
176 metaonly config DvtTypes.MetaEventDescriptor metaEventChanCtxChg = {
177 versionId: "2.0",
178 analysisType: DvtTypes.DvtAnalysisType_CONTEXTCHANGE,
179 displayText: "Channel Ctx Change",
180 tooltipText: "Channel ID Context Change",
181 numParameters: 5,
182 paramInfo: [
183 { name: '__FILE__',
184 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
185 dataTypeName: 'String',
186 units: 'none',
187 isHidden: false
188 },
189 { name: '__LINE__',
190 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
191 dataTypeName: 'Int',
192 units: 'none',
193 isHidden: false
194 },
195 { name: 'Prev. Chan ID',
196 dataDesc: DvtTypes.DvtDataDesc_CHANNELID,
197 dataTypeName: 'Int',
198 units: 'none',
199 isHidden: false
200 },
201 { name: 'fmt',
202 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
203 dataTypeName: 'String',
204 units: 'none',
205 isHidden: false
206 },
207 { name: 'New Chan ID',
208 dataDesc: DvtTypes.DvtDataDesc_CHANNELID,
209 dataTypeName: 'Int',
210 units: 'none',
211 isHidden: false
212 }]
213
214 };
215 /*!
216 * ======== getCtxId ========
217 * Get the ID for the current channel
218 *
219 * @a(returns)
220 * returns the channel ID logged by the last call to UIAChanCtx_logCtxChg.
221 */
222 @DirectCall
223 UInt getCtxId();
224
225 /*!
226 * ======== getEnableOnValue ========
227 * Get the EnableOn value
228 *
229 * @a(returns) returns the channel ID value that logging will be enabled for.
230 */
231 @DirectCall
232 UInt getEnableOnValue();
233
234 /*!
235 * ======== setEnableOnValue ========
236 * Set the EnableOn value
237 *
238 * @param(value) the CtxId value that logging will be enabled for.
239 */
240 @DirectCall
241 Void setEnableOnValue(UInt value);
242
243 /*!
244 * ======== isLoggingEnabled ========
245 * returns true if the new context matches the value to enable logging with.
246 *
247 * Default implementation of the IUIACtx_IsLoggingEnabledFxn for user context.
248 * To enable context-aware filtering, in the .cfg script assign
249 * UIAChanCtx_isLoggingEnabledFxn = '&UIAChanCtx_isLoggingEnabled'
250 * or assign your own implementation of this function.
251 *
252 * @param(newChanId) the new channel ID
253 * @a(returns) true if logging is enabled
254 */
255 @DirectCall
256 Bool isLoggingEnabled(UInt newChanId);
257
258 /*!
259 * ======== setOldValue =========
260 * sets ti_uia_events_UIAChanCtx_gLastValue to the new value and returns the old value before it was updated.
261 *
262 * @param(newValue) the new value to save in the global variable
263 * @a(return0 the original value of the global variable before it was updated.
264 */
265 @DirectCall
266 UInt setOldValue(UInt newValue);
267
268 internal:
269
270 struct Module_State {
271 UInt mLastValue;
272 UInt mEnableOnValue;
273 };
274 }