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