module ti.sysbios.syncs.SyncSwi

Implements ISync using Swis

Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Swimore ... ]
C synopsis target-domain sourced in ti/sysbios/syncs/SyncSwi.xdc
#include <ti/sysbios/syncs/SyncSwi.h>
Functions
Void
Void
Void
Void
Functions common to all ISync modules
Bool 
Void 
Int 
Functions common to all target instances
Functions common to all target modules
Defines
#define
#define
#define
Typedefs
typedef SyncSwi_Object *
typedef struct
typedef struct
typedef struct
typedef enum
Constants
extern const Assert_Id 
 
DETAILS
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Swi
This module uses ti.sysbios.knl.Swi.post to implement xdc.runtime.knl.ISync.signal The implementation of xdc.runtime.knl.ISync.wait is empty and returns FALSE for timeout, since Swis are asynchronous in nature.
Modules like ti.sdo.io.Stream use an ISync.Handle for selecting the synchronization mechanism. This allows Stream to be independent of the synchronization mechanism.
An instance of SyncSwi requires an Swi.Handle. When given a null Swi.Handle, SynSwi will assert.
 
const SyncSwi_NO_WAIT

Used to specify no waiting

C synopsis target-domain
#define SyncSwi_NO_WAIT (UInt)0
 
 
const SyncSwi_Q_BLOCKING

Blocking quality

C synopsis target-domain
#define SyncSwi_Q_BLOCKING (Int)1
 
DETAILS
Implementations with this "quality" may cause the calling thread to block;
 
const SyncSwi_WAIT_FOREVER

Used to wait forever

C synopsis target-domain
#define SyncSwi_WAIT_FOREVER (UInt)~(0)
 
 
enum SyncSwi_WaitStatus

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncSwi_WaitStatus {
    SyncSwi_WaitStatus_ERROR,
    SyncSwi_WaitStatus_TIMEOUT,
    SyncSwi_WaitStatus_SUCCESS
} SyncSwi_WaitStatus;
 
 
config SyncSwi_A_nullHandle  // module-wide

Assert when baseHandle is null

C synopsis target-domain
extern const Assert_Id SyncSwi_A_nullHandle;
 
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId SyncSwi_Module_id();
// Get this module's unique id
 
Bool SyncSwi_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle SyncSwi_Module_heap();
// The heap from which this module allocates memory
 
Bool SyncSwi_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 SyncSwi_Module_getMask();
// Returns the diagnostics mask for this module
 
Void SyncSwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct SyncSwi_Object SyncSwi_Object;
// Opaque internal representation of an instance object
 
typedef SyncSwi_Object *SyncSwi_Handle;
// Client reference to an instance object
 
typedef struct SyncSwi_Struct SyncSwi_Struct;
// Opaque client structure large enough to hold an instance object
 
SyncSwi_Handle SyncSwi_handle(SyncSwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
SyncSwi_Struct *SyncSwi_struct(SyncSwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct SyncSwi_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Swi_Handle swi;
    // Swi handle to be used
} SyncSwi_Params;
 
Void SyncSwi_Params_init(SyncSwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config SyncSwi_Params.swi  // instance

Swi handle to be used

C synopsis target-domain
struct SyncSwi_Params {
      ...
    Swi_Handle swi;
 
Runtime Instance Creation

C synopsis target-domain
SyncSwi_Handle SyncSwi_create(const SyncSwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void SyncSwi_construct(SyncSwi_Struct *structP, const SyncSwi_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

C synopsis target-domain
Void SyncSwi_delete(SyncSwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void SyncSwi_destruct(SyncSwi_Struct *structP);
// Finalize the instance object inside the provided structure
 
SyncSwi_query()  // instance

Query for a particular quality

C synopsis target-domain
Bool SyncSwi_query(SyncSwi_Handle handle, Int qual);
 
ARGUMENTS
handle — handle of a previously-created SyncSwi instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
 
SyncSwi_signal()  // instance

Called at completion of an activity

C synopsis target-domain
Void SyncSwi_signal(SyncSwi_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created SyncSwi 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.
 
SyncSwi_wait()  // instance

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncSwi_wait(SyncSwi_Handle handle, UInt timeout, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created SyncSwi 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.
Instance Convertors

C synopsis target-domain
ISync_Handle SyncSwi_Handle_upCast(SyncSwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
SyncSwi_Handle SyncSwi_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int SyncSwi_Object_count();
// The number of statically-created instance objects
 
SyncSwi_Handle SyncSwi_Object_get(SyncSwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
SyncSwi_Handle SyncSwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
SyncSwi_Handle SyncSwi_Object_next(SyncSwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle SyncSwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *SyncSwi_Handle_label(SyncSwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String SyncSwi_Handle_name(SyncSwi_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/syncs/SyncSwi.xdc
var SyncSwi = xdc.useModule('ti.sysbios.syncs.SyncSwi');
module-wide constants & types
 
        const SyncSwi.WaitStatus_ERROR;
        const SyncSwi.WaitStatus_TIMEOUT;
        const SyncSwi.WaitStatus_SUCCESS;
module-wide config parameters
        msg: "A_nullHandle: Null handle passed to create"
    };
 
per-instance config parameters
    var params = new SyncSwi.Params// Instance config-params object;
        params.swi// Swi handle to be used = Swi.Handle null;
per-instance creation
    var inst = SyncSwi.create// Create an instance-object(params);
 
 
const SyncSwi.NO_WAIT

Used to specify no waiting

Configuration settings
const SyncSwi.NO_WAIT = 0;
 
C SYNOPSIS
 
const SyncSwi.Q_BLOCKING

Blocking quality

Configuration settings
const SyncSwi.Q_BLOCKING = 1;
 
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
 
const SyncSwi.WAIT_FOREVER

Used to wait forever

Configuration settings
const SyncSwi.WAIT_FOREVER = ~(0);
 
C SYNOPSIS
 
enum SyncSwi.WaitStatus

Error codes returned by ISync_wait

Configuration settings
values of type SyncSwi.WaitStatus
    const SyncSwi.WaitStatus_ERROR;
    const SyncSwi.WaitStatus_TIMEOUT;
    const SyncSwi.WaitStatus_SUCCESS;
 
C SYNOPSIS
 
config SyncSwi.A_nullHandle  // module-wide

Assert when baseHandle is null

Configuration settings
SyncSwi.A_nullHandle = Assert.Desc {
    msg: "A_nullHandle: Null handle passed to create"
};
 
C SYNOPSIS
 
metaonly config SyncSwi.common$  // module-wide

Common module configuration parameters

Configuration settings
SyncSwi.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

Configuration settings
var params = new SyncSwi.Params;
// Instance config-params object
    params.swi = Swi.Handle null;
    // Swi handle to be used
 
config SyncSwi.Params.swi  // instance

Swi handle to be used

Configuration settings
var params = new SyncSwi.Params;
  ...
params.swi = Swi.Handle null;
 
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new SyncSwi.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = SyncSwi.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, 23 May 2019 00:23:07 GMT