index 844246328da8ae242d743212ae245474969da137..88d1973496ee0a59dc21a4f2a221682e56d6010a 100644 (file)
/*
- * Copyright (c) 2012-2013, Texas Instruments Incorporated
+ * Copyright (c) 2012-2014, Texas Instruments Incorporated
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-/** ============================================================================
- * @file MmRpc.h
+/**
+ * @file ti/ipc/mm/MmRpc.h
*
* @brief Multi-Media derived Remote Procedure Call
*
- * ============================================================================
+ * @note MmRpc is currently only available for HLOS (Linux, QNX, Android).
*/
#ifndef ti_ipc_mm_MmRpc__include
#include <stddef.h>
#include <stdint.h>
-#if defined (__cplusplus)
+#if defined(__cplusplus)
extern "C" {
#endif
*/
#define MmRpc_E_FAIL (-1)
+/*!
+ * @brief Invalid parameter type
+ */
+#define MmRpc_E_INVALIDPARAM (-2)
+
+/*!
+ * @brief Memory allocation failed
+ */
+#define MmRpc_E_NOMEM (-3)
+
+/*!
+ * @brief A system call failed
+ */
+#define MmRpc_E_SYS (-4)
+
/*!
* @brief Size of parameter array in function context structure
*/
-#define MmRpc_MAX_PARAMETERS (10)
+#define MmRpc_MAX_PARAMS (10)
/*!
* @brief Maximum size of translation array in function context structure
*/
#define MmRpc_MAX_TRANSLATIONS (1024)
+/*!
+ * @brief Macro for computing offset to a field of a structure.
+ *
+ * @code
+ * struct foobar {
+ * int a;
+ * int *p;
+ * };
+ *
+ * struct foobar *sp = ...;
+ * offset = MmRpc_OFFSET(sp, &sp->p);
+ * struct foobar st = ...;
+ * offset = MmRpc_OFFSET(&st, &st.p);
+ * @endcode
+ */
+#define MmRpc_OFFSET(base, field) ((unsigned int)(field)-(unsigned int)(base))
+
/*!
* @brief MmRpc_Handle type
*/
* @brief MmRpc_ParamType enum
*/
typedef enum {
- MmRpc_ParamType_Atomic = 1, /*!< atomic data type */
+ MmRpc_ParamType_Scalar = 1, /*!< pass by value */
MmRpc_ParamType_Ptr, /*!< data pointer */
- MmRpc_ParamType_PtrOffset /*!< pointer offset */
+ MmRpc_ParamType_OffPtr, /*!< buffer at offset in memory block */
+ MmRpc_ParamType_Elem /*!< array element */
} MmRpc_ParamType;
/*!
union {
struct {
size_t size; /*!< size of the data */
- size_t data; /*!< atomic data */
- } atomic;
+ size_t data; /*!< data (pass by value)*/
+ } scalar;
struct {
- size_t size; /*!< size of the data */
+ size_t size; /*!< size of the data referenced */
size_t addr; /*!< pointer value */
size_t handle; /*!< memory allocator handle */
} ptr;
struct {
- size_t size; /*!< size of the data */
- size_t offset; /*!< offset value */
- size_t base; /*!< base pointer value */
+ size_t size; /*!< size (bytes) of param structure */
+ size_t base; /*!< param address */
+ size_t offset; /*!< offset within param */
size_t handle; /*!< memory allocator handle */
- } ptrOffset;
+ } offPtr;
+
} param;
} MmRpc_Param;
typedef struct {
uint32_t index; /*!< parameter index to base pointer */
- ptrdiff_t offset; /*!< offset from the base address to pointer */
- size_t base; /*!< user virtual address */
-} MmRpc_Txlt;
+ ptrdiff_t offset; /*!< offset to embedded pointer
+ *
+ * If param type is MmRpc_ParamType_Ptr, offset
+ * to embedded pointer from addr. If param type
+ * is MmRpc_ParamType_OffPtr, offset to embedded
+ * pointer from base+offset.
+ */
+ size_t base; /*!< addr or file descriptor [+ data offset]
+ *
+ * If param type is MmRpc_ParamType_Ptr, the
+ * value of the embedded pointer. If param type
+ * is MmRpc_ParamType_OffPtr, the file descriptor
+ * of the block referenced by the embedded pointer
+ * plus an optional data offset.
+ */
+ size_t handle; /*!< memory allocator handle */
+} MmRpc_Xlt;
/*!
* @brief Function call context structure
*/
typedef struct {
- uint32_t fxn_id; /*!< The function to call. */
- uint32_t num_params; /*!< Number of elements in param array. */
- MmRpc_Param params[MmRpc_MAX_PARAMETERS];
- /*!< The array of parameters */
- uint32_t num_translations;
- /*!< The number of translations needed
- * in the offsets array */
- MmRpc_Txlt *translations; /*!< array of translations */
+ uint32_t fxn_id; /*!< function id to call */
+ uint32_t num_params; /*!< number of parameters in params array */
+ MmRpc_Param params[MmRpc_MAX_PARAMS];
+ /*!< the array of parameters */
+ uint32_t num_xlts; /*!< number of translations in xltAry */
+ MmRpc_Xlt * xltAry; /*!< array of translations */
} MmRpc_FxnCtx;
+/*!
+ * @brief Memory buffer types
+ *
+ * @remark Not all operating systems support all buffer types.
+ */
+typedef enum {
+ MmRpc_BufType_Handle, /*!< memory allocator handle */
+ MmRpc_BufType_Ptr /*!< buffer address */
+} MmRpc_BufType;
+
+/*!
+ * @brief Memory buffer descriptor
+ */
+typedef union {
+ size_t handle; /*!< file descriptor or handle */
+
+ struct {
+ size_t addr; /*!< address of memory buffer */
+ size_t size; /*!< size (bytes) of memory buffer */
+ } ptr;
+
+} MmRpc_BufDesc;
+
/*!
* @brief Instance create parameters
*/
/*!
* @brief Invoke a remote procedure call
*
+ * @param[in] handle MmRpc handle, obtained from MmRpc_create()
+ * @param[in] ctx Context with which to invoke the remote service
+ * @param[in, out] ret Return value from the remotely invoked service
+ *
+ * @pre @c handle must be a valid handle for the service instance
+ * returned by an earlier call to MmRpc_create().
+ *
+ * @sa MmRpc_create()
+ * @sa MmRpc_delete()
*/
int MmRpc_call(MmRpc_Handle handle, MmRpc_FxnCtx *ctx, int32_t *ret);
/*!
* @brief Create an MmRpc instance
*
+ * @param[in] service Name of the service to create
+ * @param[in] params Initialized MmRpc parameters
+ * @param[in,out] handlePtr Space to hold the MmRpc handle
+ *
+ * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
+ * @retval MmRpc_E_FAIL @copydoc MmRpc_E_FAIL
+ *
+ * @remark This instantiates an instance of the service on a remote
+ * core. Each remote instance consists of a unique thread
+ * listening for requests made via a call to MmRpc_call().
*/
-int MmRpc_create(const char *proc, const char *service,
- const MmRpc_Params *params, MmRpc_Handle *handlPtr);
+int MmRpc_create(const char *service, const MmRpc_Params *params,
+ MmRpc_Handle *handlePtr);
/*!
* @brief Delete an MmRpc instance
*
+ * @param[in] handlePtr MmRpc handle, obtained from MmRpc_create()
+ *
+ * @pre @c handlePtr must be a valid handle for the service instance
+ * returned by an earlier call to MmRpc_create()
+ *
+ * @sa MmRpc_create()
*/
int MmRpc_delete(MmRpc_Handle *handlePtr);
+/*!
+ * @brief Release buffers which were declared in use
+ *
+ * @param[in] handle Service handle returned by MmRpc_create()
+ * @param[in] type Buffer descriptor type
+ * @param[in] num Number of elements in @c desc array
+ * @param[in] desc Pointer to array of buffer descriptors
+ *
+ * @pre @c handle must be a valid handle for the service instance
+ * returned by an earlier call to MmRpc_create().
+ *
+ * @remark When the remote processor no longer needs a reference
+ * to a buffer, calling MmRpc_release() will release the
+ * buffer and any associated resources.
+ *
+ * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
+ * @retval MmRpc_E_INVALIDPARAM @copydoc MmRpc_E_INVALIDPARAM
+ * @retval MmRpc_E_NOMEM @copydoc MmRpc_E_NOMEM
+ * @retval MmRpc_E_SYS @copydoc MmRpc_E_SYS
+ *
+ * @sa MmRpc_use()
+ */
+int MmRpc_release(MmRpc_Handle handle, MmRpc_BufType type, int num,
+ MmRpc_BufDesc *desc);
+
+/*!
+ * @brief Declare the use of the given buffers
+ *
+ * @param[in] handle Service handle returned by MmRpc_create()
+ * @param[in] type Buffer descriptor type
+ * @param[in] num Number of elements in @c desc array
+ * @param[in] desc Pointer to array of buffer descriptors
+ *
+ * @pre @c handle must be a valid handle for the service instance
+ * returned by an earlier call to MmRpc_create().
+ *
+ * @remark When using MmRpc_call() to invoke remote function calls,
+ * any referenced buffers will be made available to the
+ * remote processor only for the duration of the remote
+ * function call. If the remote processor maintains a
+ * reference to the buffer across multiple invocations of
+ * MmRpc_call(), then the application must declare the buffer
+ * "in use". This will make the buffer persistent.
+ *
+ * @remark The application must release the buffer when it is no
+ * longer needed.
+ *
+ * @code
+ * #include <ti/ipc/mm/MmRpc.h>
+ *
+ * MmRpc_BufDesc desc[2];
+ *
+ * desc[0].handle = fd1;
+ * desc[1].handle = fd2;
+ *
+ * MmRpc_use(h, MmRpc_BufType_Handle, 2, desc);
+ * @endcode
+ *
+ * @retval MmRpc_S_SUCCESS @copydoc MmRpc_S_SUCCESS
+ * @retval MmRpc_E_INVALIDPARAM @copydoc MmRpc_E_INVALIDPARAM
+ * @retval MmRpc_E_NOMEM @copydoc MmRpc_E_NOMEM
+ * @retval MmRpc_E_SYS @copydoc MmRpc_E_SYS
+ *
+ * @sa MmRpc_release()
+ */
+int MmRpc_use(MmRpc_Handle handle, MmRpc_BufType type, int num,
+ MmRpc_BufDesc *desc);
+
+/*!
+ * @brief Get the id of an MmRpc instance
+ * (currently only supported in QNX)
+ *
+ * @param[in] handle Service handle returned by MmRpc_create()
+ *
+ * @retval 32-bit id corresponding to the MmRpc instance
+ *
+ * @remark This returns the id corresponding to the MmRpc instance.
+ * This id can be used to identify the MmRpc instance
+ * on the slave core during instance deletion.
+ */
+uint32_t MmRpc_getId(MmRpc_Handle handle);
+
/*!
* @brief Initialize the instance create parameter structure
*
void MmRpc_Params_init(MmRpc_Params *params);
-
-#if defined (__cplusplus)
+#if defined(__cplusplus)
}
#endif
#endif /* ti_ipc_mm_MmRpc__include */