RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
rkhtrc.h File Reference

Platform - independent interface for RKH trace facility. More...

#include "rkhcfg.h"
#include "rkhtype.h"
#include "rkhplat.h"
#include "rkhevt.h"

Go to the source code of this file.

Data Structures

struct  RKH_TRC_FIL_T
 Represents the filter of signal and active object. More...
 

Macros

#define RKH_CFG_TRC_SIZEOF_TE_ID   8
 Specify the size of the trace event identification. The valid values [in bits] are 8, 16 or 32. Default is 8. More...
 
#define RKH_FILTER_ON_GROUP(grp)   rkh_trc_filter_group_(FILTER_ON, (grp), EUNCHANGE)
 Suppress the enabled trace events from a specific group. Use the RKH_TRC_ALL_GROUPS to disable all groups.
 
#define RKH_FILTER_OFF_GROUP(grp)   rkh_trc_filter_group_(FILTER_OFF, (grp), EUNCHANGE)
 Emit the enabled trace events from a specific group. Use the RKH_TRC_ALL_GROUPS to enable all groups.
 
#define RKH_FILTER_ON_EVENT(evt)   rkh_trc_filter_event_(FILTER_ON, (evt))
 Suppress (disable) one trace event. Use the RKH_TRC_ALL_EVENTS to disable all trace events.
 
#define RKH_FILTER_OFF_EVENT(evt)   rkh_trc_filter_event_(FILTER_OFF, (evt))
 Emit (enable) one trace event. Use the RKH_TRC_ALL_EVENTS to enable all trace events. More...
 
#define RKH_FILTER_ON_GROUP_ALL_EVENTS(grp)   rkh_trc_filter_group_(FILTER_ON, (grp), ECHANGE)
 Suppress (disable) all events in a specific group.
 
#define RKH_FILTER_OFF_GROUP_ALL_EVENTS(grp)   rkh_trc_filter_group_(FILTER_OFF, (grp), ECHANGE)
 Emit (enable) all events in a specific group. More...
 
#define RKH_FILTER_ON_SMA(sma)   rkh_trc_symFil(&fsma, RKH_SMA_ACCESS_CONST(sma, prio), FILTER_ON)
 Suppress the enable trace events related to a specified active object.
 
#define RKH_FILTER_ON_ALL_SMA()   rkh_trc_symFil(&fsma, 0, RKH_TRC_SET_ALL(FILTER_ON))
 Suppress all enabled trace events related to specified active object.
 
#define RKH_FILTER_OFF_SMA(sma)   rkh_trc_symFil(&fsma, RKH_SMA_ACCESS_CONST(sma, prio), FILTER_OFF)
 Emmit the enabled trace events related to a specified active object.
 
#define RKH_FILTER_OFF_ALL_SMA()   rkh_trc_symFil(&fsma, 0, RKH_TRC_SET_ALL(FILTER_OFF))
 Emmit all enabled trace events related to specified active object.
 
#define RKH_FILTER_ON_SIGNAL(sig)   rkh_trc_symFil(&fsig, (sig), FILTER_ON)
 Suppress the enabled trace events related to a specified event signal.
 
#define RKH_FILTER_ON_ALL_SIGNALS()   rkh_trc_symFil(&fsig, 0, RKH_TRC_SET_ALL(FILTER_ON))
 Suppress all enabled trace events related to specified event signal.
 
#define RKH_FILTER_OFF_SIGNAL(sig)   rkh_trc_symFil(&fsig, (sig), FILTER_OFF)
 Emmit the enabled trace events related to a specified event signal.
 
#define RKH_FILTER_OFF_ALL_SIGNALS()   rkh_trc_symFil(&fsig, 0, RKH_TRC_SET_ALL(FILTER_OFF))
 Emmit all enabled trace events related to specified event signal.
 
#define RKH_TRC_AO_ISOFF(prio)   && rkh_trc_symFil_isoff(&fsma, (RKH_TRC_FSLOT)(prio))
 Test the state machine application (SMA) filter condition. More...
 
#define RKH_TRC_SIG_ISOFF(sig)   && rkh_trc_symFil_isoff(&fsig, (RKH_TRC_FSLOT)(sig))
 Test the event signal filter condition. More...
 
#define RKH_TRC_MAX_EVENTS   (RKH_MAX_NUM_TE_PER_GROUP * RKH_TRC_MAX_GROUPS)
 
#define RKH_TRC_MAX_SIGNALS   (RKH_CFG_FWK_MAX_SIGNALS / 8)
 The size of trcsigftbl[] (trace signal filter table) depends on RKH_CFG_FWK_MAX_SIGNALS and RKH_CFG_FWK_SIZEOF_EVT (see rkhcfg.h).
 
#define RKH_TOT_NUM_TRC_EVTS
 
#define RKH_TRC_MAX_EVENTS_IN_BYTES   RKH_TOT_NUM_TRC_EVTS
 Defines the size of trace filter table according to RKH_TOT_NUM_TRC_EVTS and RKH_TRC_MAX_EVENTS.
 
#define RKH_USE_TRC_SENDER
 This macro is used to verify the sender object usage on post an event. More...
 
#define RKH_TRC_ALL_GROUPS   RKH_TG_NGROUP
 Emit or suppress tracing for all groups and events.
 
#define RKH_TRC_ALL_EVENTS   RKH_TE_NEVENT
 Emit or suppress all trace events.
 
#define RKH_TRC_SET_ALL(mode_)   ((mode_) | RKH_TRC_ALL_FILTERS)
 Emit or supress tracing for all signal/active objects.
 
#define RKH_XOR   0x20
 
#define RKH_FLG   0x7E
 
#define RKH_ESC   0x7D
 
#define RKH_TRC_CHK()
 Inserts the previously calculated checksum as: checksum = 0 - sum mod-256 -> ~(sum mod-256) + 1.
 
#define RKH_TRC_FLG()   RKH_TRC_U8_RAW(RKH_FLG)
 Inserts directly into the trace stream the flag byte in a raw (without escaped sequence) manner.
 
#define RKH_TRC_BEGIN(eid_, prio_, sig_)
 
#define RKH_TRC_END()
 
#define RKH_TRC_BEGIN_NOCRIT(eid_, prio_, sig_)
 
#define RKH_TRC_BEGIN_WOAO_NOCRIT(eid_, sig_)
 
#define RKH_TRC_BEGIN_WOSIG_NOCRIT(eid_, prio_)
 
#define RKH_TRC_BEGIN_WOAOSIG_NOCRIT(eid_)
 
#define RKH_TRC_END_NOCRIT()
 
#define RKH_TRC_BEGIN_WOFIL(eid_)
 
#define RKH_TRC_END_WOFIL()
 
#define RKH_TRC_BEGIN_WOFIL_NOCRIT(eid_)   rkh_trc_begin(eid_);
 
#define RKH_TRC_END_WOFIL_NOCRIT()   rkh_trc_end(); \
 
#define RKH_TRC_BEGIN_DFT(eid_)
 
#define RKH_TRC_END_DFT()
 
#define RKH_TRC_U8_RAW(d)   rkh_trc_put((d))
 Insert a 1-byte without escaping it.
 
#define RKH_TRC_UI8(d)   rkh_trc_u8((rui8_t)(d))
 Insert a 1-byte data.
 
#define RKH_TRC_UI16(d)   rkh_trc_u16((d))
 Insert a 2-byte data.
 
#define RKH_TRC_UI32(d)   rkh_trc_u32((d))
 Insert a 4-byte data.
 
#define RKH_TRC_STR(s)   rkh_trc_str((s))
 Insert a string.
 
#define RKH_TRC_USR_BEGIN(eid_)
 
#define RKH_TRC_USR_END()
 
#define RKH_TRC_USR_BEGIN_NOCRIT(eid_)
 
#define RKH_TRC_USR_END_NOCRIT()
 
#define RKH_TUSR_I8(w_, d_)
 Output formatted ri8_t to the trace record.
 
#define RKH_TUSR_UI8(w_, d_)
 Output formatted rui8_t to the trace record.
 
#define RKH_TUSR_I16(w_, d_)
 Output formatted ri16_t to the trace record.
 
#define RKH_TUSR_UI16(w_, d_)
 Output formatted rui16_t to the trace record.
 
#define RKH_TUSR_I32(w_, d_)
 Output formatted ri32_t to the trace record.
 
#define RKH_TUSR_UI32(w_, d_)
 Output formatted rui32_t to the trace record.
 
#define RKH_TUSR_X32(w_, d_)
 Output formatted rui32_t to the trace record.
 
#define RKH_TUSR_STR(s_)   rkh_trc_fmt_str((s_))
 Output formatted zero-terminated ASCII string to the trace record.
 
#define RKH_TUSR_MEM(mem_, size_)   rkh_trc_fmt_mem((mem_), (size_))
 Output formatted memory block of up to 255 bytes to the trace record.
 
#define RKH_TUSR_OBJ(obj_)   rkh_trc_fmt_u32((rui8_t)RKH_OBJ_T, (rui32_t)(obj_))
 Output formatted object pointer to the trace record.
 
#define RKH_TUSR_FUN(fun_)   rkh_trc_fmt_u32((rui8_t)RKH_FUN_T, (rui32_t)(fun_))
 Output formatted function pointer to the trace record.
 
#define RKH_TUSR_SIG(sig_)   rkh_trc_fmt_u8((rui8_t)RKH_ESIG_T, (rui8_t)(sig_))
 Output formatted event signal to the trace record.
 
#define RKH_TRC_NSEQ()
 Insert the sequence number byte.
 
#define RKH_TRC_HDR(eid)
 Insert the trace event header in the stream.
 
#define RKH_TRC_SYM(sym)   RKH_TRC_UI32((rui32_t)sym)
 Insert a object address as trace record argument.
 
#define RKH_TRC_SNDR(sym)   RKH_TRC_SYM(sym)
 Insert a sender object address as trace record argument.
 
#define RKH_TRC_FUN(sym)   RKH_TRC_UI32((rui32_t)sym)
 Insert a function address as trace record argument.
 
#define RKH_TRC_NTICK(nt)   RKH_TRC_UI8(nt)
 
#define RKH_TRC_NBLK(nb)   RKH_TRC_UI8(nb)
 
#define RKH_TRC_BSIZE(bs)   RKH_TRC_UI8(bs)
 
#define RKH_TRC_NE(ne)   RKH_TRC_UI8(ne)
 
#define RKH_TRC_SIG(e)   RKH_TRC_UI8(e)
 
#define RKH_TRC_ES(es)   RKH_TRC_UI8(es)
 
#define RKH_TR_MP_INIT(memPool_, nBlocks_, blockSize_)
 Initializes the previously allocated memory pool data strcuture RKH_MP_T. More...
 
#define RKH_TR_MP_GET(memPool_, nFree_, nMin_)
 Get a memory block from one of the previously allocated memory pool. More...
 
#define RKH_TR_MP_PUT(memPool_, nFree_)
 When the application is done with the memory block, it must be returned to the appropiate memory pool. The block must be allocated from the same memory pool to which it is returned. More...
 
#define RKH_TR_RQ_INIT(queue_, actObj_, nElem_)
 Initializes the previously allocated queue data structure RKH_RQ_T. More...
 
#define RKH_TR_RQ_GET(queue_, nElem_)
 Get and remove an element from a queue. More...
 
#define RKH_TR_RQ_FIFO(queue_, nElem_, nMin_)
 Puts an element on a queue in a FIFO manner. The element is queued by reference, not by copy. More...
 
#define RKH_TR_RQ_LIFO(queue_, nElem_, nMin_)
 Puts an element on a queue in a LIFO manner. The element is queued by reference, not by copy. More...
 
#define RKH_TR_RQ_FULL(queue_)
 Queue is full. More...
 
#define RKH_TR_RQ_DPT(queue_)
 Depletes a queue. Empties the contents of the queue and eliminates all stored elements. More...
 
#define RKH_TR_RQ_GET_LAST(queue_)
 Get the last element from the queue. More...
 
#define RKH_TR_SMA_ACT(actObj_, actObjPrio_)
 Initializes and activates a previously created state machine application (SMA) as known as active object. More...
 
#define RKH_TR_SMA_TERM(actObj_, actObjPrio_)
 Terminate a state machine application (SMA) as known as active object. More...
 
#define RKH_TR_SMA_GET(actObj_, evt_, poolID_, refCntr_)
 Get an event from the active object's queue. More...
 
#define RKH_TR_SMA_FIFO(actObj_, evt_, sender_, poolID_, refCntr_)
 Send an event to a state machine application (SMA) as known as active object through a queue using the FIFO policy. A message is a pointer size variable and its use is application specific. More...
 
#define RKH_TR_SMA_LIFO(actObj_, evt_, sender_, poolID_, refCntr_)
 Send an event to a state machine application (SMA) as known as active object through a queue using the LIFO policy. A message is a pointer size variable and its use is application specific. More...
 
#define RKH_TR_SMA_REG(actObj_, prio)
 Registers a state machine application (SMA) as known as active object into the framework, which implies to store a pointer to the SMA in the priority table. More...
 
#define RKH_TR_SMA_UNREG(actObj_, prio)
 Removes the SMA as known as active object from the priority table, and thus from the framework, by simply replacing the link to the SMA being deleted with a NULL pointer. More...
 
#define RKH_TR_SM_INIT(actObj_, initState_)
 Inits a previously created state machine calling its initializing action. More...
 
#define RKH_TR_SM_CLRH(actObj_, history_)
 Erase the history of a state. It can be a shallow or deep history. More...
 
#define RKH_TR_SMA_DCH(actObj_, evt_, state_)
 Executes a state machine in a run-to-completation (RTC) model. More...
 
#define RKH_TR_SM_TRN(actObj_, sourceState_, targetState_)
 Source and target state of the transition. The target could be either basic state, composite state or pseudostate. More...
 
#define RKH_TR_SM_STATE(actObj_, state_)
 Legal, stable and final state of transition. More...
 
#define RKH_TR_SM_ENSTATE(actObj_, state_)
 Entered state. More...
 
#define RKH_TR_SM_EXSTATE(actObj_, state_)
 Exited state. More...
 
#define RKH_TR_SM_NENEX(actObj_, nEnState_, nExState_)
 Number of entry and exit states in transition. More...
 
#define RKH_TR_SM_NTRNACT(actObj_, nta, nts)
 Number of executed actions and segments of the transition. More...
 
#define RKH_TR_SM_TS_STATE(actObj_, state_)
 Destination state or pseudostate of a transition segment. More...
 
#define RKH_TR_SM_EVT_PROC(actObj_)
 The arrived event was succesfully processed and HSM resides in an allowed state. More...
 
#define RKH_TR_SM_EVT_NFOUND(actObj_, evt_)
 The arrived event was't founded in the transition table. More...
 
#define RKH_TR_SM_GRD_FALSE(actObj_)
 The transition was cancelled by guard function. More...
 
#define RKH_TR_SM_CND_NFOUND(actObj_)
 The branch function returned a value not founded in the branch table. More...
 
#define RKH_TR_SM_UNKN_STATE(actObj_)
 Unknown state. More...
 
#define RKH_TR_SM_EX_HLEVEL(actObj_)
 The transition exceeded the allowed hierarchical level. More...
 
#define RKH_TR_SM_EX_TSEG(actObj_)
 The transition exceeded the allowed number of segments within a compound transtion. More...
 
#define RKH_TR_SM_EXE_ACT(actionType_, actObj_, state_, action_)   (void)0
 Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard. More...
 
#define RKH_TR_TMR_INIT(timer_, signal_)
 Initializes the previously allocated timer structure RKH_TMR_T. More...
 
#define RKH_TR_TMR_START(timer_, actObj_, nTicks_, period_)
 Start a timer. More...
 
#define RKH_TR_TMR_STOP(timer_, nTicks_, period_)
 Stops a running timer. More...
 
#define RKH_TR_TMR_TOUT(timer_, signal_, actObj_)
 Timer expired. More...
 
#define RKH_TR_TMR_REM(timer_)
 Removes timer from the active timer list. More...
 
#define RKH_TR_FWK_EN()
 Initializes the RKH framework. More...
 
#define RKH_TR_FWK_EX()
 Exit the RKH framework. More...
 
#define RKH_TR_FWK_EPREG(evtPool_, storageSize_, evtSize_)
 Registers a new event pool into the event pool list. More...
 
#define RKH_TR_FWK_AE(evtSize_, evt_, poolID_, refCnt_)
 Allocates an event from the previously created event pool. More...
 
#define RKH_TR_FWK_GC(evt_, poolID_, refCnt_)
 Attempt to recycle an event. More...
 
#define RKH_TR_FWK_GCR(evt_, poolID_, refCnt_)
 Effective recycling event. More...
 
#define RKH_TR_FWK_DEFER(queue_, evt_)
 Defer an event to a given separate event queue. More...
 
#define RKH_TR_FWK_RCALL(actObj_, evt_)
 Recall a deferred event from a given event queue. More...
 
#define RKH_TR_FWK_OBJ(obj_)
 Entry symbol table for memory object. More...
 
#define RKH_TR_FWK_OBJ_NAME(obj_, name_)
 Entry symbol table for memory object. Very similar to RKH_TR_FWK_OBJ() but the name of object must be explicitely defined. More...
 
#define RKH_TR_FWK_SIG(stateObj_)
 Entry symbol table for event signal. More...
 
#define RKH_TR_FWK_FUN(function_)
 Entry symbol table for function object. More...
 
#define RKH_TR_FWK_EXE_FUN(function_)
 The function was executed. More...
 
#define RKH_TR_FWK_SYNC_EVT(function_, senderObj_, receiverObj_)
 The function was synchronously executed. It is not explicitely used by the RKH, instead it's frequently placed on application source code. More...
 
#define RKH_TR_FWK_TUSR(__e)
 Entry symbol table for user-defined trace events. More...
 
#define RKH_TR_FWK_TCFG(timeStamp_)
 Send trace configuration to Trazer. More...
 
#define RKH_TR_FWK_ASSERT(mod_, ln_)
 Assertion expression was evaluated to false. More...
 
#define RKH_TR_FWK_AO(actObj_)
 Entry symbol table for active object. More...
 
#define RKH_TR_FWK_STATE(actObj_, stateObj_)
 Entry symbol table for state object. More...
 
#define RKH_TR_FWK_PSTATE(actObj_, pseudoStObj_)
 Entry symbol table for pseudostate object. More...
 
#define RKH_TR_FWK_TIMER(timerObj_)
 Entry symbol table for timer object. More...
 
#define RKH_TR_FWK_EPOOL(evtPoolObj_)
 Entry symbol table for event pool object. More...
 
#define RKH_TR_FWK_QUEUE(queueObj_)
 Entry symbol table for queue object. More...
 
#define RKH_MP_START   GRPLSH(RKH_TG_MP)
 Trace event offset. More...
 
#define RKH_RQ_START   GRPLSH(RKH_TG_RQ)
 Trace event offset. More...
 
#define RKH_SMA_START   GRPLSH(RKH_TG_SMA)
 Trace event offset. More...
 
#define RKH_SM_START   GRPLSH(RKH_TG_SM)
 Trace event offset. More...
 
#define RKH_TMR_START   GRPLSH(RKH_TG_TMR)
 Trace event offset. More...
 
#define RKH_FWK_START   GRPLSH(RKH_TG_FWK)
 Trace event offset. More...
 
#define RKH_USR_START   GRPLSH(RKH_TG_USR)
 Trace event offset. More...
 
#define RKH_UT_START   GRPLSH(RKH_TG_UT)
 Trace event offset. More...
 
#define RKH_MP_TTBL_RANGE   1
 
#define RKH_RQ_TTBL_RANGE   1
 
#define RKH_SMA_TTBL_RANGE   1
 
#define RKH_SM_TTBL_RANGE   3
 
#define RKH_TIM_TTBL_RANGE   1
 
#define RKH_FWK_TTBL_RANGE   3
 
#define RKH_USR_TTBL_RANGE   4
 
#define RKH_UT_TTBL_RANGE   2
 

Typedefs

typedef rui8_t RKH_TRC_FSLOT
 This data type defines the size of filter table for AO and signals.
 
typedef rui8_t RKH_TE_ID_T
 Describes a trace event identification (ID). More...
 
typedef rui8_t RKH_TG_T
 Group of events.
 
typedef rui16_t RKH_TS_T
 Defines the size of trace timestamp. More...
 

Enumerations

enum  RKH_TRC_FMT {
  RKH_I8_T,
  RKH_UI8_T,
  RKH_I16_T,
  RKH_UI16_T,
  RKH_I32_T,
  RKH_UI32_T,
  RKH_X32_T,
  RKH_STR_T,
  RKH_MEM_T,
  RKH_OBJ_T,
  RKH_FUN_T,
  RKH_ESIG_T
}
 Enumerates data formats recognized by Trazer. More...
 
enum  RKH_TRC_GROUPS {
  RKH_TG_MP,
  RKH_TG_RQ,
  RKH_TG_SMA,
  RKH_TG_SM,
  RKH_TG_TMR,
  RKH_TG_FWK,
  RKH_TG_USR,
  RKH_TG_UT
}
 RKH group of trace events. More...
 
enum  RKH_TRC_EVENTS {
  RKH_TE_MP_INIT = RKH_MP_START,
  RKH_TE_MP_GET,
  RKH_TE_MP_PUT ,
  RKH_TE_RQ_INIT = RKH_RQ_START,
  RKH_TE_RQ_GET,
  RKH_TE_RQ_FIFO,
  RKH_TE_RQ_LIFO,
  RKH_TE_RQ_FULL,
  RKH_TE_RQ_DPT,
  RKH_TE_RQ_GET_LAST ,
  RKH_TE_SMA_ACT = RKH_SMA_START,
  RKH_TE_SMA_TERM,
  RKH_TE_SMA_GET,
  RKH_TE_SMA_FIFO,
  RKH_TE_SMA_LIFO,
  RKH_TE_SMA_REG,
  RKH_TE_SMA_UNREG,
  RKH_TE_SMA_DCH ,
  RKH_TE_SM_INIT = RKH_SM_START,
  RKH_TE_SM_CLRH,
  RKH_TE_SM_TRN,
  RKH_TE_SM_STATE,
  RKH_TE_SM_ENSTATE,
  RKH_TE_SM_EXSTATE,
  RKH_TE_SM_NENEX,
  RKH_TE_SM_NTRNACT,
  RKH_TE_SM_TS_STATE,
  RKH_TE_SM_EVT_PROC,
  RKH_TE_SM_EVT_NFOUND,
  RKH_TE_SM_GRD_FALSE,
  RKH_TE_SM_CND_NFOUND,
  RKH_TE_SM_UNKN_STATE,
  RKH_TE_SM_EX_HLEVEL,
  RKH_TE_SM_EX_TSEG,
  RKH_TE_SM_EXE_ACT ,
  RKH_TE_TMR_INIT = RKH_TMR_START,
  RKH_TE_TMR_START,
  RKH_TE_TMR_STOP,
  RKH_TE_TMR_TOUT,
  RKH_TE_TMR_REM ,
  RKH_TE_FWK_EN = RKH_FWK_START,
  RKH_TE_FWK_EX,
  RKH_TE_FWK_EPREG,
  RKH_TE_FWK_AE,
  RKH_TE_FWK_GC,
  RKH_TE_FWK_GCR,
  RKH_TE_FWK_DEFER,
  RKH_TE_FWK_RCALL,
  RKH_TE_FWK_OBJ,
  RKH_TE_FWK_SIG,
  RKH_TE_FWK_FUN,
  RKH_TE_FWK_EXE_FUN,
  RKH_TE_FWK_SYNC_EVT,
  RKH_TE_FWK_TUSR,
  RKH_TE_FWK_TCFG,
  RKH_TE_FWK_ASSERT,
  RKH_TE_FWK_AO,
  RKH_TE_FWK_STATE,
  RKH_TE_FWK_PSTATE,
  RKH_TE_FWK_TIMER,
  RKH_TE_FWK_EPOOL,
  RKH_TE_FWK_QUEUE
}
 RKH trace events. More...
 
enum  RKH_SUBTE_SM_EXE_ACT {
  RKH_SUBTE_SM_EXE_ACT_EFF,
  RKH_SUBTE_SM_EXE_ACT_EN,
  RKH_SUBTE_SM_EXE_ACT_EX,
  RKH_SUBTE_SM_EXE_ACT_INI,
  RKH_SUBTE_SM_EXE_ACT_PP,
  RKH_SUBTE_SM_EXE_ACT_GRD
}
 Sub-event of RKH_TE_SM_EXE_ACT event. More...
 

Functions

void rkh_trc_init (void)
 Initializes the RKH's trace record service. More...
 
rui8_t * rkh_trc_get (void)
 Retrieves a pointer to oldest stored byte in the trace stream. Frequently, this function is used by the called trace analyzer. More...
 
rui8_t * rkh_trc_get_block (TRCQTY_T *nget)
 Retrieves a pointer to a contiguous block of data from the trace stream. More...
 
void rkh_trc_put (rui8_t b)
 Put a data byte into the trace stream. More...
 
void rkh_trc_filter_group_ (rui8_t ctrl, RKH_TG_T grp, rui8_t mode)
 Emit or suppress all trace events from a specific group. More...
 
void rkh_trc_filter_event_ (rui8_t ctrl, RKH_TE_ID_T evt)
 Emit or suppress a specific event. More...
 
rbool_t rkh_trc_isoff_ (RKH_TE_ID_T e)
 Test the group and event filter condition. More...
 
void rkh_trc_symFil (const RKH_TRC_FIL_T *filter, RKH_TRC_FSLOT slot, rui8_t mode)
 Emmit or suppresse trace events related to a particular active object or event signal. More...
 
rbool_t rkh_trc_symFil_isoff (const RKH_TRC_FIL_T *filter, RKH_TRC_FSLOT slot)
 Test the active objecto or signal filter condition. More...
 
void rkh_trc_begin (RKH_TE_ID_T eid)
 Store the trace record header in the stream. More...
 
void rkh_trc_end (void)
 Terminate the recorded trace event. More...
 
void rkh_trc_clear_chk (void)
 Clear to zero the trace record checksum. More...
 
void rkh_trc_u8 (rui8_t d)
 Store a 8-bit data into the current trace event buffer without format information. More...
 
void rkh_trc_u16 (rui16_t d)
 Store a 16-bit data into the current trace event buffer without format information. More...
 
void rkh_trc_u32 (rui32_t d)
 Store a 32-bit data into the current trace event buffer without format information. More...
 
void rkh_trc_str (const char *s)
 Store a string terminated in '\0' into the current trace event buffer without format information. More...
 
void rkh_trc_obj (RKH_TE_ID_T tre, rui8_t *obj, const char *obj_name)
 Output object symbol record. More...
 
void rkh_trc_sig (RKH_SIG_T sig, const char *sig_name)
 Output signal symbol record. More...
 
void rkh_trc_ao (struct RKH_SMA_T *ao)
 Output active object (AO) symbol record. More...
 
void rkh_trc_state (struct RKH_SMA_T *ao, rui8_t *state)
 Output state symbol record. More...
 
void rkh_trc_fmt_u8 (rui8_t fmt, rui8_t d)
 Store a 8-bit data into the current trace event buffer with format information. More...
 
void rkh_trc_fmt_u16 (rui8_t fmt, rui16_t d)
 Store a 16-bit data into the current trace event buffer with format information. More...
 
void rkh_trc_fmt_u32 (rui8_t fmt, rui32_t d)
 Store a 32-bit data into the current trace event buffer with format information. More...
 
void rkh_trc_fmt_str (const char *s)
 Store a string terminated in '\0' into the current trace event buffer with format information. More...
 
void rkh_trc_fmt_mem (rui8_t const *mem, rui8_t size)
 Output memory block of up to 255-bytes with format information. More...
 
void rkh_trc_filter_get (RKH_FilterTbl *outFilterTbl)
 Get a memory reference to every trace filter table. More...
 

Detailed Description

Platform - independent interface for RKH trace facility.

Definition in file rkhtrc.h.

Macro Definition Documentation

#define RKH_CFG_TRC_SIZEOF_TE_ID   8

Specify the size of the trace event identification. The valid values [in bits] are 8, 16 or 32. Default is 8.

See also
RKH_TE_ID_T data type.
Note
In the future releases, it should be defined in the configuration file of the RKH framework.

Definition at line 82 of file rkhtrc.h.

#define RKH_TRC_AO_ISOFF (   prio)    && rkh_trc_symFil_isoff(&fsma, (RKH_TRC_FSLOT)(prio))

Test the state machine application (SMA) filter condition.

Parameters
[in]prioSMA priority.
Returns
'1' (RKH_TRUE) if the SMA is not filtered, otherwise '0' (RKH_FALSE).
Note
This macro is internal to RKH and the user application should not call it.

Definition at line 306 of file rkhtrc.h.

#define RKH_TRC_SIG_ISOFF (   sig)    && rkh_trc_symFil_isoff(&fsig, (RKH_TRC_FSLOT)(sig))

Test the event signal filter condition.

Parameters
[in]sigevent signal.
Returns
'1' (RKH_TRUE) if the signal is not filtered, otherwise '0' (RKH_FALSE).
Note
This macro is internal to RKH and the user application should not call it.

Definition at line 327 of file rkhtrc.h.

#define RKH_TRC_MAX_EVENTS   (RKH_MAX_NUM_TE_PER_GROUP * RKH_TRC_MAX_GROUPS)

Specify the maximum number of trace events, this number is direclty related with the RKH_TRC_EVENTS enumeration. The smaller this number, the lower the RAM consumption. See trceftbl table.

Definition at line 361 of file rkhtrc.h.

#define RKH_MP_START   GRPLSH(RKH_TG_MP)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 403 of file rkhtrc.h.

#define RKH_RQ_START   GRPLSH(RKH_TG_RQ)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 404 of file rkhtrc.h.

#define RKH_SMA_START   GRPLSH(RKH_TG_SMA)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 405 of file rkhtrc.h.

#define RKH_SM_START   GRPLSH(RKH_TG_SM)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 406 of file rkhtrc.h.

#define RKH_TMR_START   GRPLSH(RKH_TG_TMR)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 407 of file rkhtrc.h.

#define RKH_FWK_START   GRPLSH(RKH_TG_FWK)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 408 of file rkhtrc.h.

#define RKH_USR_START   GRPLSH(RKH_TG_USR)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 409 of file rkhtrc.h.

#define RKH_UT_START   GRPLSH(RKH_TG_UT)

Trace event offset.

The trace event ID is arranged as:

event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
The lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Definition at line 410 of file rkhtrc.h.

#define RKH_MP_TTBL_RANGE   1

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 419 of file rkhtrc.h.

#define RKH_RQ_TTBL_RANGE   1

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 420 of file rkhtrc.h.

#define RKH_SMA_TTBL_RANGE   1

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 421 of file rkhtrc.h.

#define RKH_SM_TTBL_RANGE   3

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 422 of file rkhtrc.h.

#define RKH_TIM_TTBL_RANGE   1

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 423 of file rkhtrc.h.

#define RKH_FWK_TTBL_RANGE   3

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 424 of file rkhtrc.h.

#define RKH_USR_TTBL_RANGE   4

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 425 of file rkhtrc.h.

#define RKH_UT_TTBL_RANGE   2

Max. number of used trace events in a particular group in octets, thus the desired value must be divided by 8 (1 -> 8 events).

Note
Must be less than or equal to RKH_MAX_NUM_TE_PER_GROUP/8.

Definition at line 426 of file rkhtrc.h.

#define RKH_TOT_NUM_TRC_EVTS
Value:
#define RKH_RQ_TTBL_RANGE
Definition: rkhtrc.h:420
#define RKH_SMA_TTBL_RANGE
Definition: rkhtrc.h:421
#define RKH_UT_TTBL_RANGE
Definition: rkhtrc.h:426
#define RKH_USR_TTBL_RANGE
Definition: rkhtrc.h:425
#define RKH_SM_TTBL_RANGE
Definition: rkhtrc.h:422
#define RKH_TIM_TTBL_RANGE
Definition: rkhtrc.h:423
#define RKH_MP_TTBL_RANGE
Definition: rkhtrc.h:419
#define RKH_FWK_TTBL_RANGE
Definition: rkhtrc.h:424

Defines the total number of trace events.

Definition at line 432 of file rkhtrc.h.

#define RKH_USE_TRC_SENDER

This macro is used to verify the sender object usage on post an event.

The macros RKH_TIM_TICK(), RKH_SMA_POST_FIFO(), and RKH_SMA_POST_LIFO() takes an additional argument sender, which is a pointer to the sender object. This argument is actually only used when software tracing is enabled (macro RKH_USE_TRC_SENDER is defined). When software tracing is disabled, the macros RKH_TIM_TICK(), RKH_SMA_POST_FIFO(), and RKH_SMA_POST_LIFO() calls rkh_tmr_tick(), rkh_sma_post_fifo(), and rkh_sma_post_lifo() respectively without any arguments, so the overhead of passing this extra argument is entirely avoided.

Definition at line 493 of file rkhtrc.h.

#define RKH_XOR   0x20

x-ored byte for stuffing a single byte

Definition at line 519 of file rkhtrc.h.

#define RKH_FLG   0x7E

flag byte, used as a trace event delimiter

Definition at line 522 of file rkhtrc.h.

#define RKH_ESC   0x7D

escape byte stuffing a single byte

Definition at line 525 of file rkhtrc.h.

#define RKH_TRC_BEGIN (   eid_,
  prio_,
  sig_ 
)
Value:
if (rkh_trc_isoff_(eid_) \
{ \
RKH_ENTER_CRITICAL_(); \
#define RKH_TRC_AO_ISOFF(prio)
Test the state machine application (SMA) filter condition.
Definition: rkhtrc.h:306
#define RKH_TRC_SIG_ISOFF(sig)
Test the event signal filter condition.
Definition: rkhtrc.h:327
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.
rbool_t rkh_trc_isoff_(RKH_TE_ID_T e)
Test the group and event filter condition.

Each trace event always begins with the macro RKH_TRC_BEGIN() and ends with the matching macro RKH_TRC_END(). These macros are not terminated with the semicolon. This pair of macros locks interrupts at the beginning and unlocks at the end of each record.

Parameters
[in]eid_is the trace event ID (RKH_TRC_EVENTS).
[in]prio_priority of active object.
[in]sig_signal.
Note
Both arguments are used in the on/off filter.
The runtime filter is optional and could be enabled or disabled with the RKH_CFG_TRC_RTFIL_EN in the rkhcfg.h file.
This macro always invokes the rkh_trc_begin() function.

Definition at line 568 of file rkhtrc.h.

#define RKH_TRC_END ( )
Value:
RKH_EXIT_CRITICAL_(); \
}
void rkh_trc_end(void)
Terminate the recorded trace event.

Each trace event always begins with the macro RKH_TRC_BEGIN() and ends with the matching macro RKH_TRC_END(). These macros are not terminated with the semicolon. This pair of macros locks interrupts at the beginning and unlocks at the end of each record.

Note
This macro always invokes the rkh_trc_end() function.

Definition at line 606 of file rkhtrc.h.

#define RKH_TRC_BEGIN_NOCRIT (   eid_,
  prio_,
  sig_ 
)
Value:
if (rkh_trc_isoff_(eid_) \
{ \
#define RKH_TRC_AO_ISOFF(prio)
Test the state machine application (SMA) filter condition.
Definition: rkhtrc.h:306
#define RKH_TRC_SIG_ISOFF(sig)
Test the event signal filter condition.
Definition: rkhtrc.h:327
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.
rbool_t rkh_trc_isoff_(RKH_TE_ID_T e)
Test the group and event filter condition.

Idem RKH_TRC_BEGIN() macro but without entering critical section.

Parameters
[in]eid_is the trace event ID (RKH_TRC_EVENTS).
[in]prio_priority of active object.
[in]sig_signal.

Definition at line 618 of file rkhtrc.h.

#define RKH_TRC_BEGIN_WOAO_NOCRIT (   eid_,
  sig_ 
)
Value:
if (rkh_trc_isoff_(eid_) \
{ \
#define RKH_TRC_SIG_ISOFF(sig)
Test the event signal filter condition.
Definition: rkhtrc.h:327
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.
rbool_t rkh_trc_isoff_(RKH_TE_ID_T e)
Test the group and event filter condition.

Idem RKH_TRC_BEGIN_WOAO() macro but without entering critical section.

Parameters
[in]eid_is the trace event ID (RKH_TRC_EVENTS).
[in]sig_signal.

Definition at line 632 of file rkhtrc.h.

#define RKH_TRC_BEGIN_WOSIG_NOCRIT (   eid_,
  prio_ 
)
Value:
if (rkh_trc_isoff_(eid_) \
RKH_TRC_AO_ISOFF(prio_)) \
{ \
#define RKH_TRC_AO_ISOFF(prio)
Test the state machine application (SMA) filter condition.
Definition: rkhtrc.h:306
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.
rbool_t rkh_trc_isoff_(RKH_TE_ID_T e)
Test the group and event filter condition.

Idem RKH_TRC_BEGIN_WOSIG() macro but without entering critical section.

Parameters
[in]eid_is the trace event ID (RKH_TRC_EVENTS).
[in]prio_priority of active object.

Definition at line 645 of file rkhtrc.h.

#define RKH_TRC_BEGIN_WOAOSIG_NOCRIT (   eid_)
Value:
if (rkh_trc_isoff_(eid_)) \
{ \
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.
rbool_t rkh_trc_isoff_(RKH_TE_ID_T e)
Test the group and event filter condition.

Idem RKH_TRC_BEGIN_WOAOSIG() macro but without entering critical section.

Parameters
[in]eid_is the trace event ID (RKH_TRC_EVENTS).

Definition at line 657 of file rkhtrc.h.

#define RKH_TRC_END_NOCRIT ( )
Value:
}
void rkh_trc_end(void)
Terminate the recorded trace event.

Idem RKH_TRC_EXIT() macro but without exiting critical section.

Definition at line 665 of file rkhtrc.h.

#define RKH_TRC_BEGIN_WOFIL (   eid_)
Value:
RKH_SR_ALLOC(); \
RKH_ENTER_CRITICAL_(); \
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.

Idem RKH_TRC_BEGIN() macro but use it for trace events that are independent of any runtime filter.

Definition at line 709 of file rkhtrc.h.

#define RKH_TRC_END_WOFIL ( )
Value:
RKH_EXIT_CRITICAL_();
void rkh_trc_end(void)
Terminate the recorded trace event.

Idem RKH_TRC_END() macro but use it for trace events that are independent of any runtime filter.

Definition at line 718 of file rkhtrc.h.

#define RKH_TRC_BEGIN_WOFIL_NOCRIT (   eid_)    rkh_trc_begin(eid_);

Idem RKH_TRC_BEGIN_WOFIL() macro but without entering critical section.

Definition at line 725 of file rkhtrc.h.

#define RKH_TRC_END_WOFIL_NOCRIT ( )    rkh_trc_end(); \

Idem RKH_TRC_END_WOFIL_NOCRIT() macro but without entering critical section.

Definition at line 732 of file rkhtrc.h.

#define RKH_TRC_BEGIN_DFT (   eid_)
Value:
RKH_SR_ALLOC(); \
RKH_ENTER_CRITICAL_(); \
RKH_TRC_TE_ID(eid_);
void rkh_trc_clear_chk(void)
Clear to zero the trace record checksum.

Idem RKH_TRC_BEGIN() macro with default configuration, i.e. without timestamp, and number of sequence, but with 8-bit checksum.

Definition at line 739 of file rkhtrc.h.

#define RKH_TRC_END_DFT ( )
Value:
RKH_EXIT_CRITICAL_();
void rkh_trc_end(void)
Terminate the recorded trace event.

Idem RKH_TRC_END() macro but use it for trace events that are independent of any runtime filter.

Definition at line 749 of file rkhtrc.h.

#define RKH_TRC_USR_BEGIN (   eid_)
Value:
RKH_SR_ALLOC(); \
if (rkh_trc_isoff_(eid_)) \
{ \
RKH_ENTER_CRITICAL_(); \
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.
rbool_t rkh_trc_isoff_(RKH_TE_ID_T e)
Test the group and event filter condition.

Idem RKH_TRC_BEGIN() macro but use it for user trace events.

Definition at line 792 of file rkhtrc.h.

#define RKH_TRC_USR_END ( )
Value:
RKH_EXIT_CRITICAL_(); \
}
void rkh_trc_end(void)
Terminate the recorded trace event.

Idem RKH_TRC_END() macro but use it for user trace events.

Definition at line 802 of file rkhtrc.h.

#define RKH_TRC_USR_BEGIN_NOCRIT (   eid_)
Value:
if (rkh_trc_isoff_(eid_)) \
{ \
void rkh_trc_begin(RKH_TE_ID_T eid)
Store the trace record header in the stream.
rbool_t rkh_trc_isoff_(RKH_TE_ID_T e)
Test the group and event filter condition.

Idem RKH_TRC_USR_BEGIN() macro but without entering critical section.

Definition at line 810 of file rkhtrc.h.

#define RKH_TRC_USR_END_NOCRIT ( )
Value:
}
void rkh_trc_end(void)
Terminate the recorded trace event.

Idem RKH_TRC_USR_END() macro but without exiting critical section.

Definition at line 818 of file rkhtrc.h.

#define RKH_TRC_NTICK (   nt)    RKH_TRC_UI8(nt)

Insert a ntick value as trace record argument.

Definition at line 1026 of file rkhtrc.h.

#define RKH_TRC_NBLK (   nb)    RKH_TRC_UI8(nb)

Insert a nblock value as trace record argument.

Definition at line 1043 of file rkhtrc.h.

#define RKH_TRC_BSIZE (   bs)    RKH_TRC_UI8(bs)

Insert the block size value as trace record argument.

Definition at line 1084 of file rkhtrc.h.

#define RKH_TRC_NE (   ne)    RKH_TRC_UI8(ne)

Insert a nelem value as trace record argument.

Definition at line 1101 of file rkhtrc.h.

#define RKH_TRC_SIG (   e)    RKH_TRC_UI8(e)

Insert a signal number as trace record argument.

Definition at line 1142 of file rkhtrc.h.

#define RKH_TRC_ES (   es)    RKH_TRC_UI8(es)

Insert a event size value as trace record argument.

Definition at line 1159 of file rkhtrc.h.

Typedef Documentation

typedef rui8_t RKH_TE_ID_T

Describes a trace event identification (ID).

The trace event ID is arranged as: event number = | G | G | G | E | E | E | E | E |
G's: group number.
E's: event's group.
Where the lower 5 bits (E's) of the event ID are used to determine the trace event, while the next three most significant bits (G's) are used to determine the corresponding group. Therefore, is able to define 8 groups and 32 events per group.

Trace events are binary data consisting of a trace header and its associated event data. Every trace header is made up of a ID and a timestamp. The number of bytes used by the timestamp is configurable by RKH_TRC_SIZEOF_TS (1, 2 or 4 bytes). After the timestamp follows the event data. The content and size of the data portion of a trace event is determined by the event ID. All types of events are stored in a single ring buffer, called trace stream, using a variable event size. In this manner the recorder always holds the most recent history. On the other hand, all data are stored in little-endian order (least significant byte first). Also, they are stored into the trace stream 1 byte at a time, thus avoiding any potential data misalignment problems.

Note
The timestamp is optional, thus it could be eliminated from the trace event in compile-time with RKH_CFG_TRC_TSTAMP_EN = 0.

Definition at line 3060 of file rkhtrc.h.

typedef rui16_t RKH_TS_T

Defines the size of trace timestamp.

The valid values [in bits] are 8, 16 or 32. Default is 16. This type is configurable via the RKH_CFGPORT_TRC_SIZEOF_TSTAMP preprocessor option.

Definition at line 3446 of file rkhtrc.h.

Enumeration Type Documentation

Enumerates data formats recognized by Trazer.

Trazer uses this enumeration is used only internally for the formatted user data elements.

Enumerator
RKH_I8_T 

signed 8-bit integer format

RKH_UI8_T 

unsigned 8-bit integer format

RKH_I16_T 

signed 16-bit integer format

RKH_UI16_T 

unsigned 16-bit integer format

RKH_I32_T 

signed 32-bit integer format

RKH_UI32_T 

unsigned 16-bit integer format

RKH_X32_T 

signed 16-bit integer in hex format

RKH_STR_T 

zero-terminated ASCII string format

RKH_MEM_T 

up to 255-bytes memory block format

RKH_OBJ_T 

object pointer format

RKH_FUN_T 

function pointer format

RKH_ESIG_T 

event signal format

Definition at line 2957 of file rkhtrc.h.

RKH group of trace events.

Enumerator
RKH_TG_MP 

Memory Pool group (MP)

RKH_TG_RQ 

Reference Queue group (RQ)

RKH_TG_SMA 

State Machine Application group (SMA)

RKH_TG_SM 

State Machine group (SM)

RKH_TG_TMR 

Timer group (TIM)

RKH_TG_FWK 

Framework RKH group (FWK)

RKH_TG_USR 

User group (USR)

RKH_TG_UT 

Unit test harness group (UT)

Definition at line 3079 of file rkhtrc.h.

RKH trace events.

RKH trace event structure

(1) RKH_TRC_BEGIN(trc_evt, ao_prio, signal) \
(2) RKH_TRC_ARG0(arg0); \
(3) RKH_TRC_ARG1(arg1); \
(4) RKH_TRC_....(...); \
  • (1,5) Each trace event always begins with the macro RKH_TRC_BEGIN() and ends with the matching macro RKH_TRC_END(). These macros are not terminated with the semicolon. The record-begin macro RKH_TRC_BEGIN() takes three arguments. The first argument 'trc_evt' is the trace event ID, the second argument 'ao_prio' is the active object priority, and the third argument 'signal' is the event signal number. These arguments are used in the on/off filters. The runtime filter is optional and could be enabled or disabled with the RKH_CFG_TRC_RTFIL_EN in the rkhcfg.h file. This pair of macros locks interrupts at the beginning and unlocks at the end of each record.
  • (2-4) Sandwiched between these two macros are the argument-generating macros that actually insert individual event argument elements into the trace stream.

Example:

#define RKH_TR_RQ_INIT(q, ao, nelem) \
RKH_TRC_BEGIN_WOAOSIG(RKH_TE_RQ_INITS) \
RKH_TRC_SYM(q); \
RKH_TRC_SYM(ao); \
RKH_TRC_NE(nelem); \
RKH_TRC_END()
#define RKH_TR_SMA_FIFO(ao, ev, snr, pid, rc) \
RKH_TRC_BEGIN(RKH_TE_SMA_FIFO, \
RKH_SMA_ACCESS_CONST(actObj_, prio), \
ev->e) \
RKH_TRC_SYM(ao); \
RKH_TRC_SIG(ev->e); \
RKH_TRC_SNDR(snr); \
RKH_TRC_UI8(pid); \
RKH_TRC_UI8(rc); \
RKH_TRC_END()

Each trace event and its arguments are placed in the trace stream like a simple data protocol frame. The protocol has been specifically designed to simplify the data management overhead in the target yet allow detection of any data dropouts due to the trace buffer overruns. The protocol has not only provisions for detecting gaps in the data and other errors but allows for instantaneous resynchronization after any error, to minimize data loss. [MS]

Frame

| ... |
(1) | event ID | 1,2,4-byte
(2) | sequence number | 1-byte
(3) | timestamp | 2,4-bytes
(4) | args | n-byte
(5) | checksum | 1-byte
(6) | flag | 1-byte
| ... |
  • (1) Each frame starts with the trace event ID bytes, which is one of the predefined RKH records or an application-specific record.
  • (2) Following the sequence number is the sequence number byte. The target component increments this number for every frame inserted into the stream. The sequence number allows the trazer tool to detect any data discontinuities. If the RKH_CFG_TRC_NSEQ_EN is set to 1 then RKH will add to the trace record the sequence number.
  • (3) Following the sequence number is the timestamp. The number of bytes used by the timestamp is configurable by the macro RKH_CFGPORT_TRC_SIZEOF_TSTAMP. If the RKH_CFG_TRC_TSTAMP_EN is set to 1 then RKH will add to the trace record the timestamp field.
  • (4) Following the timestamp is zero or more data bytes for args.
  • (5) Following the data is the checksum byte. The checksum is computed over the sequence number, the trace event ID, and all the data bytes. If the RKH_CFG_TRC_CHK_EN is set to 1 then RKH will add to the trace record a checksum byte.
  • (6) Following the checksum is the flag byte, which delimits the frame. The flag is the 0x7E. Only one flag is inserted between frames.

To avoid confusing unintentional flag bytes that can naturally occur in the data stream with an intentionally sent flag, the protocol uses a technique known as byte stuffing or escaping to make the flag bytes transparent during the transmission. Whenever the transmitter encounters a flag byte in the data, it inserts a 2-byte escape sequence to the output stream. The first byte is the escape byte, defined as binary 0x7D. The second byte is the original byte XOR-ed with 0x20. The transmitter computes the checksum over the sequence number, the trace event ID, and all data bytes before performing any byte stuffing.

User trace events

The user application could defined its own trace events to be placed at anywhere in the application level. Allowing to generate tracing information from the application-level code like a "printf" but with much less overhead.

(1) RKH_TRC_USR_BEGIN(MY_TRACE) \
(2) RKH_TRC_ARG0(arg0); \
(3) RKH_TRC_ARG1(arg1); \
(4) RKH_TRC_....(...); \
  • (1,5) Each trace event always begins with the macro RKH_TRC_USR_BEGIN() and ends with the matching macro RKH_TRC_USR_END(). The record-begin macro RKH_TRC_USR_BEGIN() takes one argument, 'eid_' is the user trace event ID, from the RKH_TE_USER value. This pair of macros locks interrupts at the beginning and unlocks at the end of each record.
  • (2-4) Sandwiched between these two macros are the argument-generating macros that actually insert individual event argument elements into the trace stream.

Argument-generating macros for building user trace events:

  • RKH_TUSR_STR() Output formatted zero-terminated ASCII string to the trace record.
  • RKH_TUSR_MEM() Output formatted memory block of up to 255 bytes to the trace record.
  • RKH_TUSR_FUN() Output formatted function pointer to the trace record.

Example:

enum
{
LOWPWR_USR_TRACE = RKH_TE_USER,
DISCONNECTED_USR_TRACE
...
};
void
some_function(...)
{
rui8_t d1 = 255;
rui16_t d2 = 65535;
rui32_t d3 = 65535;
char *str = "hello";
RKH_TRC_USR_BEGIN(LOWPWR_USR_TRACE)
RKH_TUSR_I8(3, d1);
RKH_TUSR_UI8(3, d1);
RKH_TUSR_I16(4, d2);
RKH_TUSR_UI16(4, d2);
RKH_TUSR_I32(5, d3);
RKH_TUSR_UI32(5, d3);
RKH_TUSR_X32(4, d3);
RKH_TUSR_MEM((rui8_t*)&d3, sizeof(rui32_t));
RKH_TUSR_FUN(main);
RKH_TUSR_SIG(ZERO);
}
See also
RKH_TRC_HDR(), RKH_TRC_END(), RKH_TRC_CHK().
Enumerator
RKH_TE_MP_INIT 

Initializes the previously allocated memory pool data strcuture RKH_MP_T.

RKH_TE_MP_GET 

Get a memory block from one of the previously allocated memory pool.

RKH_TE_MP_PUT 

When the application is done with the memory block, it must be returned to the appropiate memory pool. The block must be allocated from the same memory pool to which it is returned.

RKH_TE_RQ_INIT 

Initializes the previously allocated queue data structure RKH_RQ_T.

RKH_TE_RQ_GET 

Get and remove an element from a queue.

RKH_TE_RQ_FIFO 

Puts an element on a queue in a FIFO manner. The element is queued by reference, not by copy.

RKH_TE_RQ_LIFO 

Puts an element on a queue in a LIFO manner. The element is queued by reference, not by copy.

RKH_TE_RQ_FULL 

Queue is full.

RKH_TE_RQ_DPT 

Depletes a queue. Empties the contents of the queue and eliminates all stored elements.

RKH_TE_RQ_GET_LAST 

Get the last element from the queue.

RKH_TE_SMA_ACT 

Initializes and activates a previously created state machine application (SMA) as known as active object.

RKH_TE_SMA_TERM 

Terminate a state machine application (SMA) as known as active object.

RKH_TE_SMA_GET 

Get an event from the active object's queue.

RKH_TE_SMA_FIFO 

Send an event to a state machine application (SMA) as known as active object through a queue using the FIFO policy. A message is a pointer size variable and its use is application specific.

RKH_TE_SMA_LIFO 

Send an event to a state machine application (SMA) as known as active object through a queue using the LIFO policy. A message is a pointer size variable and its use is application specific.

RKH_TE_SMA_REG 

Registers a state machine application (SMA) as known as active object into the framework, which implies to store a pointer to the SMA in the priority table.

RKH_TE_SMA_UNREG 

Removes the SMA as known as active object from the priority table, and thus from the framework, by simply replacing the link to the SMA being deleted with a NULL pointer.

RKH_TE_SMA_DCH 

Executes a state machine in a run-to-completation (RTC) model.

RKH_TE_SM_INIT 

Inits a previously created state machine calling its initializing action.

RKH_TE_SM_CLRH 

Erase the history of a state. It can be a shallow or deep history.

RKH_TE_SM_TRN 

Source and target state of the transition. The target could be either basic state, composite state or pseudostate.

RKH_TE_SM_STATE 

Legal, stable and final state of transition.

RKH_TE_SM_ENSTATE 

Entered state.

RKH_TE_SM_EXSTATE 

Exited state.

RKH_TE_SM_NENEX 

Number of entry and exit states in transition.

RKH_TE_SM_NTRNACT 

Number of executed actions and segments of the transition.

RKH_TE_SM_TS_STATE 

Destination state or pseudostate of a transition segment.

RKH_TE_SM_EVT_PROC 

The arrived event was succesfully processed and HSM resides in an allowed state.

RKH_TE_SM_EVT_NFOUND 

The arrived event was't founded in the transition table.

RKH_TE_SM_GRD_FALSE 

The transition was cancelled by guard function.

RKH_TE_SM_CND_NFOUND 

The branch function returned a value not founded in the branch table.

RKH_TE_SM_UNKN_STATE 

Unknown state.

RKH_TE_SM_EX_HLEVEL 

The transition exceeded the allowed hierarchical level.

RKH_TE_SM_EX_TSEG 

The transition exceeded the allowed number of segments within a compound transtion.

RKH_TE_SM_EXE_ACT 

Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard.

RKH_TE_TMR_INIT 

Initializes the previously allocated timer structure RKH_TMR_T.

RKH_TE_TMR_START 

Start a timer.

RKH_TE_TMR_STOP 

Stops a running timer.

RKH_TE_TMR_TOUT 

Timer expired.

RKH_TE_TMR_REM 

Removes timer from the active timer list.

RKH_TE_FWK_EN 

Initializes the RKH framework.

RKH_TE_FWK_EX 

Exit the RKH framework.

RKH_TE_FWK_EPREG 

Registers a new event pool into the event pool list.

RKH_TE_FWK_AE 

Allocates an event from the previously created event pool.

RKH_TE_FWK_GC 

Attempt to recycle an event.

RKH_TE_FWK_GCR 

Effective recycling event.

RKH_TE_FWK_DEFER 

Defer an event to a given separate event queue.

RKH_TE_FWK_RCALL 

Recall a deferred event from a given event queue.

RKH_TE_FWK_OBJ 

Entry symbol table for memory object.

RKH_TE_FWK_SIG 

Entry symbol table for event signal.

RKH_TE_FWK_FUN 

Entry symbol table for function object.

RKH_TE_FWK_EXE_FUN 

The function was executed.

RKH_TE_FWK_SYNC_EVT 

The function was synchronously executed. It is not explicitely used by the RKH, instead it's frequently placed on application source code.

RKH_TE_FWK_TUSR 

Entry symbol table for user-defined trace events.

RKH_TE_FWK_TCFG 

Send trace configuration to Trazer.

RKH_TE_FWK_ASSERT 

Assertion expression was evaluated to false.

RKH_TE_FWK_AO 

Entry symbol table for active object.

RKH_TE_FWK_STATE 

Entry symbol table for state object.

RKH_TE_FWK_PSTATE 

Entry symbol table for pseudostate object.

RKH_TE_FWK_TIMER 

Entry symbol table for timer object.

RKH_TE_FWK_EPOOL 

Entry symbol table for event pool object.

RKH_TE_FWK_QUEUE 

Entry symbol table for queue object.

Definition at line 3316 of file rkhtrc.h.

Sub-event of RKH_TE_SM_EXE_ACT event.

Enumerator
RKH_SUBTE_SM_EXE_ACT_EFF 

Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard.

RKH_SUBTE_SM_EXE_ACT_EN 

Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard.

RKH_SUBTE_SM_EXE_ACT_EX 

Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard.

RKH_SUBTE_SM_EXE_ACT_INI 

Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard.

RKH_SUBTE_SM_EXE_ACT_PP 

Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard.

RKH_SUBTE_SM_EXE_ACT_GRD 

Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard.

Definition at line 3421 of file rkhtrc.h.

Function Documentation

void rkh_trc_init ( void  )

Initializes the RKH's trace record service.

Note
rkh_trc_init() is NOT protected with a critical section.
rui8_t* rkh_trc_get ( void  )

Retrieves a pointer to oldest stored byte in the trace stream. Frequently, this function is used by the called trace analyzer.

Note
The data is stored in a single ring buffer, called trace stream. In this manner the recorder always holds the most recent history. rkh_trc_get() is NOT protected with a critical section.
Returns
A pointer to the oldest stored byte if trace stream was not empty, otherwise NULL pointer.
rui8_t* rkh_trc_get_block ( TRCQTY_T *  nget)

Retrieves a pointer to a contiguous block of data from the trace stream.

The function returns the pointer to the beginning of the block, and writes the number of bytes in the block to the location pointed to by nget. The argument nget is also used as input to provide the maximum size of the data block that the caller can accept. Frequently, this function is used by the called trace analyzer.

Parameters
[in]ngetwhen this function is invoked nget is used as an input to provide the maximum size of the data block to be retrieved. Also, it is used as an output retrieving the size of block.
Returns
The pointer to the beginning of the block, and writes the number of bytes in the block to the location pointed to by nget. If this number differs from the nget parameter, the end-of-stream was reached. If the trace stream is empty, the function returns NULL and the content pointed by nget is set to zero.
Note
The data is stored in a single ring buffer, called trace stream. In this manner the recorder always holds the most recent history. rkh_trc_get_block() is NOT protected with a critical section.
void rkh_trc_put ( rui8_t  b)

Put a data byte into the trace stream.

Parameters
[in]bdata to be written in the trace stream.
Note
The data is stored in a single ring buffer, called trace stream. In this manner the recorder always holds the most recent history. rkh_trc_put() is NOT protected with a critical section.
void rkh_trc_filter_group_ ( rui8_t  ctrl,
RKH_TG_T  grp,
rui8_t  mode 
)

Emit or suppress all trace events from a specific group.

The stream is initially created with an empty filter (that is, without filtering any event type). If this is not the required behavior, the application can build a set of event types, include the appropriate event types in it, and apply it as a filter to the stream. After that, the stream will reject any event whose type is in the filter set.

Gathering many events generates a lot of data, which requires memory and processor time. It also makes the task of interpreting the data more difficult. Because the amount of data that the instrumented framework generates can be overwhelming, the RKH supports several types of filters that can use it to reduce the amount of data to be processed. The available groups are enumerated in RKH_TRC_GROUPS.

Parameters
[in]ctrlfilter option, the available options are FILTER_ON or FILTER_OFF.
[in]grptrace group. The available groups are enumerated in RKH_TRC_GROUPS.
[in]modefilter mode. ECHANGE indicates that the all event's group are accordingly changed as filter option value, otherwise EUNCHANGE.
Usage
Note
This function is internal to RKH and the user application should not call it. Please use RKH_FILTER_ON_GROUP(), or RKH_FILTER_OFF_GROUP() macros instead.
void rkh_trc_filter_event_ ( rui8_t  ctrl,
RKH_TE_ID_T  evt 
)

Emit or suppress a specific event.

The stream is initially created with an empty filter (that is, without filtering any event type). If this is not the required behavior, the application can build a set of event types, include the appropriate event types in it, and apply it as a filter to the stream. After that, the stream will reject any event whose type is in the filter set.

Gathering many events generates a lot of data, which requires memory and processor time. It also makes the task of interpreting the data more difficult. Because the amount of data that the instrumented framework generates can be overwhelming, the RKH supports several types of filters that can use it to reduce the amount of data to be processed. The available events are enumerated in RKH_TRC_EVENTS.

Parameters
[in]ctrlfilter option, the available options are FILTER_ON or FILTER_OFF.
[in]evttrace event. The available events are enumerated in RKH_TRC_EVENTS.
Usage
Note
This function is internal to RKH and the user application should not call it. Please use RKH_FILTER_ON_EVENT(), or RKH_FILTER_OFF_EVENT() macros instead.
rbool_t rkh_trc_isoff_ ( RKH_TE_ID_T  e)

Test the group and event filter condition.

Parameters
[in]etrace event ID. The available events are enumerated in RKH_TRC_EVENTS.
Returns
'1' (RKH_TRUE) if the group and event is not filtered, otherwise '0' (RKH_FALSE).
Note
This function is internal to RKH and the user application should not call it.
void rkh_trc_symFil ( const RKH_TRC_FIL_T filter,
RKH_TRC_FSLOT  slot,
rui8_t  mode 
)

Emmit or suppresse trace events related to a particular active object or event signal.

Parameters
[in]filterfilter type.
[in]slotindicates the filter slot to be applied.
[in]modefilter option, the available options are FILTER_ON or FILTER_OFF.
Note
This function is internal to RKH and the user application should not call it. Please use RKH_FILTER_ON_SMA()/RKH_FILTER_ON_SIGNAL(), or RKH_FILTER_OFF_SMA()/RKH_FILTER_OFF_SIGNAL() macros instead.
rbool_t rkh_trc_symFil_isoff ( const RKH_TRC_FIL_T filter,
RKH_TRC_FSLOT  slot 
)

Test the active objecto or signal filter condition.

Parameters
[in]filterfilter type.
[in]slotindicates the filter slot to be applied.
Returns
'1' (RKH_TRUE) if the group and event is not filtered, otherwise '0' (RKH_FALSE).
Note
This function is internal to RKH and the user application should not call it.
void rkh_trc_begin ( RKH_TE_ID_T  eid)

Store the trace record header in the stream.

By means of RKH_TRC_HDR() macro stores the listed data fields in the stream buffer (in that order):

  • Trace event ID [n-bytes]. The number of bytes that it uses is specified by the size of RKH_TE_ID_T data type.
  • Sequence number [1-byte]. If the RKH_CFG_TRC_NSEQ_EN is set to 1 then RKH will add to the trace record an incremental number (1-byte), used like a sequence number.
  • Timestamp [1, 2 or 4 bytes]. If the RKH_CFG_TRC_TSTAMP_EN is set to 1 then RKH will add to the trace record a timestamp field. It's configurable by means of RKH_CFGPORT_TRC_SIZEOF_TSTAMP.
Parameters
[in]eidtrace event ID. The available events are enumerated in RKH_TRC_EVENTS.
Note
This function should be called indirectly through the macro RKH_TRC_BEGIN.
Usage
The next listing shows the implemented RKH_TRC_HDR() macro:
RKH_TRC_HDR(eid) \
(1) chk = 0; \
(2) RKH_TRC_TE_ID(eid); \
(3) RKH_TRC_NSEQ(); \
(4) RKH_TRC_TSTAMP()
  • (1) Initialize the trace record checksum.
  • (2) Insert the event ID
  • (3) Insert the sequence number
  • (4) Insert the timestamp
void rkh_trc_end ( void  )

Terminate the recorded trace event.

This function inserts a the flag byte, which delimits the frame. The flag is the 0x7E.

Note
This function should be called indirectly through the macro RKH_TRC_END.
void rkh_trc_clear_chk ( void  )

Clear to zero the trace record checksum.

Note
This function should be called indirectly through the macro RKH_TRC_BEGIN_DFT().
void rkh_trc_u8 ( rui8_t  d)

Store a 8-bit data into the current trace event buffer without format information.

Parameters
[in]ddata
void rkh_trc_u16 ( rui16_t  d)

Store a 16-bit data into the current trace event buffer without format information.

Parameters
[in]ddata
void rkh_trc_u32 ( rui32_t  d)

Store a 32-bit data into the current trace event buffer without format information.

Parameters
[in]ddata
void rkh_trc_str ( const char *  s)

Store a string terminated in '\0' into the current trace event buffer without format information.

Parameters
[in]spointer to string treminated in '\0'
void rkh_trc_obj ( RKH_TE_ID_T  tre,
rui8_t *  obj,
const char *  obj_name 
)

Output object symbol record.

Parameters
[in]tretrace event ID. The available events are enumerated in RKH_TRC_EVENTS.
[in]objaddress of the object in memory.
[in]obj_namestring terminated in '\0'.
Note
This function is internal to RKH and the user application should not call it.
void rkh_trc_sig ( RKH_SIG_T  sig,
const char *  sig_name 
)

Output signal symbol record.

Parameters
[in]sigsignal number.
[in]sig_namestring terminated in '\0'.
Note
This function is internal to RKH and the user application should not call it.
void rkh_trc_ao ( struct RKH_SMA_T ao)

Output active object (AO) symbol record.

Parameters
[in]aoaddress of active object symbol.
Note
This function is internal to RKH and the user application should not call it.
void rkh_trc_state ( struct RKH_SMA_T ao,
rui8_t *  state 
)

Output state symbol record.

Parameters
[in]aoaddress of active object symbol.
[in]stateaddress of state symbol.
Note
This function is internal to RKH and the user application should not call it.
void rkh_trc_fmt_u8 ( rui8_t  fmt,
rui8_t  d 
)

Store a 8-bit data into the current trace event buffer with format information.

Parameters
[in]fmtformat information
[in]ddata
void rkh_trc_fmt_u16 ( rui8_t  fmt,
rui16_t  d 
)

Store a 16-bit data into the current trace event buffer with format information.

Parameters
[in]fmtformat information
[in]ddata
void rkh_trc_fmt_u32 ( rui8_t  fmt,
rui32_t  d 
)

Store a 32-bit data into the current trace event buffer with format information.

Parameters
[in]fmtformat information
[in]ddata
void rkh_trc_fmt_str ( const char *  s)

Store a string terminated in '\0' into the current trace event buffer with format information.

Parameters
[in]spointer to string terminated in '\0'
void rkh_trc_fmt_mem ( rui8_t const *  mem,
rui8_t  size 
)

Output memory block of up to 255-bytes with format information.

Parameters
[in]mempointer to memory block.
[in]sizesize of memory block.
void rkh_trc_filter_get ( RKH_FilterTbl *  outFilterTbl)

Get a memory reference to every trace filter table.

Parameters
[out]outFilterTblpointer to every filter table.