| /* --COPYRIGHT--,ESD |
| * Copyright (c) 2008-2019 Texas Instruments Incorporated |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Public License v1.0 and Eclipse Distribution License |
| * v. 1.0 which accompanies this distribution. The Eclipse Public License is |
| * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse |
| * Distribution License is available at |
| * http://www.eclipse.org/org/documents/edl-v10.php. |
| * |
| * Contributors: |
| * Texas Instruments - initial implementation |
| * --/COPYRIGHT--*/ |
| /* |
| * ========= Text.xdc ======== |
| */ |
| |
| package xdc.runtime; |
| |
| /*! |
| * ======== Text ======== |
| * Runtime text handling services |
| * |
| * This module efficiently manages a collection of strings that have common |
| * substrings. Collections with a high degree of commonality are stored in |
| * much less space than as an ordinary table of independent C strings. |
| * |
| * To further save space, the "compressed" representation need not even |
| * be loaded in the target's memory; see `{@link #isLoaded}`. |
| * |
| * The total space available for the compressed representation of text strings |
| * is limited to 32K characters; the lowest 15 bits of a 16-bit "rope id" are |
| * an index of a storage array. |
| */ |
| @Template("./Text.xdt") |
| @DirectCall |
| module Text { |
| |
| /*! |
| * ======== CordAddr ======== |
| * @_nodoc |
| */ |
| typedef Types.CordAddr CordAddr; |
| |
| /*! |
| * ======== Label ======== |
| */ |
| typedef Types.Label Label; |
| |
| /*! |
| * ======== RopeId ======== |
| * @_nodoc |
| * |
| * A rope id is a 16-bit value whose most-significant bit indicates |
| * whether the lower 15-bits are an offset into the string table |
| * `charTab` or an offset into the "node" table `nodeTab`. |
| * |
| * The node id 0 represents the empty string "". |
| */ |
| /* REQ_TAG(SYSBIOS-892) */ |
| typedef Types.RopeId RopeId; |
| |
| /*! |
| * ======== Module_View ======== |
| * @_nodoc |
| */ |
| @XmlDtd |
| metaonly struct Module_View { |
| Ptr charBase; |
| Ptr nodeBase; |
| }; |
| |
| /*! |
| * ======== nameUnknown ======== |
| * Default unknowable instance name |
| * |
| * The name of an instance if the module's instances are configured to |
| * not have names. |
| */ |
| /* REQ_TAG(SYSBIOS-889) */ |
| config String nameUnknown = "{unknown-instance-name}"; |
| |
| /*! |
| * ======== nameEmpty ======== |
| * Default `NULL` instance name |
| * |
| * The name used if the instance's name has been set to `NULL`. |
| */ |
| /* REQ_TAG(SYSBIOS-890) */ |
| config String nameEmpty = "{empty-instance-name}"; |
| |
| /*! |
| * ======== nameStatic ======== |
| * Default static instance name |
| * |
| * The name of an instance if the name exists but it's not loaded |
| * on the target. |
| */ |
| /* REQ_TAG(SYSBIOS-891) */ |
| config String nameStatic = "{static-instance-name}"; |
| |
| /*! |
| * ======== isLoaded ======== |
| * Ensure character-strings are loaded in target memory |
| * |
| * Character strings managed by this module are allocated together |
| * with other character strings, and loaded to the target, when this |
| * parameter is set to its default value `true`. If this parameter is |
| * set to `false`, the character strings managed by Text are kept in the |
| * application object file, but they are not loaded to the target. |
| * |
| * A consequence of setting this parameter to `false` is that all names |
| * assigned to static instances are set to NULL, and cannot be displayed by |
| * the code loaded to the target. Also, the Log Events that automatically |
| * print instance names will print NULL for any static instance. |
| * |
| * ROV is not affected by this parameter and it will also correctly display |
| * names of static instances in their modules' views. ROV detects these |
| * names from the saved configuration files. |
| * |
| * Module and event IDs are still unique and Log.Events within one module |
| * have consecutive IDs. |
| */ |
| /* REQ_TAG(SYSBIOS-888) */ |
| config Bool isLoaded = true; |
| |
| /*! |
| * ======== cordText ======== |
| * Return `NULL` if cord is in `charTab` and `isLoaded` is `FALSE` |
| * @_nodoc |
| */ |
| String cordText(CordAddr cord); |
| |
| /*! |
| * ======== ropeText ======== |
| * Convert rope to an ordinary C string |
| * |
| * Convert rope to an ordinary C string or to NULL if rope refers |
| * to a node in nodeTab |
| * |
| * @_nodoc |
| */ |
| /* REQ_TAG(SYSBIOS-886) */ |
| CString ropeText(RopeId rope); |
| |
| /*! |
| * ======== matchRope ======== |
| * Compare pattern string `pat` to String identified by `rope`. |
| * @_nodoc |
| * |
| * This function is invoked from `{@link Diags#setMask()}`, see the |
| * documentation for that function to find out how the patterns are |
| * created. |
| * |
| * @a(pre-conditions) |
| * @p(blist) |
| * - lenp must be less than or equal to the length of pat |
| * - wildcard '%' is at src[(*lenp) - 1], if it's in the the pattern |
| * @p |
| |
| * @a(post-conditions) |
| * @p(blist) |
| * - lenp is decreased by the length of any matching prefix |
| * @p |
| * |
| * Returns: |
| * @p(blist) |
| * - -1 `pat` does not match string |
| * - 0 string is a prefix of pattern |
| * - 1 wildcard match |
| * @p |
| */ |
| /* REQ_TAG(SYSBIOS-893) */ |
| Int matchRope(RopeId rope, CString pat, UShort *lenp); |
| |
| /*! |
| * ======== putLab ======== |
| * Convert label to an ASCII character sequence |
| * |
| * This function converts a `{@link Types#Label}` to a sequence of |
| * ASCII characters, writes the characters to the supplied buffer, |
| * updates the buffer pointer to point to the location after the last |
| * output character, and returns the number of characters output. |
| * |
| * No more than `len` characters will be output. If the label would |
| * otherwise be longer, the output is truncated at the point where a |
| * potential overflow is detected. The return value always reflects the |
| * number of characters output, but it may be less than `len`. |
| * |
| * Label structures can be initialized from any module's instance handle |
| * using the module's `Mod_Handle_label()` method. See |
| * `{@link Types#Label}` for more information. |
| * |
| * @param(lab) address of the label to interpret |
| * @param(bufp) address of the output buffer pointer or `NULL` |
| * |
| * If `bufp` is `NULL`, the label's characters are |
| * output via `{@link System#putch()}`. |
| * |
| * @param(len) maximum number of characters to generate |
| * |
| * If `len` is negative, the number of characters to be |
| * generated is not limited. |
| * |
| * @a(returns) |
| * The return value always reflects the number of characters output, |
| * but it may be less than `len`. |
| * |
| * @see Types#Label |
| */ |
| /* REQ_TAG(SYSBIOS-895), REQ_TAG(SYSBIOS-897), REQ_TAG(SYSBIOS-898) */ |
| Int putLab(Types.Label *lab, Char **bufp, Int len); |
| |
| /*! |
| * ======== putMod ======== |
| * Convert module ID to its ASCII name |
| * |
| * This function converts a `{@link Types#ModuleId}` to a sequence of |
| * ASCII characters, writes the characters to the supplied buffer, |
| * updates the buffer pointer to point to the location after the last |
| * output character, and returns the number of characters output. |
| * |
| * No more than `len` characters will be output. If the module name would |
| * otherwise be longer, the output is truncated at the point where a |
| * potential overflow is detected. The return value always reflects the |
| * number of characters output, but it may be less than `len`. |
| * |
| * @param(mid) ID of the module |
| * @param(bufp) address of the output buffer pointer or `NULL` |
| * |
| * If `bufp` is `NULL`, the module's name characters are |
| * output via `{@link System#putch()}`. |
| * |
| * @param(len) maximum number of characters to generate |
| * |
| * If `len` is negative, the number of characters to be |
| * generated is not limited. |
| * |
| * @a(returns) |
| * The return value always reflects the number of characters output, |
| * but it may be less than `len`. |
| */ |
| /* REQ_TAG(SYSBIOS-894), REQ_TAG(SYSBIOS-897), REQ_TAG(SYSBIOS-898) */ |
| Int putMod(Types.ModuleId mid, Char **bufp, Int len); |
| |
| /*! |
| * ======== putSite ======== |
| * Convert call site structure to an ASCII character sequence |
| * |
| * This function converts a `{@link Types#Site}` to a sequence of |
| * ASCII characters, writes the characters to the supplied buffer, |
| * updates the buffer pointer to point to the location after the last |
| * output character, and returns the number of characters output. |
| * |
| * No more than `len` characters will be output. If the sequence would |
| * otherwise be longer, the output is truncated at the point where a |
| * potential overflow is detected. |
| * |
| * @param(site) address of the call site structure to interpret |
| * @param(bufp) address of the output buffer pointer or `NULL` |
| * |
| * If `bufp` is `NULL`, the site's name characters are |
| * output via `{@link System#putch()}`. |
| * |
| * @param(len) maximum number of characters to generate |
| * |
| * If `len` is negative, the number of characters to be |
| * generated is not limited. |
| * |
| * @a(returns) |
| * The return value always reflects the number of characters output, |
| * but it may be less than `len`. |
| */ |
| /* REQ_TAG(SYSBIOS-896), REQ_TAG(SYSBIOS-897), REQ_TAG(SYSBIOS-898) */ |
| Int putSite(Types.Site *site, Char **bufp, Int len); |
| |
| internal: |
| |
| struct Node { |
| Types.RopeId left; |
| Types.RopeId right; |
| }; |
| |
| typedef Bool (*RopeVisitor)(Ptr, CString); |
| |
| struct MatchVisState { |
| CString pat; |
| UShort *lenp; |
| Int res; |
| }; |
| |
| struct PrintVisState { |
| Char **bufp; |
| UShort len; |
| Int res; |
| }; |
| |
| /* charTab[] and nodeTab[] are the "compressed" representation of |
| * target strings used to name instances, modules, packages, ... |
| * |
| * The predefined node id 0 represents the empty string. |
| */ |
| config Char charTab[] = [0]; |
| config Node nodeTab[] = [{left: 0, right: 0}]; |
| |
| /* REQ_TAG(SYSBIOS-887) */ |
| config Int16 charCnt = 1; |
| config Int16 nodeCnt = 1; |
| |
| /* |
| * The module ids are allocated as follows: |
| * 0x1 - 0x4000 unnamed modules |
| * 0x4001 - 0x7FFF registry modules |
| * 0x8000 - 0xFFFF named modules |
| * |
| * See 'genModNames' in Text.xs |
| * |
| * TODO - We may be able to set unnamedModsLastId based on the config |
| * to give the Registry more room, but then the Registry id range |
| * would not be a constant. |
| */ |
| config UInt16 unnamedModsLastId = 0x4000; |
| config UInt16 registryModsLastId = 0x7FFF; |
| |
| /* unnamedModCnt can be used to define a constant that allows external |
| * modules to define their own module IDs that don't conflict with the |
| * statically configured modules; e.g., the dlog example could use this |
| */ |
| // config Int16 unnamedModCnt = 0; |
| |
| /*! |
| * ======== defineRopeCord ======== |
| * Put text in charTab[] and return its offset within charTab |
| */ |
| function defineRopeCord(text); |
| |
| /*! |
| * ======== defineRopeNode ======== |
| * Create a new Node structure, add it to nodeTabe, and return nodeId, |
| * which is an offset within nodeTab with the leftmost bit set. |
| */ |
| function defineRopeNode(left, right); |
| |
| function fetchAddr(raddr); |
| function fetchCord(cid); |
| function fetchId(rid); |
| function fetchNode(nid); |
| |
| function genModNames(); |
| function genPkgName(); |
| |
| Bool matchVisFxn(Ptr p, CString s); |
| Bool printVisFxn(Ptr p, CString s); |
| |
| Void visitRope(RopeId rope, RopeVisitor visFxn, Ptr visState); |
| Void visitRope2(RopeId rope, RopeVisitor visFxn, Ptr visState, |
| CString stack[]); |
| |
| typedef Void (*VisitRopeFxn)(RopeId, RopeVisitor, Ptr); |
| typedef Void (*VisitRopeFxn2)(RopeId, RopeVisitor, Ptr, CString[]); |
| |
| config VisitRopeFxn visitRopeFxn = visitRope; |
| |
| config VisitRopeFxn2 visitRopeFxn2 = visitRope2; |
| |
| /*! |
| * ======== xprintf ======== |
| * @param(bufp) address of the output buffer pointer or `NULL` |
| * |
| * If `bufp` is `NULL`, the site's name characters are |
| * output via `{@link System#putch()}`. |
| * |
| * @param(len) maximum number of characters to generate |
| * |
| * If `len` is negative, the number of characters to be |
| * generated is not limited. |
| * |
| * @a(returns) |
| * The return value always reflects the number of characters output, |
| * but it may be less than `len`. |
| */ |
| Int xprintf(Char **bufp, SizeT len, CString fmt, ...); |
| |
| struct Module_State { |
| CPtr charBase; |
| CPtr nodeBase; |
| }; |
| } |