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