1 /*
2 * Copyright (c) 2008 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * */
12 /*!
13 * ======== Trace ========
14 * Trace support
15 *
16 * This module allows system integrators to selectively enable trace
17 * statements, from within XDCscripts. Trace statements can be selected
18 * based on the file (capsule) and the package in which they are located.
19 * For example, trace statements from file `Mod.xs` in package `myPkgs.pkgA'
20 * can be enabled either with `Trace.capsuleEnable(["myPkgs/pkgA/Mod"])` or
21 * with `Trace.packageEnable(["myPkgs.pkgA"])`.
22 *
23 * Trace statements can also belong to groups, strings defined by package
24 * producers when they need to group related trace statements, distributed
25 * across different modules and packages, into trace units that can be
26 * disabled or enabled as a whole. If some of the trace statements from file
27 * `Mod.xs` are tagged to belong to a group "init", the following will
28 * activate them:
29 * @p(code) 30 * Trace.groupEnable(["init"]);
31 * @p 32 *
33 * Each trace statement by default belongs to the group "all". To activate
34 * all trace statements:
35 * @p(code) 36 * Trace.setLevel(2);
37 * Trace.groupEnable(["all"]);
38 * @p 39 *
40 */
41 metaonlymodule Trace {
42
43 typedef String StringArray[];
44
45 /*!
46 * ======== level ========
47 * @_nodoc 48 * Select the amount of printed messages
49 */
50 config Int level = 0;
51
52 /*!
53 * ======== capsules ========
54 * @_nodoc 55 * Array of regular expressions enabling trace in capsules
56 */
57 config StringArray capsules = [];
58
59 /*!
60 * ======== packages ========
61 * @_nodoc 62 * Array of regular expressions enabling trace in packages
63 */
64 config StringArray packages = [];
65
66 /*!
67 * ======== groups ========
68 * @_nodoc 69 * Array of regular expressions enabling trace in groups
70 */
71 config StringArray groups = [];
72
73 /*!
74 * ======== packageLoad ========
75 * Enable trace of loaded packages
76 *
77 * This setting enables the messages related to loading packages.
78 * If `true`, whenever a package is loaded, the following info is
79 * displayed:
80 * @p(blist) 81 * - name of a package loading another package
82 * - name of the loaded package
83 * - repository from which the package is being loaded
84 * @p 85 */
86 config Bool packageLoad = false;
87
88 /*!
89 * ======== useModule ========
90 * Enable trace of used modules
91 *
92 * This setting enables the messages that inform when the function
93 * `xdc.useModule()` is invoked on a module, and when a module's
94 * `module$use` function is invoked.
95 */
96 config Bool useModule = false;
97
98 /*!
99 * ======== addSupergroup ========
100 * Add a group that contains other groups
101 *
102 * This function allows giving a name to an array of existing
103 * trace groups.
104 *
105 * @param(supergroup) name of the new group
106 * @param(subgroups) array of the existing trace groups
107 */
108 Void addSupergroup(String supergroup, StringArray subgroups);
109
110 /*!
111 * ======== capsuleEnable ========
112 * Enable trace output from selected capsules
113 *
114 * Capsules are either XDCscript files or Java source files. The
115 * function parameter is treated as an array of JavaScript
116 * regular expressions, therefore it can contain partial capsule
117 * names.
118 *
119 * If this function is invoked repeatedly, each new call replaces
120 * the array of currently enabled capsules with the array supplied
121 * as the parameter. The array of the currently enabled capsules is
122 * returned. If the function is invoked with a zero-length array, it
123 * returns the currently enabled capsules, but it also leaves them
124 * active. Therefore, the sequence of calls that would add new
125 * capsules instead of replacing the current ones is:
126 * @p(code) 127 * var current = Trace.capsuleEnable([]);
128 * current[current.length++] = "pkg/ModA.xs";
129 * current[current.length++] = "pkg/ModB.xs";
130 * Trace.capsuleEnable(current);
131 * @p 132 *
133 * To disable trace for all capsules, the function must be invoked
134 * with an empty string as the only element of the array.
135 * @p(code) 136 * Trace.capsuleEnable([""]);
137 * @p 138 *
139 * @param(capsules) array of capsule names
140 *
141 * @a(return) array of currently enabled capsule names
142 */
143 StringArray capsuleEnable(StringArray capsules);
144
145 /*!
146 * ======== groupEnable ========
147 * Enable trace output from selected groups
148 *
149 * A group is a string defined by package producers when they need to
150 * group related trace statements, distributed across different
151 * modules and packages, into trace units that can be disabled or
152 * enabled as a whole. The function parameter is treated as an array
153 * of JavaScript regular expressions, therefore it can contain partial
154 * group names.
155 *
156 * If this function is invoked repeatedly, each new call replaces
157 * the array of currently enabled groups with the array supplied
158 * as the parameter. The array of the currently enabled groups is
159 * returned. If the function is invoked with a zero-length array, it
160 * returns the currently enabled groups, but it also leaves them
161 * active. Therefore, the sequence of calls that would add new groups
162 * instead of replacing the current ones is:
163 * @p(code) 164 * var current = Trace.groupEnable([]);
165 * current[current.length++] = "libPkgs";
166 * Trace.groupEnable(current);
167 * @p 168 *
169 * To disable trace for all groups, the function must be invoked
170 * with an empty string as the only element of the array.
171 * @p(code) 172 * Trace.groupEnable([""]);
173 * @p 174 *
175 * @param(groups) array of groups
176 *
177 * @a(return) array of currently enabled groups
178 */
179 StringArray groupEnable(StringArray groups);
180
181 /*!
182 * ======== packageEnable ========
183 * Enable trace output from selected packages
184 *
185 * Packages that can be enabled through this function are RTSC
186 * packages and Java packages. The function parameter is treated as
187 * an array of JavaScript regular expressions, therefore it can
188 * contain partial package names.
189 *
190 * If this function is invoked repeatedly, each new call replaces
191 * the array of currently enabled packages with the array supplied
192 * as the parameter. The array of the currently enabled packages is
193 * returned. If the function is invoked with a zero-length array, it
194 * returns the currently enabled packages, but it also leaves them
195 * active. Therefore, the sequence of calls that would add new
196 * packages instead of replacing the current ones is:
197 * @p(code) 198 * var current = Trace.packageEnable([]);
199 * current[current.length++] = "ti.targets";
200 * Trace.packageEnable(current);
201 * @p 202 *
203 * To disable trace for all packages, the function must be invoked
204 * with an empty string as the only element of the array.
205 * @p(code) 206 * Trace.packageEnable([""]);
207 * @p 208 *
209 * @param(packages) array of package names
210 *
211 * @a(return) array of currently enabled package names
212 */
213 StringArray packageEnable(StringArray packages);
214
215 /*!
216 * ======== setLevel ========
217 * Set the verbosity level
218 *
219 * This function limits trace output to trace statement tagged with
220 * level equal or lower than this function's parameter. By default,
221 * the verbosity level is set to 0, which is the least verbose level.
222 * The most verbose level is 2.
223 */
224 Int setLevel(Int level);
225
226 /*!
227 * ======== start ========
228 * @_nodoc 229 * Activate trace
230 */
231 Void start();
232 }
233 /*
234 * @(#) xdc.services.global; 1, 0, 0,385; 9-20-2012 15:02:07; /db/ztree/library/trees/xdc/xdc-y36x/src/packages/
235 */
236