1 /** 2 * \file 3 * 4 * \brief SAMB Peripheral Analog-to-Digital Converter Driver 5 * 6 * Copyright (C) 2015 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 47 #ifndef ADC_SAM_B_H_INCLUDED 48 #define ADC_SAM_B_H_INCLUDED 49 50 /** 51 * \defgroup asfdoc_samb_adc_group SAM Analog-to-Digital Converter (ADC) Driver 52 * 53 * This driver for Atmel® | SMART SAM devices provides an interface for the 54 * configuration and management of the device's Analog-to-Digital Converter 55 * functionality, for the conversion of analog voltages into a corresponding 56 * digital form. 57 * 58 * The following peripheral is used by this module: 59 * - ADC (Analog-to-Digital Converter) 60 * 61 * The following devices can use this module: 62 * - Atmel | SMART SAM B11 63 * 64 * The outline of this documentation is as follows: 65 * - \ref asfdoc_samb_adc_prerequisites 66 * - \ref asfdoc_samb_adc_module_overview 67 * - \ref asfdoc_samb_adc_special_considerations 68 * - \ref asfdoc_samb_adc_extra_info 69 * - \ref asfdoc_samb_adc_examples 70 * - \ref asfdoc_samb_adc_api_overview 71 * 72 * 73 * \section asfdoc_samb_adc_prerequisites Prerequisites 74 * 75 * There are no prerequisites for this module. 76 * 77 * 78 * \section asfdoc_samb_adc_module_overview Module Overview 79 * 80 * This driver provides an interface for the Analog-to-Digital conversion 81 * functions on the device, to convert analog voltages to a corresponding 82 * digital value. The ADC has up to 12-bit resolution. 83 * 84 * \subsection asfdoc_samb_adc_module_overview_prescaler Sample Clock Prescaler 85 * \f[ 86 * F_{clk} = N + 2 \times {(throughput\_frequency)} 87 * \f] 88 * \f[ 89 * (N = ADC resolution) 90 * \f] 91 * 92 * Example: For throughput of 100KS/s use sampling clock (Fclk=1.3MHz) 93 * 94 * \subsection asfdoc_samb_adc_module_overview_resolution ADC Resolution 95 * There are two ADC resolution of operation: 96 * - \b High Resolution (11-bit) 97 * 98 * Set the reference voltage to half the supply voltage or below. In this 99 * mode the input signal dynamic range equals twice the reference voltage. 100 * 101 * Example: If supply voltage =3V and reference voltage= 1.4V, input signal 102 * dynamic range can be from ground to 2*reference voltage (0~2.8V). 103 * - \b Medium Resolution (10-bit) 104 * 105 * Set the reference voltage to any value below supply voltage (up to 106 * supply voltage - 300mV) and in this condition the input dynamic range is 107 * from zero to reference voltage. 108 * 109 * Example: If supply voltage =3V and reference voltage= 2.7V, input signal 110 * dynamic range can be from ground to reference voltage (0~2.7V). 111 * 112 * \subsection asfdoc_samb_adc_module_overview_conversion Channel Modes 113 * There are two modes for input channel selection: 114 * - Either to assign a specific input channel 115 * - Time domain multiplexing between 4 input channels 116 * - Channel1 to channel4 117 * - channel5 to channel8 118 * 119 * \section asfdoc_samb_adc_special_considerations Special Considerations 120 * An integrated analog temperature sensor is available for use with the ADC. 121 * The internal specific voltage can also be measured by the ADC. For internal 122 * ADC inputs, the internal source(s) may need to be manually enabled by the 123 * user application before they can be measured. 124 * 125 * 126 * \section asfdoc_samb_adc_extra_info Extra Information 127 * 128 * For extra information, see \ref asfdoc_samb_adc_extra. This includes: 129 * - \ref asfdoc_samb_adc_extra_acronyms 130 * - \ref asfdoc_samb_adc_extra_dependencies 131 * - \ref asfdoc_samb_adc_extra_errata 132 * - \ref asfdoc_samb_adc_extra_history 133 * 134 * 135 * \section asfdoc_samb_adc_examples Examples 136 * 137 * For a list of examples related to this driver, see 138 * \ref asfdoc_samb_adc_exqsg. 139 * 140 * 141 * \section asfdoc_samb_adc_api_overview API Overview 142 * @{ 143 */ 144 145 #ifdef __cplusplus 146 extern "C" { 147 #endif 148 149 #include <compiler.h> 150 #include <system_sam_b.h> 151 152 /** 153 * \brief ADC internal reference voltage level enum 154 * 155 * Enum for the possible internal reference voltage level for the ADC. 156 * 157 */ 158 enum adc_internal_buf { 159 /** Internal buffer voltage level: 0.5V */ 160 ADC_INTERNAL_BUF_0_5 = 0, 161 /** Internal buffer voltage level: 0.6V */ 162 ADC_INTERNAL_BUF_0_6, 163 /** Internal buffer voltage level: 0.7V */ 164 ADC_INTERNAL_BUF_0_7, 165 /** Internal buffer voltage level: 0.8V */ 166 ADC_INTERNAL_BUF_0_8, 167 /** Internal buffer voltage level: 0.9V */ 168 ADC_INTERNAL_BUF_0_9, 169 /** Internal buffer voltage level: 1.0V */ 170 ADC_INTERNAL_BUF_1_0, 171 /** Internal buffer voltage level: 1.1V */ 172 ADC_INTERNAL_BUF_1_1, 173 /** Internal buffer voltage level: 1.2V */ 174 ADC_INTERNAL_BUF_1_2, 175 /** Internal buffer voltage level: 1.3V */ 176 ADC_INTERNAL_BUF_1_3, 177 /** Internal buffer voltage level: 1.4V */ 178 ADC_INTERNAL_BUF_1_4, 179 /** Internal buffer voltage level: 1.5V */ 180 ADC_INTERNAL_BUF_1_5, 181 /** Internal buffer voltage level: 1.6V */ 182 ADC_INTERNAL_BUF_1_6, 183 /** Internal buffer voltage level: 1.7V */ 184 ADC_INTERNAL_BUF_1_7, 185 /** Internal buffer voltage level: 1.8V */ 186 ADC_INTERNAL_BUF_1_8, 187 /** Internal buffer voltage level: 1.9V */ 188 ADC_INTERNAL_BUF_1_9, 189 /** Internal buffer voltage level: 2.0V */ 190 ADC_INTERNAL_BUF_2_0, 191 }; 192 193 /** 194 * \brief ADC reference voltage enum 195 * 196 * Enum for the possible reference voltages for the ADC. 197 * 198 */ 199 enum adc_reference { 200 /** Internal form buffer reference */ 201 ADC_REFERENCE_INTERNAL_BUF = 0, 202 /** Internal from IxR reference */ 203 ADC_REFERENCE_INTERNAL_IR, 204 /** VBATT/2 reference */ 205 ADC_REFERENCE_VBATT_2, 206 /** GPIO_MS1 reference */ 207 ADC_REFERENCE_GPIO_MS1, 208 /** GPIO_MS2 reference */ 209 ADC_REFERENCE_GPIO_MS2, 210 /** GPIO_MS3 reference */ 211 ADC_REFERENCE_GPIO_MS3, 212 /** GPIO_MS4 reference */ 213 ADC_REFERENCE_GPIO_MS4, 214 /** VBATTERY reference */ 215 ADC_REFERENCE_VBATT, 216 }; 217 218 /** 219 * \brief ADC input channel selection enum 220 * 221 * Enum for the possible input channel selections for the ADC. 222 * 223 */ 224 enum adc_input_channel { 225 /** GPIO_MS1 input */ 226 ADC_INPUT_CH_GPIO_MS1 = 0, 227 /** GPIO_MS2 input */ 228 ADC_INPUT_CH_GPIO_MS2, 229 /** GPIO_MS3 input */ 230 ADC_INPUT_CH_GPIO_MS3, 231 /** GPIO_MS4 input */ 232 ADC_INPUT_CH_GPIO_MS4, 233 /** On chip temperature measurement input */ 234 ADC_INPUT_CH_TEMPERATURE, 235 /** VBATT divided by 4 voltage level */ 236 ADC_INPUT_CH_VBATT_4, 237 /** LP_LDO_OUT_1P2 low power domain voltage */ 238 ADC_INPUT_CH_LPD0_LDO, 239 /** ADC reference voltage level */ 240 ADC_INPUT_CH_VREF, 241 }; 242 243 /** 244 * \brief ADC input channel time multiplexing selection mode enum 245 * 246 * Enum for the possible channel time multiplexing mode for the ADC. 247 * 248 */ 249 enum adc_channel_mode { 250 /** 251 * Input channels time multiplexing is between channel 0 to channel 3. 252 * In this mode, ADC input channel selection is invalid. 253 */ 254 ADC_CH_MODE_CH0_TO_CH3, 255 /** 256 * Input channels time multiplexing is between channel 4 to channel 7. 257 * In this mode, ADC input channel selection is invalid. 258 */ 259 ADC_CH_MODE_CH4_TO_CH7, 260 /** Assign a specific input channel using \ref adc_input_channel */ 261 ADC_CH_MODE_ASSIGN, 262 }; 263 264 /** 265 * \brief ADC input dynamic range selection enum 266 * 267 * Enum for the possible input dynamic range for the ADC. 268 * 269 */ 270 enum adc_input_dynamic_range{ 271 /** Input dynamic range from 0V to VBATT voltage level */ 272 ADC_INPUT_DYNAMIC_RANGE_0 = 0, 273 /** Input dynamic range from 0.08*VBATT to 0.92*VBATT voltage level */ 274 ADC_INPUT_DYNAMIC_RANGE_1, 275 /** Input dynamic range from 0.17*VBATT to 0.83*VBATT voltage level */ 276 ADC_INPUT_DYNAMIC_RANGE_2, 277 /** Input dynamic range from 0.25*VBATT to 0.75*VBATT voltage level */ 278 ADC_INPUT_DYNAMIC_RANGE_3, 279 }; 280 281 /** 282 * \brief ADC comparator biasing current enum 283 * 284 * Enum for the possible comparator biasing current for the ADC different 285 * sampling rates. 286 * 287 */ 288 enum adc_bias_current { 289 /** Comparator bias current is 4uA for throughput 100KS/s */ 290 ADC_BIAS_CURRENT_0 = 0, 291 /** Comparator bias current is 8uA */ 292 ADC_BIAS_CURRENT_1, 293 /** Comparator bias current is 20uA */ 294 ADC_BIAS_CURRENT_2, 295 /** Comparator bias current is 24uA for throughput 1MS/s */ 296 ADC_BIAS_CURRENT_3, 297 }; 298 299 /** 300 * \brief ADC configuration structure 301 * 302 * Configuration structure for an ADC instance. This structure should be 303 * initialized by the \ref adc_get_config_defaults() 304 * function before being modified by the user application. 305 */ 306 struct adc_config { 307 /** Voltage reference */ 308 enum adc_reference reference; 309 /** Internal reference voltage level */ 310 enum adc_internal_buf internal_vref; 311 /** Input channel */ 312 enum adc_input_channel input_channel; 313 /** Input channel selection */ 314 enum adc_channel_mode channel_mode; 315 /** Input channel time multiplexing selection mode */ 316 enum adc_input_dynamic_range input_dynamic_range; 317 /** Comparator biasing current selection */ 318 enum adc_bias_current bias_current; 319 /** Invert ADC Clock */ 320 bool invert_clock; 321 /** Fractional part for the clock divider */ 322 uint8_t frac_part; 323 /** Integer part for the clock divider */ 324 uint16_t int_part; 325 }; 326 327 /** \name Configuration, initialization and get status 328 * @{ 329 */ 330 void adc_get_config_defaults(struct adc_config *const config); 331 void adc_init(struct adc_config *config); 332 uint32_t adc_get_status(void); 333 /** @}*/ 334 335 /** \name Enable/Disable and Reset 336 * @{ 337 */ 338 void adc_enable(void); 339 void adc_disable(void); 340 void adc_reset(void); 341 /** @}*/ 342 343 /** \name Read Result 344 * @{ 345 */ 346 enum status_code adc_read(enum adc_input_channel input_channel, uint16_t *result); 347 /** @}*/ 348 349 /** @}*/ 350 351 #ifdef __cplusplus 352 } 353 #endif 354 355 356 /** 357 * \page asfdoc_samb_adc_extra Extra Information for ADC Driver 358 * 359 * \section asfdoc_samb_adc_extra_acronyms Acronyms 360 * Below is a table listing the acronyms used in this module, along with their 361 * intended meanings. 362 * 363 * <table> 364 * <tr> 365 * <th>Acronym</th> 366 * <th>Description</th> 367 * </tr> 368 * <tr> 369 * <td>ADC</td> 370 * <td>Analog-to-Digital Converter</td> 371 * </tr> 372 * </table> 373 * 374 * 375 * \section asfdoc_samb_adc_extra_dependencies Dependencies 376 * There are no dependencies related to this driver. 377 * 378 * 379 * \section asfdoc_samb_adc_extra_errata Errata 380 * There are no errata related to this driver. 381 * 382 * 383 * \section asfdoc_samb_adc_extra_history Module History 384 * An overview of the module history is presented in the table below, with 385 * details on the enhancements and fixes made to the module since its first 386 * release. The current version of this corresponds to the newest version in 387 * the table. 388 * 389 * <table> 390 * <tr> 391 * <th>Changelog</th> 392 * </tr> 393 * <tr> 394 * <td>Initial Release</td> 395 * </tr> 396 * </table> 397 */ 398 399 /** 400 * \page asfdoc_samb_adc_exqsg Examples for ADC Driver 401 * 402 * This is a list of the available Quick Start guides (QSGs) and example 403 * applications for \ref asfdoc_samb_adc_group. QSGs are simple examples with 404 * step-by-step instructions to configure and use this driver in a selection of 405 * use cases. Note that a QSG can be compiled as a standalone application or be 406 * added to the user application. 407 * 408 * - \subpage asfdoc_samb_adc_basic_use_case 409 * 410 * \page asfdoc_samb_adc_document_revision_history Document Revision History 411 * 412 * <table> 413 * <tr> 414 * <th>Doc. Rev.</td> 415 * <th>Date</td> 416 * <th>Comments</td> 417 * </tr> 418 * <tr> 419 * <td>A</td> 420 * <td>09/2015</td> 421 * <td>Initial document release</td> 422 * </tr> 423 * </table> 424 */ 425 426 #endif /* ADC_SAM_B_H_INCLUDED */ 427