module xdc.runtime.Text
index URL

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
#include <xdc/runtime/Text.h>
Functions
Int 
Text_putLab// Convert label to an ASCII character sequence(Types_Label *lab, Char **bufp, Int len);
Int 
Text_putMod// Convert module ID to its ASCII name(Types_ModuleId mid, Char **bufp, Int len);
Int 
Text_putSite// Convert call site structure to an ASCII character sequence(Types_Site *site, Char **bufp, Int len);
Functions common to all target modules
Text_Module_getMask// Returns the diagnostics mask for this module, Text_Module_hasMask// Test whether this module has a diagnostics mask, Text_Module_heap// The heap from which this module allocates memory, Text_Module_id// Get this module's unique id, Text_Module_setMask// Set the diagnostics mask for this module, Text_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Types_Label 
Text_Label// ;
Constants
extern const Bool 
Text_isLoaded// Ensure character-strings are loaded in target memory;
extern const String 
Text_nameEmpty// Default NULL instance name;
extern const String 
Text_nameStatic// Default static instance name;
extern const String 
Text_nameUnknown// Default unknowable instance name;
 
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
index URL
C synopsis target-domain
typedef Types_Label Text_Label;
 
 
config Text_isLoaded  // module-wide
index URL

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 removed from the application.
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. The same code would print the pointers to the names if this parameter is set to true and 'isLoaded is set to 'false`.
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.
 
config Text_nameEmpty  // module-wide
index URL

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
index URL

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
index URL

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
index URL

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
Types.Label
 
Text_putMod()  // module-wide
index URL

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
index URL

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
index URL

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
 
Configuration settings sourced in xdc/runtime/Text.xdc
var Text = xdc.useModule('xdc.runtime.Text');
module-wide config parameters
    Text.isLoaded// Ensure character-strings are loaded in target memory = Bool true;
    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}";
 
    Text.common$// Common module configuration parameters = Types.Common$ undefined;
 
 
config Text.isLoaded  // module-wide
index URL

Ensure character-strings are loaded in target memory

Configuration settings
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 removed from the application.
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. The same code would print the pointers to the names if this parameter is set to true and 'isLoaded is set to 'false`.
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.
C SYNOPSIS
Text_isLoaded
 
config Text.nameEmpty  // module-wide
index URL

Default NULL instance name

Configuration settings
Text.nameEmpty = String "{empty-instance-name}";
 
DETAILS
The name used if the instance's name has been set to NULL.
C SYNOPSIS
Text_nameEmpty
 
config Text.nameStatic  // module-wide
index URL

Default static instance name

Configuration settings
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
Text_nameStatic
 
config Text.nameUnknown  // module-wide
index URL

Default unknowable instance name

Configuration settings
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
Text_nameUnknown
 
metaonly config Text.common$  // module-wide
index URL

Common module configuration parameters

Configuration settings
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 Fri, 18 Aug 2017 21:17:08 GMT