SPI.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2018, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  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.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT OWNER OR
 * CONTRIBUTORS 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.
 */
/*!*****************************************************************************
 *  @file       SPI.h
 *
 *  @brief      SPI driver interface
 *
 *  The SPI driver interface provides device independent APIs, data types,
 *  and macros. The SPI header file should be included in an application as
 *  follows:
 *  @code
 *  #include <ti/drivers/SPI.h>
 *  @endcode
 *
 *  # Overview #
 *  The Serial Peripheral Interface (SPI) driver is a generic, full-duplex
 *  driver that transmits and receives data on a SPI bus.  SPI is sometimes
 *  called SSI (Synchronous Serial Interface).
 *  The SPI protocol defines the format of a data transfer over the SPI bus,
 *  but it leaves flow control, data formatting, and handshaking mechanisms
 *  to higher-level software layers.
 *
 *  The APIs in this driver serve as an interface to a typical RTOS
 *  application.  Its purpose is to redirect the SPI APIs to specific
 *  driver implementations which are specified using a pointer to a
 *  #SPI_FxnTable.  The specific SPI implementations are responsible for
 *  creating all the RTOS specific primitives to allow for thread-safe
 *  operation.
 *
 *  The SPI driver operates on some key definitions and assumptions:
 *  - The driver operates transparently from the chip select. Some SPI
 *    controllers feature a hardware chip select to assert SPI slave
 *    peripherals. See the specific peripheral implementations on chip
 *    select requirements.
 *
 *  - The SPI protocol does not account for a built-in handshaking mechanism
 *    and neither does this SPI driver. Therefore, when operating in
 *    ::SPI_SLAVE mode, the application must provide such a mechanism to
 *    ensure that the SPI slave is ready for the SPI master. The SPI slave
 *    must call SPI_transfer() *before* the SPI master starts transmitting.
 *    Some example application mechanisms could include:
 *    - Timed delays on the SPI master to guarantee the SPI slave is ready
 *      for a SPI transaction.
 *    - A form of GPIO flow control from the slave to the SPI master to notify
 *      the master when ready.
 *
 *  # Usage #
 *
 *  To use the SPI driver to send data over the SPI bus, the application
 *  calls the following APIs:
 *    - SPI_init(): Initialize the SPI driver.
 *    - SPI_Params_init():  Initialize a #SPI_Params structure with default
 *      values.  Then change the parameters from non-default values as
 *      needed.
 *    - SPI_open():  Open an instance of the SPI driver, passing the
 *      initialized parameters, or NULL, and an index (described later).
 *    - SPI_transfer():  Transmit/receive data.  This function takes a
 *      #SPI_Transaction argument that specifies buffers for data to be
 *      transmitted/received.
 *    - SPI_close():  De-initialize the SPI instance.
 *
 *  The following code example opens a SPI instance as a master SPI,
 *  and issues a transaction.
 *
 *  @code
 *  SPI_Handle      spi;
 *  SPI_Params      spiParams;
 *  SPI_Transaction spiTransaction;
 *  uint8_t         transmitBuffer[MSGSIZE];
 *  uint8_t         receiveBuffer[MSGSIZE];
 *  bool            transferOK;
 *
 *  SPI_init();  // Initialize the SPI driver
 *
 *  SPI_Params_init(&spiParams);  // Initialize SPI parameters
 *  spiParams.dataSize = 8;       // 8-bit data size
 *
 *  spi = SPI_open(Board_SPI0, &spiParams);
 *  if (spi == NULL) {
 *      while (1);  // SPI_open() failed
 *  }
 *
 *  // Fill in transmitBuffer
 *
 *  spiTransaction.count = MSGSIZE;
 *  spiTransaction.txBuf = (void *)transmitBuffer;
 *  spiTransaction.rxBuf = (void *)receiveBuffer;
 *
 *  transferOK = SPI_transfer(spi, &spiTransaction);
 *  if (!transferOK) {
 *      // Error in SPI or transfer already in progress.
 *      while (1);
 *  }
 *  @endcode
 *
 *  More details on usage are provided in the following subsections.
 *
 *  ### SPI Driver Configuration #
 *
 *  In order to use the SPI APIs, the application is required
 *  to provide device-specific SPI configuration in the Board.c file.
 *  The SPI driver interface defines a configuration data structure:
 *
 *  @code
 *  typedef struct SPI_Config_ {
 *      SPI_FxnTable  const    *fxnTablePtr;
 *      void                   *object;
 *      void          const    *hwAttrs;
 *  } SPI_Config;
 *  @endcode
 *
 *  The application must declare an array of SPI_Config elements, named
 *  SPI_config[].  Each element of SPI_config[] must be populated with
 *  pointers to a device specific SPI driver implementation's function
 *  table, driver object, and hardware attributes.  The hardware attributes
 *  define properties such as the SPI peripheral's base address, and
 *  the MOSI and MISO pins.  Each element in SPI_config[] corresponds to
 *  a SPI instance, and none of the elements should have NULL pointers.
 *  There is no correlation between the index and the
 *  peripheral designation (such as SPI0 or SPI1).  For example, it is
 *  possible to use SPI_config[0] for SPI1.
 *
 *  Because the SPI configuration is very device dependent, you will need to
 *  check the doxygen for the device specific SPI implementation.  There you
 *  will find a description of the SPI hardware attributes.  Please also
 *  refer to the Board.c file of any of your examples to see the SPI
 *  configuration.
 *
 *  ### Initializing the SPI Driver #
 *
 *  SPI_init() must be called before any other SPI APIs.  This function
 *  iterates through the elements of the SPI_config[] array, calling
 *  the element's device implementation SPI initialization function.
 *
 *  ### SPI Parameters
 *
 *  The #SPI_Params structure is passed to the SPI_open() call.  If NULL
 *  is passed for the parameters, SPI_open() uses default parameters.
 *  A #SPI_Params structure is initialized with default values by passing
 *  it to SPI_Params_init().
 *  Some of the SPI parameters are described below.  To see brief descriptions
 *  of all the parameters, see #SPI_Params.
 *
 *  #### SPI Mode
 *  The SPI driver operates in both SPI master and SPI slave modes.
 *  Logically, the implementation is identical, however the difference
 *  between these two modes is driven by hardware.  The default mode is
 *  ::SPI_MASTER, but can be set to slave mode by setting ::SPI_Params.mode
 *  to ::SPI_SLAVE in the parameters passed to SPI_open().  See
 *  <a href="#Master_Slave_Modes"> Master/Slave Modes</a> for further
 *  details.
 *
 *  #### SPI Transfer Mode
 *  The SPI driver supports two transfer modes of operation: blocking and
 *  callback. The transfer mode is determined by the transferMode parameter
 *  in the SPI_Params data structure. The SPI driver
 *  defaults to blocking mode, if the application does not set it.
 *  Once a SPI driver is opened, the only way to change the operation mode
 *  is to close and re-open the SPI instance with the new transfer mode.
 *
 *  In blocking mode, a task's code execution is blocked until a SPI
 *  transaction has completed or a timeout has occurred. This ensures
 *  that only one SPI transfer operates at a given time. Other tasks requesting
 *  SPI transfers while a transfer is currently taking place will receive
 *  a FALSE return value.  If a timeout occurs the transfer is canceled, the
 *  task is unblocked & will receive a FALSE return value. The transaction
 *  count field will have the amount of frames which were transferred
 *  successfully before the timeout.  In blocking mode, transfers cannot be
 *  performed in software or hardware ISR context.
 *
 *  In callback mode, a SPI transaction functions asynchronously, which
 *  means that it does not block code execution. After a SPI transaction
 *  has been completed, the SPI driver calls a user-provided hook function.
 *  Callback mode is supported in the execution context of tasks and
 *  hardware interrupt routines.  However, if a SPI transaction is
 *  requested while a transaction is taking place, SPI_transfer() returns
 *  FALSE.
 *
 *  #### SPI Frame Formats and Data Size
 *  The SPI driver can configure the device's SPI peripheral to transfer
 *  data in several SPI format options: SPI (with various polarity and phase
 *  settings), TI, and Micro-wire. The frame format is set with
 *  SPI_Params.frameFormat. Some SPI implementations may not support all frame
 *  formats & the SPI driver will fail to opened.  Refer to the device specific
 *  implementation documentation for details on which frame formats are
 *  supported.
 *
 *  The smallest single unit of data transmitted onto the SPI bus is called
 *  a SPI frame and is of size SPI_Params.dataSize.  A series of SPI frames
 *  transmitted/received on a SPI bus is known as a SPI transaction.
 *
 *  ### Opening the SPI Driver #
 *  After initializing the SPI driver by calling SPI_init(), the application
 *  can open a SPI instance by calling SPI_open().  This function
 *  takes an index into the SPI_config[] array, and a SPI parameters data
 *  structure.   The SPI instance is specified by the index of the SPI in
 *  SPI_config[].  Only one SPI index can be used at a time;
 *  calling SPI_open() a second time with the same index previously
 *  passed to SPI_open() will result in an error.  You can,
 *  though, re-use the index if the instance is closed via SPI_close().
 *
 *  If no SPI_Params structure is passed to SPI_open(), default values are
 *  used. If the open call is successful, it returns a non-NULL value.
 *
 *  Example opening a SPI driver instance in blocking mode:
 *  @code
 *  SPI_Handle  spi;
 *  SPI_Params  spiParams;
 *
 *  SPI_Params_init(&spiParams);
 *  spiParams.transferMode = SPI_MODE_BLOCKING;
 *  spi = SPI_open(Board_SPI0, &spiParams);
 *
 *  if (spi == NULL) {
 *      // Error opening SPI
 *      while(1);
 *  }
 *  @endcode
 *
 *  Example opening a SPI driver instance in callback mode:
 *  @code
 *  SPI_Handle spi;
 *  SPI_Params spiParams;
 *
 *  SPI_Params_init(&spiParams);
 *  spiParams.transferMode = SPI_MODE_CALLBACK;
 *  spiParams.transferCallbackFxn = UserCallbackFxn;
 *
 *  spi = SPI_open(Board_SPI0, &spiParams);
 *  if (spi == NULL) {
 *      // Error opening SPI
 *      while (1);
 *  }
 *  @endcode
 *
 *
 *  ### SPI Transactions #
 *
 *  A SPI transaction consists of a series of SPI frames
 *  transmitted/received on a SPI bus.  A SPI transaction is performed
 *  using SPI_transfer(). SPI_transfer() accepts a pointer to a
 *  #SPI_Transaction structure that dictates the quantity of data to be
 *  sent and received.
 *  The SPI_Transaction.txBuf and SPI_Transaction.rxBuf are both pointers
 *  to data buffers.  If txBuf is NULL, the driver sends SPI frames with all
 *  data set to the default value specified in the hardware attributes. If
 *  rxBuf is NULL, the driver discards all SPI frames received. SPI_transfer()
 *  of a SPI transaction is performed atomically.
 *
 *  @warning The use of NULL as a sentinel txBuf or rxBuf value to determine
 *  whether the SPI transaction includes a tx or rx component implies
 *  that it is not possible to perform a transmit or receive transfer
 *  directly from/to a buffer with a base address of 0x00000000. To support
 *  this rare use-case, the application will have to manually copy the
 *  contents of location 0x00000000 to/from a temporary buffer before/after
 *  the tx/rx SPI transaction.
 *
 *  When the SPI is opened, the dataSize value determines the element types
 *  of txBuf and rxBuf. If the dataSize is from 4 to 8 bits, the driver
 *  assumes the data buffers are of type uint8_t (unsigned char). If the
 *  dataSize is from 8 to 16 bits, the driver assumes the data buffers are
 *  of type uint16_t (unsigned short).  If the dataSize is greater than
 *  16 bits, the driver assumes the data buffers are uint32_t (unsigned long).
 *  Some SPI driver implementations may not support all data sizes; refer
 *  to device specific SPI implementation documentation for details on
 *  what data sizes are supported.
 *
 *  The optional SPI_Transaction.arg variable can only be used when the
 *  SPI driver has been opened in callback mode. This variable is used to
 *  pass a user-defined value into the user-defined callback function.
 *
 *  SPI_transfer() always performs full-duplex SPI transactions. This means
 *  the SPI simultaneously receives data as it transmits data. The application
 *  is responsible for formatting the data to be transmitted as well as
 *  determining whether the data received is meaningful.
 *  Specifics about SPI frame formatting and data sizes are provided in
 *  device-specific data sheets and technical reference manuals.
 *
 *  The following code snippets perform SPI transactions.
 *
 *  Example transferring 6-bit SPI frames.  The transmit and receive
 *  buffers are of type uint8_t.
 *  @code
 *  SPI_Transaction spiTransaction;
 *  uint8_t         transmitBuffer[BUFSIZE];
 *  uint8_t         receiveBuffer[BUFSIZE];
 *  bool            transferOK;
 *
 *  SPI_Params_init(&spiParams);
 *  spiParams.dataSize = 6;
 *  spi = SPI_open(Board_SPI0, &spiParams);
 *  ...
 *  spiTransaction.count = someIntegerValue;
 *  spiTransaction.txBuf = transmitBuffer;
 *  spiTransaction.rxBuf = receiveBuffer;
 *
 *  transferOK = SPI_transfer(spi, &spiTransaction);
 *  if (!transferOK) {
 *      // Error in SPI or transfer already in progress.
 *  }
 *  @endcode
 *
 *  Example transferring 12-bit SPI frames.  The transmit and receive
 *  buffers are of type uint16_t.
 *  @code
 *  SPI_Transaction spiTransaction;
 *  uint16_t        transmitBuffer[BUFSIZE];
 *  uint16_t        receiveBuffer[BUFSIZE];
 *  bool            transferOK;
 *
 *  SPI_Params_init(&spiParams);
 *  spiParams.dataSize = 12;
 *  spi = SPI_open(Board_SPI0, &spiParams);
 *  ...
 *  spiTransaction.count = someIntegerValue;
 *  spiTransaction.txBuf = transmitBuffer;
 *  spiTransaction.rxBuf = receiveBuffer;
 *
 *  transferOK = SPI_transfer(spi, &spiTransaction);
 *  if (!transferOK) {
 *      // Error in SPI or transfer already in progress.
 *  }
 *  @endcode
 *
 *  ### Canceling a transaction #
 *  SPI_transferCancel() is used to cancel a SPI transaction when the driver is
 *  used in ::SPI_MODE_CALLBACK mode.
 *
 *  Calling this API while no transfer is in progress has no effect. If a
 *  transfer is in progress, it is canceled and the callback functions is
 *  called.
 *  The ::SPI_Status status field in the ::SPI_Transaction structure
 *  can be examined within the callback to determine if the transaction
 *  succeeded.
 *
 *  Example:
 *  @code
 *  SPI_transferCancel(spi);
 *  @endcode
 *
 *
 *  <h2><a NAME="Master_Slave_Modes">Master/Slave Modes</a></h2>
 *  This SPI driver functions in both SPI master and SPI slave modes.
 *  Logically, the implementation is identical, however the difference between
 *  these two modes is driven by hardware. As a SPI master, the peripheral is
 *  in control of the clock signal and therefore will commence communications
 *  to the SPI slave immediately. As a SPI slave, the SPI driver prepares
 *  the peripheral to transmit and receive data in a way such that the
 *  peripheral is ready to transfer data when the SPI master initiates a
 *  transaction.
 *
 *  ### Asserting on Chip Select
 *  The SPI protocol requires that the SPI master asserts a SPI slave's chip
 *  select pin prior to starting a SPI transaction. While this protocol is
 *  generally followed, various types of SPI peripherals have different
 *  timing requirements as to when and for how long the chip select pin must
 *  remain asserted for a SPI transaction.
 *
 *  Commonly, the SPI master uses a hardware chip select to assert and
 *  de-assert the SPI slave for every data frame. In other cases, a SPI slave
 *  imposes the requirement of asserting the chip select over several SPI
 *  data frames. This is generally accomplished by using a regular,
 *  general-purpose output pin. Due to the complexity of such SPI peripheral
 *  implementations, this SPI driver has been designed to operate
 *  transparently to the SPI chip select. When the hardware chip
 *  select is used, the peripheral automatically selects/enables the
 *  peripheral. When using a software chip select, the application needs to
 *  handle the proper chip select and pin configuration.  Chip select support
 *  will vary per SPI peripheral, refer to the device specific implementation
 *  documentation for details on chip select support.
 *
 *  - _Hardware chip select_  No additional action by the application is
 *    required.
 *  - _Software chip select_  The application needs to handle the chip select
 *    assertion and de-assertion for the proper SPI peripheral.
 *
 *  # Implementation #
 *
 *  This module serves as the main interface for RTOS applications. Its
 *  purpose is to redirect the module's APIs to specific peripheral
 *  implementations which are specified using a pointer to a #SPI_FxnTable.
 *
 *  The SPI driver interface module is joined (at link time) to an
 *  array of SPI_Config data structures named *SPI_config*.
 *  The SPI_config array is implemented in the application with each entry
 *  being an instance of a SPI peripheral. Each entry in *SPI_config* contains
 *  the following:
 *  - (SPI_FxnTable *)  A pointer to a set of functions that implement a
 *    SPI peripheral.
 *  - (void *)  A data object that is associated with the SPI_FxnTable.
 *  - (void *)  The hardware attributes that are associated with the
 *    SPI_FxnTable.
 *
 *******************************************************************************
 */

#ifndef ti_drivers_SPI__include
#define ti_drivers_SPI__include

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#define SPI_CMD_RESERVED           (32)

#define SPI_STATUS_RESERVED        (-32)

#define SPI_STATUS_SUCCESS         (0)

#define SPI_STATUS_ERROR           (-1)

#define SPI_STATUS_UNDEFINEDCMD    (-2)

/* Add SPI_CMD_<commands> here */

#define SPI_WAIT_FOREVER           (~(0U))

typedef struct SPI_Config_    *SPI_Handle;

typedef enum SPI_Status_ {
    SPI_TRANSFER_COMPLETED = 0,      
    SPI_TRANSFER_STARTED,            
    SPI_TRANSFER_CANCELED,           
    SPI_TRANSFER_FAILED,             
    SPI_TRANSFER_CSN_DEASSERT,       
    SPI_TRANSFER_PEND_CSN_ASSERT,    
    SPI_TRANSFER_QUEUED              
} SPI_Status;

typedef struct SPI_Transaction_ {
    /* User input (write-only) fields */
    size_t     count;       
    void      *txBuf;       
    void      *rxBuf;       
    void      *arg;         
    /* User output (read-only) fields */
    SPI_Status status;      
    void *nextPtr;          
} SPI_Transaction;

typedef void (*SPI_CallbackFxn) (SPI_Handle handle,
    SPI_Transaction *transaction);
typedef enum SPI_Mode_ {
    SPI_MASTER = 0,    
    SPI_SLAVE  = 1     
} SPI_Mode;

typedef enum SPI_FrameFormat_ {
    SPI_POL0_PHA0 = 0,    
    SPI_POL0_PHA1 = 1,    
    SPI_POL1_PHA0 = 2,    
    SPI_POL1_PHA1 = 3,    
    SPI_TI        = 4,    
    SPI_MW        = 5     
} SPI_FrameFormat;

typedef enum SPI_TransferMode_ {
    SPI_MODE_BLOCKING,
    SPI_MODE_CALLBACK
} SPI_TransferMode;

typedef struct SPI_Params_ {
    SPI_TransferMode transferMode;       
    uint32_t         transferTimeout;    
    SPI_CallbackFxn  transferCallbackFxn;
    SPI_Mode         mode;               
    uint32_t         bitRate;            
    uint32_t         dataSize;           
    SPI_FrameFormat  frameFormat;        
    void            *custom;             
} SPI_Params;

typedef void (*SPI_CloseFxn) (SPI_Handle handle);

typedef int_fast16_t (*SPI_ControlFxn) (SPI_Handle handle, uint_fast16_t cmd,
    void *arg);

typedef void (*SPI_InitFxn) (SPI_Handle handle);

typedef SPI_Handle (*SPI_OpenFxn) (SPI_Handle handle, SPI_Params *params);

typedef bool (*SPI_TransferFxn) (SPI_Handle handle,
    SPI_Transaction *transaction);

typedef void (*SPI_TransferCancelFxn) (SPI_Handle handle);

typedef struct SPI_FxnTable_ {
    SPI_CloseFxn          closeFxn;

    SPI_ControlFxn        controlFxn;

    SPI_InitFxn           initFxn;

    SPI_OpenFxn           openFxn;

    SPI_TransferFxn       transferFxn;

    SPI_TransferCancelFxn transferCancelFxn;
} SPI_FxnTable;

typedef struct SPI_Config_ {
    SPI_FxnTable const *fxnTablePtr;

    void               *object;

    void         const *hwAttrs;
} SPI_Config;

extern void SPI_close(SPI_Handle handle);

extern int_fast16_t SPI_control(SPI_Handle handle, uint_fast16_t cmd,
    void *controlArg);

extern void SPI_init(void);

extern SPI_Handle SPI_open(uint_least8_t index, SPI_Params *params);

extern void SPI_Params_init(SPI_Params *params);

extern bool SPI_transfer(SPI_Handle handle, SPI_Transaction *transaction);

extern void SPI_transferCancel(SPI_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_SPI__include */