AMiRo-OS

/*

AMiRo-OS is an operating system designed for the Autonomous Mini Robot (AMiRo) platform.

Copyright (C) 2016..2019  Thomas Schöpping et al.

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 3 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/>.

*/

/**

 * @file    aos_sssp.c

 * @brief   SSSP related code.

 *

 * @addtogroup aos_sssp

 * @{

 */

#include <amiroos.h>

#if (AMIROOS_CFG_SSSP_ENABLE == true) || defined(__DOXYGEN__)

/******************************************************************************/

/* LOCAL DEFINITIONS                                                          */

/******************************************************************************/

/******************************************************************************/

/* EXPORTED VARIABLES                                                         */

/******************************************************************************/

/******************************************************************************/

/* LOCAL TYPES                                                                */

/******************************************************************************/

/******************************************************************************/

/* LOCAL VARIABLES                                                            */

/******************************************************************************/

/**

 * @brief   A timer event based delays.

 */

static virtual_timer_t _delayTimer;

/**

 * @brief   Event source for the delay timer.

 */

static event_source_t _eventSourceDelay;

/**

 * @brief   Event listener for the delay event.

 */

static event_listener_t _eventListenerDelay;

/******************************************************************************/

/* LOCAL FUNCTIONS                                                            */

/******************************************************************************/

/**

 * @brief   General callback function to be used for any local timers.

 *

 * @param[in] par   A pointer to an @p event_source_t to be fired.

 */

static void _timerCallback(void* par)

{

  aosDbgCheck(par != NULL);

  chSysLockFromISR();

  chEvtBroadcastI((event_source_t*)par);

  chSysUnlockFromISR();

  return;

}

/**

 * @brief   Waits for the S signal to switch to the desired state.

 *

 * @param[in]   listener      Pointer to the GPIO event listener to be used.

 * @param[in]   flags         Event flags to listen to by the event listener (indicating a S signal event).

 * @param[in]   signalstate   Desired state of the S signal ti be waited for.

 * @param[out]  received      Output variable to store the received event mask to.

 *

 * @return  Status, indicating whether the expected event was received.

 */

static inline aos_status_t _waitForS(event_listener_t* listener, eventflags_t flags, apalControlGpioState_t signalstate, eventmask_t* received)

{

  aosDbgCheck(listener != NULL);

  aosDbgCheck(flags != 0);

  aosDbgCheck(received != NULL);

  // wait for the next event (do not apply any filters in order not to miss any events)

  *received = chEvtWaitOne(ALL_EVENTS);

  // if the correct event was triggered

  if (*received == listener->events) {

    apalControlGpioState_t s;

    apalControlGpioGet(&moduleSsspGpioS, &s);

    // only check for the expected event

    if (flags & listener->flags && s == signalstate) {

      // unset the expected flags but keep any other ones

      listener->flags &= ~flags;

      return AOS_SUCCESS;

    }

  }

  return AOS_FAILURE;

}

/**

 * @brief   Uses the local delay timer to setup a timed event and waits for it to fire.

 *

 * @param[in]   dt          Delay time in microseconds to be set to the timer.

 * @param[in]   mask        Event mask to be used for the delay timer.

 * @param[in]   arm_timer   Flag to indicate whether the timer has to be armed yet (i.e. on first call of this function).

 * @param[out]  received    Output variable to store the received event mask to.

 *

 * @return  Status, indicating whether the expected event (delay timer) was received.

 */

static inline aos_status_t _delay(uint32_t dt, eventmask_t mask, bool arm_timer, eventmask_t* received)

{

  aosDbgCheck(dt != TIME_IMMEDIATE);

  aosDbgCheck(mask != 0);

  aosDbgCheck(received != NULL);

  // arm the delay timer once

  if (arm_timer) {

    chEvtRegisterMask(&_eventSourceDelay, &_eventListenerDelay, mask);

    chVTSet(&_delayTimer, chTimeUS2I(dt), _timerCallback, &_eventSourceDelay);

  }

  // wait for any event to occur (do not apply any filters in order not to miss any events)

  *received = chEvtWaitOne(ALL_EVENTS);

  // if the timer event was received, cleanup

  if (*received & _eventListenerDelay.events) {

    chEvtUnregister(&_eventSourceDelay, &_eventListenerDelay);

    return AOS_SUCCESS;

  }

  return AOS_FAILURE;

}

/******************************************************************************/

/* EXPORTED FUNCTIONS                                                         */

/******************************************************************************/

/**

 * @brief   Initialize all SSSP related data.

 */

void aosSsspInit(void)

{

  // local variables

  apalControlGpioState_t state;

#if (AMIROOS_CFG_SSSP_STARTUP == true)

  // AMiRo-OS has to perform the basic initialization

  aos.sssp.stage = AOS_SSSP_STAGE_STARTUP_1_1;

#else /* (AMIROOS_CFG_SSSP_STARTUP == true) */

  // basic initialization was already performed by a bootloader

  aos.sssp.stage = AOS_SSSP_STAGE_STARTUP_2_1;

#endif /* (AMIROOS_CFG_SSSP_STARTUP == true) */

  // check all SSSP signals for correct state

  apalControlGpioGet(&moduleSsspGpioS, &state);

  aosDbgAssert(state == APAL_GPIO_ON);

  apalControlGpioGet(&moduleSsspGpioPD, &state);

  aosDbgAssert(state == APAL_GPIO_OFF);

#if (AMIROOS_CFG_SSSP_STACK_END != true)

  apalControlGpioGet(&moduleSsspGpioUP, &state);

  aosDbgAssert(state == APAL_GPIO_OFF);

#endif /* (AMIROOS_CFG_SSSP_STACK_END != true) */

#if (AMIROOS_CFG_SSSP_STACK_START != true)

  apalControlGpioGet(&moduleSsspGpioDN, &state);

  aosDbgAssert(state == APAL_GPIO_OFF);

#endif /* (AMIROOS_CFG_SSSP_STACK_START != true) */

#if (AMIROOS_CFG_SSSP_MSI == true)

  // module ID is initialized as 'invalid'

  aos.sssp.moduleId = AOS_SSSP_MODULEID_INVALID;

#endif /* (AMIROOS_CFG_SSSP_MSI == true) */

  // initialize static variables

  chVTObjectInit(&_delayTimer);

  chEvtObjectInit(&_eventSourceDelay);

  return;

}

/**

 * @brief   Proceed to the next SSSP stage.

 *

 * @param[in]   listener  An optional listener, in case the system has to wait for a specific event.

 * @param[in]   flags     The relevant flags to wait for (mandatory if a listener is given).

 * @param[in]   mask      If the stage transition involves a timer event (handled internally by this function),

 *                        the given input value of this parameter defines the mask to be used for that event.

 *                        In case a listener was specified, the according mask is retrieved from the listener but this parameter is still used as input for sanity checks.

 * @param[out]  received  Output variable to store the received event mask to.

 *

 * @return  Status, indicating whether proceeding in the protocol was successful.

 */

aos_status_t aosSsspProceed(event_listener_t* listener, eventflags_t flags, eventmask_t mask, eventmask_t* received)

{

  // local variables

#pragma GCC diagnostic push

#pragma GCC diagnostic ignored "-Wunused-but-set-variable"

  static aos_ssspstage_t laststage = AOS_SSSP_STAGE_UNDEFINED;

#pragma GCC diagnostic pop

  aos_ssspstage_t nextstage = aos.sssp.stage;

  // behaviour depends on current SSSP stage of the system

  switch (aos.sssp.stage) {

#if (AMIROOS_CFG_SSSP_STARTUP == true)

    /*

     * Deactivate S signal.

     * Master node delays execution by one period AOS_SSSP_DELAY.

     */

    case AOS_SSSP_STAGE_STARTUP_1_1:

    {

#if (AMIROOS_CFG_SSSP_MASTER == true)

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask != 0);

      aosDbgCheck(received != NULL);

      // delay execution and deactivate the S signal on success

      if (_delay(AOS_SSSP_DELAY, mask, (laststage != AOS_SSSP_STAGE_STARTUP_1_1), received) == AOS_SUCCESS) {

        apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_OFF);

        nextstage = AOS_SSSP_STAGE_STARTUP_1_2;

      }

#else /* (AMIROOS_CFG_SSSP_MASTER == true) */

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask == 0);

      aosDbgCheck(received == NULL);

      // deactivate S signal and proceed

      apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_OFF);

      nextstage = AOS_SSSP_STAGE_STARTUP_1_2;

#endif /* (AMIROOS_CFG_SSSP_MASTER == true) */

      break;

    }

    /*

     * Wait for the S signal to become inactive.

     */

    case AOS_SSSP_STAGE_STARTUP_1_2:

    {

      aosDbgCheck(listener != NULL);

      aosDbgCheck(flags != 0);

      aosDbgCheck(mask == listener->events);

      aosDbgCheck(received != NULL);

      // wait for the S signal to become inactive and proceed on success

      if (_waitForS(listener, flags, APAL_GPIO_OFF, received) == AOS_SUCCESS) {

        nextstage = AOS_SSSP_STAGE_STARTUP_1_3;

      }

      break;

    }

    /*

     * Wait for the S signal to be activated by the master module.

     * The master delays execution by one period AOS_SSSP_DELAY.

     */

    case AOS_SSSP_STAGE_STARTUP_1_3:

    {

#if (AMIROOS_CFG_SSSP_MASTER == true)

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask != 0);

      aosDbgCheck(received != NULL);

      // delay execution and deactivate the S signal on success

      if (_delay(AOS_SSSP_DELAY, mask, (laststage != AOS_SSSP_STAGE_STARTUP_1_3), received) == AOS_SUCCESS) {

        apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_ON);

        nextstage = AOS_SSSP_STAGE_STARTUP_2_1;

      }

#else /* (AMIROOS_CFG_SSSP_MASTER == true) */

      aosDbgCheck(listener != NULL);

      aosDbgCheck(flags != 0);

      aosDbgCheck(mask == listener->events);

      aosDbgCheck(received != NULL);

      // wait for the S signal to become active and activate it as well and proceed on success

      if (_waitForS(listener, flags, APAL_GPIO_ON, received) == AOS_SUCCESS) {

        apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_ON);

        nextstage = AOS_SSSP_STAGE_STARTUP_2_1;

      }

#endif /* (AMIROOS_CFG_SSSP_MASTER == true) */

      break;

    }

#endif /* (AMIROOS_CFG_SSSP_STARTUP == true) */

    /*

     * Deactivate S signal.

     * Master node delays execution by one period AOS_SSSP_DELAY

     */

    case AOS_SSSP_STAGE_STARTUP_2_1:

    {

#if (AMIROOS_CFG_SSSP_MASTER == true)

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask != 0);

      aosDbgCheck(received != NULL);

      // delay execution and deactivate the S signal on success

      if (_delay(AOS_SSSP_DELAY, mask, (laststage != AOS_SSSP_STAGE_STARTUP_2_1), received) == AOS_SUCCESS) {

        apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_OFF);

        nextstage = AOS_SSSP_STAGE_STARTUP_2_2;

      }

#else /* (AMIROOS_CFG_SSSP_MASTER == true) */

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask == 0);

      aosDbgCheck(received == NULL);

      // deactivate S signal and proceed

      apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_OFF);

      nextstage = AOS_SSSP_STAGE_STARTUP_2_2;

      mask = 0;

#endif /* (AMIROOS_CFG_SSSP_MASTER == true) */

      break;

    }

    /*

     * Wait for the S signal to become inactive.

     */

    case AOS_SSSP_STAGE_STARTUP_2_2:

    {

      aosDbgCheck(listener != NULL);

      aosDbgCheck(flags != 0);

      aosDbgCheck(mask == listener->events);

      aosDbgCheck(received != NULL);

      // wait for the S signal to become inactive and proceed on success

      if (_waitForS(listener, flags, APAL_GPIO_OFF, received) == AOS_SUCCESS) {

#if (AMIROOS_CFG_SSSP_MSI == true)

        nextstage = AOS_SSSP_STAGE_STARTUP_3;

#else /* (AMIROOS_CFG_SSSP_MSI == true) */

        nextstage = AOS_SSSP_STAGE_OPERATION;

#endif /* (AMIROOS_CFG_SSSP_MSI == true) */

      }

      break;

    }

#if (AMIROOS_CFG_SSSP_MSI == true)

      //TODO

#endif /* (AMIROOS_CFG_SSSP_MSI == true) */

    /*

     * Delay execution by one perion AOS_SSSP_DELAY, deactivate the SYNC signal and proceed.

     * NOTE: Actually only the module that initiated the shutdown has to delay execution here.

     *       For the sake of simlicity though, each module delays execution.

     */

    case AOS_SSSP_STAGE_SHUTDOWN_1_2:

    {

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask == 0);

      aosDbgCheck(received == NULL);

      // delay execution

      aosThdUSleep(AOS_SSSP_DELAY);

      // deactivate S signal

      apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_OFF);

      nextstage = AOS_SSSP_STAGE_SHUTDOWN_1_3;

      break;

    }

#if (AMIROOS_CFG_SSSP_SHUTDOWN == true)

    /*

     * Wait for S signal to become inactive.

     */

    case AOS_SSSP_STAGE_SHUTDOWN_1_3:

    {

      aosDbgCheck(listener != NULL);

      aosDbgCheck(flags != 0);

      aosDbgCheck(mask == listener->events);

      aosDbgCheck(received != NULL);

      // wait for the S signal to become inactive and proceed on success

      if (_waitForS(listener, flags, APAL_GPIO_OFF, received) == AOS_SUCCESS) {

        nextstage = AOS_SSSP_STAGE_SHUTDOWN_2_1;

      }

      break;

    }

    /*

     * Evaluate PD signal to determine whether a shutdown or restart is requested.

     * The logical state is returned by the function call.

     */

    case AOS_SSSP_STAGE_SHUTDOWN_2_1:

    {

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask == 0);

      aosDbgCheck(received != NULL);

      // evaluate PD signal

      apalControlGpioState_t pd;

      apalControlGpioGet(&moduleSsspGpioPD, &pd);

      *received = (pd == APAL_GPIO_ON) ? (eventmask_t)~0 : 0;

      nextstage = AOS_SSSP_STAGE_SHUTDOWN_2_2;

      break;

    }

    /*

     * Proceed with no further actions required.

     */

    case AOS_SSSP_STAGE_SHUTDOWN_2_2:

    {

      aosDbgCheck(listener == NULL);

      aosDbgCheck(flags == 0);

      aosDbgCheck(mask == 0);

      aosDbgCheck(received == NULL);

      nextstage = AOS_SSSP_STAGE_SHUTDOWN_2_3;

      break;

    }

#endif /* (AMIROOS_CFG_SSSP_SHUTDOWN == true) */

    default:

    {

      // this case must never occur!

      aosDbgAssertMsg(false, "Invalid SSSP stage tranition occurred");

      break;

    }

  } /* end of switch (aos.sssp.stage) */

  // outro and return

  laststage = aos.sssp.stage;

  const aos_status_t status = (nextstage > aos.sssp.stage) ? AOS_SUCCESS : AOS_FAILURE;

  aos.sssp.stage = nextstage;

  return status;

}

void aosSsspShutdownInit(void)

{

  // activate S signal

  apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_ON);

  // proceed to shutdown phase

  aos.sssp.stage = AOS_SSSP_STAGE_SHUTDOWN_1_2;

  return;

}

#if (AMIROOS_CFG_SSSP_SHUTDOWN == true) || defined(__DOXYGEN__)

/**

 * @brief   Sequnetially broadcast an identifier via S to specify a specific way to shutdown or restart.

 *

 * @param[in] identifier  Identifier to be broadcasted.

 */

void aosSsspShutdownBroadcastIdentifier(unsigned int identifier)

{

  // only broadcast anything if a identifier greater than 0 was specified

  if (identifier > 0) {

    // broadcast identifier

    for (unsigned int pulse = 0; pulse < identifier; ++pulse) {

      // wait one delay time with S being deactivated

      aosThdUSleep(AOS_SSSP_DELAY);

      // activate S for one AOS_SSSP_DELAY.

      apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_ON);

      aosThdUSleep(AOS_SSSP_DELAY);

      apalControlGpioSet(&moduleSsspGpioS, APAL_GPIO_OFF);

    }

  }

  // let a timeout pass and return

  aosThdUSleep(AOS_SSSP_TIMEOUT);

  return;

}

/**

 * @brief   Wait for a pulse during the SSSP shutdown disambiguation procedure.

 * @details Whenever a pulse is received, the identifier is incremented.

 *          Otherwise the internal timer is configured and will eventually trigger a timeout event.

 *

 * @param[in]     gpiolistener  Event listener for GPIO events.

 * @param[in]     sflags        Event flags to be set by edges on the S signal.

 * @param[in]     timermask     Event maks to use for the internal timer.

 * @param[in,out] identifier    Identifier variable to increment.

 *

 * @return  The event mask of whatever event was received during this function call.

 */

eventmask_t aosSsspShutdownWaitForIdentifierPulse(event_listener_t* gpiolistener, const eventflags_t sflags, eventmask_t timermask, unsigned int* identifier)

{

  aosDbgCheck(gpiolistener != NULL);

  aosDbgCheck(sflags != 0);

  aosDbgCheck(timermask != 0);

  aosDbgCheck(identifier != NULL);

  // local variables

  eventmask_t mask;

  eventflags_t flags;

  apalControlGpioState_t sstate;

  // arm the timer once

  if (!chVTIsArmed(&_delayTimer)) {

    chEvtRegisterMask(&_eventSourceDelay, &_eventListenerDelay, timermask);

    chVTSet(&_delayTimer, chTimeUS2I(AOS_SSSP_TIMEOUT), _timerCallback, &_eventSourceDelay);

  }

  // wait for any event to occur (do not apply any filters in order not to miss any events)

  mask = chEvtWaitOne(ALL_EVENTS);

  // GPIO event

  if (mask & gpiolistener->events) {

    // retreive flags without clearing them

    flags = gpiolistener->flags;

    apalControlGpioGet(&moduleSsspGpioS, &sstate);

    if (flags == sflags) {

      apalControlGpioGet(&moduleSsspGpioS, &sstate);

      // if this was the end of a pulse

      if (sstate == APAL_GPIO_OFF) {

        // restart the timer

        chVTReset(&_delayTimer);

        chVTSet(&_delayTimer, chTimeUS2I(AOS_SSSP_TIMEOUT), _timerCallback, &_eventSourceDelay);

        // increment the identifier

        ++(*identifier);

      }

    }

  }

  // timer event

  else if (mask & _eventListenerDelay.events) {

    // unregister event

    chEvtUnregister(&_eventSourceDelay, &_eventListenerDelay);

  }

  // any further events must be handled externally

  return mask;

}

#endif /* (AMIROOS_CFG_SSSP_SHUTDOWN == true) */

#endif /* (AMIROOS_CFG_SSSP_ENABLE == true) */

/** @} */