m2mb API docs  25.21.002
m2mb API sets documentation
m2mb_os.h
Go to the documentation of this file.
1 /*===============================================================================================*/
2 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
28 #ifndef M2MB_OS_H
29 #define M2MB_OS_H
30 
31 /* Include ======================================================================================*/
32 
33 /* Global declarations ==========================================================================*/
34 #define M2MB_OS_TASK_INVALID 0
35 #define M2MB_OS_TASK_INVALID_ATTR 0
36 
37 #define M2MB_OS_TASK_AUTOSTART 1
38 #define M2MB_OS_TASK_NOT_START 0
39 
40 #define M2MB_OS_ISR_ON 1
41 #define M2MB_OS_ISR_OFF 0
42 
43 /* in bytes */
44 #define M2MB_OS_MIN_STACK_SIZE 1024
45 
46 /* category for errno */
47 #define M2MB_FS_CAT ( (UINT32)0 )
48 #define M2MB_SMS_CAT ( (UINT32)1 )
49 #define M2MB_GNSS_CAT ( (UINT32)2 )
50 #define M2MB_OS_CAT ( (UINT32)3 )
51 
52 /*-----------------------------------------------------------------------------------------------
53 
54  can be called directly without specify CMDS_ARGS
55  m2mb_os_taskSetAttrItem_( &taskAttrHandle,
56  M2MB_OS_TASK_SEL_CMD_CREATE_ATTR, NULL,
57  M2MB_OS_TASK_SEL_CMD_NAME, "myTask",
58  M2MB_OS_TASK_SEL_CMD_PRIORITY, 201,
59  M2MB_OS_TASK_SEL_CMD_PREEMPTIONTH, 201,
60  M2MB_OS_TASK_SEL_CMD_AUTOSTART, M2MB_OS_TASK_AUTOSTART,
61  M2MB_OS_TASK_SEL_CMD_USRNAME, "myUserTask"
62  );
63  -----------------------------------------------------------------------------------------------*/
64 #ifdef _WIN32
65 #define m2mb_os_taskSetAttrItem_( h, ... ) m2mb_os_taskSetAttrItem( h, CMDS_ARGS( __VA_ARGS__ ) )
66 #else
67 #define m2mb_os_taskSetAttrItem_( h, args... ) m2mb_os_taskSetAttrItem( h, CMDS_ARGS( args ) )
68 #endif
69 
70 /*-----------------------------------------------------------------------------------------------*/
71 
72 /* Global typedefs ==============================================================================*/
73 typedef struct M2MB_OS_TASK_ATTR_HANDLE_TAG *M2MB_OS_TASK_ATTR_HANDLE;
74 typedef struct M2MB_OS_TASK_HANDLE_TAG *M2MB_OS_TASK_HANDLE;
75 
76 /* specified type for entry function of task */
77 typedef void( *ENTRY_FN )( void * );
78 
79 typedef enum
80 {
81  M2MB_OS_TASK_SEL_CMD_CREATE_ATTR,
82  M2MB_OS_TASK_SEL_CMD_DEL_ATTR,
83  /* use as Os name : the name during task creation */
84  M2MB_OS_TASK_SEL_CMD_NAME,
85  /* if set, usr name could be different from initial CMD NAME */
86  M2MB_OS_TASK_SEL_CMD_USRNAME,
87  M2MB_OS_TASK_SEL_CMD_STACK_START,
88  M2MB_OS_TASK_SEL_CMD_STACK_SIZE,
89  M2MB_OS_TASK_SEL_CMD_PRIORITY,
90  M2MB_OS_TASK_SEL_CMD_PREEMPTIONTH,
91  /* time slice: use max ticks for task to run when other tasks with same priority are ready */
92  M2MB_OS_TASK_SEL_CMD_TSLICE,
93  /* start task soon after m2mb_os_taskCreate is called: no need to call m2mb_os_taskResume */
94  M2MB_OS_TASK_SEL_CMD_AUTOSTART,
95 
96  /* state of the task: see M2MB_OS_TASK_STATE_E */
97  M2MB_OS_TASK_SEL_CMD_STATE,
98  /* task running count */
99  M2MB_OS_TASK_SEL_CMD_RUN_CNT,
100 
101  /* ---- */
102  M2MB_OS_TASK_SEL_CMD_END,
103  ENUM_TO_INT( M2MB_OS_TASK_SEL_CMD_E )
104 } M2MB_OS_TASK_SEL_CMD_E;
105 
106 typedef enum
107 {
108  M2MB_OS_TASK_STATE_READY,
109  M2MB_OS_TASK_STATE_COMPLETED,
110  M2MB_OS_TASK_STATE_TERMINATED,
111  M2MB_OS_TASK_STATE_SUSP,
112  M2MB_OS_TASK_STATE_SLEEP,
113  M2MB_OS_TASK_STATE_QUEUE_SUSP,
114  M2MB_OS_TASK_STATE_SEMAPHORE_SUSP,
115  M2MB_OS_TASK_STATE_SIG_SUSP,
116  M2MB_OS_TASK_STATE_BLOCK_MEM_SUSP,
117  M2MB_OS_TASK_STATE_BYTE_MEM_SUSP,
118  M2MB_OS_TASK_STATE_MUTEX_SUSP = 0x0D,
119 
120  /* ---- */
121  M2MB_OS_TASK_STATE_END,
122  ENUM_TO_INT( M2MB_OS_TASK_STATE_E )
123 } M2MB_OS_TASK_STATE_E;
124 
125 typedef enum
126 {
127  M2MB_OS_MEMINFO_FRAGMENTS, /* the total number of memory fragments */
128  M2MB_OS_MEMINFO_BYTES_AVAILABLE, /* the total number of available bytes */
129  M2MB_OS_MEMINFO_SIZE, /* the total number of memory size */
130 
131  M2MB_OS_MEMINFO_BYTES_MAX_OCCUPATION = 6, /* the max occupation of bytes that have been allocated */
132  /* ---- */
133  M2MB_OS_MEMINFO_END,
134  ENUM_TO_INT( M2MB_OS_MEMINFO_E )
135 } M2MB_OS_MEMINFO_E;
136 
137 /* Global functions =============================================================================*/
138 
139 /*-----------------------------------------------------------------------------------------------*/
173 /*-----------------------------------------------------------------------------------------------*/
174 
175 UINT32 M2MB_OS_MS2TICKS( UINT32 ms );
176 
177 /*-----------------------------------------------------------------------------------------------*/
214 /*-----------------------------------------------------------------------------------------------*/
215 void *m2mb_os_malloc( UINT32 size );
216 
217 /*-----------------------------------------------------------------------------------------------*/
261 /*-----------------------------------------------------------------------------------------------*/
262 void *m2mb_os_calloc( UINT32 size );
263 
264 /*-----------------------------------------------------------------------------------------------*/
301 /*-----------------------------------------------------------------------------------------------*/
302 M2MB_OS_RESULT_E m2mb_os_free( void *pMem );
303 
304 /*-----------------------------------------------------------------------------------------------*/
328 /*-----------------------------------------------------------------------------------------------*/
329 M2MB_OS_RESULT_E m2mb_os_init( void );
330 
331 /*-----------------------------------------------------------------------------------------------*/
436 /*-----------------------------------------------------------------------------------------------*/
437 M2MB_OS_RESULT_E m2mb_os_taskCreate(
438  M2MB_OS_TASK_HANDLE *pTaskHandle,
439  M2MB_OS_TASK_ATTR_HANDLE *pTaskAttr,
440  ENTRY_FN entryFn,
441  void *pArg
442 );
443 
444 /*-----------------------------------------------------------------------------------------------*/
574 /*-----------------------------------------------------------------------------------------------*/
575 M2MB_OS_RESULT_E m2mb_os_taskGetItem(
576  M2MB_OS_TASK_HANDLE taskHandle,
577  M2MB_OS_TASK_SEL_CMD_E selCmd,
578  MEM_W *pOut,
579  void *pIn
580 );
581 
582 
583 /*-----------------------------------------------------------------------------------------------*/
629 /*-----------------------------------------------------------------------------------------------*/
630 M2MB_OS_RESULT_E m2mb_os_taskSetItem(
631  M2MB_OS_TASK_HANDLE taskHandle,
632  M2MB_OS_TASK_SEL_CMD_E selCmd,
633  void *pIn
634 );
635 
636 /*-----------------------------------------------------------------------------------------------*/
713 /*-----------------------------------------------------------------------------------------------*/
714 M2MB_OS_RESULT_E m2mb_os_taskSetAttrItem(
715  M2MB_OS_TASK_ATTR_HANDLE *pTaskAttrHandle,
716  UINT8 nCmds,
717  ...
718 );
719 
720 /*-----------------------------------------------------------------------------------------------*/
756 /*-----------------------------------------------------------------------------------------------*/
757 M2MB_OS_RESULT_E m2mb_os_taskSleep( UINT32 ticks );
758 
759 /*-----------------------------------------------------------------------------------------------*/
788 /*-----------------------------------------------------------------------------------------------*/
789 M2MB_OS_TASK_HANDLE m2mb_os_taskGetId( void );
790 
791 /*-----------------------------------------------------------------------------------------------*/
824 /*-----------------------------------------------------------------------------------------------*/
825 M2MB_OS_RESULT_E m2mb_os_taskSuspend( M2MB_OS_TASK_HANDLE taskHandle );
826 
827 /*-----------------------------------------------------------------------------------------------*/
862 /*-----------------------------------------------------------------------------------------------*/
863 M2MB_OS_RESULT_E m2mb_os_taskResume( M2MB_OS_TASK_HANDLE taskHandle );
864 
865 /*-----------------------------------------------------------------------------------------------*/
902 /*-----------------------------------------------------------------------------------------------*/
903 M2MB_OS_RESULT_E m2mb_os_taskTerminate( M2MB_OS_TASK_HANDLE taskHandle );
904 
905 /*-----------------------------------------------------------------------------------------------*/
942 /*-----------------------------------------------------------------------------------------------*/
943 M2MB_OS_RESULT_E m2mb_os_taskRestart( M2MB_OS_TASK_HANDLE taskHandle );
944 
945 /*-----------------------------------------------------------------------------------------------*/
987 /*-----------------------------------------------------------------------------------------------*/
988 M2MB_OS_RESULT_E m2mb_os_taskDelete( M2MB_OS_TASK_HANDLE taskHandle );
989 
990 /*-----------------------------------------------------------------------------------------------*/
1040 /*-----------------------------------------------------------------------------------------------*/
1041 M2MB_OS_RESULT_E m2mb_os_taskCooperate( void );
1042 
1043 /*-----------------------------------------------------------------------------------------------*/
1143 /*-----------------------------------------------------------------------------------------------*/
1144 M2MB_OS_RESULT_E m2mb_os_taskWaitAbort( M2MB_OS_TASK_HANDLE taskHandle );
1145 
1146 /*-----------------------------------------------------------------------------------------------*/
1177 /*-----------------------------------------------------------------------------------------------*/
1178 MEM_W m2mb_os_getSysTicks( void );
1179 
1180 /*-----------------------------------------------------------------------------------------------*/
1210 /*-----------------------------------------------------------------------------------------------*/
1211 M2MB_OS_RESULT_E m2mb_os_setSysTicks( UINT32 newTick );
1212 
1213 /*-----------------------------------------------------------------------------------------------*/
1238 /*-----------------------------------------------------------------------------------------------*/
1239 FLOAT32 m2mb_os_getSysTickDuration_ms( void );
1240 
1241 /*-----------------------------------------------------------------------------------------------*/
1279 /*-----------------------------------------------------------------------------------------------*/
1280 M2MB_OS_RESULT_E m2mb_os_get_errno( UINT32 *pCategory, INT32 *pErrno );
1281 
1282 /*-----------------------------------------------------------------------------------------------*/
1283 /*-----------------------------------------------------------------------------------------------*/
1340 /*-----------------------------------------------------------------------------------------------*/
1341 M2MB_OS_RESULT_E m2mb_os_memInfo( M2MB_OS_MEMINFO_E memInfoSelect, MEM_W *pOut );
1342 
1343 /*-----------------------------------------------------------------------------------------------*/
1390 /*-----------------------------------------------------------------------------------------------*/
1391 void *m2mb_os_realloc( void *ptr, UINT32 size );
1392 
1393 
1394 /*-----------------------------------------------------------------------------------------------*/
1415 /*-----------------------------------------------------------------------------------------------*/
1416 M2MB_OS_RESULT_E m2mb_os_RAMAvail( MEM_W *p_total, MEM_W *p_available );
1417 
1418 
1419 
1420 
1421 #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 coperate 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)
total and current RAM available for applications