am65xx: Remove dependence on DEVMEM entry
[ipc/ipcdev.git] / packages / ti / ipc / family / tci6638 / VirtQueue.xdc
1 /*
2  * Copyright (c) 2013-2015 Texas Instruments Incorporated - http://www.ti.com
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 /** ============================================================================
34  *  @file       VirtQueue.xdc
35  *
36  *  @brief      Virtio Queue interface for BIOS
37  *
38  *  Differences between BIOS version and Linux kernel (include/linux/virtio.h):
39  *  - Renamed module from virtio.h to VirtQueue.h to match the API prefixes;
40  *  - BIOS (XDC) types and CamelCasing used;
41  *  - virtio_device concept removed (i.e, assumes no containing device);
42  *  - removed scatterlist;
43  *  - VirtQueues are created statically here, so just added a VirtQueue_init()
44  *    fxn to take the place of the Virtio vring_new_virtqueue() API;
45  *  - The notify function is implicit in the implementation, and not provided
46  *    by the client, as it is in Linux virtio.
47  *  - Broke into APIs to add/get used and avail buffers, as the API is
48  *    assymmetric.
49  *
50  *  Usage:
51  *     This IPC only works between one processor designated as the Host (Linux)
52  *     and one or more Slave processors (BIOS).
53  *
54  *     For any Host/Slave pair, there are 2 VirtQueues (aka Vrings);
55  *     Only the Host adds new buffers to the avail list of a vring;
56  *     Available buffers can be empty or full, depending on direction;
57  *     Used buffer means "processed" (emptied or filled);
58  *
59  *  Host:
60  *    - To send buffer to the slave processor:
61  *          add_avail_buf(slave_virtqueue);
62  *          kick(slave_virtqueue);
63  *          get_used_buf(slave_virtqueue);
64  *    - To receive buffer from slave processor:
65  *          add_avail_buf(host_virtqueue);
66  *          kick(host_virtqueue);
67  *          get_used_buf(host_virtqueue);
68  *
69  *  Slave:
70  *    - To send buffer to the host:
71  *          get_avail_buf(host_virtqueue);
72  *          add_used_buf(host_virtqueue);
73  *          kick(host_virtqueue);
74  *    - To receive buffer from the host:
75  *          get_avail_buf(slave_virtqueue);
76  *          add_used_buf(slave_virtqueue);
77  *          kick(slave_virtqueue);
78  *
79  *  All VirtQueue operations can be called in any context.
80  *
81  *  The virtio header should be included in an application as follows:
82  *  @code
83  *  #include <ti/ipc/rpmsg/VirtQueue.h>
84  *  @endcode
85  *
86  *  ============================================================================
87  */
88 package ti.ipc.family.tci6638;
90 import ti.sdo.ipc.notifyDrivers.IInterrupt;
91 import ti.sdo.utils.MultiProc;
92 import ti.sysbios.gates.GateAll;
93 import ti.sysbios.knl.Swi;
95 /*!
96  *  ======== VirtQueue ========
97  */
98 @InstanceInitError
99 @Template("./VirtQueue.xdt")
101 module VirtQueue
103     // -------- Module Constants --------
105     // -------- Module Types --------
108     /*!
109      *  ======== BasicView ========
110      *  @_nodoc
111      */
112     metaonly struct BasicView {
114     };
116     /*!
117      *  ======== ModuleView ========
118      *  @_nodoc
119      */
120     metaonly struct ModuleView {
122     };
124     /*!
125      *  ======== rovViewInfo ========
126      *  @_nodoc
127      */
128 /*    @Facet
129     metaonly config ViewInfo.Instance rovViewInfo =
130         xdc.rov.ViewInfo.create({
131             viewMap: [
132                 ['Basic',  {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',  structName: 'BasicView'}],
133                 ['Module', {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
134             ]
135          });
136 */
137     // -------- Module Proxies --------
139     /*! @_nodoc
140      *  IInterrupt proxy that handles interrupts between multiple CPU cores
141      */
142     proxy InterruptProxy inherits IInterrupt;
144     // -------- Module Parameters --------
146     /* Per Core offset of start of VRING control structures from CORE0 */
147     config UInt32 VRING_OFFSET = 0x00080000;
149     /*
150      * Sizes of the virtqueues (expressed in number of buffers supported,
151      * and must be power of two)
152      */
153     config UInt VQ0_SIZE = 256;
154     config UInt VQ1_SIZE = 256;
156     /* See VirtQueue.c also for other constants:   */
157     config UInt RP_MSG_NUM_BUFS = VQ0_SIZE; /* must be power of two */
159     config UInt PAGE_SIZE = 4096;
161     /*
162      * The alignment to use between consumer and producer parts of vring.
163      * Note: this is part of the "wire" protocol. If you change this, you need
164      * to update your BIOS image as well
165      */
166     config UInt RP_MSG_VRING_ALIGN = 4096;
168    /*!
169     * ======== startup ========
170     *
171     * Plug interrupts, and if host, initialize vring memory and send
172     * startup sequence events to slave.
173     */
174     Void startup(UInt16 remoteProcId, Bool isHost);
176     /*!
177      *  ======== cacheWb ========
178      *  Flush the SysMin trace buffer
179      *
180      *  This function should be configured as an idle function.
181      *
182      *  @p(code)
183      *  var Idle = xdc.useModule('ti.sysbios.knl.Idle');
184      *  Idle.addFunc('&VirtQueue_cacheWb');
185      *  @p
186      */
187     Void cacheWb();
189 instance:
191     /*!
192      *  @brief      Initialize at runtime the VirtQueue
193      *
194      *  Maps to Instance_init function
195      *
196      *  @param[in]  remoteProcId    Remote processor ID associated with this VirtQueue.
197      *
198      *  @Returns    Returns a handle to a new initialized VirtQueue.
199      */
200     @DirectCall
201     create(UInt16 remoteProcId);
203     /*!
204      *  @brief      Notify other processor of new buffers in the queue.
205      *
206      *  After one or more add_buf calls, invoke this to kick the other side.
207      *
208      *  @param[in]  vq        the VirtQueue.
209      *
210      *  @sa         VirtQueue_addBuf
211      */
212     @DirectCall
213     Void kick();
215     /*!
216      *  @brief      VirtQueue instance returns slave status
217      *
218      *  Returns if this VirtQueue instance belongs to a slave
219      *
220      *  @param[in]  vq        the VirtQueue.
221      *
222      */
223     @DirectCall
224     Bool isSlave();
226     /*!
227      *  @brief      VirtQueue instance returns host status
228      *
229      *  Returns if this VirtQueue instance belongs to a host
230      *
231      *  @param[in]  vq        the VirtQueue.
232      *
233      */
234     @DirectCall
235     Bool isHost();
237     /*!
238      *  @brief      VirtQueue instance returns queue ID
239      *
240      *  Returns VirtQueue instance's queue ID.
241      *
242      *  @param[in]  vq        the VirtQueue.
243      *
244      */
245     @DirectCall
246     UInt16 getId();
248     /*!
249      *  @brief      VirtQueue instance returns Swi handle
250      *
251      *  Returns VirtQueue instance Swi handle
252      *
253      *  @param[in]  vq        the VirtQueue.
254      *
255      */
256     @DirectCall
257     Swi.Handle getSwiHandle();
259     /*
260      *  ========================================================================
261      *  Host Only Functions:
262      *  ========================================================================
263      */
265     /*!
266      *  @brief      Add available buffer to virtqueue's available buffer list.
267      *              Only used by Host.
268      *
269      *  @param[in]  vq        the VirtQueue.
270      *  @param[in]  buf      the buffer to be processed by the slave.
271      *
272      *  @return     Remaining capacity of queue or a negative error.
273      *
274      *  @sa         VirtQueue_getUsedBuf
275      */
276     @DirectCall
277     Int addAvailBuf(Void *buf);
279     /*!
280      *  @brief      Get the next used buffer.
281      *              Only used by Host.
282      *
283      *  @param[in]  vq        the VirtQueue.
284      *
285      *  @return     Returns NULL or the processed buffer.
286      *
287      *  @sa         VirtQueue_addAvailBuf
288      */
289     @DirectCall
290     Void *getUsedBuf();
292     /*
293      *  ========================================================================
294      *  Slave Only Functions:
295      *  ========================================================================
296      */
298     /*!
299      *  @brief      Get the next available buffer.
300      *              Only used by Slave.
301      *
302      *  @param[in]  vq        the VirtQueue.
303      *  @param[out] buf       Pointer to location of available buffer;
304      *  @param[out] len       Length of the available buffer message.
305      *
306      *  @return     Returns a token used to identify the available buffer, to be
307      *              passed back into VirtQueue_addUsedBuf();
308      *              token is negative if failure to find an available buffer.
309      *
310      *  @sa         VirtQueue_addUsedBuf
311      */
312     @DirectCall
313     Int16 getAvailBuf(Void **buf, Int *len);
315     /*!
316      *  @brief      Add used buffer to virtqueue's used buffer list.
317      *              Only used by Slave.
318      *
319      *  @param[in]  vq        the VirtQueue.
320      *  @param[in]  token     token of the buffer added to vring used list.
321      *  @param[in]  len       length of the message being added.
322      *
323      *  @return     Remaining capacity of queue or a negative error.
324      *
325      *  @sa         VirtQueue_getAvailBuf
326      */
327     @DirectCall
328     Int addUsedBuf(Int16 token, Int len);
330     // -------- Handle Parameters --------
332     config Bool host = false;
334     config Fxn callback = null;
336     config Swi.Handle swiHandle = null;
338     config UInt intVectorId = ~1u;
340     config Int vqId = 0;
342     // -------- Handle Functions --------
344 internal:   /* not for client use */
346     void init();
348     /*!
349      *  ======== hostIsr ========
350      */
351     Void hostIsr(UArg msg);
353     /*!
354      *  ======== slaveIsr ========
355      */
356     Void slaveIsr(UArg msg);
358     /*!
359      * ======== Module_State ========
360      * @_nodoc
361      */
362     struct Module_State
363     {
364         UInt16 hostSlaveSynced;
365         UInt16 virtQueueInitialized;
366         UInt32 *queueRegistry;
367         Ptr    traceBufPtr;
368     }
370     /*!
371      *  ======== Instance_State ========
372      *  @_nodoc
373      */
374     struct Instance_State {
375         Bool hostSlaveSynced;
376         UInt16 id;
377         Fxn callback;
378         Swi.Handle swiHandle;
379         Void *vringPtr;
380         UInt16 num_free;
381         UInt16 last_avail_idx;
382         UInt16 last_used_idx;
383         UInt16 procId;
384         GateAll.Handle gateH;
385     };