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 *
107 * @param subgroups array of the existing trace groups
108 */
109 Void addSupergroup(String supergroup, StringArray subgroups);
110
111 /*!
112 * ======== capsuleEnable ========
113 * Enable trace output from selected capsules
114 *
115 * Capsules are either XDCscript files or Java source files. The
116 * function parameter is treated as an array of JavaScript
117 * regular expressions, therefore it can contain partial capsule
118 * names.
119 *
120 * If this function is invoked repeatedly, each new call replaces
121 * the array of currently enabled capsules with the array supplied
122 * as the parameter. The array of the currently enabled capsules is
123 * returned. If the function is invoked with a zero-length array, it
124 * returns the currently enabled capsules, but it also leaves them
125 * active. Therefore, the sequence of calls that would add new
126 * capsules instead of replacing the current ones is:
127 * @p(code) 128 * var current = Trace.capsuleEnable([]);
129 * current[current.length++] = "pkg/ModA.xs";
130 * current[current.length++] = "pkg/ModB.xs";
131 * Trace.capsuleEnable(current);
132 * @p 133 *
134 * To disable trace for all capsules, the function must be invoked
135 * with an empty string as the only element of the array.
136 * @p(code) 137 * Trace.capsuleEnable([""]);
138 * @p 139 *
140 * @params capsules array of capsule names
141 *
142 * @a(return) array of currently enabled capsule names
143 */
144 StringArray capsuleEnable(StringArray capsules);
145
146 /*!
147 * ======== groupEnable ========
148 * Enable trace output from selected groups
149 *
150 * A group is a string defined by package producers when they need to
151 * group related trace statements, distributed across different
152 * modules and packages, into trace units that can be disabled or
153 * enabled as a whole. The function parameter is treated as an array
154 * of JavaScript regular expressions, therefore it can contain partial
155 * group names.
156 *
157 * If this function is invoked repeatedly, each new call replaces
158 * the array of currently enabled groups with the array supplied
159 * as the parameter. The array of the currently enabled groups is
160 * returned. If the function is invoked with a zero-length array, it
161 * returns the currently enabled groups, but it also leaves them
162 * active. Therefore, the sequence of calls that would add new groups
163 * instead of replacing the current ones is:
164 * @p(code) 165 * var current = Trace.groupEnable([]);
166 * current[current.length++] = "libPkgs";
167 * Trace.groupEnable(current);
168 * @p 169 *
170 * To disable trace for all groups, the function must be invoked
171 * with an empty string as the only element of the array.
172 * @p(code) 173 * Trace.groupEnable([""]);
174 * @p 175 *
176 * @params groups array of groups
177 *
178 * @a(return) array of currently enabled groups
179 */
180 StringArray groupEnable(StringArray groups);
181
182 /*!
183 * ======== packageEnable ========
184 * Enable trace output from selected packages
185 *
186 * Packages that can be enabled through this function are RTSC
187 * packages and Java packages. The function parameter is treated as
188 * an array of JavaScript regular expressions, therefore it can
189 * contain partial package names.
190 *
191 * If this function is invoked repeatedly, each new call replaces
192 * the array of currently enabled packages with the array supplied
193 * as the parameter. The array of the currently enabled packages is
194 * returned. If the function is invoked with a zero-length array, it
195 * returns the currently enabled packages, but it also leaves them
196 * active. Therefore, the sequence of calls that would add new
197 * packages instead of replacing the current ones is:
198 * @p(code) 199 * var current = Trace.packageEnable([]);
200 * current[current.length++] = "ti.targets";
201 * Trace.packageEnable(current);
202 * @p 203 *
204 * To disable trace for all packages, the function must be invoked
205 * with an empty string as the only element of the array.
206 * @p(code) 207 * Trace.packageEnable([""]);
208 * @p 209 *
210 * @params capsules array of package names
211 *
212 * @a(return) array of currently enabled package names
213 */
214 StringArray packageEnable(StringArray packages);
215
216 /*!
217 * ======== setLevel ========
218 * Set the verbosity level
219 *
220 * This function limits trace output to trace statement tagged with
221 * level equal or lower than this function's parameter. By default,
222 * the verbosity level is set to 0, which is the least verbose level.
223 * The most verbose level is 2.
224 */
225 Int setLevel(Int level);
226
227 /*!
228 * ======== start ========
229 * @_nodoc 230 * Activate trace
231 */
232 Void start();
233 }
234 /*
235 * @(#) xdc.services.global; 1, 0, 0,298; 1-12-2011 10:12:32; /db/ztree/library/trees/xdc/xdc-v55x/src/packages/
236 */
237