mbed official / mbed

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

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_SAMD21G18A/TOOLCHAIN_ARM_MICRO/dac_feature.h@172:65be27845400, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc 
mbed library release version 165

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Kojto 111:4336505e4b1c 1 /**
Kojto 111:4336505e4b1c 2 * \file
Kojto 111:4336505e4b1c 3 *
Kojto 111:4336505e4b1c 4 * \brief SAM Peripheral Digital-to-Analog Converter Driver
Kojto 111:4336505e4b1c 5 *
Kojto 111:4336505e4b1c 6 * Copyright (C) 2012-2015 Atmel Corporation. All rights reserved.
Kojto 111:4336505e4b1c 7 *
Kojto 111:4336505e4b1c 8 * \asf_license_start
Kojto 111:4336505e4b1c 9 *
Kojto 111:4336505e4b1c 10 * \page License
Kojto 111:4336505e4b1c 11 *
Kojto 111:4336505e4b1c 12 * Redistribution and use in source and binary forms, with or without
Kojto 111:4336505e4b1c 13 * modification, are permitted provided that the following conditions are met:
Kojto 111:4336505e4b1c 14 *
Kojto 111:4336505e4b1c 15 * 1. Redistributions of source code must retain the above copyright notice,
Kojto 111:4336505e4b1c 16 * this list of conditions and the following disclaimer.
Kojto 111:4336505e4b1c 17 *
Kojto 111:4336505e4b1c 18 * 2. Redistributions in binary form must reproduce the above copyright notice,
Kojto 111:4336505e4b1c 19 * this list of conditions and the following disclaimer in the documentation
Kojto 111:4336505e4b1c 20 * and/or other materials provided with the distribution.
Kojto 111:4336505e4b1c 21 *
Kojto 111:4336505e4b1c 22 * 3. The name of Atmel may not be used to endorse or promote products derived
Kojto 111:4336505e4b1c 23 * from this software without specific prior written permission.
Kojto 111:4336505e4b1c 24 *
Kojto 111:4336505e4b1c 25 * 4. This software may only be redistributed and used in connection with an
Kojto 111:4336505e4b1c 26 * Atmel microcontroller product.
Kojto 111:4336505e4b1c 27 *
Kojto 111:4336505e4b1c 28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
Kojto 111:4336505e4b1c 29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
Kojto 111:4336505e4b1c 30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
Kojto 111:4336505e4b1c 31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
Kojto 111:4336505e4b1c 32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
Kojto 111:4336505e4b1c 33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
Kojto 111:4336505e4b1c 34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
Kojto 111:4336505e4b1c 35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
Kojto 111:4336505e4b1c 36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
Kojto 111:4336505e4b1c 37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
Kojto 111:4336505e4b1c 38 * POSSIBILITY OF SUCH DAMAGE.
Kojto 111:4336505e4b1c 39 *
Kojto 111:4336505e4b1c 40 * \asf_license_stop
Kojto 111:4336505e4b1c 41 *
Kojto 111:4336505e4b1c 42 */
Kojto 111:4336505e4b1c 43 /*
Kojto 111:4336505e4b1c 44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
Kojto 111:4336505e4b1c 45 */
Kojto 111:4336505e4b1c 46 #ifndef DAC_FEATURE_H_INCLUDED
Kojto 111:4336505e4b1c 47 #define DAC_FEATURE_H_INCLUDED
Kojto 111:4336505e4b1c 48
Kojto 111:4336505e4b1c 49 /**
Kojto 111:4336505e4b1c 50 * \defgroup asfdoc_sam0_dac_group SAM Digital-to-Analog Driver (DAC)
Kojto 111:4336505e4b1c 51 *
Kojto 111:4336505e4b1c 52 * This driver for Atmel&reg; | SMART ARM&reg;-based microcontrollers provides an interface for the conversion of
Kojto 111:4336505e4b1c 53 * digital values to analog voltage. The following driver API modes are covered
Kojto 111:4336505e4b1c 54 * by this manual:
Kojto 111:4336505e4b1c 55 *
Kojto 111:4336505e4b1c 56 * - Polled APIs
Kojto 111:4336505e4b1c 57 * \if DAC_CALLBACK_MODE
Kojto 111:4336505e4b1c 58 * - Callback APIs
Kojto 111:4336505e4b1c 59 * \endif
Kojto 111:4336505e4b1c 60 *
Kojto 111:4336505e4b1c 61 * The following peripherals are used by this module:
Kojto 111:4336505e4b1c 62 * - DAC (Digital-to-Analog Converter)
Kojto 111:4336505e4b1c 63 *
Kojto 111:4336505e4b1c 64 * The following devices can use this module:
Kojto 111:4336505e4b1c 65 * - Atmel | SMART SAM D20/D21
Kojto 111:4336505e4b1c 66 * - Atmel | SMART SAM D10/D11
Kojto 111:4336505e4b1c 67 * - Atmel | SMART SAM DA0/DA1
Kojto 111:4336505e4b1c 68 * - Atmel | SMART SAM C21
Kojto 111:4336505e4b1c 69 *
Kojto 111:4336505e4b1c 70 * The outline of this documentation is as follows:
Kojto 111:4336505e4b1c 71 * - \ref asfdoc_sam0_dac_prerequisites
Kojto 111:4336505e4b1c 72 * - \ref asfdoc_sam0_dac_module_overview
Kojto 111:4336505e4b1c 73 * - \ref asfdoc_sam0_dac_special_considerations
Kojto 111:4336505e4b1c 74 * - \ref asfdoc_sam0_dac_extra_info
Kojto 111:4336505e4b1c 75 * - \ref asfdoc_sam0_dac_examples
Kojto 111:4336505e4b1c 76 * - \ref asfdoc_sam0_dac_api_overview
Kojto 111:4336505e4b1c 77 *
Kojto 111:4336505e4b1c 78 *
Kojto 111:4336505e4b1c 79 * \section asfdoc_sam0_dac_prerequisites Prerequisites
Kojto 111:4336505e4b1c 80 *
Kojto 111:4336505e4b1c 81 * There are no prerequisites for this module.
Kojto 111:4336505e4b1c 82 *
Kojto 111:4336505e4b1c 83 *
Kojto 111:4336505e4b1c 84 * \section asfdoc_sam0_dac_module_overview Module Overview
Kojto 111:4336505e4b1c 85 *
Kojto 111:4336505e4b1c 86 * The Digital-to-Analog converter converts a digital value to analog voltage.
Kojto 111:4336505e4b1c 87 * The SAM DAC module has one channel with 10-bit resolution,
Kojto 111:4336505e4b1c 88 * and is capable of converting up to 350k samples per second (ksps).
Kojto 111:4336505e4b1c 89 *
Kojto 111:4336505e4b1c 90 * A common use of DAC is to generate audio signals by connecting the DAC
Kojto 111:4336505e4b1c 91 * output to a speaker, or to generate a reference voltage; either for an
Kojto 111:4336505e4b1c 92 * external circuit or an internal peripheral such as the Analog Comparator.
Kojto 111:4336505e4b1c 93 *
Kojto 111:4336505e4b1c 94 * After being set up, the DAC will convert new digital values written to the
Kojto 111:4336505e4b1c 95 * conversion data register (DATA) to an analog value either on the VOUT pin of
Kojto 111:4336505e4b1c 96 * the device, or internally for use as an input to the AC, ADC, and other analog
Kojto 111:4336505e4b1c 97 * modules.
Kojto 111:4336505e4b1c 98 *
Kojto 111:4336505e4b1c 99 * Writing the DATA register will start a new conversion. It is also possible
Kojto 111:4336505e4b1c 100 * to trigger the conversion from the event system.
Kojto 111:4336505e4b1c 101 *
Kojto 111:4336505e4b1c 102 * A simplified block diagram of the DAC can be seen in
Kojto 111:4336505e4b1c 103 * \ref asfdoc_sam0_dac_module_block_diagram "the figure below".
Kojto 111:4336505e4b1c 104 *
Kojto 111:4336505e4b1c 105 * \anchor asfdoc_sam0_dac_module_block_diagram
Kojto 111:4336505e4b1c 106 * \image html dac_block_diagram.svg "DAC Block Diagram"
Kojto 111:4336505e4b1c 107 *
Kojto 111:4336505e4b1c 108 * \subsection asfdoc_sam0_dac_conversion_range Conversion Range
Kojto 111:4336505e4b1c 109 * The conversion range is between GND and the selected voltage reference.
Kojto 111:4336505e4b1c 110 * Available voltage references are:
Kojto 111:4336505e4b1c 111 * \li AVCC voltage reference
Kojto 111:4336505e4b1c 112 * \li Internal 1V reference (INT1V)
Kojto 111:4336505e4b1c 113 * \li External voltage reference (AREF)
Kojto 111:4336505e4b1c 114 *
Kojto 111:4336505e4b1c 115 * \note Internal references will be enabled by the driver, but not disabled.
Kojto 111:4336505e4b1c 116 * Any reference not used by the application should be disabled by the application.
Kojto 111:4336505e4b1c 117 *
Kojto 111:4336505e4b1c 118 * The output voltage from a DAC channel is given as:
Kojto 111:4336505e4b1c 119 * \f[
Kojto 111:4336505e4b1c 120 * V_{OUT} = \frac{DATA}{0x3FF} \times VREF
Kojto 111:4336505e4b1c 121 * \f]
Kojto 111:4336505e4b1c 122 *
Kojto 111:4336505e4b1c 123 * \subsection asfdoc_sam0_dac_conversion Conversion
Kojto 111:4336505e4b1c 124 * The digital value written to the conversion data register (DATA) will be
Kojto 111:4336505e4b1c 125 * converted to an analog value.
Kojto 111:4336505e4b1c 126 * Writing the DATA register will start a new conversion.
Kojto 111:4336505e4b1c 127 * It is also possible to write the conversion data to the DATABUF register,
Kojto 111:4336505e4b1c 128 * the writing of the DATA register can then be triggered from the event
Kojto 111:4336505e4b1c 129 * system, which will load the value from DATABUF to DATA.
Kojto 111:4336505e4b1c 130 *
Kojto 111:4336505e4b1c 131 * \subsection asfdoc_sam0_dac_analog_output Analog Output
Kojto 111:4336505e4b1c 132 * The analog output value can be output to either the VOUT pin or internally,
Kojto 111:4336505e4b1c 133 * but not both at the same time.
Kojto 111:4336505e4b1c 134 *
Kojto 111:4336505e4b1c 135 * \subsubsection asfdoc_sam0_dac_analog_output_external External Output
Kojto 111:4336505e4b1c 136 * The output buffer must be enabled in order to drive the DAC output to the
Kojto 111:4336505e4b1c 137 * VOUT pin. Due to the output buffer, the DAC has high drive strength, and is
Kojto 111:4336505e4b1c 138 * capable of driving both resistive and capacitive loads, as well as loads
Kojto 111:4336505e4b1c 139 * which combine both.
Kojto 111:4336505e4b1c 140 *
Kojto 111:4336505e4b1c 141 * \subsubsection asfdoc_sam0_dac_analog_output_internal Internal Output
Kojto 111:4336505e4b1c 142 * The analog value can be internally available for use as input to the
Kojto 111:4336505e4b1c 143 * AC or ADC modules.
Kojto 111:4336505e4b1c 144 *
Kojto 111:4336505e4b1c 145 * \subsection asfdoc_sam0_dac_events Events
Kojto 111:4336505e4b1c 146 * Events generation and event actions are configurable in the DAC.
Kojto 111:4336505e4b1c 147 * The DAC has one event line input and one event output: <i>Start Conversion</i>
Kojto 111:4336505e4b1c 148 * and <i>Data Buffer Empty</i>.
Kojto 111:4336505e4b1c 149 *
Kojto 111:4336505e4b1c 150 * If the Start Conversion input event is enabled in the module configuration,
Kojto 111:4336505e4b1c 151 * an incoming event will load data from the data buffer to the data register
Kojto 111:4336505e4b1c 152 * and start a new conversion. This method synchronizes conversions with
Kojto 111:4336505e4b1c 153 * external events (such as those from a timer module) and ensures regular and
Kojto 111:4336505e4b1c 154 * fixed conversion intervals.
Kojto 111:4336505e4b1c 155 *
Kojto 111:4336505e4b1c 156 * If the Data Buffer Empty output event is enabled in the module configuration,
Kojto 111:4336505e4b1c 157 * events will be generated when the DAC data buffer register becomes empty and
Kojto 111:4336505e4b1c 158 * new data can be loaded to the buffer.
Kojto 111:4336505e4b1c 159 *
Kojto 111:4336505e4b1c 160 * \note The connection of events between modules requires the use of the
Kojto 111:4336505e4b1c 161 * \ref asfdoc_sam0_events_group "SAM Event System Driver (EVENTS)"
Kojto 111:4336505e4b1c 162 * to route output event of one module to the the input event of another.
Kojto 111:4336505e4b1c 163 * For more information on event routing, refer to the event driver
Kojto 111:4336505e4b1c 164 * documentation.
Kojto 111:4336505e4b1c 165 *
Kojto 111:4336505e4b1c 166 * \subsection asfdoc_sam0_dac_data_adjust Left and Right Adjusted Values
Kojto 111:4336505e4b1c 167 * The 10-bit input value to the DAC is contained in a 16-bit register. This
Kojto 111:4336505e4b1c 168 * can be configured to be either left or right adjusted. In
Kojto 111:4336505e4b1c 169 * \ref asfdoc_sam0_dac_module_adj_modes "the figure below" both options are
Kojto 111:4336505e4b1c 170 * shown, and the position of the most (MSB) and the least (LSB) significant bits
Kojto 111:4336505e4b1c 171 * are indicated. The unused bits should always be written to zero.
Kojto 111:4336505e4b1c 172 *
Kojto 111:4336505e4b1c 173 * \anchor asfdoc_sam0_dac_module_adj_modes
Kojto 111:4336505e4b1c 174 * \dot
Kojto 111:4336505e4b1c 175 * digraph {
Kojto 111:4336505e4b1c 176 * subgraph cluster_right {
Kojto 111:4336505e4b1c 177 * msbl [label="MSB", shape=none, group="msbl"];
Kojto 111:4336505e4b1c 178 * lsbl [label="LSB", shape=none];
Kojto 111:4336505e4b1c 179 * node [shape=none];
Kojto 111:4336505e4b1c 180 * color="white";
Kojto 111:4336505e4b1c 181 * reg_left [label=<
Kojto 111:4336505e4b1c 182 * <table cellspacing="0" cellpadding="2" width="100%">
Kojto 111:4336505e4b1c 183 * <tr>
Kojto 111:4336505e4b1c 184 * <td port="msb">15</td>
Kojto 111:4336505e4b1c 185 * <td>14</td>
Kojto 111:4336505e4b1c 186 * <td>13</td>
Kojto 111:4336505e4b1c 187 * <td>12</td>
Kojto 111:4336505e4b1c 188 * <td>11</td>
Kojto 111:4336505e4b1c 189 * <td>10</td>
Kojto 111:4336505e4b1c 190 * <td>9</td>
Kojto 111:4336505e4b1c 191 * <td>8</td>
Kojto 111:4336505e4b1c 192 * <td>7</td>
Kojto 111:4336505e4b1c 193 * <td port="lsb">6</td>
Kojto 111:4336505e4b1c 194 * <td>5</td>
Kojto 111:4336505e4b1c 195 * <td>4</td>
Kojto 111:4336505e4b1c 196 * <td>3</td>
Kojto 111:4336505e4b1c 197 * <td>2</td>
Kojto 111:4336505e4b1c 198 * <td>1</td>
Kojto 111:4336505e4b1c 199 * <td>0</td>
Kojto 111:4336505e4b1c 200 * </tr>
Kojto 111:4336505e4b1c 201 * <tr>
Kojto 111:4336505e4b1c 202 * <td COLSPAN="10"> DATA[9:0] </td>
Kojto 111:4336505e4b1c 203 * <td BGCOLOR="lightgray"> </td>
Kojto 111:4336505e4b1c 204 * <td BGCOLOR="lightgray"> </td>
Kojto 111:4336505e4b1c 205 * <td BGCOLOR="lightgray"> </td>
Kojto 111:4336505e4b1c 206 * <td BGCOLOR="lightgray"> </td>
Kojto 111:4336505e4b1c 207 * <td BGCOLOR="lightgray"> </td>
Kojto 111:4336505e4b1c 208 * <td BGCOLOR="lightgray"> </td>
Kojto 111:4336505e4b1c 209 * </tr>
Kojto 111:4336505e4b1c 210 * </table>
Kojto 111:4336505e4b1c 211 * >];
Kojto 111:4336505e4b1c 212 * msbl -> reg_left:msb:n;
Kojto 111:4336505e4b1c 213 * lsbl -> reg_left:lsb;
Kojto 111:4336505e4b1c 214 * label ="Left adjusted.\n";
Kojto 111:4336505e4b1c 215 * }
Kojto 111:4336505e4b1c 216 * subgraph cluster_left {
Kojto 111:4336505e4b1c 217 * rankdir=TB;
Kojto 111:4336505e4b1c 218 * msb [label="MSB", shape=none];
Kojto 111:4336505e4b1c 219 * lsb [label="LSB", shape=none];
Kojto 111:4336505e4b1c 220 * color="white";
Kojto 111:4336505e4b1c 221 * node [shape=none];
Kojto 111:4336505e4b1c 222 * reg_right [label=<
Kojto 111:4336505e4b1c 223 * <table cellspacing="0" cellpadding="2">
Kojto 111:4336505e4b1c 224 * <tr>
Kojto 111:4336505e4b1c 225 * <td>15</td>
Kojto 111:4336505e4b1c 226 * <td>14</td>
Kojto 111:4336505e4b1c 227 * <td>13</td>
Kojto 111:4336505e4b1c 228 * <td>12</td>
Kojto 111:4336505e4b1c 229 * <td>11</td>
Kojto 111:4336505e4b1c 230 * <td>10</td>
Kojto 111:4336505e4b1c 231 * <td port="msb">9</td>
Kojto 111:4336505e4b1c 232 * <td>8</td>
Kojto 111:4336505e4b1c 233 * <td>7</td>
Kojto 111:4336505e4b1c 234 * <td>6</td>
Kojto 111:4336505e4b1c 235 * <td>5</td>
Kojto 111:4336505e4b1c 236 * <td>4</td>
Kojto 111:4336505e4b1c 237 * <td>3</td>
Kojto 111:4336505e4b1c 238 * <td>2</td>
Kojto 111:4336505e4b1c 239 * <td>1</td>
Kojto 111:4336505e4b1c 240 * <td port="lsb">0</td>
Kojto 111:4336505e4b1c 241 * </tr>
Kojto 111:4336505e4b1c 242 * <tr>
Kojto 111:4336505e4b1c 243 * <td BGCOLOR="lightgray"></td>
Kojto 111:4336505e4b1c 244 * <td BGCOLOR="lightgray"></td>
Kojto 111:4336505e4b1c 245 * <td BGCOLOR="lightgray"></td>
Kojto 111:4336505e4b1c 246 * <td BGCOLOR="lightgray"></td>
Kojto 111:4336505e4b1c 247 * <td BGCOLOR="lightgray"></td>
Kojto 111:4336505e4b1c 248 * <td BGCOLOR="lightgray"></td>
Kojto 111:4336505e4b1c 249 * <td COLSPAN="10"> DATA[9:0] </td>
Kojto 111:4336505e4b1c 250 * </tr>
Kojto 111:4336505e4b1c 251 * </table>
Kojto 111:4336505e4b1c 252 * >];
Kojto 111:4336505e4b1c 253 * msb -> reg_right:msb;
Kojto 111:4336505e4b1c 254 * lsb -> reg_right:lsb:n;
Kojto 111:4336505e4b1c 255 * label = "Right adjusted.\n";
Kojto 111:4336505e4b1c 256 * graph [shape=none];
Kojto 111:4336505e4b1c 257 * }
Kojto 111:4336505e4b1c 258 * }
Kojto 111:4336505e4b1c 259 * \enddot
Kojto 111:4336505e4b1c 260 *
Kojto 111:4336505e4b1c 261 * \subsection asfdoc_sam0_dac_clk_sources Clock Sources
Kojto 111:4336505e4b1c 262 * The clock for the DAC interface (CLK_DAC) is generated by the Power Manager.
Kojto 111:4336505e4b1c 263 * This clock is turned on by default, and can be enabled and disabled in the
Kojto 111:4336505e4b1c 264 * Power Manager.
Kojto 111:4336505e4b1c 265 *
Kojto 111:4336505e4b1c 266 * Additionally, an asynchronous clock source (GCLK_DAC) is required.
Kojto 111:4336505e4b1c 267 * These clocks are normally disabled by default. The selected clock source
Kojto 111:4336505e4b1c 268 * must be enabled in the Power Manager before it can be used by the DAC.
Kojto 111:4336505e4b1c 269 * The DAC core operates asynchronously from the user interface and
Kojto 111:4336505e4b1c 270 * peripheral bus. As a consequence, the DAC needs two clock cycles of both
Kojto 111:4336505e4b1c 271 * CLK_DAC and GCLK_DAC to synchronize the values written to some of the
Kojto 111:4336505e4b1c 272 * control and data registers.
Kojto 111:4336505e4b1c 273 * The oscillator source for the GCLK_DAC clock is selected in the System
Kojto 111:4336505e4b1c 274 * Control Interface (SCIF).
Kojto 111:4336505e4b1c 275 *
Kojto 111:4336505e4b1c 276 * \section asfdoc_sam0_dac_special_considerations Special Considerations
Kojto 111:4336505e4b1c 277 *
Kojto 111:4336505e4b1c 278 * \subsection asfdoc_sam0_dac_special_considerations_output_buffer Output Driver
Kojto 111:4336505e4b1c 279 * The DAC can only do conversions in Active or Idle modes. However, if the
Kojto 111:4336505e4b1c 280 * output buffer is enabled it will draw current even if the system is in
Kojto 111:4336505e4b1c 281 * sleep mode. Therefore, always make sure that the output buffer is not
Kojto 111:4336505e4b1c 282 * enabled when it is not needed, to ensure minimum power consumption.
Kojto 111:4336505e4b1c 283 *
Kojto 111:4336505e4b1c 284 * \subsection asfdoc_sam0_dac_special_considerations_conversion_time Conversion Time
Kojto 111:4336505e4b1c 285 * DAC conversion time is approximately 2.85µs. The user must ensure that new
Kojto 111:4336505e4b1c 286 * data is not written to the DAC before the last conversion is complete.
Kojto 111:4336505e4b1c 287 * Conversions should be triggered by a periodic event from a Timer/Counter or
Kojto 111:4336505e4b1c 288 * another peripheral.
Kojto 111:4336505e4b1c 289 *
Kojto 111:4336505e4b1c 290 *
Kojto 111:4336505e4b1c 291 * \section asfdoc_sam0_dac_extra_info Extra Information
Kojto 111:4336505e4b1c 292 *
Kojto 111:4336505e4b1c 293 * For extra information, see \ref asfdoc_sam0_dac_extra. This includes:
Kojto 111:4336505e4b1c 294 * - \ref asfdoc_sam0_dac_extra_acronyms
Kojto 111:4336505e4b1c 295 * - \ref asfdoc_sam0_dac_extra_dependencies
Kojto 111:4336505e4b1c 296 * - \ref asfdoc_sam0_dac_extra_errata
Kojto 111:4336505e4b1c 297 * - \ref asfdoc_sam0_dac_extra_history
Kojto 111:4336505e4b1c 298 *
Kojto 111:4336505e4b1c 299 *
Kojto 111:4336505e4b1c 300 * \section asfdoc_sam0_dac_examples Examples
Kojto 111:4336505e4b1c 301 *
Kojto 111:4336505e4b1c 302 * For a list of examples related to this driver, see
Kojto 111:4336505e4b1c 303 * \ref asfdoc_sam0_dac_exqsg.
Kojto 111:4336505e4b1c 304 *
Kojto 111:4336505e4b1c 305 *
Kojto 111:4336505e4b1c 306 * \section asfdoc_sam0_dac_api_overview API Overview
Kojto 111:4336505e4b1c 307 * @{
Kojto 111:4336505e4b1c 308 */
Kojto 111:4336505e4b1c 309
Kojto 111:4336505e4b1c 310 #ifdef __cplusplus
Kojto 111:4336505e4b1c 311 extern "C" {
Kojto 111:4336505e4b1c 312 #endif
Kojto 111:4336505e4b1c 313
Kojto 111:4336505e4b1c 314 #include <compiler.h>
Kojto 111:4336505e4b1c 315 #include <clock.h>
Kojto 111:4336505e4b1c 316 #include <gclk.h>
Kojto 111:4336505e4b1c 317
Kojto 111:4336505e4b1c 318
Kojto 111:4336505e4b1c 319 /**
Kojto 111:4336505e4b1c 320 * \name DAC Status Flags
Kojto 111:4336505e4b1c 321 *
Kojto 111:4336505e4b1c 322 * DAC status flags, returned by \ref dac_get_status() and cleared by
Kojto 111:4336505e4b1c 323 * \ref dac_clear_status().
Kojto 111:4336505e4b1c 324 * @{
Kojto 111:4336505e4b1c 325 */
Kojto 111:4336505e4b1c 326
Kojto 111:4336505e4b1c 327 /** Data Buffer Empty Channel 0 - Set when data is transferred from DATABUF
Kojto 111:4336505e4b1c 328 * to DATA by a start conversion event and DATABUF is ready for new data.
Kojto 111:4336505e4b1c 329 */
Kojto 111:4336505e4b1c 330 #define DAC_STATUS_CHANNEL_0_EMPTY (1UL << 0)
Kojto 111:4336505e4b1c 331
Kojto 111:4336505e4b1c 332 /** Under-run Channel 0 - Set when a start conversion event occurs when
Kojto 111:4336505e4b1c 333 * DATABUF is empty.
Kojto 111:4336505e4b1c 334 */
Kojto 111:4336505e4b1c 335 #define DAC_STATUS_CHANNEL_0_UNDERRUN (1UL << 1)
Kojto 111:4336505e4b1c 336
Kojto 111:4336505e4b1c 337 /** @} */
Kojto 111:4336505e4b1c 338
Kojto 111:4336505e4b1c 339 /**
Kojto 111:4336505e4b1c 340 * \brief DAC reference voltage enum.
Kojto 111:4336505e4b1c 341 *
Kojto 111:4336505e4b1c 342 * Enum for the possible reference voltages for the DAC.
Kojto 111:4336505e4b1c 343 */
Kojto 111:4336505e4b1c 344 enum dac_reference {
Kojto 111:4336505e4b1c 345 /** 1V from the internal band-gap reference.*/
Kojto 111:4336505e4b1c 346 DAC_REFERENCE_INT1V = DAC_CTRLB_REFSEL(0),
Kojto 111:4336505e4b1c 347 /** Analog V<SUB>CC</SUB> as reference. */
Kojto 111:4336505e4b1c 348 DAC_REFERENCE_AVCC = DAC_CTRLB_REFSEL(1),
Kojto 111:4336505e4b1c 349 /** External reference on AREF. */
Kojto 111:4336505e4b1c 350 DAC_REFERENCE_AREF = DAC_CTRLB_REFSEL(2),
Kojto 111:4336505e4b1c 351 };
Kojto 111:4336505e4b1c 352
Kojto 111:4336505e4b1c 353 /**
Kojto 111:4336505e4b1c 354 * \brief DAC output selection enum.
Kojto 111:4336505e4b1c 355 *
Kojto 111:4336505e4b1c 356 * Enum for the DAC output selection.
Kojto 111:4336505e4b1c 357 */
Kojto 111:4336505e4b1c 358 enum dac_output {
Kojto 111:4336505e4b1c 359 /** DAC output to VOUT pin */
Kojto 111:4336505e4b1c 360 DAC_OUTPUT_EXTERNAL = DAC_CTRLB_EOEN,
Kojto 111:4336505e4b1c 361 /** DAC output as internal reference */
Kojto 111:4336505e4b1c 362 DAC_OUTPUT_INTERNAL = DAC_CTRLB_IOEN,
Kojto 111:4336505e4b1c 363 /** No output */
Kojto 111:4336505e4b1c 364 DAC_OUTPUT_NONE = 0,
Kojto 111:4336505e4b1c 365 };
Kojto 111:4336505e4b1c 366
Kojto 111:4336505e4b1c 367 /**
Kojto 111:4336505e4b1c 368 * \brief DAC channel selection enum.
Kojto 111:4336505e4b1c 369 *
Kojto 111:4336505e4b1c 370 * Enum for the DAC channel selection.
Kojto 111:4336505e4b1c 371 */
Kojto 111:4336505e4b1c 372 enum dac_channel {
Kojto 111:4336505e4b1c 373 /** DAC output channel 0. */
Kojto 111:4336505e4b1c 374 DAC_CHANNEL_0,
Kojto 111:4336505e4b1c 375 };
Kojto 111:4336505e4b1c 376
Kojto 111:4336505e4b1c 377 /**
Kojto 111:4336505e4b1c 378 * \brief DAC software device instance structure.
Kojto 111:4336505e4b1c 379 *
Kojto 111:4336505e4b1c 380 * DAC software instance structure, used to retain software state information
Kojto 111:4336505e4b1c 381 * of an associated hardware module instance.
Kojto 111:4336505e4b1c 382 *
Kojto 111:4336505e4b1c 383 * \note The fields of this structure should not be altered by the user
Kojto 111:4336505e4b1c 384 * application; they are reserved for module-internal use only.
Kojto 111:4336505e4b1c 385 */
Kojto 111:4336505e4b1c 386 struct dac_module {
Kojto 111:4336505e4b1c 387 #if !defined(__DOXYGEN__)
Kojto 111:4336505e4b1c 388 /** DAC hardware module. */
Kojto 111:4336505e4b1c 389 Dac *hw;
Kojto 111:4336505e4b1c 390 /** DAC output selection. */
Kojto 111:4336505e4b1c 391 enum dac_output output;
Kojto 111:4336505e4b1c 392 /** Reference selection. */
Kojto 111:4336505e4b1c 393 enum dac_reference reference;
Kojto 111:4336505e4b1c 394 /** DAC event selection. */
Kojto 111:4336505e4b1c 395 bool start_on_event;
Kojto 111:4336505e4b1c 396 # if DAC_CALLBACK_MODE == true
Kojto 111:4336505e4b1c 397 /** Pointer to buffer used for ADC results. */
Kojto 111:4336505e4b1c 398 volatile uint16_t *job_buffer;
Kojto 111:4336505e4b1c 399 /** Remaining number of conversions in current job. */
Kojto 111:4336505e4b1c 400 volatile uint16_t remaining_conversions;
Kojto 111:4336505e4b1c 401 /** Transferred number of conversions in current job. */
Kojto 111:4336505e4b1c 402 volatile uint16_t transferred_conversions;
Kojto 111:4336505e4b1c 403 /** DAC callback enable. */
Kojto 111:4336505e4b1c 404 bool callback_enable[DAC_CALLBACK_N];
Kojto 111:4336505e4b1c 405 /** DAC registered callback functions. */
Kojto 111:4336505e4b1c 406 dac_callback_t callback[DAC_CALLBACK_N];
Kojto 111:4336505e4b1c 407 /** Holds the status of the ongoing or last conversion job. */
Kojto 111:4336505e4b1c 408 volatile enum status_code job_status;
Kojto 111:4336505e4b1c 409 # endif
Kojto 111:4336505e4b1c 410 #endif
Kojto 111:4336505e4b1c 411 };
Kojto 111:4336505e4b1c 412
Kojto 111:4336505e4b1c 413 /**
Kojto 111:4336505e4b1c 414 * \brief DAC configuration structure.
Kojto 111:4336505e4b1c 415 *
Kojto 111:4336505e4b1c 416 * Configuration structure for a DAC instance. This structure should be
Kojto 111:4336505e4b1c 417 * initialized by the \ref dac_get_config_defaults()
Kojto 111:4336505e4b1c 418 * function before being modified by the user application.
Kojto 111:4336505e4b1c 419 */
Kojto 111:4336505e4b1c 420 struct dac_config {
Kojto 111:4336505e4b1c 421 /** Reference voltage. */
Kojto 111:4336505e4b1c 422 enum dac_reference reference;
Kojto 111:4336505e4b1c 423 /** Select DAC output. */
Kojto 111:4336505e4b1c 424 enum dac_output output;
Kojto 111:4336505e4b1c 425 /** Left adjusted data. */
Kojto 111:4336505e4b1c 426 bool left_adjust;
Kojto 111:4336505e4b1c 427 /** GCLK generator used to clock the peripheral. */
Kojto 111:4336505e4b1c 428 enum gclk_generator clock_source;
Kojto 111:4336505e4b1c 429 #ifdef FEATURE_DAC_DATABUF_WRITE_PROTECTION
Kojto 111:4336505e4b1c 430 /** Bypass DATABUF write protection. */
Kojto 111:4336505e4b1c 431 bool databuf_protection_bypass;
Kojto 111:4336505e4b1c 432 #endif
Kojto 111:4336505e4b1c 433 /** Voltage pump disable. */
Kojto 111:4336505e4b1c 434 bool voltage_pump_disable;
Kojto 111:4336505e4b1c 435 /**
Kojto 111:4336505e4b1c 436 * The DAC behaves as in normal mode when the chip enters STANDBY sleep
Kojto 111:4336505e4b1c 437 * mode.
Kojto 111:4336505e4b1c 438 */
Kojto 111:4336505e4b1c 439 bool run_in_standby;
Kojto 111:4336505e4b1c 440 #if (SAMC21)
Kojto 111:4336505e4b1c 441 /** Dither mode enable data. */
Kojto 111:4336505e4b1c 442 bool dither_mode;
Kojto 111:4336505e4b1c 443 #endif
Kojto 111:4336505e4b1c 444 };
Kojto 111:4336505e4b1c 445
Kojto 111:4336505e4b1c 446 /**
Kojto 111:4336505e4b1c 447 * \brief DAC event enable/disable structure.
Kojto 111:4336505e4b1c 448 *
Kojto 111:4336505e4b1c 449 * Event flags for the DAC module. This is used to enable and
Kojto 111:4336505e4b1c 450 * disable events via \ref dac_enable_events() and \ref dac_disable_events().
Kojto 111:4336505e4b1c 451 */
Kojto 111:4336505e4b1c 452 struct dac_events {
Kojto 111:4336505e4b1c 453 /** Start a new DAC conversion. */
Kojto 111:4336505e4b1c 454 bool on_event_start_conversion;
Kojto 111:4336505e4b1c 455 /** Enable event generation on data buffer empty. */
Kojto 111:4336505e4b1c 456 bool generate_event_on_buffer_empty;
Kojto 111:4336505e4b1c 457 #if (SAMC21)
Kojto 111:4336505e4b1c 458 /** Enable the falling edge of the input event for DAC1. */
Kojto 111:4336505e4b1c 459 bool generate_event_on_chan_falling_edge;
Kojto 111:4336505e4b1c 460 #endif
Kojto 111:4336505e4b1c 461 };
Kojto 111:4336505e4b1c 462
Kojto 111:4336505e4b1c 463 /**
Kojto 111:4336505e4b1c 464 * \brief DAC channel configuration structure
Kojto 111:4336505e4b1c 465 *
Kojto 111:4336505e4b1c 466 * Configuration for a DAC channel. This structure should be initialized by the
Kojto 111:4336505e4b1c 467 * \ref dac_chan_get_config_defaults() function before being modified by the
Kojto 111:4336505e4b1c 468 * user application.
Kojto 111:4336505e4b1c 469 */
Kojto 111:4336505e4b1c 470 struct dac_chan_config {
Kojto 111:4336505e4b1c 471 #if !defined(__DOXYGEN__)
Kojto 111:4336505e4b1c 472 /** Dummy value to ensure the struct has at least one member. */
Kojto 111:4336505e4b1c 473 uint8_t _dummy;
Kojto 111:4336505e4b1c 474 #endif
Kojto 111:4336505e4b1c 475 };
Kojto 111:4336505e4b1c 476
Kojto 111:4336505e4b1c 477 /**
Kojto 111:4336505e4b1c 478 * \name Configuration and Initialization (Channel)
Kojto 111:4336505e4b1c 479 * @{
Kojto 111:4336505e4b1c 480 */
Kojto 111:4336505e4b1c 481
Kojto 111:4336505e4b1c 482 void dac_chan_enable_output_buffer(
Kojto 111:4336505e4b1c 483 struct dac_module *const dev_inst,
Kojto 111:4336505e4b1c 484 const enum dac_channel channel);
Kojto 111:4336505e4b1c 485
Kojto 111:4336505e4b1c 486 void dac_chan_disable_output_buffer(
Kojto 111:4336505e4b1c 487 struct dac_module *const dev_inst,
Kojto 111:4336505e4b1c 488 const enum dac_channel channel);
Kojto 111:4336505e4b1c 489
Kojto 111:4336505e4b1c 490 /** @} */
Kojto 111:4336505e4b1c 491
Kojto 111:4336505e4b1c 492 /** @} */
Kojto 111:4336505e4b1c 493
Kojto 111:4336505e4b1c 494 /**
Kojto 111:4336505e4b1c 495 * \page asfdoc_sam0_dac_extra Extra Information for DAC Driver
Kojto 111:4336505e4b1c 496 *
Kojto 111:4336505e4b1c 497 * \section asfdoc_sam0_dac_extra_acronyms Acronyms
Kojto 111:4336505e4b1c 498 * The table below presents the acronyms used in this module:
Kojto 111:4336505e4b1c 499 *
Kojto 111:4336505e4b1c 500 * <table>
Kojto 111:4336505e4b1c 501 * <tr>
Kojto 111:4336505e4b1c 502 * <th>Acronym</th>
Kojto 111:4336505e4b1c 503 * <th>Description</th>
Kojto 111:4336505e4b1c 504 * </tr>
Kojto 111:4336505e4b1c 505 * <tr>
Kojto 111:4336505e4b1c 506 * <td>ADC</td>
Kojto 111:4336505e4b1c 507 * <td>Analog-to-Digital Converter</td>
Kojto 111:4336505e4b1c 508 * </tr>
Kojto 111:4336505e4b1c 509 * <tr>
Kojto 111:4336505e4b1c 510 * <td>AC</td>
Kojto 111:4336505e4b1c 511 * <td>Analog Comparator</td>
Kojto 111:4336505e4b1c 512 * </tr>
Kojto 111:4336505e4b1c 513 * <tr>
Kojto 111:4336505e4b1c 514 * <td>DAC</td>
Kojto 111:4336505e4b1c 515 * <td>Digital-to-Analog Converter</td>
Kojto 111:4336505e4b1c 516 * </tr>
Kojto 111:4336505e4b1c 517 * <tr>
Kojto 111:4336505e4b1c 518 * <td>LSB</td>
Kojto 111:4336505e4b1c 519 * <td>Least Significant Bit</td>
Kojto 111:4336505e4b1c 520 * </tr>
Kojto 111:4336505e4b1c 521 * <tr>
Kojto 111:4336505e4b1c 522 * <td>MSB</td>
Kojto 111:4336505e4b1c 523 * <td>Most Significant Bit</td>
Kojto 111:4336505e4b1c 524 * </tr>
Kojto 111:4336505e4b1c 525 * <tr>
Kojto 111:4336505e4b1c 526 * <td>DMA</td>
Kojto 111:4336505e4b1c 527 * <td>Direct Memory Access</td>
Kojto 111:4336505e4b1c 528 * </tr>
Kojto 111:4336505e4b1c 529 * </table>
Kojto 111:4336505e4b1c 530 *
Kojto 111:4336505e4b1c 531 *
Kojto 111:4336505e4b1c 532 * \section asfdoc_sam0_dac_extra_dependencies Dependencies
Kojto 111:4336505e4b1c 533 * This driver has the following dependencies:
Kojto 111:4336505e4b1c 534 *
Kojto 111:4336505e4b1c 535 * - \ref asfdoc_sam0_system_pinmux_group "System Pin Multiplexer Driver"
Kojto 111:4336505e4b1c 536 *
Kojto 111:4336505e4b1c 537 *
Kojto 111:4336505e4b1c 538 * \section asfdoc_sam0_dac_extra_errata Errata
Kojto 111:4336505e4b1c 539 * There are no errata related to this driver.
Kojto 111:4336505e4b1c 540 *
Kojto 111:4336505e4b1c 541 *
Kojto 111:4336505e4b1c 542 * \section asfdoc_sam0_dac_extra_history Module History
Kojto 111:4336505e4b1c 543 * An overview of the module history is presented in the table below, with
Kojto 111:4336505e4b1c 544 * details on the enhancements and fixes made to the module since its first
Kojto 111:4336505e4b1c 545 * release. The current version of this corresponds to the newest version in
Kojto 111:4336505e4b1c 546 * the table.
Kojto 111:4336505e4b1c 547 *
Kojto 111:4336505e4b1c 548 * <table>
Kojto 111:4336505e4b1c 549 * <tr>
Kojto 111:4336505e4b1c 550 * <th>Changelog</th>
Kojto 111:4336505e4b1c 551 * </tr>
Kojto 111:4336505e4b1c 552 * <tr>
Kojto 111:4336505e4b1c 553 * <td>Add configuration for using 14-bit hardware dithering (SAMC21 support)</td>
Kojto 111:4336505e4b1c 554 * </tr>
Kojto 111:4336505e4b1c 555 * <tr>
Kojto 111:4336505e4b1c 556 * <td>Added new configuration parameters \c databuf_protection_bypass,
Kojto 111:4336505e4b1c 557 * \c voltage_pump_disable. Added new callback functions
Kojto 111:4336505e4b1c 558 * \c dac_chan_write_buffer_wait,
Kojto 111:4336505e4b1c 559 * \c dac_chan_write_buffer_job, \c dac_chan_write_job,
Kojto 111:4336505e4b1c 560 * \c dac_get_job_status, \c dac_abort_job and new callback type
Kojto 111:4336505e4b1c 561 * \c DAC_CALLBACK_TRANSFER_COMPLETE for DAC conversion job</td>
Kojto 111:4336505e4b1c 562 * </tr>
Kojto 111:4336505e4b1c 563 * <tr>
Kojto 111:4336505e4b1c 564 * <td>Initial Release</td>
Kojto 111:4336505e4b1c 565 * </tr>
Kojto 111:4336505e4b1c 566 * </table>
Kojto 111:4336505e4b1c 567 */
Kojto 111:4336505e4b1c 568
Kojto 111:4336505e4b1c 569 /**
Kojto 111:4336505e4b1c 570 * \page asfdoc_sam0_dac_exqsg Examples for DAC Driver
Kojto 111:4336505e4b1c 571 *
Kojto 111:4336505e4b1c 572 * This is a list of the available Quick Start guides (QSGs) and example
Kojto 111:4336505e4b1c 573 * applications for \ref asfdoc_sam0_dac_group. QSGs are simple examples with
Kojto 111:4336505e4b1c 574 * step-by-step instructions to configure and use this driver in a selection of
Kojto 111:4336505e4b1c 575 * use cases. Note that a QSG can be compiled as a standalone application or be
Kojto 111:4336505e4b1c 576 * added to the user application.
Kojto 111:4336505e4b1c 577 *
Kojto 111:4336505e4b1c 578 * - \subpage asfdoc_sam0_dac_basic_use_case
Kojto 111:4336505e4b1c 579 * \if DAC_CALLBACK_MODE
Kojto 111:4336505e4b1c 580 * - \subpage asfdoc_sam0_dac_basic_use_case_callback
Kojto 111:4336505e4b1c 581 * \endif
Kojto 111:4336505e4b1c 582 * \if DAC_DMA_USE_MODE_SELECTION
Kojto 111:4336505e4b1c 583 * - \subpage asfdoc_sam0_adc_dma_use_case_dac_in_dma
Kojto 111:4336505e4b1c 584 * \endif
Kojto 111:4336505e4b1c 585 *
Kojto 111:4336505e4b1c 586 * \if DAC_DMA_USE_MODE_SELECTION
Kojto 111:4336505e4b1c 587 * \page asfdoc_sam0_adc_dma_use_case_dac_in_dma Quick Start Guide for Using DMA with ADC/DAC
Kojto 111:4336505e4b1c 588 * For this examples, see
Kojto 111:4336505e4b1c 589 * \ref asfdoc_sam0_adc_dma_use_case
Kojto 111:4336505e4b1c 590 * \endif
Kojto 111:4336505e4b1c 591 *
Kojto 111:4336505e4b1c 592 * \page asfdoc_sam0_dac_document_revision_history Document Revision History
Kojto 111:4336505e4b1c 593 *
Kojto 111:4336505e4b1c 594 * <table>
Kojto 111:4336505e4b1c 595 * <tr>
Kojto 111:4336505e4b1c 596 * <th>Doc. Rev.</td>
Kojto 111:4336505e4b1c 597 * <th>Date</td>
Kojto 111:4336505e4b1c 598 * <th>Comments</td>
Kojto 111:4336505e4b1c 599 * </tr>
Kojto 111:4336505e4b1c 600 * <tr>
Kojto 111:4336505e4b1c 601 * <td>42110E</td>
Kojto 111:4336505e4b1c 602 * <td>06/2015</td>
Kojto 111:4336505e4b1c 603 * <td>Add SAMC21 and SAMDAx support</td>
Kojto 111:4336505e4b1c 604 * </tr>
Kojto 111:4336505e4b1c 605 * <tr>
Kojto 111:4336505e4b1c 606 * <td>42110D</td>
Kojto 111:4336505e4b1c 607 * <td>12/2014</td>
Kojto 111:4336505e4b1c 608 * <td>Add SAMD10/D11 support</td>
Kojto 111:4336505e4b1c 609 * </tr>
Kojto 111:4336505e4b1c 610 * <tr>
Kojto 111:4336505e4b1c 611 * <td>42110C</td>
Kojto 111:4336505e4b1c 612 * <td>01/2014</td>
Kojto 111:4336505e4b1c 613 * <td>Add SAMD21 support</td>
Kojto 111:4336505e4b1c 614 * </tr>
Kojto 111:4336505e4b1c 615 * <tr>
Kojto 111:4336505e4b1c 616 * <td>42110B</td>
Kojto 111:4336505e4b1c 617 * <td>06/2013</td>
Kojto 111:4336505e4b1c 618 * <td>Added additional documentation on the event system. Corrected
Kojto 111:4336505e4b1c 619 * documentation typos.</td>
Kojto 111:4336505e4b1c 620 * </tr>
Kojto 111:4336505e4b1c 621 * <tr>
Kojto 111:4336505e4b1c 622 * <td>42110A</td>
Kojto 111:4336505e4b1c 623 * <td>06/2013</td>
Kojto 111:4336505e4b1c 624 * <td>Initial document release</td>
Kojto 111:4336505e4b1c 625 * </tr>
Kojto 111:4336505e4b1c 626 * </table>
Kojto 111:4336505e4b1c 627 */
Kojto 111:4336505e4b1c 628
Kojto 111:4336505e4b1c 629 #ifdef __cplusplus
Kojto 111:4336505e4b1c 630 }
Kojto 111:4336505e4b1c 631 #endif
Kojto 111:4336505e4b1c 632
Kojto 111:4336505e4b1c 633
Kojto 111:4336505e4b1c 634 #endif /* DAC_FEATURE_H_INCLUDED */
Kojto 111:4336505e4b1c 635