m2mb API docs  25.30.004.0
m2mb API sets documentation
m2mb_hwTmr.h
Go to the documentation of this file.
1 /* $version: 252203 */
2 /*===============================================================================================*/
3 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
25 #ifndef M2MB_HW_TMR_H
26 #define M2MB_HW_TMR_H
27 
28 /* Include ======================================================================================*/
29 
30 /* Global declarations ==========================================================================*/
31 #define M2MB_HWTMR_INVALID 0
32 #define M2MB_HWTMR_INVALID_ATTR 0
33 
34 #define M2MB_HWTMR_PERIODIC_TMR 1
35 #define M2MB_HWTMR_ONESHOT_TMR 0
36 
37 
38 #define M2MB_HWTMR_AUTOSTART 1
39 #define M2MB_HWTMR_NOT_START 0
40 
41 /* for backward compatibility : use M2MB_HWTMR_AUTOSTART */
42 #define M2MB_HW_TASK_AUTOSTART 1 /* use M2MB_HWTMR_AUTOSTART instead */
43 #define M2MB_HW_TASK_NOT_START 0 /* use M2MB_HWTMR_NOT_START instead */
44 
45 /* minimum period allowed: less than this values is changed in the minimum to avoid
46  system issue */
47 #define M2MB_HWTMR_MIN_TIMEOUT ( 100 ) /* minimum allowed timeout in us */
48 
49 /* maximum allowed timeout in us is related to MEmory Wide bus : e.g 32 bit -> 0xFFFFFFFF */
50 #define M2MB_HWTMR_MAX_TIMEOUT ( ( 1<<(sizeof(MEM_W)*4 - 1) ) | ~( 1<<(sizeof(MEM_W)*4 - 1) ) )
51 
52 
53 #define M2MB_HWTMR_UNIT_FACTOR ( 1000 ) /* is ms to us: current base time in us */
54 #define M2MB_HWTMR_TIME_MS(timems) ( timems * M2MB_HWTMR_UNIT_FACTOR )
55 #define M2MB_HWTMR_TIME_S(times) M2MB_HWTMR_TIME_MS(times * 1000 )
56 
57 
58 #ifdef _WIN32
59 #define m2mb_hwTmr_setAttrItem_( h, ... ) m2mb_hwTmr_setAttrItem( h, CMDS_ARGS( __VA_ARGS__ ) )
60 #else
61 #define m2mb_hwTmr_setAttrItem_( h, args... ) m2mb_hwTmr_setAttrItem( h, CMDS_ARGS( args ) )
62 #endif
63 
64 /* Global typedefs ==============================================================================*/
65 
66 /* every enum has been rename to M2MB_HWTMR_xxx in bacward compatibility mode
67  so M2MB_HW_xxx or M2MB_HWTMR_xxx can be used in the enum M2MB_HWTMR_RESULT_E
68 */
69 #define enum_rename( a ) M2MB_HW_##a, M2MB_HWTMR_##a = M2MB_HW_##a
70 #define enum_rename_set( a, val ) M2MB_HW_##a = val, M2MB_HWTMR_##a = M2MB_HW_##a
71 
72 /* error for HW TIMER module */
73 typedef enum M2MB_HWTMR_RESULT
74 {
75  /* M2MB_HWTMR_xxx is the same of M2MB_HWxx_ and they can be interchanged */
76 
77  /* M2MB_HWTMR_SUCCESS */ enum_rename_set( SUCCESS, 0 ),
78  /* M2MB_HWTMR_DELETED, */ enum_rename( DELETED ),
79  /* M2MB_HWTMR_PTR_ERROR, */ enum_rename( PTR_ERROR ),
80  /* M2MB_HWTMR_NO_MEMORY, */ enum_rename( NO_MEMORY ),
81  /* M2MB_HWTMR_TIMER_ERROR, */ enum_rename( TIMER_ERROR ),
82  /* M2MB_HWTMR_TICK_ERROR, */ enum_rename( TICK_ERROR ),
83  /* M2MB_HWTMR_START_ERROR, */ enum_rename( START_ERROR ),
84  /* M2MB_HWTMR_STOP_ERROR, */ enum_rename( STOP_ERROR ),
85  /* M2MB_HWTMR_TICK_ERROR_TIMER_RUN, */ enum_rename( TICK_ERROR_TIMER_RUN ),
86  /* M2MB_HWTMR_PERIOD_ERROR_TIMER_RUN, */ enum_rename( PERIOD_ERROR_TIMER_RUN ),
87  /* M2MB_HWTMR_CB_ERROR_TIMER_RUN, */ enum_rename( CB_ERROR_TIMER_RUN ),
88  /* M2MB_HWTMR_ARG_ERROR_TIMER_RUN, */ enum_rename( ARG_ERROR_TIMER_RUN ),
89  /* M2MB_HWTMR_TIME_DURATION_ERROR_TIMER_RUN,*/ enum_rename( TIME_DURATION_ERROR_TIMER_RUN ),
90  /* M2MB_HWTMR_GENERIC_ERROR, */ enum_rename( GENERIC_ERROR ),
91  /* M2MB_HWTMR_INVALID_ARG, */ enum_rename( INVALID_ARG ),
92  /* M2MB_HWTMR_ERROR, */ enum_rename( ERROR ),
93  /* M2MB_HWTMR_ERROR_INVALID_ARG, */ enum_rename( ERROR_INVALID_ARG ),
94  /* M2MB_HWTMR_ERR_INVALID_PARAM, */ enum_rename( ERR_INVALID_PARAM ),
95  /* M2MB_HWTMR_ERR_NO_MEMORY, */ enum_rename( ERR_NO_MEMORY ),
96  /* M2MB_HWTMR_ERR_NO_RESOURCE, */ enum_rename( ERR_NO_RESOURCE ),
97  /* M2MB_HWTMR_ERR_BUSY, */ enum_rename( ERR_BUSY ),
98  /* M2MB_HWTMR_ERR_NO_ENTRY, */ enum_rename( ERR_NO_ENTRY ),
99  /* M2MB_HWTMR_ERR_NOT_SUPPORTED, */ enum_rename( ERR_NOT_SUPPORTED ),
100  /* M2MB_HWTMR_ERR_TIMEOUT, */ enum_rename( ERR_TIMEOUT ),
101  /* M2MB_HWTMR_ERR_BOUNDS, */ enum_rename( ERR_BOUNDS ),
102  /* M2MB_HWTMR_ERR_BAD_PAYLOAD, */ enum_rename( ERR_BAD_PAYLOAD ),
103  /* M2MB_HWTMR_ERR_EXISTS, */ enum_rename( ERR_EXISTS ),
104  /* M2MB_HWTMR_ERR_NOT_STARTED, */ enum_rename( ERR_NOT_STARTED ),
105  /* M2MB_HWTMR_ERR_ALREADY_EXPIRED, */ enum_rename( ERR_ALREADY_EXPIRED ),
106 
107 
108  /* M2MB_HWTMR_ERR_UNKNOWN = 255, */ enum_rename_set( ERR_UNKNOWN, 255 ),
109  /* M2MB_HWTMR_END, */ enum_rename( END ),
110 
111  ENUM_TO_INT( M2MB_HWTMR_RESULT_E )
112 } M2MB_HWTMR_RESULT_E;
113 
114 
115 /* availbale timer states */
116 typedef enum
117 {
118  M2MB_HWTMR_STATE_TOSTART,
119  M2MB_HWTMR_STATE_RUN,
120  M2MB_HWTMR_STATE_STOP,
121  M2MB_HWTMR_STATE_DELETED
122 } M2MB_HWTMR_STATE_E;
123 
124 /* set or get commands ; not always all availbale */
125 typedef enum
126 {
127  M2MB_HWTMR_SEL_CMD_CREATE_ATTR,
128  M2MB_HWTMR_SEL_CMD_DEL_ATTR,
129  /* name and usrname attribute NOT supported: backward compatibility */
130  M2MB_HWTMR_SEL_CMD_NAME_ATTR_NO_SUPPORTED,
131  M2MB_HWTMR_SEL_CMD_USRNAME_ATTR_NO_SUPPORTED,
132  M2MB_HWTMR_SEL_CMD_CB_FUNC,
133  /* argument to be passed to callback */
134  M2MB_HWTMR_SEL_CMD_ARG_CB,
135  /* period of the timer duration expressed in system ticks
136  In any case the corresponding limit is M2MB_HWTMR_MAX_TIMEOUT in us
137  So upper limit is M2MB_HWTMR_MAX_TIMEOUT[us]/SystemTimeTick[us]
138  */
139  M2MB_HWTMR_SEL_CMD_TICKS_PERIOD,
140  /* FFU: not supported period of elapsing in ticks */
141  M2MB_HWTMR_SEL_CMD_TICKS2ELAPSE,
142  /* period of the timer duration in us units */
143  M2MB_HWTMR_SEL_CMD_TIME_DURATION,
144  /* define if it is periodic or not */
145  M2MB_HWTMR_SEL_CMD_PERIODIC,
146  /* not need to call m2mb_hwTmr_start */
147  M2MB_HWTMR_SEL_CMD_AUTOSTART,
148  M2MB_HWTMR_SEL_CMD_STATE,
149 
150  /* ---- */
151  M2MB_HWTMR_SEL_CMD_END,
152  ENUM_TO_INT( M2MB_HWTMR_SEL_CMD_E )
153 } M2MB_HWTMR_SEL_CMD_E;
154 
155 
156 typedef struct M2MB_HWTMR_HANDLE_TAG *M2MB_HWTMR_HANDLE;
157 typedef struct M2MB_HWTMR_ATTR_HANDLE_TAG *M2MB_HWTMR_ATTR_HANDLE;
158 
159 typedef void ( *USR_HWTMR_CB )( M2MB_HWTMR_HANDLE handle, void *arg );
160 
161 /* Global functions =============================================================================*/
162 /*-----------------------------------------------------------------------------------------------*/
295 /*-----------------------------------------------------------------------------------------------*/
296 
297 M2MB_HWTMR_RESULT_E m2mb_hwTmr_init( M2MB_HWTMR_HANDLE *pTmrHwHandle,
298  M2MB_HWTMR_ATTR_HANDLE *pTmrHwAttr
299  );
300 /*-----------------------------------------------------------------------------------------------*/
332 /*-----------------------------------------------------------------------------------------------*/
333 
334 M2MB_HWTMR_RESULT_E m2mb_hwTmr_deinit( M2MB_HWTMR_HANDLE tmrHwHandle );
335 
336 /*-----------------------------------------------------------------------------------------------*/
363 /*-----------------------------------------------------------------------------------------------*/
364 
365 M2MB_HWTMR_RESULT_E m2mb_hwTmr_start( M2MB_HWTMR_HANDLE tmrHwHandle );
366 
367 /*-----------------------------------------------------------------------------------------------*/
393 /*-----------------------------------------------------------------------------------------------*/
394 
395 M2MB_HWTMR_RESULT_E m2mb_hwTmr_stop( M2MB_HWTMR_HANDLE tmrHwHandle );
396 
397 /*-----------------------------------------------------------------------------------------------*/
430 /*-----------------------------------------------------------------------------------------------*/
431 M2MB_HWTMR_RESULT_E m2mb_hwTmr_setAttrItem( M2MB_HWTMR_ATTR_HANDLE *pTmrHwAttrHandle,
432  UINT8 nCmds,
433  ...
434  );
435 /*-----------------------------------------------------------------------------------------------*/
478 /*-----------------------------------------------------------------------------------------------*/
479 M2MB_HWTMR_RESULT_E m2mb_hwTmr_getItem( M2MB_HWTMR_HANDLE tmrHwHandle,
480  M2MB_HWTMR_SEL_CMD_E selCmd,
481  MEM_W *pOut,
482  void *pIn
483  );
484 /*-----------------------------------------------------------------------------------------------*/
524 /*-----------------------------------------------------------------------------------------------*/
525 M2MB_HWTMR_RESULT_E m2mb_hwTmr_setItem( M2MB_HWTMR_HANDLE tmrHwHandle,
526  M2MB_HWTMR_SEL_CMD_E selCmd,
527  void *pIn
528  );
529 
530 /*-----------------------------------------------------------------------------------------------*/
551 M2MB_HWTMR_RESULT_E m2mb_hwTmr_timeGet_ms( UINT64 *ms_time );
552 
553 
554 /* Global define ================================================================================*/
555 
556 #endif /* M2M_HW_TMR_H */
557 
m2mb_hwTmr_getItem
M2MB_HWTMR_RESULT_E m2mb_hwTmr_getItem(M2MB_HWTMR_HANDLE tmrHwHandle, M2MB_HWTMR_SEL_CMD_E selCmd, MEM_W *pOut, void *pIn)
Get specific properties of the timer.
m2mb_hwTmr_init
M2MB_HWTMR_RESULT_E m2mb_hwTmr_init(M2MB_HWTMR_HANDLE *pTmrHwHandle, M2MB_HWTMR_ATTR_HANDLE *pTmrHwAttr)
Application timer Creation.
m2mb_hwTmr_setAttrItem
M2MB_HWTMR_RESULT_E m2mb_hwTmr_setAttrItem(M2MB_HWTMR_ATTR_HANDLE *pTmrHwAttrHandle, UINT8 nCmds,...)
Set specific attribute for timer creation.
m2mb_hwTmr_start
M2MB_HWTMR_RESULT_E m2mb_hwTmr_start(M2MB_HWTMR_HANDLE tmrHwHandle)
Start application timer.
m2mb_hwTmr_setItem
M2MB_HWTMR_RESULT_E m2mb_hwTmr_setItem(M2MB_HWTMR_HANDLE tmrHwHandle, M2MB_HWTMR_SEL_CMD_E selCmd, void *pIn)
Set specific properties of the timer.
m2mb_hwTmr_deinit
M2MB_HWTMR_RESULT_E m2mb_hwTmr_deinit(M2MB_HWTMR_HANDLE tmrHwHandle)
Timer deinit => deletion.
m2mb_hwTmr_stop
M2MB_HWTMR_RESULT_E m2mb_hwTmr_stop(M2MB_HWTMR_HANDLE tmrHwHandle)
Stop an application timer.
m2mb_hwTmr_timeGet_ms
M2MB_HWTMR_RESULT_E m2mb_hwTmr_timeGet_ms(UINT64 *ms_time)
get time in ms