1 /* --COPYRIGHT--,ESD
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 * --/COPYRIGHT--*/
13 /*
14 * ========= Text.xdc ========
15 *
16 *! Revision History
17 *! ================
18 *! 22-May-2009 sasha added isLoaded doc comments
19 *! 03-Dec-2007 sasha implemented code review changes
20 */
21
22 package xdc.runtime;
23
24 /*!
25 * ======== Text ========
26 * Runtime text handling services
27 *
28 * This module efficiently manages a collection of strings that have
29 * common substrings. Collections with a high degree of commonality
30 * are stored in much less space than as ordinary table of independent
31 * C strings.
32 *
33 * To further save space, the "compressed" representation need not even
34 * be loaded in the target's memory; see `{@link #isLoaded}`.
35 *
36 * The total space available for the compressed representation of text
37 * strings is limited to 64K characters; each string is represented by
38 * a 16-bit "rope id".
39 */
40 @Template("./Text.xdt")
41 module Text {
42
43 /*!
44 * ======== CordAddr ========
45 * @_nodoc 46 */
47 typedef Types.CordAddr CordAddr;
48
49 /*!
50 * ======== Label ========
51 */
52 typedef Types.Label Label;
53
54 /*!
55 * ======== RopeId ========
56 * @_nodoc 57 *
58 * A rope id is a 16-bit value whose most-significant bit indicates
59 * whether the lower 15-bits are an offset into the string table
60 * `charTab` or an offset into the "node" table `nodeTab`.
61 *
62 * The node id 0 represents the empty string "".
63 */
64 typedef Types.RopeId RopeId;
65
66 /*!
67 * ======== Module_View ========
68 * @_nodoc 69 */
70 @XmlDtd
71 metaonlystruct Module_View {
72 Ptr charBase;
73 Ptr nodeBase;
74 };
75
76 /*!
77 * ======== nameUnknown ========
78 * Default unknowable instance name
79 *
80 * The name of an instance if the module's instances are configured to
81 * not have names.
82 */
83 config String nameUnknown = "{unknown-instance-name}";
84
85 /*!
86 * ======== nameEmpty ========
87 * Default `NULL` instance name
88 *
89 * The name used if the instance's name has been set to `NULL`.
90 */
91 config String nameEmpty = "{empty-instance-name}";
92
93 /*!
94 * ======== nameStatic ========
95 * Default static instance name
96 *
97 * The name of an instance if the name exists but it's not loaded
98 * on the target.
99 */
100 config String nameStatic = "{static-instance-name}";
101
102 /*!
103 * ======== isLoaded ========
104 * Ensure character-strings are loaded in target memory
105 *
106 * Character strings managed by this module are allocated together
107 * with other character strings, and loaded to the target, when this
108 * parameter is set to its default value `true`. If this parameter is
109 * set to `false`, the character strings managed by Text are separated
110 * in their own section `xdc.noload`, which is not loaded to the target.
111 *
112 * @a(Note) 113 * For TI and GNU targets, the section `xdc.noload` is not loaded to
114 * the target, but it can overlay other output sections. If the linker
115 * allocates `xdc.noload` so that it overlaps the section that contains
116 * character strings when `isLoaded` is `false`, ROV/RTA functionality
117 * can be affected. In such a case, an error message is displayed that
118 * indicates the overlap between `xdc.noload` and another section, whose
119 * name depends on the target (.`const` on TI targets, `.rodata` on
120 * GNU targets).
121 * The user can solve that problem by specifying an address for
122 * `xdc.noload` to unconfigured memory, and ensure that `.const` and
123 * `xdc.noload` do not overlap.
124 * @p(code) 125 * Program.sectMap["xdc.noload"] = new prog.SectionSpec();
126 * Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
127 * @p 128 */
129 config Bool isLoaded = true;
130
131 /*!
132 * ======== cordText ========
133 * Return `NULL` if cord is in `charTab` and `isLoaded` is `FALSE`
134 * @_nodoc 135 */
136 String cordText(CordAddr cord);
137
138 /*!
139 * ======== ropeText ========
140 * Convert rope to an ordinary C string
141 *
142 * Convert rope to an ordinary C string or to NULL if rope refers
143 * to a node in nodeTab
144 *
145 * @_nodoc 146 */
147 String ropeText(RopeId rope);
148
149 /*!
150 * ======== matchRope ========
151 * Compare pattern string `pat` to String identified by `rope`.
152 * @_nodoc 153 *
154 * @a(pre-conditions)
155 * @p(blist) 156 * - lenp must be less than or equal to the length of pat
157 * @p 158 159 * @a(post-conditions)
160 * @p(blist) 161 * - lenp is decreased by the length of any matching prefix
162 * @p 163 *
164 * Returns:
165 * @p(blist) 166 * - -1 `pat` does not match string
167 * - 0 string is a prefix of pattern
168 * - 1 wildcard match
169 * @p 170 */
171 Int matchRope(RopeId rope, String pat, Int *lenp);
172
173 /*!
174 * ======== putLab ========
175 * Convert label to an ASCII character sequence
176 *
177 * This function converts a `{@link Types#Label}` to a sequence of
178 * ASCII characters, writes the characters to the supplied buffer,
179 * updates the buffer pointer to point to the location after the last
180 * output character, and returns the number of characters output.
181 *
182 * No more than `len` characters will be output. If the label would
183 * otherwise be longer, the output is truncated at the point where a
184 * potential overflow is detected. The return value always reflects the
185 * number of characters output, but it may be less than `len`.
186 *
187 * Label structures can be initialized from any module's instance handle
188 * using the module's `Mod_Handle_label()` method. See
189 * `{@link Types#Label}` for more information.
190 *
191 * @param(lab) address of the label to interpret
192 * @param(bufp) address of the output buffer pointer or `NULL`
193 *
194 * If `bufp` is `NULL`, the label's characters are
195 * output via `{@link System#putch()}`.
196 *
197 * @param(len) maximum number of characters to generate
198 *
199 * If `len` is negative, the number of characters to be
200 * generated is not limited.
201 *
202 * @a(returns) 203 * The return value always reflects the number of characters output,
204 * but it may be less than `len`.
205 *
206 * @see Types#Label
207 */
208 Int putLab(Types.Label *lab, Char **bufp, Int len);
209
210 /*!
211 * ======== putMod ========
212 * Convert module ID to its ASCII name
213 *
214 * This function converts a `{@link Types#ModuleId}` to a sequence of
215 * ASCII characters, writes the characters to the supplied buffer,
216 * updates the buffer pointer to point to the location after the last
217 * output character, and returns the number of characters output.
218 *
219 * No more than `len` characters will be output. If the module name would
220 * otherwise be longer, the output is truncated at the point where a
221 * potential overflow is detected. The return value always reflects the
222 * number of characters output, but it may be less than `len`.
223 *
224 * @param(mid) ID of the module
225 * @param(bufp) address of the output buffer pointer or `NULL`
226 *
227 * If `bufp` is `NULL`, the module's name characters are
228 * output via `{@link System#putch()}`.
229 *
230 * @param(len) maximum number of characters to generate
231 *
232 * If `len` is negative, the number of characters to be
233 * generated is not limited.
234 *
235 * @a(returns) 236 * The return value always reflects the number of characters output,
237 * but it may be less than `len`.
238 */
239 Int putMod(Types.ModuleId mid, Char **bufp, Int len);
240
241 /*!
242 * ======== putSite ========
243 * Convert call site structure to an ASCII character sequence
244 *
245 * This function converts a `{@link Types#Site}` to a sequence of
246 * ASCII characters, writes the characters to the supplied buffer,
247 * updates the buffer pointer to point to the location after the last
248 * output character, and returns the number of characters output.
249 *
250 * No more than `len` characters will be output. If the sequence would
251 * otherwise be longer, the output is truncated at the point where a
252 * potential overflow is detected.
253 *
254 * @param(site) address of the call site structure to interpret
255 * @param(bufp) address of the output buffer pointer or `NULL`
256 *
257 * If `bufp` is `NULL`, the site's name characters are
258 * output via `{@link System#putch()}`.
259 *
260 * @param(len) maximum number of characters to generate
261 *
262 * If `len` is negative, the number of characters to be
263 * generated is not limited.
264 *
265 * @a(returns) 266 * The return value always reflects the number of characters output,
267 * but it may be less than `len`.
268 */
269 Int putSite(Types.Site *site, Char **bufp, Int len);
270
271 internal:
272
273 struct Node {
274 Types.RopeId left;
275 Types.RopeId right;
276 };
277
278 typedef Bool (*RopeVisitor)(Ptr, String);
279
280 struct MatchVisState {
281 String pat;
282 Int *lenp;
283 Int res;
284 };
285
286 struct PrintVisState {
287 Char **bufp;
288 Int len;
289 Int res;
290 };
291
292 /* charTab[] and nodeTab[] are the "compressed" representation of
293 * target strings used to name instances, modules, packages, ...
294 *
295 * The predefined node id 0 represents the empty string.
296 */
297 config Char charTab[] = [0];
298 config Node nodeTab[] = [{left: 0, right: 0}];
299
300 config Int16 charCnt = 1;
301 config Int16 nodeCnt = 1;
302
303 /* unnamedModCnt can be used to define a constant that allows external
304 * modules to define their own module IDs that don't conflict with the
305 * statically configured modules; e.g., the dlog example could use this
306 */
307 // config Int16 unnamedModCnt = 0;
308
309 function defineRopeCord(text);
310 function defineRopeNode(left, right);
311
312 function fetchAddr(raddr);
313 function fetchCord(cid);
314 function fetchId(rid);
315 function fetchNode(nid);
316
317 function genModNames();
318 function genPkgName();
319
320 Bool matchVisFxn(Ptr p, String s);
321 Bool printVisFxn(Ptr p, String s);
322
323 Void visitRope(RopeId rope, Fxn visFxn, Ptr visState);
324 Void visitRope2(RopeId rope, Fxn visFxn, Ptr visState, String stack[]);
325
326 typedef Void (*VisitRopeFxn)(RopeId, Fxn, Ptr);
327 typedef Void (*VisitRopeFxn2)(RopeId, Fxn, Ptr, String[]);
328
329 config VisitRopeFxn visitRopeFxn = visitRope;
330
331 config VisitRopeFxn2 visitRopeFxn2 = visitRope2;
332
333 Int xprintf(Char **bufp, String fmt, ...);
334
335 struct Module_State {
336 Ptr charBase;
337 Ptr nodeBase;
338 };
339 }
340 /*
341 * @(#) xdc.runtime; 2, 0, 0, 0,214; 7-29-2009 14:53:45; /db/ztree/library/trees/xdc-t56x/src/packages/
342 */
343