Table of Contents
When a program needs to be traced, it has to generate some information each time it reaches a "significant step" (certain instruction in the program's source code). In the standard terminology, this step is called a trace point, and the tracing information which is generated at that point is called a trace event. A program containing one or more of this trace points is named instrumented application.
The definition of events and the mapping between these and their corresponding names is hard-coded in the RKH implementation. Therefore, these events are common for all the state machine applications and never change (they are always traced). The trace events are associated with a integer value and are explicity listed and defined (enumerated) as shown below in this file.
The standard defines that the trace system has to store some information for each trace event (also named arguments) being generated, including, at least, the following:
- the trace event identifier (RKH_TE_<group>_<event> definitions),
- a timestamp (optional),
- any extra data that the system wants to associate with the event (optional).
When the system or an application trace an event, all the information related to it has to be stored somewhere before it can be retrieved, in order to be analyzed. This place is a trace stream. Formally speaking, a trace stream is defined as a non-persistent, internal (opaque) data object containing a sequence of trace events plus some internal information to interpret those trace events.
Also, the streams support runtime filtering. The application can define and apply a filter to a trace stream. Basically, the filter establishes which event types the stream is accepting (and hence storing) and which are not. Therefore, trace events corresponding to types which are filtered out from a certain stream will not be stored in the stream. The stream in the system can potentially be applied a different filter. This filter can be applied, removed or changed at any time.
This section includes:
- Trace event structure
- Trace tool configuration
- Implementing the trace session support
- Using runtime trace filters
- Trace event table
- TRAZER - The fundamental RKH's tracing tool
- Reading and analysing traces using Trace Compass
Trace event structure
RKH trace event structure
- (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:
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) 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,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_I8() Output formatted ri8_t to the trace record.
- RKH_TUSR_UI8() Output formatted rui8_t to the trace record.
- RKH_TUSR_I16() Output formatted ri16_t to the trace record.
- RKH_TUSR_UI16() Output formatted rui16_t to the trace record.
- RKH_TUSR_I32() Output formatted ri32_t to the trace record.
- RKH_TUSR_UI32() Output formatted rui32_t to the trace record.
- RKH_TUSR_X32() Output formatted rui32_t to the trace record.
- 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_OBJ() Output formatted object pointer to the trace record.
- RKH_TUSR_FUN() Output formatted function pointer to the trace record.
- RKH_TUSR_SIG() Output formatted event signal to the trace record.
Example:
- See also
- RKH_TRC_END()
Trace tool configuration
First of all, RKH has a set of configuration options related to trace tool facility, which an user that require this feature must be properly configure in the rkhcfg.h header file. See Configuration section for more information about that.
Implementing the trace session support
For using the native trace facility the user should implement several functions which are platform and application specific. These function prototypes are definied within rkh.h file and listed below:
- rkh_trc_open() This function is application-specific and the user needs to define it. At a minimum, this function must initialize and/or configure the trace stream by calling rkh_trc_init() and RKH_TRC_SEND_CFG() respectively.
- Note
- This function is internal to RKH and the user application should not call it. Instead, use RKH_TRC_OPEN() macro.
- See also
- rkhtrc.h file.
- Usage
- rkh_trc_close() This function is application-specific and the user needs to define it.
- Note
- This function is internal to RKH and the user application should not call it. Instead, use RKH_TRC_CLOSE() macro.
- See also
- rkhtrc.h file.
- Usage
- rkh_trc_flush() This function is application-specific and the user needs to define it. When the RKH trace an event, all the information related to it has to be stored somewhere before it can be retrieved, in order to be analyzed. This place is a trace stream. Frequently, events traced are stored in the stream until it is flushed.
- Note
- This function is internal to RKH and the user application should not call it. Instead, use RKH_TRC_FLUSH() macro.
- See also
- rkhtrc.h file.
- Usage
- voidrkh_trc_flush( void ){rui8_t *blk;TRCQTY_T nbytes;RKH_SR_ALLOC();FOREVER{nbytes = (TRCQTY_T)1024;RKH_ENTER_CRITICAL_();blk = rkh_trc_get_block( &nbytes );RKH_EXIT_CRITICAL_();if((blk != (rui8_t *)0)){FTBIN_FLUSH( blk, nbytes );TCP_TRACE_SEND_BLOCK( blk, nbytes );}elsebreak;}}#define RKH_SR_ALLOC()RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts...Definition: rkhitl.h:2051rui8_t * rkh_trc_get_block(TRCQTY_T *nget)Retrieves a pointer to a contiguous block of data from the trace stream.
- rkh_trc_getts() This function is application-specific and the user needs to define it. The data returned is defined in compile-time by means of RKH_SIZEOF_TSTAMP.
- Returns
- Timestamp (RKH_TS_T data type).
- See also
- rkhtrc.h file.
- Usage
Using runtime trace filters
Also, the streams support runtime filtering. The application can define and apply a filter to a trace stream. Basically, the filter establishes which event types the stream is accepting (and hence storing) and which are not. Therefore, trace events corresponding to types which are filtered out from the stream will not be stored in the stream. The stream in the system can potentially be applied a different filters. This filter can be applied, removed or changed at any time. A filter could be applied either specific trace event or all events from a specific group.
This section includes:
- Emit or suppress all trace events from a specific group
- Emit or suppress a specific event
- Emit or suppress the trace events related to a specific SMA (active object)
- Emit or suppress the trace events related to a specific signal (user event).
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_TG_<group>.
Please use RKH_FILTER_ON_GROUP(), RKH_FILTER_ON_GROUP_ALL_EVENTS(), RKH_FILTER_OFF_GROUP_ALL_EVENTS(), or RKH_FILTER_OFF_GROUP() macros to do that.
Example:
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_TE_<group>_<event> definitions.
Please use RKH_FILTER_ON_EVENT(), or RKH_FILTER_OFF_EVENT() macros to do that.
Example:
Emit or suppress the trace events related to a specific SMA (active object)
Please use RKH_FILTER_ON_SMA(), RKH_FILTER_OFF_SMA(), RKH_FILTER_ON_ALL_SMA()/RKH_FILTER_OFF_ALL_SMA to do that.
Example:
Emit or suppress the trace events related to a specific signal (user event).
Please use RKH_FILTER_ON_SIGNAL(), RKH_FILTER_OFF_SIGNAL(), RKH_FILTER_ON_ALL_SIGNALS()/RKH_FILTER_OFF_ALL_SIGNALS() to do that.
Example:
Trace event table
This section provides a table that lists all the trace events and summarizes the data included for each.
| Related with memory pool module (MP) | |||||
|---|---|---|---|---|---|
| Group | ID | Trace Event | Description | Parameters | |
| RKH_TG_MP | 0 | RKH_TE_MP_INIT(SYM mp, NBLK nblock, BSIZE bsize) | Initializes the previously allocated memory pool data strcuture RKH_MEMPOOL_T. | mp | Pointer to previously allocated memory pool structure |
| nblock | Total number of blocks in bytes. | ||||
| bsize | Maximum block size in bytes. | ||||
| 1 | RKH_TE_MP_GET (SYM mp, NBLK nfree, NBLK nmin) | Get a memory block from one of the previously allocated memory pool. | mp | Pointer to previously allocated memory pool structure | |
| nfree | Number of free blocks remaining. | ||||
| nmin | Minimum number of free blocks ever in this pool, i.e. holds the lowest number of free blocks ever present in the pool. | ||||
| 2 | RKH_TE_MP_PUT (SYM mp, NBLK 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. | mp | Pointer to previously allocated memory pool structure | |
| nfree | Number of free blocks remaining. | ||||
| Related with queue module (QUE) | |||||
| Group | ID | Trace Event | Description | Parameters | |
| RKH_TG_QUE | 0 | RKH_TE_QUE_INIT (SYM q, SYM ao, NE nelem) | Initializes the previously allocated queue data structure RKH_QUEUE_T. | q | Event queue of the SMA (a.k.a Active Object). |
| ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | ||||
| nelem | Number of elements. | ||||
| 1 | RKH_TE_QUE_GET (SYM q, NE nelem) | Get and remove an element from a queue. | q | Event queue of the SMA (a.k.a Active Object). | |
| nelem | Number of elements. | ||||
| 2 | RKH_TE_QUE_FIFO (SYM q, NE nelem, NE nmin) | Puts an element on a queue in a FIFO manner. The element is queued by reference, not by copy. | q | Event queue of the SMA (a.k.a Active Object). | |
| nelem | Number of elements. | ||||
| nmin | Minimum number of free elements ever in this queue. The nmin low-watermark provides valuable empirical data for proper sizing of the queue. | ||||
| 3 | RKH_TE_QUE_LIFO (SYM q, NE nelem, NE nmin) | Puts an element on a queue in a LIFO manner. The element is queued by reference, not by copy. | q | Event queue of the SMA (a.k.a Active Object). | |
| nelem | Number of elements. | ||||
| nmin | Minimum number of free elements ever in this queue. The nmin low-watermark provides valuable empirical data for proper sizing of the queue. | ||||
| 4 | RKH_TE_QUE_FULL (SYM q) | Queue is full. | q | Event queue of the SMA (a.k.a Active Object). | |
| 5 | RKH_TE_QUE_DPT (SYM q) | Depletes a queue. Empties the contents of the queue and eliminates all stored elements. | q | Event queue of the SMA (a.k.a Active Object). | |
| 6 | RKH_TE_QUE_GET_LAST (SYM q) | Get the last element from the queue. | q | Event queue of the SMA (a.k.a Active Object). | |
| Related with State Machine Application (SMA) or Active Object | |||||
| Group | ID | Trace Event | Description | Parameters | |
| RKH_TG_SMA | 0 | RKH_TE_SMA_ACT (SYM ao, UI8 prio, NE msgQueueSize) | Initializes and activates a previously created state machine application (SMA) as known as active object. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. |
| prio | SMA (a.k.a Active Object) priority. | ||||
| msgQueueSize | Number of elements. | ||||
| 1 | RKH_TE_SMA_TERM (SYM ao, UI8 prio) | Terminate a state machine application (SMA) as known as active object. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| prio | SMA (a.k.a Active Object) priority. | ||||
| 2 | RKH_TE_SMA_GET (SYM ao, SIG sig, UI8 pid, UI8 refc, NE nElem, NE nMin) | Get an event from the active object's queue. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| sig | Signal of the event instance. | ||||
| pid | Attribute of dynamic events. | ||||
| refc | Attribute of dynamic events. | ||||
| nElem | Number of elements currently in the queue. | ||||
| nMin | Minimum number of free elements ever in this queue. The nmin low-watermark provides valuable empirical data for proper sizing of the queue. | ||||
| 3 | RKH_TE_SMA_FIFO(SYM ao, SIG sig, SYM snr, UI8 pid, UI8 refc, NE nElem, Ne nMin) | 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. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| sig | Signal of the event instance. | ||||
| snr | Sender object | ||||
| pid | Attribute of dynamic events. | ||||
| refc | Attribute of dynamic events. | ||||
| nElem | Number of elements currently in the queue. | ||||
| nMin | Minimum number of free elements ever in this queue. The nmin low-watermark provides valuable empirical data for proper sizing of the queue. | ||||
| 4 | RKH_TE_SMA_LIFO(SYM ao, SIG sig, SYM snr, UI8 pid, UI8 refc, NE nElem, NE nMin) | 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. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| sig | Signal of the event instance. | ||||
| snr | Sender object | ||||
| pid | Attribute of dynamic events. | ||||
| refc | Attribute of dynamic events. | ||||
| nElem | Number of elements currently in the queue. | ||||
| nMin | Minimum number of free elements ever in this queue. The nmin low-watermark provides valuable empirical data for proper sizing of the queue. | ||||
| 5 | RKH_TE_SMA_REG (SYM ao, UI8 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. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| prio | SMA (a.k.a Active Object) priority. | ||||
| 6 | RKH_TE_SMA_UNREG (SYM ao, UI8 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. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| prio | SMA (a.k.a Active Object) priority. | ||||
| 6 | RKH_TE_SMA_DEFER (SYM q, SIG sig) | Defer an event to a given separate event queue. | q | Event queue of the SMA (a.k.a Active Object). | |
| sig | Signal of the event instance. | ||||
| 7 | RKH_TE_SMA_RCALL (SYM ao, SIG sig) | Recall a deferred event from a given event queue. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| sig | Signal of the event instance. | ||||
| Related with State Machines (SM) | |||||
| Group | ID | Trace Event | Description | Parameters | |
| RKH_TG_SM | 0 | RKH_TE_SM_INIT (SYM ao, SYM ist) | Inits a previously created state machine calling its initializing action. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. |
| ist | Points to initial state. | ||||
| 1 | RKH_TE_SM_CLRH (SYM ao, SYM h) | Erase the history of a state. It can be a shallow or deep history. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| h | Points to state's history. | ||||
| 3 | RKH_TE_SM_TRN (SYM ao, SYM sst, SYM tst) | Source and target state of the transition. The target could be either basic state, composite state or pseudostate. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| sst | Source state of transition | ||||
| tst | Target state of transition | ||||
| 4 | RKH_TE_SM_STATE (SYM ao, SYM st) | Legal, stable and final state of transition. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| nxtst | Next state of transition | ||||
| 5 | RKH_TE_SM_ENSTATE (SYM ao, SYM st) | Entered state. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| st | Entry state | ||||
| 6 | RKH_TE_SM_EXSTATE (SYM ao, SYM st) | Exited state. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| st | Exited state | ||||
| 7 | RKH_TE_SM_NENEX (SYM ao, UI8 nen, UI8 nex) | Number of entry and exit states in transition. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| nen | Number of entry states | ||||
| nex | Number of exited states | ||||
| 8 | RKH_TE_SM_NTRNACT (SYM ao, UI8 nta, UI8 nts) | Number of executed actions and segments of the transition. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| nta | Number of executed actions | ||||
| nts | Number of transition segments | ||||
| 9 | RKH_TE_SM_TS_STATE (SYM ao, SYM st) | Destination state or pseudostate of a transition segment. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| st | Next state or pseudostate in transition | ||||
| 10 | RKH_TE_SM_EVT_PROC (SYM ao) | The arrived event was succesfully processed and HSM resides in an allowed state. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| 2 | RKH_TE_SM_EVT_NFOUND (SYM ao, SIG sig) | The arrived event was't founded in the transition table. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| sig | Signal of the event instance. | ||||
| 12 | RKH_TE_SM_CND_NFOUND (SYM ao) | The branch function returned a value not founded in the branch table. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| 13 | RKH_TE_SM_GRD_FALSE (SYM ao) | The transition was cancelled by guard function. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| 14 | RKH_TE_SM_UNKN_STATE (SYM ao) | Unknown state. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| 15 | RKH_TE_SM_EX_HLEVEL (SYM ao) | The transition exceeded the allowed hierarchical level. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| 16 | RKH_TE_SM_EX_TSEG (SYM ao) | The transition exceeded the allowed number of segments within a compound transtion. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| 8 | RKH_TE_SM_EXE_ACT (UI8 act_type, SYM ao, SYM st, FUN act) | Executes a behavior (action) of state machine, it could be an entry, exit, effect, init, preprocessor or guard. | act_type | Sub-event of RKH_TE_SM_EXE_ACT event. | |
| ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | ||||
| st | Points to associated state | ||||
| act | Points to executed action | ||||
| 2 | RKH_TE_SM_DCH (SYM ao, SIG sig, SYM st) | Executes a state machine in a run-to-completation (RTC) model. | ao | Points to the associated SMA (a.k.a Active Object) that receives the enqueued events. | |
| sig | Signal of the event instance. | ||||
| st | Current state (basic or substate) | ||||
| Related with timer module (TMR) | |||||
| Group | ID | Trace Event | Description | Parameters | |
| RKH_TG_TMR | 0 | RKH_TE_TMR_INIT (SYM t, SIG sig) | Initializes the previously allocated timer structure RKH_TMR_T. | t | Pointer to previously allocated timer structure |
| sig | Signal of the event instance. | ||||
| 1 | RKH_TE_TMR_START (SYM t, SYM ao, NTICK ntick, NTICK per) | Start a timer. | t | Pointer to previously allocated timer structure | |
| ao | State machine application (a.k.a Active Object) that receives the timer event. | ||||
| ntick | Tick down-counter. | ||||
| per | Number of ticks for all timer expirations after the first (expiration period). A zero for this parameter makes the timer a one-shot timer, otherwise, for periodic timers, any value in range. | ||||
| 2 | RKH_TE_TMR_STOP (SYM t, NTICK ntick, NTICK per) | Stops a running timer. | t | Pointer to previously allocated timer structure | |
| ntick | Tick down-counter. | ||||
| per | Number of ticks for all timer expirations after the first (expiration period). A zero for this parameter makes the timer a one-shot timer, otherwise, for periodic timers, any value in range. | ||||
| 3 | RKH_TE_TMR_TOUT (SYM t, SIG sig, SYM ao) | Timer expired. | t | Pointer to previously allocated timer structure | |
| sig | Signal of the event instance. | ||||
| ao | State machine application (a.k.a Active Object) that receives the timer event. | ||||
| 4 | RKH_TE_TMR_REM (SYM t) | Removes timer from the active timer list. | t | Pointer to previously allocated timer structure | |
| Miscellanueos and related with Framework (FWK) | |||||
| Group | ID | Trace Event | Description | Parameters | |
| RKH_TG_FWK | 0 | RKH_TE_FWK_EN () | Initializes the RKH framework. | ||
| 1 | RKH_TE_FWK_EX () | Exit the RKH framework. | |||
| 2 | RKH_TE_FWK_EPREG (UI8 ep, UI32 ss, ES es) | Registers a new event pool into the event pool list. | ep | Event pool index in the list | |
| ss | Storage size in bytes | ||||
| es | Event size | ||||
| 3 | RKH_TE_FWK_AE (ES es, SIG sig, UI8 pid, UI8 refc) | Allocates an event from the previously created event pool. | es | Event size | |
| sig | Signal of the event instance. | ||||
| pid | Attribute of dynamic events. | ||||
| refc | Attribute of dynamic events. | ||||
| nUsed | Current number of memory blocks used | ||||
| nMin | Minimum number of free blocks ever in this pool, i.e. holds the lowest number of free blocks ever present in the pool. | ||||
| sender | Pointer to the actor that request a memory block | ||||
| 4 | RKH_TE_FWK_GC (SIG sig, UI8 pid, UI8 refc) | Attempt to recycle an event. | sig | Signal of the event instance. | |
| pid | Attribute of dynamic events. | ||||
| refc | Attribute of dynamic events. | ||||
| 5 | RKH_TE_FWK_GCR (SIG sig, UI8 pid, UI8 refc) | Effective recycling event. | sig | Signal of the event instance. | |
| pid | Attribute of dynamic events. | ||||
| refc | Attribute of dynamic events. | ||||
| nUsed | Current number of memory blocks used | ||||
| nMin | Minimum number of free blocks ever in this pool, i.e. holds the lowest number of free blocks ever present in the pool. | ||||
| sender | Pointer to the actor that request a memory block | ||||
| 4 | RKH_TE_FWK_GC (SIG sig, UI8 pid, UI8 refc) | Attempt to recycle an event. | sig | Signal of the event instance. | |
| pid | Attribute of dynamic events. | ||||
| refc | Attribute of dynamic events. | ||||
| 8 | RKH_TE_FWK_OBJ (SYM obj, STR nm) | Entry symbol table for memory object. | obj | Object memory address | |
| nm | Name of object | ||||
| 9 | RKH_TE_FWK_SIG (SIG sig, STR nm) | Entry symbol table for event signal. | sig | Signal of the event instance. | |
| nm | Name of event signal | ||||
| 10 | RKH_TE_FWK_FUN (FUN func, STR nm) | Entry symbol table for function object. | func | Function memory address | |
| nm | Name of object | ||||
| 11 | RKH_TE_FWK_EXE_FUN (FUN func) | The function was executed. | func | Function memory address | |
| 12 | RKH_TE_FWK_SYNC_EVT (FUN fn, SYM snr, SYM rcr) | The function was synchronously executed. It is not explicitely used by the RKH, instead it's frequently placed on application source code. | fn | Function address | |
| snr | Sender object | ||||
| rcr | Receiver object | ||||
| 13 | RKH_TE_FWK_TUSR (UI8 usrtrc, STR nm) | Entry symbol table for user-defined trace events. | usrtrc | User-defined trace event | |
| nm | Name of user-defined event | ||||
| 14 | RKH_TE_FWK_TCFG (CFG cfg) | Send trace configuration to Trazer. | cfg | Configuration parameters of trace facility | |
| 15 | RKH_TE_FWK_ASSERT (SRT mod, UI16 ln) | Assertion expression was evaluated to false. | mod | C/C++ module (.c file) | |
| ln | Line number of assertion | ||||
| 16 | RKH_TE_FWK_AO (SYM obj, STR nm) | Entry symbol table for active object. | obj | Active object memory address | |
| nm | Name of object | ||||
| 17 | RKH_TE_FWK_STATE (SYM ao, SYM obj, STR nm) | Entry symbol table for state object. | ao | Active object memory address | |
| obj | State object memory address | ||||
| nm | Name of object | ||||
| 18 | RKH_TE_FWK_PSTATE (SYM ao, SYM obj, STR nm) | Entry symbol table for pseudostate object. | ao | Active object memory address | |
| obj | Pseudostate object memory address | ||||
| nm | Name of object | ||||
| 19 | RKH_TE_FWK_TIMER (SYM obj, STR nm) | Entry symbol table for timer object. | obj | Timer object memory address | |
| nm | Name of object | ||||
| 20 | RKH_TE_FWK_EPOOL (UI8 poolId, STR nm) | Entry symbol table for event pool object. | poolId | Event pool ID | |
| nm | Name of object | ||||
| 21 | RKH_TE_FWK_QUEUE (SYM obj, STR nm) | Entry symbol table for queue object. | obj | Queue object memory address | |
| nm | Name of object | ||||
| 22 | RKH_TE_FWK_ACTOR (SYM obj, STR nm) | Entry symbol table for actor object. | obj | Actor object address | |
| nm | Name of object | ||||
TRAZER - The fundamental RKH's tracing tool
Trazer is a visualization tool that works in conjuntion with the RKH framework built in trace facility. Trazer gives the possibility to display selectively the recording of all events of your system, state machines, queues, timers, etc. Trazer helps you to faster troubleshooting especially on complex problems where a debugger is not sufficient, by providing a simple consolidated, human-readable textual output. Given the RKH cross plataform portability, trace data may come from 8, 16, or 32-bits platforms. In order to that Trazer need to be configured to support this diversity of plataform and the wide range of RKH framework configurations.
Here is the Trazer Reference Manual
Reading and analysing traces using Trace Compass
In order to solve performance and reliability issues by reading and analyzing traces of a reactive and embedded application based on the RKH framework is proposed using the powerful Eclipse Trace Compass.
Trace Compass is an open source application for viewing and analyzing any type of logs or traces. Its goal is to provide views, graphs, metrics, etc. to help extract useful information from traces, in a way that is more user-friendly and informative than huge text dumps.
The project TraceTC brings a simple guide on how to use Trace Compass together with RKH tracing tool.
