GateSwi.h File Reference

Detailed Description

Software Interrupt Gate.

GateSwi uses Swi_disable() and Swi_restore() as the resource locking mechanism. This gate can be used whenever the resource is being shared by Tasks or Swis.

The duration between the enter and leave should be as short as possible to minimize Swi latency.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Params_init	Y	Y	Y	Y	Y
query	Y	Y	Y	Y	Y
construct	Y	Y	Y	Y	N
create	N*	N*	Y	Y	N
delete	N*	N*	Y	Y	N
destruct	Y	Y	Y	Y	N
enter	N	Y	Y	Y**	Y**
leave	N	Y	Y	Y**	Y**
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. GateSwi_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. GateSwi_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/Swi.h>
#include <ti/sysbios/runtime/Error.h>

Include dependency graph for GateSwi.h:

Go to the source code of this file.

Data Structures
struct	GateSwi_Params
struct	GateSwi_Struct

Typedefs
typedef struct GateSwi_Params	GateSwi_Params
typedef struct GateSwi_Struct	GateSwi_Struct
typedef struct GateSwi_Struct	GateSwi_Object
typedef GateSwi_Object *	GateSwi_Handle

Functions
bool	GateSwi_canBePreempted (void)
	query Gate 'preempt' characteristics More...
bool	GateSwi_canBlock (void)
	query Gate 'blocking' characteristics More...
GateSwi_Handle	GateSwi_create (const GateSwi_Params *prms, Error_Block *eb)
	Create a GateSwi gate. More...
GateSwi_Handle	GateSwi_construct (GateSwi_Struct *obj, const GateSwi_Params *prms)
	Construct a GateSwi gate. More...
void	GateSwi_delete (GateSwi_Handle *gate)
	Delete a GateSwi gate. More...
void	GateSwi_destruct (GateSwi_Struct *obj)
	Destruct a GateSwi gate. More...
void	GateSwi_Params_init (GateSwi_Params *prms)
	Initialize the GateSwi_Params structure with default values. More...
intptr_t	GateSwi_enter (GateSwi_Handle gate)
	enter the GateSwi gate More...
void	GateSwi_leave (GateSwi_Handle gate, intptr_t key)
	leave the GateSwi gate More...

Typedef Documentation

GateSwi_Params

typedef struct GateSwi_Params GateSwi_Params

GateSwi_Struct

typedef struct GateSwi_Struct GateSwi_Struct

GateSwi_Object

typedef struct GateSwi_Struct GateSwi_Object

GateSwi_Handle

typedef GateSwi_Object* GateSwi_Handle

Function Documentation

GateSwi_canBePreempted()

bool GateSwi_canBePreempted

(

void

)

query Gate 'preempt' characteristics

GateSwi can be preempted by an hardware interrupt. Always returns true.

Return values

true

GateSwi_canBlock()

bool GateSwi_canBlock

(

void

)

query Gate 'blocking' characteristics

GateSwi enter will never block. This API always returns false.

Return values

false

GateSwi_create()

GateSwi_Handle GateSwi_create	(	const GateSwi_Params *	prms,
		Error_Block *	eb
	)

Create a GateSwi gate.

Parameters

prms	optional parameters
eb	error block

Return values

GateSwi

handle (NULL on failure)

GateSwi_construct()

GateSwi_Handle GateSwi_construct	(	GateSwi_Struct *	obj,
		const GateSwi_Params *	prms
	)

Construct a GateSwi gate.

GateSwi_construct is equivalent to GateHwi_create except that the GateSwi_Struct is pre-allocated.

Parameters

obj	pointer to a GateSwi object
prms	optional parameters

Return values

GateSwi

handle (NULL on failure)

GateSwi_delete()

void GateSwi_delete

(

GateSwi_Handle *

gate

)

Delete a GateSwi gate.

Note that GateSwi_delete takes a pointer to a GateHwi_Handle which enables GateSwi_delete to set the GateHwi handle to NULL.

Parameters

gate	pointer to a GateSwi handle

GateSwi_destruct()

void GateSwi_destruct

(

GateSwi_Struct *

obj

)

Destruct a GateSwi gate.

Parameters

obj	pointer to a GateSwi objects

GateSwi_Params_init()

void GateSwi_Params_init

(

GateSwi_Params *

prms

)

Initialize the GateSwi_Params structure with default values.

GateSwi_Params_init initializes the GateHwi_Params structure with default values. GateSwi_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

GateSwi_enter()

intptr_t GateSwi_enter

(

GateSwi_Handle

gate

)

enter the GateSwi gate

GateSwi_enter enters the GateHwi gate and returns a key for use by GateSwi_enter. GateHwi_enter calls can be nested and the key is used to unlock the gate on the final call to GateSwi_leave.

Parameters

gate	GateSwi handle

Return values

opaque

key to be passed to GateSwi_leave()

GateSwi_leave()

void GateSwi_leave	(	GateSwi_Handle	gate,
		intptr_t	key
	)

leave the GateSwi gate

GateSwi_leave exits the GateHwi gate if key matches the outermost call to GateSwi_enter. If GateHwi_enter calls are nested, the key will keep the nested calls from leaving the gate.

Parameters

gate	GateSwi handle
key	opaque key to unlock the gate