RKH
rkhsma.h
Go to the documentation of this file.
1 /*
2  * --------------------------------------------------------------------------
3  *
4  * Framework RKH
5  * -------------
6  *
7  * State-machine framework for reactive embedded systems
8  *
9  * Copyright (C) 2010 Leandro Francucci.
10  * All rights reserved. Protected by international copyright laws.
11  *
12  *
13  * RKH is free software: you can redistribute it and/or modify it under the
14  * terms of the GNU General Public License as published by the Free Software
15  * Foundation, either version 3 of the License, or (at your option) any
16  * later version.
17  *
18  * RKH is distributed in the hope that it will be useful, but WITHOUT ANY
19  * WARRANTY; without even the implied warranty of MERCHANTABILITY or
20  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
21  * more details.
22  *
23  * You should have received a copy of the GNU General Public License along
24  * with RKH, see copying.txt file.
25  *
26  * Contact information:
27  * RKH site: http://vortexmakes.com/que-es/
28  * RKH GitHub: https://github.com/vortexmakes/RKH
29  * RKH Sourceforge: https://sourceforge.net/projects/rkh-reactivesys/
30  * e-mail: lf@vortexmakes.com
31  * ---------------------------------------------------------------------------
32  */
33 
47 /* -------------------------- Development history -------------------------- */
48 /*
49  * 2017.04.05 LeFr v2.4.05 Initial version
50  */
51 
52 /* -------------------------------- Authors -------------------------------- */
53 /*
54  * LeFr Leandro Francucci lf@vortexmakes.com
55  */
56 
57 /* --------------------------------- Notes --------------------------------- */
58 /* --------------------------------- Module -------------------------------- */
59 #ifndef __RKHSMA_H__
60 #define __RKHSMA_H__
61 
62 /* ----------------------------- Include files ----------------------------- */
63 #include "rkhsm.h"
64 #include "rkhqueue.h"
65 
66 /* ---------------------- External C language linkage ---------------------- */
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70 
71 /* --------------------------------- Macros -------------------------------- */
72 #if ((RKH_CFGPORT_NATIVE_EQUEUE_EN == RKH_ENABLED) && \
73  (RKH_EN_DOXYGEN == RKH_DISABLED))
74  #ifndef RKH_EQ_TYPE
75  #define RKH_EQ_TYPE RKH_QUEUE_T
76  #endif
77 #endif
78 
79 #define RKH_SMA_NAME(smaName_) s_##smaName_
80 
87 #define RKH_SMA_ACCESS_STATE(me_) \
88  ((RKH_SM_T *)me_)->state
89 
90 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
98  #define RKH_SMA_ACCESS_CONST(me_, member_) \
99  ((RKH_SM_T *)me_)->romrkh->member_
100 #else
108  #define RKH_SMA_ACCESS_CONST(me_, member_) \
109  ((RKH_SM_T *)me_)->member_
110 #endif
111 
139 #define RKH_SMA_DCLR(me_) \
140  RKH_DCLR_PTR_TYPE(RKH_SMA_T, me_)
141 
168 #define RKH_SMA_DCLR_TYPE(type_, me_) \
169  RKH_DCLR_PTR_TYPE(type_, me_)
170 
213 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
214 #if RKH_CFGPORT_SMA_QSTO_EN == RKH_ENABLED
215  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
216  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
217  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
218  (const RKH_EVT_T **)qSto_, \
219  qStoSize, \
220  (void *)stkSto_, \
221  (rui32_t)stkSize_)
222  #else
223  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
224  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
225  (const RKH_EVT_T **)qSto_, \
226  qStoSize, \
227  (void *)0, \
228  (rui32_t)0)
229  #endif
230 #else
231  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
232  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
233  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
234  (const RKH_EVT_T **)0, \
235  qStoSize, \
236  (void *)stkSto_, \
237  (rui32_t)stkSize_)
238  #else
239  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
240  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
241  (const RKH_EVT_T **)0, \
242  qStoSize, \
243  (void *)0, \
244  (rui32_t)0)
245  #endif
246 #endif
247 #else
248 #if RKH_CFGPORT_SMA_QSTO_EN == RKH_ENABLED
249  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
250  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
251  rkh_sma_activate(me_, \
252  (const RKH_EVT_T **)qSto_, \
253  qStoSize, \
254  (void *)stkSto_, \
255  (rui32_t)stkSize_)
256  #else
257  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
258  rkh_sma_activate(me_, \
259  (const RKH_EVT_T **)qSto_, \
260  qStoSize, \
261  (void *)0, \
262  (rui32_t)0)
263  #endif
264 #else
265  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
266  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
267  rkh_sma_activate(me_, \
268  (const RKH_EVT_T **)0, \
269  qStoSize, \
270  (void *)stkSto_, \
271  (rui32_t)stkSize_)
272  #else
273  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
274  rkh_sma_activate(me_, \
275  (const RKH_EVT_T **)0, \
276  qStoSize, \
277  (void *)0, \
278  (rui32_t)0)
279  #endif
280 #endif
281 #endif
282 
347 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
348  #define RKH_SMA_CREATE(type, name, prio, ppty, initialState, \
349  initialAction, initialEvt) \
350  static RKH_SM_CONST_CREATE(name, prio, ppty, initialState, \
351  initialAction, initialEvt); \
352  static type RKH_SMA_NAME(name) = MKSMA(&RKH_SM_CONST_NAME(name), \
353  initialState)
354 #else
355  #define RKH_SMA_CREATE(type, name, prio, ppty, initialState, \
356  initialAction, initialEvt) \
357  static type RKH_SMA_NAME(name) = MKSMA(name, \
358  prio, \
359  ppty, \
360  initialState, \
361  initialAction, \
362  initialEvt)
363 #endif
364 
365 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
366  #define RKH_SMA_INIT(me, prio, ppty, initialState, initialAction, \
367  initialEvt)
368 #else
369  #define RKH_SMA_INIT(me, prio, ppty, initialState, initialAction, \
370  initialEvt) \
371  MKRT_SM(me, me, prio, ppty, initialState, initialAction, initialEvt)
372 #endif
373 
374 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
375  #define RKH_SMA_GET_OBJ(type, me)
376 #else
377  #define RKH_SMA_GET_OBJ(type, me) \
378  (type *)&RKH_SMA_NAME(me)
379 #endif
380 
390 #define RKH_SMA_DEF_PTR(me_) \
391  RKH_SMA_T *const me_ = (RKH_SMA_T *)&RKH_SMA_NAME(me_)
392 
407 #define RKH_SMA_DEF_PTR_TYPE(type, me_) \
408  type *const me_ = (type *)&RKH_SMA_NAME(me_)
409 
440 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
441  #if defined(RKH_USE_TRC_SENDER)
442  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
443  ((RKH_SMA_T *)(me_))->vptr->post_fifo((me_), (e_), (sender_))
444  #else
445  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
446  ((RKH_SMA_T *)(me_))->vptr->post_fifo((me_), (e_))
447  #endif
448 #else
449  #if defined(RKH_USE_TRC_SENDER)
450  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
451  rkh_sma_post_fifo((me_), (e_), (sender_))
452  #else
453  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
454  rkh_sma_post_fifo((me_), (e_))
455  #endif
456 #endif
457 
488 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
489  #if defined(RKH_USE_TRC_SENDER)
490  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
491  ((RKH_SMA_T *)(me_))->vptr->post_lifo((me_), (e_), (sender_))
492  #else
493  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
494  ((RKH_SMA_T *)(me_))->vptr->post_lifo((me_), (e_))
495  #endif
496 #else
497  #if defined(RKH_USE_TRC_SENDER)
498  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
499  rkh_sma_post_lifo((me_), (e_), (sender_))
500  #else
501  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
502  rkh_sma_post_lifo((me_), (e_))
503  #endif
504 #endif
505 
522 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
523  #define RKH_SMA_DISPATCH(me_, arg_) \
524  ((RKH_SMA_T *)(me_))->vptr->task((me_), (arg_))
525 #else
526  #define RKH_SMA_DISPATCH(me_, arg_) \
527  rkh_sma_dispatch((me_), (arg_))
528 #endif
529 
561 #define RKH_ARRAY_SMA_DCLR(_arr, _num) \
562  extern RKH_SMA_T * const *_arr[_num]
563 
596 #define RKH_ARRAY_SMA_DCLR_TYPE(type_, array_, num_) \
597  extern type_ * const * array_[num_]
598 
622 #define RKH_ARRAY_SMA_CREATE(_arr, _num) \
623  RKH_SMA_T * const *_arr[_num] =
624 
649 #define RKH_ARRAY_SMA_CREATE_TYPE(type_, array_, num_) \
650  type_ * const * array_[num_] =
651 
679 #define RKH_ARRAY_SMA(_arr, _ix) *_arr[_ix]
680 
681 #if R_TRC_AO_NAME_EN == RKH_ENABLED
691  #define RKH_GET_AO_NAME(ao) RKH_SMA_ACCESS_CONST(ao, name)
692 #else
693  #define RKH_GET_AO_NAME(ao) noname
694 #endif
695 
704 #define RKH_GET_SMA(_prio) \
705  rkh_sptbl[(rui8_t)(_prio)]
706 
713 #define RKH_GET_PRIO(_ao) \
714  (rui8_t)(RKH_SMA_ACCESS_CONST(_ao, prio))
715 
716 /* -------------------------------- Constants ------------------------------ */
717 /* ------------------------------- Data types ------------------------------ */
726 typedef struct RKH_SMAI_T
727 {
728  rui16_t ndevt;
729  rui16_t exectr;
730 } RKH_SMAI_T;
731 
771 struct RKH_SMA_T
772 {
777  RKH_SM_T sm;
778 
783 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
784  const RKHSmaVtbl *vptr;
785 #endif
786 
804 #if RKH_CFGPORT_SMA_THREAD_EN == RKH_ENABLED
805  RKH_THREAD_TYPE thread;
806 
826 #if RKH_CFGPORT_SMA_THREAD_DATA_EN == RKH_ENABLED
827  RKH_OSSIGNAL_TYPE os_signal;
828 #endif
829 #endif
830 
835  RKH_EQ_TYPE equeue;
836 
842  rbool_t running;
843 
850 #if RKH_CFG_SMA_GET_INFO_EN == RKH_ENABLED
851  RKH_SMAI_T sinfo;
852 #endif
853 };
854 
856 typedef void (*RKHActivate)(RKH_SMA_T *me,
857  const RKH_EVT_T **qSto, RKH_QUENE_T qSize,
858  void *stkSto, rui32_t stkSize);
859 
861 typedef void (*RKHTask)(RKH_SMA_T *me, void *arg);
862 
864 #if defined(RKH_USE_TRC_SENDER)
865 typedef void (*RKHPostFifo)(RKH_SMA_T *me, const RKH_EVT_T *e,
866  const void *const sender);
867 #else
868 typedef void (*RKHPostFifo)(RKH_SMA_T *me, const RKH_EVT_T *e);
869 #endif
870 
872 #if defined(RKH_USE_TRC_SENDER)
873 typedef void (*RKHPostLifo)(RKH_SMA_T *me, const RKH_EVT_T *e,
874  const void *const sender);
875 #else
876 typedef void (*RKHPostLifo)(RKH_SMA_T *me, const RKH_EVT_T *e);
877 #endif
878 
883 struct RKHSmaVtbl
884 {
887  RKHActivate activate;
888 
902  RKHTask task;
903 
906  RKHPostFifo post_fifo;
907 
910  RKHPostLifo post_lifo;
911 };
912 
913 /* -------------------------- External variables --------------------------- */
915 extern const RKHSmaVtbl rkhSmaVtbl;
916 
926 extern RKH_SMA_T *rkh_sptbl[RKH_CFG_FWK_MAX_SMA];
927 
928 /* -------------------------- Function prototypes -------------------------- */
929 /* -------------------- External C language linkage end -------------------- */
938 void rkh_sma_register(RKH_SMA_T *me);
939 
948 void rkh_sma_unregister(RKH_SMA_T *me);
949 
963 void rkh_sma_ctor(RKH_SMA_T *me, const RKHSmaVtbl *vtbl);
964 
995 void rkh_sma_activate(RKH_SMA_T *me, const RKH_EVT_T * *qSto,
996  RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize);
997 
1022 void rkh_sma_terminate(RKH_SMA_T *me);
1023 
1024 #if defined(RKH_USE_TRC_SENDER)
1056 void rkh_sma_post_fifo(RKH_SMA_T *me, const RKH_EVT_T *e,
1057  const void *const sender);
1058 #else
1059 void rkh_sma_post_fifo(RKH_SMA_T *me, const RKH_EVT_T *e);
1060 #endif
1061 
1062 #if defined(RKH_USE_TRC_SENDER)
1095 void rkh_sma_post_lifo(RKH_SMA_T *me, const RKH_EVT_T *e,
1096  const void *const sender);
1097 
1098 #else
1099 void rkh_sma_post_lifo(RKH_SMA_T *me, const RKH_EVT_T *e);
1100 #endif
1101 
1126 RKH_EVT_T *rkh_sma_get(RKH_SMA_T *me);
1127 
1144 void rkh_sma_dispatch(RKH_SMA_T *me, void *arg);
1145 
1188 void rkh_sma_defer(RKH_QUEUE_T *q, const RKH_EVT_T *e);
1189 
1217 RKH_EVT_T *rkh_sma_recall(RKH_SMA_T *me, RKH_QUEUE_T *q);
1218 
1230 void rkh_sma_clear_info(RKH_SMA_T *me);
1231 
1255 void rkh_sma_get_info(RKH_SMA_T *me, RKH_SMAI_T *psi);
1256 
1257 #ifdef __cplusplus
1258 }
1259 #endif
1260 
1261 /* ------------------------------ Module end ------------------------------- */
1262 #endif
1263 
1264 /* ------------------------------ End of file ------------------------------ */
rkh_sma_dispatch
void rkh_sma_dispatch(RKH_SMA_T *me, void *arg)
For cooperative scheduling policy, this function is used to dispatch the event to the active object b...
rkh_sma_post_lifo
void rkh_sma_post_lifo(RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
Send an event to a state machine application (SMA) as known as active object through a queue using th...
rkh_sma_terminate
void rkh_sma_terminate(RKH_SMA_T *me)
Terminate a state machine application (SMA) as known as active object.
rkh_sma_post_fifo
void rkh_sma_post_fifo(RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
Send an event to a state machine application (SMA) as known as active object through a queue using th...
rkh_sma_get
RKH_EVT_T * rkh_sma_get(RKH_SMA_T *me)
Get an event from the event queue of an state machine application (SMA) as known as active object....
rkh_sma_activate
void rkh_sma_activate(RKH_SMA_T *me, const RKH_EVT_T **qSto, RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize)
Initializes and activates a previously created state machine application (SMA) as known as active obj...
RKH_CFG_FWK_MAX_SMA
#define RKH_CFG_FWK_MAX_SMA
Specify the maximum number of state machine applications (SMA) to be used by the application (can be ...
Definition: rkhcfg.h:88
rkh_sptbl
RKH_SMA_T * rkh_sptbl[RKH_CFG_FWK_MAX_SMA]
Priority arranged table of registered SMA.
Definition: test_rkhfwk_pubsub.c:82
RKH_THREAD_TYPE
#define RKH_THREAD_TYPE
Frequently, the active object has its own task processing loop that waits for the signal to be posted...
Definition: rkhitl.h:2250
RKH_EQ_TYPE
#define RKH_EQ_TYPE
Defines the data type of the event queue for active objects. The event queue can be implemented with ...
Definition: rkhitl.h:2224
RKH_OSSIGNAL_TYPE
#define RKH_OSSIGNAL_TYPE
The os_signal member of RKH_SMA_T is necessary when the underlying OS does not provide an adequate qu...
Definition: rkhitl.h:2274
rkhqueue.h
Specifies the interface of the queue services.
RKH_QUENE_T
rui8_t RKH_QUENE_T
This data type defines the maximum number of elements that any queue can contain.
Definition: rkhqueue.h:97
rkhsm.h
Specifies the interface of the state-machine manager.
rkh_sma_register
void rkh_sma_register(RKH_SMA_T *me)
Registers a state machine application (SMA) as known as active object into the framework,...
rkh_sma_clear_info
void rkh_sma_clear_info(RKH_SMA_T *me)
Clear performance information for a particular state machine application (SMA) as known as active obj...
RKHTask
void(* RKHTask)(RKH_SMA_T *me, void *arg)
Definition: rkhsma.h:861
rkh_sma_recall
RKH_EVT_T * rkh_sma_recall(RKH_SMA_T *me, RKH_QUEUE_T *q)
Recall a deferred event from a given event queue.
rkh_sma_defer
void rkh_sma_defer(RKH_QUEUE_T *q, const RKH_EVT_T *e)
Defer an event to a given separate event queue.
rkhSmaVtbl
const RKHSmaVtbl rkhSmaVtbl
rkh_sma_get_info
void rkh_sma_get_info(RKH_SMA_T *me, RKH_SMAI_T *psi)
Retrieves performance information for a particular state machine application (SMA) as known as active...
RKHActivate
void(* RKHActivate)(RKH_SMA_T *me, const RKH_EVT_T **qSto, RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize)
Definition: rkhsma.h:856
rkh_sma_unregister
void rkh_sma_unregister(RKH_SMA_T *me)
Removes the SMA as known as active object from the priority table, and thus from the framework,...
RKHPostLifo
void(* RKHPostLifo)(RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
Definition: rkhsma.h:873
RKHPostFifo
void(* RKHPostFifo)(RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
Definition: rkhsma.h:865
rkh_sma_ctor
void rkh_sma_ctor(RKH_SMA_T *me, const RKHSmaVtbl *vtbl)
Initializes the virtual table of the active object instance and calls the constructor operation of it...
RKH_EVT_T
Represents events without parameters.
Definition: rkhevt.h:170
RKH_QUEUE_T
Defines the data structure used to maintain information about the queue.
Definition: rkhqueue.h:170
RKH_SM_T
Describes the state machine.
Definition: rkhsm.h:1905
RKH_SMA_T
Describes the SMA (active object in UML).
Definition: rkhsma.h:772
RKH_SMA_T::sm
RKH_SM_T sm
State machine.
Definition: rkhsma.h:777
RKH_SMA_T::os_signal
RKH_OSSIGNAL_TYPE os_signal
OS-dependent object used to signal that an event has been queued.
Definition: rkhsma.h:827
RKH_SMA_T::sinfo
RKH_SMAI_T sinfo
Performance information. This member is optional, thus it could be declared as NULL or eliminated in ...
Definition: rkhsma.h:851
RKH_SMA_T::running
rbool_t running
The Boolean loop variable determining if the thread routine of the SMA is running.
Definition: rkhsma.h:842
RKH_SMA_T::thread
RKH_THREAD_TYPE thread
Virtual pointer.
Definition: rkhsma.h:805
RKH_SMA_T::equeue
RKH_EQ_TYPE equeue
Event queue of the SMA (a.k.a Active Object).
Definition: rkhsma.h:835
RKH_SMAI_T
Defines the data structure into which the collected performance information for state machine is stor...
Definition: rkhsma.h:727
RKH_SMAI_T::exectr
rui16_t exectr
Definition: rkhsma.h:729
RKH_SMAI_T::ndevt
rui16_t ndevt
Definition: rkhsma.h:728
RKHSmaVtbl
Virtual table for the RKH_SMA_T structure.
Definition: rkhsma.h:884
RKHSmaVtbl::post_fifo
RKHPostFifo post_fifo
Definition: rkhsma.h:906
RKHSmaVtbl::activate
RKHActivate activate
Definition: rkhsma.h:887
RKHSmaVtbl::post_lifo
RKHPostLifo post_lifo
Definition: rkhsma.h:910
RKHSmaVtbl::task
RKHTask task
Virtual function to control the execution of the AO (thread task).
Definition: rkhsma.h:902