1 /** 2 * \file 3 * 4 * \brief USART related functionality declaration. 5 * 6 * Copyright (C) 2014 Atmel Corporation. All rights reserved. 7 * 8 * \asf_license_start 9 * 10 * \page License 11 * 12 * Redistribution and use in source and binary forms, with or without 13 * modification, are permitted provided that the following conditions are met: 14 * 15 * 1. Redistributions of source code must retain the above copyright notice, 16 * this list of conditions and the following disclaimer. 17 * 18 * 2. Redistributions in binary form must reproduce the above copyright notice, 19 * this list of conditions and the following disclaimer in the documentation 20 * and/or other materials provided with the distribution. 21 * 22 * 3. The name of Atmel may not be used to endorse or promote products derived 23 * from this software without specific prior written permission. 24 * 25 * 4. This software may only be redistributed and used in connection with an 26 * Atmel microcontroller product. 27 * 28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 38 * POSSIBILITY OF SUCH DAMAGE. 39 * 40 * \asf_license_stop 41 * 42 */ 43 44 #ifndef _HPL_USART_ASYNC_H_INCLUDED 45 #define _HPL_USART_ASYNC_H_INCLUDED 46 47 /** 48 * \addtogroup HPL USART 49 * 50 * \section hpl_usart_rev Revision History 51 * - v1.0.0 Initial Release 52 * 53 *@{ 54 */ 55 56 #include "hpl_usart.h" 57 #include "hpl_irq.h" 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /** 64 * \brief USART callback types 65 */ 66 enum _usart_async_callback_type { USART_ASYNC_BYTE_SENT, USART_ASYNC_RX_DONE, USART_ASYNC_TX_DONE, USART_ASYNC_ERROR }; 67 68 /** 69 * \brief USART device structure 70 * 71 * The USART device structure forward declaration. 72 */ 73 struct _usart_async_device; 74 75 /** 76 * \brief USART interrupt callbacks 77 */ 78 struct _usart_async_callbacks { 79 void (*tx_byte_sent)(struct _usart_async_device *device); 80 void (*rx_done_cb)(struct _usart_async_device *device, uint8_t data); 81 void (*tx_done_cb)(struct _usart_async_device *device); 82 void (*error_cb)(struct _usart_async_device *device); 83 }; 84 85 /** 86 * \brief USART descriptor device structure 87 */ 88 struct _usart_async_device { 89 struct _usart_async_callbacks usart_cb; 90 struct _irq_descriptor irq; 91 void * hw; 92 }; 93 /** 94 * \name HPL functions 95 */ 96 //@{ 97 /** 98 * \brief Initialize asynchronous USART 99 * 100 * This function does low level USART configuration. 101 * 102 * \param[in] device The pointer to USART device instance 103 * \param[in] hw The pointer to hardware instance 104 * 105 * \return Initialization status 106 */ 107 int32_t _usart_async_init(struct _usart_async_device *const device, void *const hw); 108 109 /** 110 * \brief Deinitialize USART 111 * 112 * This function closes the given USART by disabling its clock. 113 * 114 * \param[in] device The pointer to USART device instance 115 */ 116 void _usart_async_deinit(struct _usart_async_device *const device); 117 118 /** 119 * \brief Enable usart module 120 * 121 * This function will enable the usart module 122 * 123 * \param[in] device The pointer to USART device instance 124 */ 125 void _usart_async_enable(struct _usart_async_device *const device); 126 127 /** 128 * \brief Disable usart module 129 * 130 * This function will disable the usart module 131 * 132 * \param[in] device The pointer to USART device instance 133 */ 134 void _usart_async_disable(struct _usart_async_device *const device); 135 136 /** 137 * \brief Calculate baud rate register value 138 * 139 * \param[in] baud Required baud rate 140 * \param[in] clock_rate clock frequency 141 * \param[in] samples The number of samples 142 * \param[in] mode USART mode 143 * \param[in] fraction A fraction value 144 * 145 * \return Calculated baud rate register value 146 */ 147 uint16_t _usart_async_calculate_baud_rate(const uint32_t baud, const uint32_t clock_rate, const uint8_t samples, 148 const enum usart_baud_rate_mode mode, const uint8_t fraction); 149 150 /** 151 * \brief Set baud rate 152 * 153 * \param[in] device The pointer to USART device instance 154 * \param[in] baud_rate A baud rate to set 155 */ 156 void _usart_async_set_baud_rate(struct _usart_async_device *const device, const uint32_t baud_rate); 157 158 /** 159 * \brief Set data order 160 * 161 * \param[in] device The pointer to USART device instance 162 * \param[in] order A data order to set 163 */ 164 void _usart_async_set_data_order(struct _usart_async_device *const device, const enum usart_data_order order); 165 166 /** 167 * \brief Set mode 168 * 169 * \param[in] device The pointer to USART device instance 170 * \param[in] mode A mode to set 171 */ 172 void _usart_async_set_mode(struct _usart_async_device *const device, const enum usart_mode mode); 173 174 /** 175 * \brief Set parity 176 * 177 * \param[in] device The pointer to USART device instance 178 * \param[in] parity A parity to set 179 */ 180 void _usart_async_set_parity(struct _usart_async_device *const device, const enum usart_parity parity); 181 182 /** 183 * \brief Set stop bits mode 184 * 185 * \param[in] device The pointer to USART device instance 186 * \param[in] stop_bits A stop bits mode to set 187 */ 188 void _usart_async_set_stop_bits(struct _usart_async_device *const device, const enum usart_stop_bits stop_bits); 189 190 /** 191 * \brief Set character size 192 * 193 * \param[in] device The pointer to USART device instance 194 * \param[in] size A character size to set 195 */ 196 void _usart_async_set_character_size(struct _usart_async_device *const device, const enum usart_character_size size); 197 198 /** 199 * \brief Retrieve usart status 200 * 201 * \param[in] device The pointer to USART device instance 202 */ 203 uint32_t _usart_async_get_status(const struct _usart_async_device *const device); 204 205 /** 206 * \brief Write a byte to the given USART instance 207 * 208 * \param[in] device The pointer to USART device instance 209 * \param[in] data Data to write 210 */ 211 void _usart_async_write_byte(struct _usart_async_device *const device, uint8_t data); 212 213 /** 214 * \brief Check if USART is ready to send next byte 215 * 216 * \param[in] device The pointer to USART device instance 217 * 218 * \return Status of the ready check. 219 * \retval true if the USART is ready to send next byte 220 * \retval false if the USART is not ready to send next byte 221 */ 222 bool _usart_async_is_byte_sent(const struct _usart_async_device *const device); 223 224 /** 225 * \brief Set the state of flow control pins 226 * 227 * \param[in] device The pointer to USART device instance 228 * \param[in] state - A state of flow control pins to set 229 */ 230 void _usart_async_set_flow_control_state(struct _usart_async_device *const device, 231 const union usart_flow_control_state state); 232 233 /** 234 * \brief Retrieve the state of flow control pins 235 * 236 * This function retrieves the of flow control pins. 237 * 238 * \return USART_FLOW_CONTROL_STATE_UNAVAILABLE. 239 */ 240 union usart_flow_control_state _usart_async_get_flow_control_state(const struct _usart_async_device *const device); 241 242 /** 243 * \brief Enable data register empty interrupt 244 * 245 * \param[in] device The pointer to USART device instance 246 */ 247 void _usart_async_enable_byte_sent_irq(struct _usart_async_device *const device); 248 249 /** 250 * \brief Enable transmission complete interrupt 251 * 252 * \param[in] device The pointer to USART device instance 253 */ 254 void _usart_async_enable_tx_done_irq(struct _usart_async_device *const device); 255 256 /** 257 * \brief Retrieve ordinal number of the given USART hardware instance 258 * 259 * \param[in] device The pointer to USART device instance 260 * 261 * \return The ordinal number of the given USART hardware instance 262 */ 263 uint8_t _usart_async_get_hardware_index(const struct _usart_async_device *const device); 264 265 /** 266 * \brief Enable/disable USART interrupt 267 * 268 * param[in] device The pointer to USART device instance 269 * param[in] type The type of interrupt to disable/enable if applicable 270 * param[in] state Enable or disable 271 */ 272 void _usart_async_set_irq_state(struct _usart_async_device *const device, const enum _usart_async_callback_type type, 273 const bool state); 274 //@} 275 276 #ifdef __cplusplus 277 } 278 #endif 279 /**@}*/ 280 #endif /* _HPL_USART_ASYNC_H_INCLUDED */ 281
