AMiRo-OS

│ a makefile that allows to easily integrate the project. Furthermore, two

├── docs/

│     UML graphs (using PlantUML; see plantuml.com for further information)

│     visualize the structure of the AMiRo-LLD project. Doxygen related files

│     can be used to gererate a documentation of the whole project (wip).

│

├── drivers/

│     Each driver must provide a makefile script, which adds the required

│     include folders to the AMIROLLD_INC variable and all C source files to the

│     AMIROLLD_CSRC variable.

      AMiRo-LLD expects a configuration header "alldconf.h" to be found in the

      include paths. An according template for such file can be found here.

      There is no template for an implementation of periphAL, though. The

      provided interface header in the root directory (periphAL.h) should give

      you all required information for such an implementation anyway.

according folder in the drivers/ directory. For this guide, we will add the

fictional DEVICE1234. For this example the folders to be created are

"drivers/DEVICE1234/" and "drivers/DEVICE1234/v1/". In case there already exists

a driver implementation for this device, but you want to implement another

version from scratch (not just an update), the version subfolder must be named

accordingly (e.g. "drivers/DEVICE1234/v42/").

Most drivers will consist of exactly three files:

 - alld_DEVICE1234.mk

 - alld_DEVICE1234.h

 - alld_DEVICE1234.c

However, some drivers may feature multiple .h and/or .c files or even come with

additional subfolders. In any case, all those required folders, including the

driver root folder (i.e. "drivers/DEVICE1234/v1/"), as well as all C source

files must be added to the according makefile variables AMIROLLD_INC and

AMIROLLD_CSRC by the makefile script.

It is highly recommended that files in the driver root directory (i.e.

"drivers/DEVICE1234/v1/") use the prefix "alld_" in their names. This not only

helps to achieve an easy to understand file structure, but also prevents

compilation issues due to naming conflicts of header files.

1) create device and version folders.

2) add a makefile script.

3) add header- and source files as well as subfulders, implementing the diver

Implementation of a new driver usually is very straightforward. You most

to common functionalities). Only then you implement those functions, using

periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.) in a

separate C source file, or 'inline' in the header file itself.

implement those interface functions and map them to periphAL.

can do one of the following:

1) Think again if you really need that funcionality or whether it can be

   replicated by the existing API.

2) File a feature request to extend periphAL.

3) Write a custom patch that modifies periphAL to meet your requirements.

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

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

#define AMIROLLD_RELEASE_TYPE                   "beta"

#define AMIROLLD_VERSION_MAJOR                  1

#define AMIROLLD_VERSION_MINOR                  1

#define AMIROLLD_VERSION_PATCH                  0

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

/* CONFIGURATION & VERIFICATION                                               */

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

  #error "invalid AMiRo-LLD configuration file"

#elif (AMIRO_LLD_CFG_VERSION_MAJOR != AMIROLLD_VERSION_MAJOR) || (AMIRO_LLD_CFG_VERSION_MINOR < AMIROLLD_VERSION_MINOR)

  #error "incompatible AMiRo-LLD configuration file"

#if !defined(AMIROLLD_CFG_TIME_SIZE)

  #error "AMIROLLD_CFG_TIME_SIZE not defined in alldconf.h"

#endif /* !defined(AMIROLLD_CFG_TIME_SIZE) */

#if !defined(AMIROLLD_CFG_DBG)

  #error "AMIROLLD_CFG_DBG not defined in alldconf.h"

#endif /* !defined(AMIROLLD_CFG_DBG) */

#if !defined(AMIROLLD_CFG_GPIO)

  #error "AMIROLLD_CFG_GPIO not defined in alldconf.h"

#endif /* !defined(AMIROLLD_CFG_GPIO) */

#if !defined(AMIROLLD_CFG_PWM)

  #error "AMIROLLD_CFG_PWM not defined in alldconf.h"

#endif /* !defined(AMIROLLD_CFG_PWM) */

#if !defined(AMIROLLD_CFG_QEI)

  #error "AMIROLLD_CFG_QEI not defined in alldconf.h"

#endif /* !defined(AMIROLLD_CFG_QEI) */

#if !defined(AMIROLLD_CFG_I2C)

  #error "AMIROLLD_CFG_I2C not defined in alldconf.h"

#endif /* !defined(AMIROLLD_CFG_I2C) */

#if !defined(AMIROLLD_CFG_SPI)

  #error "AMIROLLD_CFG_SPI not defined in alldconf.h"

#endif /* !defined(AMIROLLD_CFG_SPI) */

#if ((AMIROLLD_CFG_GPIO == true) || \

     (AMIROLLD_CFG_PWM == true)  || \

     (AMIROLLD_CFG_QEI == true)  || \

     (AMIROLLD_CFG_I2C == true)  || \

     (AMIROLLD_CFG_SPI == true)) && \

    !defined(AMIROLLD_CFG_PERIPHAL_HEADER)

  #error "AMIROLLD_CFG_PERIPHAL_HEADER required but not defined in alldconf.h"

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

/* PERIPHERY ABSTRACTION LAYER (periphAL)                                     */

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

#if defined(AMIROLLD_CFG_PERIPHAL_HEADER)

#include AMIROLLD_CFG_PERIPHAL_HEADER

#endif

#include <periphAL.h>

/*

AMiRo-LLD is a compilation of low-level hardware drivers 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 Lesser 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License

along with this program.  If not, see <http://www.gnu.org/licenses/>.

*/

#ifndef AMIROLLD_PERIPHAL_H

#define AMIROLLD_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    2

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

/* DEPENDENCIES                                                               */

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

#include <stdint.h>

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

/* GENERAL                                                                    */

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

/**

 * @brief Status values used as return value for all (or most) function calls.

 * @note  The status can be used as mask of flags.

 */

typedef int8_t apalExitStatus_t;

/**

 * @brief   Status value for success (no error or warning occurred).

 */

#define APAL_STATUS_OK                          ((apalExitStatus_t)0)

#define APAL_STATUS_SUCCESS                     ((apalExitStatus_t)0)

/**

 * @brief   Status value for unspecified failure.

 */

#define APAL_STATUS_ERROR                       ((apalExitStatus_t)-1)

#define APAL_STATUS_FAILURE                     ((apalExitStatus_t)-1)

/**

 * @brief   Status value for timeout failure.

 */

#define APAL_STATUS_TIMEOUT                     ((apalExitStatus_t)-2)

/**

 * @brief   Status value for failure because of invalid arguments.

 */

#define APAL_STATUS_INVALIDARGUMENTS            ((apalExitStatus_t)-4)

/**

 * @brief   Status value for failure because the function is not available/implemented.

 */

#define APAL_STATUS_UNAVAILABLE                 ((apalExitStatus_t)-8)

/**

 * @brief   Status value for unspecified warning.

 */

#define APAL_STATUS_WARNING                     ((apalExitStatus_t)1)

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

/* DEBUG                                                                      */

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

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

#if defined(__cplusplus)

extern "C" {

#endif /* defined(__cplusplus) */

#if !defined(apalDbgAssertMsg) || defined(__DOXYGEN__)

  /**

   * @brief Assert function to check a given condition and print a message string.

   *

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

   * @param[in] fmt   Formatted message string to print.

   */

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

#endif

#if !defined(apalDbgPrintf) || defined(__DOXYGEN__)

  /**

   * @brief Printf function for messages printed only in debug builds.

   *

   * @param[in] fmt   Formatted string to print.

   *

   * return   Number of printed characters.

   */

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

#endif

#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__)

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

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

/* TIMING                                                                     */

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

/**

 * @brief Time measurement type (in microseconds).

 */

#if (AMIROLLD_CFG_TIME_SIZE == 8)

  typedef uint8_t   apalTime_t;

#elif (AMIROLLD_CFG_TIME_SIZE == 16)

  typedef uint16_t  apalTime_t;

#elif (AMIROLLD_CFG_TIME_SIZE == 32)

  typedef uint32_t  apalTime_t;

#elif (AMIROLLD_CFG_TIME_SIZE == 64)

  typedef uint64_t  apalTime_t;

#else

  #error "AMIROLLD_CFG_TIME_SIZE must be 8, 16, 32 or 64"

#endif

#ifdef __cplusplus

extern "C" {

#endif

#if !defined(apalSleep) || defined(__DOXYGEN__)

  /**

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

   *

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

   */

  void apalSleep(apalTime_t us);

#endif

#ifdef __cplusplus

}

#endif

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

/* GPIO                                                                       */

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

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

/*

 * The following type must be defined by the implementation:

 *

 * apalGpio_t

 *   Type to represent a GPIO object.

 *   Is only used via pointer by the API.

 */

/**

 * @brief Status values to read/write a GPIO port.

 */

typedef uint8_t apalGpioState_t;