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

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