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-2015, 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
 133      *      messages between RM instances.  The Rm_Packet pointer will point to
 134      *      start of the data buffer containing the RM packet data.  The
 135      *      pktHandle will point to the start of the application data path
 136      *      "packet" data structure.  The Rm_Packet pointer and pktHandle cannot
 137      *      be NULL.  They will either be different or the same value based on
 138      *      the application 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,
 160                              uint32_t pktSize,
 161                              Rm_PacketHandle *pktHandle);
 162     /**
 163      *  @b Description
 164      *  @n
 165      *      This function pointer describes the RM transport layer packet
 166      *      send function.  The application must supply a send function
 167      *      to RM instances at transport registration if the RM instance is
 168      *      intended to communicate with other RM instances.  The function
 169      *      provided by the application must match this prototype.  The provided
 170      *      function implements the sending of application data path packets,
 171      *      encapsulating RM packets, between RM instances.  The pktHandle will
 172      *      point to the start of the application data path "packet" data
 173      *      structure.
 174      *
 175      *      RM assumes that the application will free application data
 176      *      path packet and the buffer containing the Rm_Packet after
 177      *      the send operation.
 178      *
 179      *  @param[in]  appTransport
 180      *      Application transport handle to send packet on.  This value
 181      *      is provided by the application at transport registration.
 182      *
 183      *  @param[in]  pktHandle
 184      *      Pointer to the start of the application's transport "packet".
 185      *      Could be the pointer to the start of a QMSS descriptor,
 186      *      network packet, etc.
 187      *
 188      *  @retval
 189      *      0   - Packet sent okay.
 190      *  @retval
 191      *      < 0 - Packet send failed.
 192      */
 193     int32_t (*rmSendPkt)(Rm_AppTransportHandle appTransport,
 194                          Rm_PacketHandle pktHandle);
 195 } Rm_TransportCallouts;
 196
 197 /**
 198  * @brief RM transport registration configuration structure
 199  */
 200 typedef struct {
 201     /** RM Handle for which the transport is being registered */
 202     Rm_Handle              rmHandle;
 203     /** Application transport handle associated with the registered
 204      *  transport.  This value can be anything that helps the application
 205      *  identify the application transport "pipe" for which a RM packet
 206      *  should be sent on.  For example, a QMSS queue number, network
 207      *  port data structure, etc. */
 208     Rm_AppTransportHandle  appTransportHandle;
 209     /** Remote RM instance type at other end of the application transport
 210      *  "pipe". */
 211     Rm_InstType            remoteInstType;
 212     /** Pointers to application implemented transport APIs.  The APIs for the
 213      *  provided functions must match the prototypes defined in the
 214      *  #Rm_TransportCallouts structure.  Callouts need to be defined
 215      *  for each registered transport.  However, based on the application's
 216      *  implementation of transport code the same function can be provided
 217      *  for each transport registration.  In these cases, the transport
 218      *  must mux/demux the packets it receives from RM based on the
 219      *  #Rm_TransportHandle. */
 220     Rm_TransportCallouts   transportCallouts;
 221 } Rm_TransportCfg;
 222
 223 /**
 224  * @brief RM transport reconfiguration structure
 225  */
 226 typedef struct {
 227     /** Application transport handle associated with the registered
 228      *  transport.  This value can be anything that helps the application
 229      *  identify the application transport "pipe" for which a RM packet
 230      *  should be sent on.  For example, a QMSS queue number, network
 231      *  port data structure, etc. */
 232     Rm_AppTransportHandle  appTransportHandle;
 233     /** Pointers to application implemented transport APIs.  The APIs for the
 234      *  provided functions must match the prototypes defined in the
 235      *  #Rm_TransportCallouts structure.  Callouts need to be defined
 236      *  for each registered transport.  However, based on the application's
 237      *  implementation of transport code the same function can be provided
 238      *  for each transport registration.  In these cases, the transport
 239      *  must mux/demux the packets it receives from RM based on the
 240      *  #Rm_TransportHandle. */
 241     Rm_TransportCallouts   transportCallouts;
 242 } Rm_TransportReCfg;
 243
 244 /**
 245  *  @b Description
 246  *  @n
 247  *      This function is used to register transports with RM for sending and
 248  *      receiving packets between RM instances over application transport
 249  *      data paths.
 250  *
 251  *      RM Transport Restrictions:
 252  *      a) RM Servers cannot register with other Servers
 253  *      b) RM CDs cannot register with other CDs
 254  *      c) RM Clients cannot register with other Clients
 255  *      d) Clients cannot register with more than one CD or Server
 256  *      e) Clients cannot register with both a CD and Server (either or)
 257  *      f) CDs cannot register with more than one Server
 258  *
 259  *  @param[in]  transportCfg
 260  *      Pointer to the transport registration configuration structure.
 261  *
 262  *  @param[out] result
 263  *      Pointer to a signed int used to return any errors encountered during
 264  *      the transport registration process.
 265  *
 266  *  @retval
 267  *      Success - RM_TransportHandle and result = #RM_OK
 268  *  @retval
 269  *      Failure - NULL RM_TransportHandle and
 270  *                result = #RM_ERROR_INVALID_REMOTE_INST_TYPE
 271  *  @retval
 272  *      Failure - NULL RM_TransportHandle and
 273  *                result = #RM_ERROR_ALREADY_REGD_SERVER_OR_CD
 274  *  @retval
 275  *      Failure - NULL RM_TransportHandle and
 276  *                result = #RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD
 277  *  @retval
 278  *      Failure - NULL RM_TransportHandle and
 279  *                result = #RM_ERROR_TRANSPORT_SEND_NOT_REGD
 280  */
 281 Rm_TransportHandle Rm_transportRegister(const Rm_TransportCfg *transportCfg,
 282                                         int32_t *result);
 283
 284 /**
 285  *  @b Description
 286  *  @n
 287  *      This function reconfigures an existing transport handle using the
 288  *      provided transport configurations
 289  *
 290  *  @param[in]  transportHandle
 291  *      Transport handle to unregister.  The RM instance that the handle will
 292  *      be unregistered from is contained within the transportHandle.
 293  *
 294  *  @param[in]  transportReCfg
 295  *      Pointer to the transport registration configuration structure.
 296  *
 297  *  @retval
 298  *      Success - #RM_OK
 299  *  @retval
 300  *      Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
 301  */
 302 int32_t Rm_transportReconfig(Rm_TransportHandle transportHandle,
 303                              const Rm_TransportReCfg *transportReCfg);
 304
 305 /**
 306  *  @b Description
 307  *  @n
 308  *      This function unregisters the provided transportHandle from the
 309  *      RM instance
 310  *
 311  *  @param[in]  transportHandle
 312  *      Transport handle to unregister.  The RM instance that the handle will
 313  *      be unregistered from is contained within the transportHandle.
 314  *
 315  *  @retval
 316  *      Success - #RM_OK
 317  *  @retval
 318  *      Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
 319  */
 320 int32_t Rm_transportUnregister(Rm_TransportHandle transportHandle);
 321
 322 /**
 323  *  @b Description
 324  *  @n
 325  *      This function returns the RM instance name from which the service
 326  *      encapsulated within the RM packet originated
 327  *
 328  *      Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
 329  *                    and Rm_pktType_NAMESERVER_REQUEST packet types
 330  *
 331  *  @param[in]  pkt
 332  *      RM packet to extract service source instance name from.
 333  *
 334  *  @param[out] serviceInstName
 335  *      Pointer to a character array that will contain the RM instance name
 336  *      that originated the service request.  The character array MUST be
 337  *      #RM_NAME_MAX_CHARS bytes in length
 338  *
 339  *  @param[in]  charBufLen
 340  *      Length of the provided pktInstName buffer
 341  *
 342  *  @retval
 343  *      Success - #RM_OK
 344  *  @retval
 345  *      Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
 346  *      Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
 347  */
 348 int32_t Rm_receiveGetPktServiceSrcName(const Rm_Packet *pkt,
 349                                        char *serviceInstName,
 350                                        int32_t charBufLen);
 351
 352 /**
 353  *  @b Description
 354  *  @n
 355  *      This function returns the RM instance name from which the RM packet
 356  *      originated
 357  *
 358  *      Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
 359  *                    and Rm_pktType_NAMESERVER_REQUEST packet types
 360  *
 361  *  @param[in]  pkt
 362  *      RM packet to extract packet source instance name from.
 363  *
 364  *  @param[out] pktInstName
 365  *      Pointer to a character array that will contain the RM instance name
 366  *      that originated the RM request packet.  The character array MUST be
 367  *      #RM_NAME_MAX_CHARS bytes in length
 368  *
 369  *  @param[in]  charBufLen
 370  *      Length of the provided pktInstName buffer
 371  *
 372  *  @retval
 373  *      Success - #RM_OK
 374  *  @retval
 375  *      Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
 376  *      Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
 377  */
 378 int32_t Rm_receiveGetPktSrcName(const Rm_Packet *pkt,
 379                                 char *pktInstName,
 380                                 int32_t charBufLen);
 381
 382 /**
 383  *  @b Description
 384  *  @n
 385  *      This function is called by the application when it has received a RM
 386  *      packet for processing.  The application provides the transportHandle
 387  *      associated with the RM instance that should receive the packet and
 388  *      a pointer to the data buffer containing the Rm_Packet.
 389  *
 390  *      RM assumes that the application will free the data buffer containing
 391  *      the Rm_Packet after RM has finished processing the packet.
 392  *
 393  *  @param[in]  transportHandle
 394  *      RM transportHandle containing the instance that should process the
 395  *      received packet.
 396  *
 397  *  @param[in] pkt
 398  *      Pointer to the data buffer containing the Rm_Packet
 399  *
 400  *  @retval
 401  *      Success - #RM_OK
 402  *  @retval
 403  *      Failure - < #RM_OK
 404  */
 405 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle,
 406                          const Rm_Packet *pkt);
 407
 408 /**
 409 @}
 410 */
 411
 412 #ifdef __cplusplus
 413 }
 414 #endif
 415
 416 #endif /* RM_TRANSPORT_H_ */