1 2 3 4 5 6 7 8 9 10 11 12
13 14 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
24 * common substrings. Collections with a high degree of commonality
25 * are stored in much less space than as ordinary table of independent
26 * C strings.
27 *
28 * To further save space, the "compressed" representation need not even
29 * be loaded in the target's memory; see `{@link #isLoaded}`.
30 *
31 * The total space available for the compressed representation of text
32 * strings is limited to 64K characters; each string is represented by
33 * a 16-bit "rope id".
34 */
35 @Template("./Text.xdt")
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 metaonly struct 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 separated
105 * in their own section `xdc.noload`, which is not loaded to the target.
106 *
107 * @a(Note)
108 * For TI and GNU targets, the section `xdc.noload` is not loaded to
109 * the target, but it can overlay other output sections. If the linker
110 * allocates `xdc.noload` so that it overlaps the section that contains
111 * character strings when `isLoaded` is `false`, ROV/RTA functionality
112 * can be affected. In such a case, an error message is displayed that
113 * indicates the overlap between `xdc.noload` and another section, whose
114 * name depends on the target (.`const` on TI targets, `.rodata` on
115 * GNU targets).
116 * The user can solve that problem by specifying an address for
117 * `xdc.noload` to unconfigured memory, and ensure that `.const` and
118 * `xdc.noload` do not overlap.
119 * @p(code)
120 * Program.sectMap["xdc.noload"] = new prog.SectionSpec();
121 * Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
122 * @p
123 */
124 config Bool isLoaded = true;
125
126 /*!
127 * ======== cordText ========
128 * Return `NULL` if cord is in `charTab` and `isLoaded` is `FALSE`
129 * @_nodoc
130 */
131 String cordText(CordAddr cord);
132
133 /*!
134 * ======== ropeText ========
135 * Convert rope to an ordinary C string
136 *
137 * Convert rope to an ordinary C string or to NULL if rope refers
138 * to a node in nodeTab
139 *
140 * @_nodoc
141 */
142 String ropeText(RopeId rope);
143
144 /*!
145 * ======== matchRope ========
146 * Compare pattern string `pat` to String identified by `rope`.
147 * @_nodoc
148 *
149 * @a(pre-conditions)
150 * @p(blist)
151 * - lenp must be less than or equal to the length of pat
152 * @p
153
154 * @a(post-conditions)
155 * @p(blist)
156 * - lenp is decreased by the length of any matching prefix
157 * @p
158 *
159 * Returns:
160 * @p(blist)
161 * - -1 `pat` does not match string
162 * - 0 string is a prefix of pattern
163 * - 1 wildcard match
164 * @p
165 */
166 Int matchRope(RopeId rope, String pat, Int *lenp);
167
168 /*!
169 * ======== putLab ========
170 * Convert label to an ASCII character sequence
171 *
172 * This function converts a `{@link Types#Label}` to a sequence of
173 * ASCII characters, writes the characters to the supplied buffer,
174 * updates the buffer pointer to point to the location after the last
175 * output character, and returns the number of characters output.
176 *
177 * No more than `len` characters will be output. If the label would
178 * otherwise be longer, the output is truncated at the point where a
179 * potential overflow is detected. The return value always reflects the
180 * number of characters output, but it may be less than `len`.
181 *
182 * Label structures can be initialized from any module's instance handle
183 * using the module's `Mod_Handle_label()` method. See
184 * `{@link Types#Label}` for more information.
185 *
186 * @param(lab) address of the label to interpret
187 * @param(bufp) address of the output buffer pointer or `NULL`
188 *
189 * If `bufp` is `NULL`, the label's characters are
190 * output via `{@link System#putch()}`.
191 *
192 * @param(len) maximum number of characters to generate
193 *
194 * If `len` is negative, the number of characters to be
195 * generated is not limited.
196 *
197 * @a(returns)
198 * The return value always reflects the number of characters output,
199 * but it may be less than `len`.
200 *
201 * @see Types#Label
202 */
203 Int putLab(Types.Label *lab, Char **bufp, Int len);
204
205 /*!
206 * ======== putMod ========
207 * Convert module ID to its ASCII name
208 *
209 * This function converts a `{@link Types#ModuleId}` to a sequence of
210 * ASCII characters, writes the characters to the supplied buffer,
211 * updates the buffer pointer to point to the location after the last
212 * output character, and returns the number of characters output.
213 *
214 * No more than `len` characters will be output. If the module name would
215 * otherwise be longer, the output is truncated at the point where a
216 * potential overflow is detected. The return value always reflects the
217 * number of characters output, but it may be less than `len`.
218 *
219 * @param(mid) ID of the module
220 * @param(bufp) address of the output buffer pointer or `NULL`
221 *
222 * If `bufp` is `NULL`, the module's name characters are
223 * output via `{@link System#putch()}`.
224 *
225 * @param(len) maximum number of characters to generate
226 *
227 * If `len` is negative, the number of characters to be
228 * generated is not limited.
229 *
230 * @a(returns)
231 * The return value always reflects the number of characters output,
232 * but it may be less than `len`.
233 */
234 Int putMod(Types.ModuleId mid, Char **bufp, Int len);
235
236 /*!
237 * ======== putSite ========
238 * Convert call site structure to an ASCII character sequence
239 *
240 * This function converts a `{@link Types#Site}` to a sequence of
241 * ASCII characters, writes the characters to the supplied buffer,
242 * updates the buffer pointer to point to the location after the last
243 * output character, and returns the number of characters output.
244 *
245 * No more than `len` characters will be output. If the sequence would
246 * otherwise be longer, the output is truncated at the point where a
247 * potential overflow is detected.
248 *
249 * @param(site) address of the call site structure to interpret
250 * @param(bufp) address of the output buffer pointer or `NULL`
251 *
252 * If `bufp` is `NULL`, the site's name characters are
253 * output via `{@link System#putch()}`.
254 *
255 * @param(len) maximum number of characters to generate
256 *
257 * If `len` is negative, the number of characters to be
258 * generated is not limited.
259 *
260 * @a(returns)
261 * The return value always reflects the number of characters output,
262 * but it may be less than `len`.
263 */
264 Int putSite(Types.Site *site, Char **bufp, Int len);
265
266 internal:
267
268 struct Node {
269 Types.RopeId left;
270 Types.RopeId right;
271 };
272
273 typedef Bool (*RopeVisitor)(Ptr, String);
274
275 struct MatchVisState {
276 String pat;
277 Int *lenp;
278 Int res;
279 };
280
281 struct PrintVisState {
282 Char **bufp;
283 Int len;
284 Int res;
285 };
286
287 288 289 290 291
292 config Char charTab[] = [0];
293 config Node nodeTab[] = [{left: 0, right: 0}];
294
295 config Int16 charCnt = 1;
296 config Int16 nodeCnt = 1;
297
298 299 300 301 302 303 304 305 306 307 308 309
310 config UInt16 unnamedModsLastId = 0x4000;
311 config UInt16 registryModsLastId = 0x7FFF;
312
313 314 315 316
317
318
319 function defineRopeCord(text);
320 function defineRopeNode(left, right);
321
322 function fetchAddr(raddr);
323 function fetchCord(cid);
324 function fetchId(rid);
325 function fetchNode(nid);
326
327 function genModNames();
328 function genPkgName();
329
330 Bool matchVisFxn(Ptr p, String s);
331 Bool printVisFxn(Ptr p, String s);
332
333 Void visitRope(RopeId rope, Fxn visFxn, Ptr visState);
334 Void visitRope2(RopeId rope, Fxn visFxn, Ptr visState, String stack[]);
335
336 typedef Void (*VisitRopeFxn)(RopeId, Fxn, Ptr);
337 typedef Void (*VisitRopeFxn2)(RopeId, Fxn, Ptr, String[]);
338
339 config VisitRopeFxn visitRopeFxn = visitRope;
340
341 config VisitRopeFxn2 visitRopeFxn2 = visitRope2;
342
343 Int xprintf(Char **bufp, String fmt, ...);
344
345 struct Module_State {
346 Ptr charBase;
347 Ptr nodeBase;
348 };
349 }
350 351 352
353