git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4_SimpleLink_CC3220SF_CCS/ti/drivers/spi/SPICC32XXDMA.h

   1 /*
   2  * Copyright (c) 2015-2016, 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  *  @file       SPICC32XXDMA.h
  34  *
  35  *  @brief      SPI driver implementation for a CC32XX SPI controller using the
  36  *              micro DMA controller.
  37  *
  38  *  The SPI header file should be included in an application as follows:
  39  *  @code
  40  *  #include <ti/drivers/SPI.h>
  41  *  #include <ti/drivers/spi/SPICC32XXDMA.h>
  42  *  @endcode
  43  *
  44  *  Refer to @ref SPI.h for a complete description of APIs & example of use.
  45  *
  46  *  This SPI driver implementation is designed to operate on a CC32XX SPI
  47  *  controller using a micro DMA controller.
  48  *
  49  *  ## SPI Chip Select #
  50  *  This SPI controller supports a hardware chip select pin. Refer to the
  51  *  device's user manual on how this hardware chip select pin behaves in regards
  52  *  to the SPI frame format.
  53  *
  54  *  <table>
  55  *  <tr>
  56  *  <th>Chip select type</th>
  57  *  <th>SPI_MASTER mode</th>
  58  *  <th>SPI_SLAVE mode</th>
  59  *  </tr>
  60  *  <tr>
  61  *  <td>Hardware chip select</td>
  62  *  <td>No action is needed by the application to select the peripheral.</td>
  63  *  <td>See the device documentation on it's chip select requirements.</td>
  64  *  </tr>
  65  *  <tr>
  66  *  <td>Software chip select</td>
  67  *  <td>The application is responsible to ensure that correct SPI slave is
  68  *      selected before performing a SPI_transfer().</td>
  69  *  <td>See the device documentation on it's chip select requirements.</td>
  70  *  </tr>
  71  *  </table>
  72  *
  73  *  ## DMA Interrupts #
  74  *  This driver is designed to operate with the micro DMA. The micro DMA
  75  *  generates an IRQ on the perpheral's interrupt vector. This implementation
  76  *  automatically installs a DMA aware hardware ISR to service the assigned
  77  *  micro DMA channels.
  78  *
  79  *  ## SPI data frames #
  80  *  SPI data frames can be any size from 4-bits to 32-bits.  The SPI data
  81  *  frame size is set in ::SPI_Params.dataSize passed to SPI_open.
  82  *  The SPICC32XXDMA driver implementation makes assumptions on the element
  83  *  size of the ::SPI_Transaction txBuf and rxBuf arrays, based on the data
  84  *  frame size.  If the data frame size is less than or equal to 8 bits,
  85  *  txBuf and rxBuf are assumed to be arrays of 8-bit uint8_t elements.
  86  *  If the data frame size is greater than 8 bits, but less than or equal
  87  *  to 16 bits, txBuf and rxBuf are assumed to be arrays of 16-bit uint16_t
  88  *  elements.  Otherwise, txBuf and rxBuf are assumed to point to 32-bit
  89  *  uint32_t elements.
  90  *
  91  *  data frame size  | buffer element size |
  92  *  --------------   | ------------------- |
  93  *  4-8 bits         | uint8_t             |
  94  *  9-16 bits        | uint16_t            |
  95  *  16-32 bits       | uint32_t            |
  96  *
  97  *  ## DMA transfer size limit #
  98  *  The micro DMA controller only supports data transfers of up to 1024
  99  *  data frames. A data frame can be 4 to 32 bits in length.
 100  *
 101  *  ## DMA accessible memory #
 102  *  As this driver uses uDMA to transfer data/from data buffers, it is the
 103  *  responsibility of the application to ensure that these buffers reside in
 104  *  memory that is accessible by the DMA.
 105  *
 106  *******************************************************************************
 107  */
 108
 109 #ifndef ti_drivers_spi_SPICC32XXDMA__include
 110 #define ti_drivers_spi_SPICC32XXDMA__include
 111
 112 #ifdef __cplusplus
 113 extern "C" {
 114 #endif
 115
 116 #include <ti/drivers/dpl/HwiP.h>
 117 #include <ti/drivers/dpl/SemaphoreP.h>
 118 #include <ti/drivers/Power.h>
 119 #include <ti/drivers/SPI.h>
 120 #include <ti/drivers/dma/UDMACC32XX.h>
 121
 122 /**
 123  *  @addtogroup SPI_STATUS
 124  *  SPICC32XXDMA_STATUS_* macros are command codes only defined in the
 125  *  SPICC32XXDMA.h driver implementation and need to:
 126  *  @code
 127  *  #include <ti/drivers/sdspi/SPICC32XXDMA.h>
 128  *  @endcode
 129  *  @{
 130  */
 131
 132 /* Add SPICC32XXDMA_STATUS_* macros here */
 133
 134 /** @}*/
 135
 136 /**
 137  *  @addtogroup SPI_CMD
 138  *  SPICC32XXDMA_CMD_* macros are command codes only defined in the
 139  *  SPICC32XXDMA.h driver implementation and need to:
 140  *  @code
 141  *  #include <ti/drivers/sdspi/SPICC32XXDMA.h>
 142  *  @endcode
 143  *  @{
 144  */
 145
 146 /* Add SPICC32XXDMA_CMD_* macros here */
 147
 148 /** @}*/
 149
 150 #define SPICC32XXDMA_PIN_05_CLK     0x0704
 151 #define SPICC32XXDMA_PIN_06_MISO    0x0705
 152 #define SPICC32XXDMA_PIN_07_MOSI    0x0706
 153 #define SPICC32XXDMA_PIN_08_CS      0x0707
 154 #define SPICC32XXDMA_PIN_45_CLK     0x072C
 155 #define SPICC32XXDMA_PIN_50_CS      0x0931
 156 #define SPICC32XXDMA_PIN_52_MOSI    0x0833
 157 #define SPICC32XXDMA_PIN_53_MISO    0x0734
 158
 159 #define SPICC32XXDMA_PIN_NO_CONFIG  0xFFFF
 160
 161
 162 typedef unsigned long SPIBaseAddrType;
 163 typedef unsigned long SPIDataType;
 164
 165 /* SPI function table pointer */
 166 extern const SPI_FxnTable SPICC32XXDMA_fxnTable;
 167
 168 /*!
 169  *  @brief
 170  *  SPICC32XXDMA data frame size is used to determine how to configure the
 171  *  DMA data transfers. This field is to be only used internally.
 172  *
 173  *  SPICC32XXDMA_8bit:  txBuf and rxBuf are arrays of uint8_t elements
 174  *  SPICC32XXDMA_16bit: txBuf and rxBuf are arrays of uint16_t elements
 175  *  SPICC32XXDMA_32bit: txBuf and rxBuf are arrays of uint32_t elements
 176  */
 177 typedef enum SPICC32XXDMA_FrameSize {
 178     SPICC32XXDMA_8bit  = 0,
 179     SPICC32XXDMA_16bit = 1,
 180     SPICC32XXDMA_32bit = 2
 181 } SPICC32XXDMA_FrameSize;
 182
 183 /*!
 184  *  @brief  SPICC32XXDMA Hardware attributes
 185  *
 186  *  These fields, with the exception of intPriority,
 187  *  are used by driverlib APIs and therefore must be populated by
 188  *  driverlib macro definitions. For CCWare these definitions are found in:
 189  *      - driverlib/prcm.h
 190  *      - driverlib/spi.h
 191  *      - driverlib/udma.h
 192  *      - inc/hw_memmap.h
 193  *      - inc/hw_ints.h
 194  *
 195  *  intPriority is the SPI peripheral's interrupt priority, as defined by the
 196  *  underlying OS.  It is passed unmodified to the underlying OS's interrupt
 197  *  handler creation code, so you need to refer to the OS documentation
 198  *  for usage.  For example, for SYS/BIOS applications, refer to the
 199  *  ti.sysbios.family.arm.m3.Hwi documentation for SYS/BIOS usage of
 200  *  interrupt priorities.  If the driver uses the ti.dpl interface
 201  *  instead of making OS calls directly, then the HwiP port handles the
 202  *  interrupt priority in an OS specific way.  In the case of the SYS/BIOS
 203  *  port, intPriority is passed unmodified to Hwi_create().
 204  *
 205  *  A sample structure is shown below:
 206  *  @code
 207  *  #if defined(__TI_COMPILER_VERSION__)
 208  *  #pragma DATA_ALIGN(scratchBuf, 32)
 209  *  #elif defined(__IAR_SYSTEMS_ICC__)
 210  *  #pragma data_alignment=32
 211  *  #elif defined(__GNUC__)
 212  *  __attribute__ ((aligned (32)))
 213  *  #endif
 214  *  uint32_t scratchBuf;
 215  *
 216  *  const SPICC32XXDMA_HWAttrsV1 SPICC32XXDMAHWAttrs[] = {
 217  *      {
 218  *          .baseAddr = GSPI_BASE,
 219  *          .intNum = INT_GSPI,
 220  *          .intPriority = (~0),
 221  *          .spiPRCM = PRCM_GSPI,
 222  *          .csControl = SPI_HW_CTRL_CS,
 223  *          .csPolarity = SPI_CS_ACTIVELOW,
 224  *          .pinMode = SPI_4PIN_MODE,
 225  *          .turboMode = SPI_TURBO_OFF,
 226  *          .scratchBufPtr = &scratchBuf,
 227  *          .defaultTxBufValue = 0,
 228  *          .rxChannelIndex = UDMA_CH6_GSPI_RX,
 229  *          .txChannelIndex = UDMA_CH7_GSPI_TX,
 230  *          .minDmaTransferSize = 100,
 231  *          .mosiPin = SPICC32XXDMA_PIN_07_MOSI,
 232  *          .misoPin = SPICC32XXDMA_PIN_06_MISO,
 233  *          .clkPin = SPICC32XXDMA_PIN_05_CLK,
 234  *          .csPin = SPICC32XXDMA_PIN_08_CS,
 235  *      },
 236  *      ...
 237  *  };
 238  *  @endcode
 239  */
 240 typedef struct SPICC32XXDMA_HWAttrsV1 {
 241     /*! SPICC32XXDMA Peripheral's base address */
 242     SPIBaseAddrType   baseAddr;
 243
 244     /*! SPICC32XXDMA Peripheral's interrupt vector */
 245     uint32_t   intNum;
 246
 247     /*! SPICC32XXDMA Peripheral's interrupt priority */
 248     uint32_t   intPriority;
 249
 250     /*! SPI PRCM peripheral number */
 251     uint32_t   spiPRCM;
 252
 253     /*! Specify if chip select line will be controlled by SW or HW */
 254     uint32_t   csControl;
 255
 256     uint32_t   csPolarity;
 257
 258     /*! Set peripheral to work in 3-pin or 4-pin mode */
 259     uint32_t   pinMode;
 260
 261     /*! Enable or disable SPI TURBO mode */
 262     uint32_t   turboMode;
 263
 264     /*! Address of a scratch buffer of size uint32_t */
 265     uint32_t  *scratchBufPtr;
 266
 267     /*! Default TX value if txBuf == NULL */
 268     unsigned long   defaultTxBufValue;
 269
 270     /*! uDMA RX channel index */
 271     uint32_t   rxChannelIndex;
 272
 273     /*! uDMA TX channel index */
 274     uint32_t   txChannelIndex;
 275
 276     /*! Minimum amout of data to start a uDMA transfer */
 277     uint32_t   minDmaTransferSize;
 278
 279     /*! GSPI MOSI pin assignment */
 280     uint16_t   mosiPin;
 281
 282     /*! GSPI MISO pin assignment */
 283     uint16_t   misoPin;
 284
 285     /*! GSPI CLK pin assignment */
 286     uint16_t   clkPin;
 287
 288     /*! GSPI CS pin assignment */
 289     uint16_t   csPin;
 290 } SPICC32XXDMA_HWAttrsV1;
 291
 292 /*!
 293  *  @brief  SPICC32XXDMA Object
 294  *
 295  *  The application must not access any member variables of this structure!
 296  */
 297 typedef struct SPICC32XXDMA_Object {
 298     HwiP_Handle            hwiHandle;
 299     SemaphoreP_Handle      transferComplete;
 300
 301     Power_NotifyObj        notifyObj;
 302     unsigned int           powerMgrId;
 303
 304     uint32_t               bitRate;        /*!< SPI bit rate in Hz */
 305     uint32_t               dataSize;       /*!< SPI data frame size in bits */
 306     SPI_CallbackFxn        transferCallbackFxn;
 307     SPI_Transaction       *transaction;
 308
 309     void                 (*spiPollingFxn) (uint32_t baseAddr, void *rx,
 310                                    void *tx, uint8_t rxInc, uint8_t txInc,
 311                                size_t count);
 312
 313     uint8_t                rxFifoTrigger;
 314     uint8_t                txFifoTrigger;
 315     SPI_Mode               spiMode;
 316     SPI_TransferMode       transferMode;
 317     SPI_FrameFormat        frameFormat;    /*!< SPI frame format */
 318     SPICC32XXDMA_FrameSize frameSize;
 319
 320     bool                   isOpen;
 321
 322     /* UDMA */
 323     UDMACC32XX_Handle      dmaHandle;
 324 } SPICC32XXDMA_Object, *SPICC32XXDMA_Handle;
 325
 326 #ifdef __cplusplus
 327 }
 328 #endif
 329
 330 #endif /* ti_drivers_spi_SPICC32XXDMA__include */