rm_transport.h

   1 /**
   2  *   @file  rm_transport.h
   3  *
   4  *   @brief
   5  *      This is the RM include file for the generic transport interface used by RM to exchange
   6  *      RM control signals and data between RM instances
   7  *
   8  *  \par
   9  *  ============================================================================
  10  *  @n   (C) Copyright 2012, Texas Instruments, Inc.
  11  *
  12  *  Redistribution and use in source and binary forms, with or without
  13  *  modification, are permitted provided that the following conditions
  14  *  are met:
  15  *
  16  *    Redistributions of source code must retain the above copyright
  17  *    notice, this list of conditions and the following disclaimer.
  18  *
  19  *    Redistributions in binary form must reproduce the above copyright
  20  *    notice, this list of conditions and the following disclaimer in the
  21  *    documentation and/or other materials provided with the
  22  *    distribution.
  23  *
  24  *    Neither the name of Texas Instruments Incorporated nor the names of
  25  *    its contributors may be used to endorse or promote products derived
  26  *    from this software without specific prior written permission.
  27  *
  28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  31  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  32  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  33  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  34  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  38  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39  *
  40  *  \par
  41 */
  42
  43 #ifndef RM_TRANSPORT_H_
  44 #define RM_TRANSPORT_H_
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /**
  51 @addtogroup RM_TRANSPORT_API
  52 @{
  53 */
  54
  55 /** Maximum size of the RM transport packet */
  56 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (128)  // Placeholder: This will
  57                                                  // change during development
  58
  59 /**
  60  * @brief RM transport handle
  61  */
  62 typedef void *Rm_TransportHandle;
  63
  64 /**
  65  * @brief Result of RM transport layer operations
  66  */
  67 typedef int32_t   Rm_TransportResult;
  68
  69 /**
  70  * @brief RM transport layer packet packet descriptor structure
  71  */
  72 typedef struct {
  73     /** Length of packet.  Written by application when allocated */
  74     uint32_t rmPktLen;
  75     /** Pointer to RM resource packet */
  76     char rmData[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
  77 } Rm_Packet;
  78
  79
  80 typedef struct {
  81     /**
  82      *  @b Description
  83      *  @n
  84      *      This function pointer describes the RM transport layer packet
  85      *      allocation function.  The application which integrates with RM must
  86      *      supply a function to RM at initialization time that matches this
  87      *      prototype.  The provided function implements the allocation of packet
  88      *      buffers for use by the RM transport for sending messages between RM
  89      *      instances in the SOC.
  90      *
  91      *  @param[in]  transHandle
  92      *      Which application transport to allocate a packet from.
  93      *
  94      *  @param[in]  pktSize
  95      *      Size of requested packet allocation.
  96      *
  97      *  @retval
  98      *      Success - Pointer to allocated packet buffer.
  99      *  @retval
 100      *      Failure - NULL
 101      */
 102     Rm_Packet *(*rmAllocPkt)(Rm_TransportHandle transHandle, uint32_t pktSize);
 103
 104     /**
 105      *  @b Description
 106      *  @n
 107      *      This function pointer describes the RM transport layer packet
 108      *      free function.  The application which integrates with RM must
 109      *      supply a function to RM at initialization time that matches this
 110      *      prototype.  The provided function implements the free of packet
 111      *      buffers used by the RM transport for sending/receiving messages
 112      *      between RM instances in the SOC.
 113      *
 114      *  @param[in]  transHandle
 115      *      Which application transport to free the packet to.
 116      *
 117      *  @param[in]  pkt
 118      *      Pointer to resource packet to be freed.
 119      *
 120      *  @retval
 121      *      0 - Packet free okay.
 122      *  @retval
 123      *      Non-zero - Send failed.
 124      */
 125     Rm_TransportResult  (*rmFreePkt)(Rm_TransportHandle transHandle, Rm_Packet *pkt);
 126
 127     /**
 128      *  @b Description
 129      *  @n
 130      *      This function pointer describes the RM transport layer send function.
 131      *      The application which integrates with RM must supply a function to RM
 132      *      at initialization time that matches this prototype.  The provided
 133      *      function implements the send side of the transport between RM
 134      *      instances on different cores in the SOC.
 135      *
 136      *  @param[in]  transHandle
 137      *      Which application transport to send the packet over.
 138      *
 139      *  @param[in]  pkt
 140      *      Pointer to resource packet to be sent to the destination RM.
 141      *
 142      *  @retval
 143      *      0 - Packet sent okay.
 144      *  @retval
 145      *      Non-zero - Send failed.
 146      */
 147     Rm_TransportResult  (*rmSend)(Rm_TransportHandle transHandle, Rm_Packet *pkt);
 148
 149     /**
 150      *  @b Description
 151      *  @n
 152      *      This function pointer describes the RM transport layer receive
 153      *      function. The application which integrates with RM must supply a
 154      *      function to RM at initialization time that matches this prototype.
 155      *      The provided function implements the receive side of the transport
 156      *      between RM instances on different cores in the SOC.
 157      *
 158      *  @param[in]  transHandle
 159      *      Which application transport to retrieve a packet from
 160      *
 161      *  @param[in]  pkt
 162      *      Pointer to received resource packet.
 163      *
 164      *  @retval
 165      *      0 - Packet reception okay.
 166      *  @retval
 167      *      Non-zero - Packet receive failed.
 168      */
 169     Rm_TransportResult  (*rmReceive)(Rm_TransportHandle transHandle, Rm_Packet *pkt);
 170
 171     /**
 172      *  @b Description
 173      *  @n
 174      *      This function pointer describes the RM transport layer number of
 175      *      packets received function. The application which integrates with RM
 176      *      must supply a function to RM at initialization time that matches this
 177      *      prototype.  The provided function implements a query of the number of
 178      *      RM packets received on a specified transport.
 179      *
 180      *  @param[in]  transHandle
 181      *      Which application transport to check for received packets.
 182      *
 183      *  @retval
 184      *      Success -   Number of packets received over transport interfaces for
 185      *                  a RM instance.
 186      *  @retval
 187      *      Failure -   -1
 188      */
 189     int32_t (*rmNumPktsReceived)(Rm_TransportHandle transHandle);
 190 } Rm_TransportCallouts;
 191
 192 /**
 193  *  @b Description
 194  *  @n
 195  *      This is the RM transport layer function available for application
 196  *      transport code callbacks.  This API can be called if the application
 197  *      transport wants to report a received RM packet to the RM instance.
 198  *      This API can be used if RM polling the application code for received
 199  *      packets is not desired.
 200  *
 201  *  @param[in]  transHandle
 202  *      Transport handle.  Used to distinguish which RM instance the packet
 203  *      was received from and how to internally route the packet if more than
 204  *      one RM instance exists on the core.
 205  *
 206  *  @param[in]  pkt
 207  *      Pointer to received resource packet.
 208  *
 209  *  @retval
 210  *      Success - 0
 211  *  @retval
 212  *      Failure - Non-zero RM error
 213  */
 214 Rm_Result rmTransportCallback(Rm_TransHandle transHandle, Rm_Packet *pkt);
 215
 216
 217 /**
 218 @}
 219 */
 220
 221 #ifdef __cplusplus
 222 }
 223 #endif
 224
 225 #endif /* RM_TRANSPORT_H_ */