View detail for Atmel AT07896: Universal Asynchronous Receiver Transceiver (UART)

APPLICATION NOTE
AT07896: Universal Asynchronous Receiver
Transceiver (UART)
ASF PROGRAMMERS MANUAL
Universal Asynchronous Receiver Transceiver (UART)
Note
This driver applies to SAM3, SAM4S, SAM4E, SAM4N, SAM4C,
SAM4CM, SAM4CP, and SAMG devices.
The Universal Asynchronous Receiver Transmitter features a two-pin UART that
can be used for communication and debug/trace purposes and offers an ideal
medium for in-situ programming solutions. Moreover, the association with two
peripheral DMA controller (PDC) channels permits packet handling for these tasks
with processor time reduced to a minimum.
The outline of this documentation is as follows:
●
Prerequisites
●
Module Overview
●
Special Considerations
●
Extra Information
●
Examples
●
API Overview
42299A-MCU-05/2014
Table of Contents
Universal Asynchronous Receiver Transceiver (UART) .................... 1
Software License ................................................................................ 4
1. Prerequisites ................................................................................. 5
2. Module Overview .......................................................................... 6
3. Special Considerations ................................................................. 7
4. Extra Information .......................................................................... 8
5. API Overview ................................................................................ 9
5.1.
5.2.
5.3.
Variable and Type Definitions ........................................................ 9
5.1.1.
Type sam_uart_opt_t ...................................................... 9
Structure Definitions .................................................................... 9
5.2.1.
Struct sam_uart_opt ........................................................ 9
Function Definitions ..................................................................... 9
5.3.1.
Function uart_disable() ................................................... 9
5.3.2.
Function uart_disable_interrupt() ....................................... 9
5.3.3.
Function uart_disable_rx() ............................................. 10
5.3.4.
Function uart_disable_tx() .............................................. 10
5.3.5.
Function uart_enable() .................................................. 10
5.3.6.
Function uart_enable_interrupt() ...................................... 10
5.3.7.
Function uart_enable_rx() .............................................. 11
5.3.8.
Function uart_enable_tx() .............................................. 11
5.3.9.
Function uart_get_interrupt_mask() .................................. 11
5.3.10. Function uart_get_pdc_base() ........................................ 12
5.3.11. Function uart_get_status() ............................................. 12
5.3.12. Function uart_init() ....................................................... 12
5.3.13. Function uart_is_rx_buf_end() ........................................ 13
5.3.14. Function uart_is_rx_buf_full() .......................................... 13
5.3.15. Function uart_is_rx_ready() ............................................ 13
5.3.16. Function uart_is_tx_buf_empty() ..................................... 14
5.3.17. Function uart_is_tx_buf_end() ......................................... 14
5.3.18. Function uart_is_tx_empty() ........................................... 14
5.3.19. Function uart_is_tx_ready() ............................................ 15
5.3.20. Function uart_read() ..................................................... 15
5.3.21. Function uart_reset() .................................................... 16
5.3.22. Function uart_reset_rx() ................................................ 16
5.3.23. Function uart_reset_status() ........................................... 16
5.3.24. Function uart_reset_tx() ................................................ 16
5.3.25. Function uart_set_clock_divisor() .................................... 16
5.3.26. Function uart_write() ..................................................... 17
6. UART SleepWalking Example .................................................... 18
6.1.
6.2.
6.3.
6.4.
Purpose ...................................................................................
Requirements ...........................................................................
Description ...............................................................................
Usage .....................................................................................
18
18
18
18
7. Extra Information ........................................................................ 19
7.1.
7.2.
7.3.
Acronyms ................................................................................ 19
Dependencies ........................................................................... 19
Errata ...................................................................................... 19
8. Examples .................................................................................... 20
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
2
Index ................................................................................................. 21
Document Revision History .............................................................. 22
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
3
Software License
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
3. The name of Atmel may not be used to endorse or promote products derived from this software without specific
prior written permission.
4. This software may only be redistributed and used in connection with an Atmel microcontroller product.
THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN
NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
4
1.
Prerequisites
There are no prerequisites for this module.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
5
2.
Module Overview
The Universal Asynchronous Receiver Transmitter (UART) features a two-pin UART that can be used for
communication and trace purposes and offers an ideal medium for in-situ programming solutions. Moreover, the
association with peripheral DMA controller (PDC) permits packet handling for these tasks with processor time
reduced to a minimum.
The API provides the following features:
1.
Enable the UART peripheral clock in the PMC.
2.
Enable the required UART PIOs (see pio.h).
3.
Configure the UART by calling uart_init.
4.
Send data through the UART using the uart_write.
5.
Receive data from the UART using the uart_read; the availability of data. can be polled with uart_is_rx_ready.
6.
Disable the transmitter and/or the receiver of the UART with. uart_disable_tx and uart_disable_rx.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
6
3.
Special Considerations
●
This device provides a simple two pin (Recieve and Transmit) serial connection.
●
For more sophisticated usage requiring hardware handshaking etc. consider using a USART or making use of
GPIO pins and additional software. In this case consideration of power management regimes should also be
considered.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
7
4.
Extra Information
For extra information, see Extra Information. This includes:
●
Acronyms
●
Dependencies
●
Errata
●
Document Revision History
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
8
5.
API Overview
5.1
Variable and Type Definitions
5.1.1
Type sam_uart_opt_t
typedef struct sam_uart_opt sam_uart_opt_t
5.2
Structure Definitions
5.2.1
Struct sam_uart_opt
Table 5-1. Members
Type
Name
Description
uint32_t
ul_baudrate
Expected baud rate
uint32_t
ul_chmode
Configure channel mode (Normal,
Automatic, Local_loopback or
Remote_loopback)
uint32_t
ul_mck
MCK for UART
uint32_t
ul_mode
Initialize value for UART mode
register
5.3
Function Definitions
5.3.1
Function uart_disable()
Disable the specified UART receiver and transmitter.
void uart_disable(
Uart * p_uart)
Table 5-2. Parameters
5.3.2
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
[in]
ul_sources
Interrupts to be disabled
Function uart_disable_interrupt()
Disable UART interrupts.
void uart_disable_interrupt(
Uart * p_uart,
uint32_t ul_sources)
Table 5-3. Parameters
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
9
Note
5.3.3
For the meaning of ul_sources, refer to the description of the UART Interrupt Disable Register (IDR)
in the appropriate data sheet.
Function uart_disable_rx()
Disable UART receiver.
void uart_disable_rx(
Uart * p_uart)
Table 5-4. Parameters
5.3.4
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Function uart_disable_tx()
Disable UART transmitter.
void uart_disable_tx(
Uart * p_uart)
Table 5-5. Parameters
5.3.5
Function uart_enable()
Enable the specified UART receiver and transmitter.
void uart_enable(
Uart * p_uart)
Table 5-6. Parameters
5.3.6
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Function uart_enable_interrupt()
Enable UART interrupts.
void uart_enable_interrupt(
Uart * p_uart,
uint32_t ul_sources)
Table 5-7. Parameters
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
10
Data direction
Parameter name
Description
[in]
ul_sources
Interrupts to be enabled
Note
5.3.7
For the meaning of ul_sources, refer to the description of the UART Interrupt Enable Register (IER) in
the appropriate data sheet.
Function uart_enable_rx()
Enable UART receiver.
void uart_enable_rx(
Uart * p_uart)
Table 5-8. Parameters
5.3.8
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Function uart_enable_tx()
Enable the UART transmitter.
void uart_enable_tx(
Uart * p_uart)
Table 5-9. Parameters
5.3.9
Function uart_get_interrupt_mask()
Read the UART interrupt mask.
uint32_t uart_get_interrupt_mask(
Uart * p_uart)
Table 5-10. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Returns
The interrupt mask value.
Note
For the meaning of ul_sources, refer to the description of the UART Interrupt Enable Register (IER) in
the appropriate data sheet.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
11
5.3.10
Function uart_get_pdc_base()
Get the UART PDC base address.
Pdc * uart_get_pdc_base(
Uart * p_uart)
Table 5-11. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Returns
5.3.11
UART PDC registers base for PDC driver to access.
Function uart_get_status()
Get current UART status.
uint32_t uart_get_status(
Uart * p_uart)
Table 5-12. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Returns
The current UART status.
Note
For the meaning of the value returned, refer to the description of the UART Status Register(SR) in the
appropriate data sheet.
5.3.12
Function uart_init()
Configure the UART with the specified parameters.
uint32_t uart_init(
Uart * p_uart,
const sam_uart_opt_t * p_uart_opt)
Note
The PMC and PIOs must be configured first.
For more detail see sam_uart_opt_t
Table 5-13. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
12
Data direction
Parameter name
Description
[in]
p_uart_opt
Pointer to sam_uart_opt_t instance
Table 5-14. Return Values
5.3.13
Return value
Description
0
Success
1
Bad baud rate generator value
Function uart_is_rx_buf_end()
Check if a receive buffer is filled.
uint32_t uart_is_rx_buf_end(
Uart * p_uart)
Table 5-15. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Table 5-16. Return Values
5.3.14
Return value
Description
1
Receive is completed
0
Receive is still pending
Function uart_is_rx_buf_full()
Check if both receive buffers are full.
uint32_t uart_is_rx_buf_full(
Uart * p_uart)
Table 5-17. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Table 5-18. Return Values
5.3.15
Return value
Description
1
Receive buffers are full
0
Receive buffers are not full
Function uart_is_rx_ready()
Check if Received data is ready. Check if data has been received and loaded into the Recieve Holding
register(RHR).
uint32_t uart_is_rx_ready(
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
13
Uart * p_uart)
Table 5-19. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Table 5-20. Return Values
5.3.16
Return value
Description
1
One data has been received
0
No data has been received
Function uart_is_tx_buf_empty()
Check if both transmit buffers are empty.
uint32_t uart_is_tx_buf_empty(
Uart * p_uart)
Table 5-21. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Table 5-22. Return Values
5.3.17
Return value
Description
1
Transmit buffer is empty
0
Transmit buffer is not empty
Function uart_is_tx_buf_end()
Check if a transmit buffer is empty.
uint32_t uart_is_tx_buf_end(
Uart * p_uart)
Table 5-23. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Table 5-24. Return Values
5.3.18
Return value
Description
1
Transmit is completed
0
Transmit is still pending
Function uart_is_tx_empty()
Check if Transmit Hold Register is empty. Check if the last data written in Transmit Holding Register (THR) has
been loaded into the Transmit Shift Register(TSR) and the last data loaded in TSR has been transmitted.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
14
uint32_t uart_is_tx_empty(
Uart * p_uart)
Table 5-25. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Table 5-26. Return Values
5.3.19
Return value
Description
1
Transmitter is empty
0
Transmitter is not empty
Function uart_is_tx_ready()
Check if Transmit is Ready. Check if data has been loaded into the Transmit Holding Register(THR) and is waiting
to be loaded in the Transmit Shift Register (TSR).
uint32_t uart_is_tx_ready(
Uart * p_uart)
Table 5-27. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Table 5-28. Return Values
5.3.20
Return value
Description
1
Data has been transmitted
0
Transmit is not ready, data pending
Function uart_read()
Read from UART Receive Holding Register(RHR). Before reading user should check if rx is ready.
uint32_t uart_read(
Uart * p_uart,
uint8_t * puc_data)
Table 5-29. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
[out]
puc_data
Recieved data
Table 5-30. Return Values
Return value
Description
0
Success
1
I/O Failure, UART is not ready
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
15
5.3.21
Function uart_reset()
Reset UART receiver and transmitter.
void uart_reset(
Uart * p_uart)
Table 5-31. Parameters
5.3.22
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
Function uart_reset_rx()
Reset UART receiver.
void uart_reset_rx(
Uart * p_uart)
Table 5-32. Parameters
5.3.23
Function uart_reset_status()
Reset status bits.
void uart_reset_status(
Uart * p_uart)
Table 5-33. Parameters
5.3.24
Function uart_reset_tx()
Reset UART transmitter.
void uart_reset_tx(
Uart * p_uart)
Table 5-34. Parameters
5.3.25
Function uart_set_clock_divisor()
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
16
Set UART clock divisor value.
void uart_set_clock_divisor(
Uart * p_uart,
uint16_t us_divisor)
Table 5-35. Parameters
5.3.26
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
[in]
us_divisor
Value to be set
Function uart_write()
Write to UART Transmit Holding Register (THR). Before writing the user should check if tx is ready (or empty).
uint32_t uart_write(
Uart * p_uart,
const uint8_t uc_data)
Table 5-36. Parameters
Data direction
Parameter name
Description
[in]
p_uart
Pointer to a UART instance
[in]
uc_data
Data to be sent
Table 5-37. Return Values
Return value
Description
0
Success
1
I/O Failure, UART is not ready
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
17
6.
UART SleepWalking Example
6.1
Purpose
The example demonstrates how to use SleepWalking function of the UART.
6.2
Requirements
This example can be used on SAMG53 device.
The code can be found in the uart_sleepwalking_example folder.
Note
6.3
The example use a loose match condition to wake-up the system from wait mode.
Description
The example first tests the sleepwalking function in active mode. If the 's' character is received, the match interrupt
is triggered. Then it tests the SleepWalking function in wait mode. As soon as a data is received, the system wakeup from wait mode.
6.4
Usage
1.
Build the program and download it into the evaluation board.
2.
On the computer, open, and configure a terminal application (e.g., HyperTerminal on Microsoft Windows )
with these settings:
3.
®
●
115200 bauds
●
8 bits of data
●
No parity
●
1 stop bit
●
No flow control
®
In the terminal window, the following text should appear (values depend on the board and chip used):
-- Uart Sleepwalking Example xxx --- xxxxxx-xx
-- Compiled: xxx xx xxxx xx:xx:xx --
4.
the sent text should appear.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
18
7.
Extra Information
7.1
Acronyms
Below is a table listing the acronyms used in this module, along with their intended meanings.
7.2
Acronym
Definition
IDR
Interrupt Disable Register
IER
Interrupt Enable Register
PDC
Peripheral DMA Channel
SR
Status Register
Dependencies
This driver has the following dependencies:
●
7.3
None
Errata
There are no errata related to this driver.
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
19
8.
Examples
For an example application for the UART, see:
●
UART SleepWalking Example
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
20
Index
F
Function Definitions
uart_disable, 9
uart_disable_interrupt, 9
uart_disable_rx, 10
uart_disable_tx, 10
uart_enable, 10
uart_enable_interrupt, 10
uart_enable_rx, 11
uart_enable_tx, 11
uart_get_interrupt_mask, 11
uart_get_pdc_base, 12
uart_get_status, 12
uart_init, 12
uart_is_rx_buf_end, 13
uart_is_rx_buf_full, 13
uart_is_rx_ready, 13
uart_is_tx_buf_empty, 14
uart_is_tx_buf_end, 14
uart_is_tx_empty, 14
uart_is_tx_ready, 15
uart_read, 15
uart_reset, 16
uart_reset_rx, 16
uart_reset_status, 16
uart_reset_tx, 16
uart_set_clock_divisor, 16
uart_write, 17
S
Structure Definitions
sam_uart_opt, 9
T
Type Definitions
sam_uart_opt_t, 9
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
21
Document Revision History
Doc. Rev.
Date
Comments
42299A
05/2014
Initial document release
AT07896: Universal Asynchronous Receiver Transceiver (UART) [APPLICATION NOTE]
42299A-MCU-05/2014
22
Atmel Corporation
1600 Technology Drive, San Jose, CA 95110 USA
T: (+1)(408) 441.0311
F: (+1)(408) 436.4200
|
www.atmel.com
© 2014 Atmel Corporation. All rights reserved. / Rev.: 42299A-MCU-05/2014
®
®
Atmel , Atmel logo and combinations thereof, Enabling Unlimited Possibilities , and others are registered trademarks or trademarks of Atmel Corporation or its
®
subsidiaries. Windows is a registered trademark of Microsoft Corporation in U.S. and or other countries. Other terms and product names may be trademarks
of others.
Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by
this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL
ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF
INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no
representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at
any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be
used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.