index d6f6c7c77723e07168587100d9af9e14a35a5e83..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
*
* @brief Multi-Media derived Remote Procedure Call
*
- * @note MmRpc is currently only available for Linux and QNX.
- *
- *
+ * @note MmRpc is currently only available for HLOS (Linux, QNX, Android).
*/
#ifndef ti_ipc_mm_MmRpc__include
*/
#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
*/
typedef enum {
MmRpc_ParamType_Scalar = 1, /*!< pass by value */
MmRpc_ParamType_Ptr, /*!< data pointer */
+ MmRpc_ParamType_OffPtr, /*!< buffer at offset in memory block */
MmRpc_ParamType_Elem /*!< array element */
} MmRpc_ParamType;
size_t handle; /*!< memory allocator handle */
} ptr;
-#if 0 /* TBD */
struct {
- size_t size; /*!< size of the array element */
- size_t offset; /*!< offset to current array element */
- size_t base; /*!< base address of array */
+ 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 */
- } elem;
-#endif
+ } 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 */
+ 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;
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 *service, const MmRpc_Params *params,
- MmRpc_Handle *handlPtr);
+ 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)
}
#endif