1 /*
2 * Copyright (c) 2012, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * */
32
33 /*
34 * ======== Rta.xdc ========
35 * UIA RealTime Analysis module
36 *
37 * Responsible for collecting Log events and sending them to
38 * an instrumentation host. Rta only services loggers that inherit from
39 * the {@link ti.uia.runtime.IUIATransfer} interface (e.g.
40 * {@link ti.uia.runtime.LoggerCircBuf}.
41 *
42 * Rta sends records to the host from one logger instance at a
43 * time--it will finish one logger before moving on to the next one.
44 *
45 * The Rta service runs in the framework of the UIA ServiceMgr framework.
46 * Configuration of the how the logs are actually moved off the target
47 * is managed by the {@link ti.uia.runtime.ServiceMgr} modules.
48 *
49 * Before sending the records to the host, the agent will copy them into
50 * a transfer buffer. The size of this transfer buffer is configurable using
51 * the {@link ti.uia.runtime.ServiceMgr} module.
52 *
53 * Because the application may generate logs faster than the agent can send
54 * them to the host, there is a limit to how many records the agent will send
55 * from one logger before moving on to the next one. The limit is
56 * approximately the size of the logger instance.
57 *
58 * The rate at which the logs are sent up depends on two configuration
59 * parameters, {@link #period} and
60 * {@link ti.uia.runtime.ServiceMgr#transferAgentPriority}.
61 * The period does not guarantee that the collection will run
62 * at this rate. Even if the period has expired, the collection
63 * will not occur until the current running Task has yielded and there
64 * are no other higher priority Tasks ready.
65 *
66 * The Rta module also responds to commands from the host to configure logging
67 * dynamically on the target, such as changing modules' diagnostic masks and
68 * enabling or disabling loggers.
69 *
70 * To enable Rta, simply do an xdc.useModule in your configuration file.
71 * @p(code)
72 * var Rta = xdc.useModule('ti.uia.services.Rta');
73 * @p
74 * The ServiceMgr is brought in automatically be this statement. If the
75 * configuration of the ServiceMgr needs to be changed, the application must
76 * do an xdc.useModule on ti.uia.runtime.ServiceMgr and configured it as
77 * needed.
78 */
79
80 import xdc.runtime.Diags;
81 import xdc.runtime.Log;
82 import ti.uia.runtime.ServiceMgr;
83 import ti.uia.runtime.UIAPacket;
84 import ti.uia.runtime.IUIATransfer;
85 import xdc.rov.ViewInfo;
86
87 module Rta
88 {
89 /*!
90 * @_nodoc
91 * ======== ModuleView ========
92 */
93 metaonly struct ModuleView {
94 Int serviceId;
95 Bool enabled;
96 Bool snapshotMode;
97 Int period;
98 UInt numLoggers;
99 String loggers[];
100 Bits16 sequence;
101 UInt totalPacketsSent;
102 }
103
104 /*!
105 * @_nodoc
106 * ======== rovViewInfo ========
107 */
108 @Facet
109 metaonly config ViewInfo.Instance rovViewInfo =
110 ViewInfo.create({
111 viewMap: [['Module', {type: ViewInfo.MODULE,
112 viewInitFxn: 'viewInitModule',
113 structName: 'ModuleView'}
114 ]]
115 });
116
117 /*! Logged on every packet is sent call from the Rta */
118 config Log.Event LD_recordsSent = {
119 mask: Diags.USER2,
120 msg: "LD_recordsSent: Sent %d bytes from logger [%d] 0x%x"
121 };
122
123 /*! Logged when the Rta receives a command */
124 config Log.Event LD_cmdRcvd = {
125 mask: Diags.USER2,
126 msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
127 };
128
129 /*! Logged when a diags mask is changed */
130 config Log.Event LD_writeMask = {
131 mask: Diags.USER2,
132 msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
133 };
134
135 /*!
136 * ======== periodInMs ========
137 * Period in miliseconds of the RTA Transfer Agent
138 *
139 * Configures how often the RTA should collect events. The minimum
140 * value is 100ms.
141 *
142 * This value does not guarantee that the collection will run
143 * at this rate. Even if the period has expired, the collection
144 * will not occur until the current running Task has yielded and there
145 * are no other higher priority Tasks ready.
146 *
147 * Setting the period to 0, disables all collection of events. There
148 * must be a setPeriod message sent from an instrumentation host to
149 * Rta to enable it.
150 *
151 * Default is 100 milliseconds.
152 */
153 config Int periodInMs = 100;
154
155 /*! @_nodoc
156 * ======== processCallback ========
157 * Function registered with the ServiceMgr module
158 */
159 Void processCallback(ServiceMgr.Reason reason, UIAPacket.Hdr *cmd);
160
161 /*! @_nodoc
162 * ======== registerLoggers ========
163 * Register all loggers instances with the Agent so that it can service
164 * them on the target.
165 */
166 metaonly function registerLoggers(modObj);
167
168 /*!
169 * ======== disableAllLogs ========
170 * Function to disable all the logs being processed by Rta
171 *
172 * Runtime function to disable all the logs that are being
173 * processed/read by Rta. When disabled, all new Log records
174 * are discarded.
175 *
176 * Please realize that external instrumentation host (e.g.
177 * System Analyzer) might be sending down similar requests.
178 */
179 Void disableAllLogs();
180
181 /*!
182 * ======== enableAllLogs ========
183 * Function to enable all the logs being processed by Rta
184 *
185 * Runtime function to enable disable all the logs that are being
186 * processed/read by Rta.
187 *
188 * Please realize that external instrumentation host (e.g.
189 * System Analyzer) might be sending down similar requests
190 */
191 Void enableAllLogs();
192
193 /*!
194 * ======== snapshotAllLogs ========
195 * Function to delay processing of the Rta service
196 *
197 * This function informs Rta to delay for the specified waitPeriod (in ms).
198 * After the waitPeriod has expired, Rta will process all the loggers
199 * that it manages. The state of Rta (e.g. started or stopped) will
200 * be maintained after the waitPeriod is expired and all the logs
201 * processed.
202 *
203 * The reset flag determines whether to reset all the loggers at the
204 * start of the waitPeriod (true -> reset). The state of the loggers
205 * (e.g. enabled or disabled) is not changed by this flag.
206 *
207 * @param(reset) Flag to denote whether to reset the loggers or not.
208 * TRUE means reset all the loggers processed by Rta.
209 * FALSE means do not reset any of the loggers processed
210 * by Rta.
211 *
212 * @param(waitPeriod) Duration in milliseconds to wait to run the Rta
213 * service.
214 */
215 Void snapshotAllLogs(UArg reset, UArg waitPeriod);
216
217 /*!
218 * ======== resetAllLogs ========
219 * Function to resets enable all the logs being processed by Rta
220 *
221 * Runtime function to enable resets all the logs that are being
222 * processed/read by Rta. All records in the logs are discarded.
223 * The state of the logger (e.g. enabled or disabled) is not changed.
224 *
225 * Please realize that external instrumentation host (e.g.
226 * System Analyzer) might be sending down similar requests
227 */
228 Void resetAllLogs();
229
230 /*!
231 * ======== startDataTx ========
232 * Function to start the Rta service
233 *
234 * This function allows the Rta service to be turned on.
235 *
236 * Please realize that external instrumentation host (e.g.
237 * System Analyzer) might be sending down similar requests
238 */
239 Void startDataTx();
240
241 /*!
242 * ======== stopDataTx ========
243 * Function to stop the Rta service
244 *
245 * This function allows the Rta service to be turned off.
246 *
247 * Please realize that external instrumentation host (e.g.
248 * System Analyzer) might be sending down similar requests
249 */
250 Void stopDataTx();
251
252 internal:
253
254 /*
255 * ======== SERVICEID ========
256 * Method to obtain serviceId
257 */
258 readonly config ServiceMgr.ServiceId SERVICEID;
259
260
261 /*
262 * ======== sendEvents ========
263 * Send out events
264 */
265 Void sendEvents();
266
267 /*
268 * ======== processMsg ========
269 * Process an incoming message
270 */
271 Void processMsg(UIAPacket.Hdr *cmd);
272
273 /*
274 * ======== flushLogger ========
275 * Flushes a logger.
276 * @param(logger) the handle of the logger to flush
277 * @param(loggerNum) the logger's InstanceId
278 */
279 Void flushLogger(IUIATransfer.Handle logger, UInt loggerNum);
280
281 /* Control APIs */
282 Void acknowledgeCmd(Packet *resp);
283 UIAPacket.MsgType readMask(Packet *resp, UArg addr);
284 UIAPacket.MsgType writeMask(Packet *resp, UArg addr, UArg val);
285 Void enableLog(UArg log);
286 Void disableLog(UArg log);
287 Void getCpuSpeed(Packet *resp);
288 Void resetLog(UArg log);
289 Void changePeriod(UArg period);
290
291 /* Command ids */
292 enum Command {
293 Command_READ_MASK = 0,
294 Command_WRITE_MASK = 1,
295 Command_LOGGER_OFF = 2,
296 Command_LOGGER_ON = 3,
297 Command_GET_CPU_SPEED = 4,
298 Command_RESET_LOGGER = 5,
299 Command_CHANGE_PERIOD = 6,
300 Command_START_TX = 7,
301 Command_STOP_TX = 8,
302 Command_LOGGER_OFF_ALL = 9,
303 Command_LOGGER_ON_ALL = 10,
304 Command_RESET_LOGGER_ALL = 11,
305 Command_SNAPSHOT_ALL = 12
306 };
307
308 enum ErrorCode {
309 ErrorCode_NULLPOINTER = 0
310 };
311
312 /* Structure of response packet sent back to host */
313 struct Packet {
314 UIAPacket.Hdr hdr;
315 Bits32 arg0;
316 Bits32 arg1;
317 }
318
319 struct Module_State {
320 IUIATransfer.Handle loggers[];
321 UInt numLoggers;
322 UInt totalPacketsSent;
323 Int period;
324 Bits16 seq;
325 Bool txData;
326 Bool snapshot;
327 };
328 }