gpio-ext.h

Go to the documentation of this file.

#ifndef DRIVER_GPIO_EXT_H
#define DRIVER_GPIO_EXT_H
/**********************************************************************/
/*
 * Copyright (c) 2015, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief Abstract IO extender driver.
 *
 * @author SE, Jetro AS
 */ /******************************************************************/

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <lib/assert.h>
#include <dev/gpio.h>
#include <core/atomic.h>
#include <app_util_platform.h>
#include <dev/irq.h>

/**
 * \defgroup gpio_ext Extended GPIO driver
 * \ingroup abstract
 * \{
 */

/***********************************************************************
 * Global defines
 **********************************************************************/
#define GPIO_EXT_MAXPINS          16

#ifndef DRIVER_PORT_EXT_INIT_TABLE
  #error DRIVER_PORT_EXT_INIT_TABLE must point to a header file with pin init values
#endif
#define PINDEF(name, pin, mode, value, drive)   name = pin,
enum pins_ext_t {
  #include DRIVER_PORT_EXT_INIT_TABLE
};
#undef PINDEF

/**
 * GPIO driver SPI/I2C bus operation statuse
 */
enum gpio_ext_status_t
{
  GPIO_EXT_STATUS_OK         = 0, //!< Operation completed successfully
  GPIO_EXT_STATUS_COMM_ERROR = 1, //!< SPI/I2C bus error
};

/**
 * Pin direction setting
 */
enum gpio_ext_pin_dir_t
{
  DIR_UNCHANGED  = 0,  //!< Do not touch pin direction setting (leave as is)
  DIR_IN         = 1,  //!< Set pin as input
  DIR_OUT        = 2,  //!< Set pin as output
};

/**
 * Pin pullup / pulldown setting
 */
enum gpio_ext_pin_pull_t
{
  PULL_UNCHANGED  = 0, //!< Do not touch pin pullup / pulldown setting (leave as is)
  PULL_NONE       = 1, //!< Disconnect pin pullup / pulldown
  PULL_UP         = 2, //!< Pullup the pin
  PULL_DOWN       = 3, //!< Pulldown the pin
};

struct gpio_ext_t;

/**
 * GPIO driver run-time state
 */
struct gpio_ext_state_t
{
  uint16_t OutputValues;      ///< Last values set for output
  uint16_t InputValues;       ///< Last read input values
  uint16_t Direction;         ///< Current direction state (0 = in, 1 = out)
  uint16_t PullSelect;        ///< Current pullup/pulldown state (0 = pulldown, 1 = pullup)
  uint16_t PullEnable;        ///< Current pull resistor enabled state (0 = off, 1 = on)
  uint16_t InterruptStatus;   ///< Pending interrupt status
  uint16_t InterruptMask;     ///< Internal interrupt bit mask (0 = disabled, 1 = enabled)
  enum gpio_ext_status_t Status;
};

/**
 * PIN initial state configuration
 */
struct gpio_ext_init_pin_t
{
  uint8_t Value;            //!< Initial pin value
  enum gpio_mode_t Mode;    //!< Initial pin direction / pullup / pulldown configuration
  uint8_t Drive;            //!< Pin drive force in %%
};

/**********************************************************************/
/**
 * @brief Virtual function initializes pins of an gpio expander to
 *        default values based on DRIVER_PORT_EXT_INIT_TABLE
 **********************************************************************/
typedef void     (*gpio_ext_init_t)   (const struct gpio_ext_t* GpioExt);

/**********************************************************************/
/**
 * @brief Virtual function reads from gpio expander port
 **********************************************************************/
typedef uint16_t (*gpio_ext_inport_t) (const struct gpio_ext_t* GpioExt);

/**********************************************************************/
/**
 * @brief Virtual function writes to gpio expander port / pin direction
 *        register / pull select register / pull enable register /
 *        interrupt enable register / latch enable register
 **********************************************************************/
typedef void     (*gpio_ext_outport_t)(const struct gpio_ext_t* GpioExt, uint16_t Value);

/**********************************************************************/
/**
 * @brief Virtual function sets drive force to gpio expander pins
 **********************************************************************/
typedef void     (*gpio_ext_setdrive_t)(const struct gpio_ext_t* GpioExt, uint8_t Values[]);

/**
 * GPIO driver virtual function table
 */
struct gpio_ext_api_t
{
  gpio_ext_init_t                 GpioExtInit;          //!< Function to initialize GPIO expander chip
  gpio_ext_init_t                 GpioExtDisable;       //!< Function to deinitialize GPIO expander chip
  gpio_ext_inport_t               GpioExtInPort;        //!< Function to read from GPIO expander port
  gpio_ext_outport_t              GpioExtOutPort;       //!< Function to write to GPIO expander port
  gpio_ext_outport_t              GpioExtSetDirection;  //!< Function to set GPIO expander pins direction
  gpio_ext_outport_t              GpioExtSetPullSelect; //!< Function to set GPIO expander pullup/pulldown
  gpio_ext_outport_t              GpioExtSetPullEnable; //!< Function to enable/disable GPIO expander pullup/pulldowen
  gpio_ext_outport_t              GpioExtSetInterrupts; //!< Function to enable/disable GPIO expander interrupts
  gpio_ext_setdrive_t             GpioExtSetDrive;      //!< Function to set GPIO expander drive force
  gpio_ext_outport_t              GpioExtSetLatch;      //!< Function to enable/disable GPIO expander interrupt latch
};

/**
 * GPIO driver configuration data
 */
struct gpio_ext_t
{
  const void* Impl;                               //!< Device specific configuration data
  struct gpio_ext_state_t* State;                 //!< Address to struct with RAM variables used by the driver
  uint8_t PinsNum;                                //!< Total number of pins on the port
  uint16_t PortMask;                              //!< Bitmask of all the pins on the port (f.ex. 0xFF for 8-bit port, 0xFFFF for 16-bit)
  const struct gpio_ext_init_pin_t PortsInit[16]; //!< Init values for each pin
  const struct gpio_ext_api_t* Func;              //!< Virtual functions table
};

#define GPIO_EXT_VCALL(GpioExt, Fn) (GpioExt)->Func->Fn

extern void GpioExtPortWriteImpl(const struct gpio_ext_t* GpioExt,
                                 uint16_t* StoredValue, uint16_t DesiredValue,
                                 uint16_t Mask, gpio_ext_outport_t Func);

extern uint16_t GpioExtPortReadImpl(const struct gpio_ext_t* GpioExt,
                                    bool TriggerInterrupt);

extern void IrqTriggerExternal(void);

/**
  * @name Functions called from application programs
  * @{
  */

/**
 * @brief Initialize IO expander driver and chip.
 *
 * @param GpioExt      Parameters for the IO port expander to be used
 */
extern void GpioExtInit(const struct gpio_ext_t* GpioExt);

/**
 * @brief Write 16-bits data to the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Value  Data to be written to IO expander ports
 * @param Mask   Mask of pins in the port to be written
 */
static inline void GpioExtPortWrite(const struct gpio_ext_t* GpioExt,
                                    uint16_t Value, uint16_t Mask)
{
  uint16_t DesiredValue = Value & Mask;
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->OutputValues, DesiredValue,
                      Mask, GpioExt->Func->GpioExtOutPort);
}

/**
 * @brief Set bits by mask in the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Mask     Mask of pins in the port to be written
 */
static inline void GpioExtPortSet(const struct gpio_ext_t* GpioExt, uint16_t Mask)
{
  GpioExtPortWrite(GpioExt, 0xFFFF, Mask);
}

/**
 * @brief Clear bits by mask in the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Mask     Mask of pins in the port to be written
 */
static inline void GpioExtPortClear(const struct gpio_ext_t* GpioExt, uint16_t Mask)
{
  GpioExtPortWrite(GpioExt, 0x0000, Mask);
}

/**
 * @brief Invert bits by mask in the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Mask     Mask of pins in the port to be written
 */
static inline void GpioExtPortToggle(const struct gpio_ext_t* GpioExt, uint16_t Mask)
{
  uint16_t DesiredValue = atomic_xor16(&GpioExt->State->OutputValues, Mask) & Mask;
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->OutputValues, DesiredValue,
                      Mask, GpioExt->Func->GpioExtOutPort);
}

/**
 * @brief Set/clear 1 pin in the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Pin      Pin number to set/clear
 * @param Value    0 clears the pin, any other value sets it to 1
 */
static inline void GpioExtPinWrite(const struct gpio_ext_t* GpioExt, uint16_t Pin, uint16_t Value)
{
  uint16_t Mask = (1 << Pin);
  Value = Value ? Mask : 0;
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->OutputValues, Value,
                      Mask, GpioExt->Func->GpioExtOutPort);
}

/**
 * @brief Set 1 pin in the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Pin      Pin number to set
 */
static inline void GpioExtPinSet(const struct gpio_ext_t* GpioExt, uint16_t Pin)
{
  uint16_t Mask = (1 << Pin);
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->OutputValues, Mask, Mask,
                      GpioExt->Func->GpioExtOutPort);
}

/**
 * @brief Clear 1 pin in the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Pin      Pin number to clear
 */
static inline void GpioExtPinClear(const struct gpio_ext_t* GpioExt, uint16_t Pin)
{
  uint16_t Mask = (1 << Pin);
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->OutputValues, 0, Mask,
                      GpioExt->Func->GpioExtOutPort);
}

/**
 * @brief Invert 1 pin in the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Pin      Pin number to toggle
 */
static inline void GpioExtPinToggle(const struct gpio_ext_t* GpioExt, uint16_t Pin)
{
  uint16_t Mask = (1 << Pin);
  uint16_t Value = atomic_xor16(&GpioExt->State->OutputValues, Mask) & Mask;
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->OutputValues, Value, Mask,
                      GpioExt->Func->GpioExtOutPort);
}

/**
 * @brief Read all the pins from the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @return         Port value
 */
static inline uint16_t GpioExtPortRead(const struct gpio_ext_t* GpioExt)
{
  return GpioExtPortReadImpl(GpioExt, true);
}

/**
 * @brief Read a pin value from the GPIO port.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @param Pin      Global pin number to be read
 * @return         Pin value
 */
static inline uint8_t GpioExtPinRead(const struct gpio_ext_t* GpioExt, uint16_t Pin)
{
  uint16_t Port = GpioExtPortRead(GpioExt);
  return (Port & (1 << Pin)) ? 1 : 0;
}

/**
 * @brief Set IO expander ports to input or output.
 *
 * @param GpioExt     Parameters for the IO port expander to be used
 * @param Direction   0 = input, 1 = output
 * @param PullSelect  0 = pulldown, 1 = pullup
 * @param PullEnable  0 = no pull, 1 = pullup/pulldown
 * @param Mask        Mask of pins in the port to be changed
 */
extern void GpioExtPortSetup(const struct gpio_ext_t* GpioExt,
                             uint16_t Direction, uint16_t PullSelect,
                             uint16_t PullEnable, uint16_t Mask);


static inline uint16_t GpioExtInterruptsClear(const struct gpio_ext_t* GpioExt, uint16_t Mask)
{
  /* Just set GpioExt->State->InterruptStatus, not interesting in port values */
  GpioExtPortReadImpl(GpioExt, false);
  uint16_t InterruptStatus = (GpioExt->State->InterruptStatus &
                              GpioExt->State->InterruptMask) &
                              ~(GpioExt->State->Direction);
  GpioExt->State->InterruptStatus = InterruptStatus & ~Mask;
  return (InterruptStatus);
}

static inline uint16_t GpioExtInterruptsRead(const struct gpio_ext_t* GpioExt)
{
  uint16_t InterruptStatus = GpioExtInterruptsClear(GpioExt, 0xFFFF);
  GpioExt->State->InterruptStatus &= ~InterruptStatus;
  return (InterruptStatus);
}

static inline void GpioExtInterruptsEnable(const struct gpio_ext_t* GpioExt, uint16_t Mask)
{
  uint16_t InterruptMask = GpioExt->State->InterruptMask | Mask;
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->InterruptMask, InterruptMask,
                      Mask, GpioExt->Func->GpioExtSetInterrupts);
  if ((GpioExt->State->InterruptMask & GpioExt->State->InterruptStatus) &
      ~GpioExt->State->Direction)
    IrqTriggerExternal();
}

static inline void GpioExtInterruptsDisable(const struct gpio_ext_t* GpioExt, uint16_t Mask)
{
  uint16_t InterruptMask = GpioExt->State->InterruptMask & ~Mask;
  GpioExtPortWriteImpl(GpioExt, &GpioExt->State->InterruptMask, InterruptMask,
                      Mask, GpioExt->Func->GpioExtSetInterrupts);
}

static inline void GpioExtSetDrive(const struct gpio_ext_t* GpioExt, uint8_t Values[])
{
  GPIO_EXT_VCALL(GpioExt, GpioExtSetDrive)(GpioExt, Values);
}

static inline void GpioExtSetLatch(const struct gpio_ext_t* GpioExt, uint16_t Mask)
{
  GPIO_EXT_VCALL(GpioExt, GpioExtSetLatch)(GpioExt, Mask);
}

/**
 * @brief Check status of GpioExt operations and reset status to GPIO_EXT_STATUS_OK.
 *
 * @param GpioExt  Parameters for the IO port expander to be used
 * @return         GPIO_EXT_STATUS_OK if there were no errors since the last check,
 *                 errorcode otherwise.
 */
static inline uint8_t GpioExtCheckStatus(const struct gpio_ext_t* GpioExt)
{
  uint8_t ret = GpioExt->State->Status;
  GpioExt->State->Status = GPIO_EXT_STATUS_OK;
  return ret;
}

/** @} */

/** \} gpio_ext */

#endif //DRIVER_GPIO_EXT_H