MutexP.h File Reference

Detailed Description

Mutex module for the RTOS Porting Interface.

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

The MutexP module allows task to maintain critical region segments. The MutexP module has two main functions: MutexP_lock and MutexP_unlock.

The MutexP module supports recursive calls to the MutexP_lock API by a single task. The same number of MutexP_unlock calls must be done for the mutex to be release. Note: the returned key must be provided in the LIFO order. For example:

uintptr_t key1, key2;
key1 = MutexP_lock();
key2 = MutexP_lock();
MutexP_lock(key2);
MutexP_lock(key1);

---

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

Include dependency graph for MutexP.h:

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

Go to the source code of this file.

Data Structures
union	MutexP_Struct
	MutexP structure. More...
struct	MutexP_Params
	Basic MutexP Parameters. More...

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

Typedefs
typedef union MutexP_Struct	MutexP_Struct
	MutexP structure. More...
typedef void *	MutexP_Handle
	Opaque client reference to an instance of a MutexP. More...

Enumerations
enum	MutexP_Status { MutexP_OK = 0, MutexP_FAILURE = -1 }
	Status codes for MutexP APIs. More...

Functions
MutexP_Handle	MutexP_construct (MutexP_Struct *handle, MutexP_Params *params)
	Function to construct a mutex. More...
void	MutexP_destruct (MutexP_Struct *mutexP)
	Function to destruct a mutex object. More...
MutexP_Handle	MutexP_create (MutexP_Params *params)
	Function to create a mutex. More...
void	MutexP_delete (MutexP_Handle handle)
	Function to delete a mutex. More...
void	MutexP_Params_init (MutexP_Params *params)
	Initialize params structure to default values. More...
uintptr_t	MutexP_lock (MutexP_Handle handle)
	Function to lock a mutex. More...
void	MutexP_unlock (MutexP_Handle handle, uintptr_t key)
	Function to unlock a mutex. More...

Macro Definition Documentation

MutexP_STRUCT_SIZE

#define MutexP_STRUCT_SIZE   (80)

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

NoRTOS: 12 BIOS 6.x: 40 BIOS 7.x: 40 FreeRTOS: 80

Typedef Documentation

MutexP_Struct

typedef union MutexP_Struct MutexP_Struct

MutexP structure.

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

MutexP_Handle

typedef void* MutexP_Handle

Opaque client reference to an instance of a MutexP.

A MutexP_Handle returned from the MutexP_create represents that instance. and then is used in the other instance based functions (e.g. MutexP_lock, MutexP_unlock, etc.).

Enumeration Type Documentation

MutexP_Status

enum MutexP_Status

Status codes for MutexP APIs.

Enumerator
MutexP_OK	API completed successfully
MutexP_FAILURE	API failed

Function Documentation

MutexP_construct()

MutexP_Handle MutexP_construct	(	MutexP_Struct *	handle,
		MutexP_Params *	params
	)

Function to construct a mutex.

Parameters

handle	Pointer to a MutexP_Struct object
params	Pointer to the instance configuration parameters. NULL denotes to use the default parameters (MutexP default parameters as noted in MutexP_Params_init.

Returns

A MutexP_Handle on success or a NULL on an error

MutexP_destruct()

void MutexP_destruct

(

MutexP_Struct *

mutexP

)

Function to destruct a mutex object.

Parameters

mutexP

Pointer to a MutexP_Struct object that was passed to MutexP_construct().

Returns

MutexP_create()

MutexP_Handle MutexP_create

(

MutexP_Params *

params

)

Function to create a mutex.

Parameters

params

Pointer to the instance configuration parameters. NULL denotes to use the default parameters. The MutexP default parameters are noted in MutexP_Params_init.

Returns

A MutexP_Handle on success or a NULL on an error

MutexP_delete()

void MutexP_delete

(

MutexP_Handle

handle

)

Function to delete a mutex.

Parameters

handle

A MutexP_Handle returned from MutexP_create

MutexP_Params_init()

void MutexP_Params_init

(

MutexP_Params *

params

)

Initialize params structure to default values.

The default parameters are: callback - NULL.

Parameters

params

Pointer to the instance configuration parameters.

MutexP_lock()

uintptr_t MutexP_lock

(

MutexP_Handle

handle

)

Function to lock a mutex.

This function can only be called from a Task. It cannot be called from an interrupt. The lock will block until the mutex is available.

Users of a mutex should make every attempt to minimize the duration that that they have it locked. This is to minimize latency. It is recommended that the users of the mutex do not block while they have the mutex locked.

This function locks the mutex. If the mutex is locked multiple times by the caller, the same number of unlocks must be called.

Parameters

handle

A MutexP_Handle returned from MutexP_create

Returns

A key is returned. This key must be passed into MutexP_unlock.

MutexP_unlock()

void MutexP_unlock	(	MutexP_Handle	handle,
		uintptr_t	key
	)

Function to unlock a mutex.

This function unlocks the mutex. If the mutex is locked multiple times by the caller, the same number of unlocks must be called. The order of the keys must be reversed. For example

uintptr_t key1, key2;
key1 = MutexP_lock();
key2 = MutexP_lock();
MutexP_lock(key2);
MutexP_lock(key1);

Parameters

handle	A MutexP_Handle returned from MutexP_create
key	Return from MutexP_lock.