Initial Commit

1 files changed, 448 insertions, 0 deletions

diff --git a/ucs2-lib/src/ucs_pmfifos.c b/ucs2-lib/src/ucs_pmfifos.c
new file mode 100644
index 0000000..347c1b9
--- /dev/null
+++ b/ucs2-lib/src/ucs_pmfifos.c
@@ -0,0 +1,448 @@
+/*------------------------------------------------------------------------------------------------*/
+/* UNICENS V2.1.0-3491                                                                            */
+/* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG.                              */
+/*                                                                                                */
+/* This program is free software: you can redistribute it and/or modify                           */
+/* it under the terms of the GNU General Public License as published by                           */
+/* the Free Software Foundation, either version 2 of the License, or                              */
+/* (at your option) any later version.                                                            */
+/*                                                                                                */
+/* This program is distributed in the hope that it will be useful,                                */
+/* but WITHOUT ANY WARRANTY; without even the implied warranty of                                 */
+/* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                                  */
+/* GNU General Public License for more details.                                                   */
+/*                                                                                                */
+/* You should have received a copy of the GNU General Public License                              */
+/* along with this program.  If not, see <http://www.gnu.org/licenses/>.                          */
+/*                                                                                                */
+/* You may also obtain this software under a propriety license from Microchip.                    */
+/* Please contact Microchip for further information.                                              */
+/*------------------------------------------------------------------------------------------------*/
+
+/*!
+ * \file
+ * \brief Implementation of class CPmFifos
+ *
+ * \cond UCS_INTERNAL_DOC
+ * \addtogroup  G_PMFIFOS
+ * @{
+ */
+
+/*------------------------------------------------------------------------------------------------*/
+/* Includes                                                                                       */
+/*------------------------------------------------------------------------------------------------*/
+#include "ucs_pmfifos.h"
+#include "ucs_misc.h"
+#include "ucs_trace.h"
+
+/*------------------------------------------------------------------------------------------------*/
+/* Internal Constants                                                                             */
+/*------------------------------------------------------------------------------------------------*/
+/*! \brief The initialization value of sync_count. It is incremented for each sync or un-sync attempt. */
+static const uint8_t     FIFOS_SYNC_CNT_INITIAL = 0xFFU;
+
+/*------------------------------------------------------------------------------------------------*/
+/* Internal typedefs                                                                              */
+/*------------------------------------------------------------------------------------------------*/
+
+/*------------------------------------------------------------------------------------------------*/
+/* Internal prototypes                                                                            */
+/*------------------------------------------------------------------------------------------------*/
+static void Fifos_Cleanup(CPmFifos *self);
+static void Fifos_OnSyncTimeout(void *self);
+static void Fifos_OnUnsyncTimeout(void *self);
+static void Fifos_OnFifoEvent(void *self, void *fifo_id_ptr);
+
+static void Fifos_HandleFifoStateChange(CPmFifos *self, Pmp_FifoId_t fifo_id);
+static bool Fifos_AreAllFifosInState(CPmFifos *self, Fifo_SyncState_t target_state);
+
+/*------------------------------------------------------------------------------------------------*/
+/* Implementation                                                                                 */
+/*------------------------------------------------------------------------------------------------*/
+/*! \brief  Constructor of class CPmFifos
+ *  \param  self         The instance
+ *  \param  base_ptr     Reference to basic services
+ *  \param  channel_ptr  Reference to the port message channel
+ *  \param  icm_fifo_ptr Reference to ICM FIFO, or NULL.
+ *  \param  mcm_fifo_ptr Reference to MCM FIFO, or NULL.
+ *  \param  rcm_fifo_ptr Reference to RCM FIFO, or NULL.
+ *  \details At least one FIFO (MCM or ICM) must be provided.
+ */
+void Fifos_Ctor(CPmFifos *self, CBase *base_ptr, CPmChannel *channel_ptr, CPmFifo *icm_fifo_ptr, CPmFifo *mcm_fifo_ptr, CPmFifo *rcm_fifo_ptr)
+{
+    MISC_MEM_SET(self, 0, sizeof(*self));
+
+    self->base_ptr      = base_ptr;
+    self->channel_ptr   = channel_ptr;
+    self->state         = FIFOS_S_UNSYNCED;
+
+    self->unsync_initial = false;
+    Fifos_ConfigureSyncParams(self, FIFOS_SYNC_RETRIES, FIFOS_SYNC_TIMEOUT);
+
+    self->fifos[PMP_FIFO_ID_ICM] = icm_fifo_ptr;
+    self->fifos[PMP_FIFO_ID_RCM] = rcm_fifo_ptr;
+    self->fifos[PMP_FIFO_ID_MCM] = mcm_fifo_ptr;
+
+    T_Ctor(&self->init_timer); 
+    Sub_Ctor(&self->event_subject, self->base_ptr->ucs_user_ptr);
+    Obs_Ctor(&self->obs_icm, self, &Fifos_OnFifoEvent);
+    Obs_Ctor(&self->obs_rcm, self, &Fifos_OnFifoEvent);
+    Obs_Ctor(&self->obs_mcm, self, &Fifos_OnFifoEvent);
+
+    TR_ASSERT(self->base_ptr->ucs_user_ptr, "[FIFOS]", (!((icm_fifo_ptr == NULL) && (mcm_fifo_ptr == NULL))));
+
+    if (icm_fifo_ptr != NULL)
+    {
+        Fifo_AddStateObserver(icm_fifo_ptr, &self->obs_icm);
+    }
+
+    if (rcm_fifo_ptr != NULL)
+    {
+        Fifo_AddStateObserver(rcm_fifo_ptr, &self->obs_rcm);
+    }
+
+    if (mcm_fifo_ptr != NULL)
+    {
+        Fifo_AddStateObserver(mcm_fifo_ptr, &self->obs_mcm);
+    }
+
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_Ctor(): FIFOS created, state %d", 1U, self->state));
+}
+
+/*! \brief          Adds an observer of synchronization events
+ *  \param self     The instance
+ *  \param obs_ptr  The observer. The notification result type is Fifos_Event_t.
+ */
+void Fifos_AddEventObserver(CPmFifos *self, CObserver *obs_ptr)
+{
+    TR_ASSERT(self->base_ptr->ucs_user_ptr, "[FIFOS]", (obs_ptr != 0));
+    (void)Sub_AddObserver(&self->event_subject, obs_ptr);
+}
+
+/*! \brief          Removes an observer of synchronization events
+ *  \param self     The instance
+ *  \param obs_ptr  The observer.
+ */
+void Fifos_RemoveEventObserver(CPmFifos *self, CObserver *obs_ptr)
+{
+    TR_ASSERT(self->base_ptr->ucs_user_ptr, "[FIFOS]", (obs_ptr != 0));
+    (void)Sub_RemoveObserver(&self->event_subject, obs_ptr);
+}
+
+/*! \brief          Forces all FIFOs to state UNSYNCED without waiting for INIC responses and
+ *                  without throwing events
+ *  \details        Stops the LLD interface and releases all pending message resources.
+ *                  This function shall be called if the UCS requires a un-normal termination
+ *                  which is not detected by port message protocol.
+ *  \param self     The instance
+ */
+void Fifos_ForceTermination(CPmFifos *self)
+{
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_ForceTermination(): Termination started, state: %d", 1U, self->state));
+    Fifos_Cleanup(self);
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_ForceTermination(): Termination done, state: %d", 1U, self->state));
+}
+
+/*! \brief          Configures retries and timeout for synchronize or un-synchronize
+ *                  operation
+ *  \details        This method shall be called before starting a synchronization or un-synchronization
+ *                  or after it has finished. The current counter of synchronization attempts is reset.
+ *  \param self     The instance
+ *  \param retries  The number of retries until event FIFOS_EV_SYNC_FAILED or 
+ *                  FIFOS_EV_UNSYNC_FAILED will be notified
+ *  \param timeout  The timeout in milliseconds when the retry is performed
+ */
+void Fifos_ConfigureSyncParams(CPmFifos *self, uint8_t retries, uint16_t timeout)
+{
+    self->cmd_retries = retries;
+    self->cmd_timeout = timeout;
+    self->sync_cnt = FIFOS_SYNC_CNT_INITIAL;
+}
+
+/*------------------------------------------------------------------------------------------------*/
+/* Synchronization                                                                                */
+/*------------------------------------------------------------------------------------------------*/
+/*! \brief    Initializes all port message FIFOs
+ *  \details  Possible results of the operation are the following events which are fired
+ *            asynchronously. Refer also Fifos_AddEventObserver() and \ref Fifos_Event_t.
+ *            - \ref FIFOS_EV_SYNC_ESTABLISHED
+ *            - \ref FIFOS_EV_SYNC_FAILED
+ *  \param    self        The instance
+ *  \param    reset_cnt   If \c true resets the synchronization counter. In this case an automatic
+ *                        retries will be done after the first synchronization timeout.
+ *  \param    force_sync  If \c true the method will also trigger the synchronization of already 
+ *                        synced \ref CPmFifo objects.
+ */
+void Fifos_Synchronize(CPmFifos *self, bool reset_cnt, bool force_sync)
+{
+    uint8_t cnt;
+    self->state = FIFOS_S_SYNCING;
+    self->unsync_initial = false;
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_Synchronize(): Synchronization started, state: %d", 1U, self->state));
+
+    if (reset_cnt)
+    {
+        self->sync_cnt = FIFOS_SYNC_CNT_INITIAL;
+    }
+
+    self->sync_cnt++;
+    Pmch_Initialize(self->channel_ptr);                     /* Start LLD if not already done */
+
+    for (cnt = 0U; cnt < PMP_MAX_NUM_FIFOS; cnt++)
+    {
+        if (self->fifos[cnt] != NULL)
+        {
+            if (force_sync || (Fifo_GetState(self->fifos[cnt]) != FIFO_S_SYNCED))
+            {
+                Fifo_Synchronize(self->fifos[cnt]);
+            }
+        }
+    }
+
+    Tm_SetTimer(&self->base_ptr->tm, &self->init_timer, 
+                &Fifos_OnSyncTimeout, self, 
+                self->cmd_timeout, 0U);
+}
+
+/*! \brief      Un-initializes all port message FIFOs
+ *  \details    Possible results of the operation are the following events which are fired
+ *              asynchronously. Refer also Fifos_AddEventObserver() and \ref Fifos_Event_t.
+ *              - \ref FIFOS_EV_UNSYNC_COMPLETE
+ *              - \ref FIFOS_EV_UNSYNC_FAILED
+ *  \param      self       The instance
+ *  \param      reset_cnt  If \c true resets the synchronization counter. In this case an automatic
+ *                         retries will be done after the first synchronization timeout.
+ *  \param      initial    If the un-synchronization shall be executed prior to a initial synchronization
+ *                         it is recommended to set the argument to \c true. After notifying the event 
+ *                         FIFOS_EV_UNSYNC_COMPLETE the LLD interface will not be stopped. The subsequent 
+ *                         call of Fifos_Synchronize() will not start the LLD interface un-necessarily.
+ *                         To trigger a final un-synchronization \c initial shall be set to \c false.
+ *                         I.e., FIFOS_EV_UNSYNC_COMPLETE stops the LLD interface.
+ */
+void Fifos_Unsynchronize(CPmFifos *self, bool reset_cnt, bool initial)
+{
+    uint8_t cnt;
+    self->state = FIFOS_S_UNSYNCING;
+    self->unsync_initial = initial;
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_Unsynchronize(): Un-synchronization started, state: %d", 1U, self->state));
+
+    if (reset_cnt)
+    {
+        self->sync_cnt = FIFOS_SYNC_CNT_INITIAL;
+    }
+
+    self->sync_cnt++;
+    Pmch_Initialize(self->channel_ptr);                     /* Start LLD if not already done */
+
+    for (cnt = 0U; cnt < PMP_MAX_NUM_FIFOS; cnt++)
+    {
+        if (self->fifos[cnt] != NULL)
+        {
+            if (initial || (Fifo_GetState(self->fifos[cnt]) != FIFO_S_UNSYNCED_READY))
+            {
+                Fifo_Unsynchronize(self->fifos[cnt]);
+            }
+        }
+    }
+
+    Tm_SetTimer(&self->base_ptr->tm, &self->init_timer, 
+                &Fifos_OnUnsyncTimeout, self, 
+                self->cmd_timeout, 0U);
+}
+
+/*! \brief  Handles the synchronization timeout
+ *  \param  self    The instance
+ */
+static void Fifos_OnSyncTimeout(void *self)
+{
+    CPmFifos *self_ = (CPmFifos*)self;
+    Fifos_Event_t the_event = FIFOS_EV_SYNC_FAILED;
+
+    self_->state = FIFOS_S_UNSYNCED;
+
+    TR_INFO((self_->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_OnSyncTimeout(): state: %d", 1U, self_->state));
+
+    if (self_->sync_cnt < self_->cmd_retries)
+    {
+        Fifos_Synchronize(self_, false, false);             /* retry synchronization after first timeout */
+    }
+    else
+    {
+        Fifos_Cleanup(self_);
+        Sub_Notify(&self_->event_subject, &the_event);
+    }
+}
+
+/*! \brief  Handles the un-synchronization timeout
+ *  \param  self    The instance
+ */
+static void Fifos_OnUnsyncTimeout(void *self)
+{
+    CPmFifos *self_ = (CPmFifos*)self;
+    Fifos_Event_t the_event = FIFOS_EV_UNSYNC_FAILED;
+
+    self_->state = FIFOS_S_UNSYNCED;
+    TR_INFO((self_->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_OnUnsyncTimeout(): state: %d", 1U, self_->state));
+
+    if (self_->sync_cnt < self_->cmd_retries)
+    {
+        Fifos_Unsynchronize(self_, false, self_->unsync_initial);   /* retry synchronization after first timeout */
+    }
+    else
+    {
+        self_->unsync_initial = false;                              /* un-sync timeout will lead to termination - stop LLD */
+        Fifos_Cleanup(self_);
+        Sub_Notify(&self_->event_subject, &the_event);
+    }
+}
+
+/*! \brief      Performs a cleanup of the Port Message Channel and the dedicated FIFOs
+ *  \details    Releases all message objects which are currently in use.
+ *  \param      self            The instance
+ */
+static void Fifos_Cleanup(CPmFifos *self)
+{
+    uint8_t count;
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_Cleanup(): Channel cleanup started", 0U));
+
+    if (self->unsync_initial == false)
+    {
+        Pmch_Uninitialize(self->channel_ptr);
+    }
+
+    for (count = 0U; count < PMP_MAX_NUM_FIFOS; count++)    /* stop & cleanup all FIFOs */
+    {
+        if (self->fifos[count] != NULL)
+        {                                                   /* stop and avoid recursion */
+            Fifo_Stop(self->fifos[count], FIFO_S_UNSYNCED_INIT, false);
+            Fifo_Cleanup(self->fifos[count]);
+        }
+    }
+
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_Cleanup(): Channel cleanup completed", 0U));
+
+    /* notify external event after message objects were released */
+    self->state = FIFOS_S_UNSYNCED;
+}
+
+/*------------------------------------------------------------------------------------------------*/
+/* FIFO observation                                                                               */
+/*------------------------------------------------------------------------------------------------*/
+
+/*! \brief  Notifies an event to the host class
+ *  \param  self        The instance
+ *  \param  fifo_id_ptr Specific event identifier, pointer to "fifo_id"
+ */
+static void Fifos_OnFifoEvent(void *self, void *fifo_id_ptr)
+{
+    CPmFifos *self_ = (CPmFifos*)self;
+    Fifos_HandleFifoStateChange(self_, *((Pmp_FifoId_t*)fifo_id_ptr));
+}
+
+/*! \brief  Executes transition to new synchronization states
+ *  \param  self        The instance
+ *  \param  fifo_id     The FIFO identifier
+ */
+static void Fifos_HandleFifoStateChange(CPmFifos *self, Pmp_FifoId_t fifo_id)
+{
+    Fifos_Event_t the_event;
+
+    TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_HandleFifoStateChange(): FIFOs state: %d, FIFO: %d, FIFO State: %d", 3U, 
+             self->state, fifo_id, Fifo_GetState(self->fifos[fifo_id])));
+
+    switch (self->state)
+    {
+        case FIFOS_S_SYNCING:
+            if (Fifos_AreAllFifosInState(self, FIFO_S_SYNCED))
+            {
+                self->state = FIFOS_S_SYNCED;                           /* now the complete channel is synced */
+                Tm_ClearTimer(&self->base_ptr->tm, &self->init_timer);
+                Fifos_ConfigureSyncParams(self, FIFOS_UNSYNC_RETRIES, FIFOS_UNSYNC_TIMEOUT);
+                the_event = FIFOS_EV_SYNC_ESTABLISHED;
+                Sub_Notify(&self->event_subject, &the_event);
+                TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_HandleFifoStateChange(): Synchronization of Port Message channel completed", 0U));
+            }
+            break;
+
+        case FIFOS_S_UNSYNCING:
+            if (Fifos_AreAllFifosInState(self, FIFO_S_UNSYNCED_READY))
+            {
+                Fifos_Cleanup(self);
+                self->state = FIFOS_S_UNSYNCED;                         /* now the complete channel is un-synced */
+                Tm_ClearTimer(&self->base_ptr->tm, &self->init_timer);
+                the_event = FIFOS_EV_UNSYNC_COMPLETE;
+                Sub_Notify(&self->event_subject, &the_event);
+                TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_HandleFifoStateChange(): Un-synchronization of Port Message channel completed", 0U));
+            }
+            break;
+
+        case FIFOS_S_SYNCED:
+            if (!Fifos_AreAllFifosInState(self, FIFO_S_SYNCED))
+            {
+                self->state = FIFOS_S_UNSYNCING;                        /* set state to 'unsyncing' and wait until all FIFOs are unsynced */
+                self->sync_cnt = 0U;                                    /* pretend having triggered an un-sync which starts the timer */
+                Tm_SetTimer(&self->base_ptr->tm, &self->init_timer, 
+                            &Fifos_OnUnsyncTimeout, self, 
+                            FIFOS_UNSYNC_TIMEOUT, 0U);
+                the_event = FIFOS_EV_SYNC_LOST;
+                Sub_Notify(&self->event_subject, &the_event);
+                TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_HandleFifoStateChange(): Lost synchronization of Port Message channel", 0U));
+            }
+            if (Fifos_AreAllFifosInState(self, FIFO_S_UNSYNCED_READY))
+            {
+                Fifos_Cleanup(self);
+                self->state = FIFOS_S_UNSYNCED;                         /* the complete channel suddenly goes unsynced_complete */
+                Tm_ClearTimer(&self->base_ptr->tm, &self->init_timer);
+                the_event = FIFOS_EV_UNSYNC_COMPLETE;
+                Sub_Notify(&self->event_subject, &the_event);
+                TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_HandleFifoStateChange(): Sudden un-synchronization of Port Message channel completed", 0U));
+            }
+            break;
+
+        case FIFOS_S_UNSYNCED:
+            TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_HandleFifoStateChange(): Unexpected FIFO event in state unsynced", 0U));
+            break;
+
+        default:
+            TR_INFO((self->base_ptr->ucs_user_ptr, "[FIFOS]", "Fifos_HandleFifoStateChange(): Unexpected FIFOs state", 0U));
+            break;
+    }
+
+    MISC_UNUSED(fifo_id);
+}
+
+/*! \brief  Helper function that evaluates if all configured FIFOs are in a given state 
+ *  \param  self            The instance
+ *  \param  target_state    The required state that is evaluated for all FIFOs
+ *  \return \c true if all FIFOs are in the given \c target_state, otherwise \c false.
+ */
+static bool Fifos_AreAllFifosInState(CPmFifos *self, Fifo_SyncState_t target_state)
+{
+    bool ret = true;
+    uint8_t cnt;
+
+    for (cnt = 0U; cnt < PMP_MAX_NUM_FIFOS; cnt++)
+    {
+        if (self->fifos[cnt] != NULL)
+        {
+            Fifo_SyncState_t state = Fifo_GetState(self->fifos[cnt]);
+
+            if (state != target_state)
+            {
+                ret = false;
+            }
+        }
+    }
+
+    return ret;
+}
+
+/*!
+ * @}
+ * \endcond
+ */
+
+/*------------------------------------------------------------------------------------------------*/
+/* End of file                                                                                    */
+/*------------------------------------------------------------------------------------------------*/
+