Functions for creating, initializing, maintaining and handling Semaphores. More...

Data Structures
struct	semStruc
	Struct for semaphore maintenance. More...

Macros
#define	SEM_NR_OF_TSK_REF_BYTES (uint8_t)((NR_OF_TSKS >> 3) + 1)
	Bytes needed to create a mask for all available tasks.

#define	MEM_OBJECTS_SEM (uint8_t)0x4u
	Number of objects for the semaphore memory pool. More...

#define	AMOUNT_OF_SEMS ((uint8_t)0x2u)
	Defines the maximum amount of different semaphores in the system. More...

#define	MEM_OBJECTS_SEM ((uint8_t)0x4u)
	Number of SyncEle that will be allocated by the Semaphore mechanism in its memory pool. More...

Typedefs
typedef uint8_t	SemNr
	Number of a semaphore.

typedef uint8_t	SemCntr
	Used as a counter variable for semaphores.

typedef enum semTypeEnum	SemType
	Enumeartion of Semaphore types.

typedef struct semStruc	Sem
	Struct for semaphore maintenance. More...

Enumerations

Functions
RetCode	sem_InitSems (void)
	Initialize the semaphore functionality. More...

static RetCode	sem_InsertTskSemQ (PSem const pSem, const SemNr semNr, PTskTCB const pTskToIns)
	Insert the given Task into the Semaphore's wait queue. More...

static TskID	sem_GetNextTskSemQ (PSem const pSem, const SemNr semNr)
	Retrieve the next Task from the Semaphore's wait queue. More...

RetCode	sem_initBinSem (const SemNr semNr)
	Initialize the Semaphore corresponding to the given number as a Binary Semaphore. More...

RetCode	sem_initCntSem (const SemNr semNr, const SemCntr ressourceCntr)
	Initialize the Semaphore corresponding to the given number as a counting Semaphore. More...

RetCode	sem_wait (const SemNr semNr, PTskTCB const tsk, const SysTicks maxSysTicksToWait)
	Request access to the resource guarded by the Semaphore corresponding to the given number. More...

RetCode	sem_Tsksignal (const SemNr semNr, PTskTCB const tsk)
	Signal the Semaphore from Task context. See sem_signal. More...

RetCode	sem_signal (const SemNr semNr)
	Signal the Semaphore to make its resources available again. More...

RetCode	sem_DeleteTskSemQ (PTskTCB const tsk)
	Delete a SemLst entry from the semaphore queue. More...

Variables
static Sem	ar_Sems [AMOUNT_OF_SEMS]
	Contains all semaphores.

static volatile TskID	ar_SemsWaitQueue [AMOUNT_OF_SEMS]
	Contains the TskID of the start of the respective semaphore's wait queue.

static volatile MemPoolID	memPoolID_SEM
	ID of the memory pool memory allocation request of semaphores are served from.

Detailed Description

Functions for creating, initializing, maintaining and handling Semaphores.

Priority Inheritance

When access to a specific resource is requested, but cannot be granted, the requesting consumer is put into a wait queue. These wait queues are sorted according to the priority of their entities. Therefore a waiting high priority task will be granted access to the resource before a waiting low priority task receives the resource. But if the resource is taken by a lower priority task and a high priority task requests access, the resource remains at the lower priority task. Therefore the high priority task is put into a waiting queue and its execution is suspended. If the lower priority task occupying the resource is suspended, because e.g. a medium priority task is activated, this medium priority task would receive processor time before the high priority task, that is currently waiting on the resource. This is called Priority Inversion.
To avoid that a lower priority task is executed before a high priority task Priority Inheritance is introduced. If a lower priority priority task is occupying a resource while a high priority task requests access to said resource the lower priority task inherits the priority of the high priority task for the duration of the access to the protected resource. Hence a medium priority task cannot preempt the actually lower priority task while it is occupying the resource and the high priority task is waiting for this resource.

Semaphores

Semaphores are a signaling mechanism to allow multiple access to a protected resource. A consumer does not get ownership of the semaphore. If a consumer is granted access the semaphore counter is decremented. When the consumer is done with accessing the protected resource the semaphore is then incremented again. As soon as the counter reaches 0 no more accesses to the protected resource will be granted. All incoming consumers are put into a wait queue and must wait for the counter to increment again and therefore for another consumer, who was previously granted access to the resource, to release the resource and hence increment the semaphore counter.

Counting Semaphores

Counting semaphores contain a counter which can be set to a specific value are incremented variably and decremented by one. This is used to limit access to a resource to the counter value.

Binary Semaphores

Contrary to counting semaphores, binary semaphores can only take the values 0 or 1 (taken or free). Much like mutexes they can be used for mutual exclusion, but unlike mutexes the consumer, which is granted access, does not receive the ownership of the semaphore.

Difference Mutex and Binary Semaphore

Since a Binary Semaphore only depends on signaling, it can be signaled from anywhere, whereas a mutex can only be released by the task that occupies it.

Macro Definition Documentation

#define AMOUNT_OF_SEMS ((uint8_t)0x2u)

Defines the maximum amount of different semaphores in the system.

Note: User Defined

#define MEM_OBJECTS_SEM (uint8_t)0x4u

Number of objects for the semaphore memory pool.

Note: User defined

#define MEM_OBJECTS_SEM ((uint8_t)0x4u)

Number of SyncEle that will be allocated by the Semaphore mechanism in its memory pool.

Note: User defined

Typedef Documentation

typedef struct semStruc Sem

Struct for semaphore maintenance.

Contains information about the semaphore.

Enumeration Type Documentation

enum semTypeEnum

Enumeartion of Semaphore types.

Enumerator
SemBin	Binary Semaphore.
SemCnt	Counting Semaphore.

Function Documentation

RetCode sem_DeleteTskSemQ ( PTskTCB const tsk )

Delete a SemLst entry from the semaphore queue.

Parameters

[in] tsk Task to be deleted from the semaphore's queue it is currently queued into

Returns: Return the success of the operation

static TskID sem_GetNextTskSemQ	(	PSem const	pSem,
		const SemNr	semNr
	)

static

Retrieve the next Task from the Semaphore's wait queue.

Parameters

[in]	pSem	Semaphore to which the wait queue belongs to
[in]	semNr	Number of the Semaphore

Returns: TskID

RetCode sem_initBinSem ( const SemNr semNr )

Initialize the Semaphore corresponding to the given number as a Binary Semaphore.

Parameters

[in] semNr Number of the Semaphore to initialize

Returns: RetCode; RET_OK; RET_NOK

RetCode sem_initCntSem	(	const SemNr	semNr,
		const SemCntr	ressourceCntr
	)

Initialize the Semaphore corresponding to the given number as a counting Semaphore.

Parameters

[in]	semNr	Number of the Semaphore to initialize
[in]	ressourceCntr	Number of ressources to initialize the Semaphore's counter with

Returns: RetCode; RET_OK; RET_NOK

RetCode sem_InitSems ( void )

Initialize the semaphore functionality.

Returns: RetCode Success of the operation

Warning: Semaphores need to be initialized before usage! Usually this takes place during initialization of the OS.

static RetCode sem_InsertTskSemQ	(	PSem const	pSem,
		const SemNr	semNr,
		PTskTCB const	pTskToIns
	)

static

Insert the given Task into the Semaphore's wait queue.

Parameters

[in]	pSem	Semaphore to which the wait queue belongs
[in]	semNr	Number of the semaphore
[in]	pTskToIns	Task to insert into the wait queue

Returns: RetCode; RET_OK; RET_NOK

RetCode sem_signal ( const SemNr semNr )

Signal the Semaphore to make its resources available again.

Parameters

[in] semNr Number of the Semaphore

Returns: RetCode; RET_OK; RET_NOK

Calling this function increments the Semaphore's resource counter.

Note: Tasks should use sem_Tsksignal!; Can be called for binary as well as counting Semaphores

RetCode sem_Tsksignal	(	const SemNr	semNr,
		PTskTCB const	tsk
	)

Signal the Semaphore from Task context. See sem_signal.

Parameters

[in]	semNr	Number of the Semaphore
[in]	tsk	Task which signals the Semaphore

Returns: RetCode; RET_OK; RET_NOK

Note: Tasks should use this function to signal a Semaphore!; Can be called for binary as well as counting Semaphores

Warning: The specified Task has to have made a wait request to the specified Semaphore beforehand!

RetCode sem_wait	(	const SemNr	semNr,
		PTskTCB const	tsk,
		const SysTicks	maxSysTicksToWait
	)

Request access to the resource guarded by the Semaphore corresponding to the given number.

Parameters

[in]	semNr	Number of the Semaphore
[in]	tsk	Task for which the request is made
[in]	maxSysTicksToWait	Maximum time in SysTicks the Task will be blocked

Returns: RetCode; RET_OK; RET_NOK

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Priority Inheritance

Semaphores

Counting Semaphores

Binary Semaphores

Difference Mutex and Binary Semaphore

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation