Merge pull request #595 from jphickey/fix-589-objid-to-arrayindex

Fix #589, promote OS_ObjectIdToArrayIndex to public API

Author: yammajamma

src/os/inc/osapi-os-core.h

@@ -428,6 +428,12 @@ uint32 OS_IdentifyObject       (osal_id_t object_id);
  * @note This does NOT verify the validity of the ID, that is left to the caller.
  * This is only the conversion logic.
  *
+ * This routine accepts any object type, and returns a value based on the
+ * maximum number of objects for that type.  This is equivalent to invoking
+ * OS_ObjectIdToArrayIndex() with the idtype set to OS_OBJECT_TYPE_UNDEFINED.
+ *
+ * @sa OS_ObjectIdToArrayIndex
+ *
  * @param[in]  object_id    The object ID to operate on
  * @param[out] *ArrayIndex  The Index to return 
  *
@@ -437,6 +443,39 @@ uint32 OS_IdentifyObject       (osal_id_t object_id);
  */
 int32 OS_ConvertToArrayIndex   (osal_id_t object_id, uint32 *ArrayIndex);
 
+/*-------------------------------------------------------------------------------------*/
+/**
+ * @brief Converts an abstract ID into a number suitable for use as an array index.
+ *
+ * This will return a unique zero-based integer number in the range of [0,MAX) for
+ * any valid object ID.  This may be used by application code as an array index
+ * for indexing into local tables.
+ *
+ * This routine operates on a specific object type, and returns a value based on the
+ * maximum number of objects for that type.
+ *
+ * If the idtype is passed as #OS_OBJECT_TYPE_UNDEFINED, then object type verification
+ * is skipped and any object ID will be accepted and converted to an index.  In this
+ * mode, the range of the output depends on the actual passed-in object type.
+ *
+ * If the idtype is passed as any other value, the passed-in ID value is first
+ * confirmed to be the correct type.  This check will guarantee that the output
+ * is within an expected range; for instance, if the type is passed as
+ * #OS_OBJECT_TYPE_OS_TASK, then the output index is guaranteed to be between 0 and
+ * #OS_MAX_TASKS-1 after successful conversion.
+ *
+ * @param[in]  idtype       The object type to convert
+ * @param[in]  object_id    The object ID to operate on
+ * @param[out] *ArrayIndex  The Index to return
+ *
+ * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_SUCCESS                 @copybrief OS_SUCCESS
+ * @retval #OS_ERR_INCORRECT_OBJ_TYPE  @copybrief OS_ERR_INCORRECT_OBJ_TYPE
+ * */
+int32 OS_ObjectIdToArrayIndex(uint32 idtype, osal_id_t id, uint32 *ArrayIndex);
+
+
+
 /*-------------------------------------------------------------------------------------*/
 /**
  * @brief call the supplied callback function for all valid object IDs

src/os/shared/inc/os-shared-idmap.h

@@ -216,15 +216,6 @@ uint32 OS_GetBaseForObjectType(uint32 idtype);
  ------------------------------------------------------------------*/
 int32 OS_ObjectIdFindByName (uint32 idtype, const char *name, osal_id_t *object_id);
 
-/*----------------------------------------------------------------
-   Function: OS_ObjectIdToArrayIndex
-
-    Purpose: Convert a 32-bit OSAL ID into a zero-based array index
-
-    Returns: OS_SUCCESS on success, or relevant error code
- ------------------------------------------------------------------*/
-int32 OS_ObjectIdToArrayIndex(uint32 idtype, osal_id_t id, uint32 *ArrayIndex);
-
 /*----------------------------------------------------------------
    Function: OS_ObjectIdGetBySearch
 

src/os/shared/src/osapi-idmap.c

@@ -663,58 +663,6 @@ void OS_Unlock_Global(uint32 idtype)
     }
 }
 
-
-/*----------------------------------------------------------------
- *
- * Function: OS_ObjectIdToArrayIndex
- *
- *  Purpose: Local helper routine, not part of OSAL API.
- *           Convert an object ID (which must be of the given type) to a number suitable
- *           for use as an array index.  The array index will be in the range of:
- *            0 <= ArrayIndex < OS_MAX_<OBJTYPE>
- *
- *            If the passed-in ID type is OS_OBJECT_TYPE_UNDEFINED, then any type
- *            is allowed.
- *
- *  returns: If the passed-in ID is not of the proper type, OS_ERROR is returned
- *           Otherwise OS_SUCCESS is returned.
- *
- *-----------------------------------------------------------------*/
-int32 OS_ObjectIdToArrayIndex(uint32 idtype, osal_id_t id, uint32 *ArrayIndex)
-{
-   uint32 max_id;
-   uint32 obj_index;
-   uint32 actual_type;
-   int32 return_code;
-
-   obj_index = OS_ObjectIdToSerialNumber_Impl(id);
-   actual_type = OS_ObjectIdToType_Impl(id);
-
-   /*
-    * If requested by the caller, enforce that the ID is of the correct type.
-    * If the caller passed OS_OBJECT_TYPE_UNDEFINED, then anything is allowed.
-    */
-   if (idtype != OS_OBJECT_TYPE_UNDEFINED && actual_type != idtype)
-   {
-       return_code = OS_ERR_INVALID_ID;
-   }
-   else
-   {
-       max_id = OS_GetMaxForObjectType(actual_type);
-       if (max_id == 0)
-       {
-           return_code = OS_ERR_INVALID_ID;
-       }
-       else
-       {
-           return_code = OS_SUCCESS;
-           *ArrayIndex = obj_index % max_id;
-       }
-   }
-
-   return return_code;
-} /* end OS_ObjectIdToArrayIndex */
-
 /*----------------------------------------------------------------
  *
  * Function: OS_ObjectIdFinalizeNew
@@ -1249,3 +1197,54 @@ int32 OS_GetResourceName(osal_id_t object_id, char *buffer, uint32 buffer_size)
 } /* end OS_GetResourceName */
 
 
+/*----------------------------------------------------------------
+ *
+ * Function: OS_ObjectIdToArrayIndex
+ *
+ *  Purpose: Convert an object ID (which must be of the given type) to a number suitable
+ *           for use as an array index.  The array index will be in the range of:
+ *            0 <= ArrayIndex < OS_MAX_<OBJTYPE>
+ *
+ *            If the passed-in ID type is OS_OBJECT_TYPE_UNDEFINED, then any type
+ *            is allowed.
+ *
+ *  returns: If the passed-in ID is not of the proper type, OS_ERROR is returned
+ *           Otherwise OS_SUCCESS is returned.
+ *
+ *-----------------------------------------------------------------*/
+int32 OS_ObjectIdToArrayIndex(uint32 idtype, osal_id_t id, uint32 *ArrayIndex)
+{
+   uint32 max_id;
+   uint32 obj_index;
+   uint32 actual_type;
+   int32 return_code;
+
+   obj_index = OS_ObjectIdToSerialNumber_Impl(id);
+   actual_type = OS_ObjectIdToType_Impl(id);
+
+   /*
+    * If requested by the caller, enforce that the ID is of the correct type.
+    * If the caller passed OS_OBJECT_TYPE_UNDEFINED, then anything is allowed.
+    */
+   if (idtype != OS_OBJECT_TYPE_UNDEFINED && actual_type != idtype)
+   {
+       return_code = OS_ERR_INVALID_ID;
+   }
+   else
+   {
+       max_id = OS_GetMaxForObjectType(actual_type);
+       if (max_id == 0)
+       {
+           return_code = OS_ERR_INVALID_ID;
+       }
+       else
+       {
+           return_code = OS_SUCCESS;
+           *ArrayIndex = obj_index % max_id;
+       }
+   }
+
+   return return_code;
+} /* end OS_ObjectIdToArrayIndex */
+
+