mbed official / mbed-src

mbed library sources

Dependents:   Encrypted my_mbed lklk CyaSSL_DTLS_Cellular ... more

Superseded

This library was superseded by mbed-dev - https://os.mbed.com/users/mbed_official/code/mbed-dev/.

Development branch of the mbed library sources. This library is kept in synch with the latest changes from the mbed SDK and it is not guaranteed to work.

If you are looking for a stable and tested release, please import one of the official mbed library releases:

Import librarymbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Last commit 20 Feb 2019 by mbed official

targets/hal/TARGET_Atmel/TARGET_SAM21/drivers/sercom/i2c/quick_start_master_dma/qs_i2c_master_dma.h@579:53297373a894, 2015-07-01 (annotated)

Committer:
mbed_official
Date:
Wed Jul 01 09:45:11 2015 +0100
Revision:
579:53297373a894
Child:
592:a274ee790e56
Synchronized with git revision d5b4d2ab9c47edb4dc5776e7177b0c2263459081



Full URL: https://github.com/mbedmicro/mbed/commit/d5b4d2ab9c47edb4dc5776e7177b0c2263459081/



Initial version of drivers for SAMR21

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 579:53297373a894 1 /**
mbed_official 579:53297373a894 2 * \file
mbed_official 579:53297373a894 3 *
mbed_official 579:53297373a894 4 * \brief SAM SERCOM I2C Master Driver with DMA Quick Start Guide
mbed_official 579:53297373a894 5 *
mbed_official 579:53297373a894 6 * Copyright (C) 2014 Atmel Corporation. All rights reserved.
mbed_official 579:53297373a894 7 *
mbed_official 579:53297373a894 8 * \asf_license_start
mbed_official 579:53297373a894 9 *
mbed_official 579:53297373a894 10 * \page License
mbed_official 579:53297373a894 11 *
mbed_official 579:53297373a894 12 * Redistribution and use in source and binary forms, with or without
mbed_official 579:53297373a894 13 * modification, are permitted provided that the following conditions are met:
mbed_official 579:53297373a894 14 *
mbed_official 579:53297373a894 15 * 1. Redistributions of source code must retain the above copyright notice,
mbed_official 579:53297373a894 16 * this list of conditions and the following disclaimer.
mbed_official 579:53297373a894 17 *
mbed_official 579:53297373a894 18 * 2. Redistributions in binary form must reproduce the above copyright notice,
mbed_official 579:53297373a894 19 * this list of conditions and the following disclaimer in the documentation
mbed_official 579:53297373a894 20 * and/or other materials provided with the distribution.
mbed_official 579:53297373a894 21 *
mbed_official 579:53297373a894 22 * 3. The name of Atmel may not be used to endorse or promote products derived
mbed_official 579:53297373a894 23 * from this software without specific prior written permission.
mbed_official 579:53297373a894 24 *
mbed_official 579:53297373a894 25 * 4. This software may only be redistributed and used in connection with an
mbed_official 579:53297373a894 26 * Atmel microcontroller product.
mbed_official 579:53297373a894 27 *
mbed_official 579:53297373a894 28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
mbed_official 579:53297373a894 29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
mbed_official 579:53297373a894 30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
mbed_official 579:53297373a894 31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
mbed_official 579:53297373a894 32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
mbed_official 579:53297373a894 33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
mbed_official 579:53297373a894 34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
mbed_official 579:53297373a894 35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
mbed_official 579:53297373a894 36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
mbed_official 579:53297373a894 37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
mbed_official 579:53297373a894 38 * POSSIBILITY OF SUCH DAMAGE.
mbed_official 579:53297373a894 39 *
mbed_official 579:53297373a894 40 * \asf_license_stop
mbed_official 579:53297373a894 41 *
mbed_official 579:53297373a894 42 */
mbed_official 579:53297373a894 43
mbed_official 579:53297373a894 44 /**
mbed_official 579:53297373a894 45 * \page asfdoc_sam0_sercom_i2c_master_dma_use_case Quick Start Guide for Using DMA with SERCOM I2C Master
mbed_official 579:53297373a894 46 *
mbed_official 579:53297373a894 47 * The supported board list:
mbed_official 579:53297373a894 48 * - SAMD21 Xplained Pro
mbed_official 579:53297373a894 49 * - SAMR21 Xplained Pro
mbed_official 579:53297373a894 50 * - SAML21 Xplained Pro
mbed_official 579:53297373a894 51 *
mbed_official 579:53297373a894 52 * In this use case, the I<SUP>2</SUP>C will used and set up as follows:
mbed_official 579:53297373a894 53 * - Master mode
mbed_official 579:53297373a894 54 * - 100KHz operation speed
mbed_official 579:53297373a894 55 * - Not operational in standby
mbed_official 579:53297373a894 56 * - 10000 packet timeout value
mbed_official 579:53297373a894 57 * - 65535 unknown bus state timeout value
mbed_official 579:53297373a894 58 *
mbed_official 579:53297373a894 59 *
mbed_official 579:53297373a894 60 * \section asfdoc_sam0_sercom_i2c_master_dma_use_case_prereq Prerequisites
mbed_official 579:53297373a894 61 * The device must be connected to an I<SUP>2</SUP>C slave.
mbed_official 579:53297373a894 62 *
mbed_official 579:53297373a894 63 * \section asfdoc_sam0_sercom_i2c_master_dma_use_setup Setup
mbed_official 579:53297373a894 64 *
mbed_official 579:53297373a894 65 * \subsection asfdoc_sam0_sercom_i2c_master_dma_use_setup_code Code
mbed_official 579:53297373a894 66 * The following must be added to the user application:
mbed_official 579:53297373a894 67 *
mbed_official 579:53297373a894 68 * - A sample buffer to send, number of entries to send and address of slave:
mbed_official 579:53297373a894 69 * \snippet qs_i2c_master_dma.c packet_data
mbed_official 579:53297373a894 70 *
mbed_official 579:53297373a894 71 * Number of times to try to send packet if it fails:
mbed_official 579:53297373a894 72 * \snippet qs_i2c_master_dma.c timeout
mbed_official 579:53297373a894 73 *
mbed_official 579:53297373a894 74 * - Globally accessible module structure:
mbed_official 579:53297373a894 75 * \snippet qs_i2c_master_dma.c dev_i2c_inst
mbed_official 579:53297373a894 76 *
mbed_official 579:53297373a894 77 * - Function for setting up the module:
mbed_official 579:53297373a894 78 * \snippet qs_i2c_master_dma.c initialize_i2c
mbed_official 579:53297373a894 79 *
mbed_official 579:53297373a894 80 * - Globally accessible DMA module structure:
mbed_official 579:53297373a894 81 * \snippet qs_i2c_master_dma.c dma_resource
mbed_official 579:53297373a894 82 *
mbed_official 579:53297373a894 83 * - Globally transfer done flag:
mbed_official 579:53297373a894 84 * \snippet qs_i2c_master_dma.c transfer_done_flag
mbed_official 579:53297373a894 85 *
mbed_official 579:53297373a894 86 * - Globally accessible DMA transfer descriptor:
mbed_official 579:53297373a894 87 * \snippet qs_i2c_master_dma.c transfer_descriptor
mbed_official 579:53297373a894 88 *
mbed_official 579:53297373a894 89 * - Function for transfer done callback:
mbed_official 579:53297373a894 90 * \snippet qs_i2c_master_dma.c transfer_done
mbed_official 579:53297373a894 91 *
mbed_official 579:53297373a894 92 * - Function for setting up the DMA resource:
mbed_official 579:53297373a894 93 * \snippet qs_i2c_master_dma.c config_dma_resource
mbed_official 579:53297373a894 94 *
mbed_official 579:53297373a894 95 * - Function for setting up the DMA transfer descriptor:
mbed_official 579:53297373a894 96 * \snippet qs_i2c_master_dma.c setup_dma_transfer_descriptor
mbed_official 579:53297373a894 97 * - Add to user application \c main():
mbed_official 579:53297373a894 98 * \snippet qs_i2c_master_dma.c init
mbed_official 579:53297373a894 99 *
mbed_official 579:53297373a894 100 * \subsection asfdoc_sam0_sercom_i2c_master_dma_use_setup_workflow Workflow
mbed_official 579:53297373a894 101 * \subsubsection asfdoc_sam0_sercom_i2c_master_dma_use_setup_workflow_i2c Configure and enable SERCOM:
mbed_official 579:53297373a894 102 * \snippet qs_i2c_master_dma.c config_i2c
mbed_official 579:53297373a894 103 * -# Create and initialize configuration structure.
mbed_official 579:53297373a894 104 * \snippet qs_i2c_master_dma.c init_conf
mbed_official 579:53297373a894 105 * -# Change settings in the configuration.
mbed_official 579:53297373a894 106 * \snippet qs_i2c_master_dma.c conf_change
mbed_official 579:53297373a894 107 * -# Initialize the module with the set configurations.
mbed_official 579:53297373a894 108 * \snippet qs_i2c_master_dma.c init_module
mbed_official 579:53297373a894 109 * -# Enable the module.
mbed_official 579:53297373a894 110 * \snippet qs_i2c_master_dma.c enable_module
mbed_official 579:53297373a894 111 *
mbed_official 579:53297373a894 112 * \subsubsection asfdoc_sam0_sercom_i2c_master_dma_use_setup_workflow_dma Configure DMA
mbed_official 579:53297373a894 113 * -# Create a DMA resource configuration structure, which can be filled out to
mbed_official 579:53297373a894 114 * adjust the configuration of a single DMA transfer.
mbed_official 579:53297373a894 115 * \snippet qs_i2c_master_dma.c dma_setup_1
mbed_official 579:53297373a894 116 *
mbed_official 579:53297373a894 117 * -# Initialize the DMA resource configuration struct with the module's
mbed_official 579:53297373a894 118 * default values.
mbed_official 579:53297373a894 119 * \snippet qs_i2c_master_dma.c dma_setup_2
mbed_official 579:53297373a894 120 * \note This should always be performed before using the configuration
mbed_official 579:53297373a894 121 * struct to ensure that all values are initialized to known default
mbed_official 579:53297373a894 122 * settings.
mbed_official 579:53297373a894 123 *
mbed_official 579:53297373a894 124 * -# Set extra configurations for the DMA resource. It is using peripheral
mbed_official 579:53297373a894 125 * trigger. SERCOM TX trigger causes a transaction transfer in
mbed_official 579:53297373a894 126 * this example.
mbed_official 579:53297373a894 127 * \snippet qs_i2c_master_dma.c dma_setup_3
mbed_official 579:53297373a894 128 *
mbed_official 579:53297373a894 129 * -# Allocate a DMA resource with the configurations.
mbed_official 579:53297373a894 130 * \snippet qs_i2c_master_dma.c dma_setup_4
mbed_official 579:53297373a894 131 *
mbed_official 579:53297373a894 132 * -# Create a DMA transfer descriptor configuration structure, which can be
mbed_official 579:53297373a894 133 * filled out to adjust the configuration of a single DMA transfer.
mbed_official 579:53297373a894 134 * \snippet qs_i2c_master_dma.c dma_setup_5
mbed_official 579:53297373a894 135 *
mbed_official 579:53297373a894 136 * -# Initialize the DMA transfer descriptor configuration struct with the module's
mbed_official 579:53297373a894 137 * default values.
mbed_official 579:53297373a894 138 * \snippet qs_i2c_master_dma.c dma_setup_6
mbed_official 579:53297373a894 139 * \note This should always be performed before using the configuration
mbed_official 579:53297373a894 140 * struct to ensure that all values are initialized to known default
mbed_official 579:53297373a894 141 * settings.
mbed_official 579:53297373a894 142 *
mbed_official 579:53297373a894 143 * -# Set the specific parameters for a DMA transfer with transfer size, source
mbed_official 579:53297373a894 144 * address, and destination address.
mbed_official 579:53297373a894 145 * \snippet qs_i2c_master_dma.c dma_setup_7
mbed_official 579:53297373a894 146 *
mbed_official 579:53297373a894 147 * -# Create the DMA transfer descriptor.
mbed_official 579:53297373a894 148 * \snippet qs_i2c_master_dma.c dma_setup_8
mbed_official 579:53297373a894 149 *
mbed_official 579:53297373a894 150 * \section asfdoc_sam0_sercom_i2c_master_dma_use_implemenation Implementation
mbed_official 579:53297373a894 151 * \subsection asfdoc_sam0_sercom_i2c_master_dma_use_implemenation_code Code
mbed_official 579:53297373a894 152 * Add to user application \c main():
mbed_official 579:53297373a894 153 * \snippet qs_i2c_master_dma.c main
mbed_official 579:53297373a894 154 *
mbed_official 579:53297373a894 155 * \subsection asfdoc_sam0_sercom_i2c_master_dma_use_implemenation_workflow Workflow
mbed_official 579:53297373a894 156 * -# Start the DMA transfer job.
mbed_official 579:53297373a894 157 * \snippet qs_i2c_master_dma.c start_transfer_job
mbed_official 579:53297373a894 158 *
mbed_official 579:53297373a894 159 * -# Set the auto address length and enable flag.
mbed_official 579:53297373a894 160 * \snippet qs_i2c_master_dma.c set_i2c_addr
mbed_official 579:53297373a894 161 *
mbed_official 579:53297373a894 162 * -# Waiting for transfer complete.
mbed_official 579:53297373a894 163 * \snippet qs_i2c_master_dma.c waiting_for_complete
mbed_official 579:53297373a894 164 *
mbed_official 579:53297373a894 165 * -# Enter an infinite loop once transfer complete.
mbed_official 579:53297373a894 166 * \snippet qs_i2c_master_dma.c inf_loop
mbed_official 579:53297373a894 167 */
mbed_official 579:53297373a894 168 /**
mbed_official 579:53297373a894 169 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
mbed_official 579:53297373a894 170 */