ipc fix: Doxygen errors are addressed
[processor-sdk/pdk.git] / packages / ti / drv / ipc / ipc.h
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  */
34 /**
35  *  \defgroup DRV_IPC_MODULE IPC Driver
36  *
37  *  @{
38  *
39  * The IPC low level driver provides the communication mechanism between
40  * various cores on J7 device.
41  * This is IPC lld driver documentation.
42  */
43 /* @} */
45 /**
46  *  \ingroup DRV_IPC_MODULE
47  *  \defgroup IPC_TOP_LEVEL IPC Driver Header
48  *            This is IPC's top level include for applications
49  *
50  *  @{
51  */
53 /**
54  *  \file ipc.h
55  *
56  *  \brief IPC Low Level Driver API/interface data types file.
57  */
59 #ifndef IPC_H_
60 #define IPC_H_
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
66 /* ========================================================================== */
67 /*                             Include Files                                  */
68 /* ========================================================================== */
69 #include <ti/csl/soc.h>
70 #include <ti/csl/csl_navss_main.h>
72 #include <ti/drv/ipc/include/ipc_types.h>
73 #include <ti/drv/ipc/include/ipc_rsctypes.h>
74 #include <ti/drv/ipc/include/ipc_config.h>
75 #include <ti/drv/ipc/include/ipc_mp.h>
76 #include <ti/drv/ipc/include/ipc_virtio.h>
77 #include <ti/drv/ipc/soc/ipc_soc.h>
79 /* ========================================================================== */
80 /*                           Macros & Typedefs                                */
81 /* ========================================================================== */
82 /**
83  *  \brief  RPMessage_Handle type
84  */
85 typedef struct RPMessage_Object_s* RPMessage_Handle;
87 /**
88  *  \brief  RPMessage_Callback
89  *
90  *  \param RPMessage_Handle    [IN]
91  *  \param arg   [IN] void* arguments to function
92  *  \param data  [IN] data pointer
93  *  \param len   [IN] length of data
94  *  \param src   [IN] source
95  *
96  */
97 typedef void (*RPMessage_Callback)(RPMessage_Handle handle, void* arg, void* data,
98                                       uint16_t len, uint32_t src);
101 /* ========================================================================== */
102 /*                         Structure Declarations                             */
103 /* ========================================================================== */
105 /**
106  *  \brief IPC initialization parameters.
107  *
108  */
109 typedef struct Ipc_InitPrms_s
111     uint32_t                instId;
112     /**< [IN] Ipc_InstanceId. Only 1 instance is supported in this
113         implementation. The value shall be 0 */
114     Ipc_PhyToVirtFxn        phyToVirtFxn;
115     /**< If not NULL, this function will be called to convert physical address
116      *   to virtual address to access the pointer returned by the IPC.
117      *   If NULL, the driver will assume a one-one mapping.
118      *
119      *   Note: The init fxn will initialize this to the default one-one map
120      *   function Ipc_defaultPhyToVirtFxn
121      */
122     Ipc_VirtToPhyFxn        virtToPhyFxn;
123     /**< If not NULL, this function will be called to convert virtual address
124      *   to physical address to be provided to IPC.
125      *   If NULL, the driver will assume a one-one mapping.
126      *
127      *   Note: The init fxn will initialize this to the default one-one map
128      *   function Ipc_defaultVirtToPhyFxn
129      */
130     Ipc_OsalPrms            osalPrms;
131     /**< OSAL callback  parameters */
133     Ipc_NewMsgReceivedFxn   newMsgFxn;
134     /**< Optional callback function, that would be invoked when a new message
135         is received */
136 } Ipc_InitPrms;
138 /**
139  *  \brief Parameter structure for creating RPMessage endpoints
140  */
141 typedef struct RPMessage_Params_s
143     uint32_t  requestedEndpt;
144     /**< Requested Endpoint - Any or next available */
146     uint32_t  numBufs;
147     /**< Maximum number of buffers to allocate for queuing received messages. */
149     void*     buf;
150     /**<  Buffer pointer to store RPMessage Object */
152     uint32_t  bufSize;
153     /**< Buffer Size. Recommended Size is (512*256 + 256).
154           - 256 buffers of 512 bytes.
155           - 256 size of RPMessage object used for bookkeeping. */
157     void*     stackBuffer;
158     /**<  Buffer used for stack for control task */
160     uint32_t  stackSize;
161     /**< StackSize used for the task */
162 } RPMessage_Params;
164 /* ========================================================================== */
165 /*                          Function Declarations                             */
166 /* ========================================================================== */
167 /**
168  *  \brief      Initialize IPC module
169  *
170  *              Very first API to be invoked to initialize internal data
171  *              structure and utilities required.
172  *
173  *  \param cfg [IN] Initialization parameters. Expected to be NULL in case of
174  *              expected use in tirtos environment and non-null in case of
175  *              baremetal
176  *
177  *  \return      #IPC_SOK or #IPC_EINVALID_PARAMS or #IPC_EFAIL
178  */
179 int32_t Ipc_init(Ipc_InitPrms *cfg);
181 /**
182  *  \brief      De Initialize IPC module
183  *
184  *              Very last API to be invoked to de initialize.
185  *
186  *  \return      #IPC_SOK
187  */
188 int32_t Ipc_deinit(void);
190 /**
191  * \brief       Returns Message Buffer Size
192  */
193 uint32_t RPMessage_getMessageBufferSize(void);
196 /**
197  * \brief       Returns local memory for RPMessage Object
198  */
199 uint32_t RPMessage_getObjMemRequired(void);
201 /**
202  *  \brief      Initialize RPMessage Module
203  *
204  *  Can be called from Main or Task context.  Must be called before
205  *  calling any other RPMessage function;
206  *
207  *  \param params [IN] Address of the RPMessage_Params structure
208  *                used to create the RPMessage
209  *
210  *  \return      #IPC_SOK or #IPC_EFAIL
211  */
212 int32_t RPMessage_init(RPMessage_Params *params);
214 /**
215  *  \brief      Add a proc to RPMessage Module
216  *
217  *  Can be called from Main or Task context.  Must be called after
218  *  calling RPMessage_init. Must be called before any other RPMessage
219  *  function to communicate with this proc;
220  *
221  *  \param proc [IN] Remote Proc ID
222  *
223  *  \return      #IPC_SOK or #IPC_EFAIL
224  */
225 int32_t RPMessage_lateInit(uint32_t proc);
228 /**
229  *  \brief      Tear down the RPMessage Module.  The module API
230  *              should not be used after this is called.
231  */
232 void RPMessage_deInit(void);
235 /**
236  *  \brief Initialize an RPMessage_Params structure to default values.
237  *
238  *  This function must be called before on a RPMessage_Params before passing
239  *  it to RPMessage_create().
240  *
241  *  \param params    [IN] Address of the RPMessage_Params structure
242  *                        to be initialized.
243  *
244  *  \return      #IPC_SOK or #IPC_EFAIL
245  */
246 int32_t RPMessageParams_init(RPMessage_Params *params);
248 /**
249  *  \brief Create a endpoint instance for receiving.
250  *
251  *  The returned handle is to an object containing a queue for receiving
252  *  messages from the transport, and a 32 bit endpoint ID unique to this local
253  *  processor.
254  *
255  *  \param params    [IN] \ref RPMessage_Params
256                           Address of an initialized RPMessage_Params
257  *                        structure or NULL will use defaults.
258  *
259  *  \param endPt    [OUT] Endpoint ID for this side of the connection.
260  *
261  *
262  *  \return RPMessage Handle, or NULL if:
263  *           - reserved endpoint already taken;
264  *           - could not allocate object
265  *
266  */
267 RPMessage_Handle RPMessage_create(RPMessage_Params *params, uint32_t *endPt);
269 /**
270  *  \brief Sets callback.
271  *
272  *  Sets the callback function and function arguments, so that
273  *  it does not need to wai for semaphore.
274  *
275  *  \param handle    [IN] An RPMessage_handle
276  *  \param cb    [IN] \ref RPMessage_Callback
277  *                    Callback function.
278  *  \param arg   [IN] Arguments of the callback function
279  *
280  *
281  *  \return     - #IPC_SOK: Message successfully returned
282  *              - #IPC_ETIMEOUT: RPMessage_recv timed out
283  *              - #IPC_EFAIL:    A general failure has occurred
284  *
285  */
286 int32_t RPMessage_setCallback(RPMessage_Handle handle, RPMessage_Callback cb, void* arg);
288 /**
289  *  \brief Receives a message from an endpoint instance
290  *
291  *  This function returns a status. It also copies data to the client.
292  *  If no message is available, it blocks on the semaphore object until
293  *  the semaphore is signaled or a timeout occurs.  The semaphore is
294  *  signaled, when Message_send is called to deliver a message to this
295  *  endpoint. If a timeout occurs, len is set to zero and the status is
296  *  RPMessage_E_TIMEOUT. If a timeout of zero is specified, the
297  *  function returns immediately and if no message is available, the len
298  *  is set to zero and the status is RPMessage_E_TIMEOUT.
299  *  RPMessage_E_UNBLOCKED status is returned, if RPMessage_unblock() is
300  *  called on the RPMessage handle.  When a message is retrieved, the
301  *  message data is copied into the memory location of the data pointer,
302  *  and RPMessage_S_SUCCESS status is returned.
303  *
304  *  \param handle    [IN] An RPMessage_handle
305  *  \param data    [OUT] Pointer to the client's data buffer.
306  *  \param len    [OUT] Amount of data received.
307  *  \param rplyEndPt    [OUT] Endpoint of source (for replies).
308  *  \param fromProcId    [OUT] ProcId of source (for replies).
309  *  \param timeout    [IN] Maximum duration to wait for a message in
310  *                              microseconds.
311  *
312  *  \return     - #IPC_SOK: Message successfully returned
313  *              - #IPC_ETIMEOUT: RPMessage_recv timed out
314  *              - #IPC_E_UNBLOCKED: RPMessage_recv was unblocked
315  *              - #IPC_EFAIL:    A general failure has occurred
316  *
317  *  \ref RPMessage_send RPMessage_unblock
318  */
319 int32_t RPMessage_recv(RPMessage_Handle handle, void* data, uint16_t *len,
320                       uint32_t *rplyEndPt, uint32_t *fromProcId, uint32_t timeout);
322 /**
323  *  \brief A non blocking API to receive message
324  *
325  *  This function check if there any received messages, if found the received
326  *      message is copied into buffer provided by the caller.
327  *  The caller will have to allocate sufficient buffer to account for the
328  *      reception of the largest message. Configured while creating the driver.
329  *
330  *  \param handle       [IN] An RPMessage_handle
331  *  \param data         [OUT] Pointer to the buffer, allocted by the caller
332  *  \param len          [OUT] Size of the received buffer, in bytes
333  *  \param rplyEndPt    [OUT] Endpoint of source (for replies)
334  *  \param fromProcId   [OUT] ProcId of source (for replies)
335  *
336  *  \return     - #IPC_SOK      : Message successfully returned
337  *              - #IPC_EBADARGS : In case where one or more arguments is NULL
338  *              - #IPC_ETIMEOUT : No messages available at this point
339  *              - #IPC_EFAIL    : Internal error
340  *
341  *  \ref RPMessage_send
342  */
343 int32_t RPMessage_recvNb(RPMessage_Handle handle, void* data, uint16_t *len,
344                    uint32_t *rplyEndPt, uint32_t *fromProcId);
346 /**
347  *  \brief Sends data to a remote processor.
348  *
349  *  \param handle     [IN] Handle of RPMessage Object
350  *  \param dstProc    [IN] Destination ProcId.
351  *  \param dstEndPt   [IN] Destination Endpoint.
352  *  \param srcEndPt   [IN] Source Endpoint.
353  *  \param data       [IN] Data payload to be copied and sent.
354  *  \param len        [IN] Amount of data to be copied.
355  *
356  *  \return     - #IPC_SOK
357  *              - #IPC_EFAIL
358  */
359 int32_t RPMessage_send(RPMessage_Handle handle,
360                       uint32_t dstProc,
361                       uint32_t dstEndPt,
362                       uint32_t srcEndPt,
363                       void*    data,
364                       uint16_t len);
366 /**
367  *  \brief Delete an endpoint instance.
368  *
369  *  This function deletes a created endpoint instance. If the
370  *  message queue is non-empty, any messages remaining in the queue
371  *  will be lost.
372  *
373  *  \param handlePtr [IN,OUT] Pointer to handle to delete.  Set to
374  *                             NULL.
375  *
376  *  \return     - #IPC_EFAIL: delete failed
377  *              - #IPC_SOK: delete successful
378  */
379 int32_t RPMessage_delete(RPMessage_Handle *handlePtr);
381 /**
382  *  \brief      Unblocks an RPMessage_recv()
383  *
384  *  Unblocks a reader thread that is blocked on a RPMessage_recv.  The
385  *  RPMessage_recv call will return with status #IPC_E_UNBLOCKED
386  *  indicating that it returned due to a RPMessage_unblock rather than by
387  *  a timeout or receiving a message.
388  *
389  *  Restrictions:
390  *  -  A queue may not be used after it has been unblocked.
391  *  -  RPMessage_unblock may only be called on a local queue.
392  *
393  *  \param[in]  handle      RPMessage handle
394  *
395  *  \sa         RPMessage_recv
396  */
397 void RPMessage_unblock(RPMessage_Handle handle);
400 /**
401  *  \brief Wait for an endpoint to become available on another
402  *         processor.
403  *
404  *  Block the current task until the specified processor announces the
405  *  named endpoint.  The name is a string that identifies the service
406  *  that is offered on the endpoint.  This allows an application to both
407  *  wait for the remote processor to signal that it is ready to
408  *  communicate and to lookup services by name.  The procId can be that
409  *  of a specific processor or PRMessage_ANY to wait for any processor
410  *  to announce the named endpoint.  Suitable values for timeout are the
411  *  same as for the ti.sysbios.knl.Semaphore module.
412  *
413  *  \param selfProcId    [IN] Remote processor ID
414  *  \param name      [IN] Name of the endpoint
415  *  \param remoteProcId    [OUT] Remote processor ID
416  *  \param remoteEndPt    [OUT] Remote endpoint ID
417  *  \param timeout    [IN] Timeout value (in system ticks)
418  *
419  *  \return     - #IPC_SOK: Endpoint successfully returned
420  *              - #IPC_ETIMEOUT: Time out occured
421  *              - #IPC_EFAIL:    Invalid input
422  */
423 int32_t RPMessage_getRemoteEndPt(uint32_t selfProcId, const char* name, uint32_t *remoteProcId,
424                              uint32_t *remoteEndPt, uint32_t timeout);
426 /**
427  *  \brief Annouce the name of an endpoint and that it is ready to
428  *         to receive messages.
429  *
430  *  Announcing an endpoint to other processesors acheives two goals.
431  *  First it signals that the endpoint is ready to recieve, and second,
432  *  the endpoint is offering the named service.  Announcements can
433  *  be sent to all remote processors by using RPMessage_ALL for
434  *  remoteProcId, otherwise only the specified processor recieves the
435  *  announcement.  The name may not be an empty string or NULL.  The
436  *  value of endPt should have been returned by a prior call to
437  *  RPMessage_create().
438  *
439  *  \param remoteProcId    [IN] \ref RPMessage_Params
440                                 The remote processor to receive the
441  *                              announcement
442  *  \param endPt    [IN] Endpoint ID to announce
443  *  \param name     [IN] Name of the service on the endpoint
444  *
445  *
446  *  \return     - #IPC_SOK: Endpoint successfully announced
447  *              - #IPC_EFAIL:    Invalid input
448  *
449  */
450 int32_t RPMessage_announce(uint32_t remoteProcId, uint32_t endPt,
451        const char* name);
453 /**
454  *  \brief New Message Interrupt Handler
455  *
456  *  \warning To be used only when built for baremetal
457  *
458  *  When built for baremetal applications, the IPC driver do not register
459  *  interrupt handler to handle interrupts from mailbox.
460  *  It's expected that user of this driver shall invoke this function, on
461  *  reception of interrupt from the mailbox associated with remote processor
462  *
463  *  \param srcProcId    [IN] The remote processor ID
464  *
465  *  \return     - None
466  *
467  */
468 void Ipc_newMessageIsr(uint32_t srcProcId);
470 /** \brief API Mailbox Enable new MSG interrupt for a given remote processor
471  *
472  *  \warning To be used only when built for baremetal
473  *
474  *  \param  selfId    Self Processor Identifier
475  *  \param  remoteProcId Remote Processor ID
476  *
477  *  \return None
478  */
479 void Ipc_mailboxEnableNewMsgInt(uint16_t selfId, uint16_t remoteProcId);
481 /** \brief API Mailbox Disable new MSG interrupt for a given remote processor
482  *
483  *  \warning To be used only when built for baremetal
484  *
485  *  \param  selfId    Self Processor Identifier
486  *  \param  remoteProcId    Remote Processor ID
487  *
488  *  \return None
489  */
490 void Ipc_mailboxDisableNewMsgInt(uint16_t selfId, uint16_t remoteProcId);
492 /* ========================================================================== */
493 /*                       Static Function Definitions                          */
494 /* ========================================================================== */
496 /* None */
498 #ifdef __cplusplus
500 #endif
502 #endif /* #ifndef IPC_H_ */
504 /* @} */