module ti.sdo.ipc.notifyDrivers.NotifyDriverCirc
index URL

A shared memory driver using circular buffer for the Notify Module

This is a ti.sdo.ipc.Notify driver that utilizes shared memory and inter-processor hardware interrupts for notification between cores. This driver supports caching. [ more ... ]
C synopsis target-domain sourced in ti/sdo/ipc/notifyDrivers/NotifyDriverCirc.xdc
#include <ti/sdo/ipc/notifyDrivers/NotifyDriverCirc.h>
Functions
Void
NotifyDriverCirc_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(NotifyDriverCirc_Params *params);
SizeT 
NotifyDriverCirc_sharedMemReq// Amount of shared memory required for creation of each instance(NotifyDriverCirc_Params *params);
Functions common to all INotifyDriver modules
Void 
NotifyDriverCirc_disable// Disable a NotifyDriver instance(NotifyDriverCirc_Handle handle);
Void 
NotifyDriverCirc_disableEvent// Disable an event(NotifyDriverCirc_Handle handle, UInt32 eventId);
Void 
NotifyDriverCirc_enable// Enable a NotifyDriver instance(NotifyDriverCirc_Handle handle);
Void 
NotifyDriverCirc_enableEvent// Enable an event(NotifyDriverCirc_Handle handle, UInt32 eventId);
Void 
NotifyDriverCirc_registerEvent// Register a callback to an event(NotifyDriverCirc_Handle handle, UInt32 eventId);
Int 
NotifyDriverCirc_sendEvent// Send a signal to an event(NotifyDriverCirc_Handle handle, UInt32 eventId, UInt32 payload, Bool waitClear);
Void 
NotifyDriverCirc_unregisterEvent// Remove an event listener from an event(NotifyDriverCirc_Handle handle, UInt32 eventId);
Functions common to all target instances
NotifyDriverCirc_handle// Convert this instance structure pointer into an instance handle, NotifyDriverCirc_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, NotifyDriverCirc_Handle_label// The label associated with this instance object, NotifyDriverCirc_Handle_name// The name of this instance object, NotifyDriverCirc_Handle_upCast// unconditionally move one level up the inheritance hierarchy, NotifyDriverCirc_Object_count// The number of statically-created instance objects, NotifyDriverCirc_Object_first// The handle of the first dynamically-created instance object, or NULL, NotifyDriverCirc_Object_get// The handle of the i-th statically-created instance object (array == NULL), NotifyDriverCirc_Object_heap// The heap used to allocate dynamically-created instance objects, NotifyDriverCirc_Object_next// The handle of the next dynamically-created instance object, or NULL, NotifyDriverCirc_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
NotifyDriverCirc_Module_getMask// Returns the diagnostics mask for this module, NotifyDriverCirc_Module_hasMask// Test whether this module has a diagnostics mask, NotifyDriverCirc_Module_heap// The heap from which this module allocates memory, NotifyDriverCirc_Module_id// Get this module's unique id, NotifyDriverCirc_Module_setMask// Set the diagnostics mask for this module, NotifyDriverCirc_Module_startupDone// Test if this module has completed startup
Typedefs
typedef NotifyDriverCirc_Object *
NotifyDriverCirc_Handle// Client reference to an instance object;
typedef struct
NotifyDriverCirc_Object// Opaque internal representation of an instance object NotifyDriverCirc_Object;
typedef struct
NotifyDriverCirc_Params// Instance config-params structure ...
typedef struct
NotifyDriverCirc_Struct// Opaque client structure large enough to hold an instance object NotifyDriverCirc_Struct;
Constants
extern const Assert_Id 
NotifyDriverCirc_A_notSupported// Assert raised when trying to use Notify_[enable/disable]Event with NotifyDriverCirc;
extern const Bool 
NotifyDriverCirc_enableStats// Enable statistics for sending an event;
extern const UInt 
NotifyDriverCirc_numMsgs// The number of messages or slots in the circular buffer;
 
DETAILS
This is a ti.sdo.ipc.Notify driver that utilizes shared memory and inter-processor hardware interrupts for notification between cores. This driver supports caching.
This driver is designed to work with a variety of devices, each with distinct interrupt mechanisms. Therefore, this module needs to be plugged with an appropriate module that implements the IInterrupt interface for a given device.
The Notify_[enable/disable]Event APIs are not supported by this driver.
The driver utilizes shared memory in the manner indicated by the following diagram.
  
  NOTE: Processors '0' and '1' correspond to the processors with lower and
        higher MultiProc ids, respectively

 sharedAddr -> --------------------------- bytes
               |  eventEntry0  (0)       | 8  
               |  eventEntry1  (0)       | 8
               |  ...                    | 
               |  eventEntry15 (0)       | 8
               |  [align to cache size]  |
               |-------------------------|
               |  eventEntry16 (0)       | 8
               |  eventEntry17 (0)       | 8
               |  ...                    | 
               |  eventEntry31 (0)       | 8
               |  [align to cache size]  |
               |-------------------------|
               |  putWriteIndex (0)      | 4
               |  [align to cache size]  |
               |-------------------------|
               |  putReadIndex (0)       | 4
               |  [align to cache size]  |
               |-------------------------|
               |  eventEntry0  (1)       | 8  
               |  eventEntry1  (1)       | 8
               |  ...                    | 
               |  eventEntry15 (1)       | 8
               |  [align to cache size]  |
               |-------------------------|
               |  eventEntry16 (1)       | 8
               |  eventEntry17 (1)       | 8
               |  ...                    | 
               |  eventEntry31 (1)       | 8
               |  [align to cache size]  |
               |-------------------------|
               |  getWriteIndex (1)      | 4
               |  [align to cache size]  |
               |-------------------------|
               |  getReadIndex (1)       | 4
               |  [align to cache size]  |
               |-------------------------|


  Legend:
  (0), (1) : Memory that belongs to the proc with lower and higher 
             MultiProc.id, respectively
   |----|  : Cache line boundary
 
config NotifyDriverCirc_A_notSupported  // module-wide
index URL

Assert raised when trying to use Notify_[enable/disable]Event with NotifyDriverCirc

C synopsis target-domain
extern const Assert_Id NotifyDriverCirc_A_notSupported;
 
 
config NotifyDriverCirc_enableStats  // module-wide
index URL

Enable statistics for sending an event

C synopsis target-domain
extern const Bool NotifyDriverCirc_enableStats;
 
DETAILS
If this parameter is to 'TRUE' and 'waitClear' is also set to TRUE when calling (@link #sendEvent(), then the module keeps track of the number of times the processor spins waiting for an empty slot and the max amount of time it waits.
 
config NotifyDriverCirc_numMsgs  // module-wide
index URL

The number of messages or slots in the circular buffer

C synopsis target-domain
extern const UInt NotifyDriverCirc_numMsgs;
 
DETAILS
This is use to determine the size of the put and get buffers. Each eventEntry is two 32bits wide, therefore the total size of each circular buffer is [numMsgs * sizeof(eventEntry)]. The total size of each buffer must be a multiple of the the cache line size. For example, if the cacheLineSize = 128 then numMsgs could be 16, 32, etc...
 
NotifyDriverCirc_sharedMemReq()  // module-wide
index URL

Amount of shared memory required for creation of each instance

C synopsis target-domain
SizeT NotifyDriverCirc_sharedMemReq(NotifyDriverCirc_Params *params);
 
ARGUMENTS
params — Pointer to parameters that will be used in the create
RETURNS
Number of MAUs in shared memory needed to create the instance.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId NotifyDriverCirc_Module_id();
// Get this module's unique id
 
Bool NotifyDriverCirc_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle NotifyDriverCirc_Module_heap();
// The heap from which this module allocates memory
 
Bool NotifyDriverCirc_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 NotifyDriverCirc_Module_getMask();
// Returns the diagnostics mask for this module
 
Void NotifyDriverCirc_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct NotifyDriverCirc_Object NotifyDriverCirc_Object;
// Opaque internal representation of an instance object
 
typedef NotifyDriverCirc_Object *NotifyDriverCirc_Handle;
// Client reference to an instance object
 
typedef struct NotifyDriverCirc_Struct NotifyDriverCirc_Struct;
// Opaque client structure large enough to hold an instance object
 
NotifyDriverCirc_Handle NotifyDriverCirc_handle(NotifyDriverCirc_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
NotifyDriverCirc_Struct *NotifyDriverCirc_struct(NotifyDriverCirc_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct NotifyDriverCirc_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Bool cacheEnabled;
    // Whether cache operations will be performed
    SizeT cacheLineSize;
    // The cache line size of the shared memory
    UInt intVectorId;
    // Interrupt vector ID to be used by the driver
    UInt localIntId;
    // Local interrupt ID for interrupt line
    UInt remoteIntId;
    // Remote interrupt ID for interrupt line
    UInt16 remoteProcId;
    // The MultiProc ID corresponding to the remote processor
    Ptr sharedAddr;
    // Address in shared memory where this instance will be placed
} NotifyDriverCirc_Params;
 
Void NotifyDriverCirc_Params_init(NotifyDriverCirc_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config NotifyDriverCirc_cacheEnabled  // instance
index URL

Whether cache operations will be performed

C synopsis target-domain
struct NotifyDriverCirc_Params {
      ...
    Bool cacheEnabled;
 
DETAILS
If it is known that no cache operations are needed for this instance set this flag to FALSE. If sharedAddr lies within a shared region and the cache enabled setting for the region is FALSE, then the value specified here will be overriden to FALSE.
 
config NotifyDriverCirc_cacheLineSize  // instance
index URL

The cache line size of the shared memory

C synopsis target-domain
struct NotifyDriverCirc_Params {
      ...
    SizeT cacheLineSize;
 
DETAILS
This value should be configured
 
config NotifyDriverCirc_intVectorId  // instance
index URL

Interrupt vector ID to be used by the driver

C synopsis target-domain
struct NotifyDriverCirc_Params {
      ...
    UInt intVectorId;
 
DETAILS
This parameter is only used by C64x+ targets
 
config NotifyDriverCirc_localIntId  // instance
index URL

Local interrupt ID for interrupt line

C synopsis target-domain
struct NotifyDriverCirc_Params {
      ...
    UInt localIntId;
 
DETAILS
For devices that support multiple inter-processor interrupt lines, this configuration parameter allows selecting a specific line to use for receiving an interrupt. The value specified here corresponds to the incoming interrupt line on the local processor.
If this configuration is not set, a default interrupt id is typically chosen.
 
config NotifyDriverCirc_remoteIntId  // instance
index URL

Remote interrupt ID for interrupt line

C synopsis target-domain
struct NotifyDriverCirc_Params {
      ...
    UInt remoteIntId;
 
DETAILS
For devices that support multiple inter-processor interrupt lines, this configuration parameter allows selecting a specific line to use for receiving an interrupt. The value specified here corresponds to the incoming interrupt line on the remote processor.
If this configuration is not set, a default interrupt id is typically chosen.
 
config NotifyDriverCirc_remoteProcId  // instance
index URL

The MultiProc ID corresponding to the remote processor

C synopsis target-domain
struct NotifyDriverCirc_Params {
      ...
    UInt16 remoteProcId;
 
DETAILS
This parameter must be set for every device. The MultiProc_getId call can be used to obtain a MultiProc id given the remote processor's name.
 
config NotifyDriverCirc_sharedAddr  // instance
index URL

Address in shared memory where this instance will be placed

C synopsis target-domain
struct NotifyDriverCirc_Params {
      ...
    Ptr sharedAddr;
 
DETAILS
Use sharedMemReq to determine the amount of shared memory required.
 
NotifyDriverCirc_disable()  // instance
index URL

Disable a NotifyDriver instance

C synopsis target-domain
Void NotifyDriverCirc_disable(NotifyDriverCirc_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created NotifyDriverCirc instance object
DETAILS
Disables the ability of a Notify driver to receive events for a given processor. This interface function is called by the Notify_disable function. Refer to its documentation for more details.
 
NotifyDriverCirc_disableEvent()  // instance
index URL

Disable an event

C synopsis target-domain
Void NotifyDriverCirc_disableEvent(NotifyDriverCirc_Handle handle, UInt32 eventId);
 
ARGUMENTS
handle — handle of a previously-created NotifyDriverCirc instance object
eventId — Number of event to disable
DETAILS
This interface function is called by the Notify_disableEvent function. Refer to its documentation for more details.
The Notify module does validation of the eventId. The Notify module enters calls this function within the Notify module gate.
 
NotifyDriverCirc_enable()  // instance
index URL

Enable a NotifyDriver instance

C synopsis target-domain
Void NotifyDriverCirc_enable(NotifyDriverCirc_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created NotifyDriverCirc instance object
DETAILS
Enables the ability of a Notify driver to receive events for a given processor. This interface function is called by the Notify_restore function. Refer to its documentation for more details.
 
NotifyDriverCirc_enableEvent()  // instance
index URL

Enable an event

C synopsis target-domain
Void NotifyDriverCirc_enableEvent(NotifyDriverCirc_Handle handle, UInt32 eventId);
 
ARGUMENTS
handle — handle of a previously-created NotifyDriverCirc instance object
eventId — Number of event to enable
DETAILS
This interface function is called by the Notify_disableEvent function. Refer to its documentation for more details.
The Notify module does validation of the eventId. The Notify module enters calls this function within the Notify module gate.
 
NotifyDriverCirc_registerEvent()  // instance
index URL

Register a callback to an event

C synopsis target-domain
Void NotifyDriverCirc_registerEvent(NotifyDriverCirc_Handle handle, UInt32 eventId);
 
ARGUMENTS
handle — handle of a previously-created NotifyDriverCirc instance object
eventId — Number of event that is being registered
DETAILS
This driver function is called by the Notify_registerEvent function within the Notify module gate. Refer to its documentation for more details.
 
NotifyDriverCirc_sendEvent()  // instance
index URL

Send a signal to an event

C synopsis target-domain
Int NotifyDriverCirc_sendEvent(NotifyDriverCirc_Handle handle, UInt32 eventId, UInt32 payload, Bool waitClear);
 
ARGUMENTS
handle — handle of a previously-created NotifyDriverCirc instance object
eventId — Number of event to signal
payload — Payload (optional) to pass to callback function
waitClear — If TRUE, have the NotifyDriver wait for acknowledgement back from the destination processor.
RETURNS
Notify status
DETAILS
This interface function is called by the Notify_sendEvent function. Notify_sendEvent does not provide any context protection for INotifyDriver_sendEvent, so appropriate measures must be taken within the driver itself.
 
NotifyDriverCirc_unregisterEvent()  // instance
index URL

Remove an event listener from an event

C synopsis target-domain
Void NotifyDriverCirc_unregisterEvent(NotifyDriverCirc_Handle handle, UInt32 eventId);
 
ARGUMENTS
handle — handle of a previously-created NotifyDriverCirc instance object
eventId — Number of event that is being unregistered
DETAILS
This driver function is called by the Notify_unregisterEvent function within the Notify module gate. Refer to it for more details.
Instance Convertors
index URL

C synopsis target-domain
INotifyDriver_Handle NotifyDriverCirc_Handle_upCast(NotifyDriverCirc_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
NotifyDriverCirc_Handle NotifyDriverCirc_Handle_downCast(INotifyDriver_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int NotifyDriverCirc_Object_count();
// The number of statically-created instance objects
 
NotifyDriverCirc_Handle NotifyDriverCirc_Object_get(NotifyDriverCirc_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
NotifyDriverCirc_Handle NotifyDriverCirc_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
NotifyDriverCirc_Handle NotifyDriverCirc_Object_next(NotifyDriverCirc_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle NotifyDriverCirc_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *NotifyDriverCirc_Handle_label(NotifyDriverCirc_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String NotifyDriverCirc_Handle_name(NotifyDriverCirc_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sdo/ipc/notifyDrivers/NotifyDriverCirc.xdc
var NotifyDriverCirc = xdc.useModule('ti.sdo.ipc.notifyDrivers.NotifyDriverCirc');
module-wide config parameters
    NotifyDriverCirc.A_notSupported// Assert raised when trying to use Notify_[enable/disable]Event with NotifyDriverCirc = Assert.Desc {
        msg: "A_notSupported: [enable/disable]Event not supported by NotifyDriverCirc"
    };
    NotifyDriverCirc.enableStats// Enable statistics for sending an event = Bool false;
    NotifyDriverCirc.numMsgs// The number of messages or slots in the circular buffer = UInt 32;
 
    NotifyDriverCirc.common$// Common module configuration parameters = Types.Common$ undefined;
    NotifyDriverCirc.rovViewInfo//  = ViewInfo.Instance ViewInfo.create;
per-instance config parameters
    var params = new NotifyDriverCirc.Params// Instance config-params object;
        params.cacheEnabled// Whether cache operations will be performed = Bool true;
        params.cacheLineSize// The cache line size of the shared memory = SizeT 128;
        params.intVectorId// Interrupt vector ID to be used by the driver = UInt ~1u;
        params.localIntId// Local interrupt ID for interrupt line = UInt -1u;
        params.remoteIntId// Remote interrupt ID for interrupt line = UInt -1u;
        params.remoteProcId// The MultiProc ID corresponding to the remote processor = UInt16 MultiProc.INVALIDID;
        params.sharedAddr// Address in shared memory where this instance will be placed = Ptr null;
 
 
config NotifyDriverCirc.A_notSupported  // module-wide
index URL

Assert raised when trying to use Notify_[enable/disable]Event with NotifyDriverCirc

XDCscript usage meta-domain
NotifyDriverCirc.A_notSupported = Assert.Desc {
    msg: "A_notSupported: [enable/disable]Event not supported by NotifyDriverCirc"
};
 
C SYNOPSIS
NotifyDriverCirc_A_notSupported
 
config NotifyDriverCirc.enableStats  // module-wide
index URL

Enable statistics for sending an event

XDCscript usage meta-domain
NotifyDriverCirc.enableStats = Bool false;
 
DETAILS
If this parameter is to 'TRUE' and 'waitClear' is also set to TRUE when calling (@link #sendEvent(), then the module keeps track of the number of times the processor spins waiting for an empty slot and the max amount of time it waits.
C SYNOPSIS
NotifyDriverCirc_enableStats
 
config NotifyDriverCirc.numMsgs  // module-wide
index URL

The number of messages or slots in the circular buffer

XDCscript usage meta-domain
NotifyDriverCirc.numMsgs = UInt 32;
 
DETAILS
This is use to determine the size of the put and get buffers. Each eventEntry is two 32bits wide, therefore the total size of each circular buffer is [numMsgs * sizeof(eventEntry)]. The total size of each buffer must be a multiple of the the cache line size. For example, if the cacheLineSize = 128 then numMsgs could be 16, 32, etc...
C SYNOPSIS
NotifyDriverCirc_numMsgs
 
metaonly config NotifyDriverCirc.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
NotifyDriverCirc.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 NotifyDriverCirc.rovViewInfo  // module-wide
index URL
XDCscript usage meta-domain
NotifyDriverCirc.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
// Instance config-params object
    params.cacheEnabled = Bool true;
    // Whether cache operations will be performed
    params.cacheLineSize = SizeT 128;
    // The cache line size of the shared memory
    params.intVectorId = UInt ~1u;
    // Interrupt vector ID to be used by the driver
    params.localIntId = UInt -1u;
    // Local interrupt ID for interrupt line
    params.remoteIntId = UInt -1u;
    // Remote interrupt ID for interrupt line
    params.remoteProcId = UInt16 MultiProc.INVALIDID;
    // The MultiProc ID corresponding to the remote processor
    params.sharedAddr = Ptr null;
    // Address in shared memory where this instance will be placed
 
config NotifyDriverCirc.cacheEnabled  // instance
index URL

Whether cache operations will be performed

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
  ...
params.cacheEnabled = Bool true;
 
DETAILS
If it is known that no cache operations are needed for this instance set this flag to FALSE. If sharedAddr lies within a shared region and the cache enabled setting for the region is FALSE, then the value specified here will be overriden to FALSE.
C SYNOPSIS
null
 
config NotifyDriverCirc.cacheLineSize  // instance
index URL

The cache line size of the shared memory

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
  ...
params.cacheLineSize = SizeT 128;
 
DETAILS
This value should be configured
C SYNOPSIS
null
 
config NotifyDriverCirc.intVectorId  // instance
index URL

Interrupt vector ID to be used by the driver

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
  ...
params.intVectorId = UInt ~1u;
 
DETAILS
This parameter is only used by C64x+ targets
C SYNOPSIS
null
 
config NotifyDriverCirc.localIntId  // instance
index URL

Local interrupt ID for interrupt line

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
  ...
params.localIntId = UInt -1u;
 
DETAILS
For devices that support multiple inter-processor interrupt lines, this configuration parameter allows selecting a specific line to use for receiving an interrupt. The value specified here corresponds to the incoming interrupt line on the local processor.
If this configuration is not set, a default interrupt id is typically chosen.
C SYNOPSIS
null
 
config NotifyDriverCirc.remoteIntId  // instance
index URL

Remote interrupt ID for interrupt line

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
  ...
params.remoteIntId = UInt -1u;
 
DETAILS
For devices that support multiple inter-processor interrupt lines, this configuration parameter allows selecting a specific line to use for receiving an interrupt. The value specified here corresponds to the incoming interrupt line on the remote processor.
If this configuration is not set, a default interrupt id is typically chosen.
C SYNOPSIS
null
 
config NotifyDriverCirc.remoteProcId  // instance
index URL

The MultiProc ID corresponding to the remote processor

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
  ...
params.remoteProcId = UInt16 MultiProc.INVALIDID;
 
DETAILS
This parameter must be set for every device. The MultiProc_getId call can be used to obtain a MultiProc id given the remote processor's name.
C SYNOPSIS
null
 
config NotifyDriverCirc.sharedAddr  // instance
index URL

Address in shared memory where this instance will be placed

XDCscript usage meta-domain
var params = new NotifyDriverCirc.Params;
  ...
params.sharedAddr = Ptr null;
 
DETAILS
Use sharedMemReq to determine the amount of shared memory required.
C SYNOPSIS
null
generated on Sat, 11 Feb 2012 00:38:04 GMT