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    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        /* charTab[] and nodeTab[] are the "compressed" representation of
   287         * target strings used to name instances, modules, packages, ...
   288         *
   289         * The predefined node id 0 represents the empty string.
   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         * The module ids are allocated as follows:
   299         * 0x1 - 0x4000     unnamed modules
   300         * 0x4001 - 0x7FFF  registry modules
   301         * 0x8000 - 0xFFFF  named modules
   302         *
   303         * See 'genModNames' in Text.xs
   304         *
   305         * TODO - We may be able to set unnamedModsLastId based on the config
   306         *        to give the Registry more room, but then the Registry id range
   307         *        would not be a constant.
   308         */
   309        config UInt16 unnamedModsLastId = 0x4000;
   310        config UInt16 registryModsLastId = 0x7FFF;
   311    
   312    /* unnamedModCnt can be used to define a constant that allows external
   313     * modules to define their own module IDs that don't conflict with the
   314     * statically configured modules; e.g., the dlog example could use this
   315     */
   316    //    config Int16 unnamedModCnt = 0;
   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     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:17; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   351     */
   352