module ti.sdo.ipc.gates.GateHWSpinlock

index URL

Multiprocessor gate that utilizes a hardware spinlock

C synopsis
Individual elements
XDCscript usage
Individual elements

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

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

Functions
Void	GateHWSpinlock_construct// Initialize a new instance object inside the provided structure(GateHWSpinlock_Struct structP, IGateProvider_Handle localGate, const GateHWSpinlock_Params params);
GateHWSpinlock_Handle	GateHWSpinlock_create// Allocate and initialize a new instance object and return its handle(IGateProvider_Handle localGate, const GateHWSpinlock_Params params, Error_Block eb);
Void	GateHWSpinlock_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateHWSpinlock_Handle *handleP);
Void	GateHWSpinlock_destruct// Finalize the instance object inside the provided structure(GateHWSpinlock_Struct *structP);
Void	GateHWSpinlock_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateHWSpinlock_Params *params);
Functions common to all IGateProvider modules
Bool	GateHWSpinlock_query// Runtime test for a particular gate quality(Int qual);
Functions common to all IGateMPSupport modules
SizeT	GateHWSpinlock_sharedMemReq// Amount of shared memory required for creation of each instance(IGateMPSupport_Params *params);
Functions common to all target instances
	GateHWSpinlock_handle// Convert this instance structure pointer into an instance handle, GateHWSpinlock_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateHWSpinlock_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, GateHWSpinlock_Handle_label// The label associated with this instance object, GateHWSpinlock_Handle_name// The name of this instance object, GateHWSpinlock_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateHWSpinlock_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, GateHWSpinlock_Object_count// The number of statically-created instance objects, GateHWSpinlock_Object_first// The handle of the first dynamically-created instance object, or NULL, GateHWSpinlock_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateHWSpinlock_Object_heap// The heap used to allocate dynamically-created instance objects, GateHWSpinlock_Object_next// The handle of the next dynamically-created instance object, or NULL, GateHWSpinlock_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	GateHWSpinlock_Module_getMask// Returns the diagnostics mask for this module, GateHWSpinlock_Module_hasMask// Test whether this module has a diagnostics mask, GateHWSpinlock_Module_heap// The heap from which this module allocates memory, GateHWSpinlock_Module_id// Get this module's unique id, GateHWSpinlock_Module_setMask// Set the diagnostics mask for this module, GateHWSpinlock_Module_startupDone// Test if this module has completed startup
Defines
#define	GateHWSpinlock_Q_BLOCKING// Blocking quality (Int)1
#define	GateHWSpinlock_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateHWSpinlock_Object *	GateHWSpinlock_Handle// Client reference to an instance object;
typedef struct	GateHWSpinlock_Object// Opaque internal representation of an instance object GateHWSpinlock_Object;
typedef struct	GateHWSpinlock_Params// Instance config-params structure ...
typedef struct	GateHWSpinlock_Struct// Opaque client structure large enough to hold an instance object GateHWSpinlock_Struct;
Constants
extern const Assert_Id	GateHWSpinlock_A_invSpinLockNum// Assert raised when provided lockNum is invalid for the relevant device;
extern const Ptr	GateHWSpinlock_baseAddr// Device-specific base address for HW Semaphore subsystem;
extern const Log_Event	GateHWSpinlock_LM_close// Logged on gate close;
extern const Log_Event	GateHWSpinlock_LM_create// Logged on gate create;
extern const Log_Event	GateHWSpinlock_LM_delete// Logged on gate deletion;
extern const Log_Event	GateHWSpinlock_LM_enter// Logged on gate enter;
extern const Log_Event	GateHWSpinlock_LM_leave// Logged on gate leave;
extern const Log_Event	GateHWSpinlock_LM_open// Logged on gate open;

const GateHWSpinlock_Q_BLOCKING

index URL

Blocking quality

C synopsis target-domain

#define GateHWSpinlock_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 GateHWSpinlock_Q_PREEMPTING

index URL

Preempting quality

C synopsis target-domain

#define GateHWSpinlock_Q_PREEMPTING (Int)2

DETAILS

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

config GateHWSpinlock_A_invSpinLockNum // module-wide

index URL

Assert raised when provided lockNum is invalid for the relevant device

C synopsis target-domain

extern const Assert_Id GateHWSpinlock_A_invSpinLockNum;

config GateHWSpinlock_LM_close // module-wide

index URL

Logged on gate close

C synopsis target-domain

extern const Log_Event GateHWSpinlock_LM_close;

config GateHWSpinlock_LM_create // module-wide

index URL

Logged on gate create

C synopsis target-domain

extern const Log_Event GateHWSpinlock_LM_create;

config GateHWSpinlock_LM_delete // module-wide

index URL

Logged on gate deletion

C synopsis target-domain

extern const Log_Event GateHWSpinlock_LM_delete;

config GateHWSpinlock_LM_enter // module-wide

index URL

Logged on gate enter

C synopsis target-domain

extern const Log_Event GateHWSpinlock_LM_enter;

config GateHWSpinlock_LM_leave // module-wide

index URL

Logged on gate leave

C synopsis target-domain

extern const Log_Event GateHWSpinlock_LM_leave;

config GateHWSpinlock_LM_open // module-wide

index URL

Logged on gate open

C synopsis target-domain

extern const Log_Event GateHWSpinlock_LM_open;

config GateHWSpinlock_baseAddr // module-wide

index URL

Device-specific base address for HW Semaphore subsystem

C synopsis target-domain

extern const Ptr GateHWSpinlock_baseAddr;

GateHWSpinlock_query() // module-wide

index URL

Runtime test for a particular gate quality

C synopsis target-domain

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

GateHWSpinlock_sharedMemReq() // module-wide

index URL

Amount of shared memory required for creation of each instance

C synopsis target-domain

SizeT GateHWSpinlock_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 GateHWSpinlock_Module_id();

// Get this module's unique id

Bool GateHWSpinlock_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle GateHWSpinlock_Module_heap();

// The heap from which this module allocates memory

Bool GateHWSpinlock_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 GateHWSpinlock_Module_getMask();

// Returns the diagnostics mask for this module

Void GateHWSpinlock_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct GateHWSpinlock_Object GateHWSpinlock_Object;

// Opaque internal representation of an instance object

typedef GateHWSpinlock_Object *GateHWSpinlock_Handle;

// Client reference to an instance object

typedef struct GateHWSpinlock_Struct GateHWSpinlock_Struct;

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

GateHWSpinlock_Handle GateHWSpinlock_handle(GateHWSpinlock_Struct *structP);

// Convert this instance structure pointer into an instance handle

GateHWSpinlock_Struct *GateHWSpinlock_struct(GateHWSpinlock_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

typedef struct GateHWSpinlock_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

} GateHWSpinlock_Params;

Void GateHWSpinlock_Params_init(GateHWSpinlock_Params *params);

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

config GateHWSpinlock_resourceId // instance

index URL

Logical resource id

C synopsis target-domain

struct GateHWSpinlock_Params {

...

UInt resourceId;

config GateHWSpinlock_sharedAddr // instance

index URL

Physical address of the shared memory

C synopsis target-domain

struct GateHWSpinlock_Params {

...

Ptr sharedAddr;

DETAILS

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

Instance Creation

index URL

C synopsis target-domain

GateHWSpinlock_Handle GateHWSpinlock_create(IGateProvider_Handle localGate, const GateHWSpinlock_Params *params, Error_Block *eb);

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

Void GateHWSpinlock_construct(GateHWSpinlock_Struct *structP, IGateProvider_Handle localGate, const GateHWSpinlock_Params *params);

// 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 GateHWSpinlock_delete(GateHWSpinlock_Handle *handleP);

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

Void GateHWSpinlock_destruct(GateHWSpinlock_Struct *structP);

// Finalize the instance object inside the provided structure

Instance Convertors

index URL

C synopsis target-domain

IGateMPSupport_Handle GateHWSpinlock_Handle_upCast(GateHWSpinlock_Handle handle);

// unconditionally move one level up the inheritance hierarchy

GateHWSpinlock_Handle GateHWSpinlock_Handle_downCast(IGateMPSupport_Handle handle);

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

IGateProvider_Handle GateHWSpinlock_Handle_upCast2(GateHWSpinlock_Handle handle);

// unconditionally move 2 levels up the inheritance hierarchy

GateHWSpinlock_Handle GateHWSpinlock_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 GateHWSpinlock_Object_count();

// The number of statically-created instance objects

GateHWSpinlock_Handle GateHWSpinlock_Object_get(GateHWSpinlock_Object *array, Int i);

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

GateHWSpinlock_Handle GateHWSpinlock_Object_first();

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

GateHWSpinlock_Handle GateHWSpinlock_Object_next(GateHWSpinlock_Handle handle);

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

IHeap_Handle GateHWSpinlock_Object_heap();

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

Types_Label *GateHWSpinlock_Handle_label(GateHWSpinlock_Handle handle, Types_Label *buf);

// The label associated with this instance object

String GateHWSpinlock_Handle_name(GateHWSpinlock_Handle handle);

// The name of this instance object

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

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

module-wide constants & types

const GateHWSpinlock.Q_BLOCKING// Blocking quality = 1;

const GateHWSpinlock.Q_PREEMPTING// Preempting quality = 2;

module-wide config parameters

GateHWSpinlock.A_invSpinLockNum// Assert raised when provided lockNum is invalid for the relevant device = Assert.Desc {

msg: "A_invSpinLockNum: Invalid hardware spinlock number"

};

GateHWSpinlock.LM_close// Logged on gate close = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_close: Gate (lockNum = %d) closed"

};

GateHWSpinlock.LM_create// Logged on gate create = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_create: Gate (lockNum = %d) created"

};

GateHWSpinlock.LM_delete// Logged on gate deletion = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_delete: Gate (lockNum = %d) deleted"

};

GateHWSpinlock.LM_enter// Logged on gate enter = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_enter: Gate (lockNum = %d) entered, returning key = %d"

};

GateHWSpinlock.LM_leave// Logged on gate leave = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_leave: Gate (lockNum = %d) left using key = %d"

};

GateHWSpinlock.LM_open// Logged on gate open = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_open: Remote gate (lockNum = %d) opened"

};

GateHWSpinlock.baseAddr// Device-specific base address for HW Semaphore subsystem = Ptr null;

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

module-wide functions

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

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

GateHWSpinlock.setReserved// Reserve a HW spinlock for use outside of IPC(UInt lockNum) returns Void

per-instance config parameters

var params = new GateHWSpinlock.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 = GateHWSpinlock.create// Create an instance-object(IGateProvider.Handle localGate, params);

const GateHWSpinlock.Q_BLOCKING

index URL

Blocking quality

XDCscript usage meta-domain

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

GateHWSpinlock_Q_BLOCKING

const GateHWSpinlock.Q_PREEMPTING

index URL

Preempting quality

XDCscript usage meta-domain

const GateHWSpinlock.Q_PREEMPTING = 2;

DETAILS

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

C SYNOPSIS

GateHWSpinlock_Q_PREEMPTING

config GateHWSpinlock.A_invSpinLockNum // module-wide

index URL

Assert raised when provided lockNum is invalid for the relevant device

XDCscript usage meta-domain

GateHWSpinlock.A_invSpinLockNum = Assert.Desc {

msg: "A_invSpinLockNum: Invalid hardware spinlock number"

};

C SYNOPSIS

GateHWSpinlock_A_invSpinLockNum

config GateHWSpinlock.LM_close // module-wide

index URL

Logged on gate close

XDCscript usage meta-domain

GateHWSpinlock.LM_close = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_close: Gate (lockNum = %d) closed"

};

C SYNOPSIS

GateHWSpinlock_LM_close

config GateHWSpinlock.LM_create // module-wide

index URL

Logged on gate create

XDCscript usage meta-domain

GateHWSpinlock.LM_create = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_create: Gate (lockNum = %d) created"

};

C SYNOPSIS

GateHWSpinlock_LM_create

config GateHWSpinlock.LM_delete // module-wide

index URL

Logged on gate deletion

XDCscript usage meta-domain

GateHWSpinlock.LM_delete = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_delete: Gate (lockNum = %d) deleted"

};

C SYNOPSIS

GateHWSpinlock_LM_delete

config GateHWSpinlock.LM_enter // module-wide

index URL

Logged on gate enter

XDCscript usage meta-domain

GateHWSpinlock.LM_enter = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_enter: Gate (lockNum = %d) entered, returning key = %d"

};

C SYNOPSIS

GateHWSpinlock_LM_enter

config GateHWSpinlock.LM_leave // module-wide

index URL

Logged on gate leave

XDCscript usage meta-domain

GateHWSpinlock.LM_leave = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_leave: Gate (lockNum = %d) left using key = %d"

};

C SYNOPSIS

GateHWSpinlock_LM_leave

config GateHWSpinlock.LM_open // module-wide

index URL

Logged on gate open

XDCscript usage meta-domain

GateHWSpinlock.LM_open = Log.EventDesc {

mask: Diags.USER1,

msg: "LM_open: Remote gate (lockNum = %d) opened"

};

C SYNOPSIS

GateHWSpinlock_LM_open

config GateHWSpinlock.baseAddr // module-wide

index URL

Device-specific base address for HW Semaphore subsystem

XDCscript usage meta-domain

GateHWSpinlock.baseAddr = Ptr null;

C SYNOPSIS

GateHWSpinlock_baseAddr

metaonly config GateHWSpinlock.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

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

index URL

Returns the number of resources offered by the GateMP delegate

XDCscript usage meta-domain

GateHWSpinlock.getNumResources() returns UInt

metaonly GateHWSpinlock.queryMeta() // module-wide

index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain

GateHWSpinlock.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.

metaonly GateHWSpinlock.setReserved() // module-wide

index URL

Reserve a HW spinlock for use outside of IPC

XDCscript usage meta-domain

GateHWSpinlock.setReserved(UInt lockNum) returns Void

ARGUMENTS

lockNum — HW spinlock number to reserve

DETAILS

GateMP will, by default, manage all HW spinlocks on the device unless this API is used to set aside specific spinlocks for use outside of IPC.

Instance Config Parameters

index URL

XDCscript usage meta-domain

var params = new GateHWSpinlock.Params;

// Instance config-params object

params.resourceId = UInt 0;

// Logical resource id

params.sharedAddr = Ptr null;

// Physical address of the shared memory

config GateHWSpinlock.resourceId // instance

index URL

Logical resource id

XDCscript usage meta-domain

var params = new GateHWSpinlock.Params;

...

params.resourceId = UInt 0;

C SYNOPSIS

null

config GateHWSpinlock.sharedAddr // instance

index URL

Physical address of the shared memory

XDCscript usage meta-domain

var params = new GateHWSpinlock.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 GateHWSpinlock.Params;

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = GateHWSpinlock.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:59 GMT