packages/ti/drv/spi/SPI.h

   1 /*
   2  * Copyright (c) 2014-2015, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /**
  34  *  \defgroup DRV_SPI_MODULE SPI Driver
  35  *
  36  *  @{
  37  */
  38 /* @} */
  39
  40 /**
  41  *  \ingroup DRV_SPI_MODULE
  42  *  \defgroup DRV_SPI_API_MODULE SPI Driver API
  43  *            SPI driver interface
  44  *
  45  *  @{
  46  */
  47
  48 /** ============================================================================
  49  *  @file       SPI.h
  50  *
  51  *  @brief      SPI driver interface
  52  *
  53  *  The SPI header file should be included in an application as follows:
  54  *  @code
  55  *  #include <ti/drv/spi/SPI.h>
  56  *  @endcode
  57  *
  58  *  ============================================================================
  59  */
  60
  61 #ifndef SPI_H
  62 #define SPI_H
  63
  64 #ifdef __cplusplus
  65 extern "C" {
  66 #endif
  67
  68 #include <stdint.h>
  69 #include <stdbool.h>
  70 #include <stddef.h>
  71
  72 /*!
  73  * Common SPI_control command code reservation offset.
  74  * SPI driver implementations should offset command codes with SPI_CMD_RESERVED
  75  * growing positively
  76  *
  77  * Example implementation specific command codes:
  78  * @code
  79  * #define SPIXYZ_COMMAND0         SPI_CMD_RESERVED + 0
  80  * #define SPIXYZ_COMMAND1         SPI_CMD_RESERVED + 1
  81  * @endcode
  82  */
  83 #define SPI_CMD_RESERVED            (32U)
  84
  85 /*!
  86  * Common SPI_control status code reservation offset.
  87  * SPI driver implementations should offset status codes with
  88  * SPI_STATUS_RESERVED growing negatively.
  89  *
  90  * Example implementation specific status codes:
  91  * @code
  92  * #define SPIXYZ_STATUS_ERROR0    SPI_STATUS_RESERVED - 0
  93  * #define SPIXYZ_STATUS_ERROR1    SPI_STATUS_RESERVED - 1
  94  * #define SPIXYZ_STATUS_ERROR2    SPI_STATUS_RESERVED - 2
  95  * @endcode
  96  */
  97 #define SPI_STATUS_RESERVED        (-((int32_t)32))
  98
  99 /*!
 100  * \brief   Successful status code returned by SPI_control().
 101  *
 102  * SPI_control() returns SPI_STATUS_SUCCESS if the control code was executed
 103  * successfully.
 104  */
 105 #define SPI_STATUS_SUCCESS         (int32_t)(0)
 106
 107 /*!
 108  * \brief   Generic error status code returned by SPI_control().
 109  *
 110  * SPI_control() returns SPI_STATUS_ERROR if the control code was not executed
 111  * successfully.
 112  */
 113 #define SPI_STATUS_ERROR          (-((int32_t)1))
 114
 115 /*!
 116  * \brief   An error status code returned by SPI_control() for undefined
 117  * command codes.
 118  *
 119  * SPI_control() returns SPI_STATUS_UNDEFINEDCMD if the control code is not
 120  * recognized by the driver implementation.
 121  */
 122 #define SPI_STATUS_UNDEFINEDCMD   (-((int32_t)2))
 123
 124 /*!
 125  *  @brief    Wait forever define
 126  */
 127 #define SPI_WAIT_FOREVER (~(0U))
 128
 129 /*!
 130  *  @brief      A handle that is returned from a SPI_open() call.
 131  */
 132 typedef struct SPI_Config_s      *SPI_Handle;
 133
 134 /*!
 135  *  @brief      Status codes that are set by the SPI driver.
 136  */
 137 typedef enum SPI_Status_s {
 138     SPI_TRANSFER_COMPLETED = 0,
 139     SPI_TRANSFER_STARTED,
 140     SPI_TRANSFER_CANCELED,
 141     SPI_TRANSFER_FAILED,
 142     SPI_TRANSFER_CSN_DEASSERT,
 143     SPI_TRANSFER_TIMEOUT
 144 } SPI_Status;
 145
 146 /*!
 147  *  @brief
 148  *  A ::SPI_Transaction data structure is used with SPI_transfer(). It indicates
 149  *  how many ::SPI_FrameFormat frames are sent and received from the buffers
 150  *  pointed to txBuf and rxBuf.
 151  *  The arg variable is an user-definable argument which gets passed to the
 152  *  ::SPI_CallbackFxn when the SPI driver is in ::SPI_MODE_CALLBACK.
 153  */
 154 typedef struct SPI_Transaction_s {
 155     /* User input (write-only) fields */
 156     size_t     count;      /*!< Number of frames for this transaction */
 157     void      *txBuf;      /*!< void * to a buffer with data to be transmitted */
 158     void      *rxBuf;      /*!< void * to a buffer to receive data */
 159     void      *arg;        /*!< Argument to be passed to the callback function */
 160
 161     /* User output (read-only) fields */
 162     SPI_Status status;     /*!< Status code set by SPI_transfer */
 163
 164     /* Driver-use only fields */
 165 } SPI_Transaction;
 166
 167 /*!
 168  *  @brief      The definition of a callback function used by the SPI driver
 169  *              when used in ::SPI_MODE_CALLBACK
 170  *
 171  *  @param      SPI_Handle          SPI_Handle
 172  *  @param      SPI_Transaction*    SPI_Transaction*
 173  */
 174 typedef void        (*SPI_CallbackFxn) (SPI_Handle handle,
 175                                         SPI_Transaction * transaction);
 176 /*!
 177  *  @brief
 178  *  Definitions for various SPI modes of operation.
 179  */
 180 typedef enum SPI_Mode_s {
 181     SPI_MASTER      = 0,    /*!< SPI in master mode */
 182     SPI_SLAVE       = 1     /*!< SPI in slave mode */
 183 } SPI_Mode;
 184
 185 /*!
 186  *  @brief
 187  *  Definitions for various SPI data frame formats.
 188  */
 189 typedef enum SPI_FrameFormat_s {
 190     SPI_POL0_PHA0   = 0,    /*!< SPI mode Polarity 0 Phase 0 */
 191     SPI_POL0_PHA1   = 1,    /*!< SPI mode Polarity 0 Phase 1 */
 192     SPI_POL1_PHA0   = 2,    /*!< SPI mode Polarity 1 Phase 0 */
 193     SPI_POL1_PHA1   = 3,    /*!< SPI mode Polarity 1 Phase 1 */
 194     SPI_TI          = 4,    /*!< TI mode */
 195     SPI_MW          = 5     /*!< Micro-wire mode */
 196 } SPI_FrameFormat;
 197
 198 /*!
 199  *  @brief
 200  *
 201  *  SPI transfer mode determines the whether the SPI controller operates
 202  *  synchronously or asynchronously. In ::SPI_MODE_BLOCKING mode SPI_transfer()
 203  *  blocks code execution until the SPI transaction has completed. In
 204  *  ::SPI_MODE_CALLBACK SPI_transfer() does not block code execution and instead
 205  *  calls a ::SPI_CallbackFxn callback function when the transaction has
 206  *  completed.
 207  */
 208 typedef enum SPI_TransferMode_s {
 209     /*!
 210      * SPI_transfer() blocks execution. This mode can only be used when called
 211      * within a Task context
 212      */
 213     SPI_MODE_BLOCKING,
 214     /*!
 215      * SPI_transfer() does not block code execution and will call a
 216      * ::SPI_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context.
 217      */
 218     SPI_MODE_CALLBACK
 219 } SPI_TransferMode;
 220
 221 /*!
 222  *  @brief SPI Parameters
 223  *
 224  *  SPI Parameters are used to with the SPI_open() call. Default values for
 225  *  these parameters are set using SPI_Params_init().
 226  *
 227  *  @sa         SPI_Params_init()
 228  */
 229 typedef struct SPI_Params_s {
 230     SPI_TransferMode    transferMode;       /*!< Blocking or Callback mode */
 231     uint32_t            transferTimeout;    /*!< Transfer timeout in system
 232                                                  ticks (Not supported with all
 233                                                  implementations */
 234     SPI_CallbackFxn     transferCallbackFxn;/*!< Callback function pointer */
 235     SPI_Mode            mode;               /*!< Master or Slave mode */
 236     uint32_t            bitRate;            /*!< SPI bit rate in Hz */
 237     uint32_t            dataSize;           /*!< SPI data frame size in bits */
 238     SPI_FrameFormat     frameFormat;        /*!< SPI frame format */
 239     void               *custom;             /*!< Custom argument used by driver
 240                                                  implementation */
 241 } SPI_Params;
 242
 243 /*!
 244  *  @brief      A function pointer to a driver specific implementation of
 245  *              SPI_close().
 246  */
 247 typedef void        (*SPI_CloseFxn)          (SPI_Handle handle);
 248
 249 /*!
 250  *  @brief      A function pointer to a driver specific implementation of
 251  *              SPI_control().
 252  */
 253 typedef int32_t         (*SPI_ControlFxn)        (SPI_Handle handle,
 254                                               uint32_t cmd,
 255                                               const void *arg);
 256
 257 /*!
 258  *  @brief      A function pointer to a driver specific implementation of
 259  *              SPI_init().
 260  */
 261 typedef void        (*SPI_InitFxn)           (SPI_Handle handle);
 262
 263 /*!
 264  *  @brief      A function pointer to a driver specific implementation of
 265  *              SPI_open().
 266  */
 267 typedef SPI_Handle  (*SPI_OpenFxn)           (SPI_Handle handle,
 268                                               const SPI_Params *params);
 269
 270 /*!
 271  *  @brief      A function pointer to a driver specific implementation of
 272  *              SPI_serviceISR().
 273  */
 274 typedef void        (*SPI_ServiceISRFxn)     (SPI_Handle handle);
 275
 276 /*!
 277  *  @brief      A function pointer to a driver specific implementation of
 278  *              SPI_transfer().
 279  */
 280 typedef bool        (*SPI_TransferFxn)       (SPI_Handle handle,
 281                                               SPI_Transaction *transaction);
 282
 283 /*!
 284  *  @brief      A function pointer to a driver specific implementation of
 285  *              SPI_transferCancel().
 286  */
 287 typedef void        (*SPI_TransferCancelFxn) (SPI_Handle handle);
 288
 289 /*!
 290  *  @brief      The definition of a SPI function table that contains the
 291  *              required set of functions to control a specific SPI driver
 292  *              implementation.
 293  */
 294 typedef struct SPI_FxnTable_s {
 295     /*! Function to close the specified peripheral */
 296     SPI_CloseFxn            closeFxn;
 297
 298     /*! Function to implementation specific control function */
 299     SPI_ControlFxn          controlFxn;
 300
 301     /*! Function to initialize the given data object */
 302     SPI_InitFxn             spiInitFxn;
 303
 304     /*! Function to open the specified peripheral */
 305     SPI_OpenFxn             openFxn;
 306
 307     /*! Function to initiate a SPI data transfer */
 308     SPI_TransferFxn         transferFxn;
 309
 310     /*! Function to cancel SPI data transfer */
 311     SPI_TransferCancelFxn   transferCancelFxn;
 312
 313     /*! Function to service the SPI instance */
 314     SPI_ServiceISRFxn       serviceISRFxn;
 315 } SPI_FxnTable;
 316
 317 /*!
 318  *  @brief SPI Global configuration
 319  *
 320  *  The SPI_Config structure contains a set of pointers used to characterize
 321  *  the SPI driver implementation.
 322  *
 323  *  This structure needs to be defined before calling SPI_init() and it must
 324  *  not be changed thereafter.
 325  *
 326  *  @sa     SPI_init()
 327  */
 328 typedef struct SPI_Config_s {
 329     /*! Pointer to a table of driver-specific implementations of SPI APIs */
 330     SPI_FxnTable const *fxnTablePtr;
 331
 332     /*! Pointer to a driver specific data object */
 333     void               *object;
 334
 335     /*! Pointer to a driver specific hardware attributes structure */
 336     void         const *hwAttrs;
 337 } SPI_Config;
 338
 339 #define SPI_MAX_CONFIG_CNT (8U)
 340 typedef SPI_Config SPI_config_list[SPI_MAX_CONFIG_CNT];
 341
 342
 343 /*!
 344  *  @brief  Function to close a SPI peripheral specified by the SPI handle
 345  *
 346  *  @pre    SPI_open() has to be called first.
 347  *
 348  *  @param  handle A SPI handle returned from SPI_open()
 349  *
 350  *  @sa     SPI_open()
 351  */
 352 extern void SPI_close(SPI_Handle handle);
 353
 354 /*!
 355  *  @brief  Function performs implementation specific features on a given
 356  *          SPI_Handle.
 357  *
 358  *  @pre    SPI_open() has to be called first.
 359  *
 360  *  @param  handle      A SPI handle returned from SPI_open()
 361  *
 362  *  @param  cmd         A command value defined by the driver specific
 363  *                      implementation
 364  *
 365  *  @param  arg         An optional R/W (read/write) argument that is
 366  *                      accompanied with cmd
 367  *
 368  *  @return Implementation specific return codes. Negative values indicate
 369  *          unsuccessful operations.
 370  *
 371  *  @sa     SPI_open()
 372  */
 373 extern int32_t SPI_control(SPI_Handle handle, uint32_t cmd, void *arg);
 374
 375 /*!
 376  *  @brief  This function initializes the SPI module.
 377  *
 378  *  @pre    The SPI_config structure must exist and be persistent before this
 379  *          function can be called. This function must also be called before
 380  *          any other SPI driver APIs. This function call does not modify any
 381  *          peripheral registers.
 382  */
 383 extern void SPI_init(void);
 384
 385 /*!
 386  *  @brief  This function opens a given SPI peripheral.
 387  *
 388  *  @pre    SPI controller has been initialized using SPI_init()
 389  *
 390  *  @param  idx           Logical peripheral number for the SPI indexed into
 391  *                        the SPI_config table
 392  *
 393  *  @param  params        Pointer to an parameter block, if NULL it will use
 394  *                        default values. All the fields in this structure are
 395  *                        RO (read-only).
 396  *
 397  *  @return A SPI_Handle on success or a NULL on an error or if it has been
 398  *          opened already.
 399  *
 400  *  @sa     SPI_init()
 401  *  @sa     SPI_close()
 402  */
 403 extern SPI_Handle SPI_open(uint32_t idx, SPI_Params *params);
 404
 405 /*!
 406  *  @brief  Function to initialize the SPI_Params struct to its defaults
 407  *
 408  *  @param  params      An pointer to SPI_Params structure for
 409  *                      initialization
 410  *
 411  *  Defaults values are:
 412  *      transferMode        = SPI_MODE_BLOCKING
 413  *      transferTimeout     = SPI_WAIT_FOREVER
 414  *      transferCallbackFxn = NULL
 415  *      mode                = SPI_MASTER
 416  *      bitRate             = 1000000 (Hz)
 417  *      dataSize            = 8 (bits)
 418  *      frameFormat         = SPI_POL0_PHA0
 419  */
 420 extern void SPI_Params_init(SPI_Params *params);
 421
 422 /*!
 423  *  @brief  Function to service the SPI module's interrupt service routine
 424  *
 425  *  @param  handle      A SPI_Handle
 426  */
 427 extern void SPI_serviceISR(SPI_Handle handle);
 428
 429 /*!
 430  *  @brief  Function to perform SPI transactions
 431  *
 432  *  If the SPI is in ::SPI_MASTER mode, it will immediately start the
 433  *  transaction. If the SPI is in ::SPI_SLAVE mode, it prepares itself for a
 434  *  transaction with a SPI master.
 435  *
 436  *  In ::SPI_MODE_BLOCKING, SPI_transfer will block task execution until the
 437  *  transaction has completed.
 438  *
 439  *  In ::SPI_MODE_CALLBACK, SPI_transfer() does not block task execution and
 440  *  calls a ::SPI_CallbackFxn. This makes the SPI_tranfer() safe to be used
 441  *  within a Task, Swi, or Hwi context. The ::SPI_Transaction structure must
 442  *  stay persistent until the SPI_transfer function has completed!
 443  *
 444  *  @param  handle      A SPI_Handle
 445  *
 446  *  @param  spiTrans    A pointer to a SPI_Transaction. All of the fields within
 447  *                      transaction except SPI_Transaction.count and
 448  *                      SPI_Transaction.status are WO (write-only) unless
 449  *                      otherwise noted in the driver implementations. If a
 450  *                      transaction timeout has occured, SPI_Transaction.count
 451  *                      will contain the number of frames that were transferred.
 452  *
 453  *  @return true if started successfully; else false
 454  *
 455  *  @sa     SPI_open
 456  *  @sa     SPI_transferCancel
 457  */
 458 extern bool SPI_transfer(SPI_Handle handle, SPI_Transaction *spiTrans);
 459
 460 /*!
 461  *  @brief  Function to cancel SPI transactions
 462  *
 463  *  In ::SPI_MODE_BLOCKING, SPI_transferCancel has no effect.
 464  *
 465  *  In ::SPI_MODE_CALLBACK, SPI_transferCancel() will stop an SPI transfer if
 466  *  if one is in progress.
 467  *  If a transaction was in progress, its callback function will be called
 468  *  in context from which this API is called from. The ::SPI_CallbackFxn
 469  *  function can determine if the transaction was successful or not by reading
 470  *  the ::SPI_Status status value in the ::SPI_Transaction structure.
 471  *
 472  *  @param  handle      A SPI_Handle
 473  *
 474  *  @sa     SPI_open
 475  *  @sa     SPI_transfer
 476  */
 477 extern void SPI_transferCancel(SPI_Handle handle);
 478
 479 #ifdef __cplusplus
 480 }
 481 #endif
 482
 483 #endif /* _SPI_H */
 484
 485 /* @} */