GateHwi.h File Reference

Detailed Description

Hardware Interrupt Gate.

GateHwi uses disabling and enabling of interrupts as the resource locking mechanism. Such a gate guarantees exclusive access to the CPU. This gate can be used whenever the resource is being shared by Tasks, Swis, and/or Hwis.

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

GateHwi inherits from xdc.runtime.IGateProvider, therefore supports nesting.

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	Y	Y	Y	Y**	Y**
leave	Y	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. GateHwi_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. GateHwi_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/runtime/Error.h>

Include dependency graph for GateHwi.h:

Go to the source code of this file.

Data Structures
struct	GateHwi_Params
struct	GateHwi_Struct

Typedefs
typedef struct GateHwi_Params	GateHwi_Params
typedef struct GateHwi_Struct	GateHwi_Struct
typedef struct GateHwi_Struct	GateHwi_Object
typedef GateHwi_Object *	GateHwi_Handle

Functions
bool	GateHwi_canBePreempted (void)
	query Gate 'preempt' characteristics More...
bool	GateHwi_canBlock (void)
	query Gate 'blocking' characteristics More...
GateHwi_Handle	GateHwi_create (const GateHwi_Params *prms, Error_Block *eb)
	Create a GateHwi gate. More...
GateHwi_Handle	GateHwi_construct (GateHwi_Struct *obj, const GateHwi_Params *prms)
	Construct a GateHwi gate. More...
void	GateHwi_delete (GateHwi_Handle *gate)
	Delete a GateHwi gate. More...
void	GateHwi_destruct (GateHwi_Struct *obj)
	Destruct a GateHwi gate. More...
void	GateHwi_Params_init (GateHwi_Params *prms)
	Initialize the GateHwi_Params structure with default values. More...
intptr_t	GateHwi_enter (GateHwi_Handle gate)
	enter the GateHwi gate More...
void	GateHwi_leave (GateHwi_Handle gate, intptr_t key)
	leave the GateHwi gate More...

Typedef Documentation

GateHwi_Params

typedef struct GateHwi_Params GateHwi_Params

GateHwi_Struct

typedef struct GateHwi_Struct GateHwi_Struct

GateHwi_Object

typedef struct GateHwi_Struct GateHwi_Object

GateHwi_Handle

typedef GateHwi_Object* GateHwi_Handle

Function Documentation

GateHwi_canBePreempted()

bool GateHwi_canBePreempted

(

void

)

query Gate 'preempt' characteristics

GateHwi cannot be preempted. This API always returns false.

Return values

false

GateHwi_canBlock()

bool GateHwi_canBlock

(

void

)

query Gate 'blocking' characteristics

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

Return values

false

GateHwi_create()

GateHwi_Handle GateHwi_create	(	const GateHwi_Params *	prms,
		Error_Block *	eb
	)

Create a GateHwi gate.

Parameters

prms	optional parameters
eb	error block

Return values

GateHwi

handle (NULL on failure)

GateHwi_construct()

GateHwi_Handle GateHwi_construct	(	GateHwi_Struct *	obj,
		const GateHwi_Params *	prms
	)

Construct a GateHwi gate.

GateHwi_construct is equivalent to GateHwi_create except that the GateHwi_Struct is pre-allocated.

Parameters

obj	pointer to a GateHwi object
prms	optional parameters

Return values

GateHwi

handle (NULL on failure)

GateHwi_delete()

void GateHwi_delete

(

GateHwi_Handle *

gate

)

Delete a GateHwi gate.

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

Parameters

gate	pointer to a GateHwi handle

GateHwi_destruct()

void GateHwi_destruct

(

GateHwi_Struct *

obj

)

Destruct a GateHwi gate.

Parameters

obj	pointer to a GateHwi objects

GateHwi_Params_init()

void GateHwi_Params_init

(

GateHwi_Params *

prms

)

Initialize the GateHwi_Params structure with default values.

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

GateHwi_enter()

intptr_t GateHwi_enter

(

GateHwi_Handle

gate

)

enter the GateHwi gate

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

Parameters

gate	GateHwi handle

Return values

opaque

key to be passed to GateHwi_leave()

GateHwi_leave()

void GateHwi_leave	(	GateHwi_Handle	gate,
		intptr_t	key
	)

leave the GateHwi gate

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

Parameters

gate	GateHwi handle
key	opaque key to unlock the gate