APPLICATION NOTE AT08642: Peripheral DMA Controller (PDC) Peripheral DMA Controller (PDC)

APPLICATION NOTE
AT08642: Peripheral DMA Controller (PDC)
ASF PROGRAMMERS MANUAL
Peripheral DMA Controller (PDC)
This driver for SAM4 devices provides an interface for the configuration and
management of the the Peripheral DMA Controller (PDC) module.
The PDC transfers data between on-chip serial peripherals and the on and/or offchip memories. The link between the PDC and a serial peripheral is operated by the
AHB to ABP bridge.
This module:
●
Performs transfers to/from APB communication serial peripherals
●
Supports half-duplex and full-duplex peripherals
The outline of this documentation is as follows:
●
Prerequisites
●
Module Overview
●
Special Considerations
●
Extra Information
●
Examples
●
API Overview
42316A-MCU-05/2014
Table of Contents
Peripheral DMA Controller (PDC) ...................................................... 1
Software License ................................................................................ 3
1. Prerequisites ................................................................................. 4
2. Module Overview .......................................................................... 5
3. Special Considerations ................................................................. 6
4. Extra Information .......................................................................... 7
5. Examples ...................................................................................... 8
6. API Overview ................................................................................ 9
6.1.
6.2.
6.3.
Variable and Type Definitions ........................................................ 9
6.1.1.
Type pdc_packet_t ......................................................... 9
Structure Definitions .................................................................... 9
6.2.1.
Struct pdc_packet ........................................................... 9
Function Definitions ..................................................................... 9
6.3.1.
Function pdc_disable_transfer() ........................................ 9
6.3.2.
Function pdc_enable_transfer() ........................................ 9
6.3.3.
Function pdc_read_rx_counter() ...................................... 10
6.3.4.
Function pdc_read_rx_next_counter() .............................. 10
6.3.5.
Function pdc_read_rx_next_ptr() ..................................... 10
6.3.6.
Function pdc_read_rx_ptr() ............................................ 11
6.3.7.
Function pdc_read_status() ............................................ 11
6.3.8.
Function pdc_read_tx_counter() ...................................... 11
6.3.9.
Function pdc_read_tx_next_counter() ............................... 12
6.3.10. Function pdc_read_tx_next_ptr() ..................................... 12
6.3.11. Function pdc_read_tx_ptr() ............................................ 12
6.3.12. Function pdc_rx_clear_cnt() ........................................... 13
6.3.13. Function pdc_rx_init() ................................................... 13
6.3.14. Function pdc_tx_init() .................................................... 13
7. Extra Information for Peripheral DMA Controller ........................ 15
7.1.
7.2.
7.3.
7.4.
Acronyms ................................................................................
Dependencies ...........................................................................
Errata ......................................................................................
Module History .........................................................................
15
15
15
15
8. Quickstart guide for SAM4 ......................................................... 16
8.1.
Basic Use Case ........................................................................ 16
9. Examples for Peripheral DMA Controller ................................... 17
9.1.
Peripheral DMA Controller Example ..............................................
9.1.1.
Purpose ......................................................................
9.1.2.
Requirements ...............................................................
9.1.3.
Description ...................................................................
9.1.4.
Usage .........................................................................
17
17
17
17
17
Index ................................................................................................. 18
Document Revision History .............................................................. 19
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
2
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.
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
3
1.
Prerequisites
There are no prerequisites for this module.
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
4
2.
Module Overview
The user interface of each PDC channel is integrated into the user interface of the peripheral it serves. The user
interface of unidirectional channels (receive only or transmit only), contains two 32-bit memory pointers and two
16-bit counters, one set (pointer, counter) for current transfer and one set (pointer, counter) for next transfer.
The bidirectional channel user interface contains four 32-bit memory pointers and four 16-bit counters. Each set
(pointer, counter) is used by current transmit, next transmit, current receive and next receive. Using the PDC
removes processor overhead by reducing its intervention during the transfer. This significantly reduces the number
of clock cycles required for a data transfer, which improves microcontroller performance. To launch a transfer, the
peripheral triggers its associated PDC channels by using transmit and receive signals. When the programmed data
is transferred, an end of transfer interrupt is generated by the peripheral itself.
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
5
3.
Special Considerations
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
6
4.
Extra Information
For extra information, see Extra Information for Peripheral DMA Controller. This includes:
●
Acronyms
●
Dependencies
●
Errata
●
Module History
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
7
5.
Examples
For a list of examples related to this driver, see Examples for Peripheral DMA Controller.
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
8
6.
API Overview
6.1
Variable and Type Definitions
6.1.1
Type pdc_packet_t
typedef struct pdc_packet pdc_packet_t
6.2
Structure Definitions
6.2.1
Struct pdc_packet
Table 6-1. Members
Type
Name
Description
uint32_t
ul_addr
Start address of the transfer packet
data.
uint32_t
ul_size
Transfer packet size (in units of the
peripheral data width).
Data direction
Parameter name
Description
[out]
p_pdc
Device structure pointer
[in]
ul_controls
Transfer directions (bit
PERIPH_PTCR_TXTDIS, bit
PERIPH_PTCR_TXTDIS)
6.3
Function Definitions
6.3.1
Function pdc_disable_transfer()
Disable PDC transfers (TX and/or RX).
void pdc_disable_transfer(
Pdc * p_pdc,
uint32_t ul_controls)
Table 6-2. Parameters
6.3.2
Function pdc_enable_transfer()
Enable PDC transfers (TX and/or RX).
void pdc_enable_transfer(
Pdc * p_pdc,
uint32_t ul_controls)
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
9
Note
It is forbidden to set both TXTEN and RXTEN for a half duplex peripheral.
Table 6-3. Parameters
6.3.3
Data direction
Parameter name
Description
[out]
p_pdc
Device structure pointer
[in]
ul_controls
Transfer directions (bit
PERIPH_PTCR_RXTEN and bit
PERIPH_PTCR_TXTEN)
Function pdc_read_rx_counter()
Return Receive Counter Register (RCR) value.
uint32_t pdc_read_rx_counter(
Pdc * p_pdc)
Table 6-4. Parameters
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Returns
6.3.4
Receive Counter Register value.
Function pdc_read_rx_next_counter()
Return Receive Next Counter Register (RNCR) value.
uint32_t pdc_read_rx_next_counter(
Pdc * p_pdc)
Table 6-5. Parameters
Returns
6.3.5
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Receive Next Counter Register value.
Function pdc_read_rx_next_ptr()
Return Receive Next Pointer Register (RNPR) value.
uint32_t pdc_read_rx_next_ptr(
Pdc * p_pdc)
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
10
Table 6-6. Parameters
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Returns
6.3.6
Receive Next Pointer Register value.
Function pdc_read_rx_ptr()
Return Receive Pointer Register (RPR) value.
uint32_t pdc_read_rx_ptr(
Pdc * p_pdc)
Table 6-7. Parameters
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Name
Description
Bit
RXTEN
Receiver Transfer Enabled
8
TXTEN
Transmitter Transfer Enabled
1
Returns
6.3.7
Receive Pointer Register value.
Function pdc_read_status()
Read PDC status.
uint32_t pdc_read_status(
Pdc * p_pdc)
Table 6-8. Parameters
Returns
6.3.8
PDC status register bit map.
Function pdc_read_tx_counter()
Return Transmit Counter Register (TCR) value.
uint32_t pdc_read_tx_counter(
Pdc * p_pdc)
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
11
Table 6-9. Parameters
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Returns
6.3.9
Transmit Counter Register value.
Function pdc_read_tx_next_counter()
Return Transmit Next Counter Register (TNCR) value.
uint32_t pdc_read_tx_next_counter(
Pdc * p_pdc)
Table 6-10. Parameters
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Returns
6.3.10
Transmit Next Counter Register value.
Function pdc_read_tx_next_ptr()
Return Transmit Next Pointer Register (TNPR) value.
uint32_t pdc_read_tx_next_ptr(
Pdc * p_pdc)
Table 6-11. Parameters
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
Returns
6.3.11
Transmit Next Pointer Register value.
Function pdc_read_tx_ptr()
Return Transmit Pointer Register (TPR) value.
uint32_t pdc_read_tx_ptr(
Pdc * p_pdc)
Table 6-12. Parameters
Data direction
Parameter name
Description
[in]
p_pdc
Device structure pointer
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
12
Returns
6.3.12
Transmit Pointer Register value.
Function pdc_rx_clear_cnt()
Clear PDC buffer receive counter.
void pdc_rx_clear_cnt(
Pdc * p_pdc)
Table 6-13. Parameters
6.3.13
Data direction
Parameter name
Description
[out]
p_pdc
Device structure pointer
Function pdc_rx_init()
Configure PDC for data receive.
void pdc_rx_init(
Pdc * p_pdc,
pdc_packet_t * p_packet,
pdc_packet_t * p_next_packet)
Table 6-14. Parameters
6.3.14
Data direction
Parameter name
Description
[out]
p_pdc
Device structure pointer
[in]
p_packet
Pointer to packet information for
current buffer register set, NULL to
let them as is.
[in]
p_next_packet
Pointer to packet information for
next buffer register set, NULL to let
them as is.
Function pdc_tx_init()
Configure PDC for data transmit.
void pdc_tx_init(
Pdc * p_pdc,
pdc_packet_t * p_packet,
pdc_packet_t * p_next_packet)
Table 6-15. Parameters
Data direction
Parameter name
Description
[out]
p_pdc
Device structure pointer
[in]
p_packet
Pointer to packet information for
current buffer register set, NULL to
let them as is.
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
13
Data direction
Parameter name
Description
[in]
p_next_packet
Pointer to packet information for
next buffer register set, NULL to let
them as is.
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
14
7.
Extra Information for Peripheral DMA Controller
7.1
Acronyms
Below is a table listing the acronyms used in this module, along with their intended meanings.
7.2
Acronym
Definition
AHB
Advanced High-performance Bus
AMBA
Advanced Microcontroller Bus Architecture
QSG
Quick Start Guide
RCR
Receive Counter Register
RNCR
Return Receive Next Counter Register
RNPR
Receive Next Pointer Register
RPR
Receive Pointer Register
TCR
Transmit Counter Register
TNCR
Transmit Next Counter Register
TNPR
Transmit Next Pointer Register
TPR
Transmit Pointer Register
Dependencies
This driver has the following dependencies:
●
7.3
None
Errata
There are no errata related to this driver.
7.4
Module History
An overview of the module history is presented in the table below, with details on the enhancements and fixes
made to the module since its first release. The current version of this corresponds to the newest version in the
table.
Changelog
Initial document release
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
15
8.
Quickstart guide for SAM4
This is the quickstart guide for the "PDC driver" with step-by-step instructions on how to configure and use the
driver.
8.1
Basic Use Case
A handler is required for the interrupt, below is a simple example
void console_uart_irq_handler(void)
{
/* Get UART status and check if PDC receive buffer is full */
if ((uart_get_status(CONSOLE_UART) & UART_SR_RXBUFF) == UART_SR_RXBUFF) {
/* Configure PDC for data transfer (RX and TX) */
pdc_rx_init(g_p_uart_pdc, &g_pdc_uart_packet, NULL);
pdc_tx_init(g_p_uart_pdc, &g_pdc_uart_packet, NULL);
}
}
First initialise the board:
sysclk_init();
board_init();
Now setup the PDC registers
/* Get pointer to UART PDC register base */
g_p_uart_pdc = uart_get_pdc_base(CONSOLE_UART);
/* Initialize PDC data packet for transfer */
g_pdc_uart_packet.ul_addr = (uint32_t) g_uc_pdc_buffer;
g_pdc_uart_packet.ul_size = BUFFER_SIZE;
/* Configure PDC for data receive */
pdc_rx_init(g_p_uart_pdc, &g_pdc_uart_packet, NULL);
/* Enable PDC transfers */
pdc_enable_transfer(g_p_uart_pdc, PERIPH_PTCR_RXTEN | PERIPH_PTCR_TXTEN);
Enable UART IRQ
uart_enable_interrupt(CONSOLE_UART, UART_IER_RXBUFF);
and enable UART interrupt
NVIC_EnableIRQ(CONSOLE_UART_IRQn);
Once the required number of bytes have been transferred an interupt is triggered and the handler will run. In the
interim programme to do something else, or be busy waiting
while (1) {
}
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
16
9.
Examples for Peripheral DMA Controller
This is a list of the available Quick Start guides (QSGs) and example applications for Peripheral DMA Controller
(PDC). QSGs are simple examples with step-by-step instructions to configure and use this driver in a selection of
use cases. Note that QSGs can be compiled as a standalone application or be added to the user application.
●
Peripheral DMA Controller Example
9.1
Peripheral DMA Controller Example
9.1.1
Purpose
The pdc_uart example demonstrates how to use PDC driver to receive/send data from/to the UART.
9.1.2
Requirements
This example can be used on any SAM3/4 boards.
9.1.3
Description
The SAM controller waits for BUFFER_SIZE data to receive from the UART. As soon as the expected amount of
data is received, the whole buffer is sent back to the terminal.
9.1.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 baud
●
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):
-- PDC Uart Example xxx --- xxxxxx-xx
-- Compiled: xxx xx xxxx xx:xx:xx --
4.
The sent text should appear.
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
17
Index
F
Function Definitions
pdc_disable_transfer, 9
pdc_enable_transfer, 9
pdc_read_rx_counter, 10
pdc_read_rx_next_counter, 10
pdc_read_rx_next_ptr, 10
pdc_read_rx_ptr, 11
pdc_read_status, 11
pdc_read_tx_counter, 11
pdc_read_tx_next_counter, 12
pdc_read_tx_next_ptr, 12
pdc_read_tx_ptr, 12
pdc_rx_clear_cnt, 13
pdc_rx_init, 13
pdc_tx_init, 13
S
Structure Definitions
pdc_packet, 9
T
Type Definitions
pdc_packet_t, 9
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
18
Document Revision History
Doc. Rev.
Date
Comments
42316A
05/2014
Initial document release
AT08642: Peripheral DMA Controller (PDC) [APPLICATION NOTE]
42316A-MCU-05/2014
19
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.: 42316A-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.