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 web site: http://sourceforge.net/projects/rkh-reactivesys/
28  * e-mail: francuccilea@gmail.com
29  * ---------------------------------------------------------------------------
30  */
31 
45 /* -------------------------- Development history -------------------------- */
46 /*
47  * 2017.04.05 LeFr v2.4.05 Initial version
48  */
49 
50 /* -------------------------------- Authors -------------------------------- */
51 /*
52  * LeFr Leandro Francucci francuccilea@gmail.com
53  */
54 
55 /* --------------------------------- Notes --------------------------------- */
56 /* --------------------------------- Module -------------------------------- */
57 #ifndef __RKHSMA_H__
58 #define __RKHSMA_H__
59 
60 /* ----------------------------- Include files ----------------------------- */
61 #include "rkhsm.h"
62 #include "rkhqueue.h"
63 
64 /* ---------------------- External C language linkage ---------------------- */
65 #ifdef __cplusplus
66 extern "C" {
67 #endif
68 
69 /* --------------------------------- Macros -------------------------------- */
70 #if ((RKH_CFGPORT_NATIVE_EQUEUE_EN == RKH_ENABLED) && \
71  (RKH_EN_DOXYGEN == RKH_DISABLED))
72  #ifndef RKH_EQ_TYPE
73  #define RKH_EQ_TYPE RKH_QUEUE_T
74  #endif
75 #endif
76 
77 #define RKH_SMA_NAME(smaName_) s_##smaName_
78 
85 #define RKH_SMA_ACCESS_STATE(me_) \
86  ((RKH_SM_T *)me_)->state
87 
88 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
89 
96  #define RKH_SMA_ACCESS_CONST(me_, member_) \
97  ((RKH_SM_T *)me_)->romrkh->member_
98 #else
99 
106  #define RKH_SMA_ACCESS_CONST(me_, member_) \
107  ((RKH_SM_T *)me_)->member_
108 #endif
109 
137 #define RKH_SMA_DCLR(me_) \
138  RKH_DCLR_PTR_TYPE(RKH_SMA_T, me_)
139 
166 #define RKH_SMA_DCLR_TYPE(type_, me_) \
167  RKH_DCLR_PTR_TYPE(type_, me_)
168 
211 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
212 #if RKH_CFGPORT_SMA_QSTO_EN == RKH_ENABLED
213  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
214  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
215  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
216  (const RKH_EVT_T **)qSto_, \
217  qStoSize, \
218  (void *)stkSto_, \
219  (rui32_t)stkSize_)
220  #else
221  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
222  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
223  (const RKH_EVT_T **)qSto_, \
224  qStoSize, \
225  (void *)0, \
226  (rui32_t)0)
227  #endif
228 #else
229  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
230  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
231  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
232  (const RKH_EVT_T **)0, \
233  qStoSize, \
234  (void *)stkSto_, \
235  (rui32_t)stkSize_)
236  #else
237  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
238  ((RKH_SMA_T *)(me_))->vptr->activate(me_, \
239  (const RKH_EVT_T **)0, \
240  qStoSize, \
241  (void *)0, \
242  (rui32_t)0)
243  #endif
244 #endif
245 #else
246 #if RKH_CFGPORT_SMA_QSTO_EN == RKH_ENABLED
247  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
248  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
249  rkh_sma_activate(me_, \
250  (const RKH_EVT_T **)qSto_, \
251  qStoSize, \
252  (void *)stkSto_, \
253  (rui32_t)stkSize_)
254  #else
255  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
256  rkh_sma_activate(me_, \
257  (const RKH_EVT_T **)qSto_, \
258  qStoSize, \
259  (void *)0, \
260  (rui32_t)0)
261  #endif
262 #else
263  #if RKH_CFGPORT_SMA_STK_EN == RKH_ENABLED
264  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
265  rkh_sma_activate(me_, \
266  (const RKH_EVT_T **)0, \
267  qStoSize, \
268  (void *)stkSto_, \
269  (rui32_t)stkSize_)
270  #else
271  #define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_) \
272  rkh_sma_activate(me_, \
273  (const RKH_EVT_T **)0, \
274  qStoSize, \
275  (void *)0, \
276  (rui32_t)0)
277  #endif
278 #endif
279 #endif
280 
348 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
349  #define RKH_SMA_CREATE(type, name, prio, ppty, initialState, \
350  initialAction, initialEvt) \
351  RKH_SM_CONST_CREATE(name, prio, ppty, initialState, initialAction, \
352  initialEvt); \
353  static type RKH_SMA_NAME(name) = MKSMA(&RKH_SM_CONST_NAME(name), \
354  initialState)
355 #else
356  #define RKH_SMA_CREATE(type, name, prio, ppty, initialState, \
357  initialAction, initialEvt) \
358  static type RKH_SMA_NAME(name) = MKSMA(name, \
359  prio, \
360  ppty, \
361  initialState, \
362  initialAction, \
363  initialEvt)
364 #endif
365 
366 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
367  #define RKH_SMA_INIT(me, prio, ppty, initialState, initialAction, \
368  initialEvt)
369 #else
370  #define RKH_SMA_INIT(me, prio, ppty, initialState, initialAction, \
371  initialEvt) \
372  MKRT_SM(me, me, prio, ppty, initialState, initialAction, initialEvt)
373 #endif
374 
375 #if RKH_CFG_SMA_SM_CONST_EN == RKH_ENABLED
376  #define RKH_SMA_GET_OBJ(type, me)
377 #else
378  #define RKH_SMA_GET_OBJ(type, me) \
379  (type *)&RKH_SMA_NAME(me)
380 #endif
381 
391 #define RKH_SMA_DEF_PTR(me_) \
392  RKH_SMA_T *const me_ = (RKH_SMA_T *)&RKH_SMA_NAME(me_)
393 
408 #define RKH_SMA_DEF_PTR_TYPE(type, me_) \
409  type *const me_ = (type *)&RKH_SMA_NAME(me_)
410 
441 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
442  #if defined(RKH_USE_TRC_SENDER)
443  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
444  ((RKH_SMA_T *)(me_))->vptr->post_fifo((me_), (e_), (sender_))
445  #else
446  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
447  ((RKH_SMA_T *)(me_))->vptr->post_fifo((me_), (e_))
448  #endif
449 #else
450  #if defined(RKH_USE_TRC_SENDER)
451  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
452  rkh_sma_post_fifo((me_), (e_), (sender_))
453  #else
454  #define RKH_SMA_POST_FIFO(me_, e_, sender_) \
455  rkh_sma_post_fifo((me_), (e_))
456  #endif
457 #endif
458 
489 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
490  #if defined(RKH_USE_TRC_SENDER)
491  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
492  ((RKH_SMA_T *)(me_))->vptr->post_lifo((me_), (e_), (sender_))
493  #else
494  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
495  ((RKH_SMA_T *)(me_))->vptr->post_lifo((me_), (e_))
496  #endif
497 #else
498  #if defined(RKH_USE_TRC_SENDER)
499  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
500  rkh_sma_post_lifo((me_), (e_), (sender_))
501  #else
502  #define RKH_SMA_POST_LIFO(me_, e_, sender_) \
503  rkh_sma_post_lifo((me_), (e_))
504  #endif
505 #endif
506 
538 #define RKH_ARRAY_SMA_DCLR(_arr, _num) \
539  extern RKH_SMA_T * const *_arr[_num]
540 
573 #define RKH_ARRAY_SMA_DCLR_TYPE(type_, array_, num_) \
574  extern type_ * const * array_[num_]
575 
599 #define RKH_ARRAY_SMA_CREATE(_arr, _num) \
600  RKH_SMA_T * const *_arr[_num] =
601 
626 #define RKH_ARRAY_SMA_CREATE_TYPE(type_, array_, num_) \
627  type_ * const * array_[num_] =
628 
656 #define RKH_ARRAY_SMA(_arr, _ix) *_arr[_ix]
657 
658 #if R_TRC_AO_NAME_EN == RKH_ENABLED
659 
668  #define RKH_GET_AO_NAME(ao) RKH_SMA_ACCESS_CONST(ao, name)
669 #else
670  #define RKH_GET_AO_NAME(ao) noname
671 #endif
672 
681 #define RKH_GET_SMA(_prio) \
682  rkh_sptbl[(rui8_t)(_prio)]
683 
690 #define RKH_GET_PRIO(_ao) \
691  (rui8_t)(RKH_SMA_ACCESS_CONST(_ao, prio))
692 
693 /* -------------------------------- Constants ------------------------------ */
694 /* ------------------------------- Data types ------------------------------ */
703 typedef struct RKH_SMAI_T
704 {
705  rui16_t ndevt;
706  rui16_t exectr;
707 } RKH_SMAI_T;
708 
748 struct RKH_SMA_T
749 {
754  RKH_SM_T sm;
755 
760 #if RKH_CFG_SMA_VFUNCT_EN == RKH_ENABLED
761  const RKHSmaVtbl *vptr;
762 #endif
763 
781 #if RKH_CFGPORT_SMA_THREAD_EN == RKH_ENABLED
782  RKH_THREAD_TYPE thread;
783 
803 #if RKH_CFGPORT_SMA_THREAD_DATA_EN == RKH_ENABLED
804  RKH_OSSIGNAL_TYPE os_signal;
805 #endif
806 #endif
807 
812  RKH_EQ_TYPE equeue;
813 
819  rbool_t running;
820 
827 #if RKH_CFG_SMA_GET_INFO_EN == RKH_ENABLED
828  RKH_SMAI_T sinfo;
829 #endif
830 };
831 
833 typedef void (*RKHActivate)(RKH_SMA_T *me,
834  const RKH_EVT_T **qSto, RKH_QUENE_T qSize,
835  void *stkSto, rui32_t stkSize);
836 
838 typedef void (*RKHTask)(RKH_SMA_T *me, void *arg);
839 
841 #if defined(RKH_USE_TRC_SENDER)
842 typedef void (*RKHPostFifo)(RKH_SMA_T *me, const RKH_EVT_T *e,
843  const void *const sender);
844 #else
845 typedef void (*RKHPostFifo)(RKH_SMA_T *me, const RKH_EVT_T *e);
846 #endif
847 
849 #if defined(RKH_USE_TRC_SENDER)
850 typedef void (*RKHPostLifo)(RKH_SMA_T *me, const RKH_EVT_T *e,
851  const void *const sender);
852 #else
853 typedef void (*RKHPostLifo)(RKH_SMA_T *me, const RKH_EVT_T *e);
854 #endif
855 
860 struct RKHSmaVtbl
861 {
864  RKHActivate activate;
865 
875  RKHTask task;
876 
879  RKHPostFifo post_fifo;
880 
883  RKHPostLifo post_lifo;
884 };
885 
886 /* -------------------------- External variables --------------------------- */
888 extern const RKHSmaVtbl rkhSmaVtbl;
889 
899 extern RKH_SMA_T *rkh_sptbl[RKH_CFG_FWK_MAX_SMA];
900 
901 /* -------------------------- Function prototypes -------------------------- */
902 /* -------------------- External C language linkage end -------------------- */
911 void rkh_sma_register(RKH_SMA_T *me);
912 
921 void rkh_sma_unregister(RKH_SMA_T *me);
922 
936 void rkh_sma_ctor(RKH_SMA_T *me, const RKHSmaVtbl *vtbl);
937 
968 void rkh_sma_activate(RKH_SMA_T *me, const RKH_EVT_T * *qSto,
969  RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize);
970 
995 void rkh_sma_terminate(RKH_SMA_T *me);
996 
997 #if defined(RKH_USE_TRC_SENDER)
998 
1029 void rkh_sma_post_fifo(RKH_SMA_T *me, const RKH_EVT_T *e,
1030  const void *const sender);
1031 #else
1032 void rkh_sma_post_fifo(RKH_SMA_T *me, const RKH_EVT_T *e);
1033 #endif
1034 
1035 #if defined(RKH_USE_TRC_SENDER)
1036 
1068 void rkh_sma_post_lifo(RKH_SMA_T *me, const RKH_EVT_T *e,
1069  const void *const sender);
1070 
1071 #else
1072 void rkh_sma_post_lifo(RKH_SMA_T *me, const RKH_EVT_T *e);
1073 #endif
1074 
1099 RKH_EVT_T *rkh_sma_get(RKH_SMA_T *me);
1100 
1143 void rkh_sma_defer(RKH_QUEUE_T *q, const RKH_EVT_T *e);
1144 
1172 RKH_EVT_T *rkh_sma_recall(RKH_SMA_T *me, RKH_QUEUE_T *q);
1173 
1185 void rkh_sma_clear_info(RKH_SMA_T *me);
1186 
1210 void rkh_sma_get_info(RKH_SMA_T *me, RKH_SMAI_T *psi);
1211 
1212 #ifdef __cplusplus
1213 }
1214 #endif
1215 
1216 /* ------------------------------ Module end ------------------------------- */
1217 #endif
1218 
1219 /* ------------------------------ End of file ------------------------------ */
RKH_SMA_T::running
rbool_t running
The Boolean loop variable determining if the thread routine of the SMA is running.
Definition: rkhsma.h:819
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_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...
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...
RKHPostFifo
void(* RKHPostFifo)(RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
Definition: rkhsma.h:842
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_SMA_T
Describes the SMA (active object in UML).
Definition: rkhsma.h:748
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:2220
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:95
RKH_EVT_T
Represents events without parameters.
Definition: rkhevt.h:167
RKH_QUEUE_T
Defines the data structure used to maintain information about the queue.
Definition: rkhqueue.h:167
rkh_sptbl
RKH_SMA_T * rkh_sptbl[RKH_CFG_FWK_MAX_SMA]
Priority arranged table of registered SMA.
RKH_SMA_T::equeue
RKH_EQ_TYPE equeue
Event queue of the SMA (a.k.a Active Object).
Definition: rkhsma.h:812
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.
RKH_SMA_T::sm
RKH_SM_T sm
State machine.
Definition: rkhsma.h:754
RKHTask
void(* RKHTask)(RKH_SMA_T *me, void *arg)
Definition: rkhsma.h:838
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_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...
rkhSmaVtbl
const RKHSmaVtbl rkhSmaVtbl
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, which implies to store a pointer to the SMA in the priority table.
RKH_SM_T
Describes the state machine.
Definition: rkhsm.h:1712
RKHSmaVtbl
Virtual table for the RKH_SMA_T structure.
Definition: rkhsma.h:860
RKH_SMA_T::thread
RKH_THREAD_TYPE thread
Virtual pointer.
Definition: rkhsma.h:782
RKHPostLifo
void(* RKHPostLifo)(RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
Definition: rkhsma.h:850
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:828
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_SMAI_T
Defines the data structure into which the collected performance information for state machine is stor...
Definition: rkhsma.h:703
RKHSmaVtbl::post_fifo
RKHPostFifo post_fifo
Definition: rkhsma.h:879
RKH_SMAI_T::exectr
rui16_t exectr
Definition: rkhsma.h:706
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_SMAI_T::ndevt
rui16_t ndevt
Definition: rkhsma.h:705
rkh_sma_terminate
void rkh_sma_terminate(RKH_SMA_T *me)
Terminate a state machine application (SMA) as known as active object.
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:2244
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:804
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:86
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...
RKHSmaVtbl::task
RKHTask task
Virtual function to control the execution of the AO (thread task).
Definition: rkhsma.h:875
rkhsm.h
Specifies the interface of the state-machine manager.
RKHActivate
void(* RKHActivate)(RKH_SMA_T *me, const RKH_EVT_T **qSto, RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize)
Definition: rkhsma.h:833
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:2194
RKHSmaVtbl::activate
RKHActivate activate
Definition: rkhsma.h:864
RKHSmaVtbl::post_lifo
RKHPostLifo post_lifo
Definition: rkhsma.h:883
rkhqueue.h
Specifies the interface of the queue services.