Detailed Description

Mutex Gate.

GateMutex uses a Semaphore as the resource locking mechanism. Each GateMutex instance has its own unique Semaphore. This gate can only be used by a Task as a gate can potentially block. This gate cannot be used by a Hwi or Swi.

The task that uses a gate can call enter() any number of times without risk of being blocked, although relinquishing ownership of the gate requires a balanced number of calls to leave().

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Params_init	Y	Y	Y	Y	Y
query	Y	Y	Y	Y	Y
construct	N	N	Y	Y	N
create	N*	N*	Y	Y	N
delete	N*	N*	Y	Y	N
destruct	N	N	Y	Y	N
enter	N	N	Y	N	N
leave	N	N	Y	N	N
Definitions: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. GateMutex_Module_startupDone() returns true). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. GateMutex_Module_startupDone() returns false). : Assuming blocking Heap is used for creation. *: Must be used in enter/leave pairs.

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Semaphore.h>
#include <ti/sysbios/knl/Task.h>
#include <ti/sysbios/runtime/Error.h>

Include dependency graph for GateMutex.h:

Go to the source code of this file.

Data Structures
struct	GateMutex_Params

struct	GateMutex_Struct

Macros
#define	GateMutex_A_badContext "bad calling context"
	Assert when GateMutex_enter() is not called from correct context. GateMutex_enter() can only be called from main() or Task context (not Hwi or Swi). More...

Typedefs
typedef struct GateMutex_Params	GateMutex_Params

typedef struct GateMutex_Struct	GateMutex_Struct

typedef struct GateMutex_Struct	GateMutex_Object

typedef GateMutex_Object *	GateMutex_Handle

Functions
bool	GateMutex_canBePreempted (void)
	query Gate 'preempt' characteristics More...

bool	GateMutex_canBlock (void)
	query Gate 'blocking' characteristics More...

GateMutex_Handle	GateMutex_create (const GateMutex_Params prms, Error_Block eb)
	Create a `GateMutex` gate. More...

GateMutex_Handle	GateMutex_construct (GateMutex_Struct obj, const GateMutex_Params prms)
	Construct a `GateMutex` gate. More...

void	GateMutex_delete (GateMutex_Handle *gate)
	Delete a `GateMutex` gate. More...

void	GateMutex_destruct (GateMutex_Struct *obj)
	Destruct a `GateMutex` gate. More...

void	GateMutex_Params_init (GateMutex_Params *prms)
	Initialize the GateMutex_Params structure with default values. More...

intptr_t	GateMutex_enter (GateMutex_Handle gate)
	enter the GateMutex gate More...

void	GateMutex_leave (GateMutex_Handle gate, intptr_t key)
	leave the GateMutex gate More...

GateMutex_Handle	GateMutex_Object_first (void)
	return handle of the first GateMutex on GateMutex list More...

GateMutex_Handle	GateMutex_Object_next (GateMutex_Handle gate)
	return handle of the next GateMutex on GateMutex list More...

Macro Definition Documentation

§ GateMutex_A_badContext

#define GateMutex_A_badContext "bad calling context"

Assert when GateMutex_enter() is not called from correct context. GateMutex_enter() can only be called from main() or Task context (not Hwi or Swi).

Common causes and workarounds for hitting this Assert:

Calling printf() from a Hwi or Swi thread. Use System_printf (with SysMin) instead.
Calling Memory_alloc() from a Hwi or Swi thread. Use a different Heap manager or change the memory manager's gate type.

Typedef Documentation

§ GateMutex_Params

typedef struct GateMutex_Params GateMutex_Params

§ GateMutex_Struct

typedef struct GateMutex_Struct GateMutex_Struct

§ GateMutex_Object

typedef struct GateMutex_Struct GateMutex_Object

§ GateMutex_Handle

typedef GateMutex_Object* GateMutex_Handle

Function Documentation

§ GateMutex_canBePreempted()

bool GateMutex_canBePreempted ( void )

query Gate 'preempt' characteristics

GateMutex can be preempted. This API always returns true.

Return values

true

§ GateMutex_canBlock()

bool GateMutex_canBlock ( void )

query Gate 'blocking' characteristics

GateMutex enter can block if another task owns the gate. This API always returns true.

Return values

true

§ GateMutex_create()

GateMutex_Handle GateMutex_create	(	const GateMutex_Params *	prms,
		Error_Block *	eb
	)

Create a GateMutex gate.

Parameters

prms	optional parameters
eb	error block

Return values

GateMutex handle (NULL on failure)

§ GateMutex_construct()

GateMutex_Handle GateMutex_construct	(	GateMutex_Struct *	obj,
		const GateMutex_Params *	prms
	)

Construct a GateMutex gate.

GateMutex_construct is equivalent to GateMutex_create except that the GateMutex_Struct is pre-allocated.

Parameters

obj	pointer to a GateMutex object
prms	optional parameters

Return values

GateMutex handle (NULL on failure)

§ GateMutex_delete()

void GateMutex_delete ( GateMutex_Handle * gate )

Delete a GateMutex gate.

Note that GateMutex_delete takes a pointer to a GateMutex_Handle which enables GateMutex_delete to set the GateMutex handle to NULL.

Parameters

gate	pointer to a GateMutex handle

§ GateMutex_destruct()

void GateMutex_destruct ( GateMutex_Struct * obj )

Destruct a GateMutex gate.

Parameters

obj	pointer to a GateMutex objects

§ GateMutex_Params_init()

void GateMutex_Params_init ( GateMutex_Params * prms )

Initialize the GateMutex_Params structure with default values.

GateMutex_Params_init initializes the GateMutex_Params structure with default values. GateMutex_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.

Parameters

prms	pointer to uninitialized params structure

§ GateMutex_enter()

intptr_t GateMutex_enter ( GateMutex_Handle gate )

enter the GateMutex gate

GateMutex_enter enters the GateMutex gate and returns a key for use by GateMutex_enter. GateMutex_enter calls can be nested and the key is used to unlock the gate on the final call to GateMutex_leave.

Parameters

gate	GateMutex handle

Return values

opaque key to be passed to GateMutex_leave()

§ GateMutex_leave()

void GateMutex_leave	(	GateMutex_Handle	gate,
		intptr_t	key
	)

leave the GateMutex gate

GateMutex_leave exits the GateMutex gate if key matches the outermost call to GateMutex_enter. If GateMutex_enter calls are nested, the key will keep the nested calls from leaving the gate.

Parameters

gate	GateMutex handle
key	opaque key to unlock the gate

§ GateMutex_Object_first()

GateMutex_Handle GateMutex_Object_first ( void )

return handle of the first GateMutex on GateMutex list

Return the handle of the first GateMutex on the create/construct list. NULL if no GateMutex instances have been created or constructed.

Return values

GateMutex handle

§ GateMutex_Object_next()

GateMutex_Handle GateMutex_Object_next ( GateMutex_Handle gate )

return handle of the next GateMutex on GateMutex list

Return the handle of the next GateMutex on the create/construct list. NULL if no more GateMutexs are on the list.

Parameters

gate	GateMutex handle

Return values

GateMutex handle

Detailed Description

Calling Context

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ GateMutex_A_badContext

Typedef Documentation

§ GateMutex_Params

§ GateMutex_Struct

§ GateMutex_Object

§ GateMutex_Handle

Function Documentation

§ GateMutex_canBePreempted()

§ GateMutex_canBlock()

§ GateMutex_create()

§ GateMutex_construct()

§ GateMutex_delete()

§ GateMutex_destruct()

§ GateMutex_Params_init()

§ GateMutex_enter()

§ GateMutex_leave()

§ GateMutex_Object_first()

§ GateMutex_Object_next()