tool/mbed/mbed-sdk/libraries/mbed/targets/cmsis/TARGET_STM/TARGET_STM32F3/stm32f3xx_hal_uart_ex.c

   1 /**
   2   ******************************************************************************
   3   * @file    stm32f3xx_hal_uart_ex.c
   4   * @author  MCD Application Team
   5   * @version V1.1.0
   6   * @date    12-Sept-2014
   7   * @brief   Extended UART HAL module driver.
   8   *
   9   *          This file provides firmware functions to manage the following extended
  10   *          functionalities of the Universal Asynchronous Receiver Transmitter Peripheral (UART).
  11   *           + Initialization and de-initialization functions
  12   *           + Peripheral Control functions
  13   *
  14   *
  15   @verbatim
  16  ===============================================================================
  17                         ##### How to use this driver #####
  18  ===============================================================================
  19     [..]
  20     The UART HAL driver can be used as follows:
  21
  22     (#) Declare a UART_HandleTypeDef handle structure.
  23
  24     (#) For the UART RS485 Driver Enabled mode, initialize the UART registers
  25         by calling the HAL_RS485Ex_Init() API.
  26
  27
  28   @endverbatim
  29   ******************************************************************************
  30   * @attention
  31   *
  32   * <h2><center>&copy; COPYRIGHT(c) 2014 STMicroelectronics</center></h2>
  33   *
  34   * Redistribution and use in source and binary forms, with or without modification,
  35   * are permitted provided that the following conditions are met:
  36   *   1. Redistributions of source code must retain the above copyright notice,
  37   *      this list of conditions and the following disclaimer.
  38   *   2. Redistributions in binary form must reproduce the above copyright notice,
  39   *      this list of conditions and the following disclaimer in the documentation
  40   *      and/or other materials provided with the distribution.
  41   *   3. Neither the name of STMicroelectronics nor the names of its contributors
  42   *      may be used to endorse or promote products derived from this software
  43   *      without specific prior written permission.
  44   *
  45   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  46   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  47   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  48   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  49   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  50   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  51   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  52   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  53   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  54   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  55   *
  56   ******************************************************************************
  57   */
  58
  59 /* Includes ------------------------------------------------------------------*/
  60 #include "stm32f3xx_hal.h"
  61
  62 /** @addtogroup STM32F3xx_HAL_Driver
  63   * @{
  64   */
  65
  66 /** @defgroup UARTEx UART Extended HAL module driver
  67   * @brief UART Extended HAL module driver
  68   * @{
  69   */
  70 #ifdef HAL_UART_MODULE_ENABLED
  71
  72 /* Private typedef -----------------------------------------------------------*/
  73 /* Private define ------------------------------------------------------------*/
  74 /* Private macro -------------------------------------------------------------*/
  75 /* Private variables ---------------------------------------------------------*/
  76 /* Private function prototypes -----------------------------------------------*/
  77 /* Exported functions --------------------------------------------------------*/
  78
  79 /** @defgroup UARTEx_Exported_Functions UART Extended Exported Functions
  80   * @{
  81   */
  82
  83 /** @defgroup UARTEx_Exported_Functions_Group1 Extended Initialization and de-initialization functions
  84   * @brief    Extended Initialization and Configuration Functions
  85   *
  86 @verbatim
  87 ===============================================================================
  88             ##### Initialization and Configuration functions #####
  89  ===============================================================================
  90     [..]
  91     This subsection provides a set of functions allowing to initialize the USARTx or the UARTy
  92     in asynchronous mode.
  93       (+) For the asynchronous mode only these parameters can be configured:
  94         (++) Baud Rate
  95         (++) Word Length
  96         (++) Stop Bit
  97         (++) Parity: If the parity is enabled, then the MSB bit of the data written
  98              in the data register is transmitted but is changed by the parity bit.
  99              Depending on the frame length defined by the M bit (8-bits or 9-bits)
 100              or by the M1 and M0 bits (7-bit, 8-bit or 9-bit),
 101              the possible UART frame formats are as listed in the following table:
 102    +---------------------------------------------------------------+
 103    |    M bit  |  PCE bit  |            UART frame                 |
 104    |-----------|-----------|---------------------------------------|
 105    |     0     |     0     |    | SB | 8-bit data | STB |          |
 106    |-----------|-----------|---------------------------------------|
 107    |     0     |     1     |    | SB | 7-bit data | PB | STB |     |
 108    |-----------|-----------|---------------------------------------|
 109    |     1     |     0     |    | SB | 9-bit data | STB |          |
 110    |-----------|-----------|---------------------------------------|
 111    |     1     |     1     |    | SB | 8-bit data | PB | STB |     |
 112    +---------------------------------------------------------------+
 113    | M1M0 bits |  PCE bit  |            UART frame                 |
 114    |-----------------------|---------------------------------------|
 115    |     10    |     0     |    | SB | 7-bit data | STB |          |
 116    |-----------|-----------|---------------------------------------|
 117    |     10    |     1     |    | SB | 6-bit data | PB | STB |     |
 118    +---------------------------------------------------------------+
 119         (++) Hardware flow control
 120         (++) Receiver/transmitter modes
 121         (++) Over Sampling Method
 122         (++) One-Bit Sampling Method
 123       (+) For the asynchronous mode, the following advanced features can be configured as well:
 124         (++) TX and/or RX pin level inversion
 125         (++) data logical level inversion
 126         (++) RX and TX pins swap
 127         (++) RX overrun detection disabling
 128         (++) DMA disabling on RX error
 129         (++) MSB first on communication line
 130         (++) auto Baud rate detection
 131     [..]
 132     The HAL_RS485Ex_Init() API follows respectively the UART RS485 mode
 133     configuration procedures (details for the procedures are available in reference manual).
 134
 135 @endverbatim
 136   * @{
 137   */
 138
 139
 140 /**
 141   * @brief Initializes the RS485 Driver enable feature according to the specified
 142   *         parameters in the UART_InitTypeDef and creates the associated handle .
 143   * @param huart: uart handle
 144   * @param UART_DEPolarity: select the driver enable polarity
 145   *        This parameter can be one of the following values:
 146   *          @arg UART_DE_POLARITY_HIGH: DE signal is active high
 147   *          @arg UART_DE_POLARITY_LOW: DE signal is active low
 148   * @param UART_DEAssertionTime: Driver Enable assertion time
 149   *                         5-bit value defining the time between the activation of the DE (Driver Enable)
 150   *                         signal and the beginning of the start bit. It is expressed in sample time
 151   *                         units (1/8 or 1/16 bit time, depending on the oversampling rate)
 152   * @param UART_DEDeassertionTime: Driver Enable deassertion time
 153   *                         5-bit value defining the time between the end of the last stop bit, in a
 154   *                         transmitted message, and the de-activation of the DE (Driver Enable) signal.
 155   *                         It is expressed in sample time units (1/8 or 1/16 bit time, depending on the
 156   *                         oversampling rate).
 157   * @retval HAL status
 158   */
 159 HAL_StatusTypeDef HAL_RS485Ex_Init(UART_HandleTypeDef *huart, uint32_t UART_DEPolarity, uint32_t UART_DEAssertionTime, uint32_t UART_DEDeassertionTime)
 160 {
 161   uint32_t temp = 0x0;
 162
 163   /* Check the UART handle allocation */
 164   if(huart == HAL_NULL)
 165   {
 166     return HAL_ERROR;
 167   }
 168   /* Check the Driver Enable UART instance */
 169   assert_param(IS_UART_DRIVER_ENABLE_INSTANCE(huart->Instance));
 170
 171   /* Check the Driver Enable polarity */
 172   assert_param(IS_UART_DE_POLARITY(UART_DEPolarity));
 173
 174   /* Check the Driver Enable assertion time */
 175   assert_param(IS_UART_ASSERTIONTIME(UART_DEAssertionTime));
 176
 177   /* Check the Driver Enable deassertion time */
 178   assert_param(IS_UART_DEASSERTIONTIME(UART_DEDeassertionTime));
 179
 180   if(huart->State == HAL_UART_STATE_RESET)
 181   {
 182     /* Init the low level hardware : GPIO, CLOCK */
 183     HAL_UART_MspInit(huart);
 184   }
 185
 186   huart->State = HAL_UART_STATE_BUSY;
 187
 188   /* Disable the Peripheral */
 189   __HAL_UART_DISABLE(huart);
 190
 191   /* Set the UART Communication parameters */
 192   if (UART_SetConfig(huart) == HAL_ERROR)
 193   {
 194     return HAL_ERROR;
 195   }
 196
 197   if (huart->AdvancedInit.AdvFeatureInit != UART_ADVFEATURE_NO_INIT)
 198   {
 199     UART_AdvFeatureConfig(huart);
 200   }
 201
 202   /* Enable the Driver Enable mode by setting the DEM bit in the CR3 register */
 203   huart->Instance->CR3 |= USART_CR3_DEM;
 204
 205   /* Set the Driver Enable polarity */
 206   MODIFY_REG(huart->Instance->CR3, USART_CR3_DEP, UART_DEPolarity);
 207
 208   /* Set the Driver Enable assertion and deassertion times */
 209   temp = (UART_DEAssertionTime << UART_CR1_DEAT_ADDRESS_LSB_POS);
 210   temp |= (UART_DEDeassertionTime << UART_CR1_DEDT_ADDRESS_LSB_POS);
 211   MODIFY_REG(huart->Instance->CR1, (USART_CR1_DEDT|USART_CR1_DEAT), temp);
 212
 213   /* Enable the Peripheral */
 214   __HAL_UART_ENABLE(huart);
 215
 216   /* TEACK and/or REACK to check before moving huart->State to Ready */
 217   return (UART_CheckIdleState(huart));
 218 }
 219
 220
 221 /**
 222   * @}
 223   */
 224
 225 /** @defgroup UARTEx_Exported_Functions_Group2 Extended Peripheral Control functions
 226   * @brief    Extended Peripheral Control functions
 227   *
 228 @verbatim
 229  ===============================================================================
 230                       ##### Peripheral Control functions #####
 231  ===============================================================================
 232     [..]
 233     This subsection provides an extended function allowing to control the UART.
 234      (+) HAL_MultiProcessorEx_AddressLength_Set() API optionally sets the UART node address
 235          detection length to more than 4 bits for multiprocessor address mark wake up.
 236      (+) HAL_UARTEx_StopModeWakeUpSourceConfig() configures the address for wake-up from
 237           Stop mode based on address match
 238      (+) HAL_UARTEx_EnableStopMode() API enables the UART to wake up the MCU from stop mode
 239      (+) HAL_UARTEx_DisableStopMode() API disables the above functionality
 240 @endverbatim
 241   * @{
 242   */
 243
 244
 245
 246 /**
 247   * @brief By default in multiprocessor mode, when the wake up method is set
 248   *        to address mark, the UART handles only 4-bit long addresses detection.
 249   *        This API allows to enable longer addresses detection (6-, 7- or 8-bit
 250   *        long):
 251   *        - 6-bit address detection in 7-bit data mode
 252   *        - 7-bit address detection in 8-bit data mode
 253   *        - 8-bit address detection in 9-bit data mode
 254   * @param huart: UART handle
 255   * @param AddressLength: this parameter can be one of the following values:
 256   *          @arg UART_ADDRESS_DETECT_4B: 4-bit long address
 257   *          @arg UART_ADDRESS_DETECT_7B: 6-, 7- or 8-bit long address
 258   * @retval HAL status
 259   */
 260 HAL_StatusTypeDef HAL_MultiProcessorEx_AddressLength_Set(UART_HandleTypeDef *huart, uint32_t AddressLength)
 261 {
 262   /* Check the UART handle allocation */
 263   if(huart == HAL_NULL)
 264   {
 265     return HAL_ERROR;
 266   }
 267
 268   /* Check the address length parameter */
 269   assert_param(IS_UART_ADDRESSLENGTH_DETECT(AddressLength));
 270
 271   huart->State = HAL_UART_STATE_BUSY;
 272
 273   /* Disable the Peripheral */
 274   __HAL_UART_DISABLE(huart);
 275
 276   /* Set the address length */
 277   MODIFY_REG(huart->Instance->CR2, USART_CR2_ADDM7, AddressLength);
 278
 279   /* Enable the Peripheral */
 280   __HAL_UART_ENABLE(huart);
 281
 282   /* TEACK and/or REACK to check before moving huart->State to Ready */
 283   return (UART_CheckIdleState(huart));
 284 }
 285
 286
 287 /**
 288   * @brief Set Wakeup from Stop mode interrupt flag selection
 289   * @param huart: uart handle,
 290   * @param WakeUpSelection: address match, Start Bit detection or RXNE bit status.
 291   * This parameter can be one of the following values:
 292   *      @arg UART_WAKEUP_ON_ADDRESS
 293   *      @arg UART_WAKEUP_ON_STARTBIT
 294   *      @arg UART_WAKEUP_ON_READDATA_NONEMPTY
 295   * @retval HAL status
 296   */
 297 HAL_StatusTypeDef HAL_UARTEx_StopModeWakeUpSourceConfig(UART_HandleTypeDef *huart, UART_WakeUpTypeDef WakeUpSelection)
 298 {
 299
 300   /* check the wake-up from stop mode UART instance */
 301   assert_param(IS_UART_WAKEUP_FROMSTOP_INSTANCE(huart->Instance));
 302   /* check the wake-up selection parameter */
 303   assert_param(IS_UART_WAKEUP_SELECTION(WakeUpSelection.WakeUpEvent));
 304
 305   /* Process Locked */
 306   __HAL_LOCK(huart);
 307
 308   huart->State = HAL_UART_STATE_BUSY;
 309
 310   /* Disable the Peripheral */
 311   __HAL_UART_DISABLE(huart);
 312
 313   /* Set the wake-up selection scheme */
 314   MODIFY_REG(huart->Instance->CR3, USART_CR3_WUS, WakeUpSelection.WakeUpEvent);
 315
 316   if (WakeUpSelection.WakeUpEvent == UART_WAKEUP_ON_ADDRESS)
 317   {
 318     UART_Wakeup_AddressConfig(huart, WakeUpSelection);
 319   }
 320
 321   /* Enable the Peripheral */
 322   __HAL_UART_ENABLE(huart);
 323
 324   /* Wait until REACK flag is set */
 325   if(UART_WaitOnFlagUntilTimeout(huart, USART_ISR_REACK, RESET, HAL_UART_TIMEOUT_VALUE) != HAL_OK)
 326   {
 327     return HAL_TIMEOUT;
 328   }
 329   else
 330   {
 331     /* Initialize the UART State */
 332     huart->State= HAL_UART_STATE_READY;
 333     /* Process Unlocked */
 334     __HAL_UNLOCK(huart);
 335     return HAL_OK;
 336   }
 337 }
 338
 339
 340 /**
 341   * @brief Enable UART Stop Mode
 342   * The UART is able to wake up the MCU from Stop mode as long as UART clock is HSI or LSE
 343   * @param huart: uart handle
 344   * @retval HAL status
 345   */
 346 HAL_StatusTypeDef HAL_UARTEx_EnableStopMode(UART_HandleTypeDef *huart)
 347 {
 348   /* Process Locked */
 349   __HAL_LOCK(huart);
 350
 351   huart->State = HAL_UART_STATE_BUSY;
 352
 353   /* Set the USART UESM bit */
 354   huart->Instance->CR1 |= USART_CR1_UESM;
 355
 356   huart->State = HAL_UART_STATE_READY;
 357
 358   /* Process Unlocked */
 359   __HAL_UNLOCK(huart);
 360
 361   return HAL_OK;
 362 }
 363
 364 /**
 365   * @brief Disable UART Stop Mode
 366   * @param huart: uart handle
 367   * @retval HAL status
 368   */
 369 HAL_StatusTypeDef HAL_UARTEx_DisableStopMode(UART_HandleTypeDef *huart)
 370 {
 371   /* Process Locked */
 372   __HAL_LOCK(huart);
 373
 374   huart->State = HAL_UART_STATE_BUSY;
 375
 376   /* Clear USART UESM bit */
 377   huart->Instance->CR1 &= ~(USART_CR1_UESM);
 378
 379   huart->State = HAL_UART_STATE_READY;
 380
 381   /* Process Unlocked */
 382   __HAL_UNLOCK(huart);
 383
 384   return HAL_OK;
 385 }
 386
 387
 388 /**
 389   * @}
 390   */
 391
 392 /**
 393   * @}
 394   */
 395
 396 #endif /* HAL_UART_MODULE_ENABLED */
 397 /**
 398   * @}
 399   */
 400
 401 /**
 402   * @}
 403   */
 404
 405 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/