module ti.sdo.ce.utils.syscbuf.SysCBuf

Implementation of ISystemSupport with circular buffer for output

This implementation provides a fully functional implementation of all methods specified by ISystemSupport. [ more ... ]
C synopsis target-domain sourced in ti/sdo/ce/utils/syscbuf/SysCBuf.xdc
#include <ti/sdo/ce/utils/syscbuf/SysCBuf.h>
Functions
Int 
UInt32 
UInt32 
Functions common to all ISystemSupport modules
Void 
Void 
Void 
Void 
Bool 
Functions common to all target modules
Typedefs
typedef Void 
Constants
extern const SizeT 
extern const Bool 
extern const SysCBuf_OutputFxn 
 
DETAILS
This implementation provides a fully functional implementation of all methods specified by ISystemSupport.
This module maintains a circular buffer where data is written on SysCBuf_putch(). When the buffer is full, data is overwritten, and SysCBuf internally keeps track of the number of characters lost due to overwrite. The output buffer can be statically configured or dynamically bound to a buffer using SysCBuf_bind().
When System_flush() is called the characters in the internal buffer are "output" using the user configuratble outputFxn. There is also a user configurable "get" function that can be used to copy out a given amount from the circular buffer.
The difference between SysCBuf and the xdc.runtime.SysMin module, are the following additional features: - SysCBuf_bind() for dynamic binding of the circular output buffer. - SysCBuf_get() for copying a given amount of data from the output buffer to another buffer. - Maintaining the number of characters lost due to overrite, and the number of characters available for reading with SysCBuf_get().
As with all ISystemSupport modules, this module is the back-end for the System module; application code does not directly call these functions.
 
typedef SysCBuf_OutputFxn

Output characters in the specified buffer

C synopsis target-domain
typedef Void (*SysCBuf_OutputFxn)(Char*,UInt);
 
DETAILS
The first parameter is a pointer to a buffer of characters to be output. The second parameter is the number of characters in the buffer to output.
This function may be called with 0 as the second parameter. In this case, the function should simply return.
 
config SysCBuf_bufSize  // module-wide

Size (in MAUs) of the output

C synopsis target-domain
extern const SizeT SysCBuf_bufSize;
 
DETAILS
An internal buffer of this size is allocated. All output is stored in this internal buffer.
If 0 is specified for the size, no buffer is created.
 
config SysCBuf_flushAtExit  // module-wide

Flush the internal buffer during exit or abort

C synopsis target-domain
extern const Bool SysCBuf_flushAtExit;
 
DETAILS
If the application's target is a TI target, the internal buffer is flushed via the HOSTwrite function in the TI C Run Time Support (RTS) library.
If the application's target is not a TI target, the internal buffer is flushed to stdout via fwrite(..., stdout).
Setting this parameter to false reduces the footprint of the application at the expense of not getting output when the application ends via a System_exit(), System_abort(), exit() or abort().
 
config SysCBuf_outputFxn  // module-wide

User suplied character output function

C synopsis target-domain
extern const SysCBuf_OutputFxn SysCBuf_outputFxn;
 
DETAILS
If this parameter is set to a non-null value, the specified function will be called by to output characters buffered within SysCBuf.
For example, if you define a function named myOutputFxn, the following configuration fragment will cause SysCBuf to call myOutputFxn whenever the character buffer is flushed.
      var SysCBuf = xdc.useModule("xdc.runtime.SysCBuf");
      SysCBuf.outputFxn = "&myOutputFxn";
If this parameter is not set, a default function will be used which uses the ANSI C Standard Library function fwrite() (or HOSTwrite in the TI C Run Time Support library) to output accumulated output characters.
SEE
 
SysCBuf_abort()  // module-wide

Backend for System.abort()

C synopsis target-domain
Void SysCBuf_abort(String str);
 
ARGUMENTS
str — message to output just prior to aborting
If non-NULL, this string should be output just prior to terminating.
message to output just prior to aborting
If non-NULL, this string should be output just prior to terminating.
DETAILS
This function is called by System.abort() prior to calling the ANSI C Standard library function abort(). So, to ensure the abort processing of the system's ANSI C Standard library completes, this function should return to its caller.
This abort function writes the string to the internal output buffer and then gives all internal output to the outputFxn function if the flushAtExit configuration parameter is true.
SEE
 
SysCBuf_bind()  // module-wide

Bind the buffer 'buf' of size 'size' bytes to the SysCBuf trace buffer

C synopsis target-domain
Int SysCBuf_bind(Char *buf, UInt32 size);
 
DETAILS
Return 0 if successful, -1 otherwise.
 
SysCBuf_exit()  // module-wide

Backend for System.exit()

C synopsis target-domain
Void SysCBuf_exit(Int stat);
 
ARGUMENTS
stat — status value passed to all "atexit" handlers
This value is passed to all "atexit" handles bound via System.atexit(). If the application exits via the ANSI C Standard exit() function rather than via System_exit(), stat will be equal to System.STATUS_UNKNOWN.
DETAILS
This function is called as part the normal "atexit" processing performed by the ANSI C Standard Library's exit() function; System.exit() directly calls ANSI exit().
This function is called after all "atexit" handlers bound via System.atexit() are run and it is always called while "inside" the the System gate.
To ensure that all exit processing of the system's ANSI C Standard Library completes, this function should return to its caller. Exit handlers bound using the ANSI C Standard Library atexit() function may run before or after this function.
This exit function gives all internal output to the outputFxn function if the flushAtExit configuration parameter is true.
SEE
 
SysCBuf_flush()  // module-wide

Backend for System.flush()

C synopsis target-domain
Void SysCBuf_flush();
 
DETAILS
This function is simply called by System_flush to output any characters buffered by the underlying SystemSupport module to an output device.
The flush writes the contents of the internal character buffer via the outputFxn function.
WARNING
The System gate is used for thread safety during the entire flush operation, so care must be taken when flushing with this ISystemSupport module. Depending on the nature of the System gate, your application's interrupt latency may become a function of the bufSize parameter!
SEE
 
SysCBuf_get()  // module-wide

Copy contents of the trace buffer. Return the number of characters remaining in 'avail'. Return the number of characters lost due to wrapping in 'lost'

C synopsis target-domain
UInt32 SysCBuf_get(Char *buf, UInt32 size, UInt32 *avail, UInt32 *lost);
 
DETAILS
Return the number of characters copied.
 
SysCBuf_getSize()  // module-wide

Return the size of the trace buffer

C synopsis target-domain
UInt32 SysCBuf_getSize();
 
 
SysCBuf_putch()  // module-wide

Backend for System.printf() and System.putch()

C synopsis target-domain
Void SysCBuf_putch(Char ch);
 
ARGUMENTS
ch — character to output
DETAILS
Output a single character. This function is called by System_printf() to write each character of formated output specified by its arguments.
Places the character into an internal buffer. The flush sends the internal buffer to the outputFxn function. The internal buffer is also sent to the SysCBuf_outputFxn function by exit and abort if the flushAtExit configuration parameter is true.
SEE
 
SysCBuf_ready()  // module-wide

Test if character output can proceed

C synopsis target-domain
Bool SysCBuf_ready();
 
DETAILS
This function is called by System prior to performing any character output. If this function returns FALSE, the System functions that would normally call putch() simply return (with an appropriate error status) without ever calling putch.
This function returns true if the internal buffer is non-zero.
SEE
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId SysCBuf_Module_id();
// Get this module's unique id
 
Bool SysCBuf_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle SysCBuf_Module_heap();
// The heap from which this module allocates memory
 
Bool SysCBuf_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 SysCBuf_Module_getMask();
// Returns the diagnostics mask for this module
 
Void SysCBuf_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/sdo/ce/utils/syscbuf/SysCBuf.xdc
var SysCBuf = xdc.useModule('ti.sdo.ce.utils.syscbuf.SysCBuf');
module-wide config parameters
 
 
 
config SysCBuf.bufSize  // module-wide

Size (in MAUs) of the output

XDCscript usage meta-domain
SysCBuf.bufSize = SizeT 0;
 
DETAILS
An internal buffer of this size is allocated. All output is stored in this internal buffer.
If 0 is specified for the size, no buffer is created.
C SYNOPSIS
 
config SysCBuf.flushAtExit  // module-wide

Flush the internal buffer during exit or abort

XDCscript usage meta-domain
SysCBuf.flushAtExit = Bool true;
 
DETAILS
If the application's target is a TI target, the internal buffer is flushed via the HOSTwrite function in the TI C Run Time Support (RTS) library.
If the application's target is not a TI target, the internal buffer is flushed to stdout via fwrite(..., stdout).
Setting this parameter to false reduces the footprint of the application at the expense of not getting output when the application ends via a System_exit(), System_abort(), exit() or abort().
C SYNOPSIS
 
config SysCBuf.outputFxn  // module-wide

User suplied character output function

XDCscript usage meta-domain
SysCBuf.outputFxn = Void(*)(Char*,UInt) null;
 
DETAILS
If this parameter is set to a non-null value, the specified function will be called by to output characters buffered within SysCBuf.
For example, if you define a function named myOutputFxn, the following configuration fragment will cause SysCBuf to call myOutputFxn whenever the character buffer is flushed.
      var SysCBuf = xdc.useModule("xdc.runtime.SysCBuf");
      SysCBuf.outputFxn = "&myOutputFxn";
If this parameter is not set, a default function will be used which uses the ANSI C Standard Library function fwrite() (or HOSTwrite in the TI C Run Time Support library) to output accumulated output characters.
SEE
C SYNOPSIS
 
metaonly config SysCBuf.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
SysCBuf.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.
 
metaonly config SysCBuf.sectionName  // module-wide

Section where the internal character output buffer is placed

XDCscript usage meta-domain
SysCBuf.sectionName = String null;
 
DETAILS
The default is to have no explicit placement; i.e., the linker is free to place it anywhere in the memory map.
generated on Tue, 17 Jan 2012 07:29:09 GMT