module 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. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Text.xdc
DETAILS
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 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".
 
typedef Text_Label
C synopsis target-domain
typedef Types_Label Text_Label;
 
 
config Text_isLoaded  // module-wide

Ensure character-strings are loaded in target memory

C synopsis target-domain
extern const Bool Text_isLoaded;
 
DETAILS
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.
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.
      Program.sectMap["xdc.noload"] = new prog.SectionSpec();
      Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
 
config Text_nameEmpty  // module-wide

Default NULL instance name

C synopsis target-domain
extern const String Text_nameEmpty;
 
DETAILS
The name used if the instance's name has been set to NULL.
 
config Text_nameStatic  // module-wide

Default static instance name

C synopsis target-domain
extern const String Text_nameStatic;
 
DETAILS
The name of an instance if the name exists but it's not loaded on the target.
 
config Text_nameUnknown  // module-wide

Default unknowable instance name

C synopsis target-domain
extern const String Text_nameUnknown;
 
DETAILS
The name of an instance if the module's instances are configured to not have names.
 
Text_putLab()  // module-wide

Convert label to an ASCII character sequence

C synopsis target-domain
Int Text_putLab(Types_Label *lab, Char **bufp, Int len);
 
ARGUMENTS
lab — address of the label to interpret
bufp — address of the output buffer pointer or NULL
If bufp is NULL, the label's characters are output via System.putch().
len — maximum number of characters to generate
If len is negative, the number of characters to be generated is not limited.
DETAILS
This function converts a 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 Types.Label for more information.
RETURNS
The return value always reflects the number of characters output, but it may be less than len.
SEE
 
Text_putMod()  // module-wide

Convert module ID to its ASCII name

C synopsis target-domain
Int Text_putMod(Types_ModuleId mid, Char **bufp, Int len);
 
ARGUMENTS
mid — ID of the module
bufp — address of the output buffer pointer or NULL
If bufp is NULL, the module's name characters are output via System.putch().
len — maximum number of characters to generate
If len is negative, the number of characters to be generated is not limited.
DETAILS
This function converts a 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.
RETURNS
The return value always reflects the number of characters output, but it may be less than len.
 
Text_putSite()  // module-wide

Convert call site structure to an ASCII character sequence

C synopsis target-domain
Int Text_putSite(Types_Site *site, Char **bufp, Int len);
 
ARGUMENTS
site — address of the call site structure to interpret
bufp — address of the output buffer pointer or NULL
If bufp is NULL, the site's name characters are output via System.putch().
len — maximum number of characters to generate
If len is negative, the number of characters to be generated is not limited.
DETAILS
This function converts a 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.
RETURNS
The return value always reflects the number of characters output, but it may be less than len.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId Text_Module_id();
// Get this module's unique id
 
Bool Text_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Text_Module_heap();
// The heap from which this module allocates memory
 
Bool Text_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Text_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Text_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in xdc/runtime/Text.xdc
var Text = xdc.useModule('xdc.runtime.Text');
module-wide config parameters
    Text.nameEmpty// Default NULL instance name = String "{empty-instance-name}";
    Text.nameStatic// Default static instance name = String "{static-instance-name}";
    Text.nameUnknown// Default unknowable instance name = String "{unknown-instance-name}";
 
 
 
config Text.isLoaded  // module-wide

Ensure character-strings are loaded in target memory

XDCscript usage meta-domain
Text.isLoaded = Bool true;
 
DETAILS
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.
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.
      Program.sectMap["xdc.noload"] = new prog.SectionSpec();
      Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
C SYNOPSIS
 
config Text.nameEmpty  // module-wide

Default NULL instance name

XDCscript usage meta-domain
Text.nameEmpty = String "{empty-instance-name}";
 
DETAILS
The name used if the instance's name has been set to NULL.
C SYNOPSIS
 
config Text.nameStatic  // module-wide

Default static instance name

XDCscript usage meta-domain
Text.nameStatic = String "{static-instance-name}";
 
DETAILS
The name of an instance if the name exists but it's not loaded on the target.
C SYNOPSIS
 
config Text.nameUnknown  // module-wide

Default unknowable instance name

XDCscript usage meta-domain
Text.nameUnknown = String "{unknown-instance-name}";
 
DETAILS
The name of an instance if the module's instances are configured to not have names.
C SYNOPSIS
 
metaonly config Text.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
Text.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Thu, 01 Mar 2012 16:58:41 GMT