Integration Candidate: 2020-10-07

README.md

@@ -10,23 +10,30 @@ The autogenerated OSAL user's guide can be viewed at <https://github.com/nasa/cF
 
 ## Version History
 
+### Development Build: 5.1.0-rc1+dev49
+
+- Adds an event callback mechanism to certain state changes in OSAL. This allows the CFE PSP to be notified at these points, and therefore it can add platform-specific functionality.
+- Correct issues involving recent OS_Milli2Ticks change.
+- See <https://github.com/nasa/osal/pull/612>
+
 ### Development Build: 5.1.0-rc1+dev44
+
 - Removes OS_Tick2Micros and internalize OS_Milli2Ticks.
 - Adds ut_assert address equal macro.
 - See <https://github.com/nasa/osal/pull/607>
 
 ### Development Build: 5.1.0-rc1+dev38
+
 - Sets Revision to 99 for development builds
 - See <https://github.com/nasa/osal/pull/600>
 
-
 ### Development Build: 5.1.0-rc1+dev34
 
-- Move this existing function into the public API, as it is performs more verification than the OS_ConvertToArrayIndex
-function.
+- Move this existing function into the public API, as it is performs more verification than the OS_ConvertToArrayIndex function.
 - The C library type is signed, and this makes the result check work as intended.
 - See <https://github.com/nasa/osal/pull/596>
 
+
 ### Development Build: 5.1.0-rc1+dev16
 
  - In the next major OSAL release, this code will be no longer supported at all. It should be removed early in the cycle to avoid needing to maintain this compatibility code. This code was already conditional on the OSAL_OMIT_DEPRECATED flag and as such the CCB has already tested/verified running the code in this configuration as part of CI scripts. After this change, the build should be equivalent to the result of building with OMIT_DEPRECATED=true.

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

@@ -176,6 +176,75 @@ typedef enum
     OS_STREAM_STATE_WRITABLE   = 0x08, /**< @brief whether the stream is writable  */
 } OS_StreamState_t;
 
+/**
+ * @brief A set of events that can be used with event callback routines
+ */
+typedef enum
+{
+    OS_EVENT_RESERVED = 0,          /**< no-op/reserved event id value */
+
+    /**
+     * resource/id has been newly allocated but not yet created.
+     *
+     * This event is invoked from WITHIN the locked region, in
+     * the context of the task which is allocating the resource.
+     *
+     * If the handler returns non-success, the error will be returned
+     * to the caller and the creation process is aborted.
+     */
+    OS_EVENT_RESOURCE_ALLOCATED,
+
+    /**
+     * resource/id has been fully created/finalized.
+     *
+     * Invoked outside locked region, in the context
+     * of the task which created the resource.
+     *
+     * Data object is not used, passed as NULL.
+     *
+     * Return value is ignored - this is for information purposes only.
+     */
+    OS_EVENT_RESOURCE_CREATED,
+
+    /**
+     * resource/id has been deleted.
+     *
+     * Invoked outside locked region, in the context
+     * of the task which deleted the resource.
+     *
+     * Data object is not used, passed as NULL.
+     *
+     * Return value is ignored - this is for information purposes only.
+     */
+    OS_EVENT_RESOURCE_DELETED,
+
+    /**
+     * New task is starting.
+     *
+     * Invoked outside locked region, in the context
+     * of the task which is currently starting, before
+     * the entry point is called.
+     *
+     * Data object is not used, passed as NULL.
+     *
+     * If the handler returns non-success, task startup is aborted
+     * and the entry point is not called.
+     */
+    OS_EVENT_TASK_STARTUP,
+
+    OS_EVENT_MAX                    /**< placeholder for end of enum, not used */
+} OS_Event_t;
+
+/**
+ * @brief A callback routine for event handling.
+ *
+ * @param[in]    event      The event that occurred
+ * @param[in]    object_id  The associated object_id, or 0 if not associated with an object
+ * @param[inout] data       An abstract data/context object associated with the event, or NULL.
+ * @return status Execution status, see @ref OSReturnCodes.
+ */
+typedef int32 (*OS_EventHandler_t)(OS_Event_t event, osal_id_t object_id, void *data);
+
 /**
  * @brief For the @ref OS_GetErrorName() function, to ensure
  * everyone is making an array of the same length.
@@ -504,6 +573,25 @@ void OS_ForEachObject           (osal_id_t creator_id, OS_ArgCallback_t callback
  * @param[in]  callback_arg Opaque Argument to pass to callback function
   */
 void OS_ForEachObjectOfType     (uint32 objtype, osal_id_t creator_id, OS_ArgCallback_t callback_ptr, void *callback_arg);
+
+/*-------------------------------------------------------------------------------------*/
+/**
+ * @brief Callback routine registration
+ *
+ * This hook enables the application code to perform extra platform-specific
+ * operations on various system events such as resource creation/deletion.
+ *
+ * @note Some events are invoked while the resource is "locked" and therefore
+ * application-defined handlers for these events should not block or attempt
+ * to access other OSAL resources.
+ *
+ * @param[in] handler The application-provided event handler
+ * @return Execution status, see @ref OSReturnCodes.
+ * @retval #OS_SUCCESS @copybrief OS_SUCCESS
+ * @retval #OS_ERROR   @copybrief OS_ERROR
+ */
+int32 OS_RegisterEventHandler (OS_EventHandler_t handler);
+
 /**@}*/
 
 

src/os/inc/osapi-version.h

@@ -30,7 +30,7 @@
 /*
  * Development Build Macro Definitions
  */
-#define OS_BUILD_NUMBER 44 
+#define OS_BUILD_NUMBER 49 
 #define OS_BUILD_BASELINE "v5.1.0-rc1"
 
 /*

src/os/rtems/src/os-impl-binsem.c

@@ -39,6 +39,7 @@
 #include "os-impl-binsem.h"
 #include "os-shared-binsem.h"
 #include "os-shared-idmap.h"
+#include "os-shared-timebase.h"
 
 
 /****************************************************************************************
@@ -246,7 +247,7 @@ int32 OS_BinSemTimedWait_Impl (uint32 sem_id, uint32 msecs)
     rtems_status_code status;
     int               TimeInTicks;
 
-    if (OS_Milli2Ticks(msecs, &TimInTicks) != OS_SUCCESS)
+    if (OS_Milli2Ticks(msecs, &TimeInTicks) != OS_SUCCESS)
     {
         return OS_ERROR;
     }

src/os/rtems/src/os-impl-countsem.c

@@ -40,6 +40,7 @@
 
 #include "os-shared-countsem.h"
 #include "os-shared-idmap.h"
+#include "os-shared-timebase.h"
 
 /****************************************************************************************
                                      DEFINES
@@ -207,9 +208,12 @@ int32 OS_CountSemTake_Impl (uint32 sem_id)
 int32 OS_CountSemTimedWait_Impl (uint32 sem_id, uint32 msecs)
 {
     rtems_status_code status;
-    uint32            TimeInTicks;
+    int               TimeInTicks;
 
-    TimeInTicks = OS_Milli2Ticks(msecs);
+    if (OS_Milli2Ticks(msecs, &TimeInTicks) != OS_SUCCESS)
+    {
+        return OS_ERROR;
+    }
 
     status = rtems_semaphore_obtain(OS_impl_count_sem_table[sem_id].id, RTEMS_WAIT, TimeInTicks);
     if (status == RTEMS_TIMEOUT)

src/os/rtems/src/os-impl-queues.c

@@ -40,6 +40,8 @@
 
 #include "os-shared-queue.h"
 #include "os-shared-idmap.h"
+#include "os-shared-timebase.h"
+
 
 /****************************************************************************************
                                      DEFINES
@@ -162,6 +164,7 @@ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_c
     int32              return_code;
     rtems_status_code  status;
     rtems_interval     ticks;
+    int                tick_count;
     rtems_option       option_set;
     size_t             rtems_size;
     rtems_id           rtems_queue_id;
@@ -182,8 +185,14 @@ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_c
     else
     {
         option_set = RTEMS_WAIT;
+
         /* msecs rounded to the closest system tick count */
-        ticks = OS_Milli2Ticks(timeout);
+        if (OS_Milli2Ticks(timeout, &tick_count) != OS_SUCCESS)
+        {
+            return OS_ERROR;
+        }
+
+        ticks = (rtems_interval)tick_count;
     }
 
     /*

src/os/rtems/src/os-impl-tasks.c

@@ -40,6 +40,7 @@
 
 #include "os-shared-task.h"
 #include "os-shared-idmap.h"
+#include "os-shared-timebase.h"
 
 /****************************************************************************************
                                      DEFINES
@@ -199,15 +200,28 @@ void OS_TaskExit_Impl()
  *-----------------------------------------------------------------*/
 int32 OS_TaskDelay_Impl (uint32 milli_second)
 {
-    rtems_interval     ticks;
+    int     tick_count;
+    int32   return_code;
 
-    ticks = OS_Milli2Ticks(milli_second);
+    return_code = OS_Milli2Ticks(milli_second, &tick_count);
+
+    if (return_code != OS_SUCCESS)
+    {
+        /*
+         * always want to do some form of delay, because if
+         * this function becomes a no-op then this might create a
+         * tight loop that doesn't ever yield the CPU - effectively
+         * locking the system in an RTOS environment.
+         */
+        tick_count = 10;
+    }
 
-    rtems_task_wake_after(ticks);
     /*
     ** Always successful ( from RTEMS docs )
     */
-    return (OS_SUCCESS);
+    rtems_task_wake_after((rtems_interval)tick_count);
+
+    return (return_code);
 
 } /* end OS_TaskDelay_Impl */
 

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

@@ -57,6 +57,12 @@ struct OS_shared_global_vars
    int32             MicroSecPerTick;
    int32             TicksPerSecond;
 
+   /*
+    * The event handler is an application-defined callback
+    * that gets invoked as resources are created/configured/deleted.
+    */
+   OS_EventHandler_t EventHandler;
+
 #ifdef OSAL_CONFIG_DEBUG_PRINTF
    uint8             DebugLevel;
 #endif
@@ -69,6 +75,16 @@ struct OS_shared_global_vars
  */
 extern OS_SharedGlobalVars_t OS_SharedGlobalVars;
 
+/*---------------------------------------------------------------------------------------
+   Name: OS_NotifyEvent
+
+   Purpose: Notify the user application of a change in the state of an OSAL resource
+
+   returns: OS_SUCCESS on success, or relevant error code
+---------------------------------------------------------------------------------------*/
+int32 OS_NotifyEvent(OS_Event_t event, osal_id_t object_id, void *data);
+
+
 /*---------------------------------------------------------------------------------------
    Name: OS_API_Impl_Init
 

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

@@ -65,11 +65,36 @@ OS_SharedGlobalVars_t OS_SharedGlobalVars =
             .ShutdownFlag = 0,
             .MicroSecPerTick = 0, /* invalid, _must_ be set by implementation init */
             .TicksPerSecond = 0,  /* invalid, _must_ be set by implementation init */
+            .EventHandler = NULL,
 #if defined(OSAL_CONFIG_DEBUG_PRINTF)
             .DebugLevel = 1,
 #endif
       };
 
+
+/*----------------------------------------------------------------
+ *
+ * Function: OS_NotifyEvent
+ *
+ *  Purpose: Helper function to invoke the user-defined event handler
+ *
+ *-----------------------------------------------------------------*/
+int32 OS_NotifyEvent(OS_Event_t event, osal_id_t object_id, void *data)
+{
+    int32 status;
+
+    if (OS_SharedGlobalVars.EventHandler != NULL)
+    {
+        status = OS_SharedGlobalVars.EventHandler(event, object_id, data);
+    }
+    else
+    {
+        status = OS_SUCCESS;
+    }
+
+    return status;
+}
+
 /*
  *********************************************************************************
  *          PUBLIC API (application-callable functions)
@@ -199,6 +224,24 @@ int32 OS_API_Init(void)
    return(return_code);
 } /* end OS_API_Init */
 
+/*----------------------------------------------------------------
+ *
+ * Function: OS_RegisterEventHandler
+ *
+ *  Purpose: Implemented per public OSAL API
+ *           See description in API and header file for detail
+ *
+ *-----------------------------------------------------------------*/
+int32 OS_RegisterEventHandler (OS_EventHandler_t handler)
+{
+    if (handler == NULL)
+    {
+        return OS_INVALID_POINTER;
+    }
+
+    OS_SharedGlobalVars.EventHandler = handler;
+    return OS_SUCCESS;
+}
 
 /*----------------------------------------------------------------
  *