1 // **************************************************************************** 2 // 3 //! @file am_hal_cachectrl.h 4 //! 5 //! @brief Functions for Interfacing with the CACHE Controller. 6 //! 7 //! @addtogroup cachectrl3 Cache - Cache Control 8 //! @ingroup apollo3_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_CACHECTRL_H 48 #define AM_HAL_CACHECTRL_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 // 56 //! Designate this peripheral. 57 // 58 #define AM_APOLLO3_CACHECTRL 1 59 60 // 61 //! Cachectrl status. 62 // 63 typedef struct 64 { 65 bool bFlash0SleepMode; 66 bool bFlash1SleepMode; 67 bool bCacheReady; 68 } am_hal_cachectrl_status_t; 69 70 // **************************************************************************** 71 // 72 //! @name Cache Config 73 //! @brief Configuration selection for the cache. 74 //! 75 //! These macros may be used in conjunction with the 76 //! am_hal_cachectrl_cache_config() function to select the cache type. 77 //! 78 //! @{ 79 // 80 // **************************************************************************** 81 // 82 //! Cache description type, where: 83 //! - nWay = number of ways (associativity) 84 //! - 128B = 128 bits linesize 85 //! - 512E = 512 entries, 86 //! - 1024E = 1024 entries 87 // 88 typedef enum 89 { 90 AM_HAL_CACHECTRL_DESCR_1WAY_128B_512E = CACHECTRL_CACHECFG_CONFIG_W1_128B_512E, 91 AM_HAL_CACHECTRL_DESCR_2WAY_128B_512E = CACHECTRL_CACHECFG_CONFIG_W2_128B_512E, 92 AM_HAL_CACHECTRL_DESCR_1WAY_128B_1024E = CACHECTRL_CACHECFG_CONFIG_W1_128B_1024E 93 } am_hal_cachectrl_descr_e; 94 95 typedef enum 96 { 97 AM_HAL_CACHECTRL_NCR0 = 0, 98 AM_HAL_CACHECTRL_NCR1 = 1 99 } am_hal_cachectrl_nc_region_e; 100 101 // 102 //! Config structure for AM_HAL_CACHECTRL_CONTROL_NC_CFG 103 // 104 typedef struct 105 { 106 am_hal_cachectrl_nc_region_e eNCRegion; 107 bool bEnable; 108 uint32_t ui32StartAddr; 109 uint32_t ui32EndAddr; 110 } am_hal_cachectrl_nc_cfg_t; 111 112 // 113 //! Control operations. 114 // 115 typedef enum 116 { 117 AM_HAL_CACHECTRL_CONTROL_FLASH_CACHE_INVALIDATE = 1, 118 AM_HAL_CACHECTRL_CONTROL_STATISTICS_RESET, 119 AM_HAL_CACHECTRL_CONTROL_FLASH_ALL_SLEEP_ENABLE, 120 AM_HAL_CACHECTRL_CONTROL_FLASH_ALL_SLEEP_DISABLE, 121 AM_HAL_CACHECTRL_CONTROL_FLASH0_SLEEP_ENABLE, 122 AM_HAL_CACHECTRL_CONTROL_FLASH0_SLEEP_DISABLE, 123 AM_HAL_CACHECTRL_CONTROL_FLASH1_SLEEP_ENABLE, 124 AM_HAL_CACHECTRL_CONTROL_FLASH1_SLEEP_DISABLE, 125 AM_HAL_CACHECTRL_CONTROL_MONITOR_ENABLE, 126 AM_HAL_CACHECTRL_CONTROL_MONITOR_DISABLE, 127 AM_HAL_CACHECTRL_CONTROL_LPMMODE_RESET, 128 AM_HAL_CACHECTRL_CONTROL_LPMMODE_RECOMMENDED, 129 AM_HAL_CACHECTRL_CONTROL_LPMMODE_AGGRESSIVE, 130 AM_HAL_CACHECTRL_CONTROL_LPMMODE_SET, 131 AM_HAL_CACHECTRL_CONTROL_SEDELAY_SET, 132 AM_HAL_CACHECTRL_CONTROL_RDWAIT_SET, 133 // Configure up to two non-cacheable regions 134 AM_HAL_CACHECTRL_CONTROL_NC_CFG, 135 } am_hal_cachectrl_control_e; 136 137 // 138 //! Cache config values used for ui8Mode. 139 // 140 typedef enum 141 { 142 // Note - this enum ordering is critical, do not modify. 143 AM_HAL_CACHECTRL_CONFIG_MODE_DISABLE, 144 AM_HAL_CACHECTRL_CONFIG_MODE_INSTR, 145 AM_HAL_CACHECTRL_CONFIG_MODE_DATA, 146 AM_HAL_CACHECTRL_CONFIG_MODE_INSTR_DATA 147 } am_hal_cachectrl_config_mode_e; 148 149 // 150 //! FLASHCFG LPMMODE. 151 // 152 typedef enum 153 { 154 AM_HAL_CACHECTRL_FLASHCFG_LPMMODE_NEVER = CACHECTRL_FLASHCFG_LPMMODE_NEVER, 155 AM_HAL_CACHECTRL_FLASHCFG_LPMMODE_STANDBY = CACHECTRL_FLASHCFG_LPMMODE_STANDBY, 156 AM_HAL_CACHECTRL_FLASHCFG_LPMMODE_ALWAYS = CACHECTRL_FLASHCFG_LPMMODE_ALWAYS 157 } am_hal_cachectrl_flashcfg_lppmode_e; 158 159 160 //! @} cache config 161 // **************************************************************************** 162 // 163 // Cache configuration structure 164 // This structure used for am_hal_cachectrl_config(). 165 // 166 // **************************************************************************** 167 typedef struct 168 { 169 // 170 //! Set to one of the following 171 //! - AM_HAL_CACHECTRL_DESCR_1WAY_128B_512E 172 //! - Direct mapped, 128-bit linesize, 512 entries (4 SRAMs active) 173 //! - AM_HAL_CACHECTRL_DESCR_2WAY_128B_512E 174 //! - Two way set associative, 128-bit linesize, 512 entries (8 SRAMs active) 175 //! - AM_HAL_CACHECTRL_DESCR_1WAY_128B_1024E 176 //! - Direct-mapped set associative, 128-bit linesize, 1024 entries (8 SRAMs active) 177 am_hal_cachectrl_descr_e eDescript; 178 179 // 180 //! Set to one of the following: 181 //! - AM_HAL_CACHECTRL_CONFIG_MODE_DISABLE - Disable both instr and data caching 182 //! - AM_HAL_CACHECTRL_CONFIG_MODE_INSTR - Enable instr caching only 183 //! - AM_HAL_CACHECTRL_CONFIG_MODE_DATA - Enable data caching only 184 //! - AM_HAL_CACHECTRL_CONFIG_MODE_INSTR_DATA - Enable both instr and data caching 185 am_hal_cachectrl_config_mode_e eMode; 186 187 //! Set to one of the following: 188 //! - Set to true to enable the LRU (least recently used) replacement policy.\n 189 //! - Set to false to enable the LRR (least recently replaced) replacement policy.\n 190 //! - Note - LRR minimizes writes to the TAG SRAM. 191 // 192 bool bLRU; 193 194 } am_hal_cachectrl_config_t; 195 196 extern const am_hal_cachectrl_config_t am_hal_cachectrl_defaults; 197 198 // **************************************************************************** 199 // 200 // Function prototypes 201 // 202 // **************************************************************************** 203 // **************************************************************************** 204 // 205 //! @brief Configure the cache using the supplied settings. 206 //! 207 //! @param psConfig - pointer to a config structure containing cache settings. 208 //! 209 //! This function takes in a structure of cache settings and uses them to 210 //! configure the cache. This function will configures all of the settings in 211 //! the structure as well as recommended settings for various other cache 212 //! configuration parameters. 213 //! 214 //! @note This function does NOT enable the cache, which is handled in a separate 215 //! function. In fact, if the cache is enabled prior to calling this function, 216 //! it will return from the call disabled. 217 //! @par 218 //! @note For most applications, the default cache settings will be the most 219 //! efficient choice. To use the default cache settings with this function, use 220 //! the address of the global am_hal_cachectrl_defaults structure as the 221 //! psConfig argument. 222 //! 223 //! @return Status. 224 // 225 // **************************************************************************** 226 extern uint32_t am_hal_cachectrl_config(const am_hal_cachectrl_config_t *psConfig); 227 228 // **************************************************************************** 229 // 230 //! @brief Enable the cache. 231 //! 232 //! Enable the cache for operation. 233 //! 234 //! @return Status. 235 // 236 // **************************************************************************** 237 extern uint32_t am_hal_cachectrl_enable(void); 238 239 // **************************************************************************** 240 // 241 //! @brief Disable the cache. 242 //! 243 //! Use this function to disable cache. Other configuration settings are not 244 //! not required. 245 //! 246 //! @return Status. 247 // 248 // **************************************************************************** 249 extern uint32_t am_hal_cachectrl_disable(void); 250 251 // **************************************************************************** 252 // 253 //! @brief Assert various specific controls on the cache. 254 //! 255 //! This function is used to apply various controls on the cache. 256 //! 257 //! @param eControl - One of the following: 258 //! - AM_HAL_CACHECTRL_CONTROL_FLASH_CACHE_INVALIDATE 259 //! - AM_HAL_CACHECTRL_CONTROL_STATISTICS_RESET 260 //! - AM_HAL_CACHECTRL_CONTROL_FLASH_ALL_SLEEP_ENABLE, 261 //! - AM_HAL_CACHECTRL_CONTROL_FLASH_ALL_SLEEP_DISABLE, 262 //! - AM_HAL_CACHECTRL_CONTROL_FLASH0_SLEEP_ENABLE 263 //! - AM_HAL_CACHECTRL_CONTROL_FLASH0_SLEEP_DISABLE 264 //! - AM_HAL_CACHECTRL_CONTROL_FLASH1_SLEEP_ENABLE 265 //! - AM_HAL_CACHECTRL_CONTROL_FLASH1_SLEEP_DISABLE 266 //! 267 //! @param pArgs - pointer to args structure 268 //! 269 //! @return status - generic or interface specific status. 270 // 271 // **************************************************************************** 272 extern uint32_t am_hal_cachectrl_control(am_hal_cachectrl_control_e eControl, 273 void *pArgs); 274 275 // **************************************************************************** 276 // 277 //! @brief Cache controller status function 278 //! 279 //! This function returns the current status of the cache. 280 //! 281 //! @param psStatus - ptr to a status structure to receive the current statuses. 282 //! 283 //! @return status - generic or interface specific status. 284 // 285 // **************************************************************************** 286 extern uint32_t am_hal_cachectrl_status_get(am_hal_cachectrl_status_t *psStatus); 287 288 #ifdef __cplusplus 289 } 290 #endif 291 292 #endif // AM_HAL_CACHECTRL_H 293 294 //***************************************************************************** 295 // 296 // End Doxygen group. 297 //! @} 298 // 299 //***************************************************************************** 300
