AMiRo-OS

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

# Copyright (c) 2016..2019  Thomas Schöpping                                   #

  <module>:

      Builds the binary only for the specified module.

  flash_<module>:

      Builds the binary for the specified module and flashes it to the hardware.

  clean_<module>:

      Deletes all temporary and binary files of the specified module.

  >$$ make all -j

      This command will first build missing binary files for all modules that

      are found in the 'modules/' folder.

  >$$ make flash_DiWheelDrive_1-1

      This command will build the binary for the DiWheelDrive module

      (version 1.1) only if required, and flash it to the hardware.

  >$$ make clean; make all; make flash_DiWheelDrive_1-1

      This command will first clean all projects. In a second step the binaries

      for all modules are build from scratch. Finally the DiWheelDrive module

      (version 1.1) is updated with the latest software.

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

  1  Required Software

  2  Recommended Software

  3  Building and Flashing

  4  Developer Guides

    4.1  Adding a New Module

    4.2  Handling a Custom I/O Event in the Main Thread

    4.3  Implementing a New Low-Level Driver

    4.4  Writing a Unit Test

=====================

make AMiRo-OS work properly. It is recommended to use the .setup.sh script for

this purpose.

Any required low-level drivers for the AMiRo hardware are available in an

========================

AMiRo-OS can take advantage of an installed bootloader, which is recommended for

Advanced users can use several connections to multiple modules simultaneously.

Each additional programmer will be available as '/dev/ttyAMiRo<N>' (and

'/dev/USB<N>' respectively) with <N> being an integer number starting from zero.

Please note: Those interfaces are ordered by the time when they have been

detected by the operating system.

=========================

4 - DEVELOPER GUIDES

====================

Due to the complexity of AMiRo-OS it can be quite troublesome to get started

with the framework at the beginning. The guides in this chapter will help you

getting things done, without thorough knowledge of the software structure.

Whereas the textual descriptions of the guides provide additional informatio

about the underlying concepts and mechanisms, a short summary is provided at the

end of each chapter.

4.1  Adding a New Module

------------------------

The very first thing to do when adding a new module to support AMiRo-OS is to

create an according folder in the modules/ directory. The name of this folder

should be as unambiguous as possible (e.g. containing name and version number).

All files, which directly depent on the hardware, and thus are not portable,

belong here. Conversely, any code that can be reused on diferent hardware must

not be put in the module folder.

In a second step you have to initialize all requried files (see below) in the

newlly created module directory. It is recommended to use another module as

template for your configuration:

- alldconf.h

  Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.

- aosconf.h

  Configuration header for the AMiRo-OS project.

- board.h & board.c

  Contains definitions of GPIO names and initialization setting of those, as

  well as initialization functions.

- chconf.h

  Configuration header for the ChibiOS/RT system kernel. There are probably only

  very few configurations one here, since most settings depend on the content of

  aosconf.h and are handled module unspecific in modules/aos_chconf.h

- halconf.h

  Configuration header for ChibiOS/HAL (hardware abstraction layer).

- Makefile

  The GNU make script to build and flash AMiRo-OS for the module.

- mcuconf.h

  Configuration file for ChibiOS/JAL to initialize the microcontroller (MCU). It

  is recommended to check the kernel/ChibiOS/demos/ directory for an example

  using the according MCU and copy the mcuconf.h from there. Depending on your

  hardware you may have to modify it nevertheless, though.

- module.h & module.c

  These files act as some sort of container, where all module specific aliases

  for interfaces and GPIOs, configurations, hooks, low-level drivers, and unit

  tests are defined. These are most probably the most comprehensive files in the

  module folder.

- <mcu>.ld

  Linker script, defining the memory layout and region aliases. It is

  recommended to check ChibiOS (kernel/ChibiOS/os/common/startup/) whether a

  linker script for the according MCU already exists.

Since all these files are specific to the module hardware, youl will have to

modify the contents according to your setup in a third step. Most settings are

described in detail within the configuration files, but for others you will have

to consult the datasheet of your MCU and even take a closer look at how certain

settings are used in other modules.

Finally, you need to build and flash the project. The compiler might even help

you getting everything set up correctly. Take time to understand compilation

errors and warning and get rid of all of those (warnings should not be ignored

since they are hints that something might be amiss and the program will not act

as intended).

Summing up, you have to

1) create a module directory.

2) initialize all files (use an existing module or a ChibiOS demo as template).

3) configure all files according to your hardware setup and preferences.

4) compile, flash and check for issues.

4.2  Handling a Custom I/O Event in the Main Thread

---------------------------------------------------

In order to handle custom I/O events in the main thread, AMiRo-OS offers several

hooks to be used. First of all, you need to configure and enable the interrupt

in the according GPIO. This can be done by implementing the

MODULE_INIT_INTERRUPTS() hook in the module.h file. For information how to use

this hook, please have a look at existing modules. In the end, the interrupt

callback functions has to emit an I/O event with the according bit in the flags

mask set (like the _intCallback() function in aos_system.c). As result, whenever

a rising or falling edge (depends on configuration) is detected on that GPIO,

the interrupt service routine is executed and hence an I/O event is fired, which

can be catched by any thread in the system.

Next, you have to configure the main thread to whitelist the event flag (all I/O

events are blacklisted by default). While system relevant events like power down

are whitelisted by the OS, any custom events need to be added exl´plicitely.

This is done via the optional AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK macro, which

should be defined in the module.h file. Example:

  #define AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK                \

    (AOS_IOEVENT_FLAG(padX) | AOS_IOEVENT_FLAG(padY) | AOS_IOEVENT_FLAG(padZ))

When AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK has been defined correctly, the main

thread will be notified by the according events and execute its event handling

routine. Hence you have to implement another macro in module.h to handle the

custom event(s) appropriately: MODULE_MAIN_LOOP_IO_EVENT(eventflags). As you can

see, the variable 'eventflags' is propagated to the hook. This variable is a

mask, that allows to identify the GPIO pad(s), which caused the event, by the

bits set. Following the example above, you can check which GPIOs have caused

events by using if-clauses in the implementation of the hook:

  #define MODULE_MAIN_LOOP_IO_EVENT(eventflags) {           \

    if (eventflags & AOS_IOEVENT_FLAG(padX)) {              \

      /* handle event */                                    \

    }                                                       \

    if (eventflags & (AOS_IOEVENT_FLAG(padY) |              \

          AOS_IOEVENT_FLAG(padZ))) {                        \

      /* handle combined event */                           \

    }                                                       \

  }

Summing up, you have to

1) configure and enable the GPIO interrupt.

2) define the AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK macro.

3) implement the MODULE_MAIN_LOOP_IO_EVENT(eventflags) hook.

4.3  Implementing a New Low-Level Driver

----------------------------------------

In the AMiRo-OS framework, low-level drivers are located in the additional Git

project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at

periphery-lld/AMiRo-LLD/ and acts similar to a static library. When adding a new

low-level driver to the framework, you have to implement it, providing a

(single) header file in periphery-lld/AMiRo-LLD/include/ and the required C

sources in periphery-lld/AMiRo-LLD/source/. By convention, all filenames use the

prefix 'alld_' to avoid ambiguities. Furthermore, files should be named by the

exact designation of the hardware (e.g. 'alld_vcnl4020' instead of

'alld_proximitysensor'). Since AMiRo-LLD is intended to be usable with other

operating systems than AMiRo-OS, it provides an interface for accessing

communication interfaces and basic functionalities of the operating system. On

the one hand, several types are defined in periphery-lld/AMiRo-LLD/periphALtypes.h.

The interface functions, on the other hand, are defined by AMiRo-LLD (cf.

periphery-lld/AMiRo-LLD/templates/periphAL.h), but implemented by the operating

system (cf. periphery-lld/periphAL.h). For the implementation of the driver, you

must only use those types and functions to interact with the operating system.

If you need further functionality, which is not provided by the interface yet,

you are encouraged to extend periphAL.

Furthermore, all files must define a guard, so that the whole driver is

disabled, when the guard is not set explicitely. These guard again are named

following a convention, but instead of explaning it here, just have a look at

one of the existing drivers and look for lines like

  #if defined(AMIROLLD_CFG_USE_VCNL4020) || defined(__DOXYGEN__)

With these guards in place, the driver will be omitted by default and needs to

be enabled explicitely. In order to do so, you need to add an according #define

in the alldconf.h file of any module, which shall use the new driver.

Now the new driver is available and enabled, but not actually used yet.

Therefore you have to add according memory structures to the module.h and

module.c files - just have a look at existing modules how this is done. In some

cases you will have to configure additional interrupts and/or alter the

configuration of a communication interface (e.g. I²C). Once again, you should

take a look at existing modules and search the module.h for the hooks

MODULE_INIT_INTERRUPTS() and MODULE_INIT_PERIPHERY_COMM().

Finally, you will probably want to validate your implementation via a unit test.

How this can be done is explained in detail in the next guide.

Summing up, you have to

1) implement the driver in AMiRo-LLD using periphAL only.

2) fence all code in all files by a guard.

3) set the guard in alldconf.h to enable the driver.

4) add the driver to a module.

5) configure interrupts and interfaces as required.

6) write a unit test.

4.4  Writing a Unit Test

------------------------

AMiRo-OS provides a unit test framework for conventient testing and the ability

to opt-out all unit tests via the aosconf.h configuration file. There is also a

dedicated folder, where all unit test code belongs to. In case you want to

implement a unit test for a newly developed low-level driver, you should use the

folders unittests/periphery-lld/inc and unittests/periphery-lld/src

respectively. As with the low-level drivers, unit test files should use a prefix

in their name, namely 'ut_' and all code should be fenced via guards that

disable it by default (have a look at existing unit tests). Before you implement

a vast test, however, it is highly recommended to start with some sceleton code

(just copy an existing unit test, scoop out the test function, and rename

according variables etc.) and make it compile and run.

After you have initialized the unit test sceleton, you have to add the according

aos_unittest_t (cf. core/inc/aos_unittest.h) object to the module.h and module.c

files. These objects again require an shell command, so the unit test can be run

via the AMiRo-OS shell. As with existing unit tests, this shell command callback

function as well as any further required data should be implemented directly in

module.c, so it not accessable from any other context. In most cases this

callback function is trivial, anyway.

In order to make the shell command, which executes the unit test, available in

shell so a user can run it, it has to be associated with the shell. AMiRo-OS

provides the hook MODULE_INIT_TESTS() for this purpose, which has to be

implemented in the module.h file. Once again I recommend to have a look at an

existing module, how to use this hook.

Since the execution pipeline is set up now, you can fille your unit test with

life. Remember that the test is executed by the shell thread, so you can access

any functionality of the system, but might encounter race conditions, depending

on what other applications run concurrently.

Summing up, you have to

1) initialize a unit test sceleton in the unittests/ folder.

2) introduce an according object and configuration in module.h and module.c.

3) associate the shell command to a shell via the hook in module.h.

4) implement the full unit test in the prevously created sceleton files.

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

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

### check whether commands are available #######################################

# Checks whether the specified commands are available and can be executed.

#

# usage:      checkCommand [<command> <command> ...]

# arguments:  <command>

#                 Name of the command to check.

# return:     0

#                 All requested commands are available.

#             >0

#                 Number of requested commands that were not found.

#             -1

#                 No argument given.

#

function checkCommands {

  local status=0

  # return if no argument was specified

  if [ $# -eq 0 ]; then

    return -1

  fi

  # check all specified commands

  while [ $# -gt 0 ]; do

    command -v $1 &>/dev/null

    if [ $? -ne 0 ]; then

      printWarning "Command '$1' not available.\n"

      status=$((status + 1))

    fi

    shift 1

  done

  return $status

}

#             -2

#                 Error: Missing dependencies.

  # check dependencies

  checkCommands git

  if [ $? -ne 0 ]; then

    printError "Missing dependencies detected.\n"

    return -2

  fi

# return:     0

#                 No error or warning occurred.

#             1

#                 Warning: AMiRo-BLT Git submodule already empty

#             2

#                 Warning: Aborted by user.

#             -1

#                 Error: Unexpected input occurred

#             -2

#                 Error: Missing dependencies.

#

  # check dependencies

  checkCommands git

  if [ $? -ne 0 ]; then

    printError "Missing dependencies detected.\n"

    return -2

  fi

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

AMIROOSCORECSRC = $(wildcard $(AMIROOS_CORE_DIR)src/*.c)

AMIROOSCORECPPSRC = $(wildcard $(AMIROOS_CORE_DIR)src/*.c?*)

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

#ifndef AMIROOS_CFG_SSSP_ENABLE

  #error "AMIROOS_CFG_SSSP_ENABLE not defined in aosconf.h"

# if (AMIROOS_CFG_SSSP_ENABLE == true)

  #ifndef AMIROOS_CFG_SSSP_MASTER

    #error "AMIROOS_CFG_SSSP_MASTER not defined in aosconf.h"

  #endif

  #ifndef AMIROOS_CFG_SSSP_STACK_START

    #error "AMIROOS_CFG_SSSP_STACK_START not defined in aosconf.h"

  #ifndef AMIROOS_CFG_SSSP_STACK_END

    #error "AMIROOS_CFG_SSSP_STACK_END not defined in aosconf.h"

  #endif

  #if (AMIROOS_CFG_SSSP_STACK_START == true) && (AMIROOS_CFG_SSSP_STACK_END == true)

    #warning "AMIROOS_CFG_SSSP_STACK_START and AMIROOS_CFG_SSSP_STACK_END both enabled in aosconf.h"

    #if (AMIROOS_CFG_SSSP_MASTER != true)

      #error "AMIROOS_CFG_SSSP_MASTER must be enabled in this case"

    #endif

  #endif

  #ifndef AMIROOS_CFG_SSSP_SIGNALDELAY

    #error "AMIROOS_CFG_SSSP_SIGNALDELAY not defined in aosconf.h"

  #endif

  #ifndef AMIROOS_CFG_SSSP_SYSSYNCPERIOD

    #error "AMIROOS_CFG_SSSP_SYSSYNCPERIOD not defined in aosconf.h"

  #endif

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

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

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

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

#include <time.h>

/**

 * @brief   Enumerator to identify shutdown types.

 */

typedef enum aos_shutdown {

  AOS_SHUTDOWN_NONE,            /**< Default value if no shutdown action was initiated */

  AOS_SHUTDOWN_PASSIVE,         /**< Passive shutdown (initiated by another module). */

  AOS_SHUTDOWN_HIBERNATE,       /**< Active shutdown to hibernate mode. */

  AOS_SHUTDOWN_DEEPSLEEP,       /**< Active shutdown to deepsleep mode. */

  AOS_SHUTDOWN_TRANSPORTATION,  /**< Active shutdown to transportation mode. */

  AOS_SHUTDOWN_RESTART,         /**< Active saystem restart request. */

} aos_shutdown_t;

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

#endif /* AMIROOS_CFG_SSSP_ENABLE == true */

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

#endif /* AMIROOS_CFG_SSSP_ENABLE == true */

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

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

#if (AMIROOS_CFG_DBG == true) && (CH_DBG_FILL_THREADS == TRUE)

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

#endif /* AMIROOS_CFG_DBG == true */

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

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

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

 * @brief   Converts a GPIO pad number to a unique event flag.

 */

#define AOS_IOEVENT_FLAG(pad)                   ((eventflags_t)1 << pad)

/**

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

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

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

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

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

#else /* AMIROOS_CFG_SSSP_ENABLE == false */

/**

 * @brief   Default shutdown mode if SSSP is unavailable.

 */

#define AOS_SHUTDOWN_DEFAULT                    AOS_SHUTDOWN_DEEPSLEEP

#endif /* AMIROOS_CFG_SSSP_ENABLE */

#endif /* AMIROOS_CFG_SHELL_ENABLE == true */

#endif /* defined(MODULE_HAL_PROGIF) */

  aosprintf("CTRL: unexpected/unknown event received. mask: 0x%08X; flags: 0x%08X\n", mask, flags);

  (void)(mask);

  (void)(flags);

  return;

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

  aosDbgCheck(par != NULL);

  chSysLockFromISR();

  chEvtBroadcastI((event_source_t*)par);

  chSysUnlockFromISR();

  return;

#endif /* AMIROOS_CFG_SSSP_ENABLE == true */

  aosDbgCheck(dst != NULL);

  aosDbgCheck(n > 0 && n <= 8);

  for (uint8_t byte = 0; byte < n; ++byte) {

    dst[byte] = (uint8_t)((src >> (byte * 8)) & 0xFF);

  }

  return;

  aosDbgCheck(src != NULL);

  aosDbgCheck(n > 0 && n <= 8);

  uint64_t result = 0;

  for (uint8_t byte = 0; byte < n; ++byte) {

    result |= ((uint64_t)src[byte]) << (byte * 8);

  }

  return result;

  aosDbgCheck(src != NULL);

  return (((uint64_t)(src->tm_sec  & 0x0000003F) << (0))               |

          ((uint64_t)(src->tm_min  & 0x0000003F) << (6))               |

          ((uint64_t)(src->tm_hour & 0x0000001F) << (12))              |

          ((uint64_t)(src->tm_mday & 0x0000001F) << (17))              |

          ((uint64_t)(src->tm_mon  & 0x0000000F) << (22))              |

          ((uint64_t)(src->tm_year & 0x00FFFFFF) << (26))              |

          ((uint64_t)(src->tm_wday & 0x00000007) << (50))              |

          ((uint64_t)(src->tm_yday & 0x000001FF) << (53))              |

          ((uint64_t)((src->tm_isdst == 0) ? 0 : (src->tm_isdst > 0) ? 1 : 2) << (62)));

  aosDbgCheck(dst != NULL);

  dst->tm_sec  = (src >> 0)  & 0x0000003F;

  dst->tm_min  = (src >> 6)  & 0x0000003F;

  dst->tm_hour = (src >> 12) & 0x0000001F;

  dst->tm_mday = (src >> 17) & 0x0000001F;

  dst->tm_mon  = (src >> 22) & 0x0000000F;

  dst->tm_year = (src >> 26) & 0x00FFFFFF;

  dst->tm_wday = (src >> 50) & 0x00000007;

  dst->tm_yday = (src >> 53) & 0x000001FF;

  dst->tm_isdst = (((src >> 62) & 0x03) == 0) ? 0 : (((src >> 62) & 0x03) > 0) ? 1 : -1;

  return;

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

  // local types

  /**

  typedef enum {

    STAGE_3_1,                  /**< Initiation of SSSP startup stage 3. */

    STAGE_3_2,                  /**< Starting the sequence and broadcasting the first ID. */

    STAGE_3_3_WAITFORFIRSTID,   /**< Waiting for first ID after initiation. */

    STAGE_3_3_WAITFORIDORSIG,   /**< Waiting for next ID or activation of neighbor signal. */

    STAGE_3_3_WAITFORID,        /**< Waiting for next ID (after the module has set its own ID). */

    STAGE_3_4_FINISH,           /**< Successful finish of stage 3. */

    STAGE_3_4_ABORT_ACTIVE,     /**< Aborting stage 3 (active). */

    STAGE_3_4_ABORT,            /**< Aborting stage 3 (passive). */

  } sssp_modulestackinitstage_t;

  typedef struct {

    bool loop     : 1;

    bool wfe      : 1;

    bool wfe_next : 1;

  } flags_t;

  // local variables

  aos_shutdown_t shutdown = AOS_SHUTDOWN_NONE;

  sssp_modulestackinitstage_t stage = STAGE_3_1;

  eventmask_t eventmask = 0;

  eventflags_t ioflags = 0;

  event_source_t eventSourceTimeout;

  event_source_t eventSourceDelay;

  event_listener_t eventListenerTimeout;

  event_listener_t eventListenerDelay;

  event_listener_t eventListenerCan;

  virtual_timer_t timerTimeout;

  virtual_timer_t timerDelay;

  CANTxFrame canTxFrame;

  CANRxFrame canRxFrame;

  aos_ssspmoduleid_t lastid = 0;

#endif

  flags_t flags;

  aos_timestamp_t uptime;

  // initialize local varibles

  chEvtObjectInit(&eventSourceTimeout);

  chEvtObjectInit(&eventSourceDelay);

  chVTObjectInit(&timerTimeout);

  chVTObjectInit(&timerDelay);

  canTxFrame.RTR = CAN_RTR_DATA;

  canTxFrame.IDE = CAN_IDE_STD;

  flags.loop = true;

  flags.wfe = false; // do not wait for events in the initial iteration of the FSM loop

  flags.wfe_next = true;

  // initialize system variables

  aos.sssp.stage = AOS_SSSP_STARTUP_3_1;

  aos.sssp.moduleId = 0;

  // listen to events (timout, delay, CAN receive)

  chEvtRegisterMask(&eventSourceTimeout, &eventListenerTimeout, TIMEOUTEVENT_MASK);

  chEvtRegisterMask(&eventSourceDelay, &eventListenerDelay, DELAYEVENT_MASK);

  chEvtRegisterMask(&MODULE_HAL_CAN.rxfull_event, &eventListenerCan, CANEVENT_MASK);

  /*

  aosDbgPrintf("SSSP stack initialization sequence:\n");

  while (flags.loop) {

    switch (stage) {

      case STAGE_3_1:

        aosDbgPrintf(">>> 3-1\n");

        break;

      case STAGE_3_2:

        aosDbgPrintf(">>> 3-2\n");

        break;

      case STAGE_3_3_WAITFORFIRSTID:

        aosDbgPrintf(">>> 3-3 (1st ID)\n");

        break;

      case STAGE_3_3_WAITFORIDORSIG:

        aosDbgPrintf(">>> 3-3 (ID/sig)\n");

        break;

      case STAGE_3_3_WAITFORID:

        aosDbgPrintf(">>> 3-3 (ID)\n");

        break;

      case STAGE_3_4_FINISH:

        aosDbgPrintf(">>> 3-4 (finish)\n");

        break;

      case STAGE_3_4_ABORT_ACTIVE:

        aosDbgPrintf(">>> 3-4 (active abort)\n");

        break;

      case STAGE_3_4_ABORT:

        aosDbgPrintf(">>> 3-4 (abort)\n");

        break;

    }

    // reset wfe flag for the next iteration

    flags.wfe_next = true;

    // waiting for events (may be skipped)

    if (flags.wfe) {

      // wait for any event to occur

      aosDbgPrintf("WFE...");

      eventmask = chEvtWaitAnyTimeout(ALL_EVENTS, chTimeUS2I(AOS_SYSTEM_SSSP_TIMEOUT));

      aosDbgPrintf("\t0x%08X", eventmask);

    } else {

      aosDbgPrintf("WFE skipped");

      eventmask = 0;

    }

    aosSysGetUptime(&uptime);

    aosDbgPrintf("\t%04ums\n", (uint32_t)(uptime / MICROSECONDS_PER_MILLISECOND));

    /*

    // no event occurred at all

    if ((flags.wfe) && (eventmask == 0)) {

      aosDbgPrintf("ERR: no evt\n");

      // enforce timeout event

      chEvtBroadcast(&eventSourceTimeout);

      continue;

    }

    // if an IO event occurred

    if (eventmask & _eventListenerIO.events) {

      ioflags = chEvtGetAndClearFlags(&_eventListenerIO);

      aosDbgPrintf("INFO: IO evt (0x%08X)\n", ioflags);

      // a power-down event occurred

      if (ioflags & MODULE_SSSP_EVENTFLAGS_PD) {

        aosDbgPrintf("PD evt\n");

        // deactivate S and UP

        aosDbgPrintf("disabling S\n");

        apalControlGpioSet(&moduleSsspGpioSync, APAL_GPIO_OFF);

        aosDbgPrintf("disabling UP\n");

        apalControlGpioSet(&moduleSsspGpioUp, APAL_GPIO_OFF);

#endif

        // set shutdown flag and exit the loop

        shutdown = AOS_SHUTDOWN_PASSIVE;

        break;

      }

      // the S signal was deactivated

      if (ioflags & MODULE_SSSP_EVENTFLAGS_SYNC) {

        apalControlGpioState_t sstate;

        apalControlGpioGet(&moduleSsspGpioSync, &sstate);

        if (sstate == APAL_GPIO_ON) {

          aosDbgPrintf("S evt (enabled)\n");

        } else {

          aosDbgPrintf("S evt (disabled)\n");

          // either finish or abort

          if ((stage == STAGE_3_3_WAITFORID) && (aos.sssp.moduleId != 0)) {

            stage = STAGE_3_4_FINISH;

          } else if (stage != STAGE_3_4_ABORT) {

            stage = STAGE_3_4_ABORT_ACTIVE;

          }

      }

    }

    // an OS event occurred

    if (eventmask & _eventListenerOS.events) {

      aosDbgPrintf("WARN: OS evt\n");

      // get the flags

      eventflags_t oseventflags = chEvtGetAndClearFlags(&_eventListenerOS);

      // there should be no OS events at this point

      MODULE_SSSP_STARTUP_3_OSEVENT_HOOK(eventmask, eventflags);

      _unexpectedEventError(eventmask, oseventflags);

    }

    // if a CAN event occurred

    if ((eventmask & eventListenerCan.events)) {

      aosDbgPrintf("CAN evt\n");

      // fetch message

      if (flags.wfe) {

        canReceiveTimeout(&MODULE_HAL_CAN, CAN_ANY_MAILBOX, &canRxFrame, TIME_IMMEDIATE);

        aosDbgPrintf("CAN <- 0x%03X\n", canRxFrame.SID);

      }

      // identify and handle abort messgaes

      if (canRxFrame.SID == SSSP_STACKINIT_CANMSGID_ABORT) {

        stage = STAGE_3_4_ABORT;

      }

      // warn if a unexpected message was received

      else if ((canRxFrame.SID != SSSP_STACKINIT_CANMSGID_INIT) &&

               (canRxFrame.SID != SSSP_STACKINIT_CANMSGID_MODULEID)) {

        aosDbgPrintf("WARN: unknown msg\n");

      }

      // any further pending messages are fetched at the end of the loop

    }

    // if a timeout event occurred

    if (eventmask & eventListenerTimeout.events) {

      aosDbgPrintf("timeout evt\n");

      // is handled at the end of the loop (or must be cleared by FSM)

    }

    // if a delay event occurred

    if (eventmask & eventListenerDelay.events) {

      aosDbgPrintf("delay evt\n");

      // is handled by FSM

    }

    /*

    switch (stage) {

      case STAGE_3_1:

      {

        aos.sssp.stage = AOS_SSSP_STARTUP_3_1;

        // there was no event at all (skipped wfe)

        if (eventmask == 0 && flags.wfe == false) {