packages/ti/ipc/rpmsg/MessageQCopy.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       MessageQCopy.h
  34  *
  35  *  @brief      A simple copy-based MessageQ, to work with Linux virtio_rp_msg.
  36  *
  37  *  The following are key features of the MessageQCopy module:
  38  *  - Multiple writers, single reader.
  39  *  - Timeouts are allowed when receiving messages.
  40  *  - Supports processor copy transfers only.
  41  *  - Sending/receiving also works between enpoints on the same processor.
  42  *
  43  *  Non-Features (as compared to MessageQ):
  44  *  - zero copy messaging, using registered heaps.
  45  *  - Dependence on a NameServer (Client furnishes the endpoint IDs)
  46  *  - Arbitrary reply endpoints can be embedded in message header.
  47  *  - Priority Queues.
  48  *
  49  *  Conceptually, the reader thread owns a message queue. The reader thread
  50  *  creates a message queue. The writer threads opens a created message queue
  51  *  to get access to it.
  52  *
  53  *  Message queues are identified by a system-wide unique 32 bit queueID,
  54  *  which encodes the (MultiProc) 16 bit core ID and a local 16 bit index ID.
  55  *
  56  *  The MessageQCopy header should be included in an application as follows:
  57  *  @code
  58  *  #include <ti/ipc/rpmsg/MessageQCopy.h>
  59  *  @endcode
  60  *
  61  *  Questions:
  62  *  - Workout how connections exist: how does Ducati side cleanup when Linux
  63  *    side goes down?
  64  *  - Client needs to know max size of data buffer to allocate for receive.
  65  *  - Do we need procID's buried in the message header addresses anymore, or
  66  *    isn't that now implicit in the vrings/transport.
  67  *  - Do we want MessageQ_Unblock in this version?  (Normally used in RCM).
  68  *  - Do we want the generic ISync ability to create our own synchronizers,
  69  *    or just hard-code semaphore usage or callbacks for simplicity?
  70  *
  71  *  ============================================================================
  72  */
  73
  74 #ifndef ti_ipc_MessageQCopy__include
  75 #define ti_ipc_MessageQCopy__include
  76
  77 #if defined (__cplusplus)
  78 extern "C" {
  79 #endif
  80
  81
  82 /* =============================================================================
  83  *  Structures & Definitions
  84  * =============================================================================
  85  */
  86
  87 /*!
  88  *  @brief      Used as the timeout value to specify wait forever
  89  */
  90 #define MessageQCopy_FOREVER                ~(0)
  91
  92 /*!
  93    *  @def    MessageQCopy_S_SUCCESS
  94  *  @brief  Operation is successful.
  95  */
  96 #define MessageQCopy_S_SUCCESS              0
  97
  98 /*!
  99  *  @def    MessageQCopy_E_FAIL
 100  *  @brief  Operation is not successful.
 101  */
 102 #define MessageQCopy_E_FAIL                 -1
 103
 104 /*!
 105  *  @def    MessageQCopy_E_MEMORY
 106  *  @brief  Operation resulted in memory failure.
 107  */
 108 #define MessageQCopy_E_MEMORY               -3
 109
 110 /*!
 111  *  @def    MessageQCopy_E_TIMEOUT
 112  *  @brief  Operation timed out.
 113  */
 114 #define MessageQCopy_E_TIMEOUT              -6
 115
 116 /*!
 117  *  @def    MessageQCopy_E_NOENDPT
 118  *  @brief  No endpoint for a message.
 119  */
 120 #define MessageQCopy_E_NOENDPT              -7
 121
 122 /*!
 123  *  @def    MessageQ_E_UNBLOCKED
 124  *  @brief  MessageQCopy was unblocked
 125  */
 126 #define MessageQCopy_E_UNBLOCKED            -19
 127
 128 /*!
 129  *  @def    MessageQCopy_MAX_RESERVED_ENDPOINT
 130  *  @brief  Maximum Value for System Reserved Endpoints.
 131  */
 132 #define MessageQCopy_MAX_RESERVED_ENDPOINT  100
 133
 134 /*!
 135  *  @def    MessageQCopy_MAX_RESERVED_ENDPOINT
 136  *  @brief  Maximum Value for System Reserved Endpoints.
 137  */
 138 #define MessageQCopy_ASSIGN_ANY             0xFFFFFFFF
 139 /*!
 140  *  @brief  MessageQCopy_Handle type
 141  */
 142 typedef struct MessageQCopy_Object *MessageQCopy_Handle;
 143
 144
 145 typedef Void (*MessageQCopy_callback)(MessageQCopy_Handle, UArg, Ptr,
 146                                       UInt16, UInt32);
 147
 148 /* =============================================================================
 149  *  MessageQCopy Functions:
 150  * =============================================================================
 151  */
 152
 153
 154 /*!
 155  *  @brief      Create a MessageQCopy instance for receiving, with callback.
 156  *
 157  *  This is an extension of MessageQCopy_create(), with the option of passing
 158  *  a callback function and its argument to be called when a message is
 159  *  received.
 160  *
 161  *  @param[in]   reserved     If value is MessageQCopy_ASSIGN_ANY, then
 162  *                            any Endpoint can be assigned; otherwise, value is
 163  *                            a reserved Endpoint ID, which must be less than
 164  *                            or equal to MessageQCopy_MAX_RESERVED_ENDPOINT.
 165  *  @param[in]   callback     If non-NULL, on received data, this callback is
 166  *                            called instead of posting the internal semaphore.
 167  *  @param[in]   arg          Argument for the callback.
 168  *  @param[out]  endpoint     Endpoint ID for this side of the connection.
 169  *
 170  *
 171  *  @return     MessageQCopy Handle, or NULL if:
 172  *                            - reserved endpoint already taken;
 173  *                            - could not allocate object
 174  */
 175 MessageQCopy_Handle MessageQCopy_create(UInt32 reserved,
 176                                         MessageQCopy_callback callback,
 177                                         UArg arg,
 178                                         UInt32 * endpoint);
 179 /*!
 180  *  @brief      Receives a message from a message queue
 181  *
 182  *  This function returns a status. It also copies data to the client.
 183  *  If no message is available, it blocks on the semaphore object
 184  *  until the semaphore is signaled or a timeout occurs.
 185  *  The semaphore is signaled, when Message_send is called to deliver a message
 186  *  to this endpoint. If a timeout occurs, len is set to zero and the status is
 187  *  #MessageQCopy_E_TIMEOUT. If a timeout of zero is specified, the function
 188  *  returns immediately and if no message is available, the len is set to zero
 189  *  and the status is #MessageQCopy_E_TIMEOUT.
 190  *  The #MessageQCopy_E_UNBLOCKED status is returned, if MessageQ_unblock is called
 191  *  on the MessageQCopy handle.
 192  *  If a message is successfully retrieved, the message
 193  *  data is copied into the data pointer, and a #MessageQCopy_S_SUCCESS
 194  *  status is returned.
 195  *
 196  *  @param[in]  handle      MessageQCopy handle
 197  *  @param[out] data        Pointer to the client's data buffer.
 198  *  @param[out] len         Amount of data received.
 199  *  @param[out] rplyEndpt   Endpoint of source (for replies).
 200  *  @param[in]  timeout     Maximum duration to wait for a message in
 201  *                          microseconds.
 202  *
 203  *  @return     MessageQCopy status:
 204  *              - #MessageQCopy_S_SUCCESS: Message successfully returned
 205  *              - #MessageQCopy_E_TIMEOUT: MessageQCopy_recv timed out
 206  *              - #MessageQCopy_E_UNBLOCKED: MessageQ_get was unblocked
 207  *              - #MessageQCopy_E_FAIL:    A general failure has occurred
 208  *
 209  *  @sa         MessageQCopy_send MessageQCopy_unblock
 210  */
 211 Int MessageQCopy_recv(MessageQCopy_Handle handle, Ptr data, UInt16 *len,
 212                       UInt32 *rplyEndpt, UInt timeout);
 213
 214 /*!
 215  *  @brief      Sends data to a remote processor, or copies onto a local
 216  *              messageQ.
 217  *
 218  *  If the message is placed onto a local Message queue, the queue's
 219  *  #MessageQCopy_Params::semaphore signal function is called.
 220  *
 221  *  @param[in]  dstProc     Destination ProcId.
 222  *  @param[in]  dstEndpt    Destination Endpoint.
 223  *  @param[in]  srcEndpt    Source Endpoint.
 224  *  @param[in]  data        Data payload to be copied and sent.
 225  *  @param[in]  len         Amount of data to be copied, including Msg header.
 226  *
 227  *  @return     Status of the call.
 228  *              - #MessageQCopy_S_SUCCESS denotes success.
 229  *              - #MessageQCopy_E_FAIL denotes failure.
 230  *                The send was not successful.
 231  */
 232 Int MessageQCopy_send(UInt16 dstProc,
 233                       UInt32 dstEndpt,
 234                       UInt32 srcEndpt,
 235                       Ptr    data,
 236                       UInt16 len);
 237
 238 /*!
 239  *  @brief      Delete a created MessageQCopy instance.
 240  *
 241  *  This function deletes a created message queue instance. If the
 242  *  message queue is non-empty, any messages remaining in the queue
 243  *  will be lost.
 244  *
 245  *  @param[in,out]  handlePtr   Pointer to handle to delete.
 246  *
 247  *  @return     MessageQCopy status:
 248  *              - #MessageQCopy_E_FAIL: delete failed
 249  *              - #MessageQCopy_S_SUCCESS: delete successful, *handlePtr = NULL.
 250  */
 251 Int MessageQCopy_delete(MessageQCopy_Handle *handlePtr);
 252
 253 /*!
 254  *  @brief      Unblocks a MessageQ
 255  *
 256  *  Unblocks a reader thread that is blocked on a MessageQCopy_recv.  The
 257  *  MessageQCopy_recv call will return with status #MessageQ_E_UNBLOCKED
 258  *  indicating that it returned due to a MessageQCopy_unblock rather than by
 259  *  a timeout or receiving a message.
 260  *
 261  *  Restrictions:
 262  *  -  A queue may not be used after it has been unblocked.
 263  *  -  MessageQ_unblock may only be called on a local queue.
 264  *
 265  *  @param[in]  handle      MessageQCopy handle
 266  *
 267  *  @sa         MessageQCopy_recv
 268  */
 269 Void MessageQCopy_unblock(MessageQCopy_Handle handle);
 270
 271 #if defined (__cplusplus)
 272 }
 273 #endif /* defined (__cplusplus) */
 274 #endif /* ti_ipc_MessageQCopy__include */