|
RKH
|
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:
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:
RKH trace event structure
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
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.
Argument-generating macros for building user trace events:
Example:
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.
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:
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:
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:
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:
Please use RKH_FILTER_ON_SMA(), RKH_FILTER_OFF_SMA(), RKH_FILTER_ON_ALL_SMA()/RKH_FILTER_OFF_ALL_SMA to do that.
Example:
Please use RKH_FILTER_ON_SIGNAL(), RKH_FILTER_OFF_SIGNAL(), RKH_FILTER_ON_ALL_SIGNALS()/RKH_FILTER_OFF_ALL_SIGNALS() to do that.
Example:
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 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
1.8.10 
