module ti.sysbios.gates.GateSwi

Software Interrupt Gate

C synopsis
Individual elements
XDCscript usage
Individual elements

GateSwi uses disabling and enabling of software interrupts as the resource locking mechanism. This gate can be used whenever the resource is being shared by Swis or Tasks. This gate cannot be used by a Hwi. [ more ... ]

C synopsis target-domain sourced in ti/sysbios/gates/GateSwi.xdc

#include <ti/sysbios/gates/GateSwi.h>

Functions
Void	GateSwi_construct// Initialize a new instance object inside the provided structure(GateSwi_Struct structP, const GateSwi_Params params);
GateSwi_Handle	GateSwi_create// Allocate and initialize a new instance object and return its handle(const GateSwi_Params params, Error_Block eb);
Void	GateSwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateSwi_Handle *handleP);
Void	GateSwi_destruct// Finalize the instance object inside the provided structure(GateSwi_Struct *structP);
Void	GateSwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateSwi_Params *params);
Functions common to all IGateProvider modules
Bool	GateSwi_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
	GateSwi_handle// Convert this instance structure pointer into an instance handle, GateSwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateSwi_Handle_label// The label associated with this instance object, GateSwi_Handle_name// The name of this instance object, GateSwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateSwi_Object_count// The number of statically-created instance objects, GateSwi_Object_first// The handle of the first dynamically-created instance object, or NULL, GateSwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateSwi_Object_heap// The heap used to allocate dynamically-created instance objects, GateSwi_Object_next// The handle of the next dynamically-created instance object, or NULL, GateSwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	GateSwi_Module_getMask// Returns the diagnostics mask for this module, GateSwi_Module_hasMask// Test whether this module has a diagnostics mask, GateSwi_Module_heap// The heap from which this module allocates memory, GateSwi_Module_id// Get this module's unique id, GateSwi_Module_setMask// Set the diagnostics mask for this module, GateSwi_Module_startupDone// Test if this module has completed startup
Defines
#define	GateSwi_Q_BLOCKING// Blocking quality (Int)1
#define	GateSwi_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateSwi_Object *	GateSwi_Handle// Client reference to an instance object;
typedef struct	GateSwi_Object// Opaque internal representation of an instance object GateSwi_Object;
typedef struct	GateSwi_Params// Instance config-params structure ...
typedef struct	GateSwi_Struct// Opaque client structure large enough to hold an instance object GateSwi_Struct;
Constants
extern const Assert_Id	GateSwi_A_badContext// Asserted when enter or leave is called from a hardware interrupt thread;

DETAILS

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

GateSwi 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	N	Y	Y	Y**	N
leave	N	Y	Y	Y**	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. 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.

const GateSwi_Q_BLOCKING

index URL

Blocking quality

C synopsis target-domain

#define GateSwi_Q_BLOCKING (Int)1

DETAILS

Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.

const GateSwi_Q_PREEMPTING

index URL

Preempting quality

C synopsis target-domain

#define GateSwi_Q_PREEMPTING (Int)2

DETAILS

Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.

config GateSwi_A_badContext // module-wide

index URL

Asserted when enter or leave is called from a hardware interrupt thread

C synopsis target-domain

extern const Assert_Id GateSwi_A_badContext;

GateSwi_query() // module-wide

index URL

Runtime test for a particular gate quality

C synopsis target-domain

Bool GateSwi_query(Int qual);

ARGUMENTS

qual — constant describing a quality

RETURNS

Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.

Module-Wide Built-Ins

index URL

C synopsis target-domain

Types_ModuleId GateSwi_Module_id();

// Get this module's unique id

Bool GateSwi_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle GateSwi_Module_heap();

// The heap from which this module allocates memory

Bool GateSwi_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 GateSwi_Module_getMask();

// Returns the diagnostics mask for this module

Void GateSwi_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct GateSwi_Object GateSwi_Object;

// Opaque internal representation of an instance object

typedef GateSwi_Object *GateSwi_Handle;

// Client reference to an instance object

typedef struct GateSwi_Struct GateSwi_Struct;

// Opaque client structure large enough to hold an instance object

GateSwi_Handle GateSwi_handle(GateSwi_Struct *structP);

// Convert this instance structure pointer into an instance handle

GateSwi_Struct *GateSwi_struct(GateSwi_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

typedef struct GateSwi_Params {

// Instance config-params structure

IInstance_Params *instance;

// Common per-instance configs

} GateSwi_Params;

Void GateSwi_Params_init(GateSwi_Params *params);

// Initialize this config-params structure with supplier-specified defaults before instance creation

Instance Creation

index URL

C synopsis target-domain

GateSwi_Handle GateSwi_create(const GateSwi_Params *params, Error_Block *eb);

// Allocate and initialize a new instance object and return its handle

Void GateSwi_construct(GateSwi_Struct *structP, const GateSwi_Params *params);

// Initialize a new instance object inside the provided structure

ARGUMENTS

params — per-instance config params, or NULL to select default values (target-domain only)

eb — active error-handling block, or NULL to select default policy (target-domain only)

Instance Deletion

index URL

C synopsis target-domain

Void GateSwi_delete(GateSwi_Handle *handleP);

// Finalize and free this previously allocated instance object, setting the referenced handle to NULL

Void GateSwi_destruct(GateSwi_Struct *structP);

// Finalize the instance object inside the provided structure

Instance Convertors

index URL

C synopsis target-domain

IGateProvider_Handle GateSwi_Handle_upCast(GateSwi_Handle handle);

// unconditionally move one level up the inheritance hierarchy

GateSwi_Handle GateSwi_Handle_downCast(IGateProvider_Handle handle);

// conditionally move one level down the inheritance hierarchy; NULL upon failure

Instance Built-Ins

index URL

C synopsis target-domain

Int GateSwi_Object_count();

// The number of statically-created instance objects

GateSwi_Handle GateSwi_Object_get(GateSwi_Object *array, Int i);

// The handle of the i-th statically-created instance object (array == NULL)

GateSwi_Handle GateSwi_Object_first();

// The handle of the first dynamically-created instance object, or NULL

GateSwi_Handle GateSwi_Object_next(GateSwi_Handle handle);

// The handle of the next dynamically-created instance object, or NULL

IHeap_Handle GateSwi_Object_heap();

// The heap used to allocate dynamically-created instance objects

Types_Label *GateSwi_Handle_label(GateSwi_Handle handle, Types_Label *buf);

// The label associated with this instance object

String GateSwi_Handle_name(GateSwi_Handle handle);

// The name of this instance object

XDCscript usage meta-domain sourced in ti/sysbios/gates/GateSwi.xdc

var GateSwi = xdc.useModule('ti.sysbios.gates.GateSwi');

module-wide constants & types

const GateSwi.Q_BLOCKING// Blocking quality = 1;

const GateSwi.Q_PREEMPTING// Preempting quality = 2;

var obj = new GateSwi.BasicView// ;

obj.label = String ...

module-wide config parameters

GateSwi.A_badContext// Asserted when enter or leave is called from a hardware interrupt thread = Assert.Desc {

msg: "A_badContext: bad calling context. May not be entered from a hardware interrupt thread."

};

GateSwi.common$// Common module configuration parameters = Types.Common$ undefined;

GateSwi.rovViewInfo// = ViewInfo.Instance ViewInfo.create;

module-wide functions

GateSwi.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool

per-instance config parameters

var params = new GateSwi.Params// Instance config-params object;

per-instance creation

var inst = GateSwi.create// Create an instance-object(params);

const GateSwi.Q_BLOCKING

index URL

Blocking quality

XDCscript usage meta-domain

const GateSwi.Q_BLOCKING = 1;

DETAILS

Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.

C SYNOPSIS

GateSwi_Q_BLOCKING

const GateSwi.Q_PREEMPTING

index URL

Preempting quality

XDCscript usage meta-domain

const GateSwi.Q_PREEMPTING = 2;

DETAILS

Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.

C SYNOPSIS

GateSwi_Q_PREEMPTING

metaonly struct GateSwi.BasicView

index URL

XDCscript usage meta-domain

var obj = new GateSwi.BasicView;

obj.label = String ...

config GateSwi.A_badContext // module-wide

index URL

Asserted when enter or leave is called from a hardware interrupt thread

XDCscript usage meta-domain

GateSwi.A_badContext = Assert.Desc {

msg: "A_badContext: bad calling context. May not be entered from a hardware interrupt thread."

};

C SYNOPSIS

GateSwi_A_badContext

metaonly config GateSwi.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

GateSwi.common$ = Types.Common$ undefined;

DETAILS

All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.

metaonly config GateSwi.rovViewInfo // module-wide

index URL

XDCscript usage meta-domain

GateSwi.rovViewInfo = ViewInfo.Instance ViewInfo.create;

metaonly GateSwi.queryMeta() // module-wide

index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain

GateSwi.queryMeta(Int qual) returns Bool

ARGUMENTS

qual — constant describing a quality

RETURNS

Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.

Instance Config Parameters

index URL

XDCscript usage meta-domain

var params = new GateSwi.Params;

// Instance config-params object

Instance Creation

index URL

XDCscript usage meta-domain

var params = new GateSwi.Params;

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = GateSwi.create(params);

// Create an instance-object

ARGUMENTS

params — per-instance config params, or NULL to select default values (target-domain only)

eb — active error-handling block, or NULL to select default policy (target-domain only)

generated on Thu, 03 Feb 2011 19:01:32 GMT