begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_USART.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:        24. January 2020
  19  * $Revision:    V2.4
  20  *
  21  * Project:      USART (Universal Synchronous Asynchronous Receiver Transmitter)
  22  *               Driver definitions
  23  */
  24
  25 /* History:
  26  *  Version 2.4
  27  *    Removed volatile from ARM_USART_STATUS and ARM_USART_MODEM_STATUS
  28  *  Version 2.3
  29  *    ARM_USART_STATUS and ARM_USART_MODEM_STATUS made volatile
  30  *  Version 2.2
  31  *    Corrected ARM_USART_CPOL_Pos and ARM_USART_CPHA_Pos definitions
  32  *  Version 2.1
  33  *    Removed optional argument parameter from Signal Event
  34  *  Version 2.0
  35  *    New simplified driver:
  36  *      complexity moved to upper layer (especially data handling)
  37  *      more unified API for different communication interfaces
  38  *      renamed driver UART -> USART (Asynchronous & Synchronous)
  39  *    Added modes:
  40  *      Synchronous
  41  *      Single-wire
  42  *      IrDA
  43  *      Smart Card
  44  *    Changed prefix ARM_DRV -> ARM_DRIVER
  45  *  Version 1.10
  46  *    Namespace prefix ARM_ added
  47  *  Version 1.01
  48  *    Added events:
  49  *      ARM_UART_EVENT_TX_EMPTY,     ARM_UART_EVENT_RX_TIMEOUT
  50  *      ARM_UART_EVENT_TX_THRESHOLD, ARM_UART_EVENT_RX_THRESHOLD
  51  *    Added functions: SetTxThreshold, SetRxThreshold
  52  *    Added "rx_timeout_event" to capabilities
  53  *  Version 1.00
  54  *    Initial release
  55  */
  56
  57 #ifndef DRIVER_USART_H_
  58 #define DRIVER_USART_H_
  59
  60 #ifdef  __cplusplus
  61 extern "C"
  62 {
  63 #endif
  64
  65 #include "Driver_Common.h"
  66
  67 #define ARM_USART_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,4)  /* API version */
  68
  69
  70 /****** USART Control Codes *****/
  71
  72 #define ARM_USART_CONTROL_Pos                0
  73 #define ARM_USART_CONTROL_Msk               (0xFFUL << ARM_USART_CONTROL_Pos)
  74
  75 /*----- USART Control Codes: Mode -----*/
  76 #define ARM_USART_MODE_ASYNCHRONOUS         (0x01UL << ARM_USART_CONTROL_Pos)   ///< UART (Asynchronous); arg = Baudrate
  77 #define ARM_USART_MODE_SYNCHRONOUS_MASTER   (0x02UL << ARM_USART_CONTROL_Pos)   ///< Synchronous Master (generates clock signal); arg = Baudrate
  78 #define ARM_USART_MODE_SYNCHRONOUS_SLAVE    (0x03UL << ARM_USART_CONTROL_Pos)   ///< Synchronous Slave (external clock signal)
  79 #define ARM_USART_MODE_SINGLE_WIRE          (0x04UL << ARM_USART_CONTROL_Pos)   ///< UART Single-wire (half-duplex); arg = Baudrate
  80 #define ARM_USART_MODE_IRDA                 (0x05UL << ARM_USART_CONTROL_Pos)   ///< UART IrDA; arg = Baudrate
  81 #define ARM_USART_MODE_SMART_CARD           (0x06UL << ARM_USART_CONTROL_Pos)   ///< UART Smart Card; arg = Baudrate
  82
  83 /*----- USART Control Codes: Mode Parameters: Data Bits -----*/
  84 #define ARM_USART_DATA_BITS_Pos              8
  85 #define ARM_USART_DATA_BITS_Msk             (7UL << ARM_USART_DATA_BITS_Pos)
  86 #define ARM_USART_DATA_BITS_5               (5UL << ARM_USART_DATA_BITS_Pos)    ///< 5 Data bits
  87 #define ARM_USART_DATA_BITS_6               (6UL << ARM_USART_DATA_BITS_Pos)    ///< 6 Data bit
  88 #define ARM_USART_DATA_BITS_7               (7UL << ARM_USART_DATA_BITS_Pos)    ///< 7 Data bits
  89 #define ARM_USART_DATA_BITS_8               (0UL << ARM_USART_DATA_BITS_Pos)    ///< 8 Data bits (default)
  90 #define ARM_USART_DATA_BITS_9               (1UL << ARM_USART_DATA_BITS_Pos)    ///< 9 Data bits
  91
  92 /*----- USART Control Codes: Mode Parameters: Parity -----*/
  93 #define ARM_USART_PARITY_Pos                 12
  94 #define ARM_USART_PARITY_Msk                (3UL << ARM_USART_PARITY_Pos)
  95 #define ARM_USART_PARITY_NONE               (0UL << ARM_USART_PARITY_Pos)       ///< No Parity (default)
  96 #define ARM_USART_PARITY_EVEN               (1UL << ARM_USART_PARITY_Pos)       ///< Even Parity
  97 #define ARM_USART_PARITY_ODD                (2UL << ARM_USART_PARITY_Pos)       ///< Odd Parity
  98
  99 /*----- USART Control Codes: Mode Parameters: Stop Bits -----*/
 100 #define ARM_USART_STOP_BITS_Pos              14
 101 #define ARM_USART_STOP_BITS_Msk             (3UL << ARM_USART_STOP_BITS_Pos)
 102 #define ARM_USART_STOP_BITS_1               (0UL << ARM_USART_STOP_BITS_Pos)    ///< 1 Stop bit (default)
 103 #define ARM_USART_STOP_BITS_2               (1UL << ARM_USART_STOP_BITS_Pos)    ///< 2 Stop bits
 104 #define ARM_USART_STOP_BITS_1_5             (2UL << ARM_USART_STOP_BITS_Pos)    ///< 1.5 Stop bits
 105 #define ARM_USART_STOP_BITS_0_5             (3UL << ARM_USART_STOP_BITS_Pos)    ///< 0.5 Stop bits
 106
 107 /*----- USART Control Codes: Mode Parameters: Flow Control -----*/
 108 #define ARM_USART_FLOW_CONTROL_Pos           16
 109 #define ARM_USART_FLOW_CONTROL_Msk          (3UL << ARM_USART_FLOW_CONTROL_Pos)
 110 #define ARM_USART_FLOW_CONTROL_NONE         (0UL << ARM_USART_FLOW_CONTROL_Pos) ///< No Flow Control (default)
 111 #define ARM_USART_FLOW_CONTROL_RTS          (1UL << ARM_USART_FLOW_CONTROL_Pos) ///< RTS Flow Control
 112 #define ARM_USART_FLOW_CONTROL_CTS          (2UL << ARM_USART_FLOW_CONTROL_Pos) ///< CTS Flow Control
 113 #define ARM_USART_FLOW_CONTROL_RTS_CTS      (3UL << ARM_USART_FLOW_CONTROL_Pos) ///< RTS/CTS Flow Control
 114
 115 /*----- USART Control Codes: Mode Parameters: Clock Polarity (Synchronous mode) -----*/
 116 #define ARM_USART_CPOL_Pos                   18
 117 #define ARM_USART_CPOL_Msk                  (1UL << ARM_USART_CPOL_Pos)
 118 #define ARM_USART_CPOL0                     (0UL << ARM_USART_CPOL_Pos)         ///< CPOL = 0 (default)
 119 #define ARM_USART_CPOL1                     (1UL << ARM_USART_CPOL_Pos)         ///< CPOL = 1
 120
 121 /*----- USART Control Codes: Mode Parameters: Clock Phase (Synchronous mode) -----*/
 122 #define ARM_USART_CPHA_Pos                   19
 123 #define ARM_USART_CPHA_Msk                  (1UL << ARM_USART_CPHA_Pos)
 124 #define ARM_USART_CPHA0                     (0UL << ARM_USART_CPHA_Pos)         ///< CPHA = 0 (default)
 125 #define ARM_USART_CPHA1                     (1UL << ARM_USART_CPHA_Pos)         ///< CPHA = 1
 126
 127
 128 /*----- USART Control Codes: Miscellaneous Controls  -----*/
 129 #define ARM_USART_SET_DEFAULT_TX_VALUE      (0x10UL << ARM_USART_CONTROL_Pos)   ///< Set default Transmit value (Synchronous Receive only); arg = value
 130 #define ARM_USART_SET_IRDA_PULSE            (0x11UL << ARM_USART_CONTROL_Pos)   ///< Set IrDA Pulse in ns; arg: 0=3/16 of bit period
 131 #define ARM_USART_SET_SMART_CARD_GUARD_TIME (0x12UL << ARM_USART_CONTROL_Pos)   ///< Set Smart Card Guard Time; arg = number of bit periods
 132 #define ARM_USART_SET_SMART_CARD_CLOCK      (0x13UL << ARM_USART_CONTROL_Pos)   ///< Set Smart Card Clock in Hz; arg: 0=Clock not generated
 133 #define ARM_USART_CONTROL_SMART_CARD_NACK   (0x14UL << ARM_USART_CONTROL_Pos)   ///< Smart Card NACK generation; arg: 0=disabled, 1=enabled
 134 #define ARM_USART_CONTROL_TX                (0x15UL << ARM_USART_CONTROL_Pos)   ///< Transmitter; arg: 0=disabled, 1=enabled
 135 #define ARM_USART_CONTROL_RX                (0x16UL << ARM_USART_CONTROL_Pos)   ///< Receiver; arg: 0=disabled, 1=enabled
 136 #define ARM_USART_CONTROL_BREAK             (0x17UL << ARM_USART_CONTROL_Pos)   ///< Continuous Break transmission; arg: 0=disabled, 1=enabled
 137 #define ARM_USART_ABORT_SEND                (0x18UL << ARM_USART_CONTROL_Pos)   ///< Abort \ref ARM_USART_Send
 138 #define ARM_USART_ABORT_RECEIVE             (0x19UL << ARM_USART_CONTROL_Pos)   ///< Abort \ref ARM_USART_Receive
 139 #define ARM_USART_ABORT_TRANSFER            (0x1AUL << ARM_USART_CONTROL_Pos)   ///< Abort \ref ARM_USART_Transfer
 140
 141
 142
 143 /****** USART specific error codes *****/
 144 #define ARM_USART_ERROR_MODE                (ARM_DRIVER_ERROR_SPECIFIC - 1)     ///< Specified Mode not supported
 145 #define ARM_USART_ERROR_BAUDRATE            (ARM_DRIVER_ERROR_SPECIFIC - 2)     ///< Specified baudrate not supported
 146 #define ARM_USART_ERROR_DATA_BITS           (ARM_DRIVER_ERROR_SPECIFIC - 3)     ///< Specified number of Data bits not supported
 147 #define ARM_USART_ERROR_PARITY              (ARM_DRIVER_ERROR_SPECIFIC - 4)     ///< Specified Parity not supported
 148 #define ARM_USART_ERROR_STOP_BITS           (ARM_DRIVER_ERROR_SPECIFIC - 5)     ///< Specified number of Stop bits not supported
 149 #define ARM_USART_ERROR_FLOW_CONTROL        (ARM_DRIVER_ERROR_SPECIFIC - 6)     ///< Specified Flow Control not supported
 150 #define ARM_USART_ERROR_CPOL                (ARM_DRIVER_ERROR_SPECIFIC - 7)     ///< Specified Clock Polarity not supported
 151 #define ARM_USART_ERROR_CPHA                (ARM_DRIVER_ERROR_SPECIFIC - 8)     ///< Specified Clock Phase not supported
 152
 153
 154 /**
 155 \brief USART Status
 156 */
 157 typedef struct _ARM_USART_STATUS {
 158   uint32_t tx_busy          : 1;        ///< Transmitter busy flag
 159   uint32_t rx_busy          : 1;        ///< Receiver busy flag
 160   uint32_t tx_underflow     : 1;        ///< Transmit data underflow detected (cleared on start of next send operation)
 161   uint32_t rx_overflow      : 1;        ///< Receive data overflow detected (cleared on start of next receive operation)
 162   uint32_t rx_break         : 1;        ///< Break detected on receive (cleared on start of next receive operation)
 163   uint32_t rx_framing_error : 1;        ///< Framing error detected on receive (cleared on start of next receive operation)
 164   uint32_t rx_parity_error  : 1;        ///< Parity error detected on receive (cleared on start of next receive operation)
 165   uint32_t reserved         : 25;
 166 } ARM_USART_STATUS;
 167
 168 /**
 169 \brief USART Modem Control
 170 */
 171 typedef enum _ARM_USART_MODEM_CONTROL {
 172   ARM_USART_RTS_CLEAR,                  ///< Deactivate RTS
 173   ARM_USART_RTS_SET,                    ///< Activate RTS
 174   ARM_USART_DTR_CLEAR,                  ///< Deactivate DTR
 175   ARM_USART_DTR_SET                     ///< Activate DTR
 176 } ARM_USART_MODEM_CONTROL;
 177
 178 /**
 179 \brief USART Modem Status
 180 */
 181 typedef struct _ARM_USART_MODEM_STATUS {
 182   uint32_t cts      : 1;                ///< CTS state: 1=Active, 0=Inactive
 183   uint32_t dsr      : 1;                ///< DSR state: 1=Active, 0=Inactive
 184   uint32_t dcd      : 1;                ///< DCD state: 1=Active, 0=Inactive
 185   uint32_t ri       : 1;                ///< RI  state: 1=Active, 0=Inactive
 186   uint32_t reserved : 28;
 187 } ARM_USART_MODEM_STATUS;
 188
 189
 190 /****** USART Event *****/
 191 #define ARM_USART_EVENT_SEND_COMPLETE       (1UL << 0)  ///< Send completed; however USART may still transmit data
 192 #define ARM_USART_EVENT_RECEIVE_COMPLETE    (1UL << 1)  ///< Receive completed
 193 #define ARM_USART_EVENT_TRANSFER_COMPLETE   (1UL << 2)  ///< Transfer completed
 194 #define ARM_USART_EVENT_TX_COMPLETE         (1UL << 3)  ///< Transmit completed (optional)
 195 #define ARM_USART_EVENT_TX_UNDERFLOW        (1UL << 4)  ///< Transmit data not available (Synchronous Slave)
 196 #define ARM_USART_EVENT_RX_OVERFLOW         (1UL << 5)  ///< Receive data overflow
 197 #define ARM_USART_EVENT_RX_TIMEOUT          (1UL << 6)  ///< Receive character timeout (optional)
 198 #define ARM_USART_EVENT_RX_BREAK            (1UL << 7)  ///< Break detected on receive
 199 #define ARM_USART_EVENT_RX_FRAMING_ERROR    (1UL << 8)  ///< Framing error detected on receive
 200 #define ARM_USART_EVENT_RX_PARITY_ERROR     (1UL << 9)  ///< Parity error detected on receive
 201 #define ARM_USART_EVENT_CTS                 (1UL << 10) ///< CTS state changed (optional)
 202 #define ARM_USART_EVENT_DSR                 (1UL << 11) ///< DSR state changed (optional)
 203 #define ARM_USART_EVENT_DCD                 (1UL << 12) ///< DCD state changed (optional)
 204 #define ARM_USART_EVENT_RI                  (1UL << 13) ///< RI  state changed (optional)
 205
 206
 207 // Function documentation
 208 /**
 209   \fn          ARM_DRIVER_VERSION ARM_USART_GetVersion (void)
 210   \brief       Get driver version.
 211   \return      \ref ARM_DRIVER_VERSION
 212
 213   \fn          ARM_USART_CAPABILITIES ARM_USART_GetCapabilities (void)
 214   \brief       Get driver capabilities
 215   \return      \ref ARM_USART_CAPABILITIES
 216
 217   \fn          int32_t ARM_USART_Initialize (ARM_USART_SignalEvent_t cb_event)
 218   \brief       Initialize USART Interface.
 219   \param[in]   cb_event  Pointer to \ref ARM_USART_SignalEvent
 220   \return      \ref execution_status
 221
 222   \fn          int32_t ARM_USART_Uninitialize (void)
 223   \brief       De-initialize USART Interface.
 224   \return      \ref execution_status
 225
 226   \fn          int32_t ARM_USART_PowerControl (ARM_POWER_STATE state)
 227   \brief       Control USART Interface Power.
 228   \param[in]   state  Power state
 229   \return      \ref execution_status
 230
 231   \fn          int32_t ARM_USART_Send (const void *data, uint32_t num)
 232   \brief       Start sending data to USART transmitter.
 233   \param[in]   data  Pointer to buffer with data to send to USART transmitter
 234   \param[in]   num   Number of data items to send
 235   \return      \ref execution_status
 236
 237   \fn          int32_t ARM_USART_Receive (void *data, uint32_t num)
 238   \brief       Start receiving data from USART receiver.
 239   \param[out]  data  Pointer to buffer for data to receive from USART receiver
 240   \param[in]   num   Number of data items to receive
 241   \return      \ref execution_status
 242
 243   \fn          int32_t ARM_USART_Transfer (const void *data_out,
 244                                                  void *data_in,
 245                                            uint32_t    num)
 246   \brief       Start sending/receiving data to/from USART transmitter/receiver.
 247   \param[in]   data_out  Pointer to buffer with data to send to USART transmitter
 248   \param[out]  data_in   Pointer to buffer for data to receive from USART receiver
 249   \param[in]   num       Number of data items to transfer
 250   \return      \ref execution_status
 251
 252   \fn          uint32_t ARM_USART_GetTxCount (void)
 253   \brief       Get transmitted data count.
 254   \return      number of data items transmitted
 255
 256   \fn          uint32_t ARM_USART_GetRxCount (void)
 257   \brief       Get received data count.
 258   \return      number of data items received
 259
 260   \fn          int32_t ARM_USART_Control (uint32_t control, uint32_t arg)
 261   \brief       Control USART Interface.
 262   \param[in]   control  Operation
 263   \param[in]   arg      Argument of operation (optional)
 264   \return      common \ref execution_status and driver specific \ref usart_execution_status
 265
 266   \fn          ARM_USART_STATUS ARM_USART_GetStatus (void)
 267   \brief       Get USART status.
 268   \return      USART status \ref ARM_USART_STATUS
 269
 270   \fn          int32_t ARM_USART_SetModemControl (ARM_USART_MODEM_CONTROL control)
 271   \brief       Set USART Modem Control line state.
 272   \param[in]   control  \ref ARM_USART_MODEM_CONTROL
 273   \return      \ref execution_status
 274
 275   \fn          ARM_USART_MODEM_STATUS ARM_USART_GetModemStatus (void)
 276   \brief       Get USART Modem Status lines state.
 277   \return      modem status \ref ARM_USART_MODEM_STATUS
 278
 279   \fn          void ARM_USART_SignalEvent (uint32_t event)
 280   \brief       Signal USART Events.
 281   \param[in]   event  \ref USART_events notification mask
 282   \return      none
 283 */
 284
 285 typedef void (*ARM_USART_SignalEvent_t) (uint32_t event);  ///< Pointer to \ref ARM_USART_SignalEvent : Signal USART Event.
 286
 287
 288 /**
 289 \brief USART Device Driver Capabilities.
 290 */
 291 typedef struct _ARM_USART_CAPABILITIES {
 292   uint32_t asynchronous       : 1;      ///< supports UART (Asynchronous) mode
 293   uint32_t synchronous_master : 1;      ///< supports Synchronous Master mode
 294   uint32_t synchronous_slave  : 1;      ///< supports Synchronous Slave mode
 295   uint32_t single_wire        : 1;      ///< supports UART Single-wire mode
 296   uint32_t irda               : 1;      ///< supports UART IrDA mode
 297   uint32_t smart_card         : 1;      ///< supports UART Smart Card mode
 298   uint32_t smart_card_clock   : 1;      ///< Smart Card Clock generator available
 299   uint32_t flow_control_rts   : 1;      ///< RTS Flow Control available
 300   uint32_t flow_control_cts   : 1;      ///< CTS Flow Control available
 301   uint32_t event_tx_complete  : 1;      ///< Transmit completed event: \ref ARM_USART_EVENT_TX_COMPLETE
 302   uint32_t event_rx_timeout   : 1;      ///< Signal receive character timeout event: \ref ARM_USART_EVENT_RX_TIMEOUT
 303   uint32_t rts                : 1;      ///< RTS Line: 0=not available, 1=available
 304   uint32_t cts                : 1;      ///< CTS Line: 0=not available, 1=available
 305   uint32_t dtr                : 1;      ///< DTR Line: 0=not available, 1=available
 306   uint32_t dsr                : 1;      ///< DSR Line: 0=not available, 1=available
 307   uint32_t dcd                : 1;      ///< DCD Line: 0=not available, 1=available
 308   uint32_t ri                 : 1;      ///< RI Line: 0=not available, 1=available
 309   uint32_t event_cts          : 1;      ///< Signal CTS change event: \ref ARM_USART_EVENT_CTS
 310   uint32_t event_dsr          : 1;      ///< Signal DSR change event: \ref ARM_USART_EVENT_DSR
 311   uint32_t event_dcd          : 1;      ///< Signal DCD change event: \ref ARM_USART_EVENT_DCD
 312   uint32_t event_ri           : 1;      ///< Signal RI change event: \ref ARM_USART_EVENT_RI
 313   uint32_t reserved           : 11;     ///< Reserved (must be zero)
 314 } ARM_USART_CAPABILITIES;
 315
 316
 317 /**
 318 \brief Access structure of the USART Driver.
 319 */
 320 typedef struct _ARM_DRIVER_USART {
 321   ARM_DRIVER_VERSION     (*GetVersion)      (void);                              ///< Pointer to \ref ARM_USART_GetVersion : Get driver version.
 322   ARM_USART_CAPABILITIES (*GetCapabilities) (void);                              ///< Pointer to \ref ARM_USART_GetCapabilities : Get driver capabilities.
 323   int32_t                (*Initialize)      (ARM_USART_SignalEvent_t cb_event);  ///< Pointer to \ref ARM_USART_Initialize : Initialize USART Interface.
 324   int32_t                (*Uninitialize)    (void);                              ///< Pointer to \ref ARM_USART_Uninitialize : De-initialize USART Interface.
 325   int32_t                (*PowerControl)    (ARM_POWER_STATE state);             ///< Pointer to \ref ARM_USART_PowerControl : Control USART Interface Power.
 326   int32_t                (*Send)            (const void *data, uint32_t num);    ///< Pointer to \ref ARM_USART_Send : Start sending data to USART transmitter.
 327   int32_t                (*Receive)         (      void *data, uint32_t num);    ///< Pointer to \ref ARM_USART_Receive : Start receiving data from USART receiver.
 328   int32_t                (*Transfer)        (const void *data_out,
 329                                                    void *data_in,
 330                                              uint32_t    num);                   ///< Pointer to \ref ARM_USART_Transfer : Start sending/receiving data to/from USART.
 331   uint32_t               (*GetTxCount)      (void);                              ///< Pointer to \ref ARM_USART_GetTxCount : Get transmitted data count.
 332   uint32_t               (*GetRxCount)      (void);                              ///< Pointer to \ref ARM_USART_GetRxCount : Get received data count.
 333   int32_t                (*Control)         (uint32_t control, uint32_t arg);    ///< Pointer to \ref ARM_USART_Control : Control USART Interface.
 334   ARM_USART_STATUS       (*GetStatus)       (void);                              ///< Pointer to \ref ARM_USART_GetStatus : Get USART status.
 335   int32_t                (*SetModemControl) (ARM_USART_MODEM_CONTROL control);   ///< Pointer to \ref ARM_USART_SetModemControl : Set USART Modem Control line state.
 336   ARM_USART_MODEM_STATUS (*GetModemStatus)  (void);                              ///< Pointer to \ref ARM_USART_GetModemStatus : Get USART Modem Status lines state.
 337 } const ARM_DRIVER_USART;
 338
 339 #ifdef  __cplusplus
 340 }
 341 #endif
 342
 343 #endif /* DRIVER_USART_H_ */