module ti.sdo.ipc.family.vayu.NotifySetup
index URL

Notify driver setup proxy for Vayu

This module creates and registers the IPC Notify drivers for the Vayu device family. There are two types of notify drivers available: 1) shared memory driver, and 2) mailbox driver. Use the connections configuration parameter to select which driver to use for communicating with each remote processor. [ more ... ]
C synopsis target-domain sourced in ti/sdo/ipc/family/vayu/NotifySetup.xdc
#include <ti/sdo/ipc/family/vayu/NotifySetup.h>
Functions common to all INotifySetup modules
Int 
NotifySetup_attach// Function that will be called in Notify_attach(UInt16 remoteProcId, Ptr sharedAddr);
UInt16 
NotifySetup_numIntLines// Returns number of interrupt lines to the processor(UInt16 remoteProcId);
SizeT 
NotifySetup_sharedMemReq// Shared Memory Required for a single notification line(UInt16 remoteProcId, Ptr sharedAddr);
Functions common to all target modules
NotifySetup_Module_getMask// Returns the diagnostics mask for this module, NotifySetup_Module_hasMask// Test whether this module has a diagnostics mask, NotifySetup_Module_heap// The heap from which this module allocates memory, NotifySetup_Module_id// Get this module's unique id, NotifySetup_Module_setMask// Set the diagnostics mask for this module, NotifySetup_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct
NotifySetup_Connection// Define a notify driver connection ...
typedef enum
NotifySetup_Driver// Define the available notify drivers ...
 
DETAILS
This module creates and registers the IPC Notify drivers for the Vayu device family. There are two types of notify drivers available: 1) shared memory driver, and 2) mailbox driver. Use the connections configuration parameter to select which driver to use for communicating with each remote processor.
The shared memory notify driver is the default driver. It implements the full Notify API set. This driver uses memory for passing the notify payload between processors. The memory is allocated from SharedRegion #0.
The mailbox notify driver uses hardware FIFOs for passing the notify payload between processors. No shared memory is required. However, this driver does not implement the full Notify API set. For example, the Notify_sendEvent() API will never return Notify_E_EVTNOTREGISTERED because it does not track this information.
When configuring the notify driver, you specify which driver to use for communicating to each remote processor. If not configured, the shared memory driver will be used by default. Both sides of each connection must use the same driver. This is an easy mistake to make and there is no way to check this.
This module is primarily used by notify driver authors. It is not expected that any application would ever use this module in its runtime code. The typical use of this module is simply to configure which notify driver to use. See the following example for details.
CONFIGURATION EXAMPLE
The following is a three processor example: HOST DSP1 EVE1. In this example, HOST and DSP1 will communicate using the shared memory driver and DSP1 and EVE1 will communicate using the mailbox driver. This example explicitly configures the shared memory driver for HOST and DSP1, but this is strictly not necessary. If left unconfigured, the shared memory driver would be used as the default. Also, the connection between HOST and EVE1 is left undefined as we don't expect to use this connection.
Notice that each connection configuration specifies the remote processor name and the driver type. This is how the local processor declares which driver it will use when communicating to that remote processor. The corresponding configuration on the remote processor must be complimentary.
Add the following to your HOST configuration script.
  // configure the notify driver
  var NotifySetup = xdc.useModule('ti.sdo.ipc.family.vayu.NotifySetup');

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_SHAREDMEMORY,
          procName: "DSP1"
      })
 );
Add the following to your DSP1 configuration script.
  // configure the notify driver
  var NotifySetup = xdc.useModule('ti.sdo.ipc.family.vayu.NotifySetup');

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_SHAREDMEMORY,
          procName: "HOST"
      })
 );

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_MAILBOX,
          procName: "EVE1"
      })
  );
Add the following to your EVE1 configuration script.
  // configure the notify driver
  var NotifySetup = xdc.useModule('ti.sdo.ipc.family.vayu.NotifySetup');

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_MAILBOX,
          procName: "DSP1"
      })
 );
 
enum NotifySetup_Driver
index URL

Define the available notify drivers

C synopsis target-domain
typedef enum NotifySetup_Driver {
    NotifySetup_Driver_SHAREDMEMORY,
    // shared memory driver
    NotifySetup_Driver_MAILBOX
    // hardware mailbox driver
} NotifySetup_Driver;
 
DETAILS
For any given connection to a remote processor, one of the following notify driver types may be used. Each driver has different characteristics and system requirements.
Driver_SHAREDMEMORY
This driver uses shared memory for passing the notify payload between processors. Additional state is also stored in the shared memory.

There is a separate, cache-aligned block of memory for each event number. This is necessary to maintain cache coherency. However, this requires a non-trivial amount of memory.

Driver_MAILBOX
This driver uses a hardware FIFO (provided by the hardware mailbox) to pass the notify payload between processors. No shared memory is required by this driver.

This driver does not support the full Notify API set. This driver has lower delivery latency when compard to the shared memory driver.

 
struct NotifySetup_Connection
index URL

Define a notify driver connection

C synopsis target-domain
typedef struct NotifySetup_Connection {
    NotifySetup_Driver driver;
    // notify driver
    String procName;
    // remote processor name
} NotifySetup_Connection;
 
FIELDS
driver — The driver to be used for this connection. See the Driver enumeration for details.
procName — The name of the remote processor for the given connection.
DETAILS
Each IPC connection is defined by two end-points: the local processor and the remote processor. Each connection supports only one type of notify driver. In other words, both ends of the connection must configure the same notify driver type.
However, when a processor has multiple connections (when communicating with multiple remote processors), each connection is configured independently. Therefore, different notify drivers may be used for different connections. Currently, IPC supports only one connection for each remote processor.
The configuration for a given connection must be coordinated with the remote processor. Each processor is only able to configure its local end-point for the connection. It is important that the remote processor use the same notify driver for the connection.
 
NotifySetup_attach()  // module-wide
index URL

Function that will be called in Notify_attach

C synopsis target-domain
Int NotifySetup_attach(UInt16 remoteProcId, Ptr sharedAddr);
 
 
NotifySetup_numIntLines()  // module-wide
index URL

Returns number of interrupt lines to the processor

C synopsis target-domain
UInt16 NotifySetup_numIntLines(UInt16 remoteProcId);
 
 
NotifySetup_sharedMemReq()  // module-wide
index URL

Shared Memory Required for a single notification line

C synopsis target-domain
SizeT NotifySetup_sharedMemReq(UInt16 remoteProcId, Ptr sharedAddr);
 
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId NotifySetup_Module_id();
// Get this module's unique id
 
Bool NotifySetup_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle NotifySetup_Module_heap();
// The heap from which this module allocates memory
 
Bool NotifySetup_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 NotifySetup_Module_getMask();
// Returns the diagnostics mask for this module
 
Void NotifySetup_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in ti/sdo/ipc/family/vayu/NotifySetup.xdc
var NotifySetup = xdc.useModule('ti.sdo.ipc.family.vayu.NotifySetup');
module-wide constants & types
    values of type NotifySetup.Driver// Define the available notify drivers
        const NotifySetup.Driver_SHAREDMEMORY// shared memory driver;
        const NotifySetup.Driver_MAILBOX// hardware mailbox driver;
 
    var obj = new NotifySetup.Connection// Define a notify driver connection;
        obj.driver// notify driver = NotifySetup.Driver  ...
        obj.procName// remote processor name = String  ...
module-wide config parameters
    NotifySetup.common$// Common module configuration parameters = Types.Common$ undefined;
    NotifySetup.connections// Configure the notify driver for each given connection = NotifySetup.Connection[length] undefined;
 
 
enum NotifySetup.Driver
index URL

Define the available notify drivers

Configuration settings
values of type NotifySetup.Driver
    const NotifySetup.Driver_SHAREDMEMORY;
    // shared memory driver
    const NotifySetup.Driver_MAILBOX;
    // hardware mailbox driver
 
DETAILS
For any given connection to a remote processor, one of the following notify driver types may be used. Each driver has different characteristics and system requirements.
Driver_SHAREDMEMORY
This driver uses shared memory for passing the notify payload between processors. Additional state is also stored in the shared memory.

There is a separate, cache-aligned block of memory for each event number. This is necessary to maintain cache coherency. However, this requires a non-trivial amount of memory.

Driver_MAILBOX
This driver uses a hardware FIFO (provided by the hardware mailbox) to pass the notify payload between processors. No shared memory is required by this driver.

This driver does not support the full Notify API set. This driver has lower delivery latency when compard to the shared memory driver.

C SYNOPSIS
NotifySetup_Driver
 
struct NotifySetup.Connection
index URL

Define a notify driver connection

Configuration settings
var obj = new NotifySetup.Connection;
 
    obj.driver = NotifySetup.Driver  ...
    // notify driver
    obj.procName = String  ...
    // remote processor name
 
FIELDS
driver — The driver to be used for this connection. See the Driver enumeration for details.
procName — The name of the remote processor for the given connection.
DETAILS
Each IPC connection is defined by two end-points: the local processor and the remote processor. Each connection supports only one type of notify driver. In other words, both ends of the connection must configure the same notify driver type.
However, when a processor has multiple connections (when communicating with multiple remote processors), each connection is configured independently. Therefore, different notify drivers may be used for different connections. Currently, IPC supports only one connection for each remote processor.
The configuration for a given connection must be coordinated with the remote processor. Each processor is only able to configure its local end-point for the connection. It is important that the remote processor use the same notify driver for the connection.
C SYNOPSIS
NotifySetup_Connection
 
metaonly config NotifySetup.common$  // module-wide
index URL

Common module configuration parameters

Configuration settings
NotifySetup.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 NotifySetup.connections  // module-wide
index URL

Configure the notify driver for each given connection

Configuration settings
NotifySetup.connections = NotifySetup.Connection[length] undefined;
 
DETAILS
Use this configuration parameter to define which notify driver is to be used when communicating with remote processors. Create one entry in this array for each connection. Each entry you create, defines the local end-point of the connection. The remote processor must have a complimentary entry in its connections array.
Any connection which is undefined, will use the shared memory notify driver. It is not necessary to define all connections, just the ones which will not use the default.
To define a local end-point connection, establish a reference to this module and add a new entry to this array.
The following example show how to setup the mailbox driver for communicating from DSP1 to EVE1 and EVE2.
Add the following to your DSP1 configuration script.
  // configure the notify driver
  var NotifySetup = xdc.useModule('ti.sdo.ipc.family.vayu.NotifySetup');

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_MAILBOX,
          procName: "EVE1"
      })
 );

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_MAILBOX,
          procName: "EVE2"
      })
  );
Add the following to your EVE1 configuration script.
  // configure the notify driver
  var NotifySetup = xdc.useModule('ti.sdo.ipc.family.vayu.NotifySetup');

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_MAILBOX,
          procName: "DSP1"
      })
 );
Add the following to your EVE2 configuration script.
  // configure the notify driver
  var NotifySetup = xdc.useModule('ti.sdo.ipc.family.vayu.NotifySetup');

  NotifySetup.connections.$add(
      new NotifySetup.Connection({
          driver: NotifySetup.Driver_MAILBOX,
          procName: "DSP1"
      })
 );
generated on Fri, 21 Aug 2015 19:35:59 GMT