SDOCM00113609 Add version support for MessageQ_Params structure
authorRamsey Harris <ramsey@ti.com>
Thu, 4 Dec 2014 19:32:12 +0000 (11:32 -0800)
committerRobert Tivy <rtivy@ti.com>
Tue, 9 Dec 2014 18:27:28 +0000 (10:27 -0800)
Added a version field to the params structure; used internally
to track the structure definition changes. MessageQ_Params_init
is now a static inline function which embeds the current version
in the call site. Added new MessageQ_Params_init__S function to
initialize the given params structure. Updated MessageQ_create
to be version aware. Fixed uninitialized params structure in
the MessageQ instance object.

linux/src/api/MessageQ.c
packages/ti/ipc/MessageQ.h
packages/ti/sdo/ipc/MessageQ.c
packages/ti/sdo/ipc/MessageQ.xdc
qnx/src/api/MessageQ.c
qnx/src/ipc3x_dev/ti/syslink/ipc/hlos/knl/MessageQ_daemon.c

index 2fc61e32a10808d1d848d85e94eb52eb008f6928..3d7e8b2d7c498d92d5fbd9595a7a18e838da4da2 100644 (file)
@@ -47,6 +47,7 @@
 #include <ti/ipc/NameServer.h>
 #include <ti/ipc/MultiProc.h>
 #include <_MultiProc.h>
+#define MessageQ_internal 1     /* must be defined before include file */
 #include <ti/ipc/MessageQ.h>
 #include <_MessageQ.h>
 #include <ITransport.h>
  * =============================================================================
  */
 
+/* params structure evolution */
+typedef struct {
+    Void *synchronizer;
+} MessageQ_Params_Legacy;
+
+typedef struct {
+    Int __version;
+    Void *synchronizer;
+    MessageQ_QueueIndex queueIndex;
+} MessageQ_Params_Version2;
+
 /* structure for MessageQ module state */
 typedef struct MessageQ_ModuleObject {
     MessageQ_Handle           *queues;
@@ -108,7 +120,6 @@ typedef struct MessageQ_ModuleObject {
     Int                       refCount;
     NameServer_Handle         nameServer;
     pthread_mutex_t           gate;
-    MessageQ_Params           defaultInstParams;
     int                       seqNum;
     IMessageQTransport_Handle transports[MultiProc_MAXPROCESSORS][2];
     INetworkTransport_Handle  transInst[MessageQ_MAXTRANSPORTS];
@@ -398,20 +409,42 @@ Int MessageQ_destroy(void)
     return status;
 }
 
-
-/* Function to initialize the parameters for the MessageQ instance. */
+/*
+ *  ======== MessageQ_Params_init ========
+ *  Legacy implementation.
+ */
 Void MessageQ_Params_init(MessageQ_Params *params)
 {
-    memcpy (params, &(MessageQ_module->defaultInstParams),
-            sizeof (MessageQ_Params));
+    ((MessageQ_Params_Legacy *)params)->synchronizer = NULL;
+}
 
-    return;
+/*
+ *  ======== MessageQ_Params_init__S ========
+ *  New implementation which is version aware.
+ */
+Void MessageQ_Params_init__S(MessageQ_Params *params, Int version)
+{
+    MessageQ_Params_Version2 *params2;
+
+    switch (version) {
+
+        case MessageQ_Params_VERSION_2:
+            params2 = (MessageQ_Params_Version2 *)params;
+            params2->__version = MessageQ_Params_VERSION_2;
+            params2->synchronizer = NULL;
+            params2->queueIndex = MessageQ_ANY;
+            break;
+
+        default:
+            assert(FALSE);
+            break;
+    }
 }
 
 /*
  *  MessageQ_create - create a MessageQ object for receiving.
  */
-MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params)
+MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *pp)
 {
     Int                   status;
     MessageQ_Object      *obj = NULL;
@@ -424,6 +457,28 @@ MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params)
     LAD_ClientHandle      handle;
     struct LAD_CommandObj cmd;
     union LAD_ResponseObj rsp;
+    MessageQ_Params ps;
+
+    MessageQ_Params_init__S(&ps, MessageQ_Params_VERSION);
+
+    /* copy the given params into the current params structure */
+    if (pp != NULL) {
+
+        /* snoop the params pointer to see if it's a legacy structure */
+        if ((pp->__version == 0) || (pp->__version > 100)) {
+            ps.synchronizer = ((MessageQ_Params_Legacy *)pp)->synchronizer;
+        }
+
+        /* not legacy structure, use params version field */
+        else if (pp->__version == MessageQ_Params_VERSION_2) {
+            ps.__version = ((MessageQ_Params_Version2 *)pp)->__version;
+            ps.synchronizer = ((MessageQ_Params_Version2 *)pp)->synchronizer;
+            ps.queueIndex = ((MessageQ_Params_Version2 *)pp)->queueIndex;
+        }
+        else {
+            assert(FALSE);
+        }
+    }
 
     handle = LAD_findHandle();
     if (handle == LAD_MAXNUMCLIENTS) {
@@ -436,6 +491,7 @@ MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params)
 
     cmd.cmd = LAD_MESSAGEQ_CREATE;
     cmd.clientId = handle;
+
     if (name == NULL) {
         cmd.args.messageQCreate.name[0] = '\0';
     }
@@ -445,9 +501,7 @@ MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params)
         cmd.args.messageQCreate.name[LAD_MESSAGEQCREATEMAXNAMELEN - 1] = '\0';
     }
 
-    if (params) {
-        memcpy(&cmd.args.messageQCreate.params, params, sizeof (*params));
-    }
+    memcpy(&cmd.args.messageQCreate.params, &ps, sizeof(ps));
 
     if ((status = LAD_putCommand(&cmd)) != LAD_SUCCESS) {
         PRINTVERBOSE1(
@@ -475,10 +529,8 @@ MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params)
     /* Create the generic obj */
     obj = (MessageQ_Object *)calloc(1, sizeof (MessageQ_Object));
 
-    if (params != NULL) {
-       /* Populate the params member */
-        memcpy((Ptr) &obj->params, (Ptr)params, sizeof (MessageQ_Params));
-    }
+   /* Populate the params member */
+    memcpy(&obj->params, &ps, sizeof(ps));
 
     queueIndex = (MessageQ_QueueIndex)(rsp.messageQCreate.queueId & 0x0000ffff);
 
index c3a42b3e05733bcd451c83ae419fd87f280333f9..bcbd40632444ef3e33cd8949b53b4e00cdc32663 100644 (file)
@@ -441,6 +441,13 @@ typedef struct MessageQ_Object *MessageQ_Handle;
  *  @brief  Structure defining parameters for MessageQ_create().
  */
 typedef struct {
+/** @cond INTERNAL */
+    Int __version;
+    /*  Used internally for tracking implementation evolution.
+     *  For internal use only.
+     */
+/** @endcond INTERNAL */
+
     Void *synchronizer;
     /*!< Synchronizer instance used to signal IO completion
      *
@@ -450,13 +457,48 @@ typedef struct {
      *  present.
      */
 
+     MessageQ_QueueIndex queueIndex;
+     /*!< Value used to specify the index in the MessageQ array
+      *
+      *  This parameter allows an application to specify a queueIndex to
+      *  be used for a message queue. To use this functionality, the
+      *  MessageQ.numReservedEntries static configuration parameter must be
+      *  set to one more than the highest requested queueIndex. The
+      *  MessageQ.numReservedEntries parameter reserves that number of
+      *  message queue slots starting at 0 and proceeding to
+      *  (MessageQ.numReservedEntries - 1).
+      *
+      *  The default is MessageQ_ANY, which means it is not taken from the
+      *  reserved slots.
+      */
+
 } MessageQ_Params;
 
+/** @cond INTERNAL */
+/*  Date: 02 Dec 2014
+ *
+ *  Initial implementation of params structure which contains
+ *  a version field. This allows for binary compatibility as
+ *  the params structure is modified in the future.
+ */
+#define MessageQ_Params_VERSION_2       2
+/** @endcond INTERNAL */
+
+/** @cond INTERNAL */
+/*!
+ *  @brief      Defines the current params structure version
+ */
+#define MessageQ_Params_VERSION         MessageQ_Params_VERSION_2
+/** @endcond INTERNAL */
+
 /*!
  *  @brief  Structure defining parameters for MessageQ_create2().
  *
  *  MessageQ_Params2 is a superset of MessageQ_Params. It is used
  *  with MessageQ_create2().
+ *
+ *  @deprecated This type has been deprecated. It will be removed
+ *  in a future release. Please use MessageQ_Params instead.
  */
 typedef struct {
     Void *synchronizer;
@@ -522,7 +564,7 @@ typedef enum {
 /*!
  *  @brief      Denotes any queueId is acceptable.
  *
- *  This constant is the default for the queueId in the MessageQ_Params2
+ *  This constant is the default for the queueId in the MessageQ_Params
  *  structure.
  */
 #define MessageQ_ANY (Bits16)~(0)
@@ -567,16 +609,34 @@ Void MessageQ_unregisterTransportId(UInt tid);
  * =============================================================================
  */
 
+/** @cond INTERNAL */
+Void MessageQ_Params_init__S(MessageQ_Params *params, Int version);
+/** @endcond INTERNAL */
+
 /*!
  *  @brief      Initialize MessageQ_Params
  *
+ *  Initialized the given structure to its default values.
+ *
  *  @param[in]  params      Parameters required to create a MessageQ
  */
-Void MessageQ_Params_init(MessageQ_Params *params);
+#ifndef MessageQ_internal
+static inline Void MessageQ_Params_init(MessageQ_Params *params)
+{
+    if (params != NULL) {
+        MessageQ_Params_init__S(params, MessageQ_Params_VERSION);
+    }
+}
+#endif
 
 /*!
  *  @brief      Initialize MessageQ_Params2
  *
+ *  Initialized the given structure to its default values.
+ *
+ *  @deprecated This function has been deprecated. It will be removed
+ *  in a future release. Please use MessageQ_Params_init() instead.
+ *
  *  @param[in]  params      Parameters required to create a MessageQ
  */
 Void MessageQ_Params2_init(MessageQ_Params2 *params);
@@ -600,15 +660,18 @@ Void MessageQ_Params2_init(MessageQ_Params2 *params);
 MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params);
 
 /*!
- *  @brief      Create a MessageQ instance with the MessageQ_Params2 structure
+ *  @brief      Create a MessageQ instance using the type MessageQ_Params2
  *
  *  The name supplied here does not have to be in persistent memory.  The
  *  maximum length of the string supplied here, including the '\\0' terminator,
  *  is '32' by default.
  *
  *  There are no verifications to ensure that the name supplied in
- *  MessageQ_create2() is unique across all processors. Caution must be exercised
- *  to ensure that each processor uses a unique name.
+ *  MessageQ_create2() is unique across all processors. Caution must
+ *  be exercised to ensure that each processor uses a unique name.
+ *
+ *  @deprecated This function has been deprecated. It will be removed
+ *  in a future release. Please use MessageQ_create() instead.
  *
  *  @param[in]  name        Name of the queue
  *  @param[in]  params      Initialized MessageQ_Params2
@@ -652,33 +715,38 @@ Int MessageQ_delete(MessageQ_Handle *handlePtr);
 Int MessageQ_open(String name, MessageQ_QueueId *queueId);
 
 /*!
- *  @brief      Opens a MessageQ given the queue index and remote processor id
+ *  @brief      Opens a MessageQ given the queue index and remote processor ID
  *
- *  This function can be used instead of MessageQ_open() if the queue was created
- *  with a specified QueueIndex.
+ *  This function can be used instead of MessageQ_open() if the queue
+ *  was created with a specified QueueIndex. In the example below, the
+ *  serverFxn function must be running on the processor with PROCID 2.
  *
  *      @code
- *      #define SERVERQUEUEINDEX  1
- *      #define SERVERMULTIPROCID 2
+ *      #define SERVER_QUEIDX   1
+ *      #define SERVER_PROCID   2
  *
- *      serverFxn() {
- *          MessageQ_Params2 params2;
+ *      serverFxn()
+ *      {
+ *          MessageQ_Params params;
  *
- *          MessageQ_Params2_init(&params2);
- *          params2.queueIndex = SERVERQUEUEINDEX;
- *          messageQ = MessageQ_create2("server", &params2);
+ *          MessageQ_Params_init(&params);
+ *          params.queueIndex = SERVER_QIDX;
+ *          messageQ = MessageQ_create("server", &params);
  *          ...
+ *      }
  *
- *      clientFxn() {
+ *      clientFxn()
+ *      {
  *          MessageQ_QueueId serverQueue;
- *          serverQueue = MessageQ_openQueueId(SERVERQUEUEINDEX, SERVERMULTIPROCID);
+ *          serverQueue = MessageQ_openQueueId(SERVER_QUEIDX, SERVER_PROCID);
+ *      }
  *      @endcode
  *
- *  It is up to the application to guarantee that the queue that is being opened
- *  has already been created.  MessageQ_openQueueId() does not validate that
- *  the queue has been created (unlike the MessageQ_open() function).
+ *  It is up to the application to guarantee that the queue which is being
+ *  opened has already been created. MessageQ_openQueueId() does not validate
+ *  that the queue has been created (unlike the MessageQ_open() function).
  *
- *  @param[in] queueIndex   QueueIndex specified in MessageQ_Params2
+ *  @param[in] queueIndex   QueueIndex specified in MessageQ_Params
  *  @param[in] remoteProcId Multiproc_Id of where the created queue resides
  *
  *  @return     The MessageQ_QueueId associated with the queueIndex
index 111ce9278f258b999d597e16072cdab8ac5a2e1a..112dda39a2cc006ba5b7b878463dd18ec94834fc 100644 (file)
 #include <ti/sdo/utils/List.h>
 
 /* must be included after the internal header file for now */
+#define MessageQ_internal 1     /* must be defined before include file */
 #include <ti/sdo/ipc/_MessageQ.h>
 #include <ti/sdo/utils/_MultiProc.h>
 #include <ti/sdo/utils/_NameServer.h>
 
 #include "package/internal/MessageQ.xdc.h"
 
+/* params structure evolution */
+typedef struct {
+    Void *synchronizer;
+} MessageQ_Params_Legacy;
+
+typedef struct {
+    Int __version;
+    Void *synchronizer;
+    MessageQ_QueueIndex queueIndex;
+} MessageQ_Params_Version2;
+
 #ifdef __ti__
     #pragma FUNC_EXT_CALLED(MessageQ_Params_init);
     #pragma FUNC_EXT_CALLED(MessageQ_Params2_init);
@@ -119,14 +131,39 @@ static Void MessageQ_msgInit(MessageQ_Msg msg)
 
 /*
  *  ======== MessageQ_Params_init ========
+ *  Legacy implementation.
  */
 Void MessageQ_Params_init(MessageQ_Params *params)
 {
-    params->synchronizer = NULL;
+    ((MessageQ_Params_Legacy *)params)->synchronizer = NULL;
+}
+
+/*
+ *  ======== MessageQ_Params_init__S ========
+ *  New implementation which is version aware.
+ */
+Void MessageQ_Params_init__S(MessageQ_Params *params, Int version)
+{
+    MessageQ_Params_Version2 *params2;
+
+    switch (version) {
+
+        case MessageQ_Params_VERSION_2:
+            params2 = (MessageQ_Params_Version2 *)params;
+            params2->__version = MessageQ_Params_VERSION_2;
+            params2->synchronizer = NULL;
+            params2->queueIndex = MessageQ_ANY;
+            break;
+
+        default:
+            Assert_isTrue(FALSE, NULL);
+            break;
+    }
 }
 
 /*
  *  ======== MessageQ_Params2_init ========
+ *  Deprecated
  */
 Void MessageQ_Params2_init(MessageQ_Params2 *params)
 {
@@ -221,19 +258,36 @@ Int MessageQ_close(MessageQ_QueueId *queueId)
 /*
  *  ======== MessageQ_create ========
  */
-MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params)
+MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *pp)
 {
-    MessageQ_Handle handle;
-    MessageQ_Params2 params2;
+    ti_sdo_ipc_MessageQ_Handle handle;
+    ti_sdo_ipc_MessageQ_Params ps;
+    Error_Block eb;
 
-    MessageQ_Params2_init(&params2);
+    Error_init(&eb);
 
-    /* Use the MessageQ_Params fields if not NULL */
-    if (params != NULL) {
-        params2.synchronizer = params->synchronizer;
-    }
+    if (pp != NULL) {
+        ti_sdo_ipc_MessageQ_Params_init(&ps);
+
+        /* snoop the params pointer to see if it's a legacy structure */
+        if ((pp->__version == 0) || (pp->__version > 100)) {
+            ps.synchronizer = ((MessageQ_Params_Legacy *)pp)->synchronizer;
+        }
 
-    handle = MessageQ_create2(name, &params2);
+        /* not legacy structure, use params version field */
+        else if (pp->__version == MessageQ_Params_VERSION_2) {
+            ps.synchronizer = ((MessageQ_Params_Version2 *)pp)->synchronizer;
+            ps.queueIndex = ((MessageQ_Params_Version2 *)pp)->queueIndex;
+        }
+        else {
+            Assert_isTrue(FALSE, NULL);
+        }
+
+        handle = ti_sdo_ipc_MessageQ_create(name, &ps, &eb);
+    }
+    else {
+        handle = ti_sdo_ipc_MessageQ_create(name, NULL, &eb);
+    }
 
     return ((MessageQ_Handle)handle);
 }
index 6b597bc69814a6a70d691dc0d5b6f2f98a28899a..ca32bb906664b8c9b487201278d9d189e67b31d2 100644 (file)
@@ -642,8 +642,8 @@ instance:
      *
      *  This parameter allows an application to specify the queueIndex to
      *  be used for a message queue. To use this functionality, the
-     *  MessageQ.numReservedEntries static configuration parameter must be set to
-     *  a specific value.
+     *  MessageQ.numReservedEntries static configuration parameter must be
+     *  set to a specific value.
      *
      *  The default is {@link #ANY}. This means do that you are not asking for
      *  an explicit index. MessageQ will find the first available one which is
index 189e652b1b4cbd3fc0f7320f5add37043ed899cd..66a9219995041afcd99e630fcbc40381a6686e44 100644 (file)
 #include <ti/ipc/NameServer.h>
 #include <ti/ipc/MultiProc.h>
 #include <ti/syslink/inc/_MultiProc.h>
+#define MessageQ_internal 1     /* must be defined before include file */
 #include <ti/ipc/MessageQ.h>
 #include <_MessageQ.h>
 #include <_IpcLog.h>
  * =============================================================================
  */
 
+/* params structure evolution */
+typedef struct {
+    Void *synchronizer;
+} MessageQ_Params_Legacy;
+
+typedef struct {
+    Int __version;
+    Void *synchronizer;
+    MessageQ_QueueIndex queueIndex;
+} MessageQ_Params_Version2;
+
 /* structure for MessageQ module state */
 typedef struct MessageQ_ModuleObject {
     Int                 refCount;
@@ -190,8 +202,6 @@ typedef struct MessageQ_ModuleObject {
     /*!< Handle to the local NameServer used for storing GP objects */
     pthread_mutex_t     gate;
     /*!< Handle of gate to be used for local thread safety */
-    MessageQ_Params     defaultInstParams;
-    /*!< Default instance creation parameters */
     int                 ipcFd[MultiProc_MAXPROCESSORS];
     /*!< File Descriptors for sending to each remote processor */
     int                 seqNum;
@@ -321,13 +331,36 @@ Int MessageQ_destroy (void)
     return status;
 }
 
-/* Function to initialize the parameters for the MessageQ instance. */
-Void MessageQ_Params_init (MessageQ_Params * params)
+/*
+ *  ======== MessageQ_Params_init ========
+ *  Legacy implementation.
+ */
+Void MessageQ_Params_init(MessageQ_Params *params)
 {
-    memcpy (params, &(MessageQ_module->defaultInstParams),
-            sizeof (MessageQ_Params));
+    ((MessageQ_Params_Legacy *)params)->synchronizer = NULL;
+}
 
-    return;
+/*
+ *  ======== MessageQ_Params_init__S ========
+ *  New implementation which is version aware.
+ */
+Void MessageQ_Params_init__S(MessageQ_Params *params, Int version)
+{
+    MessageQ_Params_Version2 *params2;
+
+    switch (version) {
+
+        case MessageQ_Params_VERSION_2:
+            params2 = (MessageQ_Params_Version2 *)params;
+            params2->__version = MessageQ_Params_VERSION_2;
+            params2->synchronizer = NULL;
+            params2->queueIndex = MessageQ_ANY;
+            break;
+
+        default:
+            assert(FALSE);
+            break;
+    }
 }
 
 /*
@@ -337,7 +370,7 @@ Void MessageQ_Params_init (MessageQ_Params * params)
  *   (local ProcId/MessageQ ID) in
  *   order to get messages dispatched to this messageQ.
  */
-MessageQ_Handle MessageQ_create (String name, const MessageQ_Params * params)
+MessageQ_Handle MessageQ_create (String name, const MessageQ_Params * pp)
 {
     Int                   status    = MessageQ_S_SUCCESS;
     MessageQ_Object *     obj    = NULL;
@@ -345,9 +378,32 @@ MessageQ_Handle MessageQ_create (String name, const MessageQ_Params * params)
     UInt16                procId;
     MessageQDrv_CmdArgs   cmdArgs;
     int                   fildes[2];
+    MessageQ_Params       ps;
+
+    MessageQ_Params_init__S(&ps, MessageQ_Params_VERSION);
+
+    /* copy the given params into the current params structure */
+    if (pp != NULL) {
+
+        /* snoop the params pointer to see if it's a legacy structure */
+        if ((pp->__version == 0) || (pp->__version > 100)) {
+            ps.synchronizer = ((MessageQ_Params_Legacy *)pp)->synchronizer;
+        }
+
+        /* not legacy structure, use params version field */
+        else if (pp->__version == MessageQ_Params_VERSION_2) {
+            ps.__version = ((MessageQ_Params_Version2 *)pp)->__version;
+            ps.synchronizer = ((MessageQ_Params_Version2 *)pp)->synchronizer;
+            ps.queueIndex = ((MessageQ_Params_Version2 *)pp)->queueIndex;
+        }
+        else {
+            assert(FALSE);
+        }
+    }
 
-    cmdArgs.args.create.params = (MessageQ_Params *) params;
+    cmdArgs.args.create.params = &ps;
     cmdArgs.args.create.name = name;
+
     if (name != NULL) {
         cmdArgs.args.create.nameLen = (strlen (name) + 1);
     }
@@ -383,10 +439,8 @@ MessageQ_Handle MessageQ_create (String name, const MessageQ_Params * params)
         goto cleanup;
     }
 
-    if (params != NULL) {
-       /* Populate the params member */
-        memcpy((Ptr) &obj->params, (Ptr)params, sizeof (MessageQ_Params));
-    }
+   /* Populate the params member */
+    memcpy(&obj->params, &ps, sizeof(ps));
 
     procId = MultiProc_self();
     obj->queue = cmdArgs.args.create.queueId;
index 7a96268c46de319de14e69bc179dc555fd2f125c..0d84713df66b8fd0b52956a79af849cd9fb5b3a1 100644 (file)
@@ -350,17 +350,6 @@ exitDestroy:
     return (status);
 }
 
-/* Function to initialize the parameters for the MessageQ instance. */
-Void MessageQ_Params_init(MessageQ_Params * params)
-{
-    memcpy(params, &(MessageQ_module->defaultInstParams),
-           sizeof(MessageQ_Params));
-
-    return;
-}
-
-
-
 /*
  *   Function to create a MessageQ object for receiving.
  */