m2mb API docs  25.30.004.0
m2mb API sets documentation
m2mb_os.h
Go to the documentation of this file.
1 /* $version: 252203 */
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  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  M2MB_OS_MEMINFO_BYTES_MAX_OCCUPATION = 6, /* the max occupation of bytes that have been allocated */
133  /* ---- */
134  M2MB_OS_MEMINFO_END,
135  ENUM_TO_INT( M2MB_OS_MEMINFO_E )
136 } M2MB_OS_MEMINFO_E;
137 
138 /* Global functions =============================================================================*/
139 
140 /*-----------------------------------------------------------------------------------------------*/
174 /*-----------------------------------------------------------------------------------------------*/
175 
176 UINT32 M2MB_OS_MS2TICKS( UINT32 ms );
177 
178 /*-----------------------------------------------------------------------------------------------*/
215 /*-----------------------------------------------------------------------------------------------*/
216 void *m2mb_os_malloc( UINT32 size );
217 
218 /*-----------------------------------------------------------------------------------------------*/
262 /*-----------------------------------------------------------------------------------------------*/
263 void *m2mb_os_calloc( UINT32 size );
264 
265 /*-----------------------------------------------------------------------------------------------*/
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 /*-----------------------------------------------------------------------------------------------*/
437 /*-----------------------------------------------------------------------------------------------*/
438 M2MB_OS_RESULT_E m2mb_os_taskCreate(
439  M2MB_OS_TASK_HANDLE *pTaskHandle,
440  M2MB_OS_TASK_ATTR_HANDLE *pTaskAttr,
441  ENTRY_FN entryFn,
442  void *pArg
443 );
444 
445 /*-----------------------------------------------------------------------------------------------*/
575 /*-----------------------------------------------------------------------------------------------*/
576 M2MB_OS_RESULT_E m2mb_os_taskGetItem(
577  M2MB_OS_TASK_HANDLE taskHandle,
578  M2MB_OS_TASK_SEL_CMD_E selCmd,
579  MEM_W *pOut,
580  void *pIn
581 );
582 
583 
584 /*-----------------------------------------------------------------------------------------------*/
630 /*-----------------------------------------------------------------------------------------------*/
631 M2MB_OS_RESULT_E m2mb_os_taskSetItem(
632  M2MB_OS_TASK_HANDLE taskHandle,
633  M2MB_OS_TASK_SEL_CMD_E selCmd,
634  void *pIn
635 );
636 
637 /*-----------------------------------------------------------------------------------------------*/
714 /*-----------------------------------------------------------------------------------------------*/
715 M2MB_OS_RESULT_E m2mb_os_taskSetAttrItem(
716  M2MB_OS_TASK_ATTR_HANDLE *pTaskAttrHandle,
717  UINT8 nCmds,
718  ...
719 );
720 
721 /*-----------------------------------------------------------------------------------------------*/
757 /*-----------------------------------------------------------------------------------------------*/
758 M2MB_OS_RESULT_E m2mb_os_taskSleep( UINT32 ticks );
759 
760 /*-----------------------------------------------------------------------------------------------*/
789 /*-----------------------------------------------------------------------------------------------*/
790 M2MB_OS_TASK_HANDLE m2mb_os_taskGetId( void );
791 
792 /*-----------------------------------------------------------------------------------------------*/
831 /*-----------------------------------------------------------------------------------------------*/
832 M2MB_OS_RESULT_E m2mb_os_taskSuspend( M2MB_OS_TASK_HANDLE taskHandle );
833 
834 /*-----------------------------------------------------------------------------------------------*/
869 /*-----------------------------------------------------------------------------------------------*/
870 M2MB_OS_RESULT_E m2mb_os_taskResume( M2MB_OS_TASK_HANDLE taskHandle );
871 
872 /*-----------------------------------------------------------------------------------------------*/
909 /*-----------------------------------------------------------------------------------------------*/
910 M2MB_OS_RESULT_E m2mb_os_taskTerminate( M2MB_OS_TASK_HANDLE taskHandle );
911 
912 /*-----------------------------------------------------------------------------------------------*/
949 /*-----------------------------------------------------------------------------------------------*/
950 M2MB_OS_RESULT_E m2mb_os_taskRestart( M2MB_OS_TASK_HANDLE taskHandle );
951 
952 /*-----------------------------------------------------------------------------------------------*/
994 /*-----------------------------------------------------------------------------------------------*/
995 M2MB_OS_RESULT_E m2mb_os_taskDelete( M2MB_OS_TASK_HANDLE taskHandle );
996 
997 /*-----------------------------------------------------------------------------------------------*/
1044 /*-----------------------------------------------------------------------------------------------*/
1045 M2MB_OS_RESULT_E m2mb_os_taskCooperate( void );
1046 
1047 /*-----------------------------------------------------------------------------------------------*/
1147 /*-----------------------------------------------------------------------------------------------*/
1148 M2MB_OS_RESULT_E m2mb_os_taskWaitAbort( M2MB_OS_TASK_HANDLE taskHandle );
1149 
1150 /*-----------------------------------------------------------------------------------------------*/
1178 /*-----------------------------------------------------------------------------------------------*/
1179 MEM_W m2mb_os_getSysTicks( void );
1180 
1181 /*-----------------------------------------------------------------------------------------------*/
1211 /*-----------------------------------------------------------------------------------------------*/
1212 M2MB_OS_RESULT_E m2mb_os_setSysTicks( UINT32 newTick );
1213 
1214 /*-----------------------------------------------------------------------------------------------*/
1239 /*-----------------------------------------------------------------------------------------------*/
1240 FLOAT32 m2mb_os_getSysTickDuration_ms( void );
1241 
1242 /*-----------------------------------------------------------------------------------------------*/
1280 /*-----------------------------------------------------------------------------------------------*/
1281 M2MB_OS_RESULT_E m2mb_os_get_errno( UINT32 *pCategory, INT32 *pErrno );
1282 
1283 /*-----------------------------------------------------------------------------------------------*/
1284 /*-----------------------------------------------------------------------------------------------*/
1339 /*-----------------------------------------------------------------------------------------------*/
1340 M2MB_OS_RESULT_E m2mb_os_memInfo( M2MB_OS_MEMINFO_E memInfoSelect, MEM_W *pOut );
1341 
1342 /*-----------------------------------------------------------------------------------------------*/
1393 /*-----------------------------------------------------------------------------------------------*/
1394 void *m2mb_os_realloc( void *ptr, UINT32 size );
1395 
1396 
1397 /***************************************************************************************************
1398  \brief total and current RAM available for applications
1399 
1400  \param [in]: MEM_W *p_total Pointer to total RAM for application
1401 
1402  \param [in]: MEM_W *p_available Pointer to currently available memory
1403 
1404  \return Return_Description
1405  M2MB_OS_SUCCESS in case of success
1406  others in case of error : see m2mb_os_types.h
1407  in case of failure the total and available RAM is set to 0
1408 
1409  \details
1410 **************************************************************************************************/
1411 
1412 M2MB_OS_RESULT_E m2mb_os_RAMAvail( MEM_W *p_total, MEM_W *p_available );
1413 
1414 
1415 
1416 
1417 #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.