module ti.sdo.ipc.family.f28m35x.TransportCirc

Transport for MessageQ that uses a circular buffer

C synopsis
Individual elements
XDCscript usage
Individual elements

This is a ti.sdo.ipc.MessageQ transport that utilizes shared memory for passing messages between multiple processors. [ more ... ]

C synopsis target-domain sourced in ti/sdo/ipc/family/f28m35x/TransportCirc.xdc

#include <ti/sdo/ipc/family/f28m35x/TransportCirc.h>

Functions
Void	TransportCirc_close// Close an opened instance(TransportCirc_Handle *handle);
Void	TransportCirc_construct// Initialize a new instance object inside the provided structure(TransportCirc_Struct structP, UInt16 procId, const TransportCirc_Params params, Error_Block *eb);
TransportCirc_Handle	TransportCirc_create// Allocate and initialize a new instance object and return its handle(UInt16 procId, const TransportCirc_Params params, Error_Block eb);
Void	TransportCirc_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(TransportCirc_Handle *handleP);
Void	TransportCirc_destruct// Finalize the instance object inside the provided structure(TransportCirc_Struct *structP);
Void	TransportCirc_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(TransportCirc_Params *params);
Functions common to all IMessageQTransport modules
Bool	TransportCirc_control// Send a control command to the transport instance(TransportCirc_Handle handle, UInt cmd, UArg cmdArg);
Int	TransportCirc_getStatus// Status of a Transport instance(TransportCirc_Handle handle);
Bool	TransportCirc_put// Put the message to the remote processor(TransportCirc_Handle handle, Ptr msg);
Void	TransportCirc_setErrFxn// Sets the asynchronous error function for the transport module(IMessageQTransport_ErrFxn errFxn);
Functions common to all target instances
	TransportCirc_handle// Convert this instance structure pointer into an instance handle, TransportCirc_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, TransportCirc_Handle_label// The label associated with this instance object, TransportCirc_Handle_name// The name of this instance object, TransportCirc_Handle_upCast// unconditionally move one level up the inheritance hierarchy, TransportCirc_Object_count// The number of statically-created instance objects, TransportCirc_Object_first// The handle of the first dynamically-created instance object, or NULL, TransportCirc_Object_get// The handle of the i-th statically-created instance object (array == NULL), TransportCirc_Object_heap// The heap used to allocate dynamically-created instance objects, TransportCirc_Object_next// The handle of the next dynamically-created instance object, or NULL, TransportCirc_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	TransportCirc_Module_getMask// Returns the diagnostics mask for this module, TransportCirc_Module_hasMask// Test whether this module has a diagnostics mask, TransportCirc_Module_heap// The heap from which this module allocates memory, TransportCirc_Module_id// Get this module's unique id, TransportCirc_Module_setMask// Set the diagnostics mask for this module, TransportCirc_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void	(*TransportCirc_ErrFxn// Typedef for transport error callback function)(IMessageQTransport_Reason,IMessageQTransport_Handle,Ptr,UArg);
typedef TransportCirc_Object *	TransportCirc_Handle// Client reference to an instance object;
typedef struct	TransportCirc_Object// Opaque internal representation of an instance object TransportCirc_Object;
typedef struct	TransportCirc_Params// Instance config-params structure ...
typedef enum	TransportCirc_Reason// Reason for error function being called ...
typedef enum	TransportCirc_Status// Transport return values ...
typedef struct	TransportCirc_Struct// Opaque client structure large enough to hold an instance object TransportCirc_Struct;
Constants
extern const IMessageQTransport_ErrFxn	TransportCirc_errFxn// Asynchronous error function for the transport module;

DETAILS

This is a ti.sdo.ipc.MessageQ transport that utilizes shared memory for passing messages between multiple processors.

The transport utilizes shared memory in the manner indicated by the following diagram.

  
  NOTE: Processor '0' corresponds to the M3 and '1' corresponds to the C28

 sharedAddr -> --------------------------- bytes
               |  entry0  (0) [Put]      | 4  
               |  entry1  (0)            | 4
               |  ...                    | 
               |  entryN  (0)            | 4
               |                         | 
               |-------------------------|
               |  putWriteIndex (0)      | 4
               |                         |
               |-------------------------|
               |  getReadIndex (1)       | 4
               |                         |
               |-------------------------|
               |  entry0  (1) [Get]      | 4  
               |  entry1  (1)            | 4
               |  ...                    | 
               |  entryN  (1)            | 4
               |                         |
               |-------------------------|
               |  putWriteIndex (1)      | 4
               |                         |
               |-------------------------|
               |  getReadIndex (0)       | 4
               |                         |
               |-------------------------|


  Legend:
  (0), (1) : belongs to the respective processor
  (N)      : length of buffer

enum TransportCirc_Reason

index URL

Reason for error function being called

C synopsis target-domain

typedef enum TransportCirc_Reason {

TransportCirc_Reason_FAILEDPUT,

TransportCirc_Reason_INTERNALERR,

TransportCirc_Reason_PHYSICALERR,

TransportCirc_Reason_FAILEDALLOC

} TransportCirc_Reason;

DETAILS

First field in the errFxn

enum TransportCirc_Status

index URL

Transport return values

C synopsis target-domain

typedef enum TransportCirc_Status {

TransportCirc_S_SUCCESS,

TransportCirc_E_FAIL,

TransportCirc_E_ERROR

} TransportCirc_Status;

DETAILS

S_SUCCESS: Operation was successful
E_FAIL: Operation resulted in a failure
E_ERROR: Operation resulted in an error.

typedef TransportCirc_ErrFxn

index URL

Typedef for transport error callback function

C synopsis target-domain

typedef Void (*TransportCirc_ErrFxn)(IMessageQTransport_Reason,IMessageQTransport_Handle,Ptr,UArg);

DETAILS

First parameter: Why the error function is being called.

Second parameter: Handle of transport that had the error. NULL denotes that it is a system error, not a specific transport.

Third parameter: Pointer to the message. This is only valid for Reason_FAILEDPUT.

Fourth parameter: Transport specific information. Refer to individual transports for more details.

config TransportCirc_errFxn // module-wide

index URL

Asynchronous error function for the transport module

C synopsis target-domain

extern const IMessageQTransport_ErrFxn TransportCirc_errFxn;

TransportCirc_close() // module-wide

index URL

Close an opened instance

C synopsis target-domain

Void TransportCirc_close(TransportCirc_Handle *handle);

ARGUMENTS

handle — handle that is returned from an openByAddr

DETAILS

Closing an instance will free local memory consumed by the opened instance. Instances that are opened should be closed before the instance is deleted.

TransportCirc_setErrFxn() // module-wide

index URL

Sets the asynchronous error function for the transport module

C synopsis target-domain

Void TransportCirc_setErrFxn(IMessageQTransport_ErrFxn errFxn);

ARGUMENTS

errFxn — Function that is called when an asynchronous error occurs.

DETAILS

This API allows the user to set the function that will be called in case of an asynchronous error by the transport.

Module-Wide Built-Ins

index URL

C synopsis target-domain

Types_ModuleId TransportCirc_Module_id();

// Get this module's unique id

Bool TransportCirc_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle TransportCirc_Module_heap();

// The heap from which this module allocates memory

Bool TransportCirc_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 TransportCirc_Module_getMask();

// Returns the diagnostics mask for this module

Void TransportCirc_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct TransportCirc_Object TransportCirc_Object;

// Opaque internal representation of an instance object

typedef TransportCirc_Object *TransportCirc_Handle;

// Client reference to an instance object

typedef struct TransportCirc_Struct TransportCirc_Struct;

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

TransportCirc_Handle TransportCirc_handle(TransportCirc_Struct *structP);

// Convert this instance structure pointer into an instance handle

TransportCirc_Struct *TransportCirc_struct(TransportCirc_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

typedef struct TransportCirc_Params {

// Instance config-params structure

IInstance_Params *instance;

// Common per-instance configs

UInt priority;

// Which priority messages should this transport manage

Ptr readAddr;

// Physical address of the read address in shared memory

Ptr writeAddr;

// Physical address of the write address in shared memory

} TransportCirc_Params;

Void TransportCirc_Params_init(TransportCirc_Params *params);

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

config TransportCirc_priority // instance

index URL

Which priority messages should this transport manage

C synopsis target-domain

struct TransportCirc_Params {

...

UInt priority;

config TransportCirc_readAddr // instance

index URL

Physical address of the read address in shared memory

C synopsis target-domain

struct TransportCirc_Params {

...

Ptr readAddr;

DETAILS

This address should be specified in the local processor's memory space. It must point to the same physical write address of the remote processor its communicating with.

config TransportCirc_writeAddr // instance

index URL

Physical address of the write address in shared memory

C synopsis target-domain

struct TransportCirc_Params {

...

Ptr writeAddr;

DETAILS

This address should be specified in the local processor's memory space. It must point to the same physical read address of the remote processor its communicating with.

Instance Creation

index URL

C synopsis target-domain

TransportCirc_Handle TransportCirc_create(UInt16 procId, const TransportCirc_Params *params, Error_Block *eb);

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

Void TransportCirc_construct(TransportCirc_Struct *structP, UInt16 procId, const TransportCirc_Params *params, Error_Block *eb);

// Initialize a new instance object inside the provided structure

ARGUMENTS

procId — Remote processor id that this instance will communicate with.

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)

DETAILS

This function creates a transport instance. The transport is responsible for registering with MessageQ via the ti.sdo.ipc.MessageQ.registerTransport API.

Instance Deletion

index URL

C synopsis target-domain

Void TransportCirc_delete(TransportCirc_Handle *handleP);

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

Void TransportCirc_destruct(TransportCirc_Struct *structP);

// Finalize the instance object inside the provided structure

TransportCirc_control() // instance

index URL

Send a control command to the transport instance

C synopsis target-domain

Bool TransportCirc_control(TransportCirc_Handle handle, UInt cmd, UArg cmdArg);

ARGUMENTS

handle — handle of a previously-created TransportCirc instance object

cmd — Requested command

cmdArgs — Accompanying field for the command. This is command specific.

RETURNS

TRUE denotes acceptance of the command. FALSE denotes failure of the command.

DETAILS

This is function allows transport to specify control commands. Refer to individual transport implementions for more details.

TransportCirc_getStatus() // instance

index URL

Status of a Transport instance

C synopsis target-domain

Int TransportCirc_getStatus(TransportCirc_Handle handle);

ARGUMENTS

handle — handle of a previously-created TransportCirc instance object

RETURNS

Returns status of Transport instance

DETAILS

This function returns the status of the transport instance.

TransportCirc_put() // instance

index URL

Put the message to the remote processor

C synopsis target-domain

Bool TransportCirc_put(TransportCirc_Handle handle, Ptr msg);

ARGUMENTS

handle — handle of a previously-created TransportCirc instance object

msg — Pointer the message to be sent

RETURNS

TRUE denotes acceptance of the message to be sent. FALSE denotes the message could not be sent.

DETAILS

If the transport can accept the message, it returns TRUE. Accepting a message does not mean that it is transmitted. It simply means that the transport should be able to send the message. If the actual transfer fails, the transport calls the {@#ErrFxn} (assuming it is set up via the {@#setErrFxn} API. If the {@#ErrFxn} is not set, the message is dropped. (also...should an error be raised or just System_printf?).

If the transport cannot send the message, it returns FALSE and a filled in Error_Block. The caller still owns the message.

Instance Convertors

index URL

C synopsis target-domain

IMessageQTransport_Handle TransportCirc_Handle_upCast(TransportCirc_Handle handle);

// unconditionally move one level up the inheritance hierarchy

TransportCirc_Handle TransportCirc_Handle_downCast(IMessageQTransport_Handle handle);

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

Instance Built-Ins

index URL

C synopsis target-domain

Int TransportCirc_Object_count();

// The number of statically-created instance objects

TransportCirc_Handle TransportCirc_Object_get(TransportCirc_Object *array, Int i);

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

TransportCirc_Handle TransportCirc_Object_first();

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

TransportCirc_Handle TransportCirc_Object_next(TransportCirc_Handle handle);

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

IHeap_Handle TransportCirc_Object_heap();

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

Types_Label *TransportCirc_Handle_label(TransportCirc_Handle handle, Types_Label *buf);

// The label associated with this instance object

String TransportCirc_Handle_name(TransportCirc_Handle handle);

// The name of this instance object

XDCscript usage meta-domain sourced in ti/sdo/ipc/family/f28m35x/TransportCirc.xdc

var TransportCirc = xdc.useModule('ti.sdo.ipc.family.f28m35x.TransportCirc');

module-wide constants & types

values of type TransportCirc.Reason// Reason for error function being called

const TransportCirc.Reason_FAILEDPUT;

const TransportCirc.Reason_INTERNALERR;

const TransportCirc.Reason_PHYSICALERR;

const TransportCirc.Reason_FAILEDALLOC;

values of type TransportCirc.Status// Transport return values

const TransportCirc.S_SUCCESS;

const TransportCirc.E_FAIL;

const TransportCirc.E_ERROR;

module-wide config parameters

TransportCirc.errFxn// Asynchronous error function for the transport module = Void(*)(IMessageQTransport.Reason,IMessageQTransport.Handle,Ptr,UArg) null;

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

TransportCirc.rovViewInfo// = ViewInfo.Instance ViewInfo.create;

per-instance config parameters

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

params.priority// Which priority messages should this transport manage = UInt 0;

params.readAddr// Physical address of the read address in shared memory = Ptr null;

params.writeAddr// Physical address of the write address in shared memory = Ptr null;

per-instance creation

var inst = TransportCirc.create// Create an instance-object(UInt16 procId, params);

enum TransportCirc.Reason

index URL

Reason for error function being called

XDCscript usage meta-domain

values of type TransportCirc.Reason

const TransportCirc.Reason_FAILEDPUT;

const TransportCirc.Reason_INTERNALERR;

const TransportCirc.Reason_PHYSICALERR;

const TransportCirc.Reason_FAILEDALLOC;

DETAILS

First field in the errFxn

C SYNOPSIS

TransportCirc_Reason

enum TransportCirc.Status

index URL

Transport return values

XDCscript usage meta-domain

values of type TransportCirc.Status

const TransportCirc.S_SUCCESS;

const TransportCirc.E_FAIL;

const TransportCirc.E_ERROR;

DETAILS

S_SUCCESS: Operation was successful
E_FAIL: Operation resulted in a failure
E_ERROR: Operation resulted in an error.

C SYNOPSIS

TransportCirc_Status

config TransportCirc.errFxn // module-wide

index URL

Asynchronous error function for the transport module

XDCscript usage meta-domain

TransportCirc.errFxn = Void(*)(IMessageQTransport.Reason,IMessageQTransport.Handle,Ptr,UArg) null;

C SYNOPSIS

TransportCirc_errFxn

metaonly config TransportCirc.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

TransportCirc.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 TransportCirc.rovViewInfo // module-wide

index URL

XDCscript usage meta-domain

TransportCirc.rovViewInfo = ViewInfo.Instance ViewInfo.create;

Instance Config Parameters

index URL

XDCscript usage meta-domain

var params = new TransportCirc.Params;

// Instance config-params object

params.priority = UInt 0;

// Which priority messages should this transport manage

params.readAddr = Ptr null;

// Physical address of the read address in shared memory

params.writeAddr = Ptr null;

// Physical address of the write address in shared memory

config TransportCirc.priority // instance

index URL

Which priority messages should this transport manage

XDCscript usage meta-domain

var params = new TransportCirc.Params;

...

params.priority = UInt 0;

C SYNOPSIS

null

config TransportCirc.readAddr // instance

index URL

Physical address of the read address in shared memory

XDCscript usage meta-domain

var params = new TransportCirc.Params;

...

params.readAddr = Ptr null;

DETAILS

This address should be specified in the local processor's memory space. It must point to the same physical write address of the remote processor its communicating with.

C SYNOPSIS

null

config TransportCirc.writeAddr // instance

index URL

Physical address of the write address in shared memory

XDCscript usage meta-domain

var params = new TransportCirc.Params;

...

params.writeAddr = Ptr null;

DETAILS

This address should be specified in the local processor's memory space. It must point to the same physical read address of the remote processor its communicating with.

C SYNOPSIS

null

Instance Creation

index URL

XDCscript usage meta-domain

var params = new TransportCirc.Params;

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = TransportCirc.create(UInt16 procId, params);

// Create an instance-object

ARGUMENTS

procId — Remote processor id that this instance will communicate with.

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)

DETAILS

This function creates a transport instance. The transport is responsible for registering with MessageQ via the ti.sdo.ipc.MessageQ.registerTransport API.

generated on Sat, 11 Feb 2012 00:37:53 GMT