99043f451cc937d4dcef911ef49c3830414e1e95
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_vayu_VirtQueue__include
89 #define ti_ipc_family_vayu_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 )
127 {
128 /* Do nothing: We are emulating an XDC generated fxn, w/o XDC config! */
129 }
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)
235 }
236 #endif /* defined (__cplusplus) */
238 #endif /* ti_ipc_family_vayu_VirtQueue__include */