m2mb API docs  30.00.007
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 
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  M2MB_OS_TASK_SEL_CMD_PRIORITY,
91  M2MB_OS_TASK_SEL_CMD_PREEMPTIONTH,
92  /* time slice: use max ticks for task to run when other tasks with same priority are ready */
93  M2MB_OS_TASK_SEL_CMD_TSLICE,
94  /* start task soon after m2mb_os_taskCreate is called: no need to call m2mb_os_taskResume */
95  M2MB_OS_TASK_SEL_CMD_AUTOSTART,
96 
97  /* state of the task: see M2MB_OS_TASK_STATE_E */
98  M2MB_OS_TASK_SEL_CMD_STATE,
99  /* task running count */
100  M2MB_OS_TASK_SEL_CMD_RUN_CNT,
101 
102  /* ---- */
103  M2MB_OS_TASK_SEL_CMD_END,
104  ENUM_TO_INT( M2MB_OS_TASK_SEL_CMD_E )
105 } M2MB_OS_TASK_SEL_CMD_E;
106 
107 typedef enum
108 {
109  M2MB_OS_TASK_STATE_READY,
110  M2MB_OS_TASK_STATE_COMPLETED,
111  M2MB_OS_TASK_STATE_TERMINATED,
112  M2MB_OS_TASK_STATE_SUSP,
113  M2MB_OS_TASK_STATE_SLEEP,
114  M2MB_OS_TASK_STATE_QUEUE_SUSP,
115  M2MB_OS_TASK_STATE_SEMAPHORE_SUSP,
116  M2MB_OS_TASK_STATE_SIG_SUSP,
117  M2MB_OS_TASK_STATE_BLOCK_MEM_SUSP,
118  M2MB_OS_TASK_STATE_BYTE_MEM_SUSP,
119  M2MB_OS_TASK_STATE_MUTEX_SUSP = 0x0D,
120 
121  /* ---- */
122  M2MB_OS_TASK_STATE_END,
123  ENUM_TO_INT( M2MB_OS_TASK_STATE_E )
124 } M2MB_OS_TASK_STATE_E;
125 
126 typedef enum
127 {
128  M2MB_OS_MEMINFO_FRAGMENTS, //the total number of memory fragments
129  M2MB_OS_MEMINFO_BYTES_AVAILABLE, //the total number of available bytes
130  M2MB_OS_MEMINFO_SIZE, //the total number of memory size
131 
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 /*-----------------------------------------------------------------------------------------------*/
830 /*-----------------------------------------------------------------------------------------------*/
831 M2MB_OS_RESULT_E m2mb_os_taskSuspend( M2MB_OS_TASK_HANDLE taskHandle );
832 
833 /*-----------------------------------------------------------------------------------------------*/
868 /*-----------------------------------------------------------------------------------------------*/
869 M2MB_OS_RESULT_E m2mb_os_taskResume( M2MB_OS_TASK_HANDLE taskHandle );
870 
871 /*-----------------------------------------------------------------------------------------------*/
908 /*-----------------------------------------------------------------------------------------------*/
909 M2MB_OS_RESULT_E m2mb_os_taskTerminate( M2MB_OS_TASK_HANDLE taskHandle );
910 
911 /*-----------------------------------------------------------------------------------------------*/
948 /*-----------------------------------------------------------------------------------------------*/
949 M2MB_OS_RESULT_E m2mb_os_taskRestart( M2MB_OS_TASK_HANDLE taskHandle );
950 
951 /*-----------------------------------------------------------------------------------------------*/
993 /*-----------------------------------------------------------------------------------------------*/
994 M2MB_OS_RESULT_E m2mb_os_taskDelete( M2MB_OS_TASK_HANDLE taskHandle );
995 
996 /*-----------------------------------------------------------------------------------------------*/
1043 /*-----------------------------------------------------------------------------------------------*/
1044 M2MB_OS_RESULT_E m2mb_os_taskCooperate( void );
1045 
1046 /*-----------------------------------------------------------------------------------------------*/
1146 /*-----------------------------------------------------------------------------------------------*/
1147 M2MB_OS_RESULT_E m2mb_os_taskWaitAbort( M2MB_OS_TASK_HANDLE taskHandle );
1148 
1149 /*-----------------------------------------------------------------------------------------------*/
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 /*-----------------------------------------------------------------------------------------------*/
1338 /*-----------------------------------------------------------------------------------------------*/
1339 M2MB_OS_RESULT_E m2mb_os_memInfo( M2MB_OS_MEMINFO_E memInfoSelect, MEM_W *pOut );
1340 
1341 /*-----------------------------------------------------------------------------------------------*/
1392 /*-----------------------------------------------------------------------------------------------*/
1393 void *m2mb_os_realloc( void *ptr, UINT32 size );
1394 
1395 
1396 /***************************************************************************************************
1397  \brief total and current RAM available for applications
1398 
1399  \param [in]: MEM_W *p_total Pointer to total RAM for application
1400 
1401  \param [in]: MEM_W *p_available Pointer to currently available memory
1402 
1403  \return Return_Description
1404  M2MB_OS_SUCCESS in case of success
1405  others in case of error : see m2mb_os_types.h
1406  in case of failure the total and available RAM is set to 0
1407 
1408  \details
1409 **************************************************************************************************/
1410 
1411 M2MB_OS_RESULT_E m2mb_os_RAMAvail( MEM_W *p_total, MEM_W *p_available );
1412 
1413 
1414 
1415 
1416 #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.