1 // **************************************************************************** 2 // 3 //! @file am_hal_cachectrl.h 4 //! 5 //! @brief Functions for interfacing with the CACHE controller. 6 //! 7 //! @addtogroup cachectrl4_4p CACHE - Cache Control 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_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_APOLLO4_CACHECTRL 1 59 60 // 61 //! Cachectrl status. 62 // 63 typedef struct 64 { 65 bool bCacheReady; 66 } am_hal_cachectrl_status_t; 67 68 // **************************************************************************** 69 // 70 //! @name Cache Config 71 //! @{ 72 //! Configuration selection for the cache. 73 //! 74 //! These macros may be used in conjunction with the 75 //! am_hal_cachectrl_cache_config() function to select the cache type. 76 // 77 // **************************************************************************** 78 // 79 //! Cache description type, where: 80 //! nWay = number of ways (associativity) 81 //! 128B = 128 bits linesize 82 //! 512E = 512 entries, 1024E = 1024 entries, 2048E = 2048 entries, 4096E = 4096 entries. 83 typedef enum 84 { 85 AM_HAL_CACHECTRL_DESCR_1WAY_128B_512E = CPU_CACHECFG_CONFIG_W1_128B_512E, 86 AM_HAL_CACHECTRL_DESCR_2WAY_128B_512E = CPU_CACHECFG_CONFIG_W2_128B_512E, 87 AM_HAL_CACHECTRL_DESCR_1WAY_128B_1024E = CPU_CACHECFG_CONFIG_W1_128B_1024E, 88 AM_HAL_CACHECTRL_DESCR_1WAY_128B_2048E = CPU_CACHECFG_CONFIG_W1_128B_2048E, 89 AM_HAL_CACHECTRL_DESCR_2WAY_128B_2048E = CPU_CACHECFG_CONFIG_W2_128B_2048E, 90 AM_HAL_CACHECTRL_DESCR_1WAY_128B_4096E = CPU_CACHECFG_CONFIG_W1_128B_4096E 91 } am_hal_cachectrl_descr_e; 92 //! @} 93 94 //! Two Non-Cache Regions available. 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 //! Config struture for AM_HAL_CACHECTRL_CONTROL_NC_CFG 102 typedef struct 103 { 104 am_hal_cachectrl_nc_region_e eNCRegion; 105 bool bEnable; 106 uint32_t ui32StartAddr; 107 uint32_t ui32EndAddr; 108 } am_hal_cachectrl_nc_cfg_t; 109 110 //! Control operations. 111 typedef enum 112 { 113 AM_HAL_CACHECTRL_CONTROL_MRAM_CACHE_INVALIDATE = 1, 114 AM_HAL_CACHECTRL_CONTROL_STATISTICS_RESET, 115 AM_HAL_CACHECTRL_CONTROL_MONITOR_ENABLE, 116 AM_HAL_CACHECTRL_CONTROL_MONITOR_DISABLE, 117 AM_HAL_CACHECTRL_CONTROL_NC_CFG, 118 } am_hal_cachectrl_control_e; 119 120 //! Cache config values used for ui8Mode. 121 //! @note this enum ordering is critical, do not modify. 122 typedef enum 123 { 124 AM_HAL_CACHECTRL_CONFIG_MODE_DISABLE, 125 AM_HAL_CACHECTRL_CONFIG_MODE_INSTR, 126 AM_HAL_CACHECTRL_CONFIG_MODE_DATA, 127 AM_HAL_CACHECTRL_CONFIG_MODE_INSTR_DATA 128 } am_hal_cachectrl_config_mode_e; 129 130 // **************************************************************************** 131 // 132 //! Cache configuration structure 133 //! This structure can be used for am_hal_cachectrl_config(). 134 // 135 // **************************************************************************** 136 typedef struct 137 { 138 // 139 //! Set to one of: 140 //! AM_HAL_CACHECTRL_DESCR_1WAY_128B_512E 141 //! Direct mapped, 128-bit linesize, 512 entries (8KB cache) 142 //! AM_HAL_CACHECTRL_DESCR_2WAY_128B_512E 143 //! Two way set associative, 128-bit linesize, 512 entries (16KB cache) 144 //! AM_HAL_CACHECTRL_DESCR_1WAY_128B_1024E 145 //! Direct-mapped set associative, 128-bit linesize, 1024 entries (16KB cache) 146 //! AM_HAL_CACHECTRL_DESCR_1WAY_128B_2048E 147 //! Direct-mapped set associative, 128-bit linesize, 2048 entries (32KB cache) 148 //! AM_HAL_CACHECTRL_DESCR_2WAY_128B_2048E 149 //! Two way set associative, 128-bit linesize, 2048 entries (64KB cache) 150 //! AM_HAL_CACHECTRL_DESCR_1WAY_128B_4096E 151 //! Direct-mapped set associative, 128-bit linesize, 4096 entries (64KB cache) 152 // 153 am_hal_cachectrl_descr_e eDescript; 154 155 // 156 //! Set to one of the following: 157 //! AM_HAL_CACHECTRL_CONFIG_MODE_DISABLE - Disable both instr and data caching 158 //! AM_HAL_CACHECTRL_CONFIG_MODE_INSTR - Enable instr caching only 159 //! AM_HAL_CACHECTRL_CONFIG_MODE_DATA - Enable data caching only 160 //! AM_HAL_CACHECTRL_CONFIG_MODE_INSTR_DATA - Enable both instr and data caching 161 // 162 am_hal_cachectrl_config_mode_e eMode; 163 164 // 165 //! Set to true to enable the LRU (least recently used) replacement policy. 166 //! Set to false to enable the LRR (least recently replaced) replacement policy. 167 //! @note LRR minimizes writes to the TAG SRAM. 168 // 169 bool bLRU; 170 } am_hal_cachectrl_config_t; 171 172 extern const am_hal_cachectrl_config_t am_hal_cachectrl_defaults; 173 174 //! Number of DAXI buffers to use 175 typedef enum 176 { 177 AM_HAL_DAXI_CONFIG_NUMBUF_1 = CPU_DAXICFG_BUFFERENABLE_ONE, 178 AM_HAL_DAXI_CONFIG_NUMBUF_2 = CPU_DAXICFG_BUFFERENABLE_TWO, 179 AM_HAL_DAXI_CONFIG_NUMBUF_3 = CPU_DAXICFG_BUFFERENABLE_THREE, 180 AM_HAL_DAXI_CONFIG_NUMBUF_4 = CPU_DAXICFG_BUFFERENABLE_FOUR, 181 AM_HAL_DAXI_CONFIG_NUMBUF_8 = CPU_DAXICFG_BUFFERENABLE_EIGHT, 182 AM_HAL_DAXI_CONFIG_NUMBUF_16 = CPU_DAXICFG_BUFFERENABLE_SIXTEEN, 183 AM_HAL_DAXI_CONFIG_NUMBUF_31 = CPU_DAXICFG_BUFFERENABLE_THIRTYONE, 184 AM_HAL_DAXI_CONFIG_NUMBUF_32 = CPU_DAXICFG_BUFFERENABLE_THIRTYTWO 185 } am_hal_daxi_config_numbuf_e; 186 187 //! Aging Counter 188 typedef enum 189 { 190 AM_HAL_DAXI_CONFIG_AGING_1 = 0, 191 AM_HAL_DAXI_CONFIG_AGING_2 = 1, 192 AM_HAL_DAXI_CONFIG_AGING_4 = 2, 193 AM_HAL_DAXI_CONFIG_AGING_8 = 3, 194 AM_HAL_DAXI_CONFIG_AGING_16 = 4, 195 AM_HAL_DAXI_CONFIG_AGING_32 = 5, 196 AM_HAL_DAXI_CONFIG_AGING_64 = 6, 197 AM_HAL_DAXI_CONFIG_AGING_128 = 7, 198 AM_HAL_DAXI_CONFIG_AGING_256 = 8, 199 AM_HAL_DAXI_CONFIG_AGING_512 = 9, 200 AM_HAL_DAXI_CONFIG_AGING_1024 = 10, 201 AM_HAL_DAXI_CONFIG_AGING_2048 = 11, 202 AM_HAL_DAXI_CONFIG_AGING_4096 = 12, 203 AM_HAL_DAXI_CONFIG_AGING_8192 = 13, 204 AM_HAL_DAXI_CONFIG_AGING_16384 = 14, 205 AM_HAL_DAXI_CONFIG_AGING_32768 = 15, 206 AM_HAL_DAXI_CONFIG_AGING_65536 = 16 207 } am_hal_daxi_config_aging_e; 208 209 //! Number of Free DAXI buffers to keep 210 typedef enum 211 { 212 AM_HAL_DAXI_CONFIG_NUMFREEBUF_2 = 0, 213 AM_HAL_DAXI_CONFIG_NUMFREEBUF_3 = 1 214 } am_hal_daxi_config_numfreebuf_e; 215 216 //! Control operations. 217 typedef enum 218 { 219 AM_HAL_DAXI_CONTROL_INVALIDATE, 220 AM_HAL_DAXI_CONTROL_FLUSH, 221 AM_HAL_DAXI_CONTROL_DISABLE, 222 AM_HAL_DAXI_CONTROL_ENABLE 223 } am_hal_daxi_control_e; 224 225 // **************************************************************************** 226 // 227 //! DAXI configuration structure 228 //! This structure can be used for am_hal_daxi_config() and am_hal_daxi_config_get(). 229 // 230 // **************************************************************************** 231 typedef struct 232 { 233 bool bDaxiPassThrough; //! Puts DAXI in "pass through" mode (virtually disabling DAXI functions). 234 bool bAgingSEnabled; //! Enables aging based flushingfor shared entries. 235 am_hal_daxi_config_aging_e eAgingCounter; //! Specifies the relative counted cycles that DAXI buffers may remain unused 236 //! before being flushed. Counter is based on CPU clock cycles and buffers will 237 //! generally be flushed in 1-2 AGINGCOUNTER counted cycles.? 238 am_hal_daxi_config_numbuf_e eNumBuf; 239 am_hal_daxi_config_numfreebuf_e eNumFreeBuf; 240 } am_hal_daxi_config_t; 241 242 // **************************************************************************** 243 // 244 //! DAXI status structure 245 //! This structure can be used for am_hal_daxi_status_get(). 246 // 247 // **************************************************************************** 248 typedef struct 249 { 250 bool bDaxiReady; //! DAXI Ready Status (enabled and not processing a flush of WRITE or MODIFIED buffers). 251 bool bDaxiShared; //! DAXI status indicating at least one full buffer is shared. 252 } am_hal_daxi_status_t; 253 254 extern const am_hal_daxi_config_t am_hal_daxi_defaults; 255 256 // **************************************************************************** 257 // 258 // Function prototypes 259 // 260 // **************************************************************************** 261 // **************************************************************************** 262 // 263 //! @brief Configure the cache using the supplied settings. 264 //! 265 //! @param psConfig - pointer to a config structure containing cache settings. 266 //! 267 //! This function takes in a structure of cache settings and uses them to 268 //! configure the cache. This function will configures all of the settings in 269 //! the structure as well as recommended settings for various other cache 270 //! configuration parameters. 271 //! 272 //! This function does NOT enable the cache, which is handled in a separate 273 //! function. In fact, if the cache is enabled prior to calling this function, 274 //! it will return from the call disabled. 275 //! 276 //! For most applications, the default cache settings will be the most 277 //! efficient choice. To use the default cache settings with this function, use 278 //! the address of the global am_hal_cachectrl_defaults structure as the 279 //! psConfig argument. 280 //! 281 //! @return Status. 282 // 283 // **************************************************************************** 284 extern uint32_t am_hal_cachectrl_config(const am_hal_cachectrl_config_t *psConfig); 285 286 // **************************************************************************** 287 // 288 //! @brief Enable the cache for operation. 289 //! 290 //! @return Status. 291 // 292 // **************************************************************************** 293 extern uint32_t am_hal_cachectrl_enable(void); 294 295 // **************************************************************************** 296 // 297 //! @brief Disable the cache. 298 //! 299 //! Use this function to disable cache. Other configuration settings are not 300 //! not required. 301 //! 302 //! @return Status. 303 // 304 // **************************************************************************** 305 extern uint32_t am_hal_cachectrl_disable(void); 306 307 // **************************************************************************** 308 // 309 //! @brief Assert various specific controls on the cache. 310 //! 311 //! This function is used to apply various controls on the cache. 312 //! 313 //! @param eControl - One of the following: 314 //! @n AM_HAL_CACHECTRL_CONTROL_MRAM_CACHE_INVALIDATE 315 //! @n AM_HAL_CACHECTRL_CONTROL_STATISTICS_RESET 316 //! @n AM_HAL_CACHECTRL_CONTROL_MONITOR_ENABLE 317 //! @n AM_HAL_CACHECTRL_CONTROL_MONITOR_DISABLE 318 //! @n AM_HAL_CACHECTRL_CONTROL_NC_CFG 319 //! @param pArgs - Pointer to arguments for Control Switch Case 320 //! 321 //! @return status - generic or interface specific status. 322 // 323 // **************************************************************************** 324 extern uint32_t am_hal_cachectrl_control(am_hal_cachectrl_control_e eControl, 325 void *pArgs); 326 327 // **************************************************************************** 328 // 329 //! @brief Cache controller status function 330 //! 331 //! This function returns the current status of the cache. 332 //! 333 //! @param psStatus - ptr to a status structure to receive the current statuses. 334 //! 335 //! @return status - generic or interface specific status. 336 // 337 // **************************************************************************** 338 extern uint32_t am_hal_cachectrl_status_get(am_hal_cachectrl_status_t *psStatus); 339 340 // **************************************************************************** 341 // 342 //! @brief Configure the DAXI using the supplied settings. 343 //! 344 //! @param psConfig - pointer to a config structure containing DAXI settings. 345 //! 346 //! This function takes in a structure of DAXI settings and uses them to 347 //! configure the DAXI. If psConfig is NULL, DAXI is configured in PassThrough 348 //! 349 //! For most applications, the default DAXI settings will be the most 350 //! efficient choice. To use the default cache settings with this function, use 351 //! the address of the global am_hal_daxi_defaults structure as the 352 //! psConfig argument. 353 //! 354 //! @return Status. 355 // 356 // **************************************************************************** 357 extern uint32_t am_hal_daxi_config(const am_hal_daxi_config_t *psConfig); 358 359 // **************************************************************************** 360 // 361 //! @brief Assert various DAXI specific controls. 362 //! 363 //! This function is used to apply various controls on the DAXI. 364 //! 365 //! @param eControl - One of the following: 366 //! @n AM_HAL_DAXI_CONTROL_INVALIDATE 367 //! @n AM_HAL_DAXI_CONTROL_FLUSH 368 //! @param pArgs - Pointer to arguments for Control Switch Case 369 //! 370 //! @return status - generic or interface specific status. 371 // 372 // **************************************************************************** 373 extern uint32_t am_hal_daxi_control(am_hal_daxi_control_e eControl, void *pArgs); 374 375 // **************************************************************************** 376 // 377 //! @brief Get Current DAXI settings 378 //! 379 //! This function returns the current settings for DAXI. 380 //! 381 //! @param psConfig - ptr to a structure to receive the current values. 382 //! 383 //! @return status - generic or interface specific status. 384 // 385 // **************************************************************************** 386 extern uint32_t am_hal_daxi_config_get(am_hal_daxi_config_t *psConfig); 387 388 // **************************************************************************** 389 // 390 //! @brief DAXI Flush is Complete 391 //! 392 //! This function returns the current status for DAXI Flush in Progress. 393 //! 394 //! @param pStatus - ptr to a am_hal_daxi_status_t to receive the DAXI status. 395 //! 396 //! @return status - generic or interface specific status. 397 // 398 // **************************************************************************** 399 extern uint32_t am_hal_daxi_status_get(am_hal_daxi_status_t *pStatus); 400 401 #ifdef __cplusplus 402 } 403 #endif 404 405 #endif // AM_HAL_CACHECTRL_H 406 407 //***************************************************************************** 408 // 409 // End Doxygen group. 410 //! @} 411 // 412 //***************************************************************************** 413 414
