1 //***************************************************************************** 2 // 3 //! @file am_hal_adc.h 4 //! 5 //! @brief Functions for interfacing with the Analog to Digital Converter 6 //! 7 //! @addtogroup adc4_4p ADC - Analog-to-Digital Converter 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision stable-7da8bae71f of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 #ifndef AM_HAL_ADC_H 48 #define AM_HAL_ADC_H 49 50 //***************************************************************************** 51 // 52 //! @brief CMSIS-style macro for handling a variable IOM module number. 53 // 54 //***************************************************************************** 55 #define ADCn(n) ((ADC_Type*)(ADC_BASE + (n * (ADC_BASE - ADC_BASE)))) 56 57 // **************************************************************************** 58 // 59 //! @name Default VREF 60 //! @{ 61 //! 62 //! VREF is needed by applications in order to convert samples to voltages, 63 //! as well as to do the sample corrections in the HAL functions. 64 //! 65 //! Important: It is important to use 1.19v, as opposed to 1.20v, as the 66 //! reference voltage. 67 //! Ambiq recommends using AM_HAL_ADC_VREF to designate Vref in applications. 68 // 69 // **************************************************************************** 70 #define AM_HAL_ADC_VREF 1.19F 71 #define AM_HAL_ADC_VREFMV 1190 // Vref specified in millivolts 72 #define AM_HAL_ADC_VREFMVF (AM_HAL_ADC_VREF * 1000.0F) 73 //! @} 74 75 //***************************************************************************** 76 // 77 //! @name ADC Samples 78 //! @{ 79 //! ADC Sample Macros 80 //! 81 //! These macros may be used to set the ADc Sample bit, divisor and mask 82 // 83 //***************************************************************************** 84 #define AM_HAL_ADC_SAMPLE_BITS (12) // Number of bits in the sample 85 #define AM_HAL_ADC_SAMPLE_2N (1 << AM_HAL_ADC_SAMPLE_BITS) // Exponentiation of 2^^n 86 #define AM_HAL_ADC_SAMPLE_DIVISOR AM_HAL_ADC_SAMPLE_2N // Divisor for 12 bits 87 #define AM_HAL_ADC_SAMPLE_DIVISORF ((float)AM_HAL_ADC_SAMPLE_2N) // Divisor for 12 bits 88 #define AM_HAL_ADC_SAMPLE_MASK ((AM_HAL_ADC_SAMPLE_2N - 1) << 6) // Mask for integer portion of the sample 89 #define AM_HAL_ADC_SAMPLE_MASK_FULL (((1 << (AM_HAL_ADC_SAMPLE_BITS + 6)) - 1)) // Mask for the full sample 90 //! @} 91 92 // **************************************************************************** 93 // 94 //! @brief Maximum number of slots. 95 // 96 // **************************************************************************** 97 #define AM_HAL_ADC_MAX_SLOTS 8 98 99 // **************************************************************************** 100 // 101 //! @brief Minimum value for TRKCYC for the general purpose ADC. 102 // 103 // **************************************************************************** 104 #define AM_HAL_ADC_MIN_TRKCYC 0 105 106 // **************************************************************************** 107 // 108 //! @brief Default slope (in degK / V) of the Apollo4 temperature sensor. 109 // 110 // **************************************************************************** 111 #define AM_HAL_ADC_TEMPSENSOR_SLOPE 290.0F 112 113 // **************************************************************************** 114 // 115 //! @enum am_hal_adc_clksel_e 116 //! @brief ADC clock selection. 117 // 118 // **************************************************************************** 119 typedef enum 120 { 121 //AM_HAL_ADC_CLKSEL_HFRC = 0, 122 AM_HAL_ADC_CLKSEL_HFRC_48MHZ = ADC_CFG_CLKSEL_HFRC_48MHZ, 123 AM_HAL_ADC_CLKSEL_HFRC_48MHZ1 = ADC_CFG_CLKSEL_HFRC_48MHZ1, 124 AM_HAL_ADC_CLKSEL_HFRC_24MHZ = ADC_CFG_CLKSEL_HFRC_24MHZ, 125 AM_HAL_ADC_CLKSEL_HFRC2_48MHZ = ADC_CFG_CLKSEL_HFRC2_48MHZ 126 } am_hal_adc_clksel_e; 127 128 // **************************************************************************** 129 // 130 //! @enum am_hal_adc_rpttrigsel_e 131 //! @brief ADC periodic trigger source selection 132 // 133 // **************************************************************************** 134 typedef enum 135 { 136 AM_HAL_ADC_RPTTRIGSEL_TMR, 137 AM_HAL_ADC_RPTTRIGSEL_INT 138 } am_hal_adc_rpttrigsel_e; 139 140 // **************************************************************************** 141 // 142 //! @enum am_hal_adc_trigpol_e 143 //! @brief ADC trigger polarity 144 // 145 // **************************************************************************** 146 typedef enum 147 { 148 AM_HAL_ADC_TRIGPOL_RISING, 149 AM_HAL_ADC_TRIGPOL_FALLING 150 } am_hal_adc_trigpol_e; 151 152 // **************************************************************************** 153 // 154 //! @enum am_hal_adc_trigsel_e 155 //! @brief ADC trigger selection 156 // 157 // **************************************************************************** 158 typedef enum 159 { 160 AM_HAL_ADC_TRIGSEL_EXT0, 161 AM_HAL_ADC_TRIGSEL_EXT1, 162 AM_HAL_ADC_TRIGSEL_EXT2, 163 AM_HAL_ADC_TRIGSEL_EXT3, 164 AM_HAL_ADC_TRIGSEL_VCOMP, 165 AM_HAL_ADC_TRIGSEL_SOFTWARE = 7 166 } am_hal_adc_trigsel_e; 167 168 // 169 // ADC reference selection. 170 // 171 //typedef enum 172 //{ 173 // AM_HAL_ADC_REFSEL_INT_2P0, 174 // AM_HAL_ADC_REFSEL_INT_1P5, 175 // AM_HAL_ADC_REFSEL_EXT_2P0, 176 // AM_HAL_ADC_REFSEL_EXT_1P5 177 //} am_hal_adc_refsel_e; 178 179 // **************************************************************************** 180 // 181 //! @enum am_hal_adc_clkmode_e 182 //! @brief ADC clock mode selection. 183 // 184 // **************************************************************************** 185 typedef enum 186 { 187 AM_HAL_ADC_CLKMODE_LOW_POWER, // Disable the clock between scans for LPMODE0. 188 // Set LPCKMODE to 0x1 while configuring the ADC. 189 AM_HAL_ADC_CLKMODE_LOW_LATENCY // Low Latency Clock Mode. When set, HFRC and the 190 // adc_clk will remain on while in functioning in LPMODE0. 191 } am_hal_adc_clkmode_e; 192 193 // **************************************************************************** 194 // 195 //! @enum am_hal_adc_lpmode_e 196 //! @brief ADC low-power mode selection. 197 // 198 // **************************************************************************** 199 typedef enum 200 { 201 AM_HAL_ADC_LPMODE0, // Low Latency Clock Mode. When set, HFRC and the adc_clk 202 // will remain on while in functioning in LPMODE0. 203 AM_HAL_ADC_LPMODE1 // Powers down all circuity and clocks associated with the 204 // ADC until the next trigger event. Between scans, the reference 205 // buffer requires up to 50us of delay from a scan trigger event 206 // before the conversion will commence while operating in this mode. 207 } am_hal_adc_lpmode_e; 208 209 // **************************************************************************** 210 // 211 //! @enum am_hal_adc_repeat_e 212 //! @brief ADC repetition selection. 213 // 214 // **************************************************************************** 215 typedef enum 216 { 217 AM_HAL_ADC_SINGLE_SCAN, 218 AM_HAL_ADC_REPEATING_SCAN 219 } am_hal_adc_repeat_e; 220 221 // **************************************************************************** 222 // 223 //! @enum am_hal_adc_meas_avg_e 224 //! @brief ADC measurement averaging configuration. 225 // 226 // **************************************************************************** 227 typedef enum 228 { 229 AM_HAL_ADC_SLOT_AVG_1, 230 AM_HAL_ADC_SLOT_AVG_2, 231 AM_HAL_ADC_SLOT_AVG_4, 232 AM_HAL_ADC_SLOT_AVG_8, 233 AM_HAL_ADC_SLOT_AVG_16, 234 AM_HAL_ADC_SLOT_AVG_32, 235 AM_HAL_ADC_SLOT_AVG_64, 236 AM_HAL_ADC_SLOT_AVG_128 237 } am_hal_adc_meas_avg_e; 238 239 // **************************************************************************** 240 // 241 //! @enum am_hal_adc_slot_prec_e 242 //! @brief ADC slot precision mode. 243 // 244 // **************************************************************************** 245 typedef enum 246 { 247 AM_HAL_ADC_SLOT_12BIT, 248 AM_HAL_ADC_SLOT_12BIT_1, 249 AM_HAL_ADC_SLOT_10BIT, 250 AM_HAL_ADC_SLOT_8BIT 251 } am_hal_adc_slot_prec_e; 252 253 // **************************************************************************** 254 // 255 //! @enum am_hal_adc_slot_chan_e 256 //! @brief ADC slot channel selection. 257 // 258 // **************************************************************************** 259 typedef enum 260 { 261 // Single-ended channels 262 AM_HAL_ADC_SLOT_CHSEL_SE0, 263 AM_HAL_ADC_SLOT_CHSEL_SE1, 264 AM_HAL_ADC_SLOT_CHSEL_SE2, 265 AM_HAL_ADC_SLOT_CHSEL_SE3, 266 AM_HAL_ADC_SLOT_CHSEL_SE4, 267 AM_HAL_ADC_SLOT_CHSEL_SE5, 268 AM_HAL_ADC_SLOT_CHSEL_SE6, 269 AM_HAL_ADC_SLOT_CHSEL_SE7, 270 // Miscellaneous other signals. 271 AM_HAL_ADC_SLOT_CHSEL_TEMP, 272 AM_HAL_ADC_SLOT_CHSEL_BATT, 273 AM_HAL_ADC_SLOT_TEST_MUX, 274 AM_HAL_ADC_SLOT_CHSEL_VSS 275 } am_hal_adc_slot_chan_e; 276 277 // **************************************************************************** 278 // 279 //! @enum am_hal_adc_scale_wincomp_e 280 //! @brief cale window comparator limits 281 // 282 // **************************************************************************** 283 typedef enum 284 { 285 AM_HAL_ADC_SCALE_WINCOMP_DIS, 286 AM_HAL_ADC_SCALE_WINCOMP_EN 287 } am_hal_adc_scale_wincomp_e; 288 289 // **************************************************************************** 290 // 291 //! @enum am_hal_adc_irtt_clkdiv_e 292 //! @brief Internal repeating trigger (irtt) timer clock division 293 // 294 // **************************************************************************** 295 typedef enum 296 { 297 AM_HAL_ADC_RPTT_CLK_DIV1, 298 AM_HAL_ADC_RPTT_CLK_DIV2, 299 AM_HAL_ADC_RPTT_CLK_DIV4, 300 AM_HAL_ADC_RPTT_CLK_DIV16 = 4 301 } am_hal_adc_irtt_clkdiv_e; 302 303 // **************************************************************************** 304 // 305 //! @enum am_hal_adc_dma_prior_e 306 //! @brief DMA priority. 307 // 308 // **************************************************************************** 309 typedef enum 310 { 311 AM_HAL_ADC_PRIOR_BEST_EFFORT, 312 AM_HAL_ADC_PRIOR_SERVICE_IMMED 313 } am_hal_adc_dma_prior_e; 314 315 // **************************************************************************** 316 //! 317 //! @enum am_hal_adc_request_e 318 //! @brief ADC control function request types for am_hal_adc_control(). 319 //! 320 //! AM_HAL_ADC_REQ_TEMP_CELSIUS_GET: 321 //! pArgs must point to an array of 3 floats. To assure that the 322 //! array is valid, upon calling the 3rd float (pArgs[2]) must be 323 //! set to the value -123.456F. 324 //! AM_HAL_ADC_REQ_TEMP_TRIMS_GET: 325 //! pArgs must point to an array of 4 floats. To assure that the 326 //! array is valid, upon calling the 4th float (pArgs[3]) must be 327 //! set to the to the value -123.456F. 328 //! On return, pArgs[3] is set to 1 if the returned values are 329 //! calibrated, or 0 if default calibration values. 330 //! AM_HAL_ADC_REQ_CORRECTION_TRIMS_GET: 331 //! Returns the offset and gain correction values used by the HAL. 332 //! On entry pArgs must point to an array of 4 floats. To assure that 333 //! the array is valid, upon calling the 4th float (pArgs[3]) must be 334 //! set to the to the value -123.456F. 335 //! On return, 336 //! pArgs[0] contains the offset that is applied to each sample. 337 //! pArgs[1] contains the gain that is applied to each sample. 338 //! 339 //! Note that am_hal_adc_samples_read() automatically applies the sample 340 //! correction to samples. Therefore this function is primarily provided 341 //! to the user for informational purposes only. 342 //! 343 // **************************************************************************** 344 typedef enum 345 { 346 AM_HAL_ADC_REQ_WINDOW_CONFIG, 347 AM_HAL_ADC_REQ_TEMP_CELSIUS_GET, 348 AM_HAL_ADC_REQ_TEMP_TRIMS_GET, 349 AM_HAL_ADC_REQ_CORRECTION_TRIMS_GET, 350 } am_hal_adc_request_e; 351 352 // **************************************************************************** 353 // 354 //! @struct am_hal_adc_sample_t 355 //! @brief ADC Sample structure. 356 // 357 // **************************************************************************** 358 typedef struct 359 { 360 uint32_t ui32Sample; 361 uint32_t ui32Slot; 362 } am_hal_adc_sample_t; 363 364 //***************************************************************************** 365 // 366 //! @struct am_hal_adc_config_t 367 //! @brief Configuration structure for the ADC. 368 //! 369 //! eClock = One of the following: 370 //! AM_HAL_ADC_CLKSEL_HFRC 371 //! AM_HAL_ADC_CLKSEL_HFRC_48MHZ 372 //! AM_HAL_ADC_CLKSEL_HFRC_48MHZ1 373 //! AM_HAL_ADC_CLKSEL_HFRC2_24MHZ 374 //! AM_HAL_ADC_CLKSEL_HFRC2_48MHZ 375 //! Notes: 376 //! - AM_HAL_ADC_CLKSEL_HFRC, AM_HAL_ADC_CLKSEL_HFRC_48MHZ, and 377 //! AM_HAL_ADC_CLKSEL_HFRC_48MHZ1 all result in effectively 378 //! the same 48MHz clock source. 379 //! - See the Programmer's Guide for any implications of using 380 //! HFRC2 clock sources. 381 // 382 //***************************************************************************** 383 typedef struct 384 { 385 //! Select the ADC clock source. 386 am_hal_adc_clksel_e eClock; 387 388 //! select the periodic trigger source 389 am_hal_adc_rpttrigsel_e eRepeatTrigger; 390 391 //! Select the ADC trigger polarity. 392 am_hal_adc_trigpol_e ePolarity; 393 394 //! Select the ADC trigger source. 395 am_hal_adc_trigsel_e eTrigger; 396 397 //! Whether to disable clocks between samples. 398 am_hal_adc_clkmode_e eClockMode; 399 400 //! Select the ADC power mode. 401 am_hal_adc_lpmode_e ePowerMode; 402 403 //! Select whether the ADC will re-trigger based on a signal from timer. 404 am_hal_adc_repeat_e eRepeat; 405 406 } am_hal_adc_config_t; 407 408 //***************************************************************************** 409 // 410 //! @struct am_hal_adc_slot_config_t 411 //! @brief Configuration structure for the ADC slot. 412 // 413 //***************************************************************************** 414 typedef struct 415 { 416 //! Select the number of measurements to average 417 am_hal_adc_meas_avg_e eMeasToAvg; 418 419 //! Set additional input sampling ADC clock cycles 420 uint32_t ui32TrkCyc; 421 422 //! Select the precision mode 423 am_hal_adc_slot_prec_e ePrecisionMode; 424 425 //! Select the channel 426 am_hal_adc_slot_chan_e eChannel; 427 428 //! Select window comparison mode 429 bool bWindowCompare; 430 431 //! Enable the slot 432 bool bEnabled; 433 434 } am_hal_adc_slot_config_t; 435 436 //***************************************************************************** 437 // 438 //! @struct am_hal_adc_irtt_config_t 439 //! @brief Configuration structure for the ADC internal repeat trigger timer. 440 // 441 //***************************************************************************** 442 typedef struct 443 { 444 //! ADC-internal repeat trigger timer enable 445 bool bIrttEnable; 446 am_hal_adc_irtt_clkdiv_e eClkDiv; 447 uint32_t ui32IrttCountMax; 448 } am_hal_adc_irtt_config_t; 449 450 //***************************************************************************** 451 // 452 //! @struct am_hal_adc_dma_config_t 453 //! @brief Configuration structure for the ADC DMA 454 // 455 //***************************************************************************** 456 typedef struct 457 { 458 //! ADC DMA dynamic priority enabled. 459 bool bDynamicPriority; 460 461 //! ADC DMA static priority. 462 am_hal_adc_dma_prior_e ePriority; 463 464 //! Enable DMA for ADC 465 bool bDMAEnable; 466 467 //! Transfer count in samples 468 uint32_t ui32SampleCount; 469 470 //! Target address 471 uint32_t ui32TargetAddress; 472 473 } am_hal_adc_dma_config_t; 474 475 //***************************************************************************** 476 // 477 //! @struct am_hal_adc_window_config_t 478 //! @brief Window configuration structure for the ADC. 479 // 480 //***************************************************************************** 481 typedef struct 482 { 483 //! Scale window comparison 484 bool bScaleLimits; 485 486 //! Window limits 487 uint32_t ui32Upper; 488 uint32_t ui32Lower; 489 490 } am_hal_adc_window_config_t; 491 492 //***************************************************************************** 493 // 494 //! @struct am_hal_adc_capabilities_t 495 //! @brief Capabilities structure for the ADC. 496 // 497 //***************************************************************************** 498 typedef struct 499 { 500 uint32_t dummy; 501 502 } am_hal_adc_capabilities_t; 503 504 //***************************************************************************** 505 // 506 //! @struct am_hal_adc_status_t 507 //! @brief Status structure for the ADC. 508 // 509 //***************************************************************************** 510 typedef struct 511 { 512 // 513 // ADC power status. 514 // 515 bool bPoweredOn; 516 bool bLPMode1; 517 518 // 519 // DMA status. 520 // 521 bool bErr; 522 bool bCmp; 523 bool bTIP; 524 525 } am_hal_adc_status_t; 526 527 // **************************************************************************** 528 // 529 //! Transfer callback function prototype 530 // 531 // **************************************************************************** 532 typedef void (*am_hal_adc_callback_t)(void *pCallbackCtxt, uint32_t status); 533 534 //***************************************************************************** 535 // 536 //! @ingroup adc4 537 //! @name ADC Interrupts 538 //! @{ 539 //! Interrupt Status Bits for enable/disble use 540 //! 541 //! These macros may be used to enable an individual ADC interrupt cause. 542 // 543 //***************************************************************************** 544 #define AM_HAL_ADC_INT_DERR (_VAL2FLD(ADC_INTEN_DERR, 1)) 545 #define AM_HAL_ADC_INT_DCMP (_VAL2FLD(ADC_INTEN_DCMP, 1)) 546 #define AM_HAL_ADC_INT_WCINC (_VAL2FLD(ADC_INTEN_WCINC, 1)) 547 #define AM_HAL_ADC_INT_WCEXC (_VAL2FLD(ADC_INTEN_WCEXC, 1)) 548 #define AM_HAL_ADC_INT_FIFOOVR2 (_VAL2FLD(ADC_INTEN_FIFOOVR2, 1)) 549 #define AM_HAL_ADC_INT_FIFOOVR1 (_VAL2FLD(ADC_INTEN_FIFOOVR1, 1)) 550 #define AM_HAL_ADC_INT_SCNCMP (_VAL2FLD(ADC_INTEN_SCNCMP, 1)) 551 #define AM_HAL_ADC_INT_CNVCMP (_VAL2FLD(ADC_INTEN_CNVCMP, 1)) 552 //! @} 553 554 //***************************************************************************** 555 // 556 //! @ingroup adc4 557 //! @name ADC Fifo Read macros 558 //! @{ 559 //! 560 //! These are helper macros for interpreting FIFO data. Each ADC FIFO entry 561 //! contains information about the slot number and the FIFO depth alongside the 562 //! current sample. These macros perform the correct masking and shifting to 563 //! read those values. 564 //! 565 //! The SAMPLE and FULL_SAMPLE options refer to the fractional part of averaged 566 //! samples. If you are not using hardware averaging or don't need the 567 //! fractional part of the ADC sample, you should just use 568 //! AM_HAL_ADC_FIFO_SAMPLE. 569 //! 570 //! If you do need the fractional part, use AM_HAL_ADC_FIFO_FULL_SAMPLE. This 571 //! macro will keep six bits of precision past the decimal point. Depending on 572 //! the number of averaged samples, anywhere between 1 and 6 of these bits will 573 //! be valid. Please consult the datasheet to find out how many bits of data 574 //! are valid for your chosen averaging settings. 575 //! 576 // 577 //***************************************************************************** 578 #define AM_HAL_ADC_FIFO_SAMPLE(value) (_FLD2VAL(ADC_FIFO_DATA, value) >> 6) 579 #define AM_HAL_ADC_FIFO_FULL_SAMPLE(value) (_FLD2VAL(ADC_FIFO_DATA, value)) 580 #define AM_HAL_ADC_FIFO_SLOT(value) (_FLD2VAL(ADC_FIFO_SLOTNUM, value)) 581 #define AM_HAL_ADC_FIFO_COUNT(value) (_FLD2VAL(ADC_FIFO_COUNT, value)) 582 //! @} 583 584 #ifdef __cplusplus 585 extern "C" 586 { 587 #endif 588 589 //***************************************************************************** 590 // 591 //! @brief ADC initialization function 592 //! 593 //! @param ui32Module - module instance. 594 //! @param ppHandle - returns the handle for the module instance. 595 //! 596 //! This function accepts a module instance, allocates the interface and then 597 //! returns a handle to be used by the remaining interface functions. 598 //! 599 //! @return status - generic or interface specific status. 600 //! 601 //! @note A return of AM_HAL_STATUS_SUCCESS does not infer that the 602 //! temperature calibrations are valid. The caller must check the bMeasured 603 //! structure element in order to determine that. 604 // 605 //***************************************************************************** 606 extern uint32_t am_hal_adc_initialize(uint32_t ui32Module, void **ppHandle); 607 608 //***************************************************************************** 609 // 610 //! @brief ADC deinitialization function 611 //! 612 //! @param pHandle - returns the handle for the module instance. 613 //! 614 //! This function accepts a handle to an instance and de-initializes the 615 //! interface. 616 //! 617 //! @return status - generic or interface specific status. 618 // 619 //***************************************************************************** 620 extern uint32_t am_hal_adc_deinitialize(void *pHandle); 621 622 //***************************************************************************** 623 // 624 //! @brief ADC configuration function 625 //! 626 //! @param pHandle - handle for the module instance. 627 //! @param psConfig - pointer to the configuration structure. 628 //! 629 //! This function configures the ADC for operation. 630 //! 631 //! @return status - generic or interface specific status. 632 // 633 //***************************************************************************** 634 extern uint32_t am_hal_adc_configure(void *pHandle, 635 am_hal_adc_config_t *psConfig); 636 637 //***************************************************************************** 638 // 639 //! @brief ADC slot configuration function 640 //! 641 //! @param pHandle - handle for the module instance. 642 //! @param ui32SlotNumber - ADC Slot Number 643 //! @param pSlotConfig - pointer to the configuration structure. 644 //! 645 //! This function configures the ADC slot for operation. 646 //! 647 //! @return status - generic or interface specific status. 648 // 649 //***************************************************************************** 650 extern uint32_t am_hal_adc_configure_slot(void *pHandle, 651 uint32_t ui32SlotNumber, 652 am_hal_adc_slot_config_t *pSlotConfig); 653 654 //***************************************************************************** 655 // 656 //! @brief ADC internal repeat trigger timer configuration function 657 //! 658 //! @param pHandle - handle for the module instance. 659 //! @param pConfig - pointer to the configuration structure. 660 //! 661 //! This function configures the ADC internal repeat trigger timer for operation. 662 //! 663 //! @return status - generic or interface specific status. 664 // 665 //***************************************************************************** 666 extern uint32_t am_hal_adc_configure_irtt(void *pHandle, 667 am_hal_adc_irtt_config_t *pConfig); 668 669 //***************************************************************************** 670 // 671 //! @brief ADC internal repeating trigger timer enable function 672 //! 673 //! @param pHandle - handle for the module instance. 674 //! 675 //! This function enables internal repeating trigger timer. 676 //! 677 //! @note - am_hal_adc_enable() must be called before this function. 678 //! 679 //! @return status - generic or interface specific status. 680 // 681 //***************************************************************************** 682 extern uint32_t am_hal_adc_irtt_enable(void *pHandle); 683 684 //***************************************************************************** 685 // 686 //! @brief ADC internal repeating trigger timer disable function 687 //! 688 //! @param pHandle - handle for the module instance. 689 //! 690 //! This function disables internal repeating trigger timer. 691 //! 692 //! @return status - generic or interface specific status. 693 // 694 //***************************************************************************** 695 extern uint32_t am_hal_adc_irtt_disable(void *pHandle); 696 697 //***************************************************************************** 698 // 699 //! @brief ADC DMA configuration function 700 //! 701 //! @param pHandle - handle for the module instance. 702 //! @param pDMAConfig - pointer to the configuration structure. 703 //! 704 //! This function configures the ADC DMA for operation. 705 //! 706 //! @return status - generic or interface specific status. 707 // 708 //***************************************************************************** 709 extern uint32_t am_hal_adc_configure_dma(void *pHandle, 710 am_hal_adc_dma_config_t *pDMAConfig); 711 712 //***************************************************************************** 713 // 714 //! @brief ADC device specific control function. 715 //! 716 //! @param pHandle - handle for the module instance. 717 //! @param eRequest - One of: 718 //! AM_HAL_ADC_REQ_WINDOW_CONFIG 719 //! @n AM_HAL_ADC_REQ_TEMP_CELSIUS_GET (pArgs is required, see enums). 720 //! @n AM_HAL_ADC_REQ_TEMP_TRIMS_GET (pArgs is required, see enums). 721 //! @param pArgs - Pointer to arguments for Control Switch Case 722 //! 723 //! This function provides for special control functions for the ADC operation. 724 //! 725 //! @return status - generic or interface specific status. 726 // 727 //***************************************************************************** 728 extern uint32_t am_hal_adc_control(void *pHandle, 729 am_hal_adc_request_e eRequest, 730 void *pArgs); 731 732 //***************************************************************************** 733 // 734 //! @brief ADC enable function 735 //! 736 //! @param pHandle - handle for the module instance. 737 //! 738 //! This function enables the ADC operation. 739 //! 740 //! @return status - generic or interface specific status. 741 // 742 //***************************************************************************** 743 extern uint32_t am_hal_adc_enable(void *pHandle); 744 745 //***************************************************************************** 746 // 747 //! @brief ADC disable function 748 //! 749 //! @param pHandle - handle for the module instance. 750 //! 751 //! This function disables the ADC operation. 752 //! 753 //! @return status - generic or interface specific status. 754 // 755 //***************************************************************************** 756 extern uint32_t am_hal_adc_disable(void *pHandle); 757 758 //***************************************************************************** 759 // 760 //! @brief ADC status function 761 //! 762 //! @param pHandle - handle for the interface. 763 //! @param pStatus - return status for the interface 764 //! 765 //! This function returns the current status of the DMA operation. 766 //! 767 //! @return status - DMA status flags. 768 // 769 //***************************************************************************** 770 extern uint32_t am_hal_adc_status_get(void *pHandle, 771 am_hal_adc_status_t *pStatus ); 772 773 //***************************************************************************** 774 // 775 //! @brief ADC enable interrupts function 776 //! 777 //! @param pHandle - handle for the interface. 778 //! @param ui32IntMask - ADC interrupt mask. 779 //! 780 //! This function enables the specific indicated interrupts. 781 //! 782 //! @return status - generic or interface specific status. 783 // 784 //***************************************************************************** 785 extern uint32_t am_hal_adc_interrupt_enable(void *pHandle, uint32_t ui32IntMask); 786 787 //***************************************************************************** 788 // 789 //! @brief ADC disable interrupts function 790 //! 791 //! @param pHandle - handle for the interface. 792 //! @param ui32IntMask - ADC interrupt mask. 793 //! 794 //! This function disable the specific indicated interrupts. 795 //! 796 //! @return status - generic or interface specific status. 797 // 798 //***************************************************************************** 799 extern uint32_t am_hal_adc_interrupt_disable(void *pHandle, uint32_t ui32IntMask); 800 801 //***************************************************************************** 802 // 803 //! @brief ADC interrupt status function 804 //! 805 //! @param pHandle - handle for the interface. 806 //! @param pui32Status - pointer to status 807 //! @param bEnabledOnly - if ADC enabled 808 //! 809 //! This function returns the specific indicated interrupt status. 810 //! 811 //! @return status - generic or interface specific status. 812 // 813 //***************************************************************************** 814 extern uint32_t am_hal_adc_interrupt_status(void *pHandle, 815 uint32_t *pui32Status, 816 bool bEnabledOnly); 817 818 //***************************************************************************** 819 // 820 //! @brief ADC interrupt clear 821 //! 822 //! @param pHandle - handle for the interface. 823 //! @param ui32IntMask - uint32_t for interrupts to clear 824 //! 825 //! This function clears the interrupts for the given peripheral. 826 //! 827 //! @return status - generic or interface specific status. 828 // 829 //***************************************************************************** 830 extern uint32_t am_hal_adc_interrupt_clear(void *pHandle, uint32_t ui32IntMask); 831 832 //***************************************************************************** 833 // 834 //! @brief ADC sample read function 835 //! 836 //! @param pHandle - handle for the module instance. 837 //! @param bFullSample - true to get a full sample including 838 //! the fractional part. 839 //! @param pui32InSampleBuffer - Ptr to the input sample buffer. 840 //! If NULL then samples will be read directly 841 //! from the FIFO. 842 //! @param pui32InOutNumberSamples - Ptr to variable containing the number of 843 //! samples. 844 //! @param pui32OutBuffer - Ptr to the required output sample buffer. 845 //! 846 //! This function reads samples from the ADC FIFO or an SRAM sample buffer 847 //! returned by a DMA operation. 848 //! 849 //! @return status - generic or interface specific status. 850 // 851 //***************************************************************************** 852 extern uint32_t am_hal_adc_samples_read(void *pHandle, bool bFullSample, 853 uint32_t *pui32InSampleBuffer, 854 uint32_t *pui32InOutNumberSamples, 855 am_hal_adc_sample_t *pui32OutBuffer); 856 857 //***************************************************************************** 858 // 859 //! @brief ADC software trigger function 860 //! 861 //! @param pHandle - handle for the module instance. 862 //! 863 //! This function triggers the ADC operation. 864 //! 865 //! @return status - generic or interface specific status. 866 // 867 //***************************************************************************** 868 extern uint32_t am_hal_adc_sw_trigger(void *pHandle); 869 870 //***************************************************************************** 871 // 872 //! @brief ADC power control function 873 //! 874 //! @param pHandle - handle for the interface. 875 //! @param ePowerState - the desired power state to move the peripheral to. 876 //! @param bRetainState - flag (if true) to save/restore peripheral state upon 877 //! power state change. 878 //! 879 //! This function updates the peripheral to a given power state. 880 //! 881 //! @return status - generic or interface specific status. 882 // 883 //***************************************************************************** 884 extern uint32_t am_hal_adc_power_control(void *pHandle, 885 am_hal_sysctrl_power_state_e ePowerState, 886 bool bRetainState); 887 888 #ifdef __cplusplus 889 } 890 #endif 891 892 #endif // AM_HAL_ADC_H 893 894 //***************************************************************************** 895 // 896 // End Doxygen group. 897 //! @} 898 // 899 //***************************************************************************** 900 901
