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