packages/ti/ipc/family/omap54xx/VirtQueue.h

   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  */
  87
  88 #ifndef ti_ipc_family_omap54xx_VirtQueue__include
  89 #define ti_ipc_family_omap54xx_VirtQueue__include
  90
  91 #include <xdc/runtime/Error.h>
  92
  93 #if defined (__cplusplus)
  94 extern "C" {
  95 #endif
  96
  97 /*!
  98  *  @brief  a queue to register buffers for sending or receiving.
  99  */
 100 typedef struct VirtQueue_Object *VirtQueue_Handle;
 101
 102 /*!
 103  *  @var     VirtQueue_callback
 104  *  @brief   Signature of any callback function that can be registered with the
 105  *           VirtQueue
 106  *
 107  *  @param[in]  VirtQueue     Pointer to the VirtQueue which was signalled.
 108  */
 109 typedef Void (*VirtQueue_callback)(VirtQueue_Handle);
 110
 111 /*!
 112  *  @brief      VirtQueue_params
 113  */
 114 typedef struct VirtQueue_Params {
 115     VirtQueue_callback callback;
 116     Int vqId;
 117 } VirtQueue_Params;
 118
 119 /* Params_init */
 120 static inline void VirtQueue_Params_init( VirtQueue_Params *prms )
 121 {
 122     /* Do nothing: We are emulating an XDC generated fxn, w/o XDC config! */
 123 }
 124
 125 /*!
 126  *  @brief      Initialize at runtime the VirtQueue
 127  *
 128  *  @param[in]  procId    Processor ID associated with this VirtQueue.
 129  *  @param[in]  params    VirtQueue_Params {callback, vqId}.
 130  *  @param[in]  eb        Error_Block (or NULL).
 131  *
 132  *  @Returns    Returns a handle to a new initialized VirtQueue.
 133  */
 134 VirtQueue_Handle VirtQueue_create(UInt16 procId, VirtQueue_Params *params,
 135                                   Error_Block *eb);
 136
 137 /*!
 138  *  @brief      Notify other processor of new buffers in the queue.
 139  *
 140  *  After one or more add_buf calls, invoke this to kick the other side.
 141  *
 142  *  @param[in]  vq        the VirtQueue.
 143  *
 144  *  @sa         VirtQueue_addBuf
 145  */
 146 Void VirtQueue_kick(VirtQueue_Handle vq);
 147
 148 /*!
 149  *  @brief       Used at startup-time for initialization
 150  *
 151  *  Should be called before any other VirtQueue APIs
 152  */
 153 Void VirtQueue_startup();
 154
 155
 156 /*
 157  *  ============================================================================
 158  *  Host Only Functions:
 159  *  ============================================================================
 160  */
 161
 162 /*!
 163  *  @brief      Add available buffer to virtqueue's available buffer list.
 164  *              Only used by Host.
 165  *
 166  *  @param[in]  vq        the VirtQueue.
 167  *  @param[in]  buf      the buffer to be processed by the slave.
 168  *
 169  *  @return     Remaining capacity of queue or a negative error.
 170  *
 171  *  @sa         VirtQueue_getUsedBuf
 172  */
 173 Int VirtQueue_addAvailBuf(VirtQueue_Handle vq, Void *buf);
 174
 175 /*!
 176  *  @brief      Get the next used buffer.
 177  *              Only used by Host.
 178  *
 179  *  @param[in]  vq        the VirtQueue.
 180  *
 181  *  @return     Returns NULL or the processed buffer.
 182  *
 183  *  @sa         VirtQueue_addAvailBuf
 184  */
 185 Void *VirtQueue_getUsedBuf(VirtQueue_Handle vq);
 186
 187 /*
 188  *  ============================================================================
 189  *  Slave Only Functions:
 190  *  ============================================================================
 191  */
 192
 193 /*!
 194  *  @brief      Get the next available buffer.
 195  *              Only used by Slave.
 196  *
 197  *  @param[in]  vq        the VirtQueue.
 198  *  @param[out] buf       Pointer to location of available buffer;
 199  *  @param[out] len       Length of the available buffer message.
 200  *
 201  *  @return     Returns a token used to identify the available buffer, to be
 202  *              passed back into VirtQueue_addUsedBuf();
 203  *              token is negative if failure to find an available buffer.
 204  *
 205  *  @sa         VirtQueue_addUsedBuf
 206  */
 207 Int16 VirtQueue_getAvailBuf(VirtQueue_Handle vq, Void **buf, Int *len);
 208
 209 /*!
 210  *  @brief      Add used buffer to virtqueue's used buffer list.
 211  *              Only used by Slave.
 212  *
 213  *  @param[in]  vq        the VirtQueue.
 214  *  @param[in]  token     token of the buffer to be added to vring used list.
 215  *  @param[in]  len       length of the message being added.
 216  *
 217  *  @return     Remaining capacity of queue or a negative error.
 218  *
 219  *  @sa         VirtQueue_getAvailBuf
 220  */
 221 Int VirtQueue_addUsedBuf(VirtQueue_Handle vq, Int16 token, Int len);
 222
 223 /*!
 224  *  @brief      Post crash message to host mailbox
 225  */
 226 Void VirtQueue_postCrashToMailbox(Void);
 227
 228 #if defined (__cplusplus)
 229 }
 230 #endif /* defined (__cplusplus) */
 231
 232 #endif /* ti_ipc_family_omap54xx_VirtQueue__include */