diff --git a/rm_transport.h b/rm_transport.h
index d986ba3e97840d32bacc1a8b27fcea84bb798354..426a3cbe7117638bce5985353fd492a14d5f79c8 100644 (file)
--- a/rm_transport.h
+++ b/rm_transport.h
/**
- * @file rmtransport.h
+ * @file rm_transport.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
+ * 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.
+ * @n (C) Copyright 2012-2014, Texas Instruments, Inc.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* \par
*/
-#ifndef RMTRANSPORT_H_
-#define RMTRANSPORT_H_
+#ifndef RM_TRANSPORT_H_
+#define RM_TRANSPORT_H_
#ifdef __cplusplus
extern "C" {
#endif
+/* Standard includes */
+#include <stdbool.h>
+
/* RM includes */
#include <ti/drv/rm/rm.h>
/**
-@addtogroup RMTRANSPORT_API
+@addtogroup RM_TRANSPORT_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
+/**
+ * @brief Maximum size of RM transport packet
*/
-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
+#define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (256)
/**
* @brief RM transport handle
typedef void *Rm_TransportHandle;
/**
- * @brief RM packet types that can be sent between RM instances
+ * @brief Application transport handle. Void casted application transport
+ * data structure. The Rm_AppTransportHandle provided by the
+ * application could be anything from a queue number to a pointer
+ * to an application transport data structure. RM will provide
+ * a Rm_AppTransportHandle to the application any time RM
+ * wants to alloc or send a packet via the transport callouts
+ */
+typedef void *Rm_AppTransportHandle;
+
+/**
+ * @brief A void pointer to the start of a registered application transport
+ * packet buffer. The Rm_PacketHandle may be different from the
+ * Rm_Packet pointer based on the application transport. For example,
+ * for a QMSS based transport the Rm_PacketHandle may point to the
+ * beginning of a Host descriptor where as the Rm_Packet pointer would
+ * point to the beginning of the data buffer linked with the Host
+ * descriptor.
+ */
+typedef void *Rm_PacketHandle;
+
+/**
+ * @brief RM packet types
*/
typedef enum {
/** Allocate/Free request packet */
Rm_pktType_RESOURCE_REQUEST = 0,
/** Allocate/Free response packet */
- Rm_pktType_RESOURCE_RESPONSE = 1,
+ Rm_pktType_RESOURCE_RESPONSE,
/** RM NameServer mapping request */
- Rm_pktType_NAMESERVER_REQUEST = 2,
+ Rm_pktType_NAMESERVER_REQUEST,
/** 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_NAMESERVER_RESPONSE
} Rm_pktType;
/**
*/
typedef struct {
/** Packet length in bytes. Written by application when allocated */
- uint32_t pktLenBytes;
- /** Type of RM packet contained in the byte data array */
+ uint32_t pktLenBytes;
+ /** Type of RM packet contained in data byte array */
Rm_pktType pktType;
/** Byte array containing RM packet data */
- char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
+ char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
} Rm_Packet;
+/**
+ * @brief RM transport callout functions used by RM to allocate and send
+ * RM packets via the application data paths between RM instances
+ */
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.
+ * allocation function. The application must supply an alloc function
+ * to RM instances at transport registration if the RM instance is
+ * intended to communicate with other RM instances. The function
+ * provided by the application must match this prototype. The provided
+ * function implements the allocation of packet buffers from the
+ * application data path that the RM transport will use to send messages
+ * between RM instances. The Rm_Packet pointer will point to start of
+ * the data buffer containing the RM packet data. The pktHandle will
+ * point to the start of the application data path "packet" data
+ * structure. The Rm_Packet pointer and pktHandle cannot be NULL. They
+ * will either be different or the same value based on the application
+ * transport.
*
- * @param[in] transportHandle
- * Which application transport to allocate a packet from.
+ * @param[in] appTransport
+ * Application transport handle to allocate packet from. This value
+ * is provided by the application at transport registration.
*
* @param[in] pktSize
- * Size of requested packet allocation.
+ * Size of buffer needed by RM for the RM packet. The application
+ * must place this value in the pktLenBytes field of the Rm_Packet.
+ * after the buffer has been allocated.
+ *
+ * @param[out] pktHandle
+ * Pointer to the start of the application's transport "packet".
+ * Could be the pointer to the start of a QMSS descriptor,
+ * network packet, etc.
*
* @retval
* Success - Pointer to allocated packet buffer.
* @retval
* Failure - NULL
*/
- Rm_Packet *(*rmAllocPkt)(Rm_TransportHandle transportHandle, uint32_t pktSize);
-
+ Rm_Packet *(*rmAllocPkt)(Rm_AppTransportHandle appTransport, uint32_t pktSize,
+ Rm_PacketHandle *pktHandle);
/**
* @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.
+ * send function. The application must supply a send function
+ * to RM instances at transport registration if the RM instance is
+ * intended to communicate with other RM instances. The function
+ * provided by the application must match this prototype. The provided
+ * function implements the sending of application data path packets,
+ * encapsulating RM packets, between RM instances. The pktHandle will
+ * point to the start of the application data path "packet" data
+ * structure.
*
- * @param[in] pkt
- * Pointer to resource packet to be sent to the destination RM.
+ * RM assumes that the application will free application data
+ * path packet and the buffer containing the Rm_Packet after
+ * the send operation.
*
- * @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] appTransport
+ * Application transport handle to send packet on. This value
+ * is provided by the application at transport registration.
*
- * @param[in] transportHandle
- * Which application transport to retrieve a packet from
+ * @param[in] pktHandle
+ * Pointer to the start of the application's transport "packet".
+ * Could be the pointer to the start of a QMSS descriptor,
+ * network packet, etc.
*
* @retval
- * Non-NULL - Pointer to received RM packet.
+ * 0 - Packet sent okay.
* @retval
- * NULL - Packet receive failed.
+ * < 0 - Packet send 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);
+ int32_t (*rmSendPkt)(Rm_AppTransportHandle appTransport, Rm_PacketHandle pktHandle);
} 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;
+ /** RM Handle for which the transport is being registered */
+ Rm_Handle rmHandle;
+ /** Application transport handle associated with the registered
+ * transport. This value can be anything that helps the application
+ * identify the application transport "pipe" for which a RM packet
+ * should be sent on. For example, a QMSS queue number, network
+ * port data structure, etc. */
+ Rm_AppTransportHandle appTransportHandle;
+ /** Remote RM instance type at other end of the application transport
+ * "pipe". */
+ Rm_InstType remoteInstType;
/** 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_TransportCallouts structure. Callouts need to be defined
+ * for each registered transport. However, based on the application's
+ * implementation of transport code the same function can be provided
+ * for each transport registration. In these cases, the transport
+ * must mux/demux the packets it receives from RM based on the
+ * #Rm_TransportHandle. */
+ Rm_TransportCallouts transportCallouts;
} Rm_TransportCfg;
+/**
+ * @brief RM transport reconfiguration structure
+ */
+typedef struct {
+ /** Application transport handle associated with the registered
+ * transport. This value can be anything that helps the application
+ * identify the application transport "pipe" for which a RM packet
+ * should be sent on. For example, a QMSS queue number, network
+ * port data structure, etc. */
+ Rm_AppTransportHandle appTransportHandle;
+ /** Pointers to application implemented transport APIs. The APIs for the
+ * provided functions must match the prototypes defined in the
+ * #Rm_TransportCallouts structure. Callouts need to be defined
+ * for each registered transport. However, based on the application's
+ * implementation of transport code the same function can be provided
+ * for each transport registration. In these cases, the transport
+ * must mux/demux the packets it receives from RM based on the
+ * #Rm_TransportHandle. */
+ Rm_TransportCallouts transportCallouts;
+} Rm_TransportReCfg;
+
/**
* @b Description
* @n
* 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.
+ * RM Transport Restrictions:
+ * a) RM Servers cannot register with other Servers
+ * b) RM CDs cannot register with other CDs
+ * c) RM Clients cannot register with other Clients
+ * d) Clients cannot register with more than one CD or Server
+ * e) Clients cannot register with both a CD and Server (either or)
+ * f) CDs cannot register with more than one Server
*
* @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
+ * Pointer to the transport registration configuration structure.
+ *
+ * @param[out] result
+ * Pointer to a signed int used to return any errors encountered during
+ * the transport registration process.
*
* @retval
- * Success - non-NULL RM transport handle. No two transport handles
- * returned by RM should be the same.
+ * Success - RM_TransportHandle and result = #RM_OK
+ * @retval
+ * Failure - NULL RM_TransportHandle and result = #RM_ERROR_INVALID_REMOTE_INST_TYPE
* @retval
- * Failure - NULL
+ * Failure - NULL RM_TransportHandle and result = #RM_ERROR_ALREADY_REGD_SERVER_OR_CD
+ * @retval
+ * Failure - NULL RM_TransportHandle and result = #RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD
+ * @retval
+ * Failure - NULL RM_TransportHandle and result = #RM_ERROR_TRANSPORT_SEND_NOT_REGD
*/
-Rm_TransportHandle Rm_transportRegister (Rm_Handle rmHandle,
- Rm_TransportCfg *transportCfg);
+Rm_TransportHandle Rm_transportRegister(const Rm_TransportCfg *transportCfg, int32_t *result);
-Rm_TransportResult Rm_transportUnregister (Rm_Handle rmHandle,
- Rm_TransportHandle transportHandle);
+/**
+ * @b Description
+ * @n
+ * This function reconfigures an existing transport handle using the
+ * provided transport configurations
+ *
+ * @param[in] transportHandle
+ * Transport handle to unregister. The RM instance that the handle will
+ * be unregistered from is contained within the transportHandle.
+ *
+ * @param[in] transportReCfg
+ * Pointer to the transport registration configuration structure.
+ *
+ * @retval
+ * Success - #RM_OK
+ * @retval
+ * Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
+ */
+int32_t Rm_transportReconfig (Rm_TransportHandle transportHandle, const Rm_TransportReCfg *transportReCfg);
-int32_t Rm_receivePktIsr(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
+/**
+ * @b Description
+ * @n
+ * This function unregisters the provided transportHandle from the
+ * RM instance
+ *
+ * @param[in] transportHandle
+ * Transport handle to unregister. The RM instance that the handle will
+ * be unregistered from is contained within the transportHandle.
+ *
+ * @retval
+ * Success - #RM_OK
+ * @retval
+ * Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
+ */
+int32_t Rm_transportUnregister (Rm_TransportHandle transportHandle);
-int32_t Rm_receivePktPolling(Rm_TransportHandle transportHandle);
+/**
+ * @b Description
+ * @n
+ * This function returns the RM instance name from which the service
+ * encapsulated within the RM packet originated
+ *
+ * Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
+ * and Rm_pktType_NAMESERVER_REQUEST packet types
+ *
+ * @param[in] pkt
+ * RM packet to extract service source instance name from.
+ *
+ * @param[out] serviceInstName
+ * Pointer to a character array that will contain the RM instance name
+ * that originated the service request. The character array MUST be
+ * #RM_NAME_MAX_CHARS bytes in length
+ *
+ * @param[in] charBufLen
+ * Length of the provided pktInstName buffer
+ *
+ * @retval
+ * Success - #RM_OK
+ * @retval
+ * Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
+ * Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
+ */
+int32_t Rm_receiveGetPktServiceSrcName(const Rm_Packet *pkt, char *serviceInstName,
+ int32_t charBufLen);
+
+/**
+ * @b Description
+ * @n
+ * This function returns the RM instance name from which the RM packet
+ * originated
+ *
+ * Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
+ * and Rm_pktType_NAMESERVER_REQUEST packet types
+ *
+ * @param[in] pkt
+ * RM packet to extract packet source instance name from.
+ *
+ * @param[out] pktInstName
+ * Pointer to a character array that will contain the RM instance name
+ * that originated the RM request packet. The character array MUST be
+ * #RM_NAME_MAX_CHARS bytes in length
+ *
+ * @param[in] charBufLen
+ * Length of the provided pktInstName buffer
+ *
+ * @retval
+ * Success - #RM_OK
+ * @retval
+ * Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
+ * Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
+ */
+int32_t Rm_receiveGetPktSrcName(const Rm_Packet *pkt, char *pktInstName,
+ int32_t charBufLen);
+/**
+ * @b Description
+ * @n
+ * This function is called by the application when it has received a RM
+ * packet for processing. The application provides the transportHandle
+ * associated with the RM instance that should receive the packet and
+ * a pointer to the data buffer containing the Rm_Packet.
+ *
+ * RM assumes that the application will free the data buffer containing
+ * the Rm_Packet after RM has finished processing the packet.
+ *
+ * @param[in] transportHandle
+ * RM transportHandle containing the instance that should process the
+ * received packet.
+ *
+ * @param[in] pkt
+ * Pointer to the data buffer containing the Rm_Packet
+ *
+ * @retval
+ * Success - #RM_OK
+ * @retval
+ * Failure - < #RM_OK
+ */
+int32_t Rm_receivePacket(Rm_TransportHandle transportHandle, const Rm_Packet *pkt);
/**
@}
}
#endif
-#endif /* RMTRANSPORT_H_ */
+#endif /* RM_TRANSPORT_H_ */