[processor-sdk/performance-audio-sr.git] / processor_audio_sdk_1_00_00_00 / psdk_cust / ipc_3_43_00_00_eng / docs / cdoc / ti / ipc / family / tci6638 / 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.tci6638.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 <span class=key>package</span> ti.ipc.family.tci6638;
96 89
97 90 import ti.sdo.ipc.notifyDrivers.IInterrupt;
98 91 import ti.sdo.utils.MultiProc;
99 92 import ti.sysbios.gates.GateAll;
100 93 import ti.sysbios.knl.Swi;
101 94
102 95 <span class="xdoc">/*!
103 </span> 96 <span class="xdoc"> * ======== VirtQueue ========
104 </span> 97 <span class="xdoc"> */</span>
105 98 @InstanceInitError
106 99 @Template(<span class="string">"./VirtQueue.xdt"</span>)
107 100
108 101 <span class=key>module</span> VirtQueue
109 102 {
110 103 <span class=comment>// -------- Module Constants --------</span>
111 104
112 105 <span class=comment>// -------- Module Types --------</span>
113 106
114 107
115 108 <span class="xdoc">/*!
116 </span> 109 <span class="xdoc"> * ======== BasicView ========
117 </span> 110 <span class="xdoc"> * <b>@_nodoc</b>
118 </span> 111 <span class="xdoc"> */</span>
119 112 <span class=key>metaonly</span> <span class=key>struct</span> BasicView {
120 113
121 114 };
122 115
123 116 <span class="xdoc">/*!
124 </span> 117 <span class="xdoc"> * ======== ModuleView ========
125 </span> 118 <span class="xdoc"> * <b>@_nodoc</b>
126 </span> 119 <span class="xdoc"> */</span>
127 120 <span class=key>metaonly</span> <span class=key>struct</span> ModuleView {
128 121
129 122 };
130 123
131 124 <span class="xdoc">/*!
132 </span> 125 <span class="xdoc"> * ======== rovViewInfo ========
133 </span> 126 <span class="xdoc"> * <b>@_nodoc</b>
134 </span> 127 <span class="xdoc"> */</span>
135 128 <span class="comment">/* @Facet
136 </span> 129 <span class="comment"> metaonly config ViewInfo.Instance rovViewInfo =
137 </span> 130 <span class="comment"> xdc.rov.ViewInfo.create({
138 </span> 131 <span class="comment"> viewMap: [
139 </span> 132 <span class="comment"> ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
140 </span> 133 <span class="comment"> ['Module', {type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
141 </span> 134 <span class="comment"> ]
142 </span> 135 <span class="comment"> });
143 </span> 136 <span class="comment">*/</span>
144 137 <span class=comment>// -------- Module Proxies --------</span>
145 138
146 139 <span class="xdoc">/*! <b>@_nodoc</b>
147 </span> 140 <span class="xdoc"> * IInterrupt proxy that handles interrupts between multiple CPU cores
148 </span> 141 <span class="xdoc"> */</span>
149 142 <span class=key>proxy</span> InterruptProxy <span class=key>inherits</span> IInterrupt;
150 143
151 144 <span class=comment>// -------- Module Parameters --------</span>
152 145
153 146 <span class="comment">/* Per Core offset of start of VRING control structures from CORE0 */</span>
154 147 <span class=key>config</span> UInt32 VRING_OFFSET = 0x00080000;
155 148
156 149 <span class="comment">/*
157 </span> 150 <span class="comment"> * Sizes of the virtqueues (expressed in number of buffers supported,
158 </span> 151 <span class="comment"> * and must be power of two)
159 </span> 152 <span class="comment"> */</span>
160 153 <span class=key>config</span> UInt VQ0_SIZE = 256;
161 154 <span class=key>config</span> UInt VQ1_SIZE = 256;
162 155
163 156 <span class="comment">/* See VirtQueue.c also for other constants: */</span>
164 157 <span class=key>config</span> UInt RP_MSG_NUM_BUFS = VQ0_SIZE; <span class="comment">/* must be power of two */</span>
165 158
166 159 <span class=key>config</span> UInt PAGE_SIZE = 4096;
167 160
168 161 <span class="comment">/*
169 </span> 162 <span class="comment"> * The alignment to use between consumer and producer parts of vring.
170 </span> 163 <span class="comment"> * Note: this is part of the "wire" protocol. If you change this, you need
171 </span> 164 <span class="comment"> * to update your BIOS image as well
172 </span> 165 <span class="comment"> */</span>
173 166 <span class=key>config</span> UInt RP_MSG_VRING_ALIGN = 4096;
174 167
175 168 <span class="xdoc">/*!
176 </span> 169 <span class="xdoc"> * ======== startup ========
177 </span> 170 <span class="xdoc"> *
178 </span> 171 <span class="xdoc"> * Plug interrupts, and if host, initialize vring memory and send
179 </span> 172 <span class="xdoc"> * startup sequence events to slave.
180 </span> 173 <span class="xdoc"> */</span>
181 174 Void startup(UInt16 remoteProcId, Bool isHost);
182 175
183 176 <span class="xdoc">/*!
184 </span> 177 <span class="xdoc"> * ======== cacheWb ========
185 </span> 178 <span class="xdoc"> * Flush the SysMin trace buffer
186 </span> 179 <span class="xdoc"> *
187 </span> 180 <span class="xdoc"> * This function should be configured as an idle function.
188 </span> 181 <span class="xdoc"> *
189 </span> 182 <span class="xdoc"> * <b>@p(code)</b>
190 </span> 183 <span class="xdoc"> * var Idle = xdc.useModule('ti.sysbios.knl.Idle');
191 </span> 184 <span class="xdoc"> * Idle.addFunc('&VirtQueue_cacheWb');
192 </span> 185 <span class="xdoc"> * <b>@p</b>
193 </span> 186 <span class="xdoc"> */</span>
194 187 Void cacheWb();
195 188
196 189 <span class=key>instance</span>:
197 190
198 191 <span class="xdoc">/*!
199 </span> 192 <span class="xdoc"> * <b>@brief</b> Initialize at runtime the VirtQueue
200 </span> 193 <span class="xdoc"> *
201 </span> 194 <span class="xdoc"> * Maps to Instance_init function
202 </span> 195 <span class="xdoc"> *
203 </span> 196 <span class="xdoc"> * <b>@param</b>[in] remoteProcId Remote processor ID associated with this VirtQueue.
204 </span> 197 <span class="xdoc"> *
205 </span> 198 <span class="xdoc"> * <b>@Returns</b> Returns a handle to a new initialized VirtQueue.
206 </span> 199 <span class="xdoc"> */</span>
207 200 @DirectCall
208 201 create(UInt16 remoteProcId);
209 202
210 203 <span class="xdoc">/*!
211 </span> 204 <span class="xdoc"> * <b>@brief</b> Notify other processor of new buffers in the queue.
212 </span> 205 <span class="xdoc"> *
213 </span> 206 <span class="xdoc"> * After one or more add_buf calls, invoke this to kick the other side.
214 </span> 207 <span class="xdoc"> *
215 </span> 208 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
216 </span> 209 <span class="xdoc"> *
217 </span> 210 <span class="xdoc"> * <b>@sa</b> VirtQueue_addBuf
218 </span> 211 <span class="xdoc"> */</span>
219 212 @DirectCall
220 213 Void kick();
221 214
222 215 <span class="xdoc">/*!
223 </span> 216 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns slave status
224 </span> 217 <span class="xdoc"> *
225 </span> 218 <span class="xdoc"> * Returns if this VirtQueue instance belongs to a slave
226 </span> 219 <span class="xdoc"> *
227 </span> 220 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
228 </span> 221 <span class="xdoc"> *
229 </span> 222 <span class="xdoc"> */</span>
230 223 @DirectCall
231 224 Bool isSlave();
232 225
233 226 <span class="xdoc">/*!
234 </span> 227 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns host status
235 </span> 228 <span class="xdoc"> *
236 </span> 229 <span class="xdoc"> * Returns if this VirtQueue instance belongs to a host
237 </span> 230 <span class="xdoc"> *
238 </span> 231 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
239 </span> 232 <span class="xdoc"> *
240 </span> 233 <span class="xdoc"> */</span>
241 234 @DirectCall
242 235 Bool isHost();
243 236
244 237 <span class="xdoc">/*!
245 </span> 238 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns queue ID
246 </span> 239 <span class="xdoc"> *
247 </span> 240 <span class="xdoc"> * Returns VirtQueue instance's queue ID.
248 </span> 241 <span class="xdoc"> *
249 </span> 242 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
250 </span> 243 <span class="xdoc"> *
251 </span> 244 <span class="xdoc"> */</span>
252 245 @DirectCall
253 246 UInt16 getId();
254 247
255 248 <span class="xdoc">/*!
256 </span> 249 <span class="xdoc"> * <b>@brief</b> VirtQueue instance returns Swi handle
257 </span> 250 <span class="xdoc"> *
258 </span> 251 <span class="xdoc"> * Returns VirtQueue instance Swi handle
259 </span> 252 <span class="xdoc"> *
260 </span> 253 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
261 </span> 254 <span class="xdoc"> *
262 </span> 255 <span class="xdoc"> */</span>
263 256 @DirectCall
264 257 Swi.Handle getSwiHandle();
265 258
266 259 <span class="comment">/*
267 </span> 260 <span class="comment"> * ========================================================================
268 </span> 261 <span class="comment"> * Host Only Functions:
269 </span> 262 <span class="comment"> * ========================================================================
270 </span> 263 <span class="comment"> */</span>
271 264
272 265 <span class="xdoc">/*!
273 </span> 266 <span class="xdoc"> * <b>@brief</b> Add available buffer to virtqueue's available buffer list.
274 </span> 267 <span class="xdoc"> * Only used by Host.
275 </span> 268 <span class="xdoc"> *
276 </span> 269 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
277 </span> 270 <span class="xdoc"> * <b>@param</b>[in] buf the buffer to be processed by the slave.
278 </span> 271 <span class="xdoc"> *
279 </span> 272 <span class="xdoc"> * <b>@return</b> Remaining capacity of queue or a negative error.
280 </span> 273 <span class="xdoc"> *
281 </span> 274 <span class="xdoc"> * <b>@sa</b> VirtQueue_getUsedBuf
282 </span> 275 <span class="xdoc"> */</span>
283 276 @DirectCall
284 277 Int addAvailBuf(Void *buf);
285 278
286 279 <span class="xdoc">/*!
287 </span> 280 <span class="xdoc"> * <b>@brief</b> Get the next used buffer.
288 </span> 281 <span class="xdoc"> * Only used by Host.
289 </span> 282 <span class="xdoc"> *
290 </span> 283 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
291 </span> 284 <span class="xdoc"> *
292 </span> 285 <span class="xdoc"> * <b>@return</b> Returns NULL or the processed buffer.
293 </span> 286 <span class="xdoc"> *
294 </span> 287 <span class="xdoc"> * <b>@sa</b> VirtQueue_addAvailBuf
295 </span> 288 <span class="xdoc"> */</span>
296 289 @DirectCall
297 290 Void *getUsedBuf();
298 291
299 292 <span class="comment">/*
300 </span> 293 <span class="comment"> * ========================================================================
301 </span> 294 <span class="comment"> * Slave Only Functions:
302 </span> 295 <span class="comment"> * ========================================================================
303 </span> 296 <span class="comment"> */</span>
304 297
305 298 <span class="xdoc">/*!
306 </span> 299 <span class="xdoc"> * <b>@brief</b> Get the next available buffer.
307 </span> 300 <span class="xdoc"> * Only used by Slave.
308 </span> 301 <span class="xdoc"> *
309 </span> 302 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
310 </span> 303 <span class="xdoc"> * <b>@param</b>[out] buf Pointer to location of available buffer;
311 </span> 304 <span class="xdoc"> * <b>@param</b>[out] len Length of the available buffer message.
312 </span> 305 <span class="xdoc"> *
313 </span> 306 <span class="xdoc"> * <b>@return</b> Returns a token used to identify the available buffer, to be
314 </span> 307 <span class="xdoc"> * passed back into VirtQueue_addUsedBuf();
315 </span> 308 <span class="xdoc"> * token is negative if failure to find an available buffer.
316 </span> 309 <span class="xdoc"> *
317 </span> 310 <span class="xdoc"> * <b>@sa</b> VirtQueue_addUsedBuf
318 </span> 311 <span class="xdoc"> */</span>
319 312 @DirectCall
320 313 Int16 getAvailBuf(Void **buf, Int *len);
321 314
322 315 <span class="xdoc">/*!
323 </span> 316 <span class="xdoc"> * <b>@brief</b> Add used buffer to virtqueue's used buffer list.
324 </span> 317 <span class="xdoc"> * Only used by Slave.
325 </span> 318 <span class="xdoc"> *
326 </span> 319 <span class="xdoc"> * <b>@param</b>[in] vq the VirtQueue.
327 </span> 320 <span class="xdoc"> * <b>@param</b>[in] token token of the buffer added to vring used list.
328 </span> 321 <span class="xdoc"> * <b>@param</b>[in] len length of the message being added.
329 </span> 322 <span class="xdoc"> *
330 </span> 323 <span class="xdoc"> * <b>@return</b> Remaining capacity of queue or a negative error.
331 </span> 324 <span class="xdoc"> *
332 </span> 325 <span class="xdoc"> * <b>@sa</b> VirtQueue_getAvailBuf
333 </span> 326 <span class="xdoc"> */</span>
334 327 @DirectCall
335 328 Int addUsedBuf(Int16 token, Int len);
336 329
337 330 <span class=comment>// -------- Handle Parameters --------</span>
338 331
339 332 <span class=key>config</span> Bool host = <span class=key>false</span>;
340 333
341 334 <span class=key>config</span> Fxn callback = <span class=key>null</span>;
342 335
343 336 <span class=key>config</span> Swi.Handle swiHandle = <span class=key>null</span>;
344 337
345 338 <span class=key>config</span> UInt intVectorId = ~1u;
346 339
347 340 <span class=key>config</span> Int vqId = 0;
348 341
349 342 <span class=comment>// -------- Handle Functions --------</span>
350 343
351 344 <span class=key>internal</span>: <span class="comment">/* not for client use */</span>
352 345
353 346 <span class=key>void</span> init();
354 347
355 348 <span class="xdoc">/*!
356 </span> 349 <span class="xdoc"> * ======== hostIsr ========
357 </span> 350 <span class="xdoc"> */</span>
358 351 Void hostIsr(UArg msg);
359 352
360 353 <span class="xdoc">/*!
361 </span> 354 <span class="xdoc"> * ======== slaveIsr ========
362 </span> 355 <span class="xdoc"> */</span>
363 356 Void slaveIsr(UArg msg);
364 357
365 358 <span class="xdoc">/*!
366 </span> 359 <span class="xdoc"> * ======== Module_State ========
367 </span> 360 <span class="xdoc"> * <b>@_nodoc</b>
368 </span> 361 <span class="xdoc"> */</span>
369 362 <span class=key>struct</span> Module_State
370 363 {
371 364 UInt16 hostSlaveSynced;
372 365 UInt16 virtQueueInitialized;
373 366 UInt32 *queueRegistry;
374 367 Ptr traceBufPtr;
375 368 }
376 369
377 370 <span class="xdoc">/*!
378 </span> 371 <span class="xdoc"> * ======== Instance_State ========
379 </span> 372 <span class="xdoc"> * <b>@_nodoc</b>
380 </span> 373 <span class="xdoc"> */</span>
381 374 <span class=key>struct</span> Instance_State {
382 375 Bool hostSlaveSynced;
383 376 UInt16 id;
384 377 Fxn callback;
385 378 Swi.Handle swiHandle;
386 379 Void *vringPtr;
387 380 UInt16 num_free;
388 381 UInt16 last_avail_idx;
389 382 UInt16 last_used_idx;
390 383 UInt16 procId;
391 384 GateAll.Handle gateH;
392 385 };
393 386 }
394 </pre>
395 </body></html>