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 _HAL_SYNC_USART_H_INCLUDED 45 #define _HAL_SYNC_USART_H_INCLUDED 46 47 #include "hal_io.h" 48 #include <hpl_usart_sync.h> 49 50 /** 51 * \addtogroup doc_driver_hal_usart_sync 52 * 53 * @{ 54 */ 55 56 #ifdef __cplusplus 57 extern "C" { 58 #endif 59 60 /** 61 * \brief Synchronous USART descriptor 62 */ 63 struct usart_sync_descriptor { 64 struct io_descriptor io; 65 struct _usart_sync_device device; 66 }; 67 68 /** 69 * \brief Initialize USART interface 70 * 71 * This function initializes the given I/O descriptor to be used 72 * as USART interface descriptor. 73 * It checks if the given hardware is not initialized and 74 * if the given hardware is permitted to be initialized. 75 * 76 * \param[out] descr A USART descriptor which is used to communicate via USART 77 * \param[in] hw The pointer to hardware instance 78 * \param[in] func The pointer to as set of functions pointers 79 * 80 * \return Initialization status. 81 */ 82 int32_t usart_sync_init(struct usart_sync_descriptor *const descr, void *const hw, void *const func); 83 84 /** 85 * \brief Deinitialize USART interface 86 * 87 * This function deinitializes the given I/O descriptor. 88 * It checks if the given hardware is initialized and 89 * if the given hardware is permitted to be deinitialized. 90 * 91 * \param[in] descr A USART descriptor which is used to communicate via USART 92 * 93 * \return De-initialization status. 94 */ 95 int32_t usart_sync_deinit(struct usart_sync_descriptor *const descr); 96 97 /** 98 * \brief Enable USART interface 99 * 100 * Enables the USART interface 101 * 102 * \param[in] descr A USART descriptor which is used to communicate via USART 103 * 104 * \return Enabling status. 105 */ 106 int32_t usart_sync_enable(struct usart_sync_descriptor *const descr); 107 108 /** 109 * \brief Disable USART interface 110 * 111 * Disables the USART interface 112 * 113 * \param[in] descr A USART descriptor which is used to communicate via USART 114 * 115 * \return Disabling status. 116 */ 117 int32_t usart_sync_disable(struct usart_sync_descriptor *const descr); 118 119 /** 120 * \brief Retrieve I/O descriptor 121 * 122 * This function retrieves the I/O descriptor of the given USART descriptor. 123 * 124 * \param[in] descr A USART descriptor which is used to communicate via USART 125 * \param[out] io An I/O descriptor to retrieve 126 * 127 * \return The status of the I/O descriptor retrieving. 128 */ 129 int32_t usart_sync_get_io_descriptor(struct usart_sync_descriptor *const descr, struct io_descriptor **io); 130 131 /** 132 * \brief Specify action for flow control pins 133 * 134 * This function sets the action (or state) for the flow control pins 135 * if the flow control is enabled. 136 * It sets the state of flow control pins only if the automatic support of 137 * the flow control is not supported by the hardware. 138 * 139 * \param[in] descr A USART descriptor which is used to communicate via USART 140 * \param[in] state A state to set the flow control pins 141 * 142 * \return The status of flow control action setup. 143 */ 144 int32_t usart_sync_set_flow_control(struct usart_sync_descriptor *const descr, 145 const union usart_flow_control_state state); 146 147 /** 148 * \brief Set USART baud rate 149 * 150 * \param[in] descr A USART descriptor which is used to communicate via USART 151 * \param[in] baud_rate A baud rate to set 152 * 153 * \return The status of baud rate setting. 154 */ 155 int32_t usart_sync_set_baud_rate(struct usart_sync_descriptor *const descr, const uint32_t baud_rate); 156 157 /** 158 * \brief Set USART data order 159 * 160 * \param[in] descr A USART descriptor which is used to communicate via USART 161 * \param[in] data_order A data order to set 162 * 163 * \return The status of data order setting. 164 */ 165 int32_t usart_sync_set_data_order(struct usart_sync_descriptor *const descr, const enum usart_data_order data_order); 166 167 /** 168 * \brief Set USART mode 169 * 170 * \param[in] descr A USART descriptor which is used to communicate via USART 171 * \param[in] mode A mode to set 172 * 173 * \return The status of mode setting. 174 */ 175 int32_t usart_sync_set_mode(struct usart_sync_descriptor *const descr, const enum usart_mode mode); 176 177 /** 178 * \brief Set USART parity 179 * 180 * \param[in] descr A USART descriptor which is used to communicate via USART 181 * \param[in] parity A parity to set 182 * 183 * \return The status of parity setting. 184 */ 185 int32_t usart_sync_set_parity(struct usart_sync_descriptor *const descr, const enum usart_parity parity); 186 187 /** 188 * \brief Set USART stop bits 189 * 190 * \param[in] descr A USART descriptor which is used to communicate via USART 191 * \param[in] stop_bits Stop bits to set 192 * 193 * \return The status of stop bits setting. 194 */ 195 int32_t usart_sync_set_stopbits(struct usart_sync_descriptor *const descr, const enum usart_stop_bits stop_bits); 196 197 /** 198 * \brief Set USART character size 199 * 200 * \param[in] descr A USART descriptor which is used to communicate via USART 201 * \param[in] size A character size to set 202 * 203 * \return The status of character size setting. 204 */ 205 int32_t usart_sync_set_character_size(struct usart_sync_descriptor *const descr, const enum usart_character_size size); 206 207 /** 208 * \brief Retrieve the state of flow control pins 209 * 210 * This function retrieves the of flow control pins 211 * if the flow control is enabled. 212 * Function can return USART_FLOW_CONTROL_STATE_UNAVAILABLE in case 213 * if the flow control is done by the hardware 214 * and the pins state cannot be read out. 215 * 216 * \param[in] descr A USART descriptor which is used to communicate via USART 217 * \param[out] state The state of flow control pins 218 * 219 * \return The status of flow control state reading. 220 */ 221 int32_t usart_sync_flow_control_status(const struct usart_sync_descriptor *const descr, 222 union usart_flow_control_state *const state); 223 224 /** 225 * \brief Check if the USART transmitter is empty 226 * 227 * \param[in] descr A USART descriptor which is used to communicate via USART 228 * 229 * \return The status of USART TX empty checking. 230 * \retval 0 The USART transmitter is not empty 231 * \retval 1 The USART transmitter is empty 232 */ 233 int32_t usart_sync_is_tx_empty(const struct usart_sync_descriptor *const descr); 234 235 /** 236 * \brief Check if the USART receiver is not empty 237 * 238 * \param[in] descr A USART descriptor which is used to communicate via USART 239 * 240 * \return The status of USART RX empty checking. 241 * \retval 1 The USART receiver is not empty 242 * \retval 0 The USART receiver is empty 243 */ 244 int32_t usart_sync_is_rx_not_empty(const struct usart_sync_descriptor *const descr); 245 246 /** 247 * \brief Retrieve the current driver version 248 * 249 * \return Current driver version. 250 */ 251 uint32_t usart_sync_get_version(void); 252 253 #ifdef __cplusplus 254 } 255 #endif 256 /**@}*/ 257 #endif /* _HAL_SYNC_USART_H_INCLUDED */ 258
