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.h

 * @brief   SSSP related macros, structures and functions.

 *

 * @addtogroup aos_sssp

 * @{

 */

#ifndef AMIROOS_SSSP_H

#define AMIROOS_SSSP_H

#include <amiroos.h>

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

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

/* CONSTANTS                                                                  */

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

/**

 * @brief   Major version of the implemented SSSP.

 */

#define AOS_SSSP_VERSION_MAJOR                  1

/**

 * @brief   Minor version of the implemented SSSP.

 */

#define AOS_SSSP_VERSION_MINOR                  4

/**

 * @brief   Time of delays in microseconds.

 */

#define AOS_SSSP_DELAY                          AMIROOS_CFG_SSSP_SIGNALDELAY

/**

 * @brief   Timeout delay in microseconds according to SSSP.

 * @details SSSP 1.x defines timeouts to be ten times longer than the signal delay time.

 */

#define AOS_SSSP_TIMEOUT                        (10 * AOS_SSSP_DELAY)

/**

 * @brief   Value to indicate an invalid module ID.

 */

#define AOS_SSSP_MODULEID_INVALID               ((aos_ssspmoduleid_t)0)

/**

 * @brief   Value for broadcasting, adressing all modules.

 * @note    This value is identical to @p AOS_SSSP_MODULEID_INVALID since in the case that no module IDs were applied, addressing of specific modules is not possible, thus every communication would be a broadcast.

 */

#define AOS_SSSP_MODULEID_BROADCAST             ((aos_ssspmoduleid_t)0)

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

/* SETTINGS                                                                   */

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

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

/* CHECKS                                                                     */

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

#if (AMIROOS_CFG_SSSP_MSI == true)

  #error "SSSP module stack initialization (MSI not implemented yet"

#endif

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

/* DATA STRUCTURES AND TYPES                                                  */

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

/**

 * @brief   Enumeration of the several stages of SSSP.

 */

typedef enum {

  AOS_SSSP_STAGE_UNDEFINED    = 0x0000, /**< Identifier of yet undefined stage variable.  */

  AOS_SSSP_STAGE_STARTUP      = 0x1000, /**< Identifier of SSSP startup phase.            */

  AOS_SSSP_STAGE_STARTUP_1    = 0x1100, /**< Identifier of SSSP startup phase stage 1.    */

  AOS_SSSP_STAGE_STARTUP_1_1  = 0x1110, /**< Identifier of SSSP startup phase stage 1-1.  */

  AOS_SSSP_STAGE_STARTUP_1_2  = 0x1120, /**< Identifier of SSSP startup phase stage 1-2.  */

  AOS_SSSP_STAGE_STARTUP_1_3  = 0x1130, /**< Identifier of SSSP startup phase stage 1-3.  */

  AOS_SSSP_STAGE_STARTUP_2    = 0x1200, /**< Identifier of SSSP startup phase stage 2.    */

  AOS_SSSP_STAGE_STARTUP_2_1  = 0x1210, /**< Identifier of SSSP startup phase stage 2-1.  */

  AOS_SSSP_STAGE_STARTUP_2_2  = 0x1220, /**< Identifier of SSSP startup phase stage 2-2.  */

  AOS_SSSP_STAGE_STARTUP_3    = 0x1300, /**< Identifier of SSSP startup phase stage 3.    */

  AOS_SSSP_STAGE_STARTUP_3_1  = 0x1310, /**< Identifier of SSSP startup phase stage 3-1.  */

  AOS_SSSP_STAGE_STARTUP_3_2  = 0x1320, /**< Identifier of SSSP startup phase stage 3-2.  */

  AOS_SSSP_STAGE_STARTUP_3_3  = 0x1330, /**< Identifier of SSSP startup phase stage 3-3.  */

  AOS_SSSP_STAGE_STARTUP_3_4  = 0x1340, /**< Identifier of SSSP startup phase stage 3-4.  */

  AOS_SSSP_STAGE_OPERATION    = 0x2000, /**< Identifier of SSSP operation phase.          */

  AOS_SSSP_STAGE_SHUTDOWN     = 0x3000, /**< Identifier of SSSP shutdown phase.           */

  AOS_SSSP_STAGE_SHUTDOWN_1   = 0x3100, /**< Identifier of SSSP shutdown phase stage 1.   */

  AOS_SSSP_STAGE_SHUTDOWN_1_1 = 0x3110, /**< Identifier of SSSP shutdown phase stage 1-1. */

  AOS_SSSP_STAGE_SHUTDOWN_1_2 = 0x3120, /**< Identifier of SSSP shutdown phase stage 1-2. */

  AOS_SSSP_STAGE_SHUTDOWN_1_3 = 0x3130, /**< Identifier of SSSP shutdown phase stage 1-3. */

  AOS_SSSP_STAGE_SHUTDOWN_2   = 0x3200, /**< Identifier of SSSP shutdown phase stage 2.   */

  AOS_SSSP_STAGE_SHUTDOWN_2_1 = 0x3210, /**< Identifier of SSSP shutdown phase stage 2-1. */

  AOS_SSSP_STAGE_SHUTDOWN_2_2 = 0x3220, /**< Identifier of SSSP shutdown phase stage 2-2. */

  AOS_SSSP_STAGE_SHUTDOWN_2_3 = 0x3230, /**< Identifier of SSSP shutdown phase stage 2-3. */

} aos_ssspstage_t;

/**

 * @brief   Type to represent module IDs.

 */

#if (AMIROOS_CFG_SSSP_MODULEIDWIDTH == 8)

typedef uint8_t aos_ssspmoduleid_t;

#elif (AMIROOS_CFG_SSSP_MODULEIDWIDTH == 16) || defined(__DOXYGEN__)

typedef uint16_t aos_ssspmoduleid_t;

#elif (AMIROOS_CFG_SSSP_MODULEIDWIDTH == 32)

typedef uint32_t aos_ssspmoduleid_t;

#else

#error "AMIROOS_CFG_SSSP_MODULEIDWIDTH set to an invalid value."

#endif

/**

 * @brief   Data structure holding module-wide SSSP information.

 */

typedef struct {

  /**

   * @brief   Current execution stage of SSSP.

   */

  aos_ssspstage_t stage;

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

  /**

   * @brief   Module identifier.

   * @details A value of @p AOS_SSSP_MODULEID_INVALID indicates an uninitialized ID.

   *          The values @p AOS_SSSP_MODULEID_INVALID and @p AOS_SSSP_MODULEID_ALL are reserved and must not be set.

   */

  aos_ssspmoduleid_t moduleId;

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

} aos_ssspdata_t;

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

/* MACROS                                                                     */

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

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

/* EXTERN DECLARATIONS                                                        */

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

#if defined(__cplusplus)

extern "C" {

#endif /* defined(__cplusplus) */

  void aosSsspInit(aos_timestamp_t* system_uptime);

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

  void aosSsspShutdownInit(bool active);

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

  void aosSsspShutdownBroadcastIdentifier(unsigned int identifier);

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

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

#if ((AMIROOS_CFG_SSSP_MASTER != true) && (AMIROOS_CFG_PROFILE == true)) || defined(__DOXYGEN__)

  float aosSsspGetSyncSkew(void);

#endif /* (AMIROOS_CFG_SSSP_MASTER != true) && (AMIROOS_CFG_PROFILE == true) */

#if defined(__cplusplus)

}

#endif /* defined(__cplusplus) */

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

/* INLINE FUNCTIONS                                                           */

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

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

#endif /* AMIROOS_SSSP_H */

/** @} */