M2MB OS EV

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

#define	M2MB_OS_EV_INVALID   0
#define	M2MB_OS_EV_INVALID_ATTR   0
#define	m2mb_os_ev_setAttrItem_(h, args, ...)   m2mb_os_ev_setAttrItem( h, CMDS_ARGS( args ) )
enum	M2MB_OS_EV_SEL_CMD_E {   M2MB_OS_EV_SEL_CMD_CREATE_ATTR,   M2MB_OS_EV_SEL_CMD_DEL_ATTR,   M2MB_OS_EV_SEL_CMD_NAME,   M2MB_OS_EV_SEL_CMD_USRNAME,   M2MB_OS_EV_SEL_CMD_SUSPENDED_COUNT,   M2MB_OS_EV_SEL_CMD_1ST_SUSP,   M2MB_OS_EV_SEL_CMD_CURRENT_BITS_EVENT,   M2MB_OS_EV_SEL_CMD_END }
enum	M2MB_OS_EV_SET_OPT_E {   M2MB_OS_EV_SET = 0,   M2MB_OS_EV_CLEAR = 2,   M2MB_OS_EV_SET_OPT_END }
enum	M2MB_OS_EV_GET_OPT_E {   M2MB_OS_EV_GET_ANY = 0,   M2MB_OS_EV_GET_ANY_AND_CLEAR,   M2MB_OS_EV_GET_ALL,   M2MB_OS_EV_GET_ALL_AND_CLEAR,   M2MB_OS_EV_GET_OPT_END }
typedef struct M2MB_OS_EV_HANDLE_TAG *	M2MB_OS_EV_HANDLE
typedef struct M2MB_OS_EV_ATTR_HANDLE_TAG *	M2MB_OS_EV_ATTR_HANDLE
M2MB_OS_RESULT_E	m2mb_os_ev_init (M2MB_OS_EV_HANDLE *pEvHandle, M2MB_OS_EV_ATTR_HANDLE *pEvAttr)
	Application Event Set Creation. More...
M2MB_OS_RESULT_E	m2mb_os_ev_deinit (M2MB_OS_EV_HANDLE eveHandle)
	Application Event deinit or deletion. More...
M2MB_OS_RESULT_E	m2mb_os_ev_set (M2MB_OS_EV_HANDLE evHandle, UINT32 evBits, M2MB_OS_EV_SET_OPT_E optSet)
	Set bits of event in a specified event. More...
M2MB_OS_RESULT_E	m2mb_os_ev_get (M2MB_OS_EV_HANDLE evHandle, UINT32 reqEvBits, M2MB_OS_EV_GET_OPT_E optGet, UINT32 *pCurEvBits, UINT32 timeout)
	Get an application event. More...
M2MB_OS_RESULT_E	m2mb_os_ev_setAttrItem (M2MB_OS_EV_ATTR_HANDLE *pEvAttr, UINT8 nCmds,...)
	Set specific attribute for event init or creation. More...
M2MB_OS_RESULT_E	m2mb_os_ev_getItem (M2MB_OS_EV_HANDLE evHandle, M2MB_OS_EV_SEL_CMD_E selCmd, MEM_W *pOut, void *pIn)
	Get specific properties of the event. More...
M2MB_OS_RESULT_E	m2mb_os_ev_setItem (M2MB_OS_EV_HANDLE evHandle, M2MB_OS_EV_SEL_CMD_E selCmd, void *pIn)
	Set specific properties of the event. More...

Detailed Description

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

Macro Definition Documentation

M2MB_OS_EV_INVALID

#define M2MB_OS_EV_INVALID   0

Definition at line 55 of file m2mb_os_ev.h.

M2MB_OS_EV_INVALID_ATTR

#define M2MB_OS_EV_INVALID_ATTR   0

Definition at line 56 of file m2mb_os_ev.h.

m2mb_os_ev_setAttrItem_

#define m2mb_os_ev_setAttrItem_	(		h,
			args,
			...
	)		m2mb_os_ev_setAttrItem( h, CMDS_ARGS( args ) )

Definition at line 70 of file m2mb_os_ev.h.

Typedef Documentation

M2MB_OS_EV_ATTR_HANDLE

typedef struct M2MB_OS_EV_ATTR_HANDLE_TAG* M2MB_OS_EV_ATTR_HANDLE

Definition at line 123 of file m2mb_os_ev.h.

M2MB_OS_EV_HANDLE

typedef struct M2MB_OS_EV_HANDLE_TAG* M2MB_OS_EV_HANDLE

Definition at line 122 of file m2mb_os_ev.h.

Enumeration Type Documentation

M2MB_OS_EV_GET_OPT_E

enum M2MB_OS_EV_GET_OPT_E

Enumerator
M2MB_OS_EV_GET_ANY
M2MB_OS_EV_GET_ANY_AND_CLEAR
M2MB_OS_EV_GET_ALL
M2MB_OS_EV_GET_ALL_AND_CLEAR
M2MB_OS_EV_GET_OPT_END

Definition at line 106 of file m2mb_os_ev.h.

M2MB_OS_EV_SEL_CMD_E

enum M2MB_OS_EV_SEL_CMD_E

Enumerator
M2MB_OS_EV_SEL_CMD_CREATE_ATTR
M2MB_OS_EV_SEL_CMD_DEL_ATTR
M2MB_OS_EV_SEL_CMD_NAME
M2MB_OS_EV_SEL_CMD_USRNAME
M2MB_OS_EV_SEL_CMD_SUSPENDED_COUNT
M2MB_OS_EV_SEL_CMD_1ST_SUSP
M2MB_OS_EV_SEL_CMD_CURRENT_BITS_EVENT
M2MB_OS_EV_SEL_CMD_END

Definition at line 74 of file m2mb_os_ev.h.

M2MB_OS_EV_SET_OPT_E

enum M2MB_OS_EV_SET_OPT_E

Enumerator
M2MB_OS_EV_SET
M2MB_OS_EV_CLEAR
M2MB_OS_EV_SET_OPT_END

Definition at line 95 of file m2mb_os_ev.h.

Function Documentation

m2mb_os_ev_deinit()

M2MB_OS_RESULT_E m2mb_os_ev_deinit

(

M2MB_OS_EV_HANDLE

eveHandle

)

Application Event deinit or deletion.

This service deletes the specified os event. All tasks suspended waiting for this event are resumed with a return value egual to M2MB_OS_DELETED The resources will be released. It is the application’s responsibility to prevent use of a deleted event.

Parameters

[in]

evHandle

handle of the event

Returns

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

M2MB_OS_EVENT_ERROR Invalid event handle M2MB_OS_CALLER_ERROR Invalid caller of this service.

Note

It is the application’s responsibility to prevent use of a deleted event. Allowed From tasks Preemption Possible Yes

Example

m2mb_os_ev_get()

M2MB_OS_RESULT_E m2mb_os_ev_get	(	M2MB_OS_EV_HANDLE	evHandle,
		UINT32	reqEvBits,
		M2MB_OS_EV_GET_OPT_E	optGet,
		UINT32 *	pCurEvBits,
		UINT32	timeout
	)

Get an application event.

This service retrieves bits event from the specified event. Each event contains 32 event bits. This service can retrieve a variety of event bits combinations, as selected by the input reqEvBits.

Parameters

[in]	evHandle	handle of event
[in]	reqEvBits	requested bits event
[in]	optGet	option for get the event (see M2MB_OS_EV_GET_OPT_E)
[out]	pCurEvBits	pointer to where current bits events are written to. It contains all the currents bits as found before any actions are taken (e.g cleared as requested)
[in]	timeout	wait option in case of not success in getting requested bit event

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_EVENT_ERROR Invalid event handle M2MB_OS_DELETED event was deleted while task was suspended M2MB_OS_NO_EVENTS Service was unable to get the specified events within the specified timeout M2MB_OS_WAIT_ABORTED Suspension was aborted by another task, timer, or ISR M2MB_OS_PTR_ERROR Invalid pointer for current event bits container 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, events, and ISRs Preemption Possible Yes

Example

M2MB_OS_EV_HANDLE evHandle;
UINT32            CurEvBits;
M2MB_OS_RESULT_E  osRes;

//Request that any of the event bits 0, 4, and 8 are set. Also, if any are set
// the set bits in the selected events bit will be cleared.
//If the event bits are not set, this service suspends for a maximum of 50 timer-ticks.

osRes = m2mb_os_ev_get(evHandle, (UINT32)0x111, M2MB_OS_EV_GET_ANY_AND_CLEAR, &CurEvBits, 50 );

// or for example 2000 ms using M2MB_OS_MS2TICKS : "m2mb_os.h" has to be included
osRes = m2mb_os_ev_get(evHandle, (UINT32)0x111, M2MB_OS_EV_GET_ANY_AND_CLEAR, &CurEvBits,
                       M2MB_OS_MS2TICKS(2000) );

//If status equals M2MB_OS_SUCCESS, CurEvBits contains the actual bits event obtained, before any
//operation on them are taken, e.g clear. It means CurEvBits in the example will contain
// any of the bits 0,4,8
// plus in case, additional not requested. It is just previous event bits state

m2mb_os_ev_getItem()

M2MB_OS_RESULT_E m2mb_os_ev_getItem	(	M2MB_OS_EV_HANDLE	evHandle,
		M2MB_OS_EV_SEL_CMD_E	selCmd,
		MEM_W *	pOut,
		void *	pIn
	)

Get specific properties of the event.

This service retrieve value for specified parameter of the specified event Selecting cmd, a parameter to be retrieved can be set. To be used when event is already created: it is under application responsibility

Parameters

[in]	selCmd	Select parameter to be retrieved (see M2MB_OS_EV_SEL_CMD_E)
[in]	evHandle	handle of event param [out] pOut pointer Output parameter got: its meaning depend on selCmd used See examples as general pointer it is set to UINT32
[in]	pIn	pointer to void general Parameter to be specified, if any, to get right output See examples If parameter is not needed, use NULL

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_EVENT_ERROR Invalid counting event handle M2MB_OS_INVALID_ARG invalid arguments

Note

Not all the M2MB_OS_EV_SEL_CMD_E are always available. Of course M2MB_OS_EV_SEL_CMD_CREATE_ATTR is not right for this function. Allowed: M2MB_OS_EV_SEL_CMD_NAME M2MB_OS_EV_SEL_CMD_USRNAME ( see the code example for use of pIn ) M2MB_OS_EV_SEL_CMD_SUSPENDED_COUNT M2MB_OS_EV_SEL_CMD_1ST_SUSP M2MB_OS_EV_SEL_CMD_CURRENT_BITS_EVENT

Example

M2MB_OS_EV_ATTR_HANDLE evAttrHandle;
M2MB_OS_EV_HANDLE      evHandle;
CHAR                   MyEvName[10];
CHAR                   *pEvName;
MEM_W                  currBitEvent;
M2MB_OS_TASK           whoIs;
M2MB_OS_RESULT_E       osRes;

osRes = m2mb_os_ev_setAttrItem( &evAttrHandle,
                                CMDS_ARGS
                                (
                                  M2MB_OS_EV_SEL_CMD_CREATE_ATTR, NULL,
                                  M2MB_OS_EV_SEL_CMD_NAME, "event_1",
                                  M2MB_OS_EV_SEL_CMD_USRNAME, "myevent1"
                                )
                              );

if( osRes != M2MB_OS_SUCCESS )
  exit(...)

//create
m2mb_os_ev_init( &evHandle, &evAttrHandle );

//get the first task suspended on the list on that event handle
m2mb_os_ev_getItem( evHandle, M2MB_OS_EV_SEL_CMD_1ST_SUSP, (MEM_W *)&whoIs, NULL );
//get the current bits in the event
m2mb_os_ev_getItem( M2MB_OS_EV_SEL_CMD_CURRENT_EVENTS, evHandle, &currBitEvent, NULL );

//copy only the first 10 chars to MyTaskName array of chars
m2mb_os_ev_getItem( evHandle, M2MB_OS_EV_SEL_CMD_USRNAME,(MEM_W *)&MyEvName, (void*)10);
// or simply get the pointer of name, with NULL
m2mb_os_ev_getItem(evHandle, M2MB_OS_EV_SEL_CMD_USRNAME, (MEM_W *)&pEvName, NULL);

m2mb_os_ev_init()

M2MB_OS_RESULT_E m2mb_os_ev_init	(	M2MB_OS_EV_HANDLE *	pEvHandle,
		M2MB_OS_EV_ATTR_HANDLE *	pEvAttr
	)

Application Event Set Creation.

This service creates a group of 32 event bits. All 32 event bits in the event are initialized to zero.

Parameters

[out]	pEvHandle	pointer to event handle
[in]	pEvAttrHandle	pointer to event attribute handle

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_EVENT_ERROR Invalid application event handle: either the handle is invalid or the event is already created M2MB_OS_INVALID_ARG invalid arguments M2MB_OS_CALLER_ERROR Invalid caller of this service.

Note

After successfull event creation, event attribute will be deleted, their resources free and pEvAttr set to M2MB_OS_EV_INVALID_ATTR In case of error return, it is application's responsibility to release resources of attributes by calling m2mb_os_ev_setAttrItem( &evAttr, M2MB_OS_EV_SEL_CMD_DEL_ATTR, NULL ); Allowed From Initialization and tasks Preemption Possible No

Example

M2MB_OS_RESULT_E        osRes;
M2MB_OS_EV_ATTR_HANDLE  evAttrHandle;
M2MB_OS_EV_HANDLE       evHandle;

osRes  = m2mb_os_ev_setAttrItem( &evAttrHandle, 2,
                                 M2MB_OS_EV_SEL_CMD_CREATE_ATTR,  M2MB_OS_EV_SEL_CMD_NAME,
                                 NULL, "MyEv"
                               );
// or using CMDS_ARGS(...) macro
osRes  = m2mb_os_ev_setAttrItem( &evAttrHandle,
                                 CMDS_ARGS
                                 (
                                   M2MB_OS_EV_SEL_CMD_CREATE_ATTR, NULL,
                                   M2MB_OS_EV_SEL_CMD_NAME, "MyEv"
                                 )
                               );

osRes = m2mb_os_ev_init( &evHandle, &evAttrHandle );
if ( osRes != M2MB_OS_SUCCESS )
{
  m2mb_os_ev_setAttrItem( &evAttrHandle, M2MB_OS_EV_SEL_CMD_DEL_ATTR, NULL );
}

m2mb_os_ev_set()

M2MB_OS_RESULT_E m2mb_os_ev_set	(	M2MB_OS_EV_HANDLE	evHandle,
		UINT32	evBits,
		M2MB_OS_EV_SET_OPT_E	optSet
	)

Set bits of event in a specified event.

This service sets or clears event bits in an event, depending upon the specified set-option. All suspended tasks whose event bits request is now satisfied are resumed.

Parameters

[in]	evHandle	handle of event
[in]	evBits	event bits to set
[in]	optSet	option for set or clear specified bit (see M2MB_OS_EV_SET_OPT_E)

Returns

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

M2MB_OS_EVENT_ERROR Invalid event handle.

Note

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

Example

 M2MB_OS_EV_HANDLE evHandle;
 M2MB_OS_RESULT_E  osRes;

// Set event bit 0, 4, and 8.
osRes = m2mb_os_ev_set(evHandle, (UINT32)0x111, M2MB_OS_EV_SET);

// If osRes equals M2MB_OS_SUCCESS, the event bits have been
// set and any suspended task whose request was satisfied
// will be resumed.

osRes = m2mb_os_ev_set(evHandle, (UINT32)0x100, M2MB_OS_EV_CLEAR);
// If osRes equals M2MB_OS_SUCCESS, the event bit 8 has been
// cleared

m2mb_os_ev_setAttrItem()

M2MB_OS_RESULT_E m2mb_os_ev_setAttrItem	(	M2MB_OS_EV_ATTR_HANDLE *	pEvAttr,
		UINT8	nCmds,
			...
	)

Set specific attribute for event init or creation.

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

Parameters

[in]	pEvAttrHandle	pointer to event attribute handle of event
[in]	nCmds	number of commands to be issued at once
[in]	...	variable inputs, N cmds (see M2MB_OS_EV_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 event operation. M2MB_OS_EVENT_ERROR Invalid counting event handle M2MB_OS_INVALID_ARG invalid pEvAttr or pIn for set operation

Note

The attribute set are useful for event creation. Once created, use instead m2mb_os_ev_setItem() to set only available event properties Typical uses is only for M2MB_OS_EV_SEL_CMD_USRNAME It is under application responsibility the right use of m2mb_os_ev_setAttrItem. For instance, multi creation of attrHandle withouth free of previous resources ( M2MB_OS_EV_SEL_CMD_CREATE_ATTR without M2MB_OS_EV_SEL_CMD_DEL_ATTR in case no m2mb_os_ev_init is used in the between ) will waste memory.

Example

M2MB_OS_EV_ATTR_HANDLE evAttrHandle;
M2MB_OS_EV_HANDLE      evHandle;
UINT32                 CurEvBits;

if ( m2mb_os_ev_setAttrItem( &evAttrHandle, 1, M2MB_OS_EV_SEL_CMD_CREATE_ATTR,  NULL ) != M2MB_OS_SUCCESS )
    exit(error_creating attribute event);

m2mb_os_ev_setAttrItem( &evAttrHandle, 2, M2MB_OS_EV_SEL_CMD_NAME, M2MB_OS_EV_SEL_CMD_USRNAME,
                        "MyEv", "MyEvUser"
                      );

//or using CMDS_ARGS(...) macro
m2mb_os_ev_setAttrItem( &evAttrHandle,
                        CMDS_ARGS
                        (
                           M2MB_OS_EV_SEL_CMD_CREATE_ATTR, NULL,
                           M2MB_OS_EV_SEL_CMD_NAME, "MyEv",
                           M2MB_OS_EV_SEL_CMD_USRNAME, "MyEvUser"
                        )
                      );


if ( m2mb_os_ev_init( &evHandle, &evAttrHandle ) != M2MB_OS_SUCCESS )
{
  //in case of error remember to manually remove attribute and release resources
  m2mb_os_ev_setAttrItem( &evAttrHandle, 1, M2MB_OS_EV_SEL_CMD_DEL_ATTR, NULL );
}
//...

osRes = m2mb_os_ev_get(evHandle, (UINT32)0x111, M2MB_OS_EV_GET_ANY_AND_CLEAR, &CurEvBits, 50 );

m2mb_os_ev_setItem()

M2MB_OS_RESULT_E m2mb_os_ev_setItem	(	M2MB_OS_EV_HANDLE	evHandle,
		M2MB_OS_EV_SEL_CMD_E	selCmd,
		void *	pIn
	)

Set specific properties of the event.

This service set value for specified parameter of the specified event if available To be used when event is already created: its right use is under application responsibility By Selecting cmd, a specified parameter to be set can be selected

Parameters

[in]	evHandle	handle of event
[in]	selCmd	Select parameter to be set (see M2MB_OS_EV_SEL_CMD_E)
[in]	pIn	pointer to value to be set. If a simple value, can be easily casted to (void*) e.g. int value -3 has to be passed, use (void*)-3 NULL if no value is needed

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_EVENT_ERROR Invalid event handle M2MB_OS_INVALID_ARG invalid arguments see M2MB_OS_RESULT_E in m2mb_os_types.h for others

Note

Not all the M2MB_OS_EV_SEL_CMD_E are always available. Of course M2MB_OS_EV_SEL_CMD_CREATE_ATTR is not right for this function Only M2MB_OS_EV_SEL_CMD_USRNAME is currently allowed are ok

Example

m2mb_os_ev_setItem( evHandle, M2MB_OS_EV_SEL_CMD_USRNAME, ( void* )"MyNewName" );