module ti.ipc.transports.TransportRpmsg

Transport for MessageQ that uses vring structures

This is a ti.sdo.ipc.MessageQ transport that utilizes a pair of vrings (see Linux virtio) to communicate with a remote processor.
C synopsis target-domain sourced in ti/ipc/transports/TransportRpmsg.xdc
#include <ti/ipc/transports/TransportRpmsg.h>
Functions
Void
Void
Void
Void
Functions common to all IMessageQTransport modules
Bool 
Int 
Bool 
Void 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef Void 
typedef struct
typedef struct
typedef enum
typedef enum
typedef struct
Constants
 
 
enum TransportRpmsg_Reason

Reason for error function being called

C synopsis target-domain
typedef enum TransportRpmsg_Reason {
    TransportRpmsg_Reason_FAILEDPUT,
    TransportRpmsg_Reason_INTERNALERR,
    TransportRpmsg_Reason_PHYSICALERR,
    TransportRpmsg_Reason_FAILEDALLOC
} TransportRpmsg_Reason;
 
DETAILS
First field in the errFxn
 
enum TransportRpmsg_Status

Transport return values

C synopsis target-domain
typedef enum TransportRpmsg_Status {
    TransportRpmsg_S_SUCCESS,
    TransportRpmsg_E_FAIL,
    TransportRpmsg_E_ERROR
} TransportRpmsg_Status;
 
DETAILS
  • S_SUCCESS: Operation was successful
  • E_FAIL: Operation resulted in a failure
  • E_ERROR: Operation resulted in an error.
 
typedef TransportRpmsg_ErrFxn

Typedef for transport error callback function

C synopsis target-domain
typedef Void (*TransportRpmsg_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 TransportRpmsg_errFxn  // module-wide

Asynchronous error function for the transport module

C synopsis target-domain
extern const IMessageQTransport_ErrFxn TransportRpmsg_errFxn;
 
 
TransportRpmsg_setErrFxn()  // module-wide

Sets the asynchronous error function for the transport module

C synopsis target-domain
Void TransportRpmsg_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

C synopsis target-domain
Types_ModuleId TransportRpmsg_Module_id();
// Get this module's unique id
 
Bool TransportRpmsg_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle TransportRpmsg_Module_heap();
// The heap from which this module allocates memory
 
Bool TransportRpmsg_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 TransportRpmsg_Module_getMask();
// Returns the diagnostics mask for this module
 
Void TransportRpmsg_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct TransportRpmsg_Object TransportRpmsg_Object;
// Opaque internal representation of an instance object
 
typedef TransportRpmsg_Object *TransportRpmsg_Handle;
// Client reference to an instance object
 
typedef struct TransportRpmsg_Struct TransportRpmsg_Struct;
// Opaque client structure large enough to hold an instance object
 
TransportRpmsg_Handle TransportRpmsg_handle(TransportRpmsg_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
TransportRpmsg_Struct *TransportRpmsg_struct(TransportRpmsg_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct TransportRpmsg_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UInt priority;
    // Which priority messages should this transport manage
    Ptr sharedAddr;
    // Address in shared memory where this instance will be placed
} TransportRpmsg_Params;
 
Void TransportRpmsg_Params_init(TransportRpmsg_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config TransportRpmsg_Params.priority  // instance

Which priority messages should this transport manage

C synopsis target-domain
      ...
    UInt priority;
 
 
config TransportRpmsg_Params.sharedAddr  // instance

Address in shared memory where this instance will be placed

C synopsis target-domain
      ...
    Ptr sharedAddr;
 
Runtime Instance Creation

C synopsis target-domain
TransportRpmsg_Handle TransportRpmsg_create(UInt16 procId, const TransportRpmsg_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void TransportRpmsg_construct(TransportRpmsg_Struct *structP, UInt16 procId, const TransportRpmsg_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

C synopsis target-domain
Void TransportRpmsg_delete(TransportRpmsg_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void TransportRpmsg_destruct(TransportRpmsg_Struct *structP);
// Finalize the instance object inside the provided structure
 
TransportRpmsg_control()  // instance

Send a control command to the transport instance

C synopsis target-domain
Bool TransportRpmsg_control(TransportRpmsg_Handle handle, UInt cmd, UArg cmdArg);
 
ARGUMENTS
handle — handle of a previously-created TransportRpmsg 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.
 
TransportRpmsg_getStatus()  // instance

Status of a Transport instance

C synopsis target-domain
Int TransportRpmsg_getStatus(TransportRpmsg_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created TransportRpmsg instance object
RETURNS
Returns status of Transport instance
DETAILS
This function returns the status of the transport instance.
 
TransportRpmsg_put()  // instance

Put the message to the remote processor

C synopsis target-domain
Bool TransportRpmsg_put(TransportRpmsg_Handle handle, Ptr msg);
 
ARGUMENTS
handle — handle of a previously-created TransportRpmsg 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

C synopsis target-domain
IMessageQTransport_Handle TransportRpmsg_Handle_upCast(TransportRpmsg_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
TransportRpmsg_Handle TransportRpmsg_Handle_downCast(IMessageQTransport_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
 
ITransport_Handle TransportRpmsg_Handle_upCast2(TransportRpmsg_Handle handle);
// unconditionally move 2 levels up the inheritance hierarchy
 
TransportRpmsg_Handle TransportRpmsg_Handle_downCast2(ITransport_Handle handle);
// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int TransportRpmsg_Object_count();
// The number of statically-created instance objects
 
TransportRpmsg_Handle TransportRpmsg_Object_get(TransportRpmsg_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
TransportRpmsg_Handle TransportRpmsg_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
TransportRpmsg_Handle TransportRpmsg_Object_next(TransportRpmsg_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle TransportRpmsg_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *TransportRpmsg_Handle_label(TransportRpmsg_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String TransportRpmsg_Handle_name(TransportRpmsg_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/ipc/transports/TransportRpmsg.xdc
var TransportRpmsg = xdc.useModule('ti.ipc.transports.TransportRpmsg');
module-wide constants & types
        const TransportRpmsg.Reason_FAILEDPUT;
        const TransportRpmsg.Reason_INTERNALERR;
        const TransportRpmsg.Reason_PHYSICALERR;
        const TransportRpmsg.Reason_FAILEDALLOC;
 
        const TransportRpmsg.S_SUCCESS;
        const TransportRpmsg.E_FAIL;
        const TransportRpmsg.E_ERROR;
module-wide config parameters
 
per-instance config parameters
    var params = new TransportRpmsg.Params// Instance config-params object;
per-instance creation
    var inst = TransportRpmsg.create// Create an instance-object(UInt16 procId, params);
 
 
enum TransportRpmsg.Reason

Reason for error function being called

Configuration settings
values of type TransportRpmsg.Reason
    const TransportRpmsg.Reason_FAILEDPUT;
    const TransportRpmsg.Reason_INTERNALERR;
    const TransportRpmsg.Reason_PHYSICALERR;
    const TransportRpmsg.Reason_FAILEDALLOC;
 
DETAILS
First field in the errFxn
C SYNOPSIS
 
enum TransportRpmsg.Status

Transport return values

Configuration settings
values of type TransportRpmsg.Status
    const TransportRpmsg.S_SUCCESS;
    const TransportRpmsg.E_FAIL;
    const TransportRpmsg.E_ERROR;
 
DETAILS
  • S_SUCCESS: Operation was successful
  • E_FAIL: Operation resulted in a failure
  • E_ERROR: Operation resulted in an error.
C SYNOPSIS
 
config TransportRpmsg.errFxn  // module-wide

Asynchronous error function for the transport module

Configuration settings
TransportRpmsg.errFxn = Void(*)(IMessageQTransport.Reason,IMessageQTransport.Handle,Ptr,UArg) null;
 
C SYNOPSIS
 
metaonly config TransportRpmsg.common$  // module-wide

Common module configuration parameters

Configuration settings
TransportRpmsg.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 TransportRpmsg.Params;
// Instance config-params object
    params.priority = UInt 0;
    // Which priority messages should this transport manage
    params.sharedAddr = Ptr null;
    // Address in shared memory where this instance will be placed
 
config TransportRpmsg.Params.priority  // instance

Which priority messages should this transport manage

Configuration settings
var params = new TransportRpmsg.Params;
  ...
params.priority = UInt 0;
 
C SYNOPSIS
 
config TransportRpmsg.Params.sharedAddr  // instance

Address in shared memory where this instance will be placed

Configuration settings
var params = new TransportRpmsg.Params;
  ...
params.sharedAddr = Ptr null;
 
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new TransportRpmsg.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = TransportRpmsg.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 Fri, 06 Mar 2015 20:50:00 GMT