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 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 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 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 285 286 287 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 297 298 299 300 301 302 303 304 305 306
307 config UInt16 unnamedModsLastId = 0x4000;
308 config UInt16 registryModsLastId = 0x7FFF;
309
310 311 312 313
314
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 349
350