module ti.sdo.ipc.gates.GateHWSem

index URL

Multiprocessor gate that utilizes hardware semaphores

C synopsis
Individual elements
XDCscript usage
Individual elements

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

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

Functions
Void	GateHWSem_construct// Initialize a new instance object inside the provided structure(GateHWSem_Struct structP, IGateProvider_Handle localGate, const GateHWSem_Params params);
GateHWSem_Handle	GateHWSem_create// Allocate and initialize a new instance object and return its handle(IGateProvider_Handle localGate, const GateHWSem_Params params, Error_Block eb);
Void	GateHWSem_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateHWSem_Handle *handleP);
Void	GateHWSem_destruct// Finalize the instance object inside the provided structure(GateHWSem_Struct *structP);
Void	GateHWSem_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateHWSem_Params *params);
Functions common to all IGateProvider modules
Bool	GateHWSem_query// Runtime test for a particular gate quality(Int qual);
Functions common to all IGateMPSupport modules
SizeT	GateHWSem_sharedMemReq// Amount of shared memory required for creation of each instance(IGateMPSupport_Params *params);
Functions common to all target instances
	GateHWSem_handle// Convert this instance structure pointer into an instance handle, GateHWSem_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateHWSem_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, GateHWSem_Handle_label// The label associated with this instance object, GateHWSem_Handle_name// The name of this instance object, GateHWSem_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateHWSem_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, GateHWSem_Object_count// The number of statically-created instance objects, GateHWSem_Object_first// The handle of the first dynamically-created instance object, or NULL, GateHWSem_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateHWSem_Object_heap// The heap used to allocate dynamically-created instance objects, GateHWSem_Object_next// The handle of the next dynamically-created instance object, or NULL, GateHWSem_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	GateHWSem_Module_getMask// Returns the diagnostics mask for this module, GateHWSem_Module_hasMask// Test whether this module has a diagnostics mask, GateHWSem_Module_heap// The heap from which this module allocates memory, GateHWSem_Module_id// Get this module's unique id, GateHWSem_Module_setMask// Set the diagnostics mask for this module, GateHWSem_Module_startupDone// Test if this module has completed startup
Defines
#define	GateHWSem_Q_BLOCKING// Blocking quality (Int)1
#define	GateHWSem_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateHWSem_Object *	GateHWSem_Handle// Client reference to an instance object;
typedef struct	GateHWSem_Object// Opaque internal representation of an instance object GateHWSem_Object;
typedef struct	GateHWSem_Params// Instance config-params structure ...
typedef struct	GateHWSem_Struct// Opaque client structure large enough to hold an instance object GateHWSem_Struct;
Constants
extern const Assert_Id	GateHWSem_A_invSemNum// Asserted when supplied semNum is invalid for the relevant device;

const GateHWSem_Q_BLOCKING

index URL

Blocking quality

C synopsis target-domain

#define GateHWSem_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 GateHWSem_Q_PREEMPTING

index URL

Preempting quality

C synopsis target-domain

#define GateHWSem_Q_PREEMPTING (Int)2

DETAILS

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

config GateHWSem_A_invSemNum // module-wide

index URL

Asserted when supplied semNum is invalid for the relevant device

C synopsis target-domain

extern const Assert_Id GateHWSem_A_invSemNum;

GateHWSem_query() // module-wide

index URL

Runtime test for a particular gate quality

C synopsis target-domain

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

GateHWSem_sharedMemReq() // module-wide

index URL

Amount of shared memory required for creation of each instance

C synopsis target-domain

SizeT GateHWSem_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 GateHWSem_Module_id();

// Get this module's unique id

Bool GateHWSem_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle GateHWSem_Module_heap();

// The heap from which this module allocates memory

Bool GateHWSem_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 GateHWSem_Module_getMask();

// Returns the diagnostics mask for this module

Void GateHWSem_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct GateHWSem_Object GateHWSem_Object;

// Opaque internal representation of an instance object

typedef GateHWSem_Object *GateHWSem_Handle;

// Client reference to an instance object

typedef struct GateHWSem_Struct GateHWSem_Struct;

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

GateHWSem_Handle GateHWSem_handle(GateHWSem_Struct *structP);

// Convert this instance structure pointer into an instance handle

GateHWSem_Struct *GateHWSem_struct(GateHWSem_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

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

} GateHWSem_Params;

Void GateHWSem_Params_init(GateHWSem_Params *params);

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

config GateHWSem_resourceId // instance

index URL

Logical resource id

C synopsis target-domain

struct GateHWSem_Params {

...

UInt resourceId;

config GateHWSem_sharedAddr // instance

index URL

Physical address of the shared memory

C synopsis target-domain

struct GateHWSem_Params {

...

Ptr sharedAddr;

DETAILS

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

Instance Creation

index URL

C synopsis target-domain

GateHWSem_Handle GateHWSem_create(IGateProvider_Handle localGate, const GateHWSem_Params *params, Error_Block *eb);

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

Void GateHWSem_construct(GateHWSem_Struct *structP, IGateProvider_Handle localGate, const GateHWSem_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 GateHWSem_delete(GateHWSem_Handle *handleP);

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

Void GateHWSem_destruct(GateHWSem_Struct *structP);

// Finalize the instance object inside the provided structure

Instance Convertors

index URL

C synopsis target-domain

IGateMPSupport_Handle GateHWSem_Handle_upCast(GateHWSem_Handle handle);

// unconditionally move one level up the inheritance hierarchy

GateHWSem_Handle GateHWSem_Handle_downCast(IGateMPSupport_Handle handle);

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

IGateProvider_Handle GateHWSem_Handle_upCast2(GateHWSem_Handle handle);

// unconditionally move 2 levels up the inheritance hierarchy

GateHWSem_Handle GateHWSem_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 GateHWSem_Object_count();

// The number of statically-created instance objects

GateHWSem_Handle GateHWSem_Object_get(GateHWSem_Object *array, Int i);

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

GateHWSem_Handle GateHWSem_Object_first();

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

GateHWSem_Handle GateHWSem_Object_next(GateHWSem_Handle handle);

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

IHeap_Handle GateHWSem_Object_heap();

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

Types_Label *GateHWSem_Handle_label(GateHWSem_Handle handle, Types_Label *buf);

// The label associated with this instance object

String GateHWSem_Handle_name(GateHWSem_Handle handle);

// The name of this instance object

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

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

module-wide constants & types

const GateHWSem.Q_BLOCKING// Blocking quality = 1;

const GateHWSem.Q_PREEMPTING// Preempting quality = 2;

module-wide config parameters

GateHWSem.A_invSemNum// Asserted when supplied semNum is invalid for the relevant device = Assert.Desc {

msg: "A_invSemNum: Invalid hardware semaphore number"

};

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

module-wide functions

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

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

GateHWSem.setReserved// Reserve a HW sempahore for use outside of IPC(UInt semNum) returns Void

per-instance config parameters

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

const GateHWSem.Q_BLOCKING

index URL

Blocking quality

XDCscript usage meta-domain

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

GateHWSem_Q_BLOCKING

const GateHWSem.Q_PREEMPTING

index URL

Preempting quality

XDCscript usage meta-domain

const GateHWSem.Q_PREEMPTING = 2;

DETAILS

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

C SYNOPSIS

GateHWSem_Q_PREEMPTING

config GateHWSem.A_invSemNum // module-wide

index URL

Asserted when supplied semNum is invalid for the relevant device

XDCscript usage meta-domain

GateHWSem.A_invSemNum = Assert.Desc {

msg: "A_invSemNum: Invalid hardware semaphore number"

};

C SYNOPSIS

GateHWSem_A_invSemNum

metaonly config GateHWSem.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

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

index URL

Returns the number of resources offered by the GateMP delegate

XDCscript usage meta-domain

GateHWSem.getNumResources() returns UInt

metaonly GateHWSem.queryMeta() // module-wide

index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain

GateHWSem.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 GateHWSem.setReserved() // module-wide

index URL

Reserve a HW sempahore for use outside of IPC

XDCscript usage meta-domain

GateHWSem.setReserved(UInt semNum) returns Void

ARGUMENTS

semNum — HW semaphore number to reserve

DETAILS

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

Instance Config Parameters

index URL

XDCscript usage meta-domain

var params = new GateHWSem.Params;

// Instance config-params object

params.resourceId = UInt 0;

// Logical resource id

params.sharedAddr = Ptr null;

// Physical address of the shared memory

config GateHWSem.resourceId // instance

index URL

Logical resource id

XDCscript usage meta-domain

var params = new GateHWSem.Params;

...

params.resourceId = UInt 0;

C SYNOPSIS

null

config GateHWSem.sharedAddr // instance

index URL

Physical address of the shared memory

XDCscript usage meta-domain

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

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = GateHWSem.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 Tue, 22 May 2012 23:44:52 GMT