begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_SPI.h

   1 /*
   2  * Copyright (c) 2013-2020 ARM Limited. All rights reserved.
   3  *
   4  * SPDX-License-Identifier: Apache-2.0
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License); you may
   7  * not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
  14  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * $Date:        31. March 2020
  19  * $Revision:    V2.3
  20  *
  21  * Project:      SPI (Serial Peripheral Interface) Driver definitions
  22  */
  23
  24 /* History:
  25  *  Version 2.3
  26  *    Removed Simplex Mode (deprecated)
  27  *    Removed volatile from ARM_SPI_STATUS
  28  *  Version 2.2
  29  *    ARM_SPI_STATUS made volatile
  30  *  Version 2.1
  31  *    Renamed status flag "tx_rx_busy" to "busy"
  32  *  Version 2.0
  33  *    New simplified driver:
  34  *      complexity moved to upper layer (especially data handling)
  35  *      more unified API for different communication interfaces
  36  *    Added:
  37  *      Slave Mode
  38  *      Half-duplex Modes
  39  *      Configurable number of data bits
  40  *      Support for TI Mode and Microwire
  41  *    Changed prefix ARM_DRV -> ARM_DRIVER
  42  *  Version 1.10
  43  *    Namespace prefix ARM_ added
  44  *  Version 1.01
  45  *    Added "send_done_event" to Capabilities
  46  *  Version 1.00
  47  *    Initial release
  48  */
  49
  50 #ifndef DRIVER_SPI_H_
  51 #define DRIVER_SPI_H_
  52
  53 #ifdef  __cplusplus
  54 extern "C"
  55 {
  56 #endif
  57
  58 #include "Driver_Common.h"
  59
  60 #define ARM_SPI_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,3)  /* API version */
  61
  62
  63 #define _ARM_Driver_SPI_(n)      Driver_SPI##n
  64 #define  ARM_Driver_SPI_(n) _ARM_Driver_SPI_(n)
  65
  66
  67 /****** SPI Control Codes *****/
  68
  69 #define ARM_SPI_CONTROL_Pos              0
  70 #define ARM_SPI_CONTROL_Msk             (0xFFUL << ARM_SPI_CONTROL_Pos)
  71
  72 /*----- SPI Control Codes: Mode -----*/
  73 #define ARM_SPI_MODE_INACTIVE           (0x00UL << ARM_SPI_CONTROL_Pos)     ///< SPI Inactive
  74 #define ARM_SPI_MODE_MASTER             (0x01UL << ARM_SPI_CONTROL_Pos)     ///< SPI Master (Output on MOSI, Input on MISO); arg = Bus Speed in bps
  75 #define ARM_SPI_MODE_SLAVE              (0x02UL << ARM_SPI_CONTROL_Pos)     ///< SPI Slave  (Output on MISO, Input on MOSI)
  76 #define ARM_SPI_MODE_MASTER_SIMPLEX     (0x03UL << ARM_SPI_CONTROL_Pos)     ///< SPI Master (Output/Input on MOSI); arg = Bus Speed in bps @deprecated Simplex Mode has been removed
  77 #define ARM_SPI_MODE_SLAVE_SIMPLEX      (0x04UL << ARM_SPI_CONTROL_Pos)     ///< SPI Slave  (Output/Input on MISO) @deprecated Simplex Mode has been removed
  78
  79 /*----- SPI Control Codes: Mode Parameters: Frame Format -----*/
  80 #define ARM_SPI_FRAME_FORMAT_Pos         8
  81 #define ARM_SPI_FRAME_FORMAT_Msk        (7UL << ARM_SPI_FRAME_FORMAT_Pos)
  82 #define ARM_SPI_CPOL0_CPHA0             (0UL << ARM_SPI_FRAME_FORMAT_Pos)   ///< Clock Polarity 0, Clock Phase 0 (default)
  83 #define ARM_SPI_CPOL0_CPHA1             (1UL << ARM_SPI_FRAME_FORMAT_Pos)   ///< Clock Polarity 0, Clock Phase 1
  84 #define ARM_SPI_CPOL1_CPHA0             (2UL << ARM_SPI_FRAME_FORMAT_Pos)   ///< Clock Polarity 1, Clock Phase 0
  85 #define ARM_SPI_CPOL1_CPHA1             (3UL << ARM_SPI_FRAME_FORMAT_Pos)   ///< Clock Polarity 1, Clock Phase 1
  86 #define ARM_SPI_TI_SSI                  (4UL << ARM_SPI_FRAME_FORMAT_Pos)   ///< Texas Instruments Frame Format
  87 #define ARM_SPI_MICROWIRE               (5UL << ARM_SPI_FRAME_FORMAT_Pos)   ///< National Semiconductor Microwire Frame Format
  88
  89 /*----- SPI Control Codes: Mode Parameters: Data Bits -----*/
  90 #define ARM_SPI_DATA_BITS_Pos            12
  91 #define ARM_SPI_DATA_BITS_Msk           (0x3FUL << ARM_SPI_DATA_BITS_Pos)
  92 #define ARM_SPI_DATA_BITS(n)            (((n) & 0x3FUL) << ARM_SPI_DATA_BITS_Pos) ///< Number of Data bits
  93
  94 /*----- SPI Control Codes: Mode Parameters: Bit Order -----*/
  95 #define ARM_SPI_BIT_ORDER_Pos            18
  96 #define ARM_SPI_BIT_ORDER_Msk           (1UL << ARM_SPI_BIT_ORDER_Pos)
  97 #define ARM_SPI_MSB_LSB                 (0UL << ARM_SPI_BIT_ORDER_Pos)      ///< SPI Bit order from MSB to LSB (default)
  98 #define ARM_SPI_LSB_MSB                 (1UL << ARM_SPI_BIT_ORDER_Pos)      ///< SPI Bit order from LSB to MSB
  99
 100 /*----- SPI Control Codes: Mode Parameters: Slave Select Mode -----*/
 101 #define ARM_SPI_SS_MASTER_MODE_Pos       19
 102 #define ARM_SPI_SS_MASTER_MODE_Msk      (3UL << ARM_SPI_SS_MASTER_MODE_Pos)
 103 #define ARM_SPI_SS_MASTER_UNUSED        (0UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Not used (default)
 104 #define ARM_SPI_SS_MASTER_SW            (1UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Software controlled
 105 #define ARM_SPI_SS_MASTER_HW_OUTPUT     (2UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Hardware controlled Output
 106 #define ARM_SPI_SS_MASTER_HW_INPUT      (3UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Hardware monitored Input
 107 #define ARM_SPI_SS_SLAVE_MODE_Pos        21
 108 #define ARM_SPI_SS_SLAVE_MODE_Msk       (1UL << ARM_SPI_SS_SLAVE_MODE_Pos)
 109 #define ARM_SPI_SS_SLAVE_HW             (0UL << ARM_SPI_SS_SLAVE_MODE_Pos)  ///< SPI Slave Select when Slave: Hardware monitored (default)
 110 #define ARM_SPI_SS_SLAVE_SW             (1UL << ARM_SPI_SS_SLAVE_MODE_Pos)  ///< SPI Slave Select when Slave: Software controlled
 111
 112
 113 /*----- SPI Control Codes: Miscellaneous Controls  -----*/
 114 #define ARM_SPI_SET_BUS_SPEED           (0x10UL << ARM_SPI_CONTROL_Pos)     ///< Set Bus Speed in bps; arg = value
 115 #define ARM_SPI_GET_BUS_SPEED           (0x11UL << ARM_SPI_CONTROL_Pos)     ///< Get Bus Speed in bps
 116 #define ARM_SPI_SET_DEFAULT_TX_VALUE    (0x12UL << ARM_SPI_CONTROL_Pos)     ///< Set default Transmit value; arg = value
 117 #define ARM_SPI_CONTROL_SS              (0x13UL << ARM_SPI_CONTROL_Pos)     ///< Control Slave Select; arg: 0=inactive, 1=active
 118 #define ARM_SPI_ABORT_TRANSFER          (0x14UL << ARM_SPI_CONTROL_Pos)     ///< Abort current data transfer
 119
 120
 121 /****** SPI Slave Select Signal definitions *****/
 122 #define ARM_SPI_SS_INACTIVE              0UL                                ///< SPI Slave Select Signal Inactive
 123 #define ARM_SPI_SS_ACTIVE                1UL                                ///< SPI Slave Select Signal Active
 124
 125
 126 /****** SPI specific error codes *****/
 127 #define ARM_SPI_ERROR_MODE              (ARM_DRIVER_ERROR_SPECIFIC - 1)     ///< Specified Mode not supported
 128 #define ARM_SPI_ERROR_FRAME_FORMAT      (ARM_DRIVER_ERROR_SPECIFIC - 2)     ///< Specified Frame Format not supported
 129 #define ARM_SPI_ERROR_DATA_BITS         (ARM_DRIVER_ERROR_SPECIFIC - 3)     ///< Specified number of Data bits not supported
 130 #define ARM_SPI_ERROR_BIT_ORDER         (ARM_DRIVER_ERROR_SPECIFIC - 4)     ///< Specified Bit order not supported
 131 #define ARM_SPI_ERROR_SS_MODE           (ARM_DRIVER_ERROR_SPECIFIC - 5)     ///< Specified Slave Select Mode not supported
 132
 133
 134 /**
 135 \brief SPI Status
 136 */
 137 typedef struct _ARM_SPI_STATUS {
 138   uint32_t busy       : 1;              ///< Transmitter/Receiver busy flag
 139   uint32_t data_lost  : 1;              ///< Data lost: Receive overflow / Transmit underflow (cleared on start of transfer operation)
 140   uint32_t mode_fault : 1;              ///< Mode fault detected; optional (cleared on start of transfer operation)
 141   uint32_t reserved   : 29;
 142 } ARM_SPI_STATUS;
 143
 144
 145 /****** SPI Event *****/
 146 #define ARM_SPI_EVENT_TRANSFER_COMPLETE (1UL << 0)  ///< Data Transfer completed
 147 #define ARM_SPI_EVENT_DATA_LOST         (1UL << 1)  ///< Data lost: Receive overflow / Transmit underflow
 148 #define ARM_SPI_EVENT_MODE_FAULT        (1UL << 2)  ///< Master Mode Fault (SS deactivated when Master)
 149
 150
 151 // Function documentation
 152 /**
 153   \fn          ARM_DRIVER_VERSION ARM_SPI_GetVersion (void)
 154   \brief       Get driver version.
 155   \return      \ref ARM_DRIVER_VERSION
 156
 157   \fn          ARM_SPI_CAPABILITIES ARM_SPI_GetCapabilities (void)
 158   \brief       Get driver capabilities.
 159   \return      \ref ARM_SPI_CAPABILITIES
 160
 161   \fn          int32_t ARM_SPI_Initialize (ARM_SPI_SignalEvent_t cb_event)
 162   \brief       Initialize SPI Interface.
 163   \param[in]   cb_event  Pointer to \ref ARM_SPI_SignalEvent
 164   \return      \ref execution_status
 165
 166   \fn          int32_t ARM_SPI_Uninitialize (void)
 167   \brief       De-initialize SPI Interface.
 168   \return      \ref execution_status
 169
 170   \fn          int32_t ARM_SPI_PowerControl (ARM_POWER_STATE state)
 171   \brief       Control SPI Interface Power.
 172   \param[in]   state  Power state
 173   \return      \ref execution_status
 174
 175   \fn          int32_t ARM_SPI_Send (const void *data, uint32_t num)
 176   \brief       Start sending data to SPI transmitter.
 177   \param[in]   data  Pointer to buffer with data to send to SPI transmitter
 178   \param[in]   num   Number of data items to send
 179   \return      \ref execution_status
 180
 181   \fn          int32_t ARM_SPI_Receive (void *data, uint32_t num)
 182   \brief       Start receiving data from SPI receiver.
 183   \param[out]  data  Pointer to buffer for data to receive from SPI receiver
 184   \param[in]   num   Number of data items to receive
 185   \return      \ref execution_status
 186
 187   \fn          int32_t ARM_SPI_Transfer (const void *data_out,
 188                                                void *data_in,
 189                                          uint32_t    num)
 190   \brief       Start sending/receiving data to/from SPI transmitter/receiver.
 191   \param[in]   data_out  Pointer to buffer with data to send to SPI transmitter
 192   \param[out]  data_in   Pointer to buffer for data to receive from SPI receiver
 193   \param[in]   num       Number of data items to transfer
 194   \return      \ref execution_status
 195
 196   \fn          uint32_t ARM_SPI_GetDataCount (void)
 197   \brief       Get transferred data count.
 198   \return      number of data items transferred
 199
 200   \fn          int32_t ARM_SPI_Control (uint32_t control, uint32_t arg)
 201   \brief       Control SPI Interface.
 202   \param[in]   control  Operation
 203   \param[in]   arg      Argument of operation (optional)
 204   \return      common \ref execution_status and driver specific \ref spi_execution_status
 205
 206   \fn          ARM_SPI_STATUS ARM_SPI_GetStatus (void)
 207   \brief       Get SPI status.
 208   \return      SPI status \ref ARM_SPI_STATUS
 209
 210   \fn          void ARM_SPI_SignalEvent (uint32_t event)
 211   \brief       Signal SPI Events.
 212   \param[in]   event \ref SPI_events notification mask
 213   \return      none
 214 */
 215
 216 typedef void (*ARM_SPI_SignalEvent_t) (uint32_t event);  ///< Pointer to \ref ARM_SPI_SignalEvent : Signal SPI Event.
 217
 218
 219 /**
 220 \brief SPI Driver Capabilities.
 221 */
 222 typedef struct _ARM_SPI_CAPABILITIES {
 223   uint32_t simplex          : 1;        ///< supports Simplex Mode (Master and Slave) @deprecated Reserved (must be zero)
 224   uint32_t ti_ssi           : 1;        ///< supports TI Synchronous Serial Interface
 225   uint32_t microwire        : 1;        ///< supports Microwire Interface
 226   uint32_t event_mode_fault : 1;        ///< Signal Mode Fault event: \ref ARM_SPI_EVENT_MODE_FAULT
 227   uint32_t reserved         : 28;       ///< Reserved (must be zero)
 228 } ARM_SPI_CAPABILITIES;
 229
 230
 231 /**
 232 \brief Access structure of the SPI Driver.
 233 */
 234 typedef struct _ARM_DRIVER_SPI {
 235   ARM_DRIVER_VERSION   (*GetVersion)      (void);                             ///< Pointer to \ref ARM_SPI_GetVersion : Get driver version.
 236   ARM_SPI_CAPABILITIES (*GetCapabilities) (void);                             ///< Pointer to \ref ARM_SPI_GetCapabilities : Get driver capabilities.
 237   int32_t              (*Initialize)      (ARM_SPI_SignalEvent_t cb_event);   ///< Pointer to \ref ARM_SPI_Initialize : Initialize SPI Interface.
 238   int32_t              (*Uninitialize)    (void);                             ///< Pointer to \ref ARM_SPI_Uninitialize : De-initialize SPI Interface.
 239   int32_t              (*PowerControl)    (ARM_POWER_STATE state);            ///< Pointer to \ref ARM_SPI_PowerControl : Control SPI Interface Power.
 240   int32_t              (*Send)            (const void *data, uint32_t num);   ///< Pointer to \ref ARM_SPI_Send : Start sending data to SPI Interface.
 241   int32_t              (*Receive)         (      void *data, uint32_t num);   ///< Pointer to \ref ARM_SPI_Receive : Start receiving data from SPI Interface.
 242   int32_t              (*Transfer)        (const void *data_out,
 243                                                  void *data_in,
 244                                            uint32_t    num);                  ///< Pointer to \ref ARM_SPI_Transfer : Start sending/receiving data to/from SPI.
 245   uint32_t             (*GetDataCount)    (void);                             ///< Pointer to \ref ARM_SPI_GetDataCount : Get transferred data count.
 246   int32_t              (*Control)         (uint32_t control, uint32_t arg);   ///< Pointer to \ref ARM_SPI_Control : Control SPI Interface.
 247   ARM_SPI_STATUS       (*GetStatus)       (void);                             ///< Pointer to \ref ARM_SPI_GetStatus : Get SPI status.
 248 } const ARM_DRIVER_SPI;
 249
 250 #ifdef  __cplusplus
 251 }
 252 #endif
 253
 254 #endif /* DRIVER_SPI_H_ */