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

*/

#ifndef AMIROOS_PERIPHAL_H

#define AMIROOS_PERIPHAL_H

#include <amiro-lld.h>

/*============================================================================*/

/* VERSION                                                                    */

/*============================================================================*/

/**

 * @brief   The periphery abstraction layer interface major version.

 * @note    Changes of the major version imply incompatibilities.

 */

#define PERIPHAL_VERSION_MAJOR    1

/**

 * @brief   The periphery abstraction layer interface minor version.

 * @note    A higher minor version implies new functionalty, but all old interfaces are still available.

 */

#define PERIPHAL_VERSION_MINOR    1

/*============================================================================*/

/* DEPENDENCIES                                                               */

/*============================================================================*/

#include <aosconf.h>

#include <hal.h>

/*============================================================================*/

/* DEBUG                                                                      */

/*============================================================================*/

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

#if defined(__cplusplus)

extern "C" {

#endif /* defined(__cplusplus) */

  void _apalDbgAssertMsg(const bool c, const char* fmt, ...);

  void apalDbgPrintf(const char* fmt, ...);

#if defined(__cplusplus)

}

#endif /* defined(__cplusplus) */

/**

 * @brief Assert function to check a given condition.

 *

 * @param[in] c     The condition to check.

 */

#define apalDbgAssert(c) _apalDbgAssertMsg(c, "%s(%u): apalDbgAssert failed", __FILE__, __LINE__)

#else /* (AMIROOS_CFG_DBG != true) */

#define apalDbgAssert(constition)

#define apalDbgAssertMsg(condition, fmt, ...)

#define apalDbgPrintf(fmt, ...)

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

/*============================================================================*/

/* GENERAL                                                                    */

/*============================================================================*/

/**

 * @brief Delay execution by a specific number of microseconds.

 *

 * @param[in]   us    Time to sleep until execution continues in microseconds.

 */

static inline void apalSleep(apalTime_t us)

{

  // check if the specified time can be represented by the system

  apalDbgAssert(us <= chTimeI2US(TIME_INFINITE));

  const sysinterval_t interval = chTimeUS2I(us);

  // TIME_IMMEDIATE makes no sense and would even cause system halt

  if (interval != TIME_IMMEDIATE) {

    chThdSleep(interval);

  }

  return;

}

/*============================================================================*/

/* GPIO                                                                       */

/*============================================================================*/

#if (HAL_USE_PAL == TRUE) || defined (__DOXYGEN__)

/**

 * @brief GPIO driver type.

 */

struct apalGpio_t {

  ioline_t line;

} PACKED_VAR;

/**

 * @brief Read the current value of a GPIO pin.

 *

 * @param[in]   gpio  GPIO to read.

 * @param[out]  val   Current value of the GPIO.

 *

 * @return The status indicates whether the function call was successful.

 */

static inline apalExitStatus_t apalGpioRead(apalGpio_t* gpio, apalGpioState_t* const val)

{

  apalDbgAssert(gpio != NULL);

  apalDbgAssert(val != NULL);

  *val = (palReadLine(gpio->line) == PAL_HIGH) ? APAL_GPIO_HIGH : APAL_GPIO_LOW;

  return APAL_STATUS_OK;

}

/**

 * @brief Set the value of a GPIO pin.

 *

 * @param[in] gpio  GPIO to write.

 * @param[in] val   Value to set for the GPIO.

 *

 * @return The status indicates whether the function call was successful.

 */

static inline apalExitStatus_t apalGpioWrite(apalGpio_t* gpio, const apalGpioState_t val)

{

  apalDbgAssert(gpio != NULL);

  // palWriteLine() is not guaranteed to be atomic, thus the scheduler is locked.

  syssts_t sysstatus = chSysGetStatusAndLockX();

  palWriteLine(gpio->line, (val == APAL_GPIO_HIGH) ? PAL_HIGH : PAL_LOW);

  chSysRestoreStatusX(sysstatus);

  return APAL_STATUS_OK;

}

/**

 * @brief Toggle the output of a GPIO.

 *

 * @param[in] gpio  GPIO to toggle.

 *

 * @return The status indicates whether the function call was successful.

 */

static inline apalExitStatus_t apalGpioToggle(apalGpio_t* gpio)

{

  apalDbgAssert(gpio != NULL);

  // palWriteLine() is not guaranteed to be atomic, thus the scheduler is locked.

  syssts_t sysstatus = chSysGetStatusAndLockX();

  palWriteLine(gpio->line, (palReadLine(gpio->line) == PAL_HIGH) ? PAL_LOW : PAL_HIGH);

  chSysRestoreStatusX(sysstatus);

  return APAL_STATUS_OK;

}

/**

 * @brief Return the interrupt enable status of the GPIO.

 *

 * @param[in]   gpio      GPIO to check.

 * @param[out]  enabled   Flag, indicating whether interrupt is enabled for the GPIO.

 *

 * @return The status indicates whether the function call was successful.

 */

static inline apalExitStatus_t apalGpioIsInterruptEnabled(apalGpio_t* gpio, bool* const enabled)

{

  apalDbgAssert(gpio != NULL);

  apalDbgAssert(enabled != NULL);

  *enabled = palIsLineEventEnabledX(gpio->line);

  return APAL_STATUS_OK;

}

/**

 * @brief Get the current on/off state of a control GPIO.

 *

 * @param[in]   gpio  Control GPIO to read.

 * @param[out]  val   Current activation status of the control GPIO.

 *

 * @return The status indicates whether the function call was successful.

 */

static inline apalExitStatus_t apalControlGpioGet(const apalControlGpio_t* const cgpio, apalControlGpioState_t* const val)

{

  apalDbgAssert(cgpio != NULL);

  apalDbgAssert(cgpio->gpio != NULL);

  apalDbgAssert(val != NULL);

  *val = ((palReadLine(cgpio->gpio->line) == PAL_HIGH) ^ (cgpio->meta.active == APAL_GPIO_ACTIVE_HIGH)) ? APAL_GPIO_OFF : APAL_GPIO_ON;

  return APAL_STATUS_OK;

}

/**

 * @brief Turn a control GPIO 'on' or 'off' respectively.

 *

 * @param[in] gpio  Control GPIO to set.

 * @param[in] val   Activation value to set for the control GPIO.

 *

 * @return The status indicates whether the function call was successful.

 */

static inline apalExitStatus_t apalControlGpioSet(const apalControlGpio_t* const cgpio, const apalControlGpioState_t val)

{

  apalDbgAssert(cgpio != NULL);

  apalDbgAssert(cgpio->gpio != NULL);

  apalDbgAssert(cgpio->meta.direction == APAL_GPIO_DIRECTION_OUTPUT || cgpio->meta.direction == APAL_GPIO_DIRECTION_BIDIRECTIONAL);