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 import ti.uia.runtime.IUIATraceSyncProvider;
34
35 36 37 38 39 40 41 42 43 44 45 46
47 interface IUIATraceSyncClient inherits ti.uia.events.IUIAMetaProvider {
48
49 /*!
50 * ======== injectIntoTraceFxn ========
51 * Callback function that handles injection of info such as serial numbers
52 * of sync point events, context change events or snapshot events into a
53 * hardware trace stream. (e.g. GEM CPU Trace, System Trace, etc.)
54 *
55 * Users can provide their own custom injectIntoTraceFxn to log whatever
56 * additional information they wish to record when the hook function is called.
57 * For example, event serial numbers can be injected into the CPU
58 * trace stream and / or STM trace stream in order to enable correlation
59 * of information logged in these streams with UIA software events.
60 * @a(Examples)
61 * @p(html)
62 * <B>Example 1: Correlating events with C64X+ and C66 CPU Trace</B>
63 * @p
64 * The following is an example of the configuration script used
65 * to inject serial numbers of sync point events or context change events or
66 * snapshot Ids associated with snapshot events.
67 * @p
68 * Note that the GemTraceSync module's .xs script takes care of finding
69 * all modules that implement the IUIATraceSyncClient and assigning the
70 * GemTraceSync_injectIntoTrace function pointer to those modules'
71 * injectIntoTraceFxn config option.
72 * @p(code)
73 * //The following 3 modules all implement the IUIATraceSyncClient interface
74 * var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
75 * var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
76 * var LogSync = xdc.useModule('ti.uia.runtime.LogSync');
77 * //For C66 devices, replace the following line with
78 * // var GemTraceSync = xdc.useModule('ti.uia.family.c66.GemTraceSync');
79 * var GemTraceSync = xdc.useModule('ti.uia.family.c64p.GemTraceSync');
80 * @p
81 * @p(html)
82 * <hr>
83 * <B>Example 2: How to create a custom hook function
84 * and assign it to the LogSnapshot module</B>
85 * @p
86 * The following is an example of a 'C' code program that implements
87 * a hook function that prints out the snapshot ID that is passed in
88 * as the serialNumber
89 * @p(code)
90 * #include <xdc/std.h>
91 * #include <xdc/runtime/Gate.h>
92 * #include <ti/uia/runtime/IUIATraceSyncProvider.h>
93 * #include <ti/uia/runtime/LogSnapshot.h>
94 * #include <stdio.h>
95 * #include <string.h>
96 * extern Void myHookFxn(UInt32 serialNumber, IUIATraceSyncProvider_ContextType ctxType);
97 * Void Test();
98 * char name[32]={"Bob"};
99 * UInt32 newAppId = 0;
100 * Void myHookFxn(UInt32 serialNumber, IUIATraceSyncProvider_ContextType ctxType){
101 * volatile UInt32 syncWord;
102 * IArg key = Gate_enterSystem();
103 * printf("newAppId written with serialNumber %d and ctxType = %d\n",serialNumber,ctxType);
104 * Gate_leaveSystem(key);
105 * }
106 * Void Test(){
107 * // note that the hook function is triggered by calling LogSnapshot_getSnapshotId()
108 * // since that is where the unique snapshot ID that is passed to the
109 * // hook function is generated.
110 * Int snapshotId = LogSnapshot_getSnapshotId();
111 * LogSnapshot_writeString(snapshotId,"User-defined name=%s.",name, strlen(name));
112 * }
113 *
114 * Void main(){
115 * while(TRUE){ Test(); }
116 * }
117 * @p
118 * In order to have the above user-defined function called by the LogSnapshot
119 * module whenever it writes an event, the following configuration script
120 * is needed:
121 * @p(code)
122 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
123 * var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
124 * var IUIATraceSyncClient = xdc.useModule('ti.uia.runtime.IUIATraceSyncClient');
125 * LogSnapshot.injectIntoTraceFxn = $externFxn('myHookFxn');
126 *
127 * @p
128 * @see LoggerTypes#InjectIntoTraceFxn
129 * @see LogSnapshot
130 */
131 config LoggerTypes.InjectIntoTraceFxn injectIntoTraceFxn = null;
132 /*!
133 * ======== isInjectIntoTraceEnabled ========
134 * set false to turn off injection of sync point info into trace even
135 * if a module that implements IUIATraceSyncProvider is configured.
136 *
137 * The XDCScript associated with a module that implements IUIATraceSyncProvider
138 * is responsible for checking this config option for all IUIATraceSyncClient
139 * modules before automatically configuring the client callback function.
140 * This allows users to control which features have sync points injected
141 * into the trace stream. For example, a user may wish to configure
142 * LogSync.isInjectIntoTraceEnabled = true and
143 * LogCtxChg.isInjectIntoTraceEnabled = false in order to reduce the number
144 * of sync point events injected into the trace stream.
145 */
146 metaonly config Bool isInjectIntoTraceEnabled = true;
147
148 }