PSDK QNX API Guide
ipc.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) Texas Instruments Incorporated 2018
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the
15  * distribution.
16  *
17  * Neither the name of Texas Instruments Incorporated nor the names of
18  * its contributors may be used to endorse or promote products derived
19  * from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  */
33 
43 /* @} */
44 
59 #ifndef IPC_H_
60 #define IPC_H_
61 
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65 
66 /* ========================================================================== */
67 /* Include Files */
68 /* ========================================================================== */
69 #include <ti/csl/soc.h>
70 #include <ti/csl/csl_types.h>
71 
72 #include <ti/drv/ipc/include/ipc_types.h>
77 #include <ti/drv/ipc/soc/ipc_soc.h>
78 #include <string.h>
79 
80 /* ========================================================================== */
81 /* Macros & Typedefs */
82 /* ========================================================================== */
86 typedef struct RPMessage_Object_s* RPMessage_Handle;
87 
98 typedef void (*RPMessage_Callback)(RPMessage_Handle handle, void* arg, void* data,
99  uint16_t len, uint32_t src);
100 
101 
102 /* ========================================================================== */
103 /* Structure Declarations */
104 /* ========================================================================== */
105 
110 typedef struct Ipc_InitPrms_s
111 {
112  uint32_t instId;
115  Ipc_PhyToVirtFxn phyToVirtFxn;
123  Ipc_VirtToPhyFxn virtToPhyFxn;
131  Ipc_OsalPrms osalPrms;
134  Ipc_NewMsgReceivedFxn newMsgFxn;
138  Ipc_PrintFxn printFxn;
141 } Ipc_InitPrms;
142 
146 typedef struct RPMessage_Params_s
147 {
148  uint32_t requestedEndpt;
151  uint32_t numBufs;
154  void* buf;
157  uint32_t bufSize;
162  void* stackBuffer;
165  uint32_t stackSize;
168 
169 /* ========================================================================== */
170 /* Function Declarations */
171 /* ========================================================================== */
189 void IpcInitPrms_init(uint32_t instId, Ipc_InitPrms *initPrms);
190 
203 int32_t Ipc_init(const Ipc_InitPrms *cfg);
204 
212 int32_t Ipc_deinit(void);
213 
218 
219 
224 
237 
238 #if defined (SOC_J721E) || defined (SOC_J7200) || defined (SOC_J784S4)
250 int32_t RPMessage_lateInit(uint32_t proc);
251 #endif
252 
257 void RPMessage_deInit(void);
258 
259 
272 
293 
312 
344 int32_t RPMessage_recv(RPMessage_Handle handle, void* data, uint16_t *len,
345  uint32_t *rplyEndPt, uint32_t *fromProcId, uint32_t timeout);
346 
368 int32_t RPMessage_recvNb(RPMessage_Handle handle, void* data, uint16_t *len,
369  uint32_t *rplyEndPt, uint32_t *fromProcId);
370 
385  uint32_t dstProc,
386  uint32_t dstEndPt,
387  uint32_t srcEndPt,
388  void* data,
389  uint16_t len);
390 
404 int32_t RPMessage_delete(RPMessage_Handle *handlePtr);
405 
423 
424 
448 int32_t RPMessage_getRemoteEndPt(uint32_t currProcId, const char* name, uint32_t *remoteProcId,
449  uint32_t *remoteEndPt, uint32_t timeout);
450 
451 /*
452  * \brief Wait for an endpoint to become available on another
453  * processor with token.
454  *
455  * Block the current task until the specified processor announces the
456  * named endpoint. The name is a string that identifies the service
457  * that is offered on the endpoint. This allows an application to both
458  * wait for the remote processor to signal that it is ready to
459  * communicate and to lookup services by name. The procId can be that
460  * of a specific processor or PRMessage_ANY to wait for any processor
461  * to announce the named endpoint. Suitable values for timeout are the
462  * same as for the ti.sysbios.knl.Semaphore module.
463  * This is the same as RPMessage_getRemoteEndPt, except that a token
464  * can be taken with the request, which can be used by the application
465  * to unblock the request in order to unblock it's waiting task.
466  *
467  * \param currProcId [IN] Remote processor ID
468  * \param name [IN] Name of the endpoint
469  * \param remoteProcId [OUT] Remote processor ID
470  * \param remoteEndPt [OUT] Remote endpoint ID
471  * \param timeout [IN] Timeout value (in system ticks)
472  * \param token [IN] User-provided token that can be used to unblock the function
473  *
474  * Restrictions:
475  * - The token passed must be unique for each call.
476  *
477  * \return - #IPC_SOK: Endpoint successfully returned
478  * - #IPC_ETIMEOUT: Time out occured
479  * - #IPC_EFAIL: Invalid input
480  */
481 int32_t RPMessage_getRemoteEndPtToken(uint32_t currProcId, const char* name, uint32_t *remoteProcId,
482  uint32_t *remoteEndPt, uint32_t timeout, uint32_t token);
483 
497 void RPMessage_unblockGetRemoteEndPt(uint32_t token);
498 
523 int32_t RPMessage_announce(uint32_t remoteProcId, uint32_t endPt,
524  const char* name);
525 
535 void Ipc_mailboxEnableNewMsgInt(uint16_t selfId, uint16_t remoteProcId);
536 
546 void Ipc_mailboxDisableNewMsgInt(uint16_t selfId, uint16_t remoteProcId);
547 
548 /* ========================================================================== */
549 /* Static Function Definitions */
550 /* ========================================================================== */
551 
552 /* None */
553 
554 #ifdef __cplusplus
555 }
556 #endif
557 
558 #endif /* #ifndef IPC_H_ */
559 
560 /* @} */
void RPMessage_deInit(void)
Tear down the RPMessage Module. The module API should not be used after this is called.
void RPMessage_unblockGetRemoteEndPt(uint32_t token)
Unblocks an RPMessage_getRemoteEndPtToken() call.
void * buf
Definition: ipc.h:154
int32_t RPMessage_setCallback(RPMessage_Handle handle, RPMessage_Callback cb, void *arg)
Sets callback.
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.
uint32_t bufSize
Definition: ipc.h:157
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.
Ipc_PhyToVirtFxn phyToVirtFxn
Definition: ipc.h:115
RPMessage_Handle RPMessage_create(RPMessage_Params *params, uint32_t *endPt)
Create a endpoint instance for receiving.
int32_t Ipc_deinit(void)
De Initialize IPC module.
Ipc_PrintFxn printFxn
Definition: ipc.h:138
uint32_t requestedEndpt
Definition: ipc.h:148
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.
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.
int32_t RPMessage_init(RPMessage_Params *params)
Initialize RPMessage Module.
Ipc_NewMsgReceivedFxn newMsgFxn
Definition: ipc.h:134
void * stackBuffer
Definition: ipc.h:162
void(* RPMessage_Callback)(RPMessage_Handle handle, void *arg, void *data, uint16_t len, uint32_t src)
RPMessage_Callback.
Definition: ipc.h:98
struct RPMessage_Object_s * RPMessage_Handle
RPMessage_Handle type.
Definition: ipc.h:86
int32_t RPMessage_getRemoteEndPtToken(uint32_t currProcId, const char *name, uint32_t *remoteProcId, uint32_t *remoteEndPt, uint32_t timeout, uint32_t token)
uint32_t numBufs
Definition: ipc.h:151
void Ipc_mailboxEnableNewMsgInt(uint16_t selfId, uint16_t remoteProcId)
API Mailbox Enable new MSG interrupt for a given remote processor.
int32_t RPMessage_delete(RPMessage_Handle *handlePtr)
Delete an endpoint instance.
int32_t RPMessageParams_init(RPMessage_Params *params)
Initialize an RPMessage_Params structure to default values.
void Ipc_mailboxDisableNewMsgInt(uint16_t selfId, uint16_t remoteProcId)
API Mailbox Disable new MSG interrupt for a given remote processor.
int32_t Ipc_init(const Ipc_InitPrms *cfg)
Initialize IPC module.
Ipc_OsalPrms osalPrms
Definition: ipc.h:131
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.
uint32_t RPMessage_getObjMemRequired(void)
Returns local memory for RPMessage Object.
uint32_t instId
Definition: ipc.h:112
void RPMessage_unblock(RPMessage_Handle handle)
Unblocks an RPMessage_recv()
Ipc_VirtToPhyFxn virtToPhyFxn
Definition: ipc.h:123
uint32_t stackSize
Definition: ipc.h:165
uint32_t RPMessage_getMessageBufferSize(void)
Returns Message Buffer Size.
void IpcInitPrms_init(uint32_t instId, Ipc_InitPrms *initPrms)
Initialize IPC init params.
configurations for ipc module.
IPC - Multiproc interface.
VirtIO Interface for application.
IPC initialization parameters.
Definition: ipc.h:111
Parameter structure for creating RPMessage endpoints.
Definition: ipc.h:147