i2c-master.h

Go to the documentation of this file.

#ifndef DRIVER_I2C_MASTER_H
#define DRIVER_I2C_MASTER_H
/**********************************************************************/
/*
 * Copyright (c) 2013-2016, 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 Driver for I2C in nRF52 uC.
 *
 * @author KLO, Jetro AS
 * @author DT, Jetro AS
 */ /******************************************************************/

#include <hal/nrf_twi.h>
#include <core/work.h>
#include <lib/dlist.h>

/**
 * \defgroup i2c_master nRF52 I2C bus master driver
 * \ingroup nrf52
 * \{
 *
 * This I2C driver can be used for I2C0 and I2C1.
 *
 * First the driver setup the microcontroller to I2C master based on the i2c_t structure.
 * Then the driver does:
 * - Generates start condition
 * - Transmits slave address
 * - Transmits bytes (if any) from a given buffer
 * - Generates restart condition if bytes should be received, then receives bytes
 *   to a given buffer (ACK is sent for each received byte except for
 *   the last on where NACK is sent).
 * - Generates stop condition
 *
 * The driver returns true if communication OK, else false.
 *
 * While the I2C communication is in progress, the clock is locked and
 * energy mode EM1 is minimum required.
 */


/***********************************************************************
 * Global defines
***********************************************************************/

struct i2c_t;

/**
 * Asynchronous callback type
 *
 * @param I2c           Pointer to the I2C master instance object
 * @param ErrorMask     Bitmap of the possible bus error types, see enum i2c_error_t
 * @param Data          User data passed as I2cMasterAsync function parameter
 */
typedef void (* i2c_completion_callback_t)(const struct i2c_t *I2c,
                                           uint8_t ErrorMask,
                                           void *Data);

enum i2c_error_t
{
  I2C_BUS_HUNG_SDA_LOW  = (1 << 0),
  I2C_ADDRESS_NAK       = (1 << 1),
  I2C_DATA_NACK         = (1 << 2),
  I2C_UNEXPECTED_STOP   = (1 << 3),
};

/**
 * i2c_state_t structure holds clock lock state and other parameter used by the driver functions.
 * The structure will be set by the I2cMaster() function when called.
 *
 */
struct i2c_state_t
{
  i2c_completion_callback_t CompletionCallback; /**< Completion callback */
  void *CompletionCallbackData; /**< Completion callback data */
  uint32_t LastError;           /**< Error reason bitmap or 0 if a transfer finished successfully */
  struct dlist_t PendingI2cWorks; /**< List of works waiting for bus availability */
};

/**
 * i2c_t structure is used for configuration of I2C.
 * The structure must be initialized before the I2C driver may be used.
 *
 */
struct i2c_t
{
  NRF_TWIM_Type *Dev;         /**< Hardware interface */
  uint32_t IrqPriority;       /**< HW IRQ priority (see enum EVE_IRQ_PRIORITIES) */
  struct i2c_state_t *State;  /**< Pointer to state structure allocated in RAM */
  uint32_t Baudrate;          /**< Rate in bit/s */
  struct
  {
    uint8_t Scl;              /**< SCL pin location. */
    uint8_t Sda;              /**< SDA pin location */
  } Location;
};

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

/**********************************************************************/
/**
 * @brief Name:        I2cMasterInit\n
 * Initialize the driver. Function must be called before driver use.
 *
 * @param I2cMaster    Pointer to I2C module
 **********************************************************************/
extern void I2cMasterInit(const struct i2c_t *I2cMaster);

/**********************************************************************/
/**
 * @brief Name:        I2cBusReset\n
 * Reset the bus (clock through a bus hung)
 *
 * @param I2cMaster    Pointer to I2C module
 **********************************************************************/
extern void I2cBusReset(const struct i2c_t *I2cMaster);

/**********************************************************************/
/**
 * @brief Name:        I2cMasterAsync\n
 * Setup the microcontroller to I2C master based on the i2c_t structure (slave not supported).
 * Then the driver does:
 * - Generates start condition
 * - Transmits slave address
 * - Transmits from 0 til SrcCount bytes from the buffer SrcBuffer
 * - Generates restart condition if bytes should be received (DstCount > 0),
 *   then receives DstCount bytes to the buffer DstBuffer
 * - ACK is sent for each received byte except for the last on where NACK is sent.
 * - Generates stop condition
 * The transfer duration (number of bytes to transfer) must not exceed 50 ms.
 *
 * @param I2cMaster    Pointer to I2C module
 * @param SlaveAddress IIC slave address
 * @param SrcBuffer    Pointer to data to be written
 * @param SrcCount     Number of bytes to write
 * @param DstBuffer    Pointer to buffer to place read data
 * @param DstCount     Number of bytes to read
 * @param Callback     Completion callback
 * @param CallbackData Completion callback data
 * @return             true if communication started, else false
 **********************************************************************/
extern bool I2cMasterAsync(const struct i2c_t *I2cMaster,
                           uint8_t SlaveAddress,
                           const void *SrcBuffer,
                           uint8_t SrcCount,
                           void *DstBuffer,
                           uint8_t DstCount,
                           i2c_completion_callback_t Callback,
                           void *CallbackData);

/**********************************************************************/
/**
 * @brief Name:        I2cMasterSchedule\n
 * Schedule work when I2C bus becomes available.\n
 * In case the bus is already free, the work is scheduled immediately.
 *
 * @param I2cMaster    Pointer to I2C module
 * @param Work         Work to be scheduled immediately if I2C is free,
 *                     otherwise after I2C becomes free.
 **********************************************************************/
void I2cMasterSchedule(const struct i2c_t* I2cMaster, struct work_t* Work);

/**********************************************************************/
/**
 * @brief Name:        I2cMasterAsyncWait\n
 * Setup the microcontroller to I2C master based on the i2c_t structure (slave not supported).
 * Then the driver does:
 * - Generates start condition
 * - Transmits slave address
 * - Transmits from 0 til SrcCount bytes from the buffer SrcBuffer
 * - Generates restart condition if bytes should be received (DstCount > 0),
 *   then receives DstCount bytes to the buffer DstBuffer
 * - ACK is sent for each received byte except for the last on where NACK is sent.
 * - Generates stop condition
 * The transfer duration (number of bytes to transfer) must not exceed 50 ms.
 *
 * @param I2cMaster    Pointer to I2C module
 * @param SlaveAddress IIC slave address
 * @param SrcBuffer    Pointer to data to be written
 * @param SrcCount     Number of bytes to write
 * @param DstBuffer    Pointer to buffer to place read data
 * @param DstCount     Number of bytes to read
 * @param Callback     Completion callback
 * @param CallbackData Completion callback data
 * @param Work         If I2C is busy, the Work to be scheduled after I2C is free again.
 * @return             true if communication started, false if work will be scheduled.
 **********************************************************************/
inline bool I2cMasterAsyncWait(const struct i2c_t* I2cMaster, uint8_t SlaveAddress,
                        const void* SrcBuffer, uint8_t SrcCount,
                        void* DstBuffer, uint8_t DstCount,
                        i2c_completion_callback_t Callback, void* CallbackData,
                        struct work_t* Work)
{
  if (!I2cMasterAsync(I2cMaster, SlaveAddress, SrcBuffer, SrcCount,
                      DstBuffer, DstCount, Callback, CallbackData))
  {
    I2cMasterSchedule(I2cMaster, Work);
    return false;
  }
  return true;
}

/**********************************************************************/
/**
 * @brief Name:        I2cMaster\n
 * Setup the microcontroller to I2C master based on the i2c_t structure (slave not supported).
 * Then the driver does:
 * - Generates start condition
 * - Transmits slave address
 * - Transmits from 0 til SrcCount bytes from the buffer SrcBuffer
 * - Generates restart condition if bytes should be received (DstCount > 0),
 *   then receives DstCount bytes to the buffer DstBuffer
 * - ACK is sent for each received byte except for the last on where NACK is sent.
 * - Generates stop condition
 * The transfer duration (number of bytes to transfer) must not exceed 50 ms.
 *
 * @param I2cMaster    Pointer to I2C module
 * @param SlaveAddress IIC slave address
 * @param SrcBuffer    Pointer to data to be written
 * @param SrcCount     Number of bytes to write
 * @param DstBuffer    Pointer to buffer to place read data
 * @param DstCount     Number of bytes to read
 * @return             true if communication OK, else false
 **********************************************************************/
extern bool I2cMaster(const struct i2c_t *I2cMaster,
                      uint8_t SlaveAddress,
                      const void *SrcBuffer,
                      uint16_t SrcCount,
                      void *DstBuffer,
                      uint16_t DstCount);

/**********************************************************************/
/**
 * @brief Name:     I2cInterruptHandler\n
 * I2C master interrupt handler
 * Called from board.c at hardware interrupt context.
 *
 * @param I2cMaster       I2C parameters to be used
 ***********************************************************************/
extern void I2cMasterInterruptHandler(const struct i2c_t *I2cMaster);

/** @} */
/** \} */

#endif //DRIVER_I2C_MASTER_H