Invoke the active object activation function rkh_sma_activate(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the active object to activate. More...

Invoke the direct event posting facility rkh_sma_post_fifo(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the target active object. More...

Invoke the direct event posting facility rkh_sma_post_lifo(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the target active object. More...

This macro declares a opaque pointer to previously created state machine application (SMA aka active object) to be used as a global object.

This global pointer represent the active object in the application. These pointers are "opaque" because they cannot access the whole active object structure, but only the part inherited from the RKH_SMA_T structure. The power of an "opaque" pointer is that it allows to completely hide the definition of the active object structure and make it inaccessible to the rest of the application, thus strengthening the encapsulation concept.

Declare and allocate a SMA (active object) derived from RKH_SMA_T. Also, initializes and assigns a state machine to previously declared SMA.

In the UML specification, every state machine has a top state (the abstract root of every state machine hierarchy), which contains all the other elements of the entire state machine. RKH provides the top state using the macro RKH_SMA_CREATE(). Frequently, RKH_SMA_CREATE() is used within state-machine's module (.c file), thus the structure definition is in fact entirely encapsulated in its module and is inaccessible to the rest of the application. However, use RKH_SMA_DEF_PTR() or RKH_SMA_DEF_PTR_TYPE() macros to define a opaque pointer or typed pointer to that state machine application structure, respectively. Also, use the RKH_SMA_DCLR() macro to declare it to be for the rest of application code. RKH_SMA_T is not intended to be instantiated directly, but rather serves as the base structure for derivation of state machines in the application code. The following example illustrates how to derive an state machine from RKH_SMA_T. Please note that the RKH_SMA_T member sm is defined as the FIRST member of the derived structure.

Frequently, the active object has its own task processing loop, also as known as thread of control, that waits for the signal to be posted, and when it is, loops to remove and process all events that are currently queued.

Event deferral comes in very handy when an event arrives in a particularly inconvenient moment but can be deferred for some later time, when the system is in a much better position to handle the event. RKH supports very efficient event deferring and recalling mechanisms. This function is part of the event deferral mechanism. An SMA uses this function to defer an event e to the event queue q. RKH correctly accounts for another outstanding reference to the event and will not recycle the event at the end of the RTC step. Later, the SMA might recall one event at a time from the event queue by means of rkh_sma_recall() function.

Parameters

[in]

q

pointer to previously created queue.

[in]

e

pointer to event.

Note

For memory efficiency and best performance the deferred event queue, STORE ONLY POINTERS to events, not the whole event objects. An SMA can use multiple event queues to defer events of different kinds. The assertion inside it guarantee that operation is valid, so is not necessary to check the value returned from it.

This function is part of the event deferral support. An SMA uses this function to recall a deferred event from a given event queue. Recalling an event means that it is removed from the deferred event queue q and posted (LIFO) to the event queue of the me state machine application.

Note

For memory efficiency and best performance the destination event queue, STORE ONLY POINTERS to events, not the whole event objects.

Returns

The pointer to the recalled event to the caller, or NULL if no event has been recalled.

Retrieves performance information for a particular state machine application (SMA) as known as active object.

The user application must allocate an RKH_SMAI_T data structure used to receive data. The performance information is available during run-time for each of the RKH services. This can be useful in determining whether the application is performing properly, as well as helping to optimize the application. This information provides a "snapshot" a particular instant in time, i.e., when the service is invoked.

Parameters

[in]

me

pointer to previously created state machine application.

[in]

psi

pointer to the buffer into which the performance information will be copied by reference.

Note

See RKH_SMAI_T structure for more information. This function is optional, thus it could be eliminated in compile-time with RKH_CFG_SMA_GET_INFO_EN = 0.

Variable Documentation

Register a state machine application into the framework implies to store a pointer to the SMA in the priority table. A unique priority number must be assigned to each SMA from 0 to RKH_LOWEST_PRIO. The lower the number, the higher the priority.