blob: 822b32b6cb09651cf5b1cf3a4b056e4c62dfe281 [file] [log] [blame]
/* --COPYRIGHT--,ESD
* Copyright (c) 2008 Texas Instruments. All rights reserved.
* 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 ========
*
*! Revision History
*! ================
*! 22-May-2009 sasha added isLoaded doc comments
*! 03-Dec-2007 sasha implemented code review changes
*/
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 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 64K characters; each string is represented by
* a 16-bit "rope id".
*/
@Template("./Text.xdt")
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 "".
*/
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.
*/
config String nameUnknown = "{unknown-instance-name}";
/*!
* ======== nameEmpty ========
* Default `NULL` instance name
*
* The name used if the instance's name has been set to `NULL`.
*/
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.
*/
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 separated
* in their own section `xdc.noload`, which is not loaded to the target.
*
* @a(Note)
* For TI and GNU targets, the section `xdc.noload` is not loaded to
* the target, but it can overlay other output sections. If the linker
* allocates `xdc.noload` so that it overlaps the section that contains
* character strings when `isLoaded` is `false`, ROV/RTA functionality
* can be affected. In such a case, an error message is displayed that
* indicates the overlap between `xdc.noload` and another section, whose
* name depends on the target (.`const` on TI targets, `.rodata` on
* GNU targets).
* The user can solve that problem by specifying an address for
* `xdc.noload` to unconfigured memory, and ensure that `.const` and
* `xdc.noload` do not overlap.
* @p(code)
* Program.sectMap["xdc.noload"] = new prog.SectionSpec();
* Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
* @p
*/
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
*/
String ropeText(RopeId rope);
/*!
* ======== matchRope ========
* Compare pattern string `pat` to String identified by `rope`.
* @_nodoc
*
* @a(pre-conditions)
* @p(blist)
* - lenp must be less than or equal to the length of pat
* @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
*/
Int matchRope(RopeId rope, String pat, Int *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
*/
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`.
*/
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`.
*/
Int putSite(Types.Site *site, Char **bufp, Int len);
internal:
struct Node {
Types.RopeId left;
Types.RopeId right;
};
typedef Bool (*RopeVisitor)(Ptr, String);
struct MatchVisState {
String pat;
Int *lenp;
Int res;
};
struct PrintVisState {
Char **bufp;
Int 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}];
config Int16 charCnt = 1;
config Int16 nodeCnt = 1;
/* 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;
function defineRopeCord(text);
function defineRopeNode(left, right);
function fetchAddr(raddr);
function fetchCord(cid);
function fetchId(rid);
function fetchNode(nid);
function genModNames();
function genPkgName();
Bool matchVisFxn(Ptr p, String s);
Bool printVisFxn(Ptr p, String s);
Void visitRope(RopeId rope, Fxn visFxn, Ptr visState);
Void visitRope2(RopeId rope, Fxn visFxn, Ptr visState, String stack[]);
typedef Void (*VisitRopeFxn)(RopeId, Fxn, Ptr);
typedef Void (*VisitRopeFxn2)(RopeId, Fxn, Ptr, String[]);
config VisitRopeFxn visitRopeFxn = visitRope;
config VisitRopeFxn2 visitRopeFxn2 = visitRope2;
Int xprintf(Char **bufp, String fmt, ...);
struct Module_State {
Ptr charBase;
Ptr nodeBase;
};
}