1 //***************************************************************************** 2 // 3 //! @file am_hal_cmdq.h 4 //! 5 //! @brief Functions for Support Command Queue Operations. 6 //! 7 //! @addtogroup cmdq3p CMDQ - Command Queue Functions 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 48 #ifndef AM_HAL_CMDQ_H 49 #define AM_HAL_CMDQ_H 50 51 // 52 //! Identification for underlying hardware interface 53 // 54 typedef enum 55 { 56 AM_HAL_CMDQ_IF_IOM0, 57 AM_HAL_CMDQ_IF_IOM1, 58 AM_HAL_CMDQ_IF_IOM2, 59 AM_HAL_CMDQ_IF_IOM3, 60 AM_HAL_CMDQ_IF_IOM4, 61 AM_HAL_CMDQ_IF_IOM5, 62 AM_HAL_CMDQ_IF_MSPI0, 63 AM_HAL_CMDQ_IF_MSPI1, 64 AM_HAL_CMDQ_IF_MSPI2, 65 AM_HAL_CMDQ_IF_BLEIF, 66 AM_HAL_CMDQ_IF_MAX, 67 } am_hal_cmdq_if_e; 68 69 typedef enum 70 { 71 AM_HAL_CMDQ_PRIO_LOW, 72 AM_HAL_CMDQ_PRIO_HI, 73 } am_hal_cmdq_priority_e; 74 75 typedef struct 76 { 77 uint32_t cmdQSize; 78 uint32_t *pCmdQBuf; 79 am_hal_cmdq_priority_e priority; 80 } am_hal_cmdq_cfg_t; 81 82 typedef struct 83 { 84 uint32_t address; 85 uint32_t value; 86 } am_hal_cmdq_entry_t; 87 88 typedef struct 89 { 90 uint32_t lastIdxProcessed; 91 uint32_t lastIdxPosted; 92 uint32_t lastIdxAllocated; 93 bool bTIP; 94 bool bPaused; 95 bool bErr; 96 } am_hal_cmdq_status_t; 97 98 #ifdef __cplusplus 99 extern "C" 100 { 101 #endif 102 103 //***************************************************************************** 104 // 105 //! @brief Initialize a Command Queue 106 //! 107 //! @details Initializes the command queue data structure for the given interface 108 //! 109 //! @param hwIf - identifies the underlying hardware interface 110 //! @param pCfg - pointer to config params 111 //! @param ppHandle - Return Parameter - handle for the command queue 112 //! 113 //! @return Returns 0 on success 114 // 115 //***************************************************************************** 116 uint32_t am_hal_cmdq_init(am_hal_cmdq_if_e hwIf, am_hal_cmdq_cfg_t *pCfg, void **ppHandle); 117 118 119 //***************************************************************************** 120 // 121 //! @brief Enable a Command Queue for the given interface 122 //! 123 //! @param pHandle - handle for the command queue 124 //! 125 //! @return Returns 0 on success 126 // 127 //***************************************************************************** 128 uint32_t am_hal_cmdq_enable(void *pHandle); 129 130 //***************************************************************************** 131 // 132 //! @brief Disable a Command Queue 133 //! 134 //! @details Disables the command queue for the given interface 135 //! 136 //! @param pHandle handle for the command queue 137 //! 138 //! @return Returns 0 on success 139 // 140 //***************************************************************************** 141 uint32_t am_hal_cmdq_disable(void *pHandle); 142 143 //***************************************************************************** 144 // 145 //! @brief Allocate a block of commands for posting to a command queue 146 //! 147 //! @details Allocates a contiguous block of command queue entries from the available 148 //! space in command queue 149 //! 150 //! @param pHandle handle for the command queue 151 //! @param numCmd Size of the command block (each block being 8 bytes) 152 //! @param ppBlock - Return parameter - Pointer to contiguous block of commands, 153 //! which can be posted 154 //! @param pIdx - Return parameter - monotonically increasing transaction index 155 //! 156 //! @note This function will take care of determining that enough space is available 157 //! to create the desired block. It also takes care of necessary wrap-around 158 //! 159 //! @return Returns 0 on success 160 // 161 //***************************************************************************** 162 uint32_t am_hal_cmdq_alloc_block(void *pHandle, uint32_t numCmd, am_hal_cmdq_entry_t **ppBlock, uint32_t *pIdx); 163 164 //***************************************************************************** 165 // 166 //! @brief Release a block of commands previously allocated 167 //! 168 //! @details Releases the contiguous block of command queue entries previously allocated 169 //! without posting 170 //! 171 //! @param pHandle handle for the command queue 172 //! 173 //! @note This function will internally handles the curIdx/endIdx manipulation. 174 //! It also takes care of necessary wrap-around 175 //! 176 //! @return Returns 0 on success 177 // 178 //***************************************************************************** 179 uint32_t am_hal_cmdq_release_block(void *pHandle); 180 181 //***************************************************************************** 182 // 183 //! @brief Post the last block allocated 184 //! 185 //! @details Post the contiguous block of command queue entries previously allocated 186 //! 187 //! @param pHandle handle for the command queue 188 //! @param bInt Whether the UPD interrupt is desired once the block is processed 189 //! 190 //! @return Returns 0 on success 191 // 192 //***************************************************************************** 193 uint32_t am_hal_cmdq_post_block(void *pHandle, bool bInt); 194 195 //***************************************************************************** 196 // 197 //! @brief Get Command Queue status 198 //! 199 //! @details Get the current state of the Command queue 200 //! 201 //! @param pHandle handle for the command queue 202 //! @param pStatus Return Parameter - status information 203 //! 204 //! @return Returns 0 on success 205 // 206 //***************************************************************************** 207 uint32_t am_hal_cmdq_get_status(void *pHandle, am_hal_cmdq_status_t *pStatus); 208 209 //***************************************************************************** 210 // 211 //! @brief Terminate a Command Queue 212 //! 213 //! @details Terminates the command queue data structure 214 //! 215 //! @param pHandle - handle for the command queue 216 //! @param bForce - force queue termination 217 //! 218 //! @return Returns 0 on success 219 // 220 //***************************************************************************** 221 uint32_t am_hal_cmdq_term(void *pHandle, bool bForce); 222 223 //***************************************************************************** 224 // 225 //! @brief Clear the CQ error and resume with the next transaction. 226 //! 227 //! @param pHandle handle for the command queue 228 //! 229 //! @return Returns 0 on success 230 // 231 //***************************************************************************** 232 uint32_t am_hal_cmdq_error_resume(void *pHandle); 233 234 //***************************************************************************** 235 // 236 //! @brief Pause the CQ after finishing the current transaction. 237 //! 238 //! The CQ is in paused state after this function returns, 239 //! at the beginning of next transaction 240 //! 241 //! @param pHandle - Handle for the command queue 242 //! @param pSETCLRAddr - Points to the SETCLR register for the module 243 //! @param ui32CQPauseSETCLR - Value to be written to Pause the CQ 244 //! @param ui32CQUnpauseSETCLR - Value to be written to unpause the CQ 245 //! @param ui32usMaxDelay - Max time to wait (in uS) 246 //! 247 //! @return Returns 0 on success 248 // 249 //***************************************************************************** 250 uint32_t am_hal_cmdq_pause(void *pHandle, uint32_t *pSETCLRAddr, 251 uint32_t ui32CQPauseSETCLR, 252 uint32_t ui32CQUnpauseSETCLR, uint32_t ui32usMaxDelay); 253 254 //***************************************************************************** 255 // 256 //! @brief Reset the Command Queue 257 //! 258 //! Reset the Command Queue & associated data structures\n 259 //! This will force the CQ reset\n 260 //! This also disables the CQ 261 //! 262 //! @note Caller needs to ensure CQ is in steady state before this is done\n 263 //! 264 //! @param pHandle handle for the command queue 265 //! 266 //! @return Returns 0 on success 267 // 268 //***************************************************************************** 269 uint32_t am_hal_cmdq_reset(void *pHandle); 270 271 //***************************************************************************** 272 // 273 //! @brief Post the last block allocated with the additional wrap to start 274 //! 275 //! Post the contiguous block of command queue entries previously allocated 276 //! with the additional wrap to start 277 //! 278 //! @param pHandle handle for the command queue 279 //! @param bInt Whether the UPD interrupt is desired once the block is processed 280 //! 281 //! @return Returns 0 on success 282 // 283 //***************************************************************************** 284 uint32_t am_hal_cmdq_post_loop_block(void *pHandle, bool bInt); 285 286 #ifdef __cplusplus 287 } 288 #endif 289 290 #endif // AM_HAL_CMDQ_H 291 //***************************************************************************** 292 // 293 // End Doxygen group. 294 //! @} 295 // 296 //***************************************************************************** 297
