git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_ATSAM3X_Atmel_Studio/src/asf/sam/drivers/usart/usart.h

   1 /**\r
   2  * \file\r
   3  *\r
   4  * \brief Universal Synchronous Asynchronous Receiver Transmitter (USART) driver for SAM.\r
   5  *\r
   6  * Copyright (c) 2011-2012 Atmel Corporation. All rights reserved.\r
   7  *\r
   8  * \asf_license_start\r
   9  *\r
  10  * \page License\r
  11  *\r
  12  * Redistribution and use in source and binary forms, with or without\r
  13  * modification, are permitted provided that the following conditions are met:\r
  14  *\r
  15  * 1. Redistributions of source code must retain the above copyright notice,\r
  16  *    this list of conditions and the following disclaimer.\r
  17  *\r
  18  * 2. Redistributions in binary form must reproduce the above copyright notice,\r
  19  *    this list of conditions and the following disclaimer in the documentation\r
  20  *    and/or other materials provided with the distribution.\r
  21  *\r
  22  * 3. The name of Atmel may not be used to endorse or promote products derived\r
  23  *    from this software without specific prior written permission.\r
  24  *\r
  25  * 4. This software may only be redistributed and used in connection with an\r
  26  *    Atmel microcontroller product.\r
  27  *\r
  28  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED\r
  29  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  30  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
  31  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR\r
  32  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\r
  33  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\r
  34  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r
  35  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\r
  36  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN\r
  37  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
  38  * POSSIBILITY OF SUCH DAMAGE.\r
  39  *\r
  40  * \asf_license_stop\r
  41  *\r
  42  */\r
  43 \r
  44 #ifndef USART_H_INCLUDED\r
  45 #define USART_H_INCLUDED\r
  46 \r
  47 #include "compiler.h"\r
  48 \r
  49 /**\r
  50  * \defgroup usart_group Universal Synchronous Asynchronous Receiver Transmitter (USART)\r
  51  *\r
  52  * See \ref sam_usart_quickstart.\r
  53  *\r
  54  * This is a low-level driver implementation for the SAM Universal\r
  55  * Synchronous/Asynchronous Receiver/Transmitter.\r
  56  *\r
  57  * @{\r
  58  */\r
  59 \r
  60 /// @cond 0\r
  61 /**INDENT-OFF**/\r
  62 #ifdef __cplusplus\r
  63 extern "C" {\r
  64 #endif\r
  65 /**INDENT-ON**/\r
  66 /// @endcond\r
  67 \r
  68 /** Clock phase. */\r
  69 #define SPI_CPHA        (1 << 0)\r
  70 \r
  71 /** Clock polarity. */\r
  72 #define SPI_CPOL        (1 << 1)\r
  73 \r
  74 /** SPI mode definition. */\r
  75 #define SPI_MODE_0      (SPI_CPHA)\r
  76 #define SPI_MODE_1      0\r
  77 #define SPI_MODE_2      (SPI_CPOL | SPI_CPHA)\r
  78 #define SPI_MODE_3      (SPI_CPOL)\r
  79 \r
  80 //! Input parameters when initializing RS232 and similar modes.\r
  81 typedef struct {\r
  82         //! Set baud rate of the USART (unused in slave modes).\r
  83         uint32_t baudrate;\r
  84         \r
  85         //! Number of bits, which should be one of the following: US_MR_CHRL_5_BIT,\r
  86         //! US_MR_CHRL_6_BIT, US_MR_CHRL_7_BIT, US_MR_CHRL_8_BIT or US_MR_MODE9.\r
  87         uint32_t char_length;\r
  88         \r
  89         //! Parity type, which should be one of the following: US_MR_PAR_EVEN, US_MR_PAR_ODD,\r
  90         //! US_MR_PAR_SPACE, US_MR_PAR_MARK, US_MR_PAR_NO or US_MR_PAR_MULTIDROP.\r
  91         uint32_t parity_type;\r
  92 \r
  93         //! Number of stop bits between two characters: US_MR_NBSTOP_1_BIT,\r
  94         //! US_MR_NBSTOP_1_5_BIT, US_MR_NBSTOP_2_BIT.\r
  95         //! \note US_MR_NBSTOP_1_5_BIT is supported in asynchronous modes only.\r
  96         uint32_t stop_bits;\r
  97 \r
  98         //! Run the channel in test mode, which should be one of following: US_MR_CHMODE_NORMAL,\r
  99         //! US_MR_CHMODE_AUTOMATIC, US_MR_CHMODE_LOCAL_LOOPBACK, US_MR_CHMODE_REMOTE_LOOPBACK\r
 100         uint32_t channel_mode;\r
 101 \r
 102         //! Filter of IrDA mode, useless in other modes. \r
 103         uint32_t irda_filter;\r
 104 } sam_usart_opt_t;\r
 105 \r
 106 //! Input parameters when initializing ISO7816 mode.\r
 107 typedef struct {\r
 108         //! Set the frequency of the ISO7816 clock.\r
 109         uint32_t iso7816_hz;\r
 110         \r
 111         //! The number of ISO7816 clock ticks in every bit period (1 to 2047, 0 = disable clock).\r
 112         //! Baudrate rate = iso7816_hz / fidi_ratio\r
 113         uint32_t fidi_ratio;\r
 114 \r
 115         //! How to calculate the parity bit: US_MR_PAR_EVEN for normal mode or\r
 116         //! US_MR_PAR_ODD for inverse mode.\r
 117         uint32_t parity_type;\r
 118 \r
 119         //! Inhibit Non Acknowledge:\r
 120         //!   - 0: the NACK is generated;\r
 121         //!   - 1: the NACK is not generated.\r
 122         //!\r
 123         //! \note This bit will be used only in ISO7816 mode, protocol T = 0 receiver.\r
 124         uint32_t inhibit_nack;\r
 125 \r
 126         //! Disable successive NACKs.\r
 127         //!  - 0: NACK is sent on the ISO line as soon as a parity error occurs in the received character.\r
 128         //! Successive parity errors are counted up to the value in the max_iterations field.\r
 129         //! These parity errors generate a NACK on the ISO line. As soon as this value is reached,\r
 130         //! No additional NACK is sent on the ISO line. The ITERATION flag is asserted.\r
 131         uint32_t dis_suc_nack;\r
 132 \r
 133         //! Max number of repetitions (0 to 7).\r
 134         uint32_t max_iterations;\r
 135 \r
 136         //! Bit order in transmitted characters:\r
 137         //!   - 0: LSB first;\r
 138         //!   - 1: MSB first.\r
 139         uint32_t bit_order;\r
 140         \r
 141         //! Which protocol is used:\r
 142         //!   - 0: T = 0;\r
 143         //!   - 1: T = 1.\r
 144         uint32_t protocol_type;\r
 145 } usart_iso7816_opt_t;\r
 146 \r
 147 //! Input parameters when initializing SPI mode.\r
 148 typedef struct {\r
 149         //! Set the frequency of the SPI clock (unused in slave mode).\r
 150         uint32_t baudrate;\r
 151 \r
 152         //! Number of bits, which should be one of the following: US_MR_CHRL_5_BIT,\r
 153         //! US_MR_CHRL_6_BIT, US_MR_CHRL_7_BIT, US_MR_CHRL_8_BIT or US_MR_MODE9.\r
 154         uint32_t char_length;\r
 155 \r
 156         //! Which SPI mode to use, which should be one of the following:\r
 157         //! SPI_MODE_0, SPI_MODE_1, SPI_MODE_2, SPI_MODE_3.\r
 158         uint32_t spi_mode;\r
 159 \r
 160         //! Run the channel in test mode, which should be one of following: US_MR_CHMODE_NORMAL,\r
 161         //! US_MR_CHMODE_AUTOMATIC, US_MR_CHMODE_LOCAL_LOOPBACK, US_MR_CHMODE_REMOTE_LOOPBACK\r
 162         uint32_t channel_mode;\r
 163 } usart_spi_opt_t;\r
 164 \r
 165 void usart_reset(Usart *p_usart);\r
 166 uint32_t usart_init_rs232(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 167 uint32_t usart_init_hw_handshaking(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 168 #if (SAM3S || SAM4S || SAM3U)\r
 169 uint32_t usart_init_modem(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 170 #endif\r
 171 uint32_t usart_init_sync_master(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 172 uint32_t usart_init_sync_slave(Usart *p_usart, const sam_usart_opt_t *p_usart_opt);\r
 173 uint32_t usart_init_rs485(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 174 uint32_t usart_init_irda(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 175 uint32_t usart_init_iso7816(Usart *p_usart, const usart_iso7816_opt_t *p_usart_opt, uint32_t ul_mck);\r
 176 uint32_t usart_init_spi_master(Usart *p_usart, const usart_spi_opt_t *p_usart_opt, uint32_t ul_mck);\r
 177 uint32_t usart_init_spi_slave(Usart *p_usart, const usart_spi_opt_t *p_usart_opt);\r
 178 #if SAM3XA\r
 179 uint32_t usart_init_lin_master(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 180 uint32_t usart_init_lin_slave(Usart *p_usart, const sam_usart_opt_t *p_usart_opt, uint32_t ul_mck);\r
 181 void usart_lin_abort_tx(Usart *p_usart);\r
 182 void usart_lin_send_wakeup_signal(Usart *p_usart);\r
 183 void usart_lin_set_node_action(Usart *p_usart, uint8_t uc_action);\r
 184 void usart_lin_disable_parity(Usart *p_usart);\r
 185 void usart_lin_enable_parity(Usart *p_usart);\r
 186 void usart_lin_disable_checksum(Usart *p_usart);\r
 187 void usart_lin_enable_checksum(Usart *p_usart);\r
 188 void usart_lin_set_checksum_type(Usart *p_usart, uint8_t uc_type);\r
 189 void usart_lin_set_data_len_mode(Usart *p_usart, uint8_t uc_mode);\r
 190 void usart_lin_disable_frame_slot(Usart *p_usart);\r
 191 void usart_lin_enable_frame_slot(Usart *p_usart);\r
 192 void usart_lin_set_wakeup_signal_type(Usart *p_usart, uint8_t uc_type);\r
 193 void usart_lin_set_response_data_len(Usart *p_usart, uint8_t uc_len);\r
 194 void usart_lin_disable_pdc_mode(Usart *p_usart);\r
 195 void usart_lin_enable_pdc_mode(Usart *p_usart);\r
 196 void usart_lin_set_tx_identifier(Usart *p_usart, uint8_t uc_id);\r
 197 uint8_t usart_lin_read_identifier(Usart *p_usart);\r
 198 #endif\r
 199 void usart_enable_tx(Usart *p_usart);\r
 200 void usart_disable_tx(Usart *p_usart);\r
 201 void usart_reset_tx(Usart *p_usart);\r
 202 void usart_set_tx_timeguard(Usart *p_usart, uint32_t timeguard);\r
 203 void usart_enable_rx(Usart *p_usart);\r
 204 void usart_disable_rx(Usart *p_usart);\r
 205 void usart_reset_rx(Usart *p_usart);\r
 206 void usart_set_rx_timeout(Usart *p_usart, uint32_t timeout);\r
 207 void usart_enable_interrupt(Usart *p_usart,uint32_t ul_sources);\r
 208 void usart_disable_interrupt(Usart *p_usart,uint32_t ul_sources);\r
 209 uint32_t usart_get_interrupt_mask(Usart *p_usart);\r
 210 uint32_t usart_get_status(Usart *p_usart);\r
 211 void usart_reset_status(Usart *p_usart);\r
 212 void usart_start_tx_break(Usart *p_usart);\r
 213 void usart_stop_tx_break(Usart *p_usart);\r
 214 void usart_start_rx_timeout(Usart *p_usart);\r
 215 uint32_t usart_send_address(Usart *p_usart, uint32_t ul_addr);\r
 216 void usart_reset_iterations(Usart *p_usart);\r
 217 void usart_reset_nack(Usart *p_usart);\r
 218 void usart_restart_rx_timeout(Usart *p_usart);\r
 219 #if (SAM3S || SAM4S || SAM3U)\r
 220 void usart_drive_DTR_pin_low(Usart *p_usart);\r
 221 void usart_drive_DTR_pin_high(Usart *p_usart);\r
 222 #endif\r
 223 void usart_drive_RTS_pin_low(Usart *p_usart);\r
 224 void usart_drive_RTS_pin_high(Usart *p_usart);\r
 225 void usart_spi_force_chip_select(Usart *p_usart);\r
 226 void usart_spi_release_chip_select(Usart *p_usart);\r
 227 uint32_t usart_is_tx_ready(Usart *p_usart);\r
 228 uint32_t usart_is_tx_empty(Usart *p_usart);\r
 229 uint32_t usart_is_rx_ready(Usart *p_usart);\r
 230 uint32_t usart_is_rx_buf_end(Usart *p_usart);\r
 231 uint32_t usart_is_tx_buf_end(Usart *p_usart);\r
 232 uint32_t usart_is_rx_buf_full(Usart *p_usart);\r
 233 uint32_t usart_is_tx_buf_empty(Usart *p_usart);\r
 234 uint32_t usart_write(Usart *p_usart, uint32_t c);\r
 235 uint32_t usart_putchar(Usart *p_usart, uint32_t c);\r
 236 void usart_write_line(Usart *p_usart, const char *string);\r
 237 uint32_t usart_read(Usart *p_usart, uint32_t *c);\r
 238 uint32_t usart_getchar(Usart *p_usart, uint32_t *c);\r
 239 #if (SAM3XA || SAM3U)\r
 240 uint32_t * usart_get_tx_access(Usart *p_usart);\r
 241 uint32_t * usart_get_rx_access(Usart *p_usart);\r
 242 #endif\r
 243 Pdc *usart_get_pdc_base(Usart *p_usart);\r
 244 void usart_enable_writeprotect(Usart *p_usart);\r
 245 void usart_disable_writeprotect(Usart *p_usart);\r
 246 uint32_t usart_get_writeprotect_status(Usart *p_usart);\r
 247 uint8_t usart_get_error_number(Usart *p_usart);\r
 248 #if (SAM3S || SAM4S || SAM3U || SAM3XA)\r
 249 void usart_man_set_tx_pre_len(Usart *p_usart, uint8_t uc_len);\r
 250 void usart_man_set_tx_pre_pattern(Usart *p_usart, uint8_t uc_pattern);\r
 251 void usart_man_set_tx_polarity(Usart *p_usart, uint8_t uc_polarity);\r
 252 void usart_man_set_rx_pre_len(Usart *p_usart, uint8_t uc_len);\r
 253 void usart_man_set_rx_pre_pattern(Usart *p_usart, uint8_t uc_pattern);\r
 254 void usart_man_set_rx_polarity(Usart *p_usart, uint8_t uc_polarity);\r
 255 void usart_man_enable_drift_compensation(Usart *p_usart);\r
 256 void usart_man_disable_drift_compensation(Usart *p_usart);\r
 257 #endif\r
 258 \r
 259 /// @cond 0\r
 260 /**INDENT-OFF**/\r
 261 #ifdef __cplusplus\r
 262 }\r
 263 #endif\r
 264 /**INDENT-ON**/\r
 265 /// @endcond\r
 266 \r
 267 //! @}\r
 268 \r
 269 /**\r
 270  * \page sam_usart_quickstart Quick start guide for the SAM USART module\r
 271  *\r
 272  * This is the quick start guide for the \ref usart_group "USART module", with\r
 273  * step-by-step instructions on how to configure and use the driver in a\r
 274  * selection of use cases.\r
 275  *\r
 276  * The use cases contain several code fragments. The code fragments in the\r
 277  * steps for setup can be copied into a custom initialization function, while\r
 278  * the steps for usage can be copied into, e.g., the main application function.\r
 279  *\r
 280  * \note Some SAM devices contain both USART and UART modules, with the latter\r
 281  *       being a subset in functionality of the former but physically separate\r
 282  *       peripherals. UART modules are compatible with the USART driver, but\r
 283  *       only for the functions and modes supported by the base UART driver.\r
 284  *\r
 285  * \section usart_basic_use_case Basic use case\r
 286  * \section usart_use_cases USART use cases\r
 287  * - \ref usart_basic_use_case\r
 288  * - \subpage usart_use_case_1\r
 289  * - \subpage usart_use_case_2\r
 290  *\r
 291  * \section usart_basic_use_case Basic use case - transmit a character\r
 292  * In this use case, the USART module is configured for:\r
 293  * - Using USART0\r
 294  * - Baudrate: 9600\r
 295  * - Character length: 8 bit\r
 296  * - Parity mode: Disabled\r
 297  * - Stop bit: None\r
 298  * - RS232 mode\r
 299  *\r
 300  * \section usart_basic_use_case_setup Setup steps\r
 301  *\r
 302  * \subsection usart_basic_use_case_setup_prereq Prerequisites\r
 303  * -# \ref sysclk_group "System Clock Management (sysclock)"\r
 304  * -# \ref pio_group "Parallel Input/Output Controller (pio)"\r
 305  * -# \ref pmc_group "Power Management Controller (pmc)"\r
 306  *\r
 307  * \subsection usart_basic_use_case_setup_code Example code\r
 308  * The following configuration must be added to the project (typically to a \r
 309  * conf_usart.h file, but it can also be added to your main application file.)\r
 310  * \code\r
 311  *    #define USART_SERIAL                 USART0\r
 312  *    #define USART_SERIAL_ID              ID_USART0\r
 313  *    #define USART_SERIAL_PIO             PINS_USART_PIO\r
 314  *    #define USART_SERIAL_TYPE            PINS_USART_TYPE\r
 315  *    #define USART_SERIAL_PINS            PINS_USART_PINS\r
 316  *    #define USART_SERIAL_MASK            PINS_USART_MASK\r
 317  *    #define USART_SERIAL_BAUDRATE        9600\r
 318  *    #define USART_SERIAL_CHAR_LENGTH     US_MR_CHRL_8_BIT\r
 319  *    #define USART_SERIAL_PARITY          US_MR_PAR_NO\r
 320  *    #define USART_SERIAL_STOP_BIT        US_MR_NBSTOP_1_BIT\r
 321  * \endcode\r
 322  *\r
 323  * Add to application initialization:\r
 324  * \code\r
 325  *    sysclk_init();\r
 326  *\r
 327  *    pio_configure(USART_SERIAL_PIO, USART_SERIAL_TYPE,\r
 328  *                  USART_SERIAL_MASK, USART_SERIAL_ATTR);\r
 329  *    \r
 330  *    const sam_usart_opt_t usart_console_settings = {\r
 331  *        USART_SERIAL_BAUDRATE,\r
 332  *        USART_SERIAL_CHAR_LENGTH,\r
 333  *        USART_SERIAL_PARITY,\r
 334  *        USART_SERIAL_STOP_BIT,\r
 335  *        US_MR_CHMODE_NORMAL\r
 336  *    };\r
 337  *    \r
 338  *    pmc_enable_periph_clk(USART_SERIAL_ID);\r
 339  *   \r
 340  *    usart_init_rs232(USART_SERIAL, &usart_console_settings, sysclk_get_main_hz());\r
 341  *    usart_enable_tx(USART_SERIAL);\r
 342  *    usart_enable_rx(USART_SERIAL);\r
 343  * \endcode\r
 344  *\r
 345  * \subsection usart_basic_use_case_setup_flow Workflow\r
 346  * -# Initialize system clock:\r
 347  *   \code\r
 348  *   sysclk_init();\r
 349  *   \endcode\r
 350  * -# Configure the USART Tx and Rx pins as Outputs and Inputs respectively:\r
 351  *   \code\r
 352  *   pio_configure(PINS_UART_PIO, PINS_UART_TYPE, PINS_UART_MASK,\r
 353  *                 PINS_UART_ATTR);\r
 354  *   \endcode\r
 355  * -# Create USART options struct:\r
 356  *   \code\r
 357  *   const sam_usart_opt_t usart_console_settings = {\r
 358  *        USART_SERIAL_BAUDRATE,\r
 359  *        USART_SERIAL_CHAR_LENGTH,\r
 360  *        USART_SERIAL_PARITY,\r
 361  *        USART_SERIAL_STOP_BIT,\r
 362  *        US_MR_CHMODE_NORMAL\r
 363  *   };\r
 364  *   \endcode\r
 365  * -# Enable the clock to the USART module:\r
 366  *   \code\r
 367  *   pmc_enable_periph_clk(USART_SERIAL_ID);\r
 368  *   \endcode\r
 369  * -# Initialize the USART module in RS232 mode:\r
 370  *   \code\r
 371  *   usart_init_rs232(USART_SERIAL, &usart_console_settings, sysclk_get_main_hz());\r
 372  *   \endcode\r
 373  * -# Enable the Rx and Tx modes of the USART module:\r
 374  *   \code\r
 375  *   usart_enable_tx(USART_SERIAL);\r
 376  *   usart_enable_rx(USART_SERIAL);\r
 377  *   \endcode\r
 378  *\r
 379  * \section usart_basic_use_case_usage Usage steps\r
 380  *\r
 381  * \subsection usart_basic_use_case_usage_code Example code\r
 382  * Add to application C-file:\r
 383  * \code\r
 384  * usart_putchar(USART_SERIAL, 'a');\r
 385  * \endcode\r
 386  *\r
 387  * \subsection usart_basic_use_case_usage_flow Workflow\r
 388  * -# Send an 'a' character via USART\r
 389  *   \code usart_putchar(USART_SERIAL, 'a'); \endcode\r
 390  */\r
 391 \r
 392 /**\r
 393  * \page usart_use_case_1 USART receive character and echo back\r
 394  *\r
 395  * In this use case, the USART module is configured for:\r
 396  * - Using USART0\r
 397  * - Baudrate: 9600\r
 398  * - Character length: 8 bit\r
 399  * - Parity mode: Disabled\r
 400  * - Stop bit: None\r
 401  * - RS232 mode\r
 402  *\r
 403  * The use case waits for a received character on the configured USART and\r
 404  * echoes the character back to the same USART.\r
 405  *\r
 406  * \section usart_use_case_1_setup Setup steps\r
 407  *\r
 408  * \subsection usart_use_case_1_setup_prereq Prerequisites\r
 409  * -# \ref sysclk_group "System Clock Management (sysclock)"\r
 410  * -# \ref pio_group "Parallel Input/Output Controller (pio)"\r
 411  * -# \ref pmc_group "Power Management Controller (pmc)"\r
 412  *\r
 413  * \subsection usart_use_case_1_setup_code Example code\r
 414  * The following configuration must be added to the project (typically to a \r
 415  * conf_usart.h file, but it can also be added to your main application file.):\r
 416  * \code\r
 417  *    #define USART_SERIAL                 USART0\r
 418  *    #define USART_SERIAL_ID              ID_USART0\r
 419  *    #define USART_SERIAL_PIO             PINS_USART_PIO\r
 420  *    #define USART_SERIAL_TYPE            PINS_USART_TYPE\r
 421  *    #define USART_SERIAL_PINS            PINS_USART_PINS\r
 422  *    #define USART_SERIAL_MASK            PINS_USART_MASK\r
 423  *    #define USART_SERIAL_BAUDRATE        9600\r
 424  *    #define USART_SERIAL_CHAR_LENGTH     US_MR_CHRL_8_BIT\r
 425  *    #define USART_SERIAL_PARITY          US_MR_PAR_NO\r
 426  *    #define USART_SERIAL_STOP_BIT        US_MR_NBSTOP_1_BIT\r
 427  * \endcode\r
 428  *\r
 429  * A variable for the received byte must be added:\r
 430  * \code\r
 431  *    uint32_t received_byte;\r
 432  * \endcode\r
 433  *\r
 434  * Add to application initialization:\r
 435  * \code\r
 436  *    sysclk_init();\r
 437  *\r
 438  *    pio_configure(USART_SERIAL_PIO, USART_SERIAL_TYPE,\r
 439  *                  USART_SERIAL_MASK, USART_SERIAL_ATTR);\r
 440  *    \r
 441  *    const sam_usart_opt_t usart_console_settings = {\r
 442  *        USART_SERIAL_BAUDRATE,\r
 443  *        USART_SERIAL_CHAR_LENGTH,\r
 444  *        USART_SERIAL_PARITY,\r
 445  *        USART_SERIAL_STOP_BIT,\r
 446  *        US_MR_CHMODE_NORMAL\r
 447  *    };\r
 448  *    \r
 449  *    pmc_enable_periph_clk(USART_SERIAL_ID);\r
 450  *   \r
 451  *    usart_init_rs232(USART_SERIAL, &usart_console_settings, sysclk_get_main_hz());\r
 452  *    usart_enable_tx(USART_SERIAL);\r
 453  *    usart_enable_rx(USART_SERIAL);\r
 454  * \endcode\r
 455  *\r
 456  * \subsection usart_use_case_1_setup_flow Workflow\r
 457  * -# Initialize system clock:\r
 458  *   \code\r
 459  *   sysclk_init();\r
 460  *   \endcode\r
 461  * -# Configure the USART Tx and Rx pins as Outputs and Inputs respectively:\r
 462  *   \code\r
 463  *    pio_configure(USART_SERIAL_PIO, USART_SERIAL_TYPE,\r
 464  *                  USART_SERIAL_MASK, USART_SERIAL_ATTR);\r
 465  *   \endcode\r
 466  * -# Create USART options struct:\r
 467  *   \code\r
 468  *   const sam_usart_opt_t usart_console_settings = {\r
 469  *        USART_SERIAL_BAUDRATE,\r
 470  *        USART_SERIAL_CHAR_LENGTH,\r
 471  *        USART_SERIAL_PARITY,\r
 472  *        USART_SERIAL_STOP_BIT,\r
 473  *        US_MR_CHMODE_NORMAL\r
 474  *   };\r
 475  *   \endcode\r
 476  * -# Enable the clock to the USART module:\r
 477  *   \code pmc_enable_periph_clk(USART_SERIAL_ID); \endcode\r
 478  * -# Initialize the USART module in RS232 mode:\r
 479  *   \code usart_init_rs232(USART_SERIAL, &usart_console_settings, sysclk_get_main_hz()); \endcode\r
 480  * -# Enable the Rx and Tx modes of the USART module:\r
 481  *   \code\r
 482  *   usart_enable_tx(USART_SERIAL);\r
 483  *   usart_enable_rx(USART_SERIAL);\r
 484  *   \endcode\r
 485  *\r
 486  * \section usart_use_case_1_usage Usage steps\r
 487  *\r
 488  * \subsection usart_use_case_1_usage_code Example code\r
 489  * Add to, e.g., main loop in application C-file:\r
 490  * \code\r
 491  * received_byte = usart_getchar(USART_SERIAL);\r
 492  * usart_putchar(USART_SERIAL, received_byte);\r
 493  * \endcode\r
 494  *\r
 495  * \subsection usart_use_case_1_usage_flow Workflow\r
 496  * -# Wait for reception of a character:\r
 497  *   \code usart_getchar(USART_SERIAL, &received_byte); \endcode\r
 498  * -# Echo the character back:\r
 499  *   \code usart_putchar(USART_SERIAL, received_byte); \endcode\r
 500  */\r
 501 \r
 502 /**\r
 503  * \page usart_use_case_2 USART receive character and echo back via interrupts\r
 504  *\r
 505  * In this use case, the USART module is configured for:\r
 506  * - Using USART0\r
 507  * - Baudrate: 9600\r
 508  * - Character length: 8 bit\r
 509  * - Parity mode: Disabled\r
 510  * - Stop bit: None\r
 511  * - RS232 mode\r
 512  *\r
 513  * The use case waits for a received character on the configured USART and\r
 514  * echoes the character back to the same USART. The character reception is\r
 515  * performed via an interrupt handler, rather than the polling method used\r
 516  * in \ref usart_use_case_1.\r
 517  *\r
 518  * \section usart_use_case_2_setup Setup steps\r
 519  *\r
 520  * \subsection usart_use_case_2_setup_prereq Prerequisites\r
 521  * -# \ref sysclk_group "System Clock Management (sysclock)"\r
 522  * -# \ref pio_group "Parallel Input/Output Controller (pio)"\r
 523  * -# \ref pmc_group "Power Management Controller (pmc)"\r
 524  *\r
 525  * \subsection usart_use_case_2_setup_code Example code\r
 526  * The following configuration must be added to the project (typically to a \r
 527  * conf_usart.h file, but it can also be added to your main application file.):\r
 528  * \code\r
 529  *    #define USART_SERIAL                 USART0\r
 530  *    #define USART_SERIAL_ID              ID_USART0\r
 531  *    #define USART_SERIAL_ISR_HANDLER     USART0_Handler\r
 532  *    #define USART_SERIAL_PIO             PINS_USART_PIO\r
 533  *    #define USART_SERIAL_TYPE            PINS_USART_TYPE\r
 534  *    #define USART_SERIAL_PINS            PINS_USART_PINS\r
 535  *    #define USART_SERIAL_MASK            PINS_USART_MASK\r
 536  *    #define USART_SERIAL_BAUDRATE        9600\r
 537  *    #define USART_SERIAL_CHAR_LENGTH     US_MR_CHRL_8_BIT\r
 538  *    #define USART_SERIAL_PARITY          US_MR_PAR_NO\r
 539  *    #define USART_SERIAL_STOP_BIT        US_MR_NBSTOP_1_BIT\r
 540  * \endcode\r
 541  *\r
 542  * A variable for the received byte must be added:\r
 543  * \code\r
 544  *    uint32_t received_byte;\r
 545  * \endcode\r
 546  *\r
 547  * Add to application initialization:\r
 548  * \code\r
 549  *    sysclk_init();\r
 550  *\r
 551  *    pio_configure(USART_SERIAL_PIO, USART_SERIAL_TYPE,\r
 552  *                  USART_SERIAL_MASK, USART_SERIAL_ATTR);\r
 553  *    \r
 554  *    const sam_usart_opt_t usart_console_settings = {\r
 555  *        USART_SERIAL_BAUDRATE,\r
 556  *        USART_SERIAL_CHAR_LENGTH,\r
 557  *        USART_SERIAL_PARITY,\r
 558  *        USART_SERIAL_STOP_BIT,\r
 559  *        US_MR_CHMODE_NORMAL\r
 560  *    };\r
 561  *    \r
 562  *    pmc_enable_periph_clk(USART_SERIAL_ID);\r
 563  *   \r
 564  *    usart_init_rs232(USART_SERIAL, &usart_console_settings, sysclk_get_main_hz());\r
 565  *    usart_enable_tx(USART_SERIAL);\r
 566  *    usart_enable_rx(USART_SERIAL);\r
 567  * \r
 568  *    usart_enable_interrupt(USART_SERIAL, US_IER_RXRDY);\r
 569  *    NVIC_EnableIRQ(USART_SERIAL_IRQ);\r
 570  * \endcode\r
 571  *\r
 572  * \subsection usart_use_case_2_setup_flow Workflow\r
 573  * -# Initialize system clock:\r
 574  *   \code\r
 575  *   sysclk_init();\r
 576  *   \endcode\r
 577  * -# Configure the USART Tx and Rx pins as Outputs and Inputs respectively:\r
 578  *   \code\r
 579  *    pio_configure(USART_SERIAL_PIO, USART_SERIAL_TYPE,\r
 580  *                  USART_SERIAL_MASK, USART_SERIAL_ATTR);\r
 581  *   \endcode\r
 582  * -# Create USART options struct:\r
 583  *   \code\r
 584  *   const sam_usart_opt_t usart_console_settings = {\r
 585  *        USART_SERIAL_BAUDRATE,\r
 586  *        USART_SERIAL_CHAR_LENGTH,\r
 587  *        USART_SERIAL_PARITY,\r
 588  *        USART_SERIAL_STOP_BIT,\r
 589  *        US_MR_CHMODE_NORMAL\r
 590  *   };\r
 591  *   \endcode\r
 592  * -# Enable the clock to the USART module:\r
 593  *   \code pmc_enable_periph_clk(USART_SERIAL_ID); \endcode\r
 594  * -# Initialize the USART module in RS232 mode:\r
 595  *   \code usart_init_rs232(USART_SERIAL, &usart_console_settings, sysclk_get_main_hz()); \endcode\r
 596  * -# Enable the Rx and Tx modes of the USART module:\r
 597  *   \code\r
 598  *   usart_enable_tx(USART_SERIAL);\r
 599  *   usart_enable_rx(USART_SERIAL);\r
 600  *   \endcode\r
 601  * -# Enable the USART character reception interrupt, and general interrupts for the USART module.\r
 602  *   \code\r
 603  *   usart_enable_interrupt(USART_SERIAL, US_IER_RXRDY);\r
 604  *   NVIC_EnableIRQ(USART_SERIAL_IRQ);\r
 605  *   \endcode\r
 606  * \section usart_use_case_2_usage Usage steps\r
 607  *\r
 608  * \subsection usart_use_case_2_usage_code Example code\r
 609  * Add to your main application C-file the USART interrupt handler:\r
 610  * \code\r
 611  * void USART_SERIAL_ISR_HANDLER(void)\r
 612  * {\r
 613  *    uint32_t dw_status = usart_get_status(USART_SERIAL);\r
 614  * \r
 615  *    if (dw_status & US_CSR_RXRDY) {\r
 616  *        uint32_t received_byte;\r
 617  * \r
 618  *        usart_read(USART_SERIAL, &received_byte);\r
 619  *        usart_write(USART_SERIAL, received_byte);\r
 620  *    }\r
 621  * }\r
 622  * \endcode\r
 623  *\r
 624  * \subsection usart_use_case_2_usage_flow Workflow\r
 625  * -# When the USART ISR fires, retrieve the USART module interrupt flags:\r
 626  *   \code uint32_t dw_status = usart_get_status(USART_SERIAL); \endcode\r
 627  * -# Check if the USART Receive Character interrupt has fired:\r
 628  *   \code if (dw_status & US_CSR_RXRDY) \endcode\r
 629  * -# If a character has been received, fetch it into a temporary variable:\r
 630  *   \code usart_read(USART_SERIAL, &received_byte); \endcode\r
 631  * -# Echo the character back:\r
 632  *   \code usart_write(USART_SERIAL, received_byte); \endcode\r
 633  */\r
 634 \r
 635 #endif /* USART_H_INCLUDED */\r