module xdc.runtime.knl.SyncGeneric

index URL

Generic ISync implementation

C synopsis
Individual elements
XDCscript usage
Individual elements

This module allows users to plug in their own functions for signal, wait and query.

C synopsis target-domain sourced in xdc/runtime/knl/SyncGeneric.xdc

#include <xdc/runtime/knl/SyncGeneric.h>

Functions
Void	SyncGeneric_construct// Initialize a new instance object inside the provided structure(SyncGeneric_Struct structP, const SyncGeneric_Params params);
SyncGeneric_Handle	SyncGeneric_create// Allocate and initialize a new instance object and return its handle(const SyncGeneric_Params params, Error_Block eb);
Void	SyncGeneric_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncGeneric_Handle *handleP);
Void	SyncGeneric_destruct// Finalize the instance object inside the provided structure(SyncGeneric_Struct *structP);
Void	SyncGeneric_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncGeneric_Params *params);
Functions common to all ISync modules
Bool	SyncGeneric_query// Query for a particular quality(SyncGeneric_Handle handle, Int qual);
Void	SyncGeneric_signal// Called at completion of an activity(SyncGeneric_Handle handle);
Int	SyncGeneric_wait// Called to wait/poll for completion of an activity(SyncGeneric_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
	SyncGeneric_handle// Convert this instance structure pointer into an instance handle, SyncGeneric_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncGeneric_Handle_label// The label associated with this instance object, SyncGeneric_Handle_name// The name of this instance object, SyncGeneric_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncGeneric_Object_count// The number of statically-created instance objects, SyncGeneric_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncGeneric_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncGeneric_Object_heap// The heap used to allocate dynamically-created instance objects, SyncGeneric_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncGeneric_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	SyncGeneric_Module_getMask// Returns the diagnostics mask for this module, SyncGeneric_Module_hasMask// Test whether this module has a diagnostics mask, SyncGeneric_Module_heap// The heap from which this module allocates memory, SyncGeneric_Module_id// Get this module's unique id, SyncGeneric_Module_setMask// Set the diagnostics mask for this module, SyncGeneric_Module_startupDone// Test if this module has completed startup
Defines
#define	SyncGeneric_NO_WAIT// Used to specify no waiting (UInt)0
#define	SyncGeneric_Q_BLOCKING// Blocking quality (Int)1
#define	SyncGeneric_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncGeneric_Object *	SyncGeneric_Handle// Client reference to an instance object;
typedef struct	SyncGeneric_Object// Opaque internal representation of an instance object SyncGeneric_Object;
typedef struct	SyncGeneric_Params// Instance config-params structure ...
typedef Bool	(*SyncGeneric_QueryFunc// typedef for user specified wait function)(Int);
typedef Void	(*SyncGeneric_SignalFunc// typedef for user specified signal function)(UArg);
typedef struct	SyncGeneric_Struct// Opaque client structure large enough to hold an instance object SyncGeneric_Struct;
typedef Bool	(*SyncGeneric_WaitFunc// typedef for user specified wait function)(UArg,UInt);
typedef enum	SyncGeneric_WaitStatus// Error codes returned by ISync_wait ...

const SyncGeneric_NO_WAIT

index URL

Used to specify no waiting

C synopsis target-domain

#define SyncGeneric_NO_WAIT (UInt)0

const SyncGeneric_Q_BLOCKING

index URL

Blocking quality

C synopsis target-domain

#define SyncGeneric_Q_BLOCKING (Int)1

DETAILS

Implementations with this "quality" may cause the calling thread to block;

const SyncGeneric_WAIT_FOREVER

index URL

Used to wait forever

C synopsis target-domain

#define SyncGeneric_WAIT_FOREVER (UInt)~(0)

enum SyncGeneric_WaitStatus

index URL

Error codes returned by ISync_wait

C synopsis target-domain

typedef enum SyncGeneric_WaitStatus {

SyncGeneric_WaitStatus_ERROR,

SyncGeneric_WaitStatus_TIMEOUT,

SyncGeneric_WaitStatus_SUCCESS

} SyncGeneric_WaitStatus;

typedef SyncGeneric_QueryFunc

index URL

typedef for user specified wait function

C synopsis target-domain

typedef Bool (*SyncGeneric_QueryFunc)(Int);

typedef SyncGeneric_SignalFunc

index URL

typedef for user specified signal function

C synopsis target-domain

typedef Void (*SyncGeneric_SignalFunc)(UArg);

typedef SyncGeneric_WaitFunc

index URL

typedef for user specified wait function

C synopsis target-domain

typedef Bool (*SyncGeneric_WaitFunc)(UArg,UInt);

Module-Wide Built-Ins

index URL

C synopsis target-domain

Types_ModuleId SyncGeneric_Module_id();

// Get this module's unique id

Bool SyncGeneric_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle SyncGeneric_Module_heap();

// The heap from which this module allocates memory

Bool SyncGeneric_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 SyncGeneric_Module_getMask();

// Returns the diagnostics mask for this module

Void SyncGeneric_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct SyncGeneric_Object SyncGeneric_Object;

// Opaque internal representation of an instance object

typedef SyncGeneric_Object *SyncGeneric_Handle;

// Client reference to an instance object

typedef struct SyncGeneric_Struct SyncGeneric_Struct;

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

SyncGeneric_Handle SyncGeneric_handle(SyncGeneric_Struct *structP);

// Convert this instance structure pointer into an instance handle

SyncGeneric_Struct *SyncGeneric_struct(SyncGeneric_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

typedef struct SyncGeneric_Params {

// Instance config-params structure

IInstance_Params *instance;

// Common per-instance configs

UArg signalArg;

// user signal function arg

SyncGeneric_QueryFunc userQuery;

// user query function

SyncGeneric_SignalFunc userSignal;

// user signal function

SyncGeneric_WaitFunc userWait;

// user wait function

UArg waitArg;

// user wait function arg

} SyncGeneric_Params;

Void SyncGeneric_Params_init(SyncGeneric_Params *params);

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

config SyncGeneric_signalArg // instance

index URL

user signal function arg

C synopsis target-domain

struct SyncGeneric_Params {

...

UArg signalArg;

config SyncGeneric_userQuery // instance

index URL

user query function

C synopsis target-domain

struct SyncGeneric_Params {

...

SyncGeneric_QueryFunc userQuery;

config SyncGeneric_userSignal // instance

index URL

user signal function

C synopsis target-domain

struct SyncGeneric_Params {

...

SyncGeneric_SignalFunc userSignal;

config SyncGeneric_userWait // instance

index URL

user wait function

C synopsis target-domain

struct SyncGeneric_Params {

...

SyncGeneric_WaitFunc userWait;

config SyncGeneric_waitArg // instance

index URL

user wait function arg

C synopsis target-domain

struct SyncGeneric_Params {

...

UArg waitArg;

Instance Creation

index URL

C synopsis target-domain

SyncGeneric_Handle SyncGeneric_create(const SyncGeneric_Params *params, Error_Block *eb);

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

Void SyncGeneric_construct(SyncGeneric_Struct *structP, const SyncGeneric_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 SyncGeneric_delete(SyncGeneric_Handle *handleP);

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

Void SyncGeneric_destruct(SyncGeneric_Struct *structP);

// Finalize the instance object inside the provided structure

SyncGeneric_query() // instance

index URL

Query for a particular quality

C synopsis target-domain

Bool SyncGeneric_query(SyncGeneric_Handle handle, Int qual);

ARGUMENTS

handle — handle of a previously-created SyncGeneric instance object

qual — quality

RETURNS

TRUE or FALSE.

DETAILS

FALSE is returned if quality not supported.

SyncGeneric_signal() // instance

index URL

Called at completion of an activity

C synopsis target-domain

Void SyncGeneric_signal(SyncGeneric_Handle handle);

ARGUMENTS

handle — handle of a previously-created SyncGeneric instance object

DETAILS

This function is non-blocking. It is also required that the underlying sync be binary in nature.

This function does not take an Error.Block intentionally because it can be called from ISR context.

SyncGeneric_wait() // instance

index URL

Called to wait/poll for completion of an activity

C synopsis target-domain

Int SyncGeneric_wait(SyncGeneric_Handle handle, UInt timeout, Error_Block *eb);

ARGUMENTS

handle — handle of a previously-created SyncGeneric instance object

timeout — Timeout in microseconds

eb — Hist Pointer to Error.Block

RETURNS

Refer to description above

DETAILS

This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.

WaitStatus_ERROR if an error occured.
WaitStatus_TIMEOUT denotes timeout.
WaitStatus_SUCCESS semaphore was decremented.

Instance Convertors

index URL

C synopsis target-domain

ISync_Handle SyncGeneric_Handle_upCast(SyncGeneric_Handle handle);

// unconditionally move one level up the inheritance hierarchy

SyncGeneric_Handle SyncGeneric_Handle_downCast(ISync_Handle handle);

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

Instance Built-Ins

index URL

C synopsis target-domain

Int SyncGeneric_Object_count();

// The number of statically-created instance objects

SyncGeneric_Handle SyncGeneric_Object_get(SyncGeneric_Object *array, Int i);

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

SyncGeneric_Handle SyncGeneric_Object_first();

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

SyncGeneric_Handle SyncGeneric_Object_next(SyncGeneric_Handle handle);

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

IHeap_Handle SyncGeneric_Object_heap();

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

Types_Label *SyncGeneric_Handle_label(SyncGeneric_Handle handle, Types_Label *buf);

// The label associated with this instance object

String SyncGeneric_Handle_name(SyncGeneric_Handle handle);

// The name of this instance object

XDCscript usage meta-domain sourced in xdc/runtime/knl/SyncGeneric.xdc

var SyncGeneric = xdc.useModule('xdc.runtime.knl.SyncGeneric');

module-wide constants & types

const SyncGeneric.NO_WAIT// Used to specify no waiting = 0;

const SyncGeneric.Q_BLOCKING// Blocking quality = 1;

const SyncGeneric.WAIT_FOREVER// Used to wait forever = ~(0);

values of type SyncGeneric.WaitStatus// Error codes returned by ISync_wait

const SyncGeneric.WaitStatus_ERROR;

const SyncGeneric.WaitStatus_TIMEOUT;

const SyncGeneric.WaitStatus_SUCCESS;

module-wide config parameters

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

per-instance config parameters

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

params.signalArg// user signal function arg = UArg null;

params.userQuery// user query function = Bool(*)(Int) null;

params.userSignal// user signal function = Void(*)(UArg) null;

params.userWait// user wait function = Bool(*)(UArg,UInt) null;

params.waitArg// user wait function arg = UArg null;

per-instance creation

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

const SyncGeneric.NO_WAIT

index URL

Used to specify no waiting

XDCscript usage meta-domain

const SyncGeneric.NO_WAIT = 0;

C SYNOPSIS

SyncGeneric_NO_WAIT

const SyncGeneric.Q_BLOCKING

index URL

Blocking quality

XDCscript usage meta-domain

const SyncGeneric.Q_BLOCKING = 1;

DETAILS

Implementations with this "quality" may cause the calling thread to block;

C SYNOPSIS

SyncGeneric_Q_BLOCKING

const SyncGeneric.WAIT_FOREVER

index URL

Used to wait forever

XDCscript usage meta-domain

const SyncGeneric.WAIT_FOREVER = ~(0);

C SYNOPSIS

SyncGeneric_WAIT_FOREVER

enum SyncGeneric.WaitStatus

index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain

values of type SyncGeneric.WaitStatus

const SyncGeneric.WaitStatus_ERROR;

const SyncGeneric.WaitStatus_TIMEOUT;

const SyncGeneric.WaitStatus_SUCCESS;

C SYNOPSIS

SyncGeneric_WaitStatus

metaonly config SyncGeneric.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

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

Instance Config Parameters

index URL

XDCscript usage meta-domain

var params = new SyncGeneric.Params;

// Instance config-params object

params.signalArg = UArg null;

// user signal function arg

params.userQuery = Bool(*)(Int) null;

// user query function

params.userSignal = Void(*)(UArg) null;

// user signal function

params.userWait = Bool(*)(UArg,UInt) null;