M2MB OS SEM

This section describes the M2MB APIs to perform OS semaphore operations. More...

#define	M2MB_OS_SEM_INVALID   0
#define	M2MB_OS_SEM_INVALID_ATTR   0
enum	M2MB_OS_SEM_TYPE_E {   M2MB_OS_SEM_GEN,   M2MB_OS_SEM_BINARY,   M2MB_OS_SEM_COUNTING,   M2MB_OS_SEM_MAX }
enum	M2MB_OS_SEM_SEL_CMD_E {   M2MB_OS_SEM_SEL_CMD_CREATE_ATTR,   M2MB_OS_SEM_SEL_CMD_DEL_ATTR,   M2MB_OS_SEM_SEL_CMD_NAME,   M2MB_OS_SEM_SEL_CMD_USRNAME,   M2MB_OS_SEM_SEL_CMD_TYPE,   M2MB_OS_SEM_SEL_CMD_MAX_COUNT,   M2MB_OS_SEM_SEL_CMD_HPTF,   M2MB_OS_SEM_SEL_CMD_COUNT,   M2MB_OS_SEM_SEL_CMD_SUSPENDED_COUNT,   M2MB_OS_SEM_SEL_CMD_1ST_SUSP,   M2MB_OS_SEM_SEL_CMD_END }
typedef HANDLE	M2MB_OS_SEM_HANDLE
typedef HANDLE	M2MB_OS_SEM_ATTR_HANDLE
M2MB_OS_RESULT_E	m2mb_os_sem_init (M2MB_OS_SEM_HANDLE *pSemHandle, M2MB_OS_SEM_ATTR_HANDLE *pSemAttr)
	Semaphore creation. More...
M2MB_OS_RESULT_E	m2mb_os_sem_deinit (M2MB_OS_SEM_HANDLE semHandle)
	Semaphore deinit or deletion. More...
M2MB_OS_RESULT_E	m2mb_os_sem_get (M2MB_OS_SEM_HANDLE semHandle, UINT32 timeoutTicks)
	Get an instance of semaphore. More...
M2MB_OS_RESULT_E	m2mb_os_sem_put (M2MB_OS_SEM_HANDLE semHandle)
	Place (put) an instance in semaphore. More...
M2MB_OS_RESULT_E	m2mb_os_sem_hptf (M2MB_OS_SEM_HANDLE semHandle)
	Prioritize semaphore suspension list HPTF: Highest Priority Task First. More...
M2MB_OS_RESULT_E	m2mb_os_sem_setAttrItem (M2MB_OS_SEM_ATTR_HANDLE *pSemAttrHandle, UINT8 nCmds,...)
	Set semaphore attribute for creation. More...
M2MB_OS_RESULT_E	m2mb_os_sem_getItem (M2MB_OS_SEM_HANDLE semHandle, M2MB_OS_SEM_SEL_CMD_E selCmd, MEM_W *pOut, void *pIn)
	Get specific semaphore properties. More...
M2MB_OS_RESULT_E	m2mb_os_sem_setItem (M2MB_OS_SEM_HANDLE semHandle, M2MB_OS_SEM_SEL_CMD_E selCmd, void *pIn)
	Set specific semaphore properties. More...

Detailed Description

This section describes the M2MB APIs to perform OS semaphore operations.

Macro Definition Documentation

M2MB_OS_SEM_INVALID

#define M2MB_OS_SEM_INVALID   0

Definition at line 52 of file m2mb_os_sem.h.

M2MB_OS_SEM_INVALID_ATTR

#define M2MB_OS_SEM_INVALID_ATTR   0

Definition at line 53 of file m2mb_os_sem.h.

Typedef Documentation

M2MB_OS_SEM_ATTR_HANDLE

typedef HANDLE M2MB_OS_SEM_ATTR_HANDLE

Definition at line 93 of file m2mb_os_sem.h.

M2MB_OS_SEM_HANDLE

typedef HANDLE M2MB_OS_SEM_HANDLE

Definition at line 92 of file m2mb_os_sem.h.

Enumeration Type Documentation

M2MB_OS_SEM_SEL_CMD_E

enum M2MB_OS_SEM_SEL_CMD_E

Enumerator
M2MB_OS_SEM_SEL_CMD_CREATE_ATTR
M2MB_OS_SEM_SEL_CMD_DEL_ATTR
M2MB_OS_SEM_SEL_CMD_NAME	use as Os name
M2MB_OS_SEM_SEL_CMD_USRNAME	if set, user name could be different from Os
M2MB_OS_SEM_SEL_CMD_TYPE	type of semaphore: see M2MB_OS_SEM_TYPE_E
M2MB_OS_SEM_SEL_CMD_MAX_COUNT	max counter value for M2MB_OS_SEM_COUNTING type
M2MB_OS_SEM_SEL_CMD_HPTF	High Priority Task First: every put will move highest priority task on top of FIFO
M2MB_OS_SEM_SEL_CMD_COUNT
M2MB_OS_SEM_SEL_CMD_SUSPENDED_COUNT	number of task suspended on this resource
M2MB_OS_SEM_SEL_CMD_1ST_SUSP	first task (M2MB_OS_TASK_HANDLE) to be served when the resource will be available
M2MB_OS_SEM_SEL_CMD_END

Definition at line 65 of file m2mb_os_sem.h.

M2MB_OS_SEM_TYPE_E

enum M2MB_OS_SEM_TYPE_E

Enumerator
M2MB_OS_SEM_GEN	not limited counter value: could overflow and restart with 0
M2MB_OS_SEM_BINARY	counter limited to 1
M2MB_OS_SEM_COUNTING	counter limited to defined value
M2MB_OS_SEM_MAX

Definition at line 55 of file m2mb_os_sem.h.

Function Documentation

m2mb_os_sem_deinit()

M2MB_OS_RESULT_E m2mb_os_sem_deinit

(

M2MB_OS_SEM_HANDLE

semHandle

)

Semaphore deinit or deletion.

This service deletes the specified OS semaphore. All tasks suspended waiting for this semaphore are resumed with a

Returns

value equal to M2MB_OS_DELETED The resources will be released and handle set to M2MB_OS_SEM_INVALID It is the application's responsibility to prevent the use of a deleted semaphore.

Parameters

[in]

semHandle

Handle of the semaphore

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle M2MB_OS_INVALID_ARG Invalid arguments M2MB_OS_CALLER_ERROR Invalid caller of this service.

Note

It is the application's responsibility to prevent the use of a deleted semaphore.

semaphore. Allowed From tasks Preemption Possible Yes

Example

<C code example>

m2mb_os_sem_get()

M2MB_OS_RESULT_E m2mb_os_sem_get	(	M2MB_OS_SEM_HANDLE	semHandle,
		UINT32	timeoutTicks
	)

Get an instance of semaphore.

This service retrieves an instance (a single count) from the specified semaphore if its count is greater than 0. As a result, the specified semaphore's count is decreased by one. If count is not available parameter timeoutTicks specifies how to behave: wait forever or set a limit to wait and then exit

Parameters

[in]	semHandle	Handle of semaphore
[in]	timeoutTicks	If the timeout is specified and semaphore count is zero, the task will be suspended for a maximum time of timeout ticks

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SUCCESS Successful retrieval of a semaphore instance. M2MB_OS_DELETED Counting semaphore was deleted while task was suspended. M2MB_OS_NO_INSTANCE Service was unable to retrieve an instance of the counting semaphore (semaphore count is zero within the specified time to wait). M2MB_OS_WAIT_ABORTED Suspension was aborted by another task, timer, or ISR. M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle. M2MB_OS_WAIT_ERROR A wait option other than M2MB_OS_NO_WAIT was specified on a call from a non-task.

Note

Allowed From Initialization, tasks, timers, and ISRs Preemption Possible Yes

Example

#include "m2mb_os.h"

// set timeout as 2000 ms
m2mb_os_sem_get( semHandle, M2MB_OS_MS2TICKS(2000) );

m2mb_os_sem_getItem()

M2MB_OS_RESULT_E m2mb_os_sem_getItem	(	M2MB_OS_SEM_HANDLE	semHandle,
		M2MB_OS_SEM_SEL_CMD_E	selCmd,
		MEM_W *	pOut,
		void *	pIn
	)

Get specific semaphore properties.

This service retrieves values for a specified parameter of the specified semaphore Selecting cmd, a parameter to be retrieved can be set To be used when a semaphore is already created: its right usage is under application responsibility

Parameters

[in]	semHandle	Handle of semaphore
[in]	selCmd	Select parameter to be retrieved (see M2MB_OS_SEM_SEL_CMD_E)
[out]	pOut	Pointer Output parameter got: its meaning depend on selCmd used. See examples. As general pointer, it is set to MEM_W
[in]	pIn	Pointer to void general Parameter to be specified, if any, to get the right output. See examples. If parameter is not needed, use NULL

Returns

M2MB_OS_SUCCESS in case of success (others in case of error : see m2mb_os_types.h)

M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle M2MB_OS_INVALID_ARG Invalid arguments

Note

Not all the M2MB_OS_SEM_SEL_CMD_E are always available. Of course M2MB_OS_SEM_SEL_CMD_CREATE_ATTR is not right for this function M2MB_OS_SEM_SEL_CMD_NAME, M2MB_OS_SEM_SEL_CMD_TYPE, M2MB_OS_SEM_SEL_CMD_MAX_COUNT, M2MB_OS_SEM_SEL_CMD_COUNT, M2MB_OS_SEM_SEL_CMD_HPTF, M2MB_OS_SEM_SEL_CMD_SUSPENDED_COUNT are ok

Example

 M2MB_OS_RESULT_E        osRes;
 M2MB_OS_SEM_ATTR_HANDLE semAttrHandle;
 M2MB_OS_SEM_HANDLE      semHandle;
 UINT32                  initVal = 1;
 MEM_W                   currCount;

//create it as binary:
 osRes = m2mb_os_sem_setAttrItem( &semAttrHandle,
                                  CMDS_ARGS
                                  (
                                    M2MB_OS_SEM_SEL_CMD_COUNT, 1,
                                    M2MB_OS_SEM_SEL_CMD_MAX_COUNT, 5,
                                    M2MB_OS_SEM_SEL_CMD_TYPE, M2MB_OS_SEM_BINARY,
                                    M2MB_OS_SEM_SEL_CMD_NAME, "MyCountingSem"
                                  )
                                );
 if( osRes != M2MB_OS_SUCCESS )
   exit(...)

 //create as binary
 m2mb_os_sem_init( &semHandle, &semAttrHandle );

 m2mb_os_sem_put( semHandle );
 m2mb_os_sem_put( semHandle );
 m2mb_os_sem_put( semHandle );
 m2mb_os_sem_put( semHandle );

 m2mb_os_sem_getItem( semHandle, M2MB_OS_SEM_SEL_CMD_COUNT, &currCount, NULL );
 //you get currCount =1

m2mb_os_sem_hptf()

M2MB_OS_RESULT_E m2mb_os_sem_hptf

(

M2MB_OS_SEM_HANDLE

semHandle

)

Prioritize semaphore suspension list HPTF: Highest Priority Task First.

This service set the task waiting for this semaphore which has currently the highest priority, on the top of FIFO task suspension list It is one shot operation. To have highest priority task served first for every put, see m2m_os_sem_setItem(..) or m2mb_os_sem_setAttrItem.

Parameters

[in]

semHandle

Handle of semaphore

Returns

M2MB_OS_SUCCESS in case of success (others in case of error : see m2mb_os_types.h)

M2MB_OS_SUCCESS Successful semaphore operation. M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle M2MB_OS_INVALID_ARG Invalid oneShot parameter

Note

Allowed From Initialization, tasks, timers, and ISRs Preemption Possible No

Example usage of m2mb_os_sem_hptf

M2MB_OS_SEM_HANDLE semHandle;
//...
//already created... used semaphore
//just put highest priority task on top of suspension list
m2mb_os_sem_hptf( semHandle );

m2mb_os_sem_put(semHandle);
//will give control to the highest priority task waiting...

m2mb_os_sem_init()

M2MB_OS_RESULT_E m2mb_os_sem_init	(	M2MB_OS_SEM_HANDLE *	pSemHandle,
		M2MB_OS_SEM_ATTR_HANDLE *	pSemAttr
	)

Semaphore creation.

This service creates a counting semaphore for inter-intra task synchronization. The initial semaphore attribute are set inside M2MB_OS_SEM_ATTR_HANDLE as parameters.

Parameters

[out]	pSemHandle	Pointer to semaphore handle
[in]	pSemAttr	Pointer to semaphore attribute handle

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle M2MB_OS_INVALID_ARG Invalid arguments M2MB_OS_CALLER_ERROR Invalid caller of this service.

Note

After successful semaphore creation, semaphore attribute will be deleted, their resources free and pSemAttr set to M2MB_OS_SEM_INVALID_ATTR Allowed From Initialization and threads Preemption Possible No

Example Semaphore creation using m2mb_os_sem_init

M2MB_OS_SEM_ATTR_HANDLE semAttrHandle;
M2MB_OS_SEM_HANDLE      semHandle;
UINT32                  initVal = 1;

if ( m2mb_os_sem_setAttrItem( &semAttrHandle, 1, M2MB_OS_SEM_SEL_CMD_CREATE_ATTR,  NULL ) != M2MB_OS_SUCCESS )
    exit(error_creating attribute semaphore);

m2mb_os_sem_setAttrItem( &semAttrHandle, M2MB_OS_SEM_SEL_CMD_COUNT, initVal );
m2mb_os_sem_setAttrItem( &semAttrHandle, M2MB_OS_SEM_SEL_CMD_TYPE, M2MB_OS_SEM_GEN );
m2mb_os_sem_setAttrItem( &semAttrHandle, M2MB_OS_SEM_SEL_CMD_NAME, "MySem" );

// or simply all at once using macro CMDS_ARGS
// m2mb_os_sem_setAttrItem( &semAttrHandle,
//                          CMDS_ARGS
//                          (
//                            M2MB_OS_SEM_SEL_CMD_CREATE_ATTR,  NULL,
//                            M2MB_OS_SEM_SEL_CMD_COUNT, initVal,
//                            M2MB_OS_SEM_SEL_CMD_TYPE, M2MB_OS_SEM_GEN,
//                            M2MB_OS_SEM_SEL_CMD_NAME, "MySem",
//                          )
//                        );

m2mb_os_sem_init( &semHandle, &semAttrHandle );

m2mb_os_sem_put()

M2MB_OS_RESULT_E m2mb_os_sem_put

(

M2MB_OS_SEM_HANDLE

semHandle

)

Place (put) an instance in semaphore.

This service puts an instance into the specified counting semaphore, which in reality increments the counting semaphore by one. In case of general counting semaphore (M2MB_OS_SEM_GEN), if this service is called when the semaphore count is all ones (OxFFFFFFFF), the new put operation will cause the semaphore to be reset to zero. When M2MB_OS_SEM_BINARY or M2MB_OS_SEM_COUNTING are the type of OS semaphore, count will be limited to 1 or maxCount as specified by M2MB_OS_SEM_SEL_CMD_MAX_COUNT attribute

Parameters

[in]

semHandle

Handle of semaphore

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SUCCESS Successful semaphore put. M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle M2MB_OS_CEILING_EXCEEDED Put request exceeds maximum maxCount. M2MB_OS_INVALID_CEILING An invalid value of zero was as maxCount

Note

Allowed From Initialization, tasks, timers, and ISRs Preemption Possible Yes

Example

<C code example>

m2mb_os_sem_setAttrItem()

M2MB_OS_RESULT_E m2mb_os_sem_setAttrItem	(	M2MB_OS_SEM_ATTR_HANDLE *	pSemAttrHandle,
		UINT8	nCmds,
			...
	)

Set semaphore attribute for creation.

This service set the attribute (or create it) to be used for semaphore creation

Parameters

[in]	pSemAttrHandle	Pointer to semaphore attribute of semaphore
[in]	nCmds	Number of commands to be issued at once
[in]	...	Variable inputs, N cmds (see M2MB_OS_SEM_SEL_CMD_E) followed by N arguments for their respective issued commands. CMDS(...) and CMDS_ARGS(...) macro can be used to better insert cmd and parameters and to better control right insertion

Returns

M2MB_OS_SUCCESS in case of success (others in case of error : see m2mb_os_types.h)

M2MB_OS_SUCCESS Successful semaphore operation. M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle M2MB_OS_INVALID_ARG Invalid pSemAttr or pIn

Note

The attribute set are useful for semaphore creation. Once created, use instead m2mb_os_sem_setItem() to set semaphore properties It is under application responsibility the right use of m2mb_os_sem_setAttrItem. For instance, multi creation of attrHandle without free of previous resources ( M2MB_OS_SEM_SEL_CMD_CREATE_ATTR without M2MB_OS_SEM_SEL_CMD_DEL_ATTR in case no m2mb_os_sem_init is used in the between ) will waste memory.

Example

M2MB_OS_RESULT_E        osRes;
M2MB_OS_SEM_ATTR_HANDLE semAttrHandle;
M2MB_OS_SEM_HANDLE      semHandle;
UINT32                  initVal = 1;

if ( m2mb_os_sem_setAttrItem( &semAttrHandle, 1, M2MB_OS_SEM_SEL_CMD_CREATE_ATTR, NULL ) != M2MB_OS_SUCCESS )
    exit(error_creating attribute semaphore);

//set init value,max_count to 5, type as counting semaphore and set its name:  using 4 as nCmds
osRes = m2mb_os_sem_setAttrItem( &semAttrHandle, 4,
                                 M2MB_OS_SEM_SEL_CMD_COUNT, M2MB_OS_SEM_SEL_CMD_MAX_COUNT,
                                 M2MB_OS_SEM_SEL_CMD_TYPE,  M2MB_OS_SEM_SEL_CMD_NAME,
                                 initVal, 5, M2MB_OS_SEM_COUNTING, "MyCountingSem"
                               );
//or simply use macro CMDS_ARGS(...)
// osRes = m2mb_os_sem_setAttrItem( &semAttrHandle,
//                                  CMDS_ARGS
//                                  (
//                                    M2MB_OS_SEM_SEL_CMD_COUNT, initVal,
//                                    M2MB_OS_SEM_SEL_CMD_MAX_COUNT, 5,
//                                    M2MB_OS_SEM_SEL_CMD_TYPE, M2MB_OS_SEM_COUNTING,
//                                    M2MB_OS_SEM_SEL_CMD_NAME, "MyCountingSem"
//                                  )
//                                );

if( osRes != M2MB_OS_SUCCESS )
  exit(...)
m2mb_os_sem_init( &semHandle, &semAttrHandle );
//...

m2mb_os_sem_deinit(&semHandle);

//now create it as binary: for error set M2MB_OS_SEM_SEL_CMD_MAX_COUNT to 5: never reached as binary
osRes = m2mb_os_sem_setAttrItem( &semAttrHandle,
                                 CMDS_ARGS
                                 (
                                   M2MB_OS_SEM_SEL_CMD_COUNT, 1,
                                   M2MB_OS_SEM_SEL_CMD_MAX_COUNT, 5,
                                   M2MB_OS_SEM_SEL_CMD_TYPE, M2MB_OS_SEM_BINARY,
                                   M2MB_OS_SEM_SEL_CMD_NAME, "MyCountingSem"
                                 )
                               );
if( osRes != M2MB_OS_SUCCESS )
  exit(...)

//create as binary
m2mb_os_sem_init( &semHandle, &semAttrHandle );

m2mb_os_sem_put( semHandle );
m2mb_os_sem_put( semHandle );
m2mb_os_sem_put( semHandle );
m2mb_os_sem_put( semHandle );

//value of count will always be no more than 1

m2mb_os_sem_setItem()

M2MB_OS_RESULT_E m2mb_os_sem_setItem	(	M2MB_OS_SEM_HANDLE	semHandle,
		M2MB_OS_SEM_SEL_CMD_E	selCmd,
		void *	pIn
	)

Set specific semaphore properties.

This service sets values for a specified parameter of the specified semaphore if available Selecting cmd, a parameter to be set can be selected To be used when semaphore is already created: its right usage is under application responsibility

Parameters

[in]	semHandle	Handle of semaphore
[in]	selCmd	Select parameter to be set (see M2MB_OS_SEM_SEL_CMD_E)
[in]	pIn	Pointer to value to be set. If a simple value, can be easily casted to (void*) For example, int value -3 has to be passed, use (void*)-3 NULL if no value is needed

Returns

M2MB_OS_SUCCESS in case of success (others in case of error: see m2mb_os_types.h)

M2MB_OS_SEMAPHORE_ERROR Invalid counting semaphore handle M2MB_OS_INVALID_ARG invalid arguments

Note

Not all the M2MB_OS_SEM_SEL_CMD_E are always available. Of course M2MB_OS_SEM_SEL_CMD_CREATE_ATTR is not right for this function M2MB_OS_SEM_SEL_CMD_NAME, M2MB_OS_SEM_SEL_CMD_TYPE, M2MB_OS_SEM_SEL_CMD_MAX_COUNT, M2MB_OS_SEM_SEL_CMD_COUNT, M2MB_OS_SEM_SEL_CMD_HPTF, M2MB_OS_SEM_SEL_CMD_SUSPENDED_COUNT are ok

Example

m2mb_os_sem_setItem(semHandle, M2MB_OS_SEM_SEL_CMD_HPTF, (void*)1 );
// this will force every put to release the highest priority task waiting for semaphore
m2mb_os_sem_setItem(semHandle, M2MB_OS_SEM_SEL_CMD_HPTF, (void*)0 );
//will set standard FIFO rule again
m2mb_os_sem_setItem(semHandle, M2MB_OS_SEM_SEL_CMD_USRNAME, (void*)"ThisIsUserName");
m2mb_os_sem_setItem(semHandle, M2MB_OS_SEM_SEL_CMD_MAX_COUNT, (void*)3);
//allowed by semaphore type, new maxCount will be set at run time