1 //***************************************************************************** 2 // 3 //! @file am_hal_stimer.h 4 //! 5 //! @brief Functions for interfacing with the system timer (STIMER). 6 //! 7 //! @addtogroup stimer3p STIMER - System Timer 8 //! @ingroup apollo3p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2024, 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_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 #ifndef AM_HAL_STIMER_H 48 #define AM_HAL_STIMER_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 // 56 //! Compute address of a given COMPARE register. 57 //! @note - The parameter n should be 0 (as only 1 stimer module exists). 58 //! For Apollo3, the parameter r should be 0-7 (compare) or 0-3 (capture). 59 // 60 #define AM_REG_STIMER_COMPARE(n, r) (CTIMERADDRn(CTIMER, n, SCMPR0) + \ 61 (r * (offsetof(CTIMER_Type, SCMPR1) - offsetof(CTIMER_Type, SCMPR0)))) 62 63 //! Compute address of a given CAPTURE register. r should be 0-3. 64 #define AM_REG_STIMER_CAPTURE(n, r) (CTIMERADDRn(CTIMER, n, SCAPT0) + \ 65 (r * (offsetof(CTIMER_Type, SCAPT1) - offsetof(CTIMER_Type, SCAPT0)))) 66 67 //! Compute address of a given NVRAM register. r should be 0-3. 68 #define AM_REG_STIMER_NVRAM(n, r) (CTIMERADDRn(CTIMER, n, SNVR0) + \ 69 (r * (offsetof(CTIMER_Type, SNVR1) - offsetof(CTIMER_Type, SNVR0)))) 70 71 72 //***************************************************************************** 73 // 74 //! @name Interrupt Status Bits 75 //! @brief Interrupt Status Bits for enable/disble use 76 //! 77 //! These macros may be used to set and clear interrupt bits 78 //! @{ 79 // 80 //***************************************************************************** 81 #define AM_HAL_STIMER_INT_COMPAREA CTIMER_STMINTSTAT_COMPAREA_Msk 82 #define AM_HAL_STIMER_INT_COMPAREB CTIMER_STMINTSTAT_COMPAREB_Msk 83 #define AM_HAL_STIMER_INT_COMPAREC CTIMER_STMINTSTAT_COMPAREC_Msk 84 #define AM_HAL_STIMER_INT_COMPARED CTIMER_STMINTSTAT_COMPARED_Msk 85 #define AM_HAL_STIMER_INT_COMPAREE CTIMER_STMINTSTAT_COMPAREE_Msk 86 #define AM_HAL_STIMER_INT_COMPAREF CTIMER_STMINTSTAT_COMPAREF_Msk 87 #define AM_HAL_STIMER_INT_COMPAREG CTIMER_STMINTSTAT_COMPAREG_Msk 88 #define AM_HAL_STIMER_INT_COMPAREH CTIMER_STMINTSTAT_COMPAREH_Msk 89 90 #define AM_HAL_STIMER_INT_OVERFLOW CTIMER_STMINTSTAT_OVERFLOW_Msk 91 92 #define AM_HAL_STIMER_INT_CAPTUREA CTIMER_STMINTSTAT_CAPTUREA_Msk 93 #define AM_HAL_STIMER_INT_CAPTUREB CTIMER_STMINTSTAT_CAPTUREB_Msk 94 #define AM_HAL_STIMER_INT_CAPTUREC CTIMER_STMINTSTAT_CAPTUREC_Msk 95 #define AM_HAL_STIMER_INT_CAPTURED CTIMER_STMINTSTAT_CAPTURED_Msk 96 97 //! @} 98 99 //***************************************************************************** 100 // 101 //! @name STimer Configuration Bits 102 //! @brief Interrupt Status Bits for enable/disble use 103 //! 104 //! These macros may be used to set and clear interrupt bits 105 //! @{ 106 // 107 //***************************************************************************** 108 #define AM_HAL_STIMER_CFG_THAW _VAL2FLD(CTIMER_STCFG_FREEZE, CTIMER_STCFG_FREEZE_THAW) 109 #define AM_HAL_STIMER_CFG_FREEZE _VAL2FLD(CTIMER_STCFG_FREEZE, CTIMER_STCFG_FREEZE_FREEZE) 110 #define AM_HAL_STIMER_CFG_RUN _VAL2FLD(CTIMER_STCFG_CLEAR, CTIMER_STCFG_CLEAR_RUN) 111 #define AM_HAL_STIMER_CFG_CLEAR _VAL2FLD(CTIMER_STCFG_CLEAR, CTIMER_STCFG_CLEAR_CLEAR) 112 #define AM_HAL_STIMER_CFG_COMPARE_A_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_A_EN, CTIMER_STCFG_COMPARE_A_EN_ENABLE) 113 #define AM_HAL_STIMER_CFG_COMPARE_B_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_B_EN, CTIMER_STCFG_COMPARE_B_EN_ENABLE) 114 #define AM_HAL_STIMER_CFG_COMPARE_C_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_C_EN, CTIMER_STCFG_COMPARE_C_EN_ENABLE) 115 #define AM_HAL_STIMER_CFG_COMPARE_D_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_D_EN, CTIMER_STCFG_COMPARE_D_EN_ENABLE) 116 #define AM_HAL_STIMER_CFG_COMPARE_E_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_E_EN, CTIMER_STCFG_COMPARE_E_EN_ENABLE) 117 #define AM_HAL_STIMER_CFG_COMPARE_F_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_F_EN, CTIMER_STCFG_COMPARE_F_EN_ENABLE) 118 #define AM_HAL_STIMER_CFG_COMPARE_G_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_G_EN, CTIMER_STCFG_COMPARE_G_EN_ENABLE) 119 #define AM_HAL_STIMER_CFG_COMPARE_H_ENABLE _VAL2FLD(CTIMER_STCFG_COMPARE_H_EN, CTIMER_STCFG_COMPARE_H_EN_ENABLE) 120 121 //! @} 122 123 //***************************************************************************** 124 // 125 //! @name Clock Configuration options 126 //! @brief STimer Configuration register options. 127 //! 128 //! These options are to be used with the am_hal_stimer_config() function. 129 //! @{ 130 // 131 //***************************************************************************** 132 #define AM_HAL_STIMER_NO_CLK _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_NOCLK) 133 #define AM_HAL_STIMER_HFRC_3MHZ _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_HFRC_DIV16) 134 #define AM_HAL_STIMER_HFRC_187_5KHZ _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_HFRC_DIV256) 135 #define AM_HAL_STIMER_XTAL_32KHZ _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_XTAL_DIV1) 136 #define AM_HAL_STIMER_XTAL_16KHZ _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_XTAL_DIV2) 137 #define AM_HAL_STIMER_XTAL_1KHZ _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_XTAL_DIV32) 138 #define AM_HAL_STIMER_LFRC_1KHZ _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_LFRC_DIV1) 139 #define AM_HAL_STIMER_HFRC_CTIMER0A _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_CTIMER0A) 140 #define AM_HAL_STIMER_HFRC_CTIMER0B _VAL2FLD(CTIMER_STCFG_CLKSEL, CTIMER_STCFG_CLKSEL_CTIMER0B) 141 //! @} 142 143 144 145 //***************************************************************************** 146 // 147 //! @name Capture Control Register options. 148 //! @brief Configuration options for capture control register. 149 //! 150 //! These options are to be used with the am_hal_stimer_capture_control_set 151 //! function. 152 //! @{ 153 // 154 //***************************************************************************** 155 #define AM_HAL_STIMER_CAPTURE0_ENABLE _VAL2FLD(CTIMER_CAPTURECONTROL_CAPTURE0, CTIMER_CAPTURECONTROL_CAPTURE0_ENABLE) 156 #define AM_HAL_STIMER_CAPTURE1_ENABLE _VAL2FLD(CTIMER_CAPTURECONTROL_CAPTURE1, CTIMER_CAPTURECONTROL_CAPTURE1_ENABLE) 157 #define AM_HAL_STIMER_CAPTURE2_ENABLE _VAL2FLD(CTIMER_CAPTURECONTROL_CAPTURE2, CTIMER_CAPTURECONTROL_CAPTURE2_ENABLE) 158 #define AM_HAL_STIMER_CAPTURE3_ENABLE _VAL2FLD(CTIMER_CAPTURECONTROL_CAPTURE3, CTIMER_CAPTURECONTROL_CAPTURE3_ENABLE) 159 160 //! @} 161 162 //***************************************************************************** 163 // 164 //! Stimer configuration structure 165 // 166 //***************************************************************************** 167 typedef struct 168 { 169 // 170 //! Configuration options for the STIMER 171 // 172 uint32_t ui32STimerConfig; 173 } 174 am_hal_stimer_config_t; 175 176 //***************************************************************************** 177 // 178 // External function definitions 179 // 180 //***************************************************************************** 181 182 //***************************************************************************** 183 // 184 //! @brief Set up the stimer. 185 //! 186 //! @param ui32STimerConfig - The value to load into the configuration reg. 187 //! 188 //! @note This function should be used to perform the initial set-up of the 189 //! stimer. 190 //! 191 //! @return The 32-bit current config of the STimer Config register 192 // 193 //***************************************************************************** 194 extern uint32_t am_hal_stimer_config(uint32_t ui32STimerConfig); 195 196 //***************************************************************************** 197 // 198 //! @brief Get the current stimer value. 199 //! 200 //! This function can be used to read, uninvasively, the value in the stimer. 201 //! 202 //! @return The 32-bit value from the STimer counter register. 203 // 204 //***************************************************************************** 205 extern uint32_t am_hal_stimer_counter_get(void); 206 207 //***************************************************************************** 208 // 209 //! @brief Clear the stimer counter. 210 //! 211 //! This function clears the STimer Counter and leaves the stimer running. 212 // 213 //***************************************************************************** 214 extern void am_hal_stimer_counter_clear(void); 215 216 //***************************************************************************** 217 // 218 //! @brief Set the compare value. 219 //! 220 //! @param ui32CmprInstance - The compare register instance number (0-7). 221 //! @param ui32Delta - The value to add to the STimer counter and load into 222 //! the comparator register. 223 //! 224 //! @note There is no way to set an absolute value into a comparator register. 225 //! Only deltas added to the STimer counter can be written to the compare 226 //! registers. 227 //! 228 //! @return 0 on success. 229 // 230 //***************************************************************************** 231 extern uint32_t am_hal_stimer_compare_delta_set(uint32_t ui32CmprInstance, 232 uint32_t ui32Delta); 233 //***************************************************************************** 234 // 235 //! @brief Get the current stimer compare register value. 236 //! 237 //! @param ui32CmprInstance - The compare register instance number (0-7). 238 //! 239 //! This function can be used to read the value in an stimer compare register. 240 // 241 //***************************************************************************** 242 extern uint32_t am_hal_stimer_compare_get(uint32_t ui32CmprInstance); 243 244 //***************************************************************************** 245 // 246 //! @brief Start capturing data with the specified capture register. 247 //! 248 //! @param ui32CaptureNum - The compare register instance number (0-7) 249 //! @param ui32GPIONumber - The compare register instance number (0-7) 250 //! @param bPolarity: false (0) = Capture on low to high transition.\n 251 //! true (1) = Capture on high to low transition. 252 //! 253 //! Use this function to start capturing. 254 // 255 //***************************************************************************** 256 extern void am_hal_stimer_capture_start(uint32_t ui32CaptureNum, 257 uint32_t ui32GPIONumber, 258 bool bPolarity); 259 260 //***************************************************************************** 261 // 262 //! @brief Start capturing data with the specified capture register. 263 //! 264 //! @param ui32CaptureNum - - The Capture Register Number to read. 265 //! 266 //! Use this function to start capturing. 267 // 268 //***************************************************************************** 269 extern void am_hal_stimer_capture_stop(uint32_t ui32CaptureNum); 270 271 //***************************************************************************** 272 // 273 //! @brief Get the current stimer capture register value. 274 //! 275 //! @param ui32CaptureNum - The Capture Register Number to read. 276 //! 277 //! This function can be used to read the value in an stimer capture register. 278 //! 279 //! @return Stimer Capture Register Value. 280 // 281 //***************************************************************************** 282 extern uint32_t am_hal_stimer_capture_get(uint32_t ui32CaptureNum); 283 284 //***************************************************************************** 285 // 286 //! @brief Get the current stimer nvram register value. 287 //! 288 //! @param ui32NvramNum - The NVRAM Register Number. 289 //! @param ui32NvramVal - The value to write to NVRAM. 290 //! 291 //! This function can be used to read the value in an stimer NVRAM register. 292 // 293 //***************************************************************************** 294 extern void am_hal_stimer_nvram_set(uint32_t ui32NvramNum, uint32_t ui32NvramVal); 295 296 //***************************************************************************** 297 // 298 //! @brief Get the current stimer nvram register value. 299 //! 300 //! @param ui32NvramNum - The NVRAM Register Number to read. 301 //! 302 //! This function can be used to read the value in an stimer NVRAM register. 303 //! 304 //! @return NVRAM Register Value 305 //! 306 // 307 //***************************************************************************** 308 extern uint32_t am_hal_stimer_nvram_get(uint32_t ui32NvramNum); 309 310 //***************************************************************************** 311 // 312 //! @brief Enables the selected system timer interrupt. 313 //! 314 //! This function will enable the selected interrupts in the STIMER interrupt 315 //! enable register. 316 //! 317 //! @note In order to receive an interrupt from an stimer component, 318 //! you will need to enable the interrupt for that component in this main 319 //! register, as well as in the stimer configuration register (accessible though 320 //! am_hal_stimer_config()), and in the NVIC. 321 //! 322 //! @param ui32Interrupt - The interrupt to be used. 323 //! @parblock 324 //! 325 //! ui32Interrupt should be the logical OR of one or more of the following 326 //! values: 327 //! 328 //! AM_HAL_STIMER_INT_COMPAREA 329 //! AM_HAL_STIMER_INT_COMPAREB 330 //! AM_HAL_STIMER_INT_COMPAREC 331 //! AM_HAL_STIMER_INT_COMPARED 332 //! AM_HAL_STIMER_INT_COMPAREE 333 //! AM_HAL_STIMER_INT_COMPAREF 334 //! AM_HAL_STIMER_INT_COMPAREG 335 //! AM_HAL_STIMER_INT_COMPAREH 336 //! 337 //! AM_HAL_STIMER_INT_OVERFLOW 338 //! 339 //! AM_HAL_STIMER_INT_CAPTUREA 340 //! AM_HAL_STIMER_INT_CAPTUREB 341 //! AM_HAL_STIMER_INT_CAPTUREC 342 //! AM_HAL_STIMER_INT_CAPTURED 343 //! @endparblock 344 // 345 //***************************************************************************** 346 extern void am_hal_stimer_int_enable(uint32_t ui32Interrupt); 347 348 //***************************************************************************** 349 // 350 //! @brief Return the enabled stimer interrupts. 351 //! 352 //! This function will return all enabled interrupts in the STIMER 353 //! interrupt enable register. 354 //! 355 //! @return return enabled interrupts. This will be a logical or of: 356 //! 357 //! AM_HAL_STIMER_INT_COMPAREA 358 //! AM_HAL_STIMER_INT_COMPAREB 359 //! AM_HAL_STIMER_INT_COMPAREC 360 //! AM_HAL_STIMER_INT_COMPARED 361 //! AM_HAL_STIMER_INT_COMPAREE 362 //! AM_HAL_STIMER_INT_COMPAREF 363 //! AM_HAL_STIMER_INT_COMPAREG 364 //! AM_HAL_STIMER_INT_COMPAREH 365 //! AM_HAL_STIMER_INT_OVERFLOW 366 //! AM_HAL_STIMER_INT_CAPTUREA 367 //! AM_HAL_STIMER_INT_CAPTUREB 368 //! AM_HAL_STIMER_INT_CAPTUREC 369 //! AM_HAL_STIMER_INT_CAPTURED 370 // 371 //***************************************************************************** 372 extern uint32_t am_hal_stimer_int_enable_get(void); 373 374 //***************************************************************************** 375 // 376 //! @brief Disables the selected stimer interrupt. 377 //! 378 //! This function will disable the selected interrupts in the STIMER 379 //! interrupt register. 380 //! 381 //! @param ui32Interrupt - The interrupt to be used. 382 //! @parblock 383 //! 384 //! ui32Interrupt should be the logical OR of one or more of the following 385 //! values: 386 //! 387 //! AM_HAL_STIMER_INT_COMPAREA 388 //! AM_HAL_STIMER_INT_COMPAREB 389 //! AM_HAL_STIMER_INT_COMPAREC 390 //! AM_HAL_STIMER_INT_COMPARED 391 //! AM_HAL_STIMER_INT_COMPAREE 392 //! AM_HAL_STIMER_INT_COMPAREF 393 //! AM_HAL_STIMER_INT_COMPAREG 394 //! AM_HAL_STIMER_INT_COMPAREH 395 //! 396 //! AM_HAL_STIMER_INT_OVERFLOW 397 //! 398 //! AM_HAL_STIMER_INT_CAPTUREA 399 //! AM_HAL_STIMER_INT_CAPTUREB 400 //! AM_HAL_STIMER_INT_CAPTUREC 401 //! AM_HAL_STIMER_INT_CAPTURED 402 //! @endparblock 403 // 404 //***************************************************************************** 405 extern void am_hal_stimer_int_disable(uint32_t ui32Interrupt); 406 407 //***************************************************************************** 408 // 409 //! @brief Sets the selected stimer interrupt. 410 //! 411 //! This function will set the selected interrupts in the STIMER 412 //! interrupt register. 413 //! 414 //! @param ui32Interrupt - The interrupt to be used. 415 //! @parblock 416 //! 417 //! ui32Interrupt should be the logical OR of one or more of the following 418 //! values: 419 //! 420 //! AM_HAL_STIMER_INT_COMPAREA 421 //! AM_HAL_STIMER_INT_COMPAREB 422 //! AM_HAL_STIMER_INT_COMPAREC 423 //! AM_HAL_STIMER_INT_COMPARED 424 //! AM_HAL_STIMER_INT_COMPAREE 425 //! AM_HAL_STIMER_INT_COMPAREF 426 //! AM_HAL_STIMER_INT_COMPAREG 427 //! AM_HAL_STIMER_INT_COMPAREH 428 //! 429 //! AM_HAL_STIMER_INT_OVERFLOW 430 //! 431 //! AM_HAL_STIMER_INT_CAPTUREA 432 //! AM_HAL_STIMER_INT_CAPTUREB 433 //! AM_HAL_STIMER_INT_CAPTUREC 434 //! AM_HAL_STIMER_INT_CAPTURED 435 //! @endparblock 436 // 437 //***************************************************************************** 438 extern void am_hal_stimer_int_set(uint32_t ui32Interrupt); 439 440 //***************************************************************************** 441 // 442 //! @brief Clears the selected stimer interrupt. 443 //! 444 //! This function will clear the selected interrupts in the STIMER 445 //! interrupt register. 446 //! 447 //! @param ui32Interrupt - The interrupt to be used. 448 //! @parblock 449 //! 450 //! ui32Interrupt should be the logical OR of one or more of the following 451 //! values: 452 //! 453 //! AM_HAL_STIMER_INT_COMPAREA 454 //! AM_HAL_STIMER_INT_COMPAREB 455 //! AM_HAL_STIMER_INT_COMPAREC 456 //! AM_HAL_STIMER_INT_COMPARED 457 //! AM_HAL_STIMER_INT_COMPAREE 458 //! AM_HAL_STIMER_INT_COMPAREF 459 //! AM_HAL_STIMER_INT_COMPAREG 460 //! AM_HAL_STIMER_INT_COMPAREH 461 //! 462 //! AM_HAL_STIMER_INT_OVERFLOW 463 //! 464 //! AM_HAL_STIMER_INT_CAPTUREA 465 //! AM_HAL_STIMER_INT_CAPTUREB 466 //! AM_HAL_STIMER_INT_CAPTUREC 467 //! AM_HAL_STIMER_INT_CAPTURED 468 //! @endparblock 469 // 470 //***************************************************************************** 471 extern void am_hal_stimer_int_clear(uint32_t ui32Interrupt); 472 473 //***************************************************************************** 474 // 475 //! @brief Returns either the enabled or raw stimer interrupt status. 476 //! 477 //! This function will return the stimer interrupt status. 478 //! 479 //! @param bEnabledOnly if true returns the status of the enabled interrupts 480 //! only. 481 //! 482 //! The return value will be the logical OR of one or more of the following 483 //! values: 484 //! 485 //! @return Returns the stimer interrupt status. 486 // 487 //***************************************************************************** 488 extern uint32_t am_hal_stimer_int_status_get(bool bEnabledOnly); 489 490 491 #ifdef __cplusplus 492 } 493 #endif 494 495 #endif // AM_HAL_STIMER_H 496 497 //***************************************************************************** 498 // 499 // End Doxygen group. 500 //! @} 501 // 502 //***************************************************************************** 503
