1 /*
2 * Copyright (c) 2008 Texas Instruments. All rights reserved.
3 * This program and the accompanying materials are made available under the
4 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License
5 * v. 1.0 which accompanies this distribution. The Eclipse Public License is
6 * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
7 * Distribution License is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * Contributors:
11 * Texas Instruments - initial implementation
12 * */
13 /*
14 * ========= Text.xdc ========
15 */
16
17 package xdc.runtime;
18
19 /*!
20 * ======== Text ========
21 * Runtime text handling services
22 *
23 * This module efficiently manages a collection of strings that have common
24 * substrings. Collections with a high degree of commonality are stored in
25 * much less space than as ordinary table of independent C strings.
26 *
27 * To further save space, the "compressed" representation need not even
28 * be loaded in the target's memory; see `{@link #isLoaded}`.
29 *
30 * The total space available for the compressed representation of text strings
31 * is limited to 64K characters; each string is represented by a 16-bit
32 * "rope id".
33 */
34 @Template("./Text.xdt")
35 @DirectCall
36 module Text {
37
38 /*!
39 * ======== CordAddr ========
40 * @_nodoc 41 */
42 typedef Types.CordAddr CordAddr;
43
44 /*!
45 * ======== Label ========
46 */
47 typedef Types.Label Label;
48
49 /*!
50 * ======== RopeId ========
51 * @_nodoc 52 *
53 * A rope id is a 16-bit value whose most-significant bit indicates
54 * whether the lower 15-bits are an offset into the string table
55 * `charTab` or an offset into the "node" table `nodeTab`.
56 *
57 * The node id 0 represents the empty string "".
58 */
59 typedef Types.RopeId RopeId;
60
61 /*!
62 * ======== Module_View ========
63 * @_nodoc 64 */
65 @XmlDtd
66 metaonlystruct Module_View {
67 Ptr charBase;
68 Ptr nodeBase;
69 };
70
71 /*!
72 * ======== nameUnknown ========
73 * Default unknowable instance name
74 *
75 * The name of an instance if the module's instances are configured to
76 * not have names.
77 */
78 config String nameUnknown = "{unknown-instance-name}";
79
80 /*!
81 * ======== nameEmpty ========
82 * Default `NULL` instance name
83 *
84 * The name used if the instance's name has been set to `NULL`.
85 */
86 config String nameEmpty = "{empty-instance-name}";
87
88 /*!
89 * ======== nameStatic ========
90 * Default static instance name
91 *
92 * The name of an instance if the name exists but it's not loaded
93 * on the target.
94 */
95 config String nameStatic = "{static-instance-name}";
96
97 /*!
98 * ======== isLoaded ========
99 * Ensure character-strings are loaded in target memory
100 *
101 * Character strings managed by this module are allocated together
102 * with other character strings, and loaded to the target, when this
103 * parameter is set to its default value `true`. If this parameter is
104 * set to `false`, the character strings managed by Text are removed from
105 * the application.
106 *
107 * A consequence of setting this parameter to `false` is that all names
108 * assigned to static instances are set to NULL, and cannot be displayed by
109 * the code loaded to the target. Also, the Log Events that automatically
110 * print instance names will print NULL for any static instance. The same
111 * code would print the pointers to the names if this parameter is set to
112 * `true` and 'isLoaded` is set to '`false`.
113 *
114 * ROV is not affected by this parameter and it will also correctly display
115 * names of static instances in their modules' views. ROV detects these
116 * names from the saved configuration files.
117 *
118 * Module and event IDs are still unique and Log.Events within one module
119 * have consecutive IDs.
120 */
121 config Bool isLoaded = true;
122
123 /*!
124 * ======== cordText ========
125 * Return `NULL` if cord is in `charTab` and `isLoaded` is `FALSE`
126 * @_nodoc 127 */
128 String cordText(CordAddr cord);
129
130 /*!
131 * ======== ropeText ========
132 * Convert rope to an ordinary C string
133 *
134 * Convert rope to an ordinary C string or to NULL if rope refers
135 * to a node in nodeTab
136 *
137 * @_nodoc 138 */
139 CString ropeText(RopeId rope);
140
141 /*!
142 * ======== matchRope ========
143 * Compare pattern string `pat` to String identified by `rope`.
144 * @_nodoc 145 *
146 * @a(pre-conditions)
147 * @p(blist) 148 * - lenp must be less than or equal to the length of pat
149 * @p 150 151 * @a(post-conditions)
152 * @p(blist) 153 * - lenp is decreased by the length of any matching prefix
154 * @p 155 *
156 * Returns:
157 * @p(blist) 158 * - -1 `pat` does not match string
159 * - 0 string is a prefix of pattern
160 * - 1 wildcard match
161 * @p 162 */
163 Int matchRope(RopeId rope, CString pat, Int *lenp);
164
165 /*!
166 * ======== putLab ========
167 * Convert label to an ASCII character sequence
168 *
169 * This function converts a `{@link Types#Label}` to a sequence of
170 * ASCII characters, writes the characters to the supplied buffer,
171 * updates the buffer pointer to point to the location after the last
172 * output character, and returns the number of characters output.
173 *
174 * No more than `len` characters will be output. If the label would
175 * otherwise be longer, the output is truncated at the point where a
176 * potential overflow is detected. The return value always reflects the
177 * number of characters output, but it may be less than `len`.
178 *
179 * Label structures can be initialized from any module's instance handle
180 * using the module's `Mod_Handle_label()` method. See
181 * `{@link Types#Label}` for more information.
182 *
183 * @param(lab) address of the label to interpret
184 * @param(bufp) address of the output buffer pointer or `NULL`
185 *
186 * If `bufp` is `NULL`, the label's characters are
187 * output via `{@link System#putch()}`.
188 *
189 * @param(len) maximum number of characters to generate
190 *
191 * If `len` is negative, the number of characters to be
192 * generated is not limited.
193 *
194 * @a(returns) 195 * The return value always reflects the number of characters output,
196 * but it may be less than `len`.
197 *
198 * @see Types#Label
199 */
200 Int putLab(Types.Label *lab, Char **bufp, Int len);
201
202 /*!
203 * ======== putMod ========
204 * Convert module ID to its ASCII name
205 *
206 * This function converts a `{@link Types#ModuleId}` to a sequence of
207 * ASCII characters, writes the characters to the supplied buffer,
208 * updates the buffer pointer to point to the location after the last
209 * output character, and returns the number of characters output.
210 *
211 * No more than `len` characters will be output. If the module name would
212 * otherwise be longer, the output is truncated at the point where a
213 * potential overflow is detected. The return value always reflects the
214 * number of characters output, but it may be less than `len`.
215 *
216 * @param(mid) ID of the module
217 * @param(bufp) address of the output buffer pointer or `NULL`
218 *
219 * If `bufp` is `NULL`, the module's name characters are
220 * output via `{@link System#putch()}`.
221 *
222 * @param(len) maximum number of characters to generate
223 *
224 * If `len` is negative, the number of characters to be
225 * generated is not limited.
226 *
227 * @a(returns) 228 * The return value always reflects the number of characters output,
229 * but it may be less than `len`.
230 */
231 Int putMod(Types.ModuleId mid, Char **bufp, Int len);
232
233 /*!
234 * ======== putSite ========
235 * Convert call site structure to an ASCII character sequence
236 *
237 * This function converts a `{@link Types#Site}` to a sequence of
238 * ASCII characters, writes the characters to the supplied buffer,
239 * updates the buffer pointer to point to the location after the last
240 * output character, and returns the number of characters output.
241 *
242 * No more than `len` characters will be output. If the sequence would
243 * otherwise be longer, the output is truncated at the point where a
244 * potential overflow is detected.
245 *
246 * @param(site) address of the call site structure to interpret
247 * @param(bufp) address of the output buffer pointer or `NULL`
248 *
249 * If `bufp` is `NULL`, the site's name characters are
250 * output via `{@link System#putch()}`.
251 *
252 * @param(len) maximum number of characters to generate
253 *
254 * If `len` is negative, the number of characters to be
255 * generated is not limited.
256 *
257 * @a(returns) 258 * The return value always reflects the number of characters output,
259 * but it may be less than `len`.
260 */
261 Int putSite(Types.Site *site, Char **bufp, Int len);
262
263 internal:
264
265 struct Node {
266 Types.RopeId left;
267 Types.RopeId right;
268 };
269
270 typedef Bool (*RopeVisitor)(Ptr, CString);
271
272 struct MatchVisState {
273 CString pat;
274 Int *lenp;
275 Int res;
276 };
277
278 struct PrintVisState {
279 Char **bufp;
280 Int len;
281 Int res;
282 };
283
284 /* charTab[] and nodeTab[] are the "compressed" representation of
285 * target strings used to name instances, modules, packages, ...
286 *
287 * The predefined node id 0 represents the empty string.
288 */
289 config Char charTab[] = [0];
290 config Node nodeTab[] = [{left: 0, right: 0}];
291
292 config Int16 charCnt = 1;
293 config Int16 nodeCnt = 1;
294
295 /*
296 * The module ids are allocated as follows:
297 * 0x1 - 0x4000 unnamed modules
298 * 0x4001 - 0x7FFF registry modules
299 * 0x8000 - 0xFFFF named modules
300 *
301 * See 'genModNames' in Text.xs
302 *
303 * TODO - We may be able to set unnamedModsLastId based on the config
304 * to give the Registry more room, but then the Registry id range
305 * would not be a constant.
306 */
307 config UInt16 unnamedModsLastId = 0x4000;
308 config UInt16 registryModsLastId = 0x7FFF;
309
310 /* unnamedModCnt can be used to define a constant that allows external
311 * modules to define their own module IDs that don't conflict with the
312 * statically configured modules; e.g., the dlog example could use this
313 */
314 // config Int16 unnamedModCnt = 0;
315
316 function defineRopeCord(text);
317 function defineRopeNode(left, right);
318
319 function fetchAddr(raddr);
320 function fetchCord(cid);
321 function fetchId(rid);
322 function fetchNode(nid);
323
324 function genModNames();
325 function genPkgName();
326
327 Bool matchVisFxn(Ptr p, CString s);
328 Bool printVisFxn(Ptr p, CString s);
329
330 Void visitRope(RopeId rope, Fxn visFxn, Ptr visState);
331 Void visitRope2(RopeId rope, Fxn visFxn, Ptr visState, CString stack[]);
332
333 typedef Void (*VisitRopeFxn)(RopeId, Fxn, Ptr);
334 typedef Void (*VisitRopeFxn2)(RopeId, Fxn, Ptr, CString[]);
335
336 config VisitRopeFxn visitRopeFxn = visitRope;
337
338 config VisitRopeFxn2 visitRopeFxn2 = visitRope2;
339
340 Int xprintf(Char **bufp, SizeT len, CString fmt, ...);
341
342 struct Module_State {
343 CPtr charBase;
344 CPtr nodeBase;
345 };
346 }
347 /*
348 * @(#) xdc.runtime; 2, 1, 0,0; 2-8-2017 14:15:56; /db/ztree/library/trees/xdc/xdc-D05/src/packages/
349 */
350