Detailed Description

Semaphore module for the RTOS Porting Interface.

============================================================================

Semaphores can be counting semaphores or binary semaphores. Counting semaphores keep track of the number of times the semaphore has been posted with post functions. This is useful, for example, if you have a group of resources that are shared between tasks. Such tasks might call pend() to see if a resource is available before using one. A count of zero for a counting semaphore denotes that it is not available. A positive count denotes how many times a SemaphoreP_pend can be called before it is blocked (or returns SemaphoreP_TIMEOUT).

Binary semaphores can have only two states: available (count = 1) and unavailable (count = 0). They can be used to share a single resource between tasks. They can also be used for a basic signalling mechanism, where the semaphore can be posted multiple times. Binary semaphores do not keep track of the count; they simply track whether the semaphore has been posted or not.

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for SemaphoreP.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
union	SemaphoreP_Struct
	SemaphoreP structure. More...

struct	SemaphoreP_Params
	Basic SemaphoreP Parameters. More...

Macros
#define	SemaphoreP_STRUCT_SIZE (80)
	Number of bytes greater than or equal to the size of any RTOS SemaphoreP object. More...

#define	SemaphoreP_WAIT_FOREVER ~(0)
	Wait forever define. More...

#define	SemaphoreP_NO_WAIT (0)
	No wait define. More...

Typedefs
typedef union SemaphoreP_Struct	SemaphoreP_Struct
	SemaphoreP structure. More...

typedef void *	SemaphoreP_Handle
	Opaque client reference to an instance of a SemaphoreP. More...

Enumerations
enum	SemaphoreP_Status { SemaphoreP_OK = 0, SemaphoreP_TIMEOUT = -1 }
	Status codes for SemaphoreP APIs (for backwards compatibility) More...

enum	SemaphoreP_Mode { SemaphoreP_Mode_COUNTING = 0x0, SemaphoreP_Mode_BINARY = 0x1 }
	Mode of the semaphore. More...

Functions
SemaphoreP_Handle	SemaphoreP_construct (SemaphoreP_Struct handle, unsigned int count, SemaphoreP_Params params)

SemaphoreP_Handle	SemaphoreP_constructBinary (SemaphoreP_Struct *handle, unsigned int count)

void	SemaphoreP_destruct (SemaphoreP_Struct *semP)

SemaphoreP_Handle	SemaphoreP_create (unsigned int count, SemaphoreP_Params *params)
	Function to create a semaphore. More...

SemaphoreP_Handle	SemaphoreP_createBinary (unsigned int count)
	Function to create a binary semaphore. More...

SemaphoreP_Handle	SemaphoreP_createBinaryCallback (unsigned int count, void(*callback)(void))
	Function to create a binary semaphore. More...

void	SemaphoreP_delete (SemaphoreP_Handle handle)
	Function to delete a semaphore. More...

void	SemaphoreP_Params_init (SemaphoreP_Params *params)
	Initialize params structure to default values. More...

SemaphoreP_Status	SemaphoreP_pend (SemaphoreP_Handle handle, uint32_t timeout)
	Function to pend (wait) on a semaphore. More...

void	SemaphoreP_post (SemaphoreP_Handle handle)
	Function to post (signal) a semaphore from task of ISR context. More...

Variables
SemaphoreP_Params	SemaphoreP_defaultParams
	Default SemaphoreP instance parameters. More...

Macro Definition Documentation

§ SemaphoreP_STRUCT_SIZE

#define SemaphoreP_STRUCT_SIZE (80)

Number of bytes greater than or equal to the size of any RTOS SemaphoreP object.

NoRTOS: 16 BIOS 6.x: 28 BIOS 7.x: 28 FreeRTOS: 80

§ SemaphoreP_WAIT_FOREVER

#define SemaphoreP_WAIT_FOREVER ~(0)

Wait forever define.

§ SemaphoreP_NO_WAIT

#define SemaphoreP_NO_WAIT (0)

No wait define.

Typedef Documentation

§ SemaphoreP_Struct

typedef union SemaphoreP_Struct SemaphoreP_Struct

SemaphoreP structure.

Opaque structure that should be large enough to hold any of the RTOS specific SemaphoreP objects.

§ SemaphoreP_Handle

typedef void* SemaphoreP_Handle

Opaque client reference to an instance of a SemaphoreP.

A SemaphoreP_Handle returned from the SemaphoreP_create represents that instance and is used in the other instance based functions (e.g. SemaphoreP_post or SemaphoreP_pend, etc.).

Enumeration Type Documentation

§ SemaphoreP_Status

enum SemaphoreP_Status

Status codes for SemaphoreP APIs (for backwards compatibility)

Enumerator
SemaphoreP_OK	API completed successfully
SemaphoreP_TIMEOUT	API failed because of a timeout

§ SemaphoreP_Mode

enum SemaphoreP_Mode

Mode of the semaphore.

Enumerator
SemaphoreP_Mode_COUNTING
SemaphoreP_Mode_BINARY

Function Documentation

§ SemaphoreP_construct()

SemaphoreP_Handle SemaphoreP_construct	(	SemaphoreP_Struct *	handle,
		unsigned int	count,
		SemaphoreP_Params *	params
	)

§ SemaphoreP_constructBinary()

SemaphoreP_Handle SemaphoreP_constructBinary	(	SemaphoreP_Struct *	handle,
		unsigned int	count
	)

§ SemaphoreP_destruct()

void SemaphoreP_destruct ( SemaphoreP_Struct * semP )

§ SemaphoreP_create()

SemaphoreP_Handle SemaphoreP_create	(	unsigned int	count,
		SemaphoreP_Params *	params
	)

Function to create a semaphore.

Parameters

count	Initial count of the semaphore. For binary semaphores, only values of 0 or 1 are valid.
params	Pointer to the instance configuration parameters. NULL denotes to use the default parameters (SemaphoreP default parameters as noted in SemaphoreP_Params_init.

Returns: A SemaphoreP_Handle on success or a NULL on an error

§ SemaphoreP_createBinary()

SemaphoreP_Handle SemaphoreP_createBinary ( unsigned int count )

Function to create a binary semaphore.

This can be used instead of SemaphoreP_create() to create a binary semaphore.

Parameters

count Initial count of the binary semaphore. Only values of 0 or 1 are valid.

Returns: A SemaphoreP_Handle on success or a NULL on an error

§ SemaphoreP_createBinaryCallback()

SemaphoreP_Handle SemaphoreP_createBinaryCallback	(	unsigned int	count,
		void(*)(void)	callback
	)

Function to create a binary semaphore.

This can be used instead of SemaphoreP_create() to create a binary semaphore.

Parameters

count	Initial count of the binary semaphore. Only values of 0 or 1 are valid.
callback	Callback while pending for semaphore post

Returns: A SemaphoreP_Handle on success or a NULL on an error

§ SemaphoreP_delete()

void SemaphoreP_delete ( SemaphoreP_Handle handle )

Function to delete a semaphore.

Parameters

handle A SemaphoreP_Handle returned from SemaphoreP_create

§ SemaphoreP_Params_init()

void SemaphoreP_Params_init ( SemaphoreP_Params * params )

Initialize params structure to default values.

The default parameters are:

mode: SemaphoreP_Mode_COUNTING
name: NULL

Parameters

params Pointer to the instance configuration parameters.

§ SemaphoreP_pend()

SemaphoreP_Status SemaphoreP_pend	(	SemaphoreP_Handle	handle,
		uint32_t	timeout
	)

Function to pend (wait) on a semaphore.

Parameters

handle	A SemaphoreP_Handle returned from SemaphoreP_create
timeout	Timeout (in ClockP ticks) to wait for the semaphore to be posted (signalled).

Returns

Status of the functions

SemaphoreP_OK: Obtained the semaphore
SemaphoreP_TIMEOUT: Timed out. Semaphore was not obtained.

§ SemaphoreP_post()

void SemaphoreP_post ( SemaphoreP_Handle handle )

Function to post (signal) a semaphore from task of ISR context.

Parameters

handle A SemaphoreP_Handle returned from SemaphoreP_create

Variable Documentation

§ SemaphoreP_defaultParams

SemaphoreP_Params SemaphoreP_defaultParams

Default SemaphoreP instance parameters.

SemaphoreP_defaultParams represents the default parameters that are used when creating or constructing a SemaphoreP instance. SemaphoreP_Params_init() will use the contents of this structure for initializing the SemaphoreP_Params instance.

SemaphoreP_defaultParams is exposed to the application for the purpose of allowing the application to change the default parameters for all SemaphoreP instances created thereafter. The main intent for allowing the default parameters to be changed is for setting a semaphore's callback function to Power_idleFunc(), so that the SOC can enter low power mode when pending on a semaphore.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ SemaphoreP_STRUCT_SIZE

§ SemaphoreP_WAIT_FOREVER

§ SemaphoreP_NO_WAIT

Typedef Documentation

§ SemaphoreP_Struct

§ SemaphoreP_Handle

Enumeration Type Documentation

§ SemaphoreP_Status

§ SemaphoreP_Mode

Function Documentation

§ SemaphoreP_construct()

§ SemaphoreP_constructBinary()

§ SemaphoreP_destruct()

§ SemaphoreP_create()

§ SemaphoreP_createBinary()

§ SemaphoreP_createBinaryCallback()

§ SemaphoreP_delete()

§ SemaphoreP_Params_init()

§ SemaphoreP_pend()

§ SemaphoreP_post()

Variable Documentation

§ SemaphoreP_defaultParams