[processor-sdk/performance-audio-sr.git] / ipc_3_43_00_00_eng / docs / cdoc / ti / ipc / family / tci6614 / VirtQueue-src.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html><head><title>module ti.ipc.family.tci6614.VirtQueue</title>
3 <meta name="googlebot" content="noindex,nofollow">
4 <link rel="stylesheet" type="text/css" href="../../../../src.css"/>
5 </head>
6 <body>
7 <pre class=src>
8 1 <span class="comment">/*
9 </span> 2 <span class="comment"> * Copyright (c) 2013-2015 Texas Instruments Incorporated - http://www.ti.com
10 </span> 3 <span class="comment"> * All rights reserved.
11 </span> 4 <span class="comment"> *
12 </span> 5 <span class="comment"> * Redistribution and use in source and binary forms, with or without
13 </span> 6 <span class="comment"> * modification, are permitted provided that the following conditions
14 </span> 7 <span class="comment"> * are met:
15 </span> 8 <span class="comment"> *
16 </span> 9 <span class="comment"> * * Redistributions of source code must retain the above copyright
17 </span> 10 <span class="comment"> * notice, this list of conditions and the following disclaimer.
18 </span> 11 <span class="comment"> *
19 </span> 12 <span class="comment"> * * Redistributions in binary form must reproduce the above copyright
20 </span> 13 <span class="comment"> * notice, this list of conditions and the following disclaimer in the
21 </span> 14 <span class="comment"> * documentation and/or other materials provided with the distribution.
22 </span> 15 <span class="comment"> *
23 </span> 16 <span class="comment"> * * Neither the name of Texas Instruments Incorporated nor the names of
24 </span> 17 <span class="comment"> * its contributors may be used to endorse or promote products derived
25 </span> 18 <span class="comment"> * from this software without specific prior written permission.
26 </span> 19 <span class="comment"> *
27 </span> 20 <span class="comment"> * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
28 </span> 21 <span class="comment"> * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
29 </span> 22 <span class="comment"> * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
30 </span> 23 <span class="comment"> * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
31 </span> 24 <span class="comment"> * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32 </span> 25 <span class="comment"> * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
33 </span> 26 <span class="comment"> * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
34 </span> 27 <span class="comment"> * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
35 </span> 28 <span class="comment"> * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
36 </span> 29 <span class="comment"> * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
37 </span> 30 <span class="comment"> * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 </span> 31 <span class="comment"> *
39 </span> 32 <span class="comment"> */</span>
40 33 <span class="comment">/** ============================================================================
41 </span> 34 <span class="comment"> * @file VirtQueue.xdc
42 </span> 35 <span class="comment"> *
43 </span> 36 <span class="comment"> * @brief Virtio Queue interface for BIOS
44 </span> 37 <span class="comment"> *
45 </span> 38 <span class="comment"> * Differences between BIOS version and Linux kernel (include/linux/virtio.h):
46 </span> 39 <span class="comment"> * - Renamed module from virtio.h to VirtQueue.h to match the API prefixes;
47 </span> 40 <span class="comment"> * - BIOS (XDC) types and CamelCasing used;
48 </span> 41 <span class="comment"> * - virtio_device concept removed (i.e, assumes no containing device);
49 </span> 42 <span class="comment"> * - removed scatterlist;
50 </span> 43 <span class="comment"> * - VirtQueues are created statically here, so just added a VirtQueue_init()
51 </span> 44 <span class="comment"> * fxn to take the place of the Virtio vring_new_virtqueue() API;
52 </span> 45 <span class="comment"> * - The notify function is implicit in the implementation, and not provided
53 </span> 46 <span class="comment"> * by the client, as it is in Linux virtio.
54 </span> 47 <span class="comment"> * - Broke into APIs to add/get used and avail buffers, as the API is
55 </span> 48 <span class="comment"> * assymmetric.
56 </span> 49 <span class="comment"> *
57 </span> 50 <span class="comment"> * Usage:
58 </span> 51 <span class="comment"> * This IPC only works between one processor designated as the Host (Linux)
59 </span> 52 <span class="comment"> * and one or more Slave processors (BIOS).
60 </span> 53 <span class="comment"> *
61 </span> 54 <span class="comment"> * For any Host/Slave pair, there are 2 VirtQueues (aka Vrings);
62 </span> 55 <span class="comment"> * Only the Host adds new buffers to the avail list of a vring;
63 </span> 56 <span class="comment"> * Available buffers can be empty or full, depending on direction;
64 </span> 57 <span class="comment"> * Used buffer means "processed" (emptied or filled);
65 </span> 58 <span class="comment"> *
66 </span> 59 <span class="comment"> * Host:
67 </span> 60 <span class="comment"> * - To send buffer to the slave processor:
68 </span> 61 <span class="comment"> * add_avail_buf(slave_virtqueue);
69 </span> 62 <span class="comment"> * kick(slave_virtqueue);
70 </span> 63 <span class="comment"> * get_used_buf(slave_virtqueue);
71 </span> 64 <span class="comment"> * - To receive buffer from slave processor:
72 </span> 65 <span class="comment"> * add_avail_buf(host_virtqueue);
73 </span> 66 <span class="comment"> * kick(host_virtqueue);
74 </span> 67 <span class="comment"> * get_used_buf(host_virtqueue);
75 </span> 68 <span class="comment"> *
76 </span> 69 <span class="comment"> * Slave:
77 </span> 70 <span class="comment"> * - To send buffer to the host:
78 </span> 71 <span class="comment"> * get_avail_buf(host_virtqueue);
79 </span> 72 <span class="comment"> * add_used_buf(host_virtqueue);
80 </span> 73 <span class="comment"> * kick(host_virtqueue);
81 </span> 74 <span class="comment"> * - To receive buffer from the host:
82 </span> 75 <span class="comment"> * get_avail_buf(slave_virtqueue);
83 </span> 76 <span class="comment"> * add_used_buf(slave_virtqueue);
84 </span> 77 <span class="comment"> * kick(slave_virtqueue);
85 </span> 78 <span class="comment"> *
86 </span> 79 <span class="comment"> * All VirtQueue operations can be called in any context.
87 </span> 80 <span class="comment"> *
88 </span> 81 <span class="comment"> * The virtio header should be included in an application as follows:
89 </span> 82 <span class="comment"> * @code
90 </span> 83 <span class="comment"> * #include <ti/ipc/rpmsg/VirtQueue.h>
91 </span> 84 <span class="comment"> * @endcode
92 </span> 85 <span class="comment"> *
93 </span> 86 <span class="comment"> * ============================================================================
94 </span> 87 <span class="comment"> */</span>
95 88
96 89 import ti.sysbios.knl.Swi;
97 90 import ti.sdo.utils.MultiProc;
98 91 import ti.sysbios.gates.GateAll;
99 92
100 93 <span class="xdoc">/*!
101 </span> 94 <span class="xdoc"> * ======== VirtQueue ========
102 </span> 95 <span class="xdoc"> */</span>
103 96 @InstanceInitError
104 97 @Template(<span class="string">"./VirtQueue.xdt"</span>)
105 98
106 99 <span class=key>module</span> VirtQueue
107 100 {
108 101 <span class=comment>// -------- Module Constants --------</span>
109 102
110 103 <span class=comment>// -------- Module Types --------</span>
111 104
112 105
113 106 <span class="xdoc">/*!
114 </span> 107 <span class="xdoc"> * ======== BasicView ========
115 </span> 108 <span class="xdoc"> * <b>@_nodoc</b>
116 </span> 109 <span class="xdoc"> */</span>
117 110 <span class=key>metaonly</span> <span class=key>struct</span> BasicView {
118 111
119 112 };
120 113
121 114 <span class="xdoc">/*!
122 </span> 115 <span class="xdoc"> * ======== ModuleView ========
123 </span> 116 <span class="xdoc"> * <b>@_nodoc</b>
124 </span> 117 <span class="xdoc"> */</span>
125 118 <span class=key>metaonly</span> <span class=key>struct</span> ModuleView {
126 119
127 120 };
128 121
129 122 <span class="xdoc">/*!
130 </span> 123 <span class="xdoc"> * ======== rovViewInfo ========
131 </span> 124 <span class="xdoc"> * <b>@_nodoc</b>
132 </span> 125 <span class="xdoc"> */</span>
133 126 <span class="comment">/* @Facet
134 </span> 127 <span class="comment"> metaonly config ViewInfo.Instance rovViewInfo =
135 </span> 128 <span class="comment"> xdc.rov.ViewInfo.create({
136 </span> 129 <span class="comment"> viewMap: [
137 </span> 130 <span class="comment"> ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
138 </span> 131 <span class="comment"> ['Module', {type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
139 </span> 132 <span class="comment"> ]
140 </span> 133 <span class="comment"> });
141 </span> 134 <span class="comment">*/</span>
142 135 <span class=comment>// -------- Module Proxies --------</span>
143 136
144 137 <span class=comment>// -------- Module Parameters --------</span>
145 138
146 139 <span class="comment">/* Predefined device addresses */</span>
147 140 <span class=key>config</span> UInt32 CORE0_MEM_VRING0 = 0xA0000000;
148 141 <span class=key>config</span> UInt32 CORE0_MEM_VRING1 = 0xA0004000;
149 142 <span class=key>config</span> UInt32 VRING_OFFSET = 0x00080000;
150 143
151 144 <span class="comment">/*
152 </span> 145 <span class="comment"> * Sizes of the virtqueues (expressed in number of buffers supported,
153 </span> 146 <span class="comment"> * and must be power of two)
154 </span> 147 <span class="comment"> */</span>
155 148 <span class=key>config</span> UInt VQ0_SIZE = 256;
156 149 <span class=key>config</span> UInt VQ1_SIZE = 256;
157 150
158 151 <span class="comment">/* See VirtQueue.c also for other constants: */</span>
159 152 <span class=key>config</span> UInt RP_MSG_NUM_BUFS = VQ0_SIZE; <span class="comment">/* must be power of two */</span>
160 153
161 154 <span class=key>config</span> UInt PAGE_SIZE = 4096;
162 155
163 156 <span class="comment">/*
164 </span> 157 <span class="comment"> * The alignment to use between consumer and producer parts of vring.
165 </span> 158 <span class="comment"> * Note: this is part of the "wire" protocol. If you change this, you need
166 </span> 159 <span class="comment"> * to update your BIOS image as well
167 </span> 160 <span class="comment"> */</span>
168 161 <span class=key>config</span> UInt RP_MSG_VRING_ALIGN = 4096;
169 162
170 163 <span class="xdoc">/*!
171 </span> 164 <span class="xdoc"> * ======== startup ========
172 </span> 165 <span class="xdoc"> *
173 </span> 166 <span class="xdoc"> * Plug interrupts, and if host, initialize vring memory and send
174 </span> 167 <span class="xdoc"> * startup sequence events to slave.
175 </span> 168 <span class="xdoc"> */</span>
176 169 Void startup(UInt16 remoteProcId, Bool isHost);
177 170
178 171 <span class="xdoc">/*!
179 </span> 172 <span class="xdoc"> * ======== cacheWb ========
180 </span> 173 <span class="xdoc"> * Flush the SysMin trace buffer
181 </span> 174 <span class="xdoc"> *
182 </span> 175 <span class="xdoc"> * This function should be configured as an idle function.
183 </span> 176 <span class="xdoc"> *
184 </span> 177 <span class="xdoc"> * <b>@p(code)</b>
185 </span> 178 <span class="xdoc"> * var Idle = xdc.useModule('ti.sysbios.knl.Idle');
186 </span> 179 <span class="xdoc"> * Idle.addFunc('&VirtQueue_cacheWb');
187 </span> 180 <span class="xdoc"> * <b>@p</b>
188 </span> 181 <span class="xdoc"> */</span>
189 182 Void cacheWb();
190 183
191 184 <span class=key>instance</span>:
192 185
193 186 <span class="xdoc">/*!
194 </span> 187 <span class="xdoc"> * <b>@brief</b> Initialize at runtime the VirtQueue
195 </span> 188 <span class="xdoc"> *
196 </span> 189 <span class="xdoc"> * Maps to Instance_init function
197 </span> 190 <span class="xdoc"> *
198 </span> 191 <span class="xdoc"> * <b>@param</b>[in] remoteProcId Remote processor ID associated with this VirtQueue.
199 </span> 192 <span class="xdoc"> *
200 </span> 193 <span class="xdoc"> * <b>@Returns</b> Returns a handle to a new initialized VirtQueue.
201 </span> 194 <span class="xdoc"> */</span>
202 195 @DirectCall
203 196 create(UInt16 remoteProcId);
204 197
205 198 <span class="xdoc">/*!
206 </span> 199 <span class="xdoc"> * <b>@brief</b> Notify other processor of new buffers in the queue.
207 </span> 200 <span class="xdoc"> *
208 </span> 201 <span class="xdoc"> * After one or more add_buf calls, invoke this to kick the other side.
209 </span> 202 <span class="xdoc"> *
210 </span> 203 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
211 </span> 204 <span class="xdoc"> *
212 </span> 205 <span class="xdoc"> * <b>@sa</b> VirtQueue_addBuf
213 </span> 206 <span class="xdoc"> */</span>
214 207 @DirectCall
215 208 Void kick();
216 209
217 210 <span class="xdoc">/*!
218 </span> 211 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns slave status
219 </span> 212 <span class="xdoc"> *
220 </span> 213 <span class="xdoc"> * Returns if this VirtQueue instance belongs to a slave
221 </span> 214 <span class="xdoc"> *
222 </span> 215 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
223 </span> 216 <span class="xdoc"> *
224 </span> 217 <span class="xdoc"> */</span>
225 218 @DirectCall
226 219 Bool isSlave();
227 220
228 221 <span class="xdoc">/*!
229 </span> 222 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns host status
230 </span> 223 <span class="xdoc"> *
231 </span> 224 <span class="xdoc"> * Returns if this VirtQueue instance belongs to a host
232 </span> 225 <span class="xdoc"> *
233 </span> 226 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
234 </span> 227 <span class="xdoc"> *
235 </span> 228 <span class="xdoc"> */</span>
236 229 @DirectCall
237 230 Bool isHost();
238 231
239 232 <span class="xdoc">/*!
240 </span> 233 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns queue ID
241 </span> 234 <span class="xdoc"> *
242 </span> 235 <span class="xdoc"> * Returns VirtQueue instance's queue ID.
243 </span> 236 <span class="xdoc"> *
244 </span> 237 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
245 </span> 238 <span class="xdoc"> *
246 </span> 239 <span class="xdoc"> */</span>
247 240 @DirectCall
248 241 UInt16 getId();
249 242
250 243 <span class="xdoc">/*!
251 </span> 244 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns Swi handle
252 </span> 245 <span class="xdoc"> *
253 </span> 246 <span class="xdoc"> * Returns VirtQueue instance Swi handle
254 </span> 247 <span class="xdoc"> *
255 </span> 248 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
256 </span> 249 <span class="xdoc"> *
257 </span> 250 <span class="xdoc"> */</span>
258 251 @DirectCall
259 252 Swi.Handle getSwiHandle();
260 253
261 254 <span class="comment">/*
262 </span> 255 <span class="comment"> * ========================================================================
263 </span> 256 <span class="comment"> * Host Only Functions:
264 </span> 257 <span class="comment"> * ========================================================================
265 </span> 258 <span class="comment"> */</span>
266 259
267 260 <span class="xdoc">/*!
268 </span> 261 <span class="xdoc"> * <b>@brief</b> Add available buffer to virtqueue's available buffer list.
269 </span> 262 <span class="xdoc"> * Only used by Host.
270 </span> 263 <span class="xdoc"> *
271 </span> 264 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
272 </span> 265 <span class="xdoc"> * <b>@param</b>[in] buf the buffer to be processed by the slave.
273 </span> 266 <span class="xdoc"> *
274 </span> 267 <span class="xdoc"> * <b>@return</b> Remaining capacity of queue or a negative error.
275 </span> 268 <span class="xdoc"> *
276 </span> 269 <span class="xdoc"> * <b>@sa</b> VirtQueue_getUsedBuf
277 </span> 270 <span class="xdoc"> */</span>
278 271 @DirectCall
279 272 Int addAvailBuf(Void *buf);
280 273
281 274 <span class="xdoc">/*!
282 </span> 275 <span class="xdoc"> * <b>@brief</b> Get the next used buffer.
283 </span> 276 <span class="xdoc"> * Only used by Host.
284 </span> 277 <span class="xdoc"> *
285 </span> 278 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
286 </span> 279 <span class="xdoc"> *
287 </span> 280 <span class="xdoc"> * <b>@return</b> Returns NULL or the processed buffer.
288 </span> 281 <span class="xdoc"> *
289 </span> 282 <span class="xdoc"> * <b>@sa</b> VirtQueue_addAvailBuf
290 </span> 283 <span class="xdoc"> */</span>
291 284 @DirectCall
292 285 Void *getUsedBuf();
293 286
294 287 <span class="comment">/*
295 </span> 288 <span class="comment"> * ========================================================================
296 </span> 289 <span class="comment"> * Slave Only Functions:
297 </span> 290 <span class="comment"> * ========================================================================
298 </span> 291 <span class="comment"> */</span>
299 292
300 293 <span class="xdoc">/*!
301 </span> 294 <span class="xdoc"> * <b>@brief</b> Get the next available buffer.
302 </span> 295 <span class="xdoc"> * Only used by Slave.
303 </span> 296 <span class="xdoc"> *
304 </span> 297 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
305 </span> 298 <span class="xdoc"> * <b>@param</b>[out] buf Pointer to location of available buffer;
306 </span> 299 <span class="xdoc"> * <b>@param</b>[out] len Length of the available buffer message.
307 </span> 300 <span class="xdoc"> *
308 </span> 301 <span class="xdoc"> * <b>@return</b> Returns a token used to identify the available buffer, to be
309 </span> 302 <span class="xdoc"> * passed back into VirtQueue_addUsedBuf();
310 </span> 303 <span class="xdoc"> * token is negative if failure to find an available buffer.
311 </span> 304 <span class="xdoc"> *
312 </span> 305 <span class="xdoc"> * <b>@sa</b> VirtQueue_addUsedBuf
313 </span> 306 <span class="xdoc"> */</span>
314 307 @DirectCall
315 308 Int16 getAvailBuf(Void **buf, Int *len);
316 309
317 310 <span class="xdoc">/*!
318 </span> 311 <span class="xdoc"> * <b>@brief</b> Add used buffer to virtqueue's used buffer list.
319 </span> 312 <span class="xdoc"> * Only used by Slave.
320 </span> 313 <span class="xdoc"> *
321 </span> 314 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
322 </span> 315 <span class="xdoc"> * <b>@param</b>[in] token token of the buffer added to vring used list.
323 </span> 316 <span class="xdoc"> * <b>@param</b>[in] len length of the message being added.
324 </span> 317 <span class="xdoc"> *
325 </span> 318 <span class="xdoc"> * <b>@return</b> Remaining capacity of queue or a negative error.
326 </span> 319 <span class="xdoc"> *
327 </span> 320 <span class="xdoc"> * <b>@sa</b> VirtQueue_getAvailBuf
328 </span> 321 <span class="xdoc"> */</span>
329 322 @DirectCall
330 323 Int addUsedBuf(Int16 token, Int len);
331 324
332 325 <span class=comment>// -------- Handle Parameters --------</span>
333 326
334 327 <span class=key>config</span> Bool host = <span class=key>false</span>;
335 328
336 329 <span class=key>config</span> Fxn callback = <span class=key>null</span>;
337 330
338 331 <span class=key>config</span> Swi.Handle swiHandle = <span class=key>null</span>;
339 332
340 333 <span class=key>config</span> UInt intVectorId = ~1u;
341 334
342 335 <span class=key>config</span> Int vqId = 0;
343 336
344 337 <span class=comment>// -------- Handle Functions --------</span>
345 338
346 339 <span class=key>internal</span>: <span class="comment">/* not for client use */</span>
347 340
348 341 <span class="xdoc">/*! Statically retrieve procIds to avoid doing this at runtime */</span>
349 342 <span class=key>config</span> UInt hostProcId = MultiProc.INVALIDID;
350 343
351 344 <span class=key>void</span> init();
352 345
353 346 <span class="xdoc">/*!
354 </span> 347 <span class="xdoc"> * ======== hostIsr ========
355 </span> 348 <span class="xdoc"> */</span>
356 349 Void hostIsr(UArg msg);
357 350
358 351 <span class="xdoc">/*!
359 </span> 352 <span class="xdoc"> * ======== slaveIsr ========
360 </span> 353 <span class="xdoc"> */</span>
361 354 Void slaveIsr(UArg msg);
362 355
363 356 <span class="xdoc">/*!
364 </span> 357 <span class="xdoc"> * ======== Module_State ========
365 </span> 358 <span class="xdoc"> * <b>@_nodoc</b>
366 </span> 359 <span class="xdoc"> */</span>
367 360 <span class=key>struct</span> Module_State
368 361 {
369 362 UInt16 hostSlaveSynced;
370 363 UInt16 virtQueueInitialized;
371 364 UInt32 *queueRegistry;
372 365 Ptr traceBufPtr;
373 366 }
374 367
375 368 <span class="xdoc">/*!
376 </span> 369 <span class="xdoc"> * ======== Instance_State ========
377 </span> 370 <span class="xdoc"> * <b>@_nodoc</b>
378 </span> 371 <span class="xdoc"> */</span>
379 372 <span class=key>struct</span> Instance_State {
380 373 Bool hostSlaveSynced;
381 374 UInt16 id;
382 375 Fxn callback;
383 376 Swi.Handle swiHandle;
384 377 Void *vringPtr;
385 378 UInt16 num_free;
386 379 UInt16 last_avail_idx;
387 380 UInt16 last_used_idx;
388 381 UInt16 procId;
389 382 GateAll.Handle gateH;
390 383 };
391 384 }
392 </pre>
393 </body></html>