Introduction

This is IPC's top level include for applications

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...

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

int32_t	Ipc_init (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_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 selfProcId, 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 selfProcId, 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	Ipc_newMessageIsr (uint32_t srcProcId)
	New Message Interrupt Handler. 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...

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 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

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 ( 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_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	selfProcId,
		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

selfProcId	[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

◆ RPMessage_getRemoteEndPtToken()

int32_t RPMessage_getRemoteEndPtToken	(	uint32_t	selfProcId,
		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

◆ Ipc_newMessageIsr()

void Ipc_newMessageIsr ( uint32_t srcProcId )

New Message Interrupt Handler.

Warning: To be used only when built for baremetal

When built for baremetal applications, the IPC driver do not register interrupt handler to handle interrupts from mailbox. It's expected that user of this driver shall invoke this function, on reception of interrupt from the mailbox associated with remote processor

Parameters

srcProcId [IN] The remote processor ID

Returns: - None

◆ 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

Introduction

Files

Data Structures

Functions

Typedefs

Typedef Documentation

◆ RPMessage_Handle

◆ RPMessage_Callback

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_recv()

◆ RPMessage_recvNb()

◆ RPMessage_send()

◆ RPMessage_delete()

◆ RPMessage_unblock()

◆ RPMessage_getRemoteEndPt()

◆ RPMessage_getRemoteEndPtToken()

◆ RPMessage_unblockGetRemoteEndPt()

◆ RPMessage_announce()

◆ Ipc_newMessageIsr()

◆ Ipc_mailboxEnableNewMsgInt()

◆ Ipc_mailboxDisableNewMsgInt()