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 @RomConsts
37
38 module Text {
39
40 /*!
41 * ======== CordAddr ========
42 * @_nodoc
43 */
44 typedef Types.CordAddr CordAddr;
45
46 /*!
47 * ======== Label ========
48 */
49 typedef Types.Label Label;
50
51 /*!
52 * ======== RopeId ========
53 * @_nodoc
54 *
55 * A rope id is a 16-bit value whose most-significant bit indicates
56 * whether the lower 15-bits are an offset into the string table
57 * `charTab` or an offset into the "node" table `nodeTab`.
58 *
59 * The node id 0 represents the empty string "".
60 */
61 typedef Types.RopeId RopeId;
62
63 /*!
64 * ======== Module_View ========
65 * @_nodoc
66 */
67 @XmlDtd
68 metaonly struct Module_View {
69 Ptr charBase;
70 Ptr nodeBase;
71 };
72
73 /*!
74 * ======== nameUnknown ========
75 * Default unknowable instance name
76 *
77 * The name of an instance if the module's instances are configured to
78 * not have names.
79 */
80 config String nameUnknown = "{unknown-instance-name}";
81
82 /*!
83 * ======== nameEmpty ========
84 * Default `NULL` instance name
85 *
86 * The name used if the instance's name has been set to `NULL`.
87 */
88 config String nameEmpty = "{empty-instance-name}";
89
90 /*!
91 * ======== nameStatic ========
92 * Default static instance name
93 *
94 * The name of an instance if the name exists but it's not loaded
95 * on the target.
96 */
97 config String nameStatic = "{static-instance-name}";
98
99 /*!
100 * ======== isLoaded ========
101 * Ensure character-strings are loaded in target memory
102 *
103 * Character strings managed by this module are allocated together
104 * with other character strings, and loaded to the target, when this
105 * parameter is set to its default value `true`. If this parameter is
106 * set to `false`, the character strings managed by Text are removed from
107 * the application.
108 *
109 * A consequence of setting this parameter to `false` is that all names
110 * assigned to static instances are set to NULL, and cannot be displayed by
111 * the code loaded to the target. Also, the Log Events that automatically
112 * print instance names will print NULL for any static instance. The same
113 * code would print the pointers to the names if this parameter is set to
114 * `true` and 'isLoaded` is set to '`false`.
115 *
116 * ROV is not affected by this parameter and it will also correctly display
117 * names of static instances in their modules' views. ROV detects these
118 * names from the saved configuration files.
119 *
120 * Module and event IDs are still unique and Log.Events within one module
121 * have consecutive IDs.
122 */
123 config Bool isLoaded = true;
124
125 /*!
126 * ======== cordText ========
127 * Return `NULL` if cord is in `charTab` and `isLoaded` is `FALSE`
128 * @_nodoc
129 */
130 String cordText(CordAddr cord);
131
132 /*!
133 * ======== ropeText ========
134 * Convert rope to an ordinary C string
135 *
136 * Convert rope to an ordinary C string or to NULL if rope refers
137 * to a node in nodeTab
138 *
139 * @_nodoc
140 */
141 String ropeText(RopeId rope);
142
143 /*!
144 * ======== matchRope ========
145 * Compare pattern string `pat` to String identified by `rope`.
146 * @_nodoc
147 *
148 * @a(pre-conditions)
149 * @p(blist)
150 * - lenp must be less than or equal to the length of pat
151 * @p
152
153 * @a(post-conditions)
154 * @p(blist)
155 * - lenp is decreased by the length of any matching prefix
156 * @p
157 *
158 * Returns:
159 * @p(blist)
160 * - -1 `pat` does not match string
161 * - 0 string is a prefix of pattern
162 * - 1 wildcard match
163 * @p
164 */
165 Int matchRope(RopeId rope, CString pat, Int *lenp);
166
167 /*!
168 * ======== putLab ========
169 * Convert label to an ASCII character sequence
170 *
171 * This function converts a `{@link Types#Label}` to a sequence of
172 * ASCII characters, writes the characters to the supplied buffer,
173 * updates the buffer pointer to point to the location after the last
174 * output character, and returns the number of characters output.
175 *
176 * No more than `len` characters will be output. If the label would
177 * otherwise be longer, the output is truncated at the point where a
178 * potential overflow is detected. The return value always reflects the
179 * number of characters output, but it may be less than `len`.
180 *
181 * Label structures can be initialized from any module's instance handle
182 * using the module's `Mod_Handle_label()` method. See
183 * `{@link Types#Label}` for more information.
184 *
185 * @param(lab) address of the label to interpret
186 * @param(bufp) address of the output buffer pointer or `NULL`
187 *
188 * If `bufp` is `NULL`, the label's characters are
189 * output via `{@link System#putch()}`.
190 *
191 * @param(len) maximum number of characters to generate
192 *
193 * If `len` is negative, the number of characters to be
194 * generated is not limited.
195 *
196 * @a(returns)
197 * The return value always reflects the number of characters output,
198 * but it may be less than `len`.
199 *
200 * @see Types#Label
201 */
202 Int putLab(Types.Label *lab, Char **bufp, Int len);
203
204 /*!
205 * ======== putMod ========
206 * Convert module ID to its ASCII name
207 *
208 * This function converts a `{@link Types#ModuleId}` to a sequence of
209 * ASCII characters, writes the characters to the supplied buffer,
210 * updates the buffer pointer to point to the location after the last
211 * output character, and returns the number of characters output.
212 *
213 * No more than `len` characters will be output. If the module name would
214 * otherwise be longer, the output is truncated at the point where a
215 * potential overflow is detected. The return value always reflects the
216 * number of characters output, but it may be less than `len`.
217 *
218 * @param(mid) ID of the module
219 * @param(bufp) address of the output buffer pointer or `NULL`
220 *
221 * If `bufp` is `NULL`, the module's name characters are
222 * output via `{@link System#putch()}`.
223 *
224 * @param(len) maximum number of characters to generate
225 *
226 * If `len` is negative, the number of characters to be
227 * generated is not limited.
228 *
229 * @a(returns)
230 * The return value always reflects the number of characters output,
231 * but it may be less than `len`.
232 */
233 Int putMod(Types.ModuleId mid, Char **bufp, Int len);
234
235 /*!
236 * ======== putSite ========
237 * Convert call site structure to an ASCII character sequence
238 *
239 * This function converts a `{@link Types#Site}` to a sequence of
240 * ASCII characters, writes the characters to the supplied buffer,
241 * updates the buffer pointer to point to the location after the last
242 * output character, and returns the number of characters output.
243 *
244 * No more than `len` characters will be output. If the sequence would
245 * otherwise be longer, the output is truncated at the point where a
246 * potential overflow is detected.
247 *
248 * @param(site) address of the call site structure to interpret
249 * @param(bufp) address of the output buffer pointer or `NULL`
250 *
251 * If `bufp` is `NULL`, the site's name characters are
252 * output via `{@link System#putch()}`.
253 *
254 * @param(len) maximum number of characters to generate
255 *
256 * If `len` is negative, the number of characters to be
257 * generated is not limited.
258 *
259 * @a(returns)
260 * The return value always reflects the number of characters output,
261 * but it may be less than `len`.
262 */
263 Int putSite(Types.Site *site, Char **bufp, Int len);
264
265 internal:
266
267 struct Node {
268 Types.RopeId left;
269 Types.RopeId right;
270 };
271
272 typedef Bool (*RopeVisitor)(Ptr, String);
273
274 struct MatchVisState {
275 CString pat;
276 Int *lenp;
277 Int res;
278 };
279
280 struct PrintVisState {
281 Char **bufp;
282 Int len;
283 Int res;
284 };
285
286 287 288 289 290
291 config Char charTab[] = [0];
292 config Node nodeTab[] = [{left: 0, right: 0}];
293
294 config Int16 charCnt = 1;
295 config Int16 nodeCnt = 1;
296
297 298 299 300 301 302 303 304 305 306 307 308
309 config UInt16 unnamedModsLastId = 0x4000;
310 config UInt16 registryModsLastId = 0x7FFF;
311
312 313 314 315
316
317
318 function defineRopeCord(text);
319 function defineRopeNode(left, right);
320
321 function fetchAddr(raddr);
322 function fetchCord(cid);
323 function fetchId(rid);
324 function fetchNode(nid);
325
326 function genModNames();
327 function genPkgName();
328
329 Bool matchVisFxn(Ptr p, CString s);
330 Bool printVisFxn(Ptr p, CString s);
331
332 Void visitRope(RopeId rope, Fxn visFxn, Ptr visState);
333 Void visitRope2(RopeId rope, Fxn visFxn, Ptr visState, String stack[]);
334
335 typedef Void (*VisitRopeFxn)(RopeId, Fxn, Ptr);
336 typedef Void (*VisitRopeFxn2)(RopeId, Fxn, Ptr, String[]);
337
338 config VisitRopeFxn visitRopeFxn = visitRope;
339
340 config VisitRopeFxn2 visitRopeFxn2 = visitRope2;
341
342 Int xprintf(Char **bufp, SizeT len, CString fmt, ...);
343
344 struct Module_State {
345 CPtr charBase;
346 CPtr nodeBase;
347 };
348 }
349 350 351
352