spi.h

Go to the documentation of this file.

#ifndef DRIVER_SPI_H
#define DRIVER_SPI_H
/**********************************************************************/
/*
 * Copyright (c) 2013-2017, 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 the MCU's SPI blocks.
 *
 * @author KLO, Jetro AS
 * @author DT, Jetro AS
 */ /******************************************************************/

#include <core/clk.h>
#include <lib/dlist.h>
#include <dev/data-buffer.h>
#include <dev/gpio.h>
#include <hal/nrf_spim.h>

/**
 * \defgroup spi nRF52 SPI bus master driver
 * \ingroup nrf52
 * \{
 *
 * This SPI driver provides interface to the MCU's SPI blocks.
 *
 * Functionality included:
 * - Init and disable of SPI
 * - Disable of chip-select
 * - Enable of chip-select, including setup of clock, bitrate and TX/RX using SpiCsEnable()
 * - With chip-select enabled, the following functions may be called:
 *   - SpiTransferAsync(), SpiRead(), SpiWrite(), SpiWriteRead(), SpiFlush(), SpiIsBusy() and SpiDisable()
 *
 * Currently only master mode is supported.
 */


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

/**
 * Enables fix for errata 58
 */
#define ERRATA_58

/**
 * Size of the synchronous FIFO emulation buffer
 */
#define SPI_SYNC_FIFO_DEPTH 4

/*extern*/ struct work_t;

/*forward*/ struct spi_t;

/**
 * SpiTransferSync flasg
 */
enum spi_transfer_flags_t
{
  SPI_TRANSFER_DEFAULT = 0,
  SPI_TRANSFER_CAN_SLEEP = (1 << 0),
};

/**
 * Uninitialized chip select structure
 */
#define SPI_CS_UNINITIALIZED ((struct spi_cs_t) { .CsUnInitialized = 1 })

/**
 * spi_mode_t defines mode 0-3.
 *
 */
enum spi_mode_t
{
  SPI_MODE0 = NRF_SPIM_MODE_0,  /**< SCK active high, sample on leading edge of clock. */
  SPI_MODE1 = NRF_SPIM_MODE_1,  /**< SCK active high, sample on trailing edge of clock. */
  SPI_MODE2 = NRF_SPIM_MODE_2,  /**< SCK active low, sample on leading edge of clock. */
  SPI_MODE3 = NRF_SPIM_MODE_3   /**< SCK active low, sample on trailing edge of clock. */
};

/**
 * spi_cs_t structure defines SPI and chip select setup.
 *
 */
struct spi_cs_t
{
  union {
    struct {
      uint32_t Mode : 2;      /**< SPI_MODE0, SPI_MODE1, SPI_MODE2, SPI_MODE3 */
      uint32_t Master : 1;    /**< TRUE if Master, else FALSE - only Master functionality is implemented */
      uint32_t MsbFirst : 1;  /**< TRUE if MSB first, else FALSE */
      uint32_t MosiPin : GPIO_PIN_ID_WIDTH;   /**< MOSI pin number */
      uint32_t MisoPin : GPIO_PIN_ID_WIDTH;   /**< MISO pin number */
      uint32_t ClkPin : GPIO_PIN_ID_WIDTH;    /**< CLK pin number */
      uint32_t CsPin : GPIO_PIN_ID_WIDTH;     /**< CSn pin number */
      uint32_t CsActiveHigh : 1; /**< TRUE if CSn is active high, FALSE otherwise */
      uint32_t CsUnInitialized : 1;  /**< Internal: Set to TRUE in SpiInit */
    };
    uint32_t Raw;
  };
};

/**
 * The callback is called at completion of an asynchronous transfer.
 *
 * @param Spi        SPI to be used
 * @param CallbackData User-defined data
 */
typedef void (*spi_async_callback_t)(const struct spi_t *Spi, void *CallbackData);

/**
 * spi_state_t structure holds internal state of the SPI driver.
 *
 */
struct spi_state_t
{
  struct spi_cs_t ChipSelect; /**< Active chip select */
  struct data_buffer_t RxBuffer; /**< Receive buffer for asynchronous transfers */
  struct data_buffer_t TxBuffer; /**< Transmit buffer for asynchronous transfers */
  spi_async_callback_t Callback; /**< Asynchronous callback */
  void *CallbackData;         /**< Asynchronous callback data */
  struct dlist_t PendingCsWorks; /**< List of works waiting for the block availability */
  uint8_t Fifo[SPI_SYNC_FIFO_DEPTH]; /**< Synchronous FIFO emulation */
  uint8_t FifoTxUsed;        /**< Amount of bytes in the TX FIFO */
  uint8_t FifoRxUsed;        /**< Amount of bytes in the RX FIFO */
  uint8_t FifoPos;           /**< Position of the first byte in the FIFO */
  volatile bool Busy;        /**< SPI is busy with a transfer */
#ifdef ERRATA_58
  bool Errata58;             /**< Errata 58 workarownd is active */
#endif /* ERRATA_58 */
};

/**
 * spi_t structure is used for configuration of SPI.
 * The structure must be initialized before the SPI driver may be used.
 *
 */
struct spi_t
{
  NRF_SPIM_Type *Dev;         /**< Pointer to the physical hardware interface */
  uint32_t IrqPriority;       /**< HW IRQ priority (see enum EVE_IRQ_PRIORITIES) */
  struct spi_state_t *State;  /**< Pointer to the mutable device state */
  uint32_t DefaultBaudrate;   /**< Default baudrate in bit/s (must be <= peripheral clock / 2) */
#ifdef ERRATA_58
  uint8_t Errata58_PPI_ID;    /**< PPI ID used internally for errata 58 workarownd */
  uint8_t Errata58_GPIOTE_ID; /**< GPIOTE ID used internally for errata 58 workarownd */
#endif /* ERRATA_58 */
};

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

/**********************************************************************/
/**
 * @brief Name:     SpiInit\n
 * Initializes SPI based on selected device.
 * Master operation: Baudrate is limited to 0.5*peripheral clock.
 * Slave operation: Not implemented.
 * Called from main program level.
 *
 * @param Spi       SPI parameters to be used
 ***********************************************************************/
extern void SpiInit(const struct spi_t *Spi);

/**********************************************************************/
/**
 * @brief Name:     SpiDisable\n
 * Disables SPI based on selected device.
 * Called from main program level.
 *
 * @param Spi       SPI parameters to be used
 ***********************************************************************/
extern void SpiDisable(const struct spi_t *Spi);

/**********************************************************************/
/**
 * @brief Name:     SpiRead\n
 * WARNING: SpiWrite() must be called prior to this function.
 * Waits for data received in RX FIFO.
 *
 * @param Spi       SPI to be used
 * @return          Received data
 ***********************************************************************/
extern uint8_t SpiRead(const struct spi_t *Spi);

/**********************************************************************/
/**
 * @brief Name:      SpiWrite\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Waits for empty transmit buffer, then sends 1 byte.
 *
 * @param Spi        SPI to be used
 * @param DataToSend Data to be sent
 ***********************************************************************/
extern void SpiWrite(const struct spi_t *Spi, uint8_t DataToSend);

/**********************************************************************/
/**
 * @brief Name:      SpiWriteRead\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Waits for empty transmit buffer, sends 1 byte and waits for data
 * received in RX FIFO.
 *
 * @param Spi        SPI to be used
 * @param DataToSend Data to be sent
 * @return           Received data
 ***********************************************************************/
extern uint8_t SpiWriteRead(const struct spi_t *Spi, uint8_t DataToSend);

/**********************************************************************/
/**
 * @brief Name:      SpiTransferAsync\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Starts asynchronous data transfer (both transmit and receive).
 *
 * @param Spi        SPI to be used
 * @param TxBuffer   Transmit buffer
 * @param TxLength   Amount of bytes to be sent
 * @param RxBuffer   Receive buffer
 * @param RxLength   Amount of bytes to be received
 * @param Callback   Pointer to the function to be called when transfer is finished
 * @param CallbackData User-defined data for the callback
 ***********************************************************************/
extern void SpiTransferAsync(const struct spi_t *Spi,
    const void *TxBuffer, uint32_t TxLength,
          void *RxBuffer, uint32_t RxLength,
    spi_async_callback_t Callback, void *CallbackData);

/**********************************************************************/
/**
 * @brief Name:      SpiTransferSync\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Does synchronous data transfer (both transmit and receive).
 *
 * @param Spi        SPI to be used
 * @param TxBuffer   Transmit buffer
 * @param TxLength   Amount of bytes to be sent
 * @param RxBuffer   Receive buffer
 * @param RxLength   Amount of bytes to be received
 * @param Flags      Flags of the transfer, bit combination of spi_transfer_flags_t
 ***********************************************************************/
extern void SpiTransferSync(const struct spi_t *Spi,
    const void *TxBuffer, uint32_t TxLength,
          void *RxBuffer, uint32_t RxLength,
    uint32_t Flags);

/**********************************************************************/
/**
 * @brief Name:     SpiFlush\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Waits for any previously transmission to be complete, then flushes RX FIFO.
 *
 * @param Spi       SPI to be used
 ***********************************************************************/
extern void SpiFlush(const struct spi_t *Spi);

/**********************************************************************/
/**
 * @brief Name:     SpiIsBusy\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Testes if transmitter is busy, i.e. if data in transmit buffer and/or shift register.
 *
 * @param Spi       SPI to be used
 * @return          true if busy, else false
 ***********************************************************************/
static inline bool SpiIsBusy(const struct spi_t *Spi)
{
  struct spi_state_t *State = Spi->State;
  return State->Busy;
}

/**********************************************************************/
/**
 * @brief Name:     SpiCsInit\n
 * Initializes SPI chip select instance.
 * Called once from main program level before first SpiCsEnable() use.
 *
 * @param ChipSelect   CS parameters to be used
 * @param MaxBaudrate  Maximal baudrate for this CS
 ***********************************************************************/
extern void SpiCsInit(struct spi_cs_t ChipSelect, uint32_t MaxBaudrate);

/**********************************************************************/
/**
 * @brief Name:     SpiCsEnable\n
 * Enables peripheral clock for USART, updates SPI setting according to
 * ChipSelect, and activates chip select pin.
 *
 * @param Spi       SPI to be used
 * @param ChipSelect Chip select structure
 * @param Baudrate  If Baudrate = 0, default baudrate is used
 * @return          false if SPI is already in use, else true
 ***********************************************************************/
extern bool SpiCsEnable(const struct spi_t *Spi, struct spi_cs_t ChipSelect, uint32_t Baudrate);

/**********************************************************************/
/**
 * @brief Name:     SpiCsRegisterWait\n
 * Registers a work to be executed when the SPI block becomes available.
 *
 * @param Spi       SPI to be used
 * @param Work      The work item will be scheduled as soon as the SPI block
 *                  becomes available.
 ***********************************************************************/
extern void SpiCsRegisterWait(const struct spi_t *Spi, struct work_t *Work);

/**********************************************************************/
/**
 * @brief Name:     SpiCsWait\n
 * Enables peripheral clock for USART, updates SPI setting according to
 * ChipSelect, and activates chip select pin.
 *
 * @param Spi       SPI to be used
 * @param ChipSelect Chip select structure
 * @param Baudrate  If Baudrate = 0, default baudrate is used
 * @param Work      If SPI is already in use, the work item will be scheduled
 *                  as soon as it becomes available again.
 * @return          false if SPI is already in use, else true
 ***********************************************************************/
static inline bool __attribute__((warn_unused_result))
    SpiCsWait(const struct spi_t *Spi, struct spi_cs_t ChipSelect, uint32_t Baudrate, struct work_t *Work)
{
  bool Ret = SpiCsEnable(Spi, ChipSelect, Baudrate);
  if (!Ret)
    SpiCsRegisterWait(Spi, Work);
  return Ret;
}

/**********************************************************************/
/**
 * @brief Name:     SpiCsDisable\n
 * Waits for any ongoing transmission to end, flush RX FIFO, disables
 * chip select pin and disables peripheral clock for USART.
 *
 * @param Spi       SPI to be used
 * @param ChipSelect Chip select structure
 ***********************************************************************/
extern void SpiCsDisable(const struct spi_t *Spi, struct spi_cs_t ChipSelect);

/**********************************************************************/
/**
 * @brief Name:     SpiCsIsActive\n
 * Checks that the given chip select is active.
 *
 * @param Spi       SPI to be used
 * @param ChipSelect Chip select structure
 * @return          true if the chip select is active, false otherwise
 ***********************************************************************/
static inline bool SpiCsIsActive(const struct spi_t *Spi, struct spi_cs_t ChipSelect)
{
  return (Spi->State->ChipSelect.Raw == ChipSelect.Raw);
}

/**********************************************************************/
/**
 * @brief Name:     SpiInterruptHandler\n
 * SPI interrupt handler
 * Called from board.c at hardware interrupt context.
 *
 * @param Spi       SPI parameters to be used
 ***********************************************************************/
extern void SpiInterruptHandler(const struct spi_t *Spi);

#if 0
/**********************************************************************/
/**
 * @brief Name:     SpiReadFast\n
 * WARNING: SpiWriteFast() must be called prior to this function.
 * Waits for data received in RX FIFO.
 *
 * @param Spi       SPI to be used
 * @return          Received data
 ***********************************************************************/
static inline uint8_t SpiReadFast(const struct spi_t *Spi)
{
  register NRF_SPI_Type *Usart = Spi->Usart;

  while (Usart->EVENTS_READY == 0);
  Usart->EVENTS_READY = 0;
  return nrf_spi_rxd_get(Usart);
}

/**********************************************************************/
/**
 * @brief Name:      SpiWriteFast\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Sends 1 byte without waiting for available space in FIFO.
 * Caller must take case for the TX FIFO status.
 *
 * @param Spi        SPI to be used
 * @param DataToSend Data to be sent
 ***********************************************************************/
static inline void SpiWriteFast(const struct spi_t *Spi, uint8_t DataToSend)
{
  register NRF_SPI_Type *Usart = Spi->Usart;

  nrf_spi_txd_set(Usart, DataToSend);
}

/**********************************************************************/
/**
 * @brief Name:      SpiWriteReadFast\n
 * WARNING: SpiCsEnable() must be called prior to this function.
 * Sends 1 byte without waiting for available space in FIFO.
 * Caller must take case for the TX FIFO status.
 * Waits for data received in RX FIFO.
 *
 * @param Spi        SPI to be used
 * @param DataToSend Data to be sent
 * @return           Received data
 ***********************************************************************/
static inline uint8_t SpiWriteReadFast(const struct spi_t *Spi, uint8_t DataToSend)
{
  register NRF_SPI_Type *Usart = Spi->Usart;

  nrf_spi_txd_set(Usart, DataToSend);

  while (Usart->EVENTS_READY == 0);
  Usart->EVENTS_READY = 0;
  return nrf_spi_rxd_get(Usart);
}
#endif
/** \} */

/** \} */

#endif //DRIVER_SPI_H