1 /** 2 * 3 * \file 4 * 5 * \brief SAM UART Driver for SAMB11 6 * 7 * Copyright (C) 2015-2016 Atmel Corporation. All rights reserved. 8 * 9 * \asf_license_start 10 * 11 * \page License 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions are met: 15 * 16 * 1. Redistributions of source code must retain the above copyright notice, 17 * this list of conditions and the following disclaimer. 18 * 19 * 2. Redistributions in binary form must reproduce the above copyright notice, 20 * this list of conditions and the following disclaimer in the documentation 21 * and/or other materials provided with the distribution. 22 * 23 * 3. The name of Atmel may not be used to endorse or promote products derived 24 * from this software without specific prior written permission. 25 * 26 * 4. This software may only be redistributed and used in connection with an 27 * Atmel microcontroller product. 28 * 29 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 30 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 31 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 32 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 33 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 34 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 35 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 36 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 37 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 38 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 39 * POSSIBILITY OF SUCH DAMAGE. 40 * 41 * \asf_license_stop 42 * 43 */ 44 /* 45 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> 46 */ 47 48 #ifndef UART_H_INCLUDED 49 #define UART_H_INCLUDED 50 51 /** 52 * \defgroup asfdoc_samb_uart_group SAM UART Driver (UART) 53 * 54 * This driver for Atmel® | SMART SAM devices provides an interface for the 55 * configuration and management of the device's Universal Asynchronous 56 * Receiver/Transmitter (UART) interfaces functionality. 57 * 58 * The following peripherals are used by this module: 59 * - UART (Universal Asynchronous Receiver/Transmitter) 60 * 61 * The following devices can use this module: 62 * - Atmel | SMART SAM B11 63 * 64 * The outline of this documentation is as follows: 65 * - \ref asfdoc_samb_uart_prerequisites 66 * - \ref asfdoc_samb_uart_module_overview 67 * - \ref asfdoc_samb_uart_special_considerations 68 * - \ref asfdoc_samb_uart_extra_info 69 * - \ref asfdoc_samb_uart_examples 70 * - \ref asfdoc_samb_uart_api_overview 71 * 72 * 73 * \section asfdoc_samb_uart_prerequisites Prerequisites 74 * 75 * There are no prerequisites for this module. 76 * 77 * 78 * \section asfdoc_samb_uart_module_overview Module Overview 79 * 80 * The device UART module provides an interface between the user application 81 * logic and hardware peripheral. This driver provides an easy-to-use interface 82 * to transfer and receive data. 83 * 84 * \section asfdoc_samb_uart_special_considerations Special Considerations 85 * 86 * There are no special considerations for this module. 87 * 88 * \section asfdoc_samb_uart_extra_info Extra Information 89 * 90 * For extra information, see \ref asfdoc_samb_uart_extra. This includes: 91 * - \ref asfdoc_samb_uart_extra_acronyms 92 * - \ref asfdoc_samb_uart_extra_dependencies 93 * - \ref asfdoc_samb_uart_extra_errata 94 * - \ref asfdoc_samb_uart_extra_history 95 * 96 * 97 * \section asfdoc_samb_uart_examples Examples 98 * 99 * For a list of examples related to this driver, see 100 * \ref asfdoc_samb_uart_exqsg. 101 * 102 * 103 * \section asfdoc_samb_uart_api_overview API Overview 104 * @{ 105 */ 106 107 #include <compiler.h> 108 #include <system_sam_b.h> 109 #include <gpio.h> 110 111 #ifdef __cplusplus 112 extern "C" { 113 #endif 114 115 /** \brief UART byte bit selection 116 * 117 * Number of bit per byte selection for UART communication. 118 */ 119 enum uart_number_of_bit_selection{ 120 /** 8 bit per byte*/ 121 UART_8_BITS = UART_CONFIGURATION_NUMBER_OF_BITS_0, 122 /** 7 bit per byte*/ 123 UART_7_BITS = UART_CONFIGURATION_NUMBER_OF_BITS_1, 124 }; 125 126 /** \brief UART stop bit selection 127 * 128 * Number of stop bit selection for UART communication. 129 */ 130 enum uart_stop_bit_selection{ 131 /** 1 stop bit per byte*/ 132 UART_1_STOP_BIT = UART_CONFIGURATION_STOP_BITS_0, 133 /** 2 stop bit per byte*/ 134 UART_2_STOP_BITS = UART_CONFIGURATION_STOP_BITS_1, 135 }; 136 137 138 /** \brief UART Parity selection 139 * 140 * Parity type selection for UART communication. 141 */ 142 enum uart_parity_selection{ 143 /** No parity bit */ 144 UART_NO_PARITY = 0, 145 /** Even parity */ 146 UART_EVEN_PARITY, 147 /** Odd parity */ 148 UART_ODD_PARITY, 149 /** Space parity */ 150 UART_SPACE_PARITY, 151 /** Mark parity */ 152 UART_MARK_PARITY 153 }; 154 155 /** 156 * \brief UART module instance 157 * 158 * Forward Declaration for the device instance. 159 */ 160 struct uart_module; 161 162 /** 163 * \brief UART callback type 164 * 165 * Type of the callback functions. 166 */ 167 typedef void (*uart_callback_t)(struct uart_module *const module); 168 169 /** 170 * \brief UART Callback enum 171 * 172 * Callbacks for the UART driver. 173 */ 174 enum uart_callback { 175 /** Callback for TX FIFO not full. */ 176 UART_TX_COMPLETE, 177 /** Callback for CTS active. */ 178 UART_CTS_ACTIVE, 179 /** Callback for RX FIFO overrun. */ 180 UART_RX_COMPLETE, 181 /** Callback for RX FIFO overrun. */ 182 UART_RX_FIFO_OVERRUN, 183 /** Number of available callbacks. */ 184 UART_CALLBACK_N, 185 }; 186 187 188 /** 189 * \brief Configuration structure for the UART module 190 * 191 * This is the configuration structure for the UART Module in SAMB11. It 192 * is used as an argument for \ref uart_init to provide the desired 193 * configurations for the module. The structure should be initialized using the 194 * \ref uart_get_config_defaults . 195 */ 196 struct uart_config{ 197 /** Baud rate */ 198 uint32_t baud_rate; 199 /** Number of data bits */ 200 enum uart_number_of_bit_selection data_bits; 201 /** Number of stop bits */ 202 enum uart_stop_bit_selection stop_bits; 203 /** Parity type */ 204 enum uart_parity_selection parity; 205 /** flow control type */ 206 bool flow_control; 207 /** UART PAD pin number */ 208 uint32_t pin_number_pad[4]; 209 /** UART PAD pinmux selection */ 210 uint32_t pinmux_sel_pad[4]; 211 }; 212 213 /** 214 * \brief UART driver software device instance structure. 215 * 216 * UART driver software instance structure, used to retain software 217 * state information of an associated hardware module instance. 218 * 219 * \note The fields of this structure should not be altered by the user 220 * application; they are reserved for module-internal use only. 221 */ 222 struct uart_module { 223 /** Pointer to the hardware instance. */ 224 Uart *hw; 225 /** Array to store callback function pointers in. */ 226 uart_callback_t callback[UART_CALLBACK_N]; 227 /** Buffer pointer to where the next received character will be put */ 228 volatile uint8_t *rx_buffer_ptr; 229 /** Buffer pointer to where the next character will be transmitted from 230 **/ 231 volatile uint8_t *tx_buffer_ptr; 232 /** Remaining characters to receive */ 233 volatile uint16_t remaining_rx_buffer_length; 234 /** Remaining characters to transmit */ 235 volatile uint16_t remaining_tx_buffer_length; 236 /** Bit mask for callbacks registered. */ 237 uint8_t callback_reg_mask; 238 /** Bit mask for callbacks enabled. */ 239 uint8_t callback_enable_mask; 240 /** Holds the status of the ongoing or last operation */ 241 volatile enum status_code status; 242 }; 243 244 /** \name UART Configuration and initialization 245 * @{ 246 */ 247 void uart_get_config_defaults(struct uart_config *const config); 248 enum status_code uart_init(struct uart_module *const module, Uart * const hw, 249 const struct uart_config *const config); 250 /** @} */ 251 252 /** \name UART read and write functions 253 * @{ 254 */ 255 enum status_code uart_write_wait(struct uart_module *const module, 256 const uint8_t tx_data); 257 enum status_code uart_read_wait(struct uart_module *const module, 258 uint8_t *const rx_data); 259 enum status_code uart_write_buffer_wait(struct uart_module *const module, 260 const uint8_t *tx_data, uint32_t length); 261 enum status_code uart_read_buffer_wait(struct uart_module *const module, 262 uint8_t *rx_data, uint16_t length); 263 enum status_code uart_write_buffer_job(struct uart_module *const module, 264 uint8_t *tx_data, uint32_t length); 265 enum status_code uart_read_buffer_job(struct uart_module *const module, 266 uint8_t *rx_data, uint16_t length); 267 /** @} */ 268 269 /** \name UART callback config 270 * @{ 271 */ 272 void uart_register_callback(struct uart_module *const module, 273 uart_callback_t callback_func, 274 enum uart_callback callback_type); 275 void uart_unregister_callback(struct uart_module *module, 276 enum uart_callback callback_type); 277 void uart_enable_callback(struct uart_module *const module, 278 enum uart_callback callback_type); 279 void uart_disable_callback(struct uart_module *const module, 280 enum uart_callback callback_type); 281 /** @}*/ 282 283 /** \name UART DAM enable/disable functions 284 * @{ 285 */ 286 void uart_enable_transmit_dma(struct uart_module *const module); 287 void uart_disable_transmit_dma(struct uart_module *const module); 288 void uart_enable_receive_dma(struct uart_module *const module); 289 void uart_disable_receive_dma(struct uart_module *const module); 290 /** @}*/ 291 292 /** @}*/ 293 294 #ifdef __cplusplus 295 } 296 #endif 297 298 299 /** 300 * \page asfdoc_samb_uart_extra Extra Information for UART Driver 301 * 302 * \section asfdoc_samb_uart_extra_acronyms Acronyms 303 * Below is a table listing the acronyms used in this module, along with their 304 * intended meanings. 305 * 306 * <table> 307 * <tr> 308 * <th>Acronym</th> 309 * <th>Description</th> 310 * </tr> 311 * <tr> 312 * <td>UART</td> 313 * <td>Universal Asynchronous Receiver/Transmitter</td> 314 * </tr> 315 * </table> 316 * 317 * 318 * \section asfdoc_samb_uart_extra_dependencies Dependencies 319 * There are no dependencies related to this driver. 320 * 321 * 322 * \section asfdoc_samb_uart_extra_errata Errata 323 * There are no errata related to this driver. 324 * 325 * 326 * \section asfdoc_samb_uart_extra_history Module History 327 * An overview of the module history is presented in the table below, with 328 * details on the enhancements and fixes made to the module since its first 329 * release. The current version of this corresponds to the newest version in 330 * the table. 331 * 332 * <table> 333 * <tr> 334 * <th>Changelog</th> 335 * </tr> 336 * <tr> 337 * <td>Initial Release</td> 338 * </tr> 339 * </table> 340 */ 341 342 /** 343 * \page asfdoc_samb_uart_exqsg Examples for UART Driver 344 * 345 * This is a list of the available Quick Start guides (QSGs) and example 346 * applications for \ref asfdoc_samb_uart_group. QSGs are simple examples with 347 * step-by-step instructions to configure and use this driver in a selection of 348 * use cases. Note that QSGs can be compiled as a standalone application or be 349 * added to the user application. 350 * 351 * - \subpage asfdoc_samb_uart_basic_use_case 352 * - \subpage asfdoc_samb_uart_dma_use_case 353 * 354 * \page asfdoc_samb_uart_document_revision_history Document Revision History 355 * 356 * <table> 357 * <tr> 358 * <th>Doc. Rev.</td> 359 * <th>Date</td> 360 * <th>Comments</td> 361 * </tr> 362 * <tr> 363 * <td>A</td> 364 * <td>09/2015</td> 365 * <td>Initial release</td> 366 * </tr> 367 * </table> 368 */ 369 370 #endif 371