Files
file	ipc.h
	IPC Low Level Driver API/interface data types file.

Data Structures
struct	Ipc_InitPrms
	IPC initialization parameters. More...

struct	RPMessage_Params
	Parameter structure for creating RPMessage endpoints. More...

struct	RPMessage_Stats
	Storage structure for profiling the behavior of IPC. More...

Typedefs
typedef struct RPMessage_Object_s *	RPMessage_Handle
	RPMessage_Handle type. More...

typedef void(*	RPMessage_Callback) (RPMessage_Handle handle, void arg, void data, uint16_t len, uint32_t src)
	RPMessage_Callback. More...

typedef void(*	RPMessage_ProcCallback) (uint32_t srcEndPt, uint32_t srcProcId, uint32_t destEndPt, void *arg)

Functions
void	IpcInitPrms_init (uint32_t instId, Ipc_InitPrms *initPrms)
	Initialize IPC init params. More...

int32_t	Ipc_init (const Ipc_InitPrms *cfg)
	Initialize IPC module. More...

int32_t	Ipc_deinit (void)
	De Initialize IPC module. More...

uint32_t	RPMessage_getMessageBufferSize (void)
	Returns Message Buffer Size. More...

uint32_t	RPMessage_getObjMemRequired (void)
	Returns local memory for RPMessage Object. More...

int32_t	RPMessage_init (RPMessage_Params *params)
	Initialize RPMessage Module. More...

int32_t	RPMessage_lateInit (uint32_t proc)
	Add a proc to RPMessage Module. More...

void	RPMessage_deInit (void)
	Tear down the RPMessage Module. The module API should not be used after this is called. More...

int32_t	RPMessageParams_init (RPMessage_Params *params)
	Initialize an RPMessage_Params structure to default values. More...

RPMessage_Handle	RPMessage_create (RPMessage_Params params, uint32_t endPt)
	Create a endpoint instance for receiving. More...

int32_t	RPMessage_setCallback (RPMessage_Handle handle, RPMessage_Callback cb, void *arg)
	Sets callback. More...

int32_t	RPMessage_setCallbackForProc (RPMessage_ProcCallback cb, void *arg, int32_t priority)
	Sets callback. More...

int32_t	RPMessage_deleteCallbackForProc (void)
	Deletes callback. More...

int32_t	RPMessage_recv (RPMessage_Handle handle, void data, uint16_t len, uint32_t rplyEndPt, uint32_t fromProcId, uint32_t timeout)
	Receives a message from an endpoint instance. More...

int32_t	RPMessage_recvNb (RPMessage_Handle handle, void data, uint16_t len, uint32_t rplyEndPt, uint32_t fromProcId)
	A non blocking API to receive message. More...

int32_t	RPMessage_send (RPMessage_Handle handle, uint32_t dstProc, uint32_t dstEndPt, uint32_t srcEndPt, void *data, uint16_t len)
	Sends data to a remote processor. More...

int32_t	RPMessage_delete (RPMessage_Handle *handlePtr)
	Delete an endpoint instance. More...

void	RPMessage_unblock (RPMessage_Handle handle)
	Unblocks an RPMessage_recv() More...

int32_t	RPMessage_getRemoteEndPt (uint32_t currProcId, const char name, uint32_t remoteProcId, uint32_t *remoteEndPt, uint32_t timeout)
	Wait for an endpoint to become available on another processor. More...

int32_t	RPMessage_getRemoteEndPtToken (uint32_t currProcId, const char name, uint32_t remoteProcId, uint32_t *remoteEndPt, uint32_t timeout, uint32_t token)

void	RPMessage_unblockGetRemoteEndPt (uint32_t token)
	Unblocks an RPMessage_getRemoteEndPtToken() call. More...

int32_t	RPMessage_announce (uint32_t remoteProcId, uint32_t endPt, const char *name)
	Annouce the name of an endpoint and that it is ready to to receive messages. More...

void	RPMessage_getStats (RPMessage_Stats *stats)
	Copies the current statistics of the IPC driver into the structure provided. More...

void	Ipc_mailboxEnableNewMsgInt (uint16_t selfId, uint16_t remoteProcId)
	API Mailbox Enable new MSG interrupt for a given remote processor. More...

void	Ipc_mailboxDisableNewMsgInt (uint16_t selfId, uint16_t remoteProcId)
	API Mailbox Disable new MSG interrupt for a given remote processor. More...

Variables
uint32_t	Ipc_InitPrms::instId

Ipc_PhyToVirtFxn	Ipc_InitPrms::phyToVirtFxn

Ipc_VirtToPhyFxn	Ipc_InitPrms::virtToPhyFxn

Ipc_OsalPrms	Ipc_InitPrms::osalPrms

Ipc_NewMsgReceivedFxn	Ipc_InitPrms::newMsgFxn

Ipc_RpMboxMsgFxn	Ipc_InitPrms::rpMboxMsgFxn

Ipc_PrintFxn	Ipc_InitPrms::printFxn

uint32_t	RPMessage_Params::requestedEndpt

uint32_t	RPMessage_Params::numBufs

void *	RPMessage_Params::buf

uint32_t	RPMessage_Params::bufSize

void *	RPMessage_Params::stackBuffer

uint32_t	RPMessage_Params::stackSize

uint32_t	RPMessage_Stats::recvTotalMessages

uint32_t	RPMessage_Stats::recvMessagesLiveTransferred

uint32_t	RPMessage_Stats::recvMessagesQueued

uint32_t	RPMessage_Stats::recvBufferAllocFailures

uint32_t	RPMessage_Stats::recvEndpointFindFails

Detailed Description

This is IPC's top level include for applications

Typedef Documentation

◆ RPMessage_Handle

typedef struct RPMessage_Object_s* RPMessage_Handle

RPMessage_Handle type.

◆ RPMessage_Callback

typedef void(* RPMessage_Callback) (RPMessage_Handle handle, void *arg, void *data, uint16_t len, uint32_t src)

RPMessage_Callback.

Parameters

RPMessage_Handle	[IN]
arg	[IN] void* arguments to function
data	[IN] data pointer
len	[IN] length of data
src	[IN] source

◆ RPMessage_ProcCallback

typedef void(* RPMessage_ProcCallback) (uint32_t srcEndPt, uint32_t srcProcId, uint32_t destEndPt, void *arg)

Function Documentation

◆ IpcInitPrms_init()

void IpcInitPrms_init	(	uint32_t	instId,
		Ipc_InitPrms *	initPrms
	)

Initialize IPC init params.

        Can be called to initialize the #Ipc_InitPrms to the default
        values.

Parameters

instId	[IN] Ipc_InstanceId. Only 1 instance is supported in this implementation. The value shall be 0
initPrms	[IN] Pointer to param structure to be initialized. When building for tirtos environment, it will be filled with tirtos-compatible definitions. When using the ipc_baremetal implementation, it will be filled with baremetal definitions.

Returns: IPC_SOK or IPC_EINVALID_PARAMS or IPC_EFAIL

◆ Ipc_init()

int32_t Ipc_init ( const Ipc_InitPrms * cfg )

Initialize IPC module.

        Very first API to be invoked to initialize internal data
        structure and utilities required.

Parameters

cfg	[IN] Initialization parameters. May be NULL in order to use the module default implementation. May be non-NULL in order to use user-specified implementation.

Returns: IPC_SOK or IPC_EINVALID_PARAMS or IPC_EFAIL

◆ Ipc_deinit()

int32_t Ipc_deinit ( void )

De Initialize IPC module.

        Very last API to be invoked to de initialize.

Returns: IPC_SOK

◆ RPMessage_getMessageBufferSize()

uint32_t RPMessage_getMessageBufferSize ( void )

Returns Message Buffer Size.

◆ RPMessage_getObjMemRequired()

uint32_t RPMessage_getObjMemRequired ( void )

Returns local memory for RPMessage Object.

◆ RPMessage_init()

int32_t RPMessage_init ( RPMessage_Params * params )

Initialize RPMessage Module.

Can be called from Main or Task context. Must be called before calling any other RPMessage function;

Parameters

params [IN] Address of the RPMessage_Params structure used to create the RPMessage

Returns: IPC_SOK or IPC_EFAIL

◆ RPMessage_lateInit()

int32_t RPMessage_lateInit ( uint32_t proc )

Add a proc to RPMessage Module.

Can be called from Main or Task context. Must be called after calling RPMessage_init. Must be called before any other RPMessage function to communicate with this proc;

Parameters

proc	[IN] Remote Proc ID

Returns: IPC_SOK or IPC_EFAIL

◆ RPMessage_deInit()

void RPMessage_deInit ( void )

Tear down the RPMessage Module. The module API should not be used after this is called.

◆ RPMessageParams_init()

int32_t RPMessageParams_init ( RPMessage_Params * params )

Initialize an RPMessage_Params structure to default values.

This function must be called before on a RPMessage_Params before passing it to RPMessage_create().

Parameters

params [IN] Address of the RPMessage_Params structure to be initialized.

Returns: IPC_SOK or IPC_EFAIL

◆ RPMessage_create()

RPMessage_Handle RPMessage_create	(	RPMessage_Params *	params,
		uint32_t *	endPt
	)

Create a endpoint instance for receiving.

The returned handle is to an object containing a queue for receiving messages from the transport, and a 32 bit endpoint ID unique to this local processor.

Parameters

params	[IN] RPMessage_Params Address of an initialized RPMessage_Params structure or NULL will use defaults.
endPt	[OUT] Endpoint ID for this side of the connection.

Returns

RPMessage Handle, or NULL if:

reserved endpoint already taken;
could not allocate object

◆ RPMessage_setCallback()

int32_t RPMessage_setCallback	(	RPMessage_Handle	handle,
		RPMessage_Callback	cb,
		void *	arg
	)

Sets callback.

Sets the callback function and function arguments, so that it does not need to wai for semaphore.

Parameters

handle	[IN] An RPMessage_handle
cb	[IN] RPMessage_Callback Callback function.
arg	[IN] Arguments of the callback function

Returns

- IPC_SOK: Message successfully returned

IPC_ETIMEOUT: RPMessage_recv timed out
IPC_EFAIL: A general failure has occurred

◆ RPMessage_setCallbackForProc()

int32_t RPMessage_setCallbackForProc	(	RPMessage_ProcCallback	cb,
		void *	arg,
		int32_t	priority
	)

Sets callback.

Sets the callback function and function arguments, to run for whenever an end point created by the calling process receives a message.

Note: If a callback is already registered, calling this function with a different callback function/arg will result in IPC_EFAIL and no change to the registered callback function. To change the callback please unregister the callback for the process first.

Parameters

cb	[IN] Ipc_NewMsgReceivedFxn Callback function.
arg	[IN] Arguments of the callback function
priority	[IN] Scheduling priority to

Returns

- IPC_SOK: Calling process has successfully registered for a callback when an associated end point receives a message.

IPC_EFAIL: A general failure has occurred

◆ RPMessage_deleteCallbackForProc()

int32_t RPMessage_deleteCallbackForProc ( void )

Deletes callback.

Deletes the callback function and function arguments, to prevent future callback messages and clean up the associated resources.

Returns

- IPC_SOK: Calling process has successfully unregistered any registered callback.

IPC_EFAIL: Either a callback was not registered to begin with or there was an issue cleaning up the associated resources.

◆ RPMessage_recv()

int32_t RPMessage_recv	(	RPMessage_Handle	handle,
		void *	data,
		uint16_t *	len,
		uint32_t *	rplyEndPt,
		uint32_t *	fromProcId,
		uint32_t	timeout
	)

Receives a message from an endpoint instance.

This function returns a status. It also copies data to the client. If no message is available, it blocks on the semaphore object until the semaphore is signaled or a timeout occurs. The semaphore is signaled, when Message_send is called to deliver a message to this endpoint. If a timeout occurs, len is set to zero and the status is RPMessage_E_TIMEOUT. If a timeout of zero is specified, the function returns immediately and if no message is available, the len is set to zero and the status is RPMessage_E_TIMEOUT. RPMessage_E_UNBLOCKED status is returned, if RPMessage_unblock() is called on the RPMessage handle. When a message is retrieved, the message data is copied into the memory location of the data pointer, and RPMessage_S_SUCCESS status is returned.

Parameters

handle	[IN] An RPMessage_handle
data	[OUT] Pointer to the client's data buffer.
len	[OUT] Amount of data received.
rplyEndPt	[OUT] Endpoint of source (for replies).
fromProcId	[OUT] ProcId of source (for replies).
timeout	[IN] Maximum duration to wait for a message in microseconds.

Returns

- IPC_SOK: Message successfully returned

IPC_ETIMEOUT: RPMessage_recv timed out
IPC_E_UNBLOCKED: RPMessage_recv was unblocked
IPC_EFAIL: A general failure has occurred

RPMessage_send RPMessage_unblock

◆ RPMessage_recvNb()

int32_t RPMessage_recvNb	(	RPMessage_Handle	handle,
		void *	data,
		uint16_t *	len,
		uint32_t *	rplyEndPt,
		uint32_t *	fromProcId
	)

A non blocking API to receive message.

This function check if there any received messages, if found the received message is copied into buffer provided by the caller. The caller will have to allocate sufficient buffer to account for the reception of the largest message. Configured while creating the driver.

Parameters

handle	[IN] An RPMessage_handle
data	[OUT] Pointer to the buffer, allocted by the caller
len	[OUT] Size of the received buffer, in bytes
rplyEndPt	[OUT] Endpoint of source (for replies)
fromProcId	[OUT] ProcId of source (for replies)

Returns

- IPC_SOK : Message successfully returned

IPC_EBADARGS : In case where one or more arguments is NULL
IPC_ETIMEOUT : No messages available at this point
IPC_EFAIL : Internal error

RPMessage_send

◆ RPMessage_send()

int32_t RPMessage_send	(	RPMessage_Handle	handle,
		uint32_t	dstProc,
		uint32_t	dstEndPt,
		uint32_t	srcEndPt,
		void *	data,
		uint16_t	len
	)

Sends data to a remote processor.

Parameters

handle	[IN] Handle of RPMessage Object
dstProc	[IN] Destination ProcId.
dstEndPt	[IN] Destination Endpoint.
srcEndPt	[IN] Source Endpoint.
data	[IN] Data payload to be copied and sent.
len	[IN] Amount of data to be copied.

Returns

- IPC_SOK

IPC_EFAIL

◆ RPMessage_delete()

int32_t RPMessage_delete ( RPMessage_Handle * handlePtr )

Delete an endpoint instance.

This function deletes a created endpoint instance. If the message queue is non-empty, any messages remaining in the queue will be lost.

Parameters

handlePtr [IN,OUT] Pointer to handle to delete. Set to NULL.

Returns

- IPC_EFAIL: delete failed

IPC_SOK: delete successful

◆ RPMessage_unblock()

void RPMessage_unblock ( RPMessage_Handle handle )

Unblocks an RPMessage_recv()

Unblocks a reader thread that is blocked on a RPMessage_recv. The RPMessage_recv call will return with status IPC_E_UNBLOCKED indicating that it returned due to a RPMessage_unblock rather than by a timeout or receiving a message.

Restrictions:

A queue may not be used after it has been unblocked.
RPMessage_unblock may only be called on a local queue.

Parameters

[in] handle RPMessage handle

See also: RPMessage_recv

◆ RPMessage_getRemoteEndPt()

int32_t RPMessage_getRemoteEndPt	(	uint32_t	currProcId,
		const char *	name,
		uint32_t *	remoteProcId,
		uint32_t *	remoteEndPt,
		uint32_t	timeout
	)

Wait for an endpoint to become available on another processor.

Block the current task until the specified processor announces the named endpoint. The name is a string that identifies the service that is offered on the endpoint. This allows an application to both wait for the remote processor to signal that it is ready to communicate and to lookup services by name. The procId can be that of a specific processor or PRMessage_ANY to wait for any processor to announce the named endpoint. Suitable values for timeout are the same as for the ti.sysbios.knl.Semaphore module.

Parameters

currProcId	[IN] Remote processor ID
name	[IN] Name of the endpoint
remoteProcId	[OUT] Remote processor ID
remoteEndPt	[OUT] Remote endpoint ID
timeout	[IN] Timeout value (in system ticks)

Returns

- IPC_SOK: Endpoint successfully returned

IPC_ETIMEOUT: Time out occured
IPC_EFAIL: Invalid input
IPC_E_NO_ENDPOINT: End point not found

◆ RPMessage_getRemoteEndPtToken()

int32_t RPMessage_getRemoteEndPtToken	(	uint32_t	currProcId,
		const char *	name,
		uint32_t *	remoteProcId,
		uint32_t *	remoteEndPt,
		uint32_t	timeout,
		uint32_t	token
	)

◆ RPMessage_unblockGetRemoteEndPt()

void RPMessage_unblockGetRemoteEndPt ( uint32_t token )

Unblocks an RPMessage_getRemoteEndPtToken() call.

Unblocks a thread that is blocked on a RPMessage_getRemoteEndPtToken. The RPMessage_getRemoteEndPtToken call will return with status an invalid remoteProcId and remoteEndPt (RPMESSAGE_ANY) indicating that it returned due to a RPMessage_unblockGetRemoteEndPt rather than by a timeout or receiving the requested remote endpoint.

Parameters

[in] token Token passed when calling RPMessage_getRemoteEndPtToken

See also: RPMessage_getRemoteEndPtToken

◆ RPMessage_announce()

int32_t RPMessage_announce	(	uint32_t	remoteProcId,
		uint32_t	endPt,
		const char *	name
	)

Annouce the name of an endpoint and that it is ready to to receive messages.

Announcing an endpoint to other processesors acheives two goals. First it signals that the endpoint is ready to recieve, and second, the endpoint is offering the named service. Announcements can be sent to all remote processors by using RPMessage_ALL for remoteProcId, otherwise only the specified processor recieves the announcement. The name may not be an empty string or NULL. The value of endPt should have been returned by a prior call to RPMessage_create().

Parameters

remoteProcId	[IN] RPMessage_Params The remote processor to receive the announcement
endPt	[IN] Endpoint ID to announce
name	[IN] Name of the service on the endpoint

Returns

- IPC_SOK: Endpoint successfully announced

IPC_EFAIL: Invalid input

◆ RPMessage_getStats()

void RPMessage_getStats ( RPMessage_Stats * stats )

Copies the current statistics of the IPC driver into the structure provided.

To be able to profile how the IPC driver is reacting to a given system load/set of programs, RPMessage_getStats provides a mechanism where applications can request the current statistics of the driver. Additionally a getter function is used so that the statistics will be preserved for the lifetime of the driver without interference from other programs. The use of a public struct also allows for future statistics to be added without requiring updates in other projects, so long as functions like memset and memcpy are used.

Parameters

stats [OUT] RPMessage_Stats Pointer to structure in which to store the driver's current statistics

◆ Ipc_mailboxEnableNewMsgInt()

void Ipc_mailboxEnableNewMsgInt	(	uint16_t	selfId,
		uint16_t	remoteProcId
	)

API Mailbox Enable new MSG interrupt for a given remote processor.

Warning: To be used only when built for baremetal

Parameters

selfId	Self Processor Identifier
remoteProcId	Remote Processor ID

Returns: None

◆ Ipc_mailboxDisableNewMsgInt()

void Ipc_mailboxDisableNewMsgInt	(	uint16_t	selfId,
		uint16_t	remoteProcId
	)

API Mailbox Disable new MSG interrupt for a given remote processor.

Warning: To be used only when built for baremetal

Parameters

selfId	Self Processor Identifier
remoteProcId	Remote Processor ID

Returns: None

Variable Documentation

◆ instId

uint32_t Ipc_InitPrms::instId

[IN] Ipc_InstanceId. Only 1 instance is supported in this implementation. The value shall be 0

◆ phyToVirtFxn

Ipc_PhyToVirtFxn Ipc_InitPrms::phyToVirtFxn

If not NULL, this function will be called to convert physical address to virtual address to access the pointer returned by the IPC. If NULL, the driver will assume a one-one mapping.

Note: The init fxn will initialize this to the default one-one map function Ipc_defaultPhyToVirtFxn

◆ virtToPhyFxn

Ipc_VirtToPhyFxn Ipc_InitPrms::virtToPhyFxn

If not NULL, this function will be called to convert virtual address to physical address to be provided to IPC. If NULL, the driver will assume a one-one mapping.

Note: The init fxn will initialize this to the default one-one map function Ipc_defaultVirtToPhyFxn

◆ osalPrms

Ipc_OsalPrms Ipc_InitPrms::osalPrms

OSAL callback parameters

◆ newMsgFxn

Ipc_NewMsgReceivedFxn Ipc_InitPrms::newMsgFxn

Optional callback function, that would be invoked when a new message is received

◆ rpMboxMsgFxn

Ipc_RpMboxMsgFxn Ipc_InitPrms::rpMboxMsgFxn

Optional callback function, that would be invoked when remote processor sends actual message via mailbox instead of kick

◆ printFxn

Ipc_PrintFxn Ipc_InitPrms::printFxn

If not NULL, this function will be called to print debug/info message with appropriate string.

◆ requestedEndpt

uint32_t RPMessage_Params::requestedEndpt

Requested Endpoint - Any or next available

◆ numBufs

uint32_t RPMessage_Params::numBufs

Maximum number of buffers to allocate for queuing received messages.

◆ buf

void* RPMessage_Params::buf

Buffer pointer to store RPMessage Object

◆ bufSize

uint32_t RPMessage_Params::bufSize

Buffer Size. Recommended Size is (512*256 + 256).

256 buffers of 512 bytes.
256 size of RPMessage object used for bookkeeping.

◆ stackBuffer

void* RPMessage_Params::stackBuffer

Buffer used for stack for control task

◆ stackSize

uint32_t RPMessage_Params::stackSize

StackSize used for the task

◆ recvTotalMessages

uint32_t RPMessage_Stats::recvTotalMessages

◆ recvMessagesLiveTransferred

uint32_t RPMessage_Stats::recvMessagesLiveTransferred

◆ recvMessagesQueued

uint32_t RPMessage_Stats::recvMessagesQueued

◆ recvBufferAllocFailures

uint32_t RPMessage_Stats::recvBufferAllocFailures

◆ recvEndpointFindFails

uint32_t RPMessage_Stats::recvEndpointFindFails

Files

Data Structures

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ RPMessage_Handle

◆ RPMessage_Callback

◆ RPMessage_ProcCallback

Function Documentation

◆ IpcInitPrms_init()

◆ Ipc_init()

◆ Ipc_deinit()

◆ RPMessage_getMessageBufferSize()

◆ RPMessage_getObjMemRequired()

◆ RPMessage_init()

◆ RPMessage_lateInit()

◆ RPMessage_deInit()

◆ RPMessageParams_init()

◆ RPMessage_create()

◆ RPMessage_setCallback()

◆ RPMessage_setCallbackForProc()

◆ RPMessage_deleteCallbackForProc()

◆ RPMessage_recv()

◆ RPMessage_recvNb()

◆ RPMessage_send()

◆ RPMessage_delete()

◆ RPMessage_unblock()

◆ RPMessage_getRemoteEndPt()

◆ RPMessage_getRemoteEndPtToken()

◆ RPMessage_unblockGetRemoteEndPt()

◆ RPMessage_announce()

◆ RPMessage_getStats()

◆ Ipc_mailboxEnableNewMsgInt()

◆ Ipc_mailboxDisableNewMsgInt()

Variable Documentation

◆ instId

◆ phyToVirtFxn

◆ virtToPhyFxn

◆ osalPrms

◆ newMsgFxn

◆ rpMboxMsgFxn

◆ printFxn

◆ requestedEndpt

◆ numBufs

◆ buf

◆ bufSize

◆ stackBuffer

◆ stackSize

◆ recvTotalMessages

◆ recvMessagesLiveTransferred

◆ recvMessagesQueued

◆ recvBufferAllocFailures

◆ recvEndpointFindFails