module ti.uia.events.UIAThreadCtx

index URL

UIA Thread Context Instrumentation

*       C synopsis

*  Individual elements

*       DETAILS

*       EXAMPLES

The UIAThreadCtx module defines context change events and methods that allow tooling to identify thread context switches and to enable thread-aware filtering, trace and analysis. [ more ... ]

C synopsis

target-domain

sourced in ti/uia/events/UIAThreadCtx.h

#include <ti/uia/events/UIAThreadCtx.h>

Functions

macro Int 

Bool 

UInt 

Typedefs

typedef Bool 

Constants

extern const Log_Event 

extern const Log_Event 

extern const Bits16 

extern const Bits16 

 

DETAILS

The UIAThreadCtx module defines context change events and methods that allow tooling to identify thread context switches and to enable thread-aware filtering, trace and analysis.

It inherits IUIACtx, which defines a function pointer to an isLoggingEnabled function which, if configured to point to a function, will evaluate the function prior to logging the context change event and will store the return value of the function in ti_uia_runtime_CtxFilter_gIsLoggingEnabled, which is used to determine whether or not to log events.

The generation of UIAThreadCtx events is also controlled by a module's diagnostics mask, which is described in details in xdc.runtime.Diags. 'UIAThreadCtx` events are generated only when the Diags.ANALYSIS bit is set in the module's diagnostics mask.

The following configuration script demonstrates how the application might control the logging of ANALYSIS events embedded in the Mod module at configuration time. In this case, the configuration script arranges for the Log statements within modules to always generate ANALYSIS events. Without these configuration statements, no ANALYSIS events would be generated by any modules.

EXAMPLES

Example 1: The following example shows how to turn on and off logging of ANALYSIS events from the application source code. See the Diags_setMask() function for details on specifying the control string.

  // turn on logging of ANALYSIS events in the module
  Diags_setMask("my.pkg.Mod+Z");
 
  // turn off logging of ANALYSIS events in the module
  Diags_setMask("my.pkg.Mod-Z");

 

typedef UIAThreadCtx_IsLoggingEnabledFxn

index URL

C synopsis

target-domain

typedef Bool (*UIAThreadCtx_IsLoggingEnabledFxn)(Int);

 

 

config UIAThreadCtx_ENABLEMASK  // module-wide

index URL

Ctx Filter Enable Mask

C synopsis

target-domain

extern const Bits16 UIAThreadCtx_ENABLEMASK;

 

DETAILS

configures which bit of the ti_uia_runtime_CtxFilter_gFlags is assigned to control context aware filtering for frame context changes. Must be configured with a value that is 2**SYNCID.

 

config UIAThreadCtx_SYNCID  // module-wide

index URL

Trace Synchronization ID

C synopsis

target-domain

extern const Bits16 UIAThreadCtx_SYNCID;

 

DETAILS

configures the value to be written into the 4 bit context change type field used by the UIASync trace synchronization

 

config UIAThreadCtx_ctxChg  // module-wide

index URL

threadSwitch Context Change event

C synopsis

target-domain

extern const Log_Event UIAThreadCtx_ctxChg;

 

VALUES

fmt — a constant string that describes the context change and provides a format specifier for newThreadId

newThreadId — an integer which uniquely identifies the new context

DETAILS

Used to log a thread switch Note that the previous thread Id is logged automatically by the ti_uia_runtime_LogCtxChg_thread API. If ti_uia_events_UIAThreadCtx_isLoggingEnabledFxn is not NULL it is called and its return value determines whether logging is enabled or not.

EXAMPLE

The following C code shows how to log a Thread Context Change event that identifies a new thread using a BIOS task switch hook function

  #include <ti/uia/runtime/LogCtxChg.h>
  ...
  Void  tskSwitchHook(Task_Handle hOldTask,Task_Handle hNewTask){
          LogCtxChg_thread("thread: new = 0x%x",(Int)hNewTask);
  }

This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments. The following text is an example of what will be displayed for the event:

  "Thread Ctx Change at Line 123 in demo.c [Prev. thread ID=0x1234] New thread ID=0x1235"
 

 

config UIAThreadCtx_ctxChgWithFunc  // module-wide

index URL

threadSwitch Context Change event with prempted function and resumed function addresses

C synopsis

target-domain

extern const Log_Event UIAThreadCtx_ctxChgWithFunc;

 

VALUES

fmt — a constant string that describes the context change and provides a format specifier for newThreadId

newThreadId — an integer which uniquely identifies the new context

oldFunc — the address of the function that was preempted

newFunc — the address of the function that is being resumed

DETAILS

Used to log a thread switch along with function info (preempted function and new function) Note that the previous thread Id is logged automatically by the ti_uia_runtime_LogCtxChg_threadAndFunc API. If ti_uia_events_UIAThreadCtx_isLoggingEnabledFxn is not NULL it is called and its return value determines whether logging is enabled or not.

EXAMPLE

The following C code shows how to log a Thread Context Change event that identifies a new thread, the preempted function and the preempting function.

  #include <ti/uia/runtime/LogCtxChg.h>
  ...
  LogCtxChg_threadAndFunc("New thread ID=0x%x, oldFunc=0x%x, newFunc=0x%x",(Int)hNewTask, (Int)&oldFunc,(Int)&newFunc);
  

This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments. The following text is an example of what will be displayed for the event:

  "Thread CtxChgWithFunc at Line 123 in demo.c [Prev. thread ID=0x1234] New thread ID=0x1235, oldFunc=0x80001200, newFunc=0x80001080"
 

 

config UIAThreadCtx_isLoggingEnabledFxn  // module-wide

index URL

C synopsis

target-domain

extern const IUIACtx_IsLoggingEnabledFxn UIAThreadCtx_isLoggingEnabledFxn;

 

 

UIAThreadCtx_getCtxId()  // module-wide

index URL

Get the ID for the current thread

C synopsis

target-domain

macro Int UIAThreadCtx_getCtxId();

 

RETURNS

returns the thread ID logged by the last call to UIAThreadCtx_logCtxChg.

 

UIAThreadCtx_isLoggingEnabled()  // module-wide

index URL

returns true if the new context matches the value to enable logging with

C synopsis

target-domain

Bool UIAThreadCtx_isLoggingEnabled(UInt newThreadId);

 

ARGUMENTS

newThreadId — the new thread ID

DETAILS

Default implementation of the IUIACtx_IsLoggingEnabledFxn for user context. To enable context-aware filtering, assign UIAThreadCtx_isLoggingEnabledFxn = &UIAThreadCtx_isLoggingEnabled in the config script or programmatically, or assign your own implementation of this function.

RETURNS

true if logging is enabled

 

UIAThreadCtx_setOldValue()  // module-wide

index URL

sets ti_uia_events_UIAThreadCtx_gLastValue to the new value and returns the old value before it was updated

C synopsis

target-domain

UInt UIAThreadCtx_setOldValue(UInt newValue);

 

ARGUMENTS

newValue — the new value to save in the global variable

(return0 the original value of the global variable before it was updated.

generated on Wed, 14 Mar 2012 16:46:05 GMT