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