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