m2mb API docs  25.30.006.0
m2mb API sets documentation
m2mb_os.h
Go to the documentation of this file.
1 /* $version: 252304 */
2 /*===============================================================================================*/
3 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
29 #ifndef M2MB_OS_H
30 #define M2MB_OS_H
31 
32 /* Include ======================================================================================*/
33 
34 /* Global declarations ==========================================================================*/
35 #define M2MB_OS_TASK_INVALID 0
36 #define M2MB_OS_TASK_INVALID_ATTR 0
37 
38 #define M2MB_OS_TASK_AUTOSTART 1
39 #define M2MB_OS_TASK_NOT_START 0
40 
41 #define M2MB_OS_ISR_ON 1
42 #define M2MB_OS_ISR_OFF 0
43 
44 /* in bytes */
45 #define M2MB_OS_MIN_STACK_SIZE 1024
46 
47 /* category for errno */
48 #define M2MB_FS_CAT ( (UINT32)0 )
49 #define M2MB_SMS_CAT ( (UINT32)1 )
50 #define M2MB_GNSS_CAT ( (UINT32)2 )
51 #define M2MB_OS_CAT ( (UINT32)3 )
52 
53 /*-----------------------------------------------------------------------------------------------
54 
55  can be called directly without specify CMDS_ARGS
56  m2mb_os_taskSetAttrItem_( &taskAttrHandle,
57  M2MB_OS_TASK_SEL_CMD_CREATE_ATTR, NULL,
58  M2MB_OS_TASK_SEL_CMD_NAME, "myTask",
59  M2MB_OS_TASK_SEL_CMD_PRIORITY, 201,
60  M2MB_OS_TASK_SEL_CMD_PREEMPTIONTH, 201,
61  M2MB_OS_TASK_SEL_CMD_AUTOSTART, M2MB_OS_TASK_AUTOSTART,
62  M2MB_OS_TASK_SEL_CMD_USRNAME, "myUserTask"
63  );
64  -----------------------------------------------------------------------------------------------*/
65 #ifdef _WIN32
66 #define m2mb_os_taskSetAttrItem_( h, ... ) m2mb_os_taskSetAttrItem( h, CMDS_ARGS( __VA_ARGS__ ) )
67 #else
68 #define m2mb_os_taskSetAttrItem_( h, args... ) m2mb_os_taskSetAttrItem( h, CMDS_ARGS( args ) )
69 #endif
70 
71 /*-----------------------------------------------------------------------------------------------*/
72 
73 /* Global typedefs ==============================================================================*/
74 typedef struct M2MB_OS_TASK_ATTR_HANDLE_TAG *M2MB_OS_TASK_ATTR_HANDLE;
75 typedef struct M2MB_OS_TASK_HANDLE_TAG *M2MB_OS_TASK_HANDLE;
76 
77 /* specified type for entry function of task */
78 typedef void( *ENTRY_FN )( void * );
79 
80 typedef enum
81 {
82  M2MB_OS_TASK_SEL_CMD_CREATE_ATTR,
83  M2MB_OS_TASK_SEL_CMD_DEL_ATTR,
84  /* use as Os name : the name during task creation */
85  M2MB_OS_TASK_SEL_CMD_NAME,
86  /* if set, usr name could be different from initial CMD NAME */
87  M2MB_OS_TASK_SEL_CMD_USRNAME,
88  M2MB_OS_TASK_SEL_CMD_STACK_START,
89  M2MB_OS_TASK_SEL_CMD_STACK_SIZE,
90  /* the higher the command associated value, the lower the priority */
91  M2MB_OS_TASK_SEL_CMD_PRIORITY,
92  /* task with priority higher than the command associated value, can preempt the configured task */
93  M2MB_OS_TASK_SEL_CMD_PREEMPTIONTH,
94  /* time slice: use max ticks for task to run when other tasks with same priority are ready.
95  Task slice feature could not really be used by scheduler. Ask for the specific product or perform
96  a little test application to verify if it is supported by OS
97  */
98  M2MB_OS_TASK_SEL_CMD_TSLICE,
99  /* start task soon after m2mb_os_taskCreate is called: no need to call m2mb_os_taskResume */
100  M2MB_OS_TASK_SEL_CMD_AUTOSTART,
101  /* state of the task: see M2MB_OS_TASK_STATE_E */
102  M2MB_OS_TASK_SEL_CMD_STATE,
103  /* task running count */
104  M2MB_OS_TASK_SEL_CMD_RUN_CNT,
105 
106  /* ---- */
107  M2MB_OS_TASK_SEL_CMD_END,
108  ENUM_TO_INT( M2MB_OS_TASK_SEL_CMD_E )
109 } M2MB_OS_TASK_SEL_CMD_E;
110 
111 typedef enum
112 {
113  M2MB_OS_TASK_STATE_READY,
114  M2MB_OS_TASK_STATE_COMPLETED,
115  M2MB_OS_TASK_STATE_TERMINATED,
116  M2MB_OS_TASK_STATE_SUSP,
117  M2MB_OS_TASK_STATE_SLEEP,
118  M2MB_OS_TASK_STATE_QUEUE_SUSP,
119  M2MB_OS_TASK_STATE_SEMAPHORE_SUSP,
120  M2MB_OS_TASK_STATE_SIG_SUSP,
121  M2MB_OS_TASK_STATE_BLOCK_MEM_SUSP,
122  M2MB_OS_TASK_STATE_BYTE_MEM_SUSP,
123  M2MB_OS_TASK_STATE_MUTEX_SUSP = 0x0D,
124 
125  /* ---- */
126  M2MB_OS_TASK_STATE_END,
127  ENUM_TO_INT( M2MB_OS_TASK_STATE_E )
128 } M2MB_OS_TASK_STATE_E;
129 
130 typedef enum
131 {
132  M2MB_OS_MEMINFO_FRAGMENTS, /* the total number of memory fragments */
133  M2MB_OS_MEMINFO_BYTES_AVAILABLE, /* the total number of available bytes */
134  M2MB_OS_MEMINFO_SIZE, /* the total number of memory size */
135 
136  M2MB_OS_MEMINFO_BYTES_MAX_OCCUPATION = 6, /* the max occupation of bytes that have been allocated */
137  /* ---- */
138  M2MB_OS_MEMINFO_END,
139  ENUM_TO_INT( M2MB_OS_MEMINFO_E )
140 } M2MB_OS_MEMINFO_E;
141 
142 /* Global functions =============================================================================*/
143 
144 /*-----------------------------------------------------------------------------------------------*/
178 /*-----------------------------------------------------------------------------------------------*/
179 
180 UINT32 M2MB_OS_MS2TICKS( UINT32 ms );
181 
182 /*-----------------------------------------------------------------------------------------------*/
218 /*-----------------------------------------------------------------------------------------------*/
219 void *m2mb_os_malloc( UINT32 size );
220 
221 /*-----------------------------------------------------------------------------------------------*/
264 /*-----------------------------------------------------------------------------------------------*/
265 void *m2mb_os_calloc( UINT32 size );
266 
267 /*-----------------------------------------------------------------------------------------------*/
302 /*-----------------------------------------------------------------------------------------------*/
303 M2MB_OS_RESULT_E m2mb_os_free( void *pMem );
304 
305 /*-----------------------------------------------------------------------------------------------*/
329 /*-----------------------------------------------------------------------------------------------*/
330 M2MB_OS_RESULT_E m2mb_os_init( void );
331 
332 /*-----------------------------------------------------------------------------------------------*/
436 /*-----------------------------------------------------------------------------------------------*/
437 M2MB_OS_RESULT_E m2mb_os_taskCreate( M2MB_OS_TASK_HANDLE *pTaskHandle,
438  M2MB_OS_TASK_ATTR_HANDLE *pTaskAttr,
439  ENTRY_FN entryFn,
440  void *pArg
441  );
442 
443 /*-----------------------------------------------------------------------------------------------*/
573 /*-----------------------------------------------------------------------------------------------*/
574 M2MB_OS_RESULT_E m2mb_os_taskGetItem( M2MB_OS_TASK_HANDLE taskHandle,
575  M2MB_OS_TASK_SEL_CMD_E selCmd,
576  MEM_W *pOut,
577  void *pIn
578  );
579 
580 
581 /*-----------------------------------------------------------------------------------------------*/
627 /*-----------------------------------------------------------------------------------------------*/
628 M2MB_OS_RESULT_E m2mb_os_taskSetItem( M2MB_OS_TASK_HANDLE taskHandle,
629  M2MB_OS_TASK_SEL_CMD_E selCmd,
630  void *pIn
631  );
632 
633 /*-----------------------------------------------------------------------------------------------*/
712 /*-----------------------------------------------------------------------------------------------*/
713 M2MB_OS_RESULT_E m2mb_os_taskSetAttrItem( M2MB_OS_TASK_ATTR_HANDLE *pTaskAttrHandle,
714  UINT8 nCmds,
715  ...
716  );
717 
718 /*-----------------------------------------------------------------------------------------------*/
754 /*-----------------------------------------------------------------------------------------------*/
755 M2MB_OS_RESULT_E m2mb_os_taskSleep( UINT32 ticks );
756 
757 /*-----------------------------------------------------------------------------------------------*/
785 /*-----------------------------------------------------------------------------------------------*/
786 M2MB_OS_TASK_HANDLE m2mb_os_taskGetId( void );
787 
788 /*-----------------------------------------------------------------------------------------------*/
826 /*-----------------------------------------------------------------------------------------------*/
827 M2MB_OS_RESULT_E m2mb_os_taskSuspend( M2MB_OS_TASK_HANDLE taskHandle );
828 
829 /*-----------------------------------------------------------------------------------------------*/
864 /*-----------------------------------------------------------------------------------------------*/
865 M2MB_OS_RESULT_E m2mb_os_taskResume( M2MB_OS_TASK_HANDLE taskHandle );
866 
867 /*-----------------------------------------------------------------------------------------------*/
901 /*-----------------------------------------------------------------------------------------------*/
902 M2MB_OS_RESULT_E m2mb_os_taskTerminate( M2MB_OS_TASK_HANDLE taskHandle );
903 
904 /*-----------------------------------------------------------------------------------------------*/
940 /*-----------------------------------------------------------------------------------------------*/
941 M2MB_OS_RESULT_E m2mb_os_taskRestart( M2MB_OS_TASK_HANDLE taskHandle );
942 
943 /*-----------------------------------------------------------------------------------------------*/
982 /*-----------------------------------------------------------------------------------------------*/
983 M2MB_OS_RESULT_E m2mb_os_taskDelete( M2MB_OS_TASK_HANDLE taskHandle );
984 
985 /*-----------------------------------------------------------------------------------------------*/
1034 /*-----------------------------------------------------------------------------------------------*/
1035 M2MB_OS_RESULT_E m2mb_os_taskCooperate( void );
1036 
1037 /*-----------------------------------------------------------------------------------------------*/
1137 /*-----------------------------------------------------------------------------------------------*/
1138 M2MB_OS_RESULT_E m2mb_os_taskWaitAbort( M2MB_OS_TASK_HANDLE taskHandle );
1139 
1140 /*-----------------------------------------------------------------------------------------------*/
1170 /*-----------------------------------------------------------------------------------------------*/
1171 MEM_W m2mb_os_getSysTicks( void );
1172 
1173 /*-----------------------------------------------------------------------------------------------*/
1204 /*-----------------------------------------------------------------------------------------------*/
1205 M2MB_OS_RESULT_E m2mb_os_setSysTicks( UINT32 newTick );
1206 
1207 /*-----------------------------------------------------------------------------------------------*/
1232 /*-----------------------------------------------------------------------------------------------*/
1233 FLOAT32 m2mb_os_getSysTickDuration_ms( void );
1234 
1235 /*-----------------------------------------------------------------------------------------------*/
1271 /*-----------------------------------------------------------------------------------------------*/
1272 M2MB_OS_RESULT_E m2mb_os_get_errno( UINT32 *pCategory, INT32 *pErrno );
1273 
1274 /*-----------------------------------------------------------------------------------------------*/
1275 /*-----------------------------------------------------------------------------------------------*/
1328 /*-----------------------------------------------------------------------------------------------*/
1329 M2MB_OS_RESULT_E m2mb_os_memInfo( M2MB_OS_MEMINFO_E memInfoSelect, MEM_W *pOut );
1330 
1331 /*-----------------------------------------------------------------------------------------------*/
1382 /*-----------------------------------------------------------------------------------------------*/
1383 void *m2mb_os_realloc( void *ptr, UINT32 size );
1384 
1385 /*------------------------------------------------------------------------------------------------*/
1423 M2MB_OS_RESULT_E m2mb_os_RAMAvail( MEM_W *p_total, MEM_W *p_available );
1424 
1425 
1426 #endif /* M2MB_OS_H */
m2mb_os_taskCreate
M2MB_OS_RESULT_E m2mb_os_taskCreate(M2MB_OS_TASK_HANDLE *pTaskHandle, M2MB_OS_TASK_ATTR_HANDLE *pTaskAttr, ENTRY_FN entryFn, void *pArg)
Create application task.
m2mb_os_free
M2MB_OS_RESULT_E m2mb_os_free(void *pMem)
Free allocated memory.
m2mb_os_taskSetItem
M2MB_OS_RESULT_E m2mb_os_taskSetItem(M2MB_OS_TASK_HANDLE taskHandle, M2MB_OS_TASK_SEL_CMD_E selCmd, void *pIn)
Set specific task properties.
m2mb_os_taskCooperate
M2MB_OS_RESULT_E m2mb_os_taskCooperate(void)
Make task to cooperate by releasing scheduler control.
m2mb_os_taskDelete
M2MB_OS_RESULT_E m2mb_os_taskDelete(M2MB_OS_TASK_HANDLE taskHandle)
Task delete.
m2mb_os_taskResume
M2MB_OS_RESULT_E m2mb_os_taskResume(M2MB_OS_TASK_HANDLE taskHandle)
Resume suspended application task.
m2mb_os_taskRestart
M2MB_OS_RESULT_E m2mb_os_taskRestart(M2MB_OS_TASK_HANDLE taskHandle)
Task restart.
m2mb_os_getSysTicks
MEM_W m2mb_os_getSysTicks(void)
Get system time in ticks.
m2mb_os_init
M2MB_OS_RESULT_E m2mb_os_init(void)
Initialization of OS.
m2mb_os_setSysTicks
M2MB_OS_RESULT_E m2mb_os_setSysTicks(UINT32 newTick)
Set start system time in ticks.
m2mb_os_malloc
void * m2mb_os_malloc(UINT32 size)
Allocates bytes of memory.
m2mb_os_taskGetId
M2MB_OS_TASK_HANDLE m2mb_os_taskGetId(void)
Retrieves handle to the currently executing task.
m2mb_os_taskSuspend
M2MB_OS_RESULT_E m2mb_os_taskSuspend(M2MB_OS_TASK_HANDLE taskHandle)
Suspend application task.
m2mb_os_getSysTickDuration_ms
FLOAT32 m2mb_os_getSysTickDuration_ms(void)
Get duration of system tick in ms.
m2mb_os_calloc
void * m2mb_os_calloc(UINT32 size)
Allocates bytes of memory and init space with 0.
m2mb_os_taskTerminate
M2MB_OS_RESULT_E m2mb_os_taskTerminate(M2MB_OS_TASK_HANDLE taskHandle)
Terminates application task.
M2MB_OS_MS2TICKS
UINT32 M2MB_OS_MS2TICKS(UINT32 ms)
Convert ms to ticks.
m2mb_os_get_errno
M2MB_OS_RESULT_E m2mb_os_get_errno(UINT32 *pCategory, INT32 *pErrno)
Allow to get Errno saved in relative task environment.
m2mb_os_taskGetItem
M2MB_OS_RESULT_E m2mb_os_taskGetItem(M2MB_OS_TASK_HANDLE taskHandle, M2MB_OS_TASK_SEL_CMD_E selCmd, MEM_W *pOut, void *pIn)
Get specific task properties.
m2mb_os_taskWaitAbort
M2MB_OS_RESULT_E m2mb_os_taskWaitAbort(M2MB_OS_TASK_HANDLE taskHandle)
Abort suspension of specified task.
m2mb_os_taskSetAttrItem
M2MB_OS_RESULT_E m2mb_os_taskSetAttrItem(M2MB_OS_TASK_ATTR_HANDLE *pTaskAttrHandle, UINT8 nCmds,...)
Set specific attribute for task creation.
m2mb_os_taskSleep
M2MB_OS_RESULT_E m2mb_os_taskSleep(UINT32 ticks)
Suspend current task for specified time in ticks.
m2mb_os_memInfo
M2MB_OS_RESULT_E m2mb_os_memInfo(M2MB_OS_MEMINFO_E memInfoSelect, MEM_W *pOut)
Returns dynamic memory (HEAP) information.
m2mb_os_realloc
void * m2mb_os_realloc(void *ptr, UINT32 size)
Dynamic memory reallocation.
m2mb_os_RAMAvail
M2MB_OS_RESULT_E m2mb_os_RAMAvail(MEM_W *p_total, MEM_W *p_available)
m2mb_os_RAMAvail