Added missing package dependencies.
[ipc/ipcdev.git] / packages / ti / ipc / family / omap54xx / VirtQueue.h
1 /*
2  * Copyright (c) 2011-2013, Texas Instruments Incorporated
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 distribution.
15  *
16  * *  Neither the name of Texas Instruments Incorporated nor the names of
17  *    its contributors may be used to endorse or promote products derived
18  *    from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /** ============================================================================
33  *  @file       VirtQueue.h
34  *
35  *  @brief      Virtio Queue interface for BIOS
36  *
37  *  Differences between BIOS version and Linux kernel (include/linux/virtio.h):
38  *  - Renamed module from virtio.h to VirtQueue.h to match the API prefixes;
39  *  - BIOS (XDC) types and CamelCasing used;
40  *  - virtio_device concept removed (i.e, assumes no containing device);
41  *  - removed scatterlist;
42  *  - VirtQueues are created statically here, so just added a VirtQueue_init()
43  *    fxn to take the place of the Virtio vring_new_virtqueue() API;
44  *  - The notify function is implicit in the implementation, and not provided
45  *    by the client, as it is in Linux virtio.
46  *  - Broke into APIs to add/get used and avail buffers, as the API is
47  *    assymmetric.
48  *
49  *  Usage:
50  *     This IPC only works between one processor designated as the Host (Linux)
51  *     and one or more Slave processors (BIOS).
52  *
53  *     For any Host/Slave pair, there are 2 VirtQueues (aka Vrings);
54  *     Only the Host adds new buffers to the avail list of a vring;
55  *     Available buffers can be empty or full, depending on direction;
56  *     Used buffer means "processed" (emptied or filled);
57  *
58  *  Host:
59  *    - To send buffer to the slave processor:
60  *          add_avail_buf(slave_virtqueue);
61  *          kick(slave_virtqueue);
62  *          get_used_buf(slave_virtqueue);
63  *    - To receive buffer from slave processor:
64  *          add_avail_buf(host_virtqueue);
65  *          kick(host_virtqueue);
66  *          get_used_buf(host_virtqueue);
67  *
68  *  Slave:
69  *    - To send buffer to the host:
70  *          get_avail_buf(host_virtqueue);
71  *          add_used_buf(host_virtqueue);
72  *          kick(host_virtqueue);
73  *    - To receive buffer from the host:
74  *          get_avail_buf(slave_virtqueue);
75  *          add_used_buf(slave_virtqueue);
76  *          kick(slave_virtqueue);
77  *
78  *  All VirtQueue operations can be called in any context.
79  *
80  *  The virtio header should be included in an application as follows:
81  *  @code
82  *  #include <ti/ipc/rpmsg/VirtQueue.h>
83  *  @endcode
84  *
85  *  ============================================================================
86  */
88 #ifndef ti_ipc_family_omap54xx_VirtQueue__include
89 #define ti_ipc_family_omap54xx_VirtQueue__include
91 #include <xdc/runtime/Error.h>
93 #if defined (__cplusplus)
94 extern "C" {
95 #endif
97 /*!
98  *  @brief  VirtQueue Ids for the basic IPC transport rings.
99  */
100 #define ID_SELF_TO_A9      0
101 #define ID_A9_TO_SELF      1
103 /*!
104  *  @brief  a queue to register buffers for sending or receiving.
105  */
106 typedef struct VirtQueue_Object *VirtQueue_Handle;
108 /*!
109  *  @var     VirtQueue_callback
110  *  @brief   Signature of any callback function that can be registered with the
111  *           VirtQueue
112  *
113  *  @param[in]  VirtQueue     Pointer to the VirtQueue which was signalled.
114  */
115 typedef Void (*VirtQueue_callback)(VirtQueue_Handle);
117 /*!
118  *  @brief      VirtQueue_params
119  */
120 typedef struct VirtQueue_Params {
121     VirtQueue_callback callback;
122     Int vqId;
123 } VirtQueue_Params;
125 /* Params_init */
126 static inline void VirtQueue_Params_init( VirtQueue_Params *prms )
128     /* Do nothing: We are emulating an XDC generated fxn, w/o XDC config! */
131 /*!
132  *  @brief      Initialize at runtime the VirtQueue
133  *
134  *  @param[in]  procId    Processor ID associated with this VirtQueue.
135  *  @param[in]  params    VirtQueue_Params {callback, vqId}.
136  *  @param[in]  eb        Error_Block (or NULL).
137  *
138  *  @Returns    Returns a handle to a new initialized VirtQueue.
139  */
140 VirtQueue_Handle VirtQueue_create(UInt16 procId, VirtQueue_Params *params,
141                                   Error_Block *eb);
143 /*!
144  *  @brief      Notify other processor of new buffers in the queue.
145  *
146  *  After one or more add_buf calls, invoke this to kick the other side.
147  *
148  *  @param[in]  vq        the VirtQueue.
149  *
150  *  @sa         VirtQueue_addBuf
151  */
152 Void VirtQueue_kick(VirtQueue_Handle vq);
154 /*!
155  *  @brief       Used at startup-time for initialization
156  *
157  *  Should be called before any other VirtQueue APIs
158  */
159 Void VirtQueue_startup();
162 /*
163  *  ============================================================================
164  *  Host Only Functions:
165  *  ============================================================================
166  */
168 /*!
169  *  @brief      Add available buffer to virtqueue's available buffer list.
170  *              Only used by Host.
171  *
172  *  @param[in]  vq        the VirtQueue.
173  *  @param[in]  buf      the buffer to be processed by the slave.
174  *
175  *  @return     Remaining capacity of queue or a negative error.
176  *
177  *  @sa         VirtQueue_getUsedBuf
178  */
179 Int VirtQueue_addAvailBuf(VirtQueue_Handle vq, Void *buf);
181 /*!
182  *  @brief      Get the next used buffer.
183  *              Only used by Host.
184  *
185  *  @param[in]  vq        the VirtQueue.
186  *
187  *  @return     Returns NULL or the processed buffer.
188  *
189  *  @sa         VirtQueue_addAvailBuf
190  */
191 Void *VirtQueue_getUsedBuf(VirtQueue_Handle vq);
193 /*
194  *  ============================================================================
195  *  Slave Only Functions:
196  *  ============================================================================
197  */
199 /*!
200  *  @brief      Get the next available buffer.
201  *              Only used by Slave.
202  *
203  *  @param[in]  vq        the VirtQueue.
204  *  @param[out] buf       Pointer to location of available buffer;
205  *  @param[out] len       Length of the available buffer message.
206  *
207  *  @return     Returns a token used to identify the available buffer, to be
208  *              passed back into VirtQueue_addUsedBuf();
209  *              token is negative if failure to find an available buffer.
210  *
211  *  @sa         VirtQueue_addUsedBuf
212  */
213 Int16 VirtQueue_getAvailBuf(VirtQueue_Handle vq, Void **buf, Int *len);
215 /*!
216  *  @brief      Add used buffer to virtqueue's used buffer list.
217  *              Only used by Slave.
218  *
219  *  @param[in]  vq        the VirtQueue.
220  *  @param[in]  token     token of the buffer to be added to vring used list.
221  *  @param[in]  len       length of the message being added.
222  *
223  *  @return     Remaining capacity of queue or a negative error.
224  *
225  *  @sa         VirtQueue_getAvailBuf
226  */
227 Int VirtQueue_addUsedBuf(VirtQueue_Handle vq, Int16 token, Int len);
229 /*!
230  *  @brief      Post crash message to host mailbox
231  */
232 Void VirtQueue_postCrashToMailbox(Void);
234 #if defined (__cplusplus)
236 #endif /* defined (__cplusplus) */
238 #endif /* ti_ipc_family_omap54xx_VirtQueue__include */