1 //***************************************************************************** 2 // 3 //! @file am_hal_utils.h 4 //! 5 //! @brief HAL Utility Functions 6 //! 7 //! @addtogroup utils4_4p Utils - HAL Utility Functions 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_UTILS_H 48 #define AM_HAL_UTILS_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 #include <stdint.h> 56 #include <stdbool.h> 57 58 //***************************************************************************** 59 // 60 //! @brief Use the bootrom to implement a spin loop. 61 //! 62 //! @param ui32us - Number of microseconds to delay. Must be >=1; the 63 //! value of 0 will result in an extremely long delay. 64 //! 65 //! Use this function to implement a CPU busy waiting spin loop without cache 66 //! or delay uncertainties. 67 //! 68 //! Notes for Apollo3: 69 //! - The ROM-based function executes at 3 cycles per iteration plus the normal 70 //! function call, entry, and exit overhead and latencies. 71 //! - Cache settings affect call overhead. However, the cache does not affect 72 //! the time while inside the BOOTROM function. 73 //! - The function accounts for burst vs normal mode, along with some of the 74 //! overhead encountered with executing the function itself (such as the 75 //! check for burst mode). 76 //! - Use of the FLASH_CYCLES_US() or FLASH_CYCLES_US_NOCACHE() macros for the 77 //! ui32Iterations parameter will result in approximate microsecond timing. 78 //! - The parameter ui32Iterations==0 is allowed but is still incurs a delay. 79 //! 80 //! Example: 81 //! - MCU operating at 48MHz -> 20.83 ns / cycle 82 //! - Therefore each iteration (once inside the bootrom function) will consume 83 //! 62.5ns (non-burst-mode). 84 //! 85 //! @note Interrupts are not disabled during execution of this function. 86 //! Therefore, any interrupt taken will affect the delay timing. 87 // 88 //***************************************************************************** 89 extern void am_hal_delay_us(uint32_t ui32us); 90 91 //***************************************************************************** 92 // 93 //! @brief Delays for a desired amount of cycles while also waiting for a 94 //! status to change a value. 95 //! 96 //! @param ui32usMaxDelay - Maximum number of ~1uS delay loops. 97 //! @param ui32Address - Address of the register for the status change. 98 //! @param ui32Mask - Mask for the status change. 99 //! @param ui32Value - Target value for the status change. 100 //! 101 //! This function will delay for approximately the given number of microseconds 102 //! while checking for a status change, exiting when either the given time has 103 //! expired or the status change is detected. 104 //! 105 //! @returns AM_HAL_STATUS_SUCCESS = status change detected. 106 //! AM_HAL_STATUS_TIMEOUT = timeout. 107 // 108 //***************************************************************************** 109 extern uint32_t am_hal_delay_us_status_change(uint32_t ui32usMaxDelay, uint32_t ui32Address, 110 uint32_t ui32Mask, uint32_t ui32Value); 111 112 //***************************************************************************** 113 // 114 //! @brief Delays for a desired amount of cycles while also waiting for a 115 //! status to equal OR not-equal to a value. 116 //! 117 //! @param ui32usMaxDelay - Maximum number of ~1uS delay loops. 118 //! @param ui32Address - Address of the register for the status change. 119 //! @param ui32Mask - Mask for the status change. 120 //! @param ui32Value - Target value for the status change. 121 //! @param bIsEqual - Check for equal if true; not-equal if false. 122 //! 123 //! This function will delay for approximately the given number of microseconds 124 //! while checking for a status change, exiting when either the given time has 125 //! expired or the status change is detected. 126 //! 127 //! @returns 0 = timeout. 128 //! 1 = status change detected. 129 // 130 //***************************************************************************** 131 extern uint32_t am_hal_delay_us_status_check(uint32_t ui32usMaxDelay, uint32_t ui32Address, 132 uint32_t ui32Mask, uint32_t ui32Value, 133 bool bIsEqual); 134 135 //***************************************************************************** 136 // 137 //! @brief Read a uint32 value from a valid memory or peripheral location. 138 //! 139 //! @param pui32Address - The location to be read. 140 //! 141 //! Use this function to safely read a value from peripheral or memory locations. 142 //! 143 //! This function calls a function that resides BOOTROM or SRAM to do the actual 144 //! read, thus completely avoiding any conflict with flash or INFO space. 145 //! 146 //! @return The value read from the given address. 147 // 148 //***************************************************************************** 149 extern uint32_t am_hal_load_ui32(uint32_t *pui32Address); 150 151 //***************************************************************************** 152 // 153 //! @brief Use the bootrom to write to a location in SRAM or the system bus. 154 //! 155 //! @param pui32Address - Store the data value corresponding to this location. 156 //! @param ui32Data - 32-bit Data to be stored. 157 //! 158 //! Use this function to store a value to various peripheral or SRAM locations 159 //! that can not be touched from code running in SRAM or FLASH. There is no 160 //! known need for this function in Apollo3 at this time. 161 // 162 //***************************************************************************** 163 extern void am_hal_store_ui32(uint32_t *pui32Address, uint32_t ui32Data); 164 165 #ifdef __cplusplus 166 } 167 #endif 168 169 #endif // AM_HAL_UTILS_H 170 171 //***************************************************************************** 172 // 173 // End Doxygen group. 174 //! @} 175 // 176 //***************************************************************************** 177 178
