module ti.sysbios.family.arm.ducati.GateDualCore

A Gate for use by the two Ducati M3 cores to manage shared resources

GateDualCore uses disabling and enabling of interrupts as well as a shared variable between the two M3 cores as the resource locking mechanism. Such a gate guarantees exclusive access to a resource shared between the cores. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/GateDualCore.xdc
#include <ti/sysbios/family/arm/ducati/GateDualCore.h>
Functions
Void
Void
Void
Void
Void 
Functions common to all IGateProvider modules
Bool 
Functions common to all target instances
Functions common to all target modules
Defines
#define
#define
Typedefs
typedef struct
typedef struct
typedef struct
Constants
extern const Assert_Id 
extern const Bool 
extern const Error_Id 
extern const Error_Id 
extern const Ptr 
extern const Bool 
extern const UInt 
Variables
UInt32 
GateDualCore_gateArray// Shared array of gate variables[GateDualCore_numGates]; // linked as extern ti_sysbios_family_arm_ducati_GateDualCore_gateArray
 
DETAILS
GateDualCore uses disabling and enabling of interrupts as well as a shared variable between the two M3 cores as the resource locking mechanism. Such a gate guarantees exclusive access to a resource shared between the cores.
Each gate consumes one 32 bit word of shared memory. An array of these gates is shared between the two M3 cores and therefore the address of this array must be known to both (see gateArrayAddress).
By default, the array has 4 entries (see numGates) and is placed immediately below Core 0's default interrupt vector table address. It is the responsibility of the user to configure both cores with the same array address and size.
RESTRICTIONS
In a dual core M3 (Ducati) environment, core 0 is responsible for initializing the shared gate variable, therefore core 0 must be brought up BEFORE core 1 invokes GateDualCore_enter(). This can be achieved by simply running core 0 to its main() function prior to loading and running core 1.
GateDualCore does not support nesting of enter/leave calls.
Global interrupts are disabled upon return from GateDualCore_enter(). The duration between the enter and leave should be as short as possible to minimize Hwi latency and stalls by the other M3 core.
Gate zero (0) is reserved for the ti.sysbios.hal.unicache.Cache module and is internally configured for its use.
 
const GateDualCore_Q_BLOCKING

Blocking quality

C synopsis target-domain
#define GateDualCore_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 GateDualCore_Q_PREEMPTING

Preempting quality

C synopsis target-domain
#define GateDualCore_Q_PREEMPTING (Int)2
 
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
 
config GateDualCore_A_nestedEnter  // module-wide

Assert if nested "enter" called

C synopsis target-domain
extern const Assert_Id GateDualCore_A_nestedEnter;
 
 
config GateDualCore_E_gateInUse  // module-wide

Error raised if a Gate is already in use

C synopsis target-domain
extern const Error_Id GateDualCore_E_gateInUse;
 
 
config GateDualCore_E_invalidIndex  // module-wide

Error raised if an invalid Gate index is provided

C synopsis target-domain
extern const Error_Id GateDualCore_E_invalidIndex;
 
 
config GateDualCore_enableStats  // module-wide

Gate statistics collection flag. Default is disabled

C synopsis target-domain
extern const Bool GateDualCore_enableStats;
 
 
config GateDualCore_gateArrayAddress  // module-wide

Base address of configurable Ducati Gate Array

C synopsis target-domain
extern const Ptr GateDualCore_gateArrayAddress;
 
DETAILS
Each gate consumes one 32 bit word of shared memory. The array is shared between the two M3 cores and therefore the address of this array must be the same for both.
By default, the array has 4 entries (see numGates) and is placed immediately below Core 1's default interrupt vector table address of 0x00000800 (see ti.sysbios.family.arm.m3.Hwi.vectorTableAddress).
Gate zero (0) is reserved for the ti.sysbios.hal.unicache.Cache module.
 
config GateDualCore_initGates  // module-wide

Gate initialize flag

C synopsis target-domain
extern const Bool GateDualCore_initGates;
 
DETAILS
By default, core 0 initializes all of the gates in gateArray. This behavior can be overridden by explicitly setting this flag within your config script.
 
config GateDualCore_numGates  // module-wide

Number of Gates that can be created. Default is 4

C synopsis target-domain
extern const UInt GateDualCore_numGates;
 
DETAILS
Each gate consumes one 32 bit word of memory. (see gateArrayAddress).
 
extern GateDualCore_gateArray

Shared array of gate variables

C synopsis target-domain
UInt32 GateDualCore_gateArray[GateDualCore_numGates]; // linked as extern ti_sysbios_family_arm_ducati_GateDualCore_gateArray
 
DETAILS
This global variable is placed in its own data section and that section is placed at gateArrayAddress.
The size of the array is determined by numGates
 
GateDualCore_query()  // module-wide

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateDualCore_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.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId GateDualCore_Module_id();
// Get this module's unique id
 
Bool GateDualCore_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle GateDualCore_Module_heap();
// The heap from which this module allocates memory
 
Bool GateDualCore_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 GateDualCore_Module_getMask();
// Returns the diagnostics mask for this module
 
Void GateDualCore_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct GateDualCore_Object GateDualCore_Object;
// Opaque internal representation of an instance object
 
typedef GateDualCore_Object *GateDualCore_Handle;
// Client reference to an instance object
 
typedef struct GateDualCore_Struct GateDualCore_Struct;
// Opaque client structure large enough to hold an instance object
 
GateDualCore_Handle GateDualCore_handle(GateDualCore_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
GateDualCore_Struct *GateDualCore_struct(GateDualCore_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct GateDualCore_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UInt index;
    // index of the gate variable in the shared gateArray table
} GateDualCore_Params;
 
Void GateDualCore_Params_init(GateDualCore_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config GateDualCore_Params.index  // instance

index of the gate variable in the shared gateArray table

C synopsis target-domain
      ...
    UInt index;
 
Runtime Instance Creation

C synopsis target-domain
GateDualCore_Handle GateDualCore_create(const GateDualCore_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void GateDualCore_construct(GateDualCore_Struct *structP, const GateDualCore_Params *params, Error_Block *eb);
// 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 GateDualCore_delete(GateDualCore_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void GateDualCore_destruct(GateDualCore_Struct *structP);
// Finalize the instance object inside the provided structure
 
GateDualCore_sync()  // instance

Sync execution with the other M3 core

C synopsis target-domain
Void GateDualCore_sync(GateDualCore_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created GateDualCore instance object
Instance Convertors

C synopsis target-domain
IGateProvider_Handle GateDualCore_Handle_upCast(GateDualCore_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
GateDualCore_Handle GateDualCore_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int GateDualCore_Object_count();
// The number of statically-created instance objects
 
GateDualCore_Handle GateDualCore_Object_get(GateDualCore_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
GateDualCore_Handle GateDualCore_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
GateDualCore_Handle GateDualCore_Object_next(GateDualCore_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle GateDualCore_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *GateDualCore_Handle_label(GateDualCore_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String GateDualCore_Handle_name(GateDualCore_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/family/arm/ducati/GateDualCore.xdc
var GateDualCore = xdc.useModule('ti.sysbios.family.arm.ducati.GateDualCore');
module-wide constants & types
module-wide config parameters
        msg: "A_nestedEnter: Can't nest 'enter' calls."
    };
        msg: "E_gateInUse %d"
    };
        msg: "E_invalidIndex %d"
    };
 
module-wide functions
per-instance config parameters
    var params = new GateDualCore.Params// Instance config-params object;
per-instance creation
    var inst = GateDualCore.create// Create an instance-object(params);
 
 
const GateDualCore.Q_BLOCKING

Blocking quality

Configuration settings
const GateDualCore.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
 
const GateDualCore.Q_PREEMPTING

Preempting quality

Configuration settings
const GateDualCore.Q_PREEMPTING = 2;
 
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
 
config GateDualCore.A_nestedEnter  // module-wide

Assert if nested "enter" called

Configuration settings
GateDualCore.A_nestedEnter = Assert.Desc {
    msg: "A_nestedEnter: Can't nest 'enter' calls."
};
 
C SYNOPSIS
 
config GateDualCore.E_gateInUse  // module-wide

Error raised if a Gate is already in use

Configuration settings
GateDualCore.E_gateInUse = Error.Desc {
    msg: "E_gateInUse %d"
};
 
C SYNOPSIS
 
config GateDualCore.E_invalidIndex  // module-wide

Error raised if an invalid Gate index is provided

Configuration settings
GateDualCore.E_invalidIndex = Error.Desc {
    msg: "E_invalidIndex %d"
};
 
C SYNOPSIS
 
config GateDualCore.enableStats  // module-wide

Gate statistics collection flag. Default is disabled

Configuration settings
GateDualCore.enableStats = Bool false;
 
C SYNOPSIS
 
config GateDualCore.gateArrayAddress  // module-wide

Base address of configurable Ducati Gate Array

Configuration settings
GateDualCore.gateArrayAddress = Ptr 0x000007f0;
 
DETAILS
Each gate consumes one 32 bit word of shared memory. The array is shared between the two M3 cores and therefore the address of this array must be the same for both.
By default, the array has 4 entries (see numGates) and is placed immediately below Core 1's default interrupt vector table address of 0x00000800 (see ti.sysbios.family.arm.m3.Hwi.vectorTableAddress).
Gate zero (0) is reserved for the ti.sysbios.hal.unicache.Cache module.
C SYNOPSIS
 
config GateDualCore.initGates  // module-wide

Gate initialize flag

Configuration settings
GateDualCore.initGates = Bool undefined;
 
DETAILS
By default, core 0 initializes all of the gates in gateArray. This behavior can be overridden by explicitly setting this flag within your config script.
C SYNOPSIS
 
config GateDualCore.numGates  // module-wide

Number of Gates that can be created. Default is 4

Configuration settings
GateDualCore.numGates = UInt 4;
 
DETAILS
Each gate consumes one 32 bit word of memory. (see gateArrayAddress).
C SYNOPSIS
 
metaonly config GateDualCore.common$  // module-wide

Common module configuration parameters

Configuration settings
GateDualCore.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 config GateDualCore.rovViewInfo  // module-wide
Configuration settings
GateDualCore.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly GateDualCore.queryMeta()  // module-wide

Configuration time test for a particular gate quality

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

Configuration settings
var params = new GateDualCore.Params;
// Instance config-params object
    params.index = UInt 0;
    // index of the gate variable in the shared gateArray table
 
config GateDualCore.Params.index  // instance

index of the gate variable in the shared gateArray table

Configuration settings
var params = new GateDualCore.Params;
  ...
params.index = UInt 0;
 
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new GateDualCore.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = GateDualCore.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:22:49 GMT