rm_transport.h

   1 /**
   2  *   @file  rm_transport.h
   3  *
   4  *   @brief
   5  *      This is the RM include file for the generic transport interface
   6  *      used by RM to exchange RM control signals and data between RM instances
   7  *
   8  *  \par
   9  *  ============================================================================
  10  *  @n   (C) Copyright 2012-2013, 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 /* Standard includes */
  51 #include <stdbool.h>
  52
  53 /* RM includes */
  54 #include <ti/drv/rm/rm.h>
  55
  56 /**
  57 @addtogroup RM_TRANSPORT_API
  58 @{
  59 */
  60
  61 /**
  62  * @brief Maximum size of RM transport packet
  63  */
  64 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (256)
  65
  66 /**
  67  * @brief RM transport handle
  68  */
  69 typedef void *Rm_TransportHandle;
  70
  71 /**
  72  * @brief Application transport handle.  Void casted application transport
  73  *        data structure.  The Rm_AppTransportHandle provided by the
  74  *        application could be anything from a queue number to a pointer
  75  *        to an application transport data structure.  RM will provide
  76  *        a Rm_AppTransportHandle to the application any time RM
  77  *        wants to alloc or send a packet via the transport callouts
  78  */
  79 typedef void *Rm_AppTransportHandle;
  80
  81 /**
  82  * @brief A void pointer to the start of a registered application transport
  83  *        packet buffer.  The Rm_PacketHandle may be different from the
  84  *        rm_Packet pointer based on the application transport.  For example,
  85  *        for a QMSS based transport the Rm_PacketHandle may point to the
  86  *        beginning of a Host descriptor where as the Rm_Packet pointer would
  87  *        point to the beginning of the data buffer linked with the Host
  88  *        descriptor.
  89  */
  90 typedef void *Rm_PacketHandle;
  91
  92 /**
  93  * @brief RM packet types
  94  */
  95 typedef enum {
  96     /** Allocate/Free request packet */
  97     Rm_pktType_RESOURCE_REQUEST = 0,
  98     /** Allocate/Free response packet */
  99     Rm_pktType_RESOURCE_RESPONSE,
 100     /** RM NameServer mapping request */
 101     Rm_pktType_NAMESERVER_REQUEST,
 102     /** RM NameServer mapping response */
 103     Rm_pktType_NAMESERVER_RESPONSE
 104 } Rm_pktType;
 105
 106 /**
 107  * @brief RM transport layer packet
 108  */
 109 typedef struct {
 110     /** Packet length in bytes.  Written by application when allocated */
 111     uint32_t   pktLenBytes;
 112     /** Type of RM packet contained in data byte array */
 113     Rm_pktType pktType;
 114     /** Byte array containing RM packet data */
 115     char       data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
 116 } Rm_Packet;
 117
 118 /**
 119  * @brief RM transport callout functions used by RM to allocate and send
 120  *        RM packets via the application data paths between RM instances
 121  */
 122 typedef struct {
 123     /**
 124      *  @b Description
 125      *  @n
 126      *      This function pointer describes the RM transport layer packet
 127      *      allocation function.  The application must supply an alloc function
 128      *      to RM instances at transport registration if the RM instance is
 129      *      intended to communicate with other RM instances.  The function
 130      *      provided by the application must match this prototype.  The provided
 131      *      function implements the allocation of packet buffers from the
 132      *      application data path that the RM transport will use to send messages
 133      *      between RM instances.  The Rm_Packet pointer will point to start of
 134      *      the data buffer containing the RM packet data.  The pktHandle will
 135      *      point to the start of the application data path "packet" data
 136      *      structure.  The Rm_Packet pointer and pktHandle cannot be NULL.  They
 137      *      will either be different or the same value based on the application
 138      *      transport.
 139      *
 140      *  @param[in]  appTransport
 141      *      Application transport handle to allocate packet from.  This value
 142      *      is provided by the application at transport registration.
 143      *
 144      *  @param[in]  pktSize
 145      *      Size of buffer needed by RM for the RM packet.  The application
 146      *      must place this value in the pktLenBytes field of the Rm_Packet.
 147      *      after the buffer has been allocated.
 148      *
 149      *  @param[out]  pktHandle
 150      *      Pointer to the start of the application's transport "packet".
 151      *      Could be the pointer to the start of a QMSS descriptor,
 152      *      network packet, etc.
 153      *
 154      *  @retval
 155      *      Success - Pointer to allocated packet buffer.
 156      *  @retval
 157      *      Failure - NULL
 158      */
 159     Rm_Packet *(*rmAllocPkt)(Rm_AppTransportHandle appTransport, uint32_t pktSize,
 160                              Rm_PacketHandle *pktHandle);
 161     /**
 162      *  @b Description
 163      *  @n
 164      *      This function pointer describes the RM transport layer packet
 165      *      send function.  The application must supply a send function
 166      *      to RM instances at transport registration if the RM instance is
 167      *      intended to communicate with other RM instances.  The function
 168      *      provided by the application must match this prototype.  The provided
 169      *      function implements the sending of application data path packets,
 170      *      encapsulating RM packets, between RM instances.  The pktHandle will
 171      *      point to the start of the application data path "packet" data
 172      *      structure.
 173      *
 174      *      RM assumes that the application will free application data
 175      *      path packet and the buffer containing the Rm_Packet after
 176      *      the send operation.
 177      *
 178      *  @param[in]  appTransport
 179      *      Application transport handle to send packet on.  This value
 180      *      is provided by the application at transport registration.
 181      *
 182      *  @param[in]  pktHandle
 183      *      Pointer to the start of the application's transport "packet".
 184      *      Could be the pointer to the start of a QMSS descriptor,
 185      *      network packet, etc.
 186      *
 187      *  @retval
 188      *      0   - Packet sent okay.
 189      *  @retval
 190      *      < 0 - Packet send failed.
 191      */
 192     int32_t (*rmSendPkt)(Rm_AppTransportHandle appTransport, Rm_PacketHandle pktHandle);
 193 } Rm_TransportCallouts;
 194
 195 /**
 196  * @brief RM transport registration configuration structure
 197  */
 198 typedef struct {
 199     /** RM Handle for which the transport is being registered */
 200     Rm_Handle              rmHandle;
 201     /** Application transport handle associated with the registered
 202      *  transport.  This value can be anything that helps the application
 203      *  identify the application transport "pipe" for which a RM packet
 204      *  should be sent on.  For example, a QMSS queue number, network
 205      *  port data structure, etc. */
 206     Rm_AppTransportHandle  appTransportHandle;
 207     /** Remote RM instance type at other end of the application transport
 208      *  "pipe". */
 209     Rm_InstType            remoteInstType;
 210     /** Pointer to the remote RM instance name at other end of the
 211      *  application transport "pipe". */
 212     const char            *remoteInstName;
 213     /** Specifies whether the transport callouts are valid.
 214      *  TRUE  - Transport callouts are valid and can be stored by the RM
 215      *          instance.
 216      *  FALSE - Transport callouts are not valid and cannot not be stored by
 217      *          the RM instance. */
 218     bool                   transportCalloutsValid;
 219     /** Pointers to application implemented transport APIs.  The APIs for the
 220      *  provided functions must match the prototypes defined in the
 221      *  #Rm_TransportCallouts structure.  Callouts need only be defined
 222      *  once per RM instance.  Multiple transport registrations on the same
 223      *  intance need the transportsCallouts defined and set as valid once. */
 224     Rm_TransportCallouts   transportCallouts;
 225 } Rm_TransportCfg;
 226
 227 /**
 228  *  @b Description
 229  *  @n
 230  *      This function is used to register transports with RM for sending and
 231  *      receiving packets between RM instances over application transport
 232  *      data paths.
 233  *
 234  *      RM Transport Restrictions:
 235  *      a) RM Servers cannot register with other Servers
 236  *      b) RM CDs cannot register with other CDs
 237  *      c) RM Clients cannot register with other Clients
 238  *      d) Clients cannot register with more than one CD or Server
 239  *      e) Clients cannot register with both a CD and Server (either or)
 240  *      f) CDs cannot register with more than one Server
 241  *
 242  *  @param[in]  transportCfg
 243  *      Pointer to the transport registration configuration structure.
 244  *
 245  *  @param[out] result
 246  *      Pointer to a signed int used to return any errors encountered during
 247  *      the transport registration process.
 248  *
 249  *  @retval
 250  *      Success - RM_TransportHandle and result = #RM_OK
 251  *  @retval
 252  *      Failure - NULL RM_TransportHandle and result = #RM_ERROR_INVALID_REMOTE_INST_TYPE
 253  *  @retval
 254  *      Failure - NULL RM_TransportHandle and result = #RM_ERROR_ALREADY_REGD_SERVER_OR_CD
 255  *  @retval
 256  *      Failure - NULL RM_TransportHandle and result = #RM_ERROR_NULL_CALLOUTS_WHEN_VALID
 257  */
 258 Rm_TransportHandle Rm_transportRegister(const Rm_TransportCfg *transportCfg, int32_t *result);
 259
 260 /**
 261  *  @b Description
 262  *  @n
 263  *      This function unregisters the provided transportHandle from the
 264  *      RM instance
 265  *
 266  *  @param[in]  transportHandle
 267  *      Transport handle to unregister.  The RM instance that the handle will
 268  *      be unregistered from is contained within the transportHandle.
 269  *
 270  *  @retval
 271  *      Success - #RM_OK
 272  *  @retval
 273  *      Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
 274  */
 275 int32_t Rm_transportUnregister (Rm_TransportHandle transportHandle);
 276
 277 /**
 278  *  @b Description
 279  *  @n
 280  *      This function is called by the application when it has received a RM
 281  *      packet for processing.  The application provides the transportHandle
 282  *      associated with the RM instance that should receive the packet and
 283  *      a pointer to the data buffer containing the Rm_Packet.
 284  *
 285  *      RM assumes that the application will free the data buffer containing
 286  *      the Rm_Packet after RM has finished processing the packet.
 287  *
 288  *  @param[in]  transportHandle
 289  *      RM transportHandle containing the instance that should process the
 290  *      received packet.
 291  *
 292  *  @param[in] pkt
 293  *      Pointer to the data buffer containing the Rm_Packet
 294  *
 295  *  @retval
 296  *      Success - #RM_OK
 297  *  @retval
 298  *      Failure - < #RM_OK
 299  */
 300 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle, const Rm_Packet *pkt);
 301
 302 /**
 303 @}
 304 */
 305
 306 #ifdef __cplusplus
 307 }
 308 #endif
 309
 310 #endif /* RM_TRANSPORT_H_ */