/** * @file rmtransport.h * * @brief * This is the RM include file for the generic transport interface used by RM to exchange * RM control signals and data between RM instances * * \par * ============================================================================ * @n (C) Copyright 2012, Texas Instruments, Inc. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the * distribution. * * Neither the name of Texas Instruments Incorporated nor the names of * its contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * \par */ #ifndef RMTRANSPORT_H_ #define RMTRANSPORT_H_ #ifdef __cplusplus extern "C" { #endif /* RM includes */ #include /** @addtogroup RMTRANSPORT_API @{ */ /** RM Transport Result Return Codes */ /** RM Transport Success Code Base */ #define RM_TRANSPORT_OK_BASE (0) /** RM transport action was successful. */ #define RM_TRANSPORT_SUCCESSFUL (RM_TRANSPORT_OK_BASE) /** RM Transport Error Code Base */ #define RM_TRANSPORT_ERROR_BASE (-64) /** RM transport handle has not been registered with the RM instance */ #define RM_TRANSPORT_ERROR_HANDLE_HAS_NOT_BEEN_REGISTERED (RM_TRANSPORT_ERROR_BASE-1) /** No transports have been registered with the RM instance */ #define RM_TRANSPORT_ERROR_NO_TRANSPORTS_REGISTERED (RM_TRANSPORT_ERROR_BASE-2) /** RM packets are available but an error was encountered during reception */ #define RM_TRANSPORT_ERROR_PACKET_RECEPTION_ERROR (RM_TRANSPORT_ERROR_BASE-3) /** RM received a packet with an unknown RM packet type */ #define RM_TRANSPORT_ERROR_INVALID_PACKET_TYPE (RM_TRANSPORT_ERROR_BASE-4) /** RM resource request transaction could not be found matching the response received */ #define RM_TRANSPORT_ERROR_MATCHING_RESOURCE_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-5) /** RM NameServer request transaction could not be found matching the response received */ #define RM_TRANSPORT_ERROR_MATCHING_NAME_SERVER_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-6) /** * @brief Result of RM transport layer operations */ typedef int32_t Rm_TransportResult; /** Maximum size of the RM transport packet */ #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (256) // Placeholder: This will // change during development /** * @brief RM transport handle */ typedef void *Rm_TransportHandle; /** * @brief RM packet types that can be sent between RM instances */ typedef enum { /** Allocate/Free request packet */ Rm_pktType_RESOURCE_REQUEST = 0, /** Allocate/Free response packet */ Rm_pktType_RESOURCE_RESPONSE = 1, /** RM NameServer mapping request */ Rm_pktType_NAMESERVER_REQUEST = 2, /** RM NameServer mapping response */ Rm_pktType_NAMESERVER_RESPONSE = 3, /** Policy request packet */ Rm_pktType_POLICY_REQUEST = 4, /** Policy response packet */ Rm_pktType_POLICY_CHANGE = 5, /** Resource pool modification request */ Rm_pktType_RESOURCE_POOL_MODIFICATION_REQUEST = 6, /** Resource pool modification response */ Rm_pktType_RESOURCE_POOL_MODIFICATION_RESPONSE = 7 } Rm_pktType; /** * @brief RM transport layer packet */ typedef struct { /** Packet length in bytes. Written by application when allocated */ uint32_t pktLenBytes; /** Type of RM packet contained in the byte data array */ Rm_pktType pktType; /** Byte array containing RM packet data */ char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES]; } Rm_Packet; typedef struct { /** * @b Description * @n * This function pointer describes the RM transport layer packet * allocation function. The application which integrates with RM must * supply a function to RM at initialization time that matches this * prototype. The provided function implements the allocation of packet * buffers for use by the RM transport for sending messages between RM * instances in the SOC. * * @param[in] transportHandle * Which application transport to allocate a packet from. * * @param[in] pktSize * Size of requested packet allocation. * * @retval * Success - Pointer to allocated packet buffer. * @retval * Failure - NULL */ Rm_Packet *(*rmAllocPkt)(Rm_TransportHandle transportHandle, uint32_t pktSize); /** * @b Description * @n * This function pointer describes the RM transport layer packet * free function. The application which integrates with RM must * supply a function to RM at initialization time that matches this * prototype. The provided function implements the free of packet * buffers used by the RM transport for sending/receiving messages * between RM instances in the SOC. * * @param[in] transportHandle * Which application transport to free the packet to. * * @param[in] pkt * Pointer to resource packet to be freed. * * @retval * 0 - Packet free okay. * @retval * Non-zero - Send failed. */ int32_t (*rmFreePkt)(Rm_TransportHandle transportHandle, Rm_Packet *pkt); /** * @b Description * @n * This function pointer describes the RM transport layer send function. * The application which integrates with RM must supply a function to RM * at initialization time that matches this prototype. The provided * function implements the send side of the transport between RM * instances on different cores in the SOC. * * @param[in] transportHandle * Which application transport to send the packet over. * * @param[in] pkt * Pointer to resource packet to be sent to the destination RM. * * @retval * 0 - Packet sent okay. * @retval * Non-zero - Send failed. */ int32_t (*rmSend)(Rm_TransportHandle transportHandle, Rm_Packet *pkt); /** * @b Description * @n * This function pointer describes the RM transport layer receive * function. The application which integrates with RM must supply a * function to RM at initialization time that matches this prototype. * The provided function implements the receive side of the transport * between RM instances on different cores in the SOC. * * @param[in] transportHandle * Which application transport to retrieve a packet from * * @retval * Non-NULL - Pointer to received RM packet. * @retval * NULL - Packet receive failed. */ void * (*rmReceive)(Rm_TransportHandle transportHandle); /** * @b Description * @n * This function pointer describes the RM transport layer number of * packets received function. The application which integrates with RM * must supply a function to RM at initialization time that matches this * prototype. The provided function implements a query of the number of * RM packets received on a specified transport. * * @param[in] transportHandle * Which application transport to check for received packets. * * @retval * Success - Number of packets received over transport interfaces for * a RM instance. * @retval * Failure - -1 */ int32_t (*rmNumPktsReceived)(Rm_TransportHandle transportHandle); } Rm_TransportCallouts; /** * @brief RM transport registration configuration structure */ typedef struct { /** The transport's remote RM instance type */ Rm_InstType remoteInstType; /** Pointer to the transport's remote RM instance name */ char *remoteInstName; /** Used to specify whether the transport callouts are valid. * TRUE - Transport callouts are valid and will be stored by the RM * instance. * FALSE - Transport callouts are not valid and will not be stored by * the RM instance. */ bool transportCalloutsValid; /** Pointers to application implemented transport APIs. The APIs for the * provided functions must match the prototypes defined in the * Rm_TransportCallouts structure. Callouts will typically only be defined * for the first transport registered with an RM instance. The * transportCalloutsValid field can be used to disable RM instance's from * reading in new callout values are they're specified once. */ Rm_TransportCallouts transportCallouts; } Rm_TransportCfg; /** * @b Description * @n * This function is used to register transports with RM for sending and * receiving packets between RM instances over application transport * data paths. * * @param[in] rmHandle * RM instance to which the transport will be registered. Used internally * by RM if there are more than one RM instances per core. * * @param[in] transportCfg * Transport registration configuration structure. Provides information * regarding the application transports remote entity. For example, * if the transCfg structure specifies the remote type is the RM Server * RM will know any Server requests must be pushed to the application * transport API with the transport handle returned to the application * * @retval * Success - non-NULL RM transport handle. No two transport handles * returned by RM should be the same. * @retval * Failure - NULL */ Rm_TransportHandle Rm_transportRegister (Rm_Handle rmHandle, Rm_TransportCfg *transportCfg); Rm_TransportResult Rm_transportUnregister (Rm_Handle rmHandle, Rm_TransportHandle transportHandle); int32_t Rm_receivePktIsr(Rm_TransportHandle transportHandle, Rm_Packet *pkt); int32_t Rm_receivePktPolling(Rm_TransportHandle transportHandle); /** @} */ #ifdef __cplusplus } #endif #endif /* RMTRANSPORT_H_ */