Added MmRpc_use()/MmRpc_release() API functions.
authorRamsey Harris <ramsey@ti.com>
Fri, 30 Aug 2013 00:31:43 +0000 (17:31 -0700)
committerChris Ring <cring@ti.com>
Fri, 30 Aug 2013 02:08:53 +0000 (19:08 -0700)
These functions call into the driver to make the buffers
persistent from the remote processor view. This allows the
remote processor to maintain persistent references to the
buffers across multiple calls to MmRcp_call().

packages/ti/ipc/mm/MmRpc.c
packages/ti/ipc/mm/MmRpc.h
packages/ti/ipc/tests/Mx.c
qnx/src/ipc3x_dev/ti/syslink/inc/ti/ipc/rpmsg_rpc.h

index e6f0c119671eb9cf3b32b086e53bdb1b7a49071a..b9c7e61bfdae7d38e3d5e61abffa90169be44791 100644 (file)
 
 #include "MmRpc.h"
 
+#if defined(KERNEL_INSTALL_DIR) || defined(IPC_BUILDOS_ANDROID)
+static int MmRpc_bufHandle(MmRpc_Handle handle, int cmd, int num,
+        MmRpc_BufDesc *desc);
+#endif
+
 
 /*
  *  ======== MmRpc_Object ========
@@ -284,3 +289,104 @@ leave:
 
     return(status);
 }
+
+/*
+ *  ======== MmRcp_release ========
+ */
+int MmRpc_release(MmRpc_Handle handle, MmRpc_BufType type, int num,
+        MmRpc_BufDesc *desc)
+{
+    int stat = MmRpc_S_SUCCESS;
+
+    switch (type) {
+
+#if defined(KERNEL_INSTALL_DIR) || defined(IPC_BUILDOS_ANDROID)
+        case MmRpc_BufType_Handle:
+            stat = MmRpc_bufHandle(handle, RPPC_IOC_BUFUNREGISTER, num, desc);
+            break;
+
+#elif defined(SYSLINK_BUILDOS_QNX)
+        case MmRpc_BufType_Ptr:
+            break;
+#endif
+        default:
+            printf("MmRpc_release: Error: unsupported type value: %d\n", type);
+            stat = MmRpc_E_INVALIDPARAM;
+            break;
+    }
+
+    if (stat < 0) {
+        printf("MmRpc_release: Error: unable to release buffer\n");
+    }
+
+    return(stat);
+}
+
+/*
+ *  ======== MmRcp_use ========
+ */
+int MmRpc_use(MmRpc_Handle handle, MmRpc_BufType type, int num,
+        MmRpc_BufDesc *desc)
+{
+    int stat = MmRpc_S_SUCCESS;
+
+    switch (type) {
+
+#if defined(KERNEL_INSTALL_DIR) || defined(IPC_BUILDOS_ANDROID)
+        case MmRpc_BufType_Handle:
+            stat = MmRpc_bufHandle(handle, RPPC_IOC_BUFREGISTER, num, desc);
+            break;
+
+#elif defined(SYSLINK_BUILDOS_QNX)
+        case MmRpc_BufType_Ptr:
+            break;
+#endif
+        default:
+            printf("MmRpc_use: Error: unsupported type value: %d\n", type);
+            stat = MmRpc_E_INVALIDPARAM;
+            break;
+    }
+
+    if (stat < 0) {
+        printf("MmRpc_use: Error: unable to declare buffer use\n");
+    }
+
+    return(stat);
+}
+
+#if defined(KERNEL_INSTALL_DIR) || defined(IPC_BUILDOS_ANDROID)
+/*
+ *  ======== MmRpc_bufHandle ========
+ */
+int MmRpc_bufHandle(MmRpc_Handle handle, int cmd, int num, MmRpc_BufDesc *desc)
+{
+    int stat = MmRpc_S_SUCCESS;
+    MmRpc_Object *obj = (MmRpc_Object *)handle;
+    int i;
+    struct rppc_buf_fds reg = { num, NULL };
+
+    reg.fds = (int32_t *)malloc(num * sizeof(int32_t));
+
+    if (reg.fds == NULL) {
+        stat = MmRpc_E_NOMEM;
+        goto leave;
+    }
+
+    for (i = 0; i < num; i++) {
+        reg.fds[i] = desc[i].handle;
+    }
+
+    stat = ioctl(obj->fd, cmd, &reg);
+
+    if (stat < 0) {
+        stat = MmRpc_E_SYS;
+    }
+
+leave:
+    if (reg.fds != NULL) {
+        free(reg.fds);
+    }
+
+    return(stat);
+}
+#endif
index 2ad16ac82b3bc0fdd8827f431e1fe31111edaecd..14b36a6cd172916a848fc61ee1cae5da1dd0ddc9 100644 (file)
@@ -66,6 +66,16 @@ extern "C" {
  */
 #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
  */
@@ -168,6 +178,29 @@ typedef struct {
     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
  */
@@ -194,6 +227,70 @@ int MmRpc_create(const char *service, const MmRpc_Params *params,
  */
 int MmRpc_delete(MmRpc_Handle *handlePtr);
 
+/*!
+ *  @brief      Release buffers which were declared in use
+ *
+ *  @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
+ *
+ *  @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
+ *  @retval     MmRpc_E_INVALIDPARAM
+ *  @retval     MmRpc_E_NOMEM
+ *  @retval     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]  type    buffer descriptor type
+ *
+ *  @param[in]  num     number of elements in @c desc array
+ *
+ *  @param[in]  desc    pointer to array of buffer descriptors
+ *
+ *  @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
+ *  @retval     MmRpc_E_INVALIDPARAM
+ *  @retval     MmRpc_E_NOMEM
+ *  @retval     MmRpc_E_SYS
+ *
+ *  @sa         MmRpc_release()
+ */
+int MmRpc_use(MmRpc_Handle handle, MmRpc_BufType type, int num,
+        MmRpc_BufDesc *desc);
+
 /*!
  *  @brief      Initialize the instance create parameter structure
  *
@@ -201,7 +298,6 @@ int MmRpc_delete(MmRpc_Handle *handlePtr);
 void MmRpc_Params_init(MmRpc_Params *params);
 
 
-
 #if defined(__cplusplus)
 }
 #endif
index a0e8a6d603a495b5ee9b7cb61a3b45241c97d49e..8220fdda844ff423b9d4d5e4fa7ca259c26f7431 100644 (file)
@@ -176,6 +176,29 @@ int32_t Mx_compute_Linux(Mx_Compute *compute, int fd, int fdIn, int fdOut)
     int32_t fxnRet;
     char send_buf[512] = {0};
     int status;
+    MmRpc_BufDesc desc[1];
+    int num = 0;
+
+    /* make the output buffer persistent */
+#if defined(SYSLINK_BUILDOS_QNX)
+    desc[0].ptr.addr = compute->outBuf;
+    desc[0].ptr.size = compute->size * sizeof(uint32_t);
+    num = 1;
+
+    status = MmRpc_use(Mx_rpcIpu, MmRpc_BufType_Ptr, num, desc);
+#else
+    desc[0].handle = fdOut;
+    num = 1;
+
+    status = MmRpc_use(Mx_rpcIpu, MmRpc_BufType_Handle, num, desc);
+#endif
+
+    if (status < 0) {
+        printf("mmrpc_test: Error: MmRpc_use failed\n");
+        num = 0;
+        fxnRet = -1;
+        goto leave;
+    }
 
     /* marshall function arguments into the send buffer */
     fxnCtx = (MmRpc_FxnCtx *)send_buf;
@@ -218,6 +241,22 @@ int32_t Mx_compute_Linux(Mx_Compute *compute, int fd, int fdIn, int fdOut)
     if (status < 0) {
         printf("mmrpc_test: Error: MmRpc_call failed\n");
         fxnRet = -1;
+        goto leave;
+    }
+
+leave:
+    /* release the output buffer */
+    if (num > 0) {
+#if defined(SYSLINK_BUILDOS_QNX)
+        status = MmRpc_release(Mx_rpcIpu, MmRpc_BufType_Ptr, num, desc);
+#else
+        status = MmRpc_release(Mx_rpcIpu, MmRpc_BufType_Handle, num, desc);
+#endif
+
+        if (status < 0) {
+            printf("mmrpc_test: Error: MmRpc_release failed\n");
+            fxnRet = -1;
+        }
     }
 
     return(fxnRet);
index 3fef5a84e8d80e930e4068eed3d4f12623fb6ba0..f5da53193b2d5c545896a31a12fcf1116c92780c 100644 (file)
 
 #define __packed __attribute__ ((packed))
 
+/**
+ * struct rppc_buf_fds - rppc buffer registration/deregistration
+ * @num: number of file descriptors
+ * @fds: pointer to the array holding the file descriptors
+ */
+struct rppc_buf_fds {
+       uint32_t num;
+       int32_t *fds;
+};
+
+/*
+ * ioctl definitions
+ */
 #define RPPC_IOC_MAGIC         'r'
 #define RPPC_IOC_CREATE                _IOW(RPPC_IOC_MAGIC, 1, struct rppc_create_instance)
-/* TODO: these may not be needed */
-#define RPPC_IOC_BUFREGISTER    _IOW(RPPC_IOC_MAGIC, 2, int)
-#define RPPC_IOC_BUFUNREGISTER  _IOW(RPPC_IOC_MAGIC, 3, int)
+#define RPPC_IOC_BUFREGISTER    _IOW(RPPC_IOC_MAGIC, 2, struct rppc_buf_fds)
+#define RPPC_IOC_BUFUNREGISTER  _IOW(RPPC_IOC_MAGIC, 3, struct rppc_buf_fds)
 #define RPPC_IOC_MAXNR         (4)
 
 #define RPPC_MAX_PARAMETERS    (10)
 #define RPPC_MAX_TRANSLATIONS  (1024)
+#define RPPC_MAX_INST_NAMELEN  (48)
 
+/**
+ * enum rppc_param_type - RPC function parameter type
+ * @RPPC_PARAM_TYPE_UNKNOWN: unrecognized parameter
+ * @RPPC_PARAM_TYPE_ATOMIC: an atomic data type, 1 byte to architecture limit
+ *                         sized bytes
+ * @RPPC_PARAM_TYPE_PTR: a pointer to shared memory. The reserved field in the
+ *                      structures rppc_param and rppc_param_translation must
+ *                      contain the file descriptor of the associated dma_buf
+ * @RPPC_PARAM_TYPE_STRUCT: (unsupported) a structure type. Will be architecture
+ *                         width aligned in memory
+ *
+ * These enum values are used to identify the parameter type for every
+ * parameter argument of the remote function.
+ */
 enum rppc_param_type {
        RPPC_PARAM_TYPE_UNKNOWN = 0,
-       /* An atomic data type, 1 byte to architecture limit sized bytes */
        RPPC_PARAM_TYPE_ATOMIC,
-       /*
-        * A pointer to shared memory. The reserved field must contain
-        * the handle to the memory
-        */
        RPPC_PARAM_TYPE_PTR,
-       /*
-        * (Unsupported) A structure type. Will be architecure width
-        * aligned in memory.
-        */
        RPPC_PARAM_TYPE_STRUCT,
 };
 
+/**
+ * struct rppc_param_translation - pointer translation helper structure
+ * @index: index of the parameter where the translation needs to be done in.
+ *        used for indicating the base pointer
+ * @offset: offset from the base address to the pointer to translate
+ * @base: the base user virtual address of the pointer to translate (used to
+ *       calculate translated pointer offset).
+ * @reserved: reserved field, expected to contain the dma_buf file descriptor.
+ */
 struct rppc_param_translation {
-       /* The parameter index which indicates which is the base pointer */
-       uint32_t  index;
-       /* The offset from the base address to the pointer to translate */
+       uint32_t index;
        ptrdiff_t offset;
-       /*
-        * The base user virtual address of the pointer to translate
-        * (used to calculate translated pointer offset).
-        */
        size_t base;
-       /* reserved field */
        size_t reserved;
 };
 
+/**
+ * struct rppc_param - descriptor structure for each parameter
+ * @type: type of the parameter, as dictated by enum rppc_param_type
+ * @size: size of the data
+ * @data: either the parameter value itself (for atomic type) or
+ *       the actual user space pointer address to the data (for pointer type)
+ * @base: the base user space pointer address of the original allocated buffer,
+ *       providing a reference if data has the pointer that is at an offset
+ *       from the original pointer
+ * @reserved: file descriptor of the exported allocation (will be used to
+ *           import the associated dma_buf within the driver).
+ */
 struct rppc_param {
-       uint32_t type;          /* rppc_param_type */
-       size_t size;            /* The size of the data */
-       size_t data;            /* Either the pointer to the data or
-                               the data itself */
-       size_t base;            /* If a pointer is in data, this is the base
-                               pointer (if data has an offset from base). */
-       size_t reserved;        /* Shared Memory Handle (used only with ptrs) */
+       uint32_t type;
+       size_t size;
+       size_t data;
+       size_t base;
+       size_t reserved;
 };
 
+/**
+ * struct rppc_function - descriptor structure for the remote function
+ * @fxn_id: index of the function to invoke on the opened rppc device
+ * @num_params: number of parameters filled in the params field
+ * @params: array of parameter descriptor structures
+ * @num_translations: number of in-place translations to be performed within
+ *                   the arguments.
+ * @translations: an open array of the translation descriptor structures, whose
+ *               length is passed in num_translations. Used for translating
+ *               the pointers within the function data.
+ *
+ * This is the primary descriptor structure passed down from the userspace,
+ * describing the function, its parameter arguments and the needed translations.
+ */
 struct rppc_function {
-       /* The function to call */
        uint32_t fxn_id;
-       /* The number of parameters in the array. */
        uint32_t num_params;
-       /* The array of parameters */
        struct rppc_param params[RPPC_MAX_PARAMETERS];
-       /* The number of translations needed in the offsets array */
        uint32_t num_translations;
-       /*
-        * An indeterminate length array of offsets within
-        * payload_data to pointers which need translation
-        */
        struct rppc_param_translation translations[0];
 };
 
+/**
+ * struct rppc_function_return - function return status descriptor structure
+ * @fxn_id: index of the function invoked on the opened rppc device
+ * @status: return value of the executed function
+ */
 struct rppc_function_return {
        uint32_t fxn_id;
        uint32_t status;
 };
 
+/*
+ * helper macros for manipulating the function index in the marshalled packet
+ */
 #define RPPC_DESC_EXEC_SYNC    (0x0100)
 #define RPPC_DESC_TYPE_MASK    (0x0F00)
 
-/* TODO: Remove the relative offset */
-/** The remote functions are offset by one relative to the client */
+/*
+ * helper macros for manipulating the function index in the marshalled packet.
+ * The remote functions are offset by one relative to the client
+ * XXX: Remove the relative offset
+ */
 #define RPPC_SET_FXN_IDX(idx)  (((idx) + 1) | 0x80000000)
-
-/** The remote functions are offset by one relative to the client */
 #define RPPC_FXN_MASK(idx)     (((idx) - 1) & 0x7FFFFFFF)
 
-/* TODO: remove or mask unneeded fields for RFC */
-/** This is actually a frankensteined structure of RCM */
+/**
+ * struct rppc_packet - the actual marshalled packet
+ * @desc: type of function execution, currently only synchronous function
+ *       invocations are supported
+ * @msg_id: an incremental message index identifier
+ * @flags: a combination of job id and pool id of the worker threads
+ *        of the server
+ * @fxn_id: id of the function to execute
+ * @result: result of the remotely executed function
+ * @data_size: size of the payload packet
+ * @data: variable payload, containing the marshalled function data.
+ *
+ * This is actually a condensed structure of the Remote Command Messaging
+ * (RCM) structure. The initial fields of the structure are used by the
+ * remote-side server to schedule the execution of the function. The actual
+ * variable payload data starts from the .data field.
+ * XXX: remove or mask unneeded fields, some fields can be stripped down
+ */
 struct rppc_packet {
-       uint16_t desc;          /* RcmClient_Packet.desc */
-       uint16_t msg_id;        /* RcmClient_Packet.msgId */
-       uint32_t flags;         /* RcmClient_Message.jobId & poolId */
-       uint32_t fxn_id;        /* RcmClient_Message.fxnIdx */
-       int32_t  result;        /* RcmClient_Message.result */
-       uint32_t data_size;     /* RcmClient_Message.data_size */
-       uint8_t  data[0];       /* RcmClient_Message.data pointer */
+       uint16_t desc;
+       uint16_t msg_id;
+       uint32_t flags;
+       uint32_t fxn_id;
+       int32_t  result;
+       uint32_t data_size;
+       uint8_t  data[0];
 } __packed;
 
 
@@ -147,7 +208,15 @@ struct rppc_create_instance {
        char name[RPPC_MAX_CHANNEL_NAMELEN];
 };
 
-/** The parameter direction as relative to the function it describes */
+/**
+ * enum rppc_param_direction - direction of the function parameter
+ * @RPPC_PARAMDIR_IN: input argument
+ * @RPPC_PARAMDIR_OUT: output argument
+ * @RPPC_PARAMDIR_BI: an in and out argument
+ * @RPPC_PARAMDIR_MAX: limit value for the direction type
+ *
+ * The parameter direction is described as relative to the function.
+ */
 enum rppc_param_direction {
        RPPC_PARAMDIR_IN = 0,
        RPPC_PARAMDIR_OUT,
@@ -155,6 +224,26 @@ enum rppc_param_direction {
        RPPC_PARAMDIR_MAX
 };
 
+/**
+ * enum rppc_param_datatype - parameter data type and descriptor flags
+ * @RPPC_PARAM_VOID: parameter is of type 'void'
+ * @RPPC_PARAM_S08: parameter is of type 's8'
+ * @RPPC_PARAM_U08: parameter is of type 'u8'
+ * @RPPC_PARAM_S16: parameter is of type 's16'
+ * @RPPC_PARAM_U16: parameter is of type 'u16'
+ * @RPPC_PARAM_S32: parameter is of type 's32'
+ * @RPPC_PARAM_U32: parameter is of type 'u32'
+ * @RPPC_PARAM_S64: parameter is of type 's64'
+ * @RPPC_PARAM_U64: parameter is of type 'u64'
+ * @RPPC_PARAM_ATOMIC_MAX: limit value for scalar data types
+ * @RPPC_PARAM_MASK: mask field for retrieving the scalar data type
+ * @RPPC_PARAM_PTR: flag to indicate the data type is a pointer
+ * @RPPC_PARAM_MAX: max limit value used as a marker
+ *
+ * This enum is used to describe the data type for the parameters.
+ * A pointer of a data type is reflected by using an additional bit
+ * mask field.
+ */
 enum rppc_param_datatype {
        RPPC_PARAM_VOID = 0,
        RPPC_PARAM_S08,
@@ -168,15 +257,18 @@ enum rppc_param_datatype {
        RPPC_PARAM_ATOMIC_MAX,
 
        RPPC_PARAM_MASK = 0x7F,
-       RPPC_PARAM_PTR = 0x80, /**< Logically OR'd with lower type to make a
-                                   pointer to the correct type */
+       RPPC_PARAM_PTR = 0x80,
+
        RPPC_PARAM_MAX
 };
 
-#define RPPC_PTR_TYPE(type)    (type | RPPC_PARAM_PTR)
-#define RPPC_IS_PTR(type)      (type & RPPC_PARAM_PTR)
-#define RPPC_IS_ATOMIC(type)   ((type > RPPC_PARAM_VOID) && \
-                                       (type < RPPC_PARAM_ATOMIC_MAX))
+/*
+ * helper macros to deal with parameter types
+ */
+#define RPPC_PTR_TYPE(type)    ((type) | RPPC_PARAM_PTR)
+#define RPPC_IS_PTR(type)      ((type) & RPPC_PARAM_PTR)
+#define RPPC_IS_ATOMIC(type)   (((type) > RPPC_PARAM_VOID) && \
+                                ((type) < RPPC_PARAM_ATOMIC_MAX))
 
 //#endif /* __KERNEL__ */