- -

Synchronize threads using signals. -More...

- - - - - -

-Macros
#define	osFeature_Signals 8
	maximum number of Signal Flags available per thread

- - - - - - - - - - -

-Functions
int32_t	osSignalSet (osThreadId thread_id, int32_t signals)
	Set the specified Signal Flags of an active thread.

int32_t	osSignalClear (osThreadId thread_id, int32_t signals)
	Clear the specified Signal Flags of an active thread.

osEvent	osSignalWait (int32_t signals, uint32_t millisec)
	Wait for one or more Signal Flags to become signaled for the current RUNNING thread.

-

Description

-

Signals are used to trigger execution states between threads. The signal management functions in CMSIS-RTOS allow you to control or wait for signal flags. Each thread has up to 31 assigned signal flags. The maximum number of signal flags is defined in the cmsis_os.h file (#define osFeature_Signals).

-

A thread

-

can wait for signals to be set (using osSignalWait). Using this function, it enters the WAITING state. The osSignalWait parameter signals defines the signals that are required to put the thread back into READY state.
may set one or more flags in any other given thread (using osSignalSet).
may clear its own signals or the signals of other threads (using osSignalClear).

-

When a thread wakes up and resumes execution, its signal flags are automatically cleared.

-

Working with Signals

-

Here is a simple example that shows how two thread can communicate with each others using signals:

-

-Simple signal event communication

-

The following steps are required to use signals:

-

In the thread (for example thread ID tid_thread1) that is supposed to wait for a signal, call the wait function:
osSignalWait (0x0001, osWaitForever); // wait forever for the signal 0x0001
-
In another thread (or threads) that are supposed to wake the waiting thread up call:
osSignalSet (tid_thread1, 0x0001); // set the signal 0x0001 for thread tid_thread1
-
osDelay (1000); // wait for 1 second
-

-

Macro Definition Documentation

- -

-

- - - - -

#define osFeature_Signals 8

-

The CMSIS-RTOS API may support a variable number of signal flags. This define specifies the number of signal flags available per thread. The maximum value is 32 signal flags per thread.

- -

-

Function Documentation

- -

-

- - - - - - - - - - - - - - - - - - -

int32_t osSignalClear	(	osThreadId	thread_id,
		int32_t	signals
	)

-

Parameters

- - - -

[in]	thread_id	thread ID obtained by osThreadCreate or osThreadGetId.
[in]	signals	specifies the signal flags of the thread that shall be cleared.

-

Returns: previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters or call from ISR.

-

Note: MUST REMAIN UNCHANGED: osSignalClear shall be consistent in every CMSIS-RTOS.

-

Clear the signal flags of an active thread.

-

Note: Cannot be called from Interrupt Service Routines.

-

Code Example

-

void Thread_2 (void const *arg);

-

-osThreadDef (Thread_2, osPriorityHigh, 1, 0);

- 

-static void EX_Signal_1 (void)  {

-  int32_t  signals;

-  osThreadId thread_id;

-  

-  thread_id = osThreadCreate (osThread(Thread_2), NULL);

-  if (thread_id == NULL)  {

-    // Failed to create a thread.

-  }

-  else  {

-f    :

-    signals = osSignalClear (thread_id, 0x01);

-  }

-}

-

-

- -

-

- - - - - - - - - - - - - - - - - - -

int32_t osSignalSet	(	osThreadId	thread_id,
		int32_t	signals
	)

-

Parameters

- - - -

[in]	thread_id	thread ID obtained by osThreadCreate or osThreadGetId.
[in]	signals	specifies the signal flags of the thread that should be set.

-

Returns: previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.

-

Note: MUST REMAIN UNCHANGED: osSignalSet shall be consistent in every CMSIS-RTOS.

-

Set the signal flags of an active thread. This function may be used also within interrupt service routines.

-

Note: Interrupt Service Routines can call this function.

-

Code Example

-

void Thread_2 (void const *arg);

- 

-osThreadDef (Thread_2, osPriorityHigh, 1, 0);

- 

-static void EX_Signal_1 (void)  {

-  int32_t signals;

-  uint32_t exec;

-  osThreadId thread_id;

-  

-  thread_id = osThreadCreate (osThread(Thread_2), NULL);

-  if (thread_id == NULL)  {

-    // Failed to create a thread.

-  }

-  else  {

-    signals = osSignalSet (thread_id, 0x00000005);         // Send signals to the created thread

-  }

-}

-

-

- -

-

- - - - - - - - - - - - - - - - - - -

osEvent osSignalWait	(	int32_t	signals,
		uint32_t	millisec
	)

-

Parameters

- - - -

[in]	signals	wait until all specified signal flags set or 0 for any single signal flag.
[in]	millisec	Timout Value or 0 in case of no time-out.

-

Returns: event flag information or error code.

-

Note: MUST REMAIN UNCHANGED: osSignalWait shall be consistent in every CMSIS-RTOS.

-

Suspend the execution of the current RUNNING thread until all specified signal flags with the parameter signals are set. When the parameter signals is 0 the current RUNNING thread is suspended until any signal is set. When these signal flags are already set, the function returns instantly. Otherwise the thread is put into the state WAITING. Signal flags that are reported as event are automatically cleared.

-

The argument millisec specifies how long the system waits for the specified signal flags. While the system waits the tread calling this function is put into the state WAITING. The timeout value can have the following values:

-

when millisec is 0, the function returns instantly.
when millisec is set to osWaitForever the function will wait for an infinite time until a specified signal is set.
all other values specify a time in millisecond for a timeout.

-

Status and Error Codes
-

-

osOK: no signal received when the timeout value millisec was 0.
osEventTimeout: signal not occurred within timeout
osEventSignal: signal occurred, value.signals contains the signal flags; these signal flags are cleared.
osErrorValue: the value signals is outside of the permitted range.
osErrorISR: osSignalWait cannot be called from interrupt service routines.

-

Note: Cannot be called from Interrupt Service Routines.

-

Code Example

-

void Thread_2 (void const *arg);

-  

-osThreadDef (Thread_2, osPriorityHigh, 1, 0);

-   

-static void EX_Signal_1 (void)  {

-  osThreadId thread_id;

-  osEvent evt;

-    

-  thread_id = osThreadCreate (osThread(Thread_2), NULL);

-  if (thread_id == NULL)  {

-    // Failed to create a thread.

-  }

-  else  {

-    :

-    // wait for a signal

-    evt = osSignalWait (0x01, 100);

-    if (evt.status == osEventSignal)  {

-          // handle event status

-    }

-  }

-}

-

-

-Macros

-Functions

Description

Working with Signals

Macro Definition Documentation

Function Documentation