module ti.uia.sysbios.LoggerStreamer2

General purpose logger enabling applications to stream data to an instrumentation host

C synopsis
Individual elements
DETAILS
EXAMPLES
Configuration settings
Individual elements

This logger is an enhancement of LoggerStreamer, and is useful in situations where the application wants to manage the buffers used to store and transmit events. This includes managing the sending of the buffers to an instrumentation host (e.g. System Analyzer in CCS). LoggerStreamer2 enables the application to send a stream of packets containing UIA event data to the instrumentation host. [ more ... ]

C synopsis target-domain sourced in ti/uia/sysbios/LoggerStreamer2.xdc

#include <ti/uia/sysbios/LoggerStreamer2.h>

Functions
Void	LoggerStreamer2_construct// Initialize a new instance object inside the provided structure(LoggerStreamer2_Struct structP, const LoggerStreamer2_Params params);
LoggerStreamer2_Handle	LoggerStreamer2_create// Allocate and initialize a new instance object and return its handle(const LoggerStreamer2_Params params, Error_Block eb);
Void	LoggerStreamer2_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(LoggerStreamer2_Handle *handleP);
Void	LoggerStreamer2_destruct// Finalize the instance object inside the provided structure(LoggerStreamer2_Struct *structP);
Void	LoggerStreamer2_flush// Force LoggerStreamer2 to call the exchange function(LoggerStreamer2_Handle handle);
SizeT	LoggerStreamer2_getBufSize// Returns the Log's configured buffer size(LoggerStreamer2_Handle handle);
UArg	LoggerStreamer2_getContext// Returns the Log's context(LoggerStreamer2_Handle handle);
Void	LoggerStreamer2_initBuffer// Initializes the UIA packet header(LoggerStreamer2_Handle handle, Ptr buffer, UInt16 src);
Void	LoggerStreamer2_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(LoggerStreamer2_Params *params);
Bool	LoggerStreamer2_prime// If PrimeFxn is not set the user must call prime with the first buffer(LoggerStreamer2_Handle handle, Ptr buffer);
Void	LoggerStreamer2_setContext// Set the Log's context(LoggerStreamer2_Handle handle, UArg context);
Void	LoggerStreamer2_setModuleIdToRouteToStatusLogger// This function is provided for compatibility with the ILoggerSnapshot interface only and simply returns when called(Types_ModuleId mid);
Functions common to all ILogger modules
Bool	LoggerStreamer2_disable// Disable a log(LoggerStreamer2_Handle handle);
Bool	LoggerStreamer2_enable// Enable a log(LoggerStreamer2_Handle handle);
Void	LoggerStreamer2_write0// Process a log event with 0 arguments and the calling address(LoggerStreamer2_Handle handle, Log_Event evt, Types_ModuleId mid);
Void	LoggerStreamer2_write1// Process a log event with 1 arguments and the calling address(LoggerStreamer2_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1);
Void	LoggerStreamer2_write2// Process a log event with 2 arguments and the calling address(LoggerStreamer2_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
Void	LoggerStreamer2_write4// Process a log event with 4 arguments and the calling address(LoggerStreamer2_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
Void	LoggerStreamer2_write8// Process a log event with 8 arguments and the calling address(LoggerStreamer2_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
Functions common to all IUIATransfer modules
Bool	LoggerStreamer2_getContents// Fills buffer that is passed in with unread data, up to size bytes in length(LoggerStreamer2_Handle handle, Ptr hdrBuf, SizeT size, SizeT *cpSize);
UInt16	LoggerStreamer2_getInstanceId// Returns an ID value that uniquely identifies this instance of the logger(LoggerStreamer2_Handle handle);
SizeT	LoggerStreamer2_getMaxLength// (LoggerStreamer2_Handle handle);
IUIATransfer_TransferType	LoggerStreamer2_getTransferType// (LoggerStreamer2_Handle handle);
Bool	LoggerStreamer2_isEmpty// Returns true if the transfer buffer has no unread data(LoggerStreamer2_Handle handle);
Void	LoggerStreamer2_reset// Reset a log to empty state and enable it(LoggerStreamer2_Handle handle);
Functions common to all IFilterLogger modules
Diags_Mask	LoggerStreamer2_getFilterLevel// Returns the mask of diags categories currently set to the specified level(LoggerStreamer2_Handle handle, Diags_EventLevel level);
Void	LoggerStreamer2_setFilterLevel// Sets the level of detail that instances will log(LoggerStreamer2_Handle handle, Diags_Mask mask, Diags_EventLevel filterLevel);
Functions common to all ILoggerSnapshot modules
Void	LoggerStreamer2_writeMemoryRange// Log an event along with values from a range of memory addresses(LoggerStreamer2_Handle handle, Log_Event evt, Types_ModuleId mid, UInt32 snapshotId, IArg fileName, IArg LineNum, IArg fmt, IArg startAdrs, UInt32 lengthInMAUs);
Functions common to all target instances
	LoggerStreamer2_handle// Convert this instance structure pointer into an instance handle, LoggerStreamer2_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, LoggerStreamer2_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, LoggerStreamer2_Handle_downCast3// conditionally move 3 levels down the inheritance hierarchy; NULL upon failure, LoggerStreamer2_Handle_downCast4// conditionally move 4 levels down the inheritance hierarchy; NULL upon failure, LoggerStreamer2_Handle_label// The label associated with this instance object, LoggerStreamer2_Handle_name// The name of this instance object, LoggerStreamer2_Handle_upCast// unconditionally move one level up the inheritance hierarchy, LoggerStreamer2_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, LoggerStreamer2_Handle_upCast3// unconditionally move 3 levels up the inheritance hierarchy, LoggerStreamer2_Handle_upCast4// unconditionally move 4 levels up the inheritance hierarchy, LoggerStreamer2_Object_count// The number of statically-created instance objects, LoggerStreamer2_Object_first// The handle of the first dynamically-created instance object, or NULL, LoggerStreamer2_Object_get// The handle of the i-th statically-created instance object (array == NULL), LoggerStreamer2_Object_heap// The heap used to allocate dynamically-created instance objects, LoggerStreamer2_Object_next// The handle of the next dynamically-created instance object, or NULL, LoggerStreamer2_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	LoggerStreamer2_Module_getMask// Returns the diagnostics mask for this module, LoggerStreamer2_Module_hasMask// Test whether this module has a diagnostics mask, LoggerStreamer2_Module_heap// The heap from which this module allocates memory, LoggerStreamer2_Module_id// Get this module's unique id, LoggerStreamer2_Module_setMask// Set the diagnostics mask for this module, LoggerStreamer2_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Ptr	(LoggerStreamer2_ExchangeFxnType// Typedef for the exchange function pointer)(LoggerStreamer2_Object,Ptr);
typedef LoggerStreamer2_Object *	LoggerStreamer2_Handle// Client reference to an instance object;
typedef struct	LoggerStreamer2_Object// Opaque internal representation of an instance object LoggerStreamer2_Object;
typedef struct	LoggerStreamer2_Params// Instance config-params structure ...
typedef Ptr	(LoggerStreamer2_PrimeFxnType// Typedef for the exchange function pointer)(LoggerStreamer2_Object);
typedef struct	LoggerStreamer2_Struct// Opaque client structure large enough to hold an instance object LoggerStreamer2_Struct;
typedef enum	LoggerStreamer2_TransferType// ...
typedef enum	LoggerStreamer2_TransportType// Used to specify the type of transport to use ...
Constants
extern const Assert_Id	LoggerStreamer2_A_invalidBuffer// Assert raised when the buffer parameter is NULL;
extern const String	LoggerStreamer2_customTransportType// Custom transport used to send the records to an instrumentation host;
extern const Bool	LoggerStreamer2_filterByLevel// Support filtering of events by event level;
extern const Bool	LoggerStreamer2_isTimestampEnabled// Enable or disable logging the 64b local CPU timestamp at the start of each event;
extern const Diags_Mask	LoggerStreamer2_level1Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL1;
extern const Diags_Mask	LoggerStreamer2_level2Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL2;
extern const Diags_Mask	LoggerStreamer2_level3Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL3;
extern const Diags_Mask	LoggerStreamer2_level4Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL4;
extern const IFilterLogger_Handle	LoggerStreamer2_statusLogger// This configuration option is not supported by this logger and should be left null;
extern const Bool	LoggerStreamer2_supportLoggerDisable// Allow LoggerStreamer2 instances to be enabled/disabled during runtime;
extern const Bool	LoggerStreamer2_testForNullWrPtr// Protect against log calls during the exchange function;

DETAILS

The difference between LoggerStreamer2 and LoggerStreamer, is that each LoggerStreamer2 instance has its own buffer for events logged to that instance. By including the header file, ti/uia/runtime/LogUC.h, you can specify the LoggerStreamer2 instance that you want the event logged to.

The application is responsible for providing the buffers that LoggerStreamer2 loggers use. There are two ways to accomplish this.

Provide a prime callback function via the primeFxn configuration parameter.
Call the prime API once.

The logger stores the events in a UIAPacket_Hdr structure that allows them to be sent directly to System Analyzer (e.g. via UDP), enabling efficient streaming of the data from the target to the host. The first four 32-bit words contain a UIAPacket_Hdr structure. This struct is used by the host (e.g. System Analyzer in CCS) to help decode the data (e.g. endianess, length of data, etc.). The UIAPacket_Hdr structure is initialized via the initBuffer API. All buffers given to LoggerStreamer2 loggers (via priming or exchange) must be initialized via initBuffer.

The size of the buffer includes the UIAPacket_Hdr. LoggerStreamer2 treats the buffer as a UInt32 array, so the application must guarantee the buffers are aligned on word addresses. Alignment on cache line boundaries is recommended for best performance.

When the buffer is filled, LoggerStreamer2 will hand it off to the application using an application-provided exchange function (exchangeFxn). The exchange function must be of type ExchangeFxnType. The exchange function takes the Log instance as a parameter.

The exchange function is called within the context of a Log call, so the exchange function should be designed to be fast. Since the exchange function is called within the context of the Log call, LoggerStreamer2 guarantees no Log records are dropped (i.e. LoggerStreamer2 is lossless).

LoggerStreamer2 was designed to have as minimal impact as possible on an application when calling a Log function. There are several configuration parameters that allow an application to get the optimal performance in exchange for certain restrictions.

Interrupts are disabled during the duration of the log call including when the exchange function is called. LoggerStreamer2 will ignore any log events generated during the exchangeFxn (e.g. posting a semaphore).

NOTE: You can use LoggingSetup, but you will need to set the loggers first. LoggingSetup cannot create LoggerStreamer2 instances, since it does not know what config parameters to use. See example of LoggingSetup use below.

EXAMPLES

The following XDC configuration statements create a logger module, and assign it as the default logger for all modules.

  var Defaults = xdc.useModule('xdc.runtime.Defaults');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var LoggerStreamer2 = xdc.useModule('ti.uia.sysbios.LoggerStreamer2');

  LoggerStreamer2.isTimestampEnabled = true;

  var loggerParams = new LoggerStreamer2.Params();
  loggerParams.primeFxn = '&prime';
  loggerParams.exchangeFxn = '&exchange';
  loggerParams.context = 0;

  Program.global.logger0 = LoggerStreamer2.create(loggerParams);
  Defaults.common$.logger = Program.global.logger0;

  loggerParams.context = 1;
  Program.global.logger1 = LoggerStreamer2.create(loggerParams);

The following C code demonstrates basic prime and exchange functions, and logging to different LoggerStreamer2 instances. A real implementation would send the buffer to an instrumentation host (e.g. System Analyzer in CCS) via a transport such as UDP.

  #include <xdc/std.h>
  #include <xdc/runtime/Diags.h>
  #include <xdc/runtime/Log.h>

  #include <ti/uia/runtime/LogUC.h>

  UInt32 buffer_0[2][BUFSIZE_0];
  UInt32 buffer_1[2][BUFSIZE_1];

  Int main(Int argc, String argv[])
  {
      Log_iwriteUC0(logger0, LoggerStreamer2_L_test);
      Log_iwriteUC1(logger1, LoggerStreamer2_L_test, 0x1000);
  }

  Ptr prime(LoggerStreamer2_Object *log)
  {
      UInt32 id = (UInt32)LoggerStreamer2_getContext(log);

      if (id == 0) {
          LoggerStreamer2_initBuffer(buffer_0[0], 0);
          LoggerStreamer2_initBuffer(buffer_0[1], 0);
          return ((Ptr)buffer_0[0]);
      }
      if (id == 1) {
          LoggerStreamer2_initBuffer(buffer_1[0], 0);
          LoggerStreamer2_initBuffer(buffer_1[1], 0);
          return ((Ptr)(buffer_1[0]));
      }

      return (NULL); // Error
  }

  Ptr exchange(LoggerStreamer2_Object *log, Ptr *full)
  {
      UInt32 id = (UInt32)LoggerStreamer2_getContext(log);

      if (id == 0) {
          count_0++;
          // Ping-pong between the two buffers
          return ((Ptr*)buffer_0[count_0 & 1]);
      }
      if (id == 1) {
          count_1++;
          // Ping-pong between the two buffers
          return ((Ptr*)buffer_1[count_1 & 1]);
      }
      return (NULL);  // Error
  }

The following XDC configuration statements show how to use LoggingSetup with LoggerStreamer2.

  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
  LoggingSetup.eventUploadMode = LoggingSetup.UploadMode_STREAMER2;
  LoggingSetup.mainLogger = Program.global.logger0;
  LoggingSetup.sysbiosLogger = Program.global.logger0;

enum LoggerStreamer2_TransferType