module ti.sdo.ipc.gates.GateAAMonitor

Multiprocessor gate that utilizes an atomic access monitor (AAM)

C synopsis
Individual elements
XDCscript usage
Individual elements

C synopsis target-domain sourced in ti/sdo/ipc/gates/GateAAMonitor.xdc

#include <ti/sdo/ipc/gates/GateAAMonitor.h>

Functions
Void	GateAAMonitor_construct// Initialize a new instance object inside the provided structure(GateAAMonitor_Struct structP, IGateProvider_Handle localGate, const GateAAMonitor_Params params, Error_Block *eb);
GateAAMonitor_Handle	GateAAMonitor_create// Allocate and initialize a new instance object and return its handle(IGateProvider_Handle localGate, const GateAAMonitor_Params params, Error_Block eb);
Void	GateAAMonitor_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateAAMonitor_Handle *handleP);
Void	GateAAMonitor_destruct// Finalize the instance object inside the provided structure(GateAAMonitor_Struct *structP);
Void	GateAAMonitor_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateAAMonitor_Params *params);
Functions common to all IGateProvider modules
IArg	GateAAMonitor_enter// Enter this gate(GateAAMonitor_Handle handle);
Void	GateAAMonitor_leave// Leave this gate(GateAAMonitor_Handle handle, IArg key);
Bool	GateAAMonitor_query// Runtime test for a particular gate quality(Int qual);
Functions common to all IGateMPSupport modules
SizeT	GateAAMonitor_sharedMemReq// Amount of shared memory required for creation of each instance(IGateMPSupport_Params *params);
Functions common to all target instances
	GateAAMonitor_handle// Convert this instance structure pointer into an instance handle, GateAAMonitor_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateAAMonitor_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, GateAAMonitor_Handle_label// The label associated with this instance object, GateAAMonitor_Handle_name// The name of this instance object, GateAAMonitor_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateAAMonitor_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, GateAAMonitor_Object_count// The number of statically-created instance objects, GateAAMonitor_Object_first// The handle of the first dynamically-created instance object, or NULL, GateAAMonitor_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateAAMonitor_Object_heap// The heap used to allocate dynamically-created instance objects, GateAAMonitor_Object_next// The handle of the next dynamically-created instance object, or NULL, GateAAMonitor_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	GateAAMonitor_Module_getMask// Returns the diagnostics mask for this module, GateAAMonitor_Module_hasMask// Test whether this module has a diagnostics mask, GateAAMonitor_Module_heap// The heap from which this module allocates memory, GateAAMonitor_Module_id// Get this module's unique id, GateAAMonitor_Module_setMask// Set the diagnostics mask for this module, GateAAMonitor_Module_startupDone// Test if this module has completed startup
Defines
#define	GateAAMonitor_Q_BLOCKING// Blocking quality (Int)1
#define	GateAAMonitor_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateAAMonitor_Object *	GateAAMonitor_Handle// Client reference to an instance object;
typedef struct	GateAAMonitor_Object// Opaque internal representation of an instance object GateAAMonitor_Object;
typedef struct	GateAAMonitor_Params// Instance config-params structure ...
typedef struct	GateAAMonitor_Struct// Opaque client structure large enough to hold an instance object GateAAMonitor_Struct;
Constants
extern const Assert_Id	GateAAMonitor_A_invSharedAddr// Assert raised when supplied sharedAddr is invalid;
extern const UInt	GateAAMonitor_numInstances// Maximum number of instances supported by the GateAAMonitor module;

const GateAAMonitor_Q_BLOCKING

index URL

Blocking quality

C synopsis target-domain

#define GateAAMonitor_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 GateAAMonitor_Q_PREEMPTING

index URL

Preempting quality

C synopsis target-domain

#define GateAAMonitor_Q_PREEMPTING (Int)2

DETAILS

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

config GateAAMonitor_A_invSharedAddr // module-wide

index URL

Assert raised when supplied sharedAddr is invalid

C synopsis target-domain

extern const Assert_Id GateAAMonitor_A_invSharedAddr;

DETAILS

C6472 requires that shared region 0 be placed in SL2 memory and that all GateMP instances be allocated from region 0. The gate itself may be used to protect the contents of any shared region.

config GateAAMonitor_numInstances // module-wide

index URL

Maximum number of instances supported by the GateAAMonitor module

C synopsis target-domain

extern const UInt GateAAMonitor_numInstances;

GateAAMonitor_query() // module-wide

index URL

Runtime test for a particular gate quality

C synopsis target-domain

Bool GateAAMonitor_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.

GateAAMonitor_sharedMemReq() // module-wide

index URL

Amount of shared memory required for creation of each instance

C synopsis target-domain

SizeT GateAAMonitor_sharedMemReq(IGateMPSupport_Params *params);

ARGUMENTS

params — Pointer to the parameters that will be used in the create.

DETAILS

The value returned by this function may depend on the cache alignment requirements for the shared region from which memory will be used.

RETURNS

Number of MAUs needed to create the instance.

Module-Wide Built-Ins

index URL

C synopsis target-domain

Types_ModuleId GateAAMonitor_Module_id();

// Get this module's unique id

Bool GateAAMonitor_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle GateAAMonitor_Module_heap();

// The heap from which this module allocates memory

Bool GateAAMonitor_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 GateAAMonitor_Module_getMask();

// Returns the diagnostics mask for this module

Void GateAAMonitor_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct GateAAMonitor_Object GateAAMonitor_Object;

// Opaque internal representation of an instance object

typedef GateAAMonitor_Object *GateAAMonitor_Handle;

// Client reference to an instance object

typedef struct GateAAMonitor_Struct GateAAMonitor_Struct;

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

GateAAMonitor_Handle GateAAMonitor_handle(GateAAMonitor_Struct *structP);

// Convert this instance structure pointer into an instance handle

GateAAMonitor_Struct *GateAAMonitor_struct(GateAAMonitor_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

typedef struct GateAAMonitor_Params {

// Instance config-params structure

IInstance_Params *instance;

// Common per-instance configs

UInt resourceId;

// Logical resource id

Ptr sharedAddr;

// Physical address of the shared memory

} GateAAMonitor_Params;

Void GateAAMonitor_Params_init(GateAAMonitor_Params *params);

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

config GateAAMonitor_resourceId // instance

index URL

Logical resource id

C synopsis target-domain

struct GateAAMonitor_Params {

...

UInt resourceId;

config GateAAMonitor_sharedAddr // instance

index URL

Physical address of the shared memory

C synopsis target-domain

struct GateAAMonitor_Params {

...

Ptr sharedAddr;

DETAILS

This parameter is only used by GateMP delegates that use shared memory

Instance Creation

index URL

C synopsis target-domain

GateAAMonitor_Handle GateAAMonitor_create(IGateProvider_Handle localGate, const GateAAMonitor_Params *params, Error_Block *eb);

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

Void GateAAMonitor_construct(GateAAMonitor_Struct *structP, IGateProvider_Handle localGate, const GateAAMonitor_Params *params, Error_Block *eb);

// Initialize a new instance object inside the provided structure

ARGUMENTS

localGate — Gate to use for local protection.

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)

DETAILS

A Non-NULL gate for local protection must be passed to the create call. If no local protection is desired, a xdc.runtime.GateNull handle must be passed in.

Instance Deletion

index URL

C synopsis target-domain

Void GateAAMonitor_delete(GateAAMonitor_Handle *handleP);

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

Void GateAAMonitor_destruct(GateAAMonitor_Struct *structP);

// Finalize the instance object inside the provided structure

GateAAMonitor_enter() // instance

index URL

Enter this gate

C synopsis target-domain

IArg GateAAMonitor_enter(GateAAMonitor_Handle handle);

ARGUMENTS

handle — handle of a previously-created GateAAMonitor instance object

DETAILS

Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.

A thread may reenter a gate without blocking or failing.

RETURNS

Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.

GateAAMonitor_leave() // instance

index URL

Leave this gate

C synopsis target-domain

Void GateAAMonitor_leave(GateAAMonitor_Handle handle, IArg key);

ARGUMENTS

handle — handle of a previously-created GateAAMonitor instance object

key — the value returned by a matching call to enter

DETAILS

This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).

Instance Convertors

index URL

C synopsis target-domain

IGateMPSupport_Handle GateAAMonitor_Handle_upCast(GateAAMonitor_Handle handle);

// unconditionally move one level up the inheritance hierarchy

GateAAMonitor_Handle GateAAMonitor_Handle_downCast(IGateMPSupport_Handle handle);

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

IGateProvider_Handle GateAAMonitor_Handle_upCast2(GateAAMonitor_Handle handle);

// unconditionally move 2 levels up the inheritance hierarchy

GateAAMonitor_Handle GateAAMonitor_Handle_downCast2(IGateProvider_Handle handle);

// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure

Instance Built-Ins

index URL

C synopsis target-domain

Int GateAAMonitor_Object_count();

// The number of statically-created instance objects

GateAAMonitor_Handle GateAAMonitor_Object_get(GateAAMonitor_Object *array, Int i);

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

GateAAMonitor_Handle GateAAMonitor_Object_first();

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

GateAAMonitor_Handle GateAAMonitor_Object_next(GateAAMonitor_Handle handle);

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

IHeap_Handle GateAAMonitor_Object_heap();

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

Types_Label *GateAAMonitor_Handle_label(GateAAMonitor_Handle handle, Types_Label *buf);

// The label associated with this instance object

String GateAAMonitor_Handle_name(GateAAMonitor_Handle handle);

// The name of this instance object

XDCscript usage meta-domain sourced in ti/sdo/ipc/gates/GateAAMonitor.xdc

var GateAAMonitor = xdc.useModule('ti.sdo.ipc.gates.GateAAMonitor');

module-wide constants & types

const GateAAMonitor.Q_BLOCKING// Blocking quality = 1;

const GateAAMonitor.Q_PREEMPTING// Preempting quality = 2;

module-wide config parameters

GateAAMonitor.A_invSharedAddr// Assert raised when supplied sharedAddr is invalid = Assert.Desc {

msg: "A_invSharedAddr: Address must be in shared L2 address space"

};

GateAAMonitor.numInstances// Maximum number of instances supported by the GateAAMonitor module = UInt 32;

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

module-wide functions

GateAAMonitor.getNumResources// Returns the number of resources offered by the GateMP delegate() returns UInt

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

per-instance config parameters

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

params.resourceId// Logical resource id = UInt 0;

params.sharedAddr// Physical address of the shared memory = Ptr null;

per-instance creation

var inst = GateAAMonitor.create// Create an instance-object(IGateProvider.Handle localGate, params);

const GateAAMonitor.Q_BLOCKING

index URL

Blocking quality

XDCscript usage meta-domain

const GateAAMonitor.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

GateAAMonitor_Q_BLOCKING

const GateAAMonitor.Q_PREEMPTING

index URL

Preempting quality

XDCscript usage meta-domain

const GateAAMonitor.Q_PREEMPTING = 2;

DETAILS

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

C SYNOPSIS

GateAAMonitor_Q_PREEMPTING

config GateAAMonitor.A_invSharedAddr // module-wide

index URL

Assert raised when supplied sharedAddr is invalid

XDCscript usage meta-domain

GateAAMonitor.A_invSharedAddr = Assert.Desc {

msg: "A_invSharedAddr: Address must be in shared L2 address space"

};

DETAILS

C6472 requires that shared region 0 be placed in SL2 memory and that all GateMP instances be allocated from region 0. The gate itself may be used to protect the contents of any shared region.

C SYNOPSIS

GateAAMonitor_A_invSharedAddr

config GateAAMonitor.numInstances // module-wide

index URL

Maximum number of instances supported by the GateAAMonitor module

XDCscript usage meta-domain

GateAAMonitor.numInstances = UInt 32;

C SYNOPSIS

GateAAMonitor_numInstances

metaonly config GateAAMonitor.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

GateAAMonitor.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 GateAAMonitor.getNumResources() // module-wide

index URL

Returns the number of resources offered by the GateMP delegate

XDCscript usage meta-domain

GateAAMonitor.getNumResources() returns UInt

metaonly GateAAMonitor.queryMeta() // module-wide

index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain

GateAAMonitor.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 GateAAMonitor.Params;

// Instance config-params object

params.resourceId = UInt 0;

// Logical resource id

params.sharedAddr = Ptr null;

// Physical address of the shared memory

config GateAAMonitor.resourceId // instance

index URL

Logical resource id

XDCscript usage meta-domain

var params = new GateAAMonitor.Params;

...

params.resourceId = UInt 0;

C SYNOPSIS

null

config GateAAMonitor.sharedAddr // instance

index URL

Physical address of the shared memory

XDCscript usage meta-domain

var params = new GateAAMonitor.Params;

...

params.sharedAddr = Ptr null;

DETAILS

This parameter is only used by GateMP delegates that use shared memory

C SYNOPSIS

null

Instance Creation

index URL

XDCscript usage meta-domain

var params = new GateAAMonitor.Params;

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = GateAAMonitor.create(IGateProvider.Handle localGate, params);

// Create an instance-object

ARGUMENTS

localGate — Gate to use for local protection.

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)

DETAILS

A Non-NULL gate for local protection must be passed to the create call. If no local protection is desired, a xdc.runtime.GateNull handle must be passed in.

generated on Sat, 11 Feb 2012 00:37:58 GMT