1 //***************************************************************************** 2 // 3 //! @file am_hal_sdhc.h 4 //! 5 //! @brief Functions for interfacing with the SDHC. 6 //! 7 //! @addtogroup sdhc_4p SDHC host controller 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 stable-7da8bae71f of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 #ifndef AM_HAL_SDHC_H 48 #define AM_HAL_SDHC_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 //***************************************************************************** 56 // 57 //! CMSIS-Style macro for handling a variable SDHC module number. 58 // 59 //***************************************************************************** 60 #define SDHCn(n) ((SDIO_Type*)(SDIO_BASE + n)) 61 62 //***************************************************************************** 63 // 64 //! @brief SDHC initialization function 65 //! 66 //! @param ui32Module - module instance. 67 //! @param ppHandle - returns the handle for the module instance. 68 //! 69 //! This function accepts a module instance, allocates the interface and then 70 //! returns a handle to be used by the remaining interface functions. 71 //! 72 //! @return status - generic or interface specific status. 73 // 74 //***************************************************************************** 75 extern uint32_t am_hal_sdhc_initialize(uint32_t ui32Module, 76 void **ppHandle); 77 78 //***************************************************************************** 79 // 80 //! @brief SDHC deinitialization function 81 //! 82 //! @param pHandle - the handle for the module instance. 83 //! 84 //! This function accepts a handle to an instance and de-initializes the 85 //! interface. 86 //! 87 //! @return status - generic or interface specific status. 88 // 89 //***************************************************************************** 90 extern uint32_t am_hal_sdhc_deinitialize(void *pHandle); 91 92 //***************************************************************************** 93 // 94 //! @brief SDHC power control function 95 //! 96 //! @param pHandle - handle for the interface. 97 //! @param ePowerState - the desired power state to move the peripheral to. 98 //! @param bRetainState - flag (if true) to save/restore peripheral state upon 99 //! power state change. 100 //! 101 //! This function updates the peripheral to a given power state. 102 //! 103 //! @return status - generic or interface specific status. 104 // 105 //***************************************************************************** 106 extern uint32_t am_hal_sdhc_power_control(void *pHandle, 107 am_hal_sysctrl_power_state_e ePowerState, 108 bool bRetainState); 109 110 //***************************************************************************** 111 // 112 //! @brief SDHC setup card host function 113 //! 114 //! @param pHandle - handle for the interface. 115 //! @param pHost - pointer to the card host data structure. 116 //! 117 //! This function updates pHost related settings by checking the capabilites of underlying 118 //! SDHC host controller. These settings are important for validate the arguments to the card 119 //! block read, write, erase, speed, bus width. 120 //! 121 //! @return status - generic or interface specific status. 122 // 123 //***************************************************************************** 124 extern uint32_t am_hal_sdhc_setup_host(void *pHandle, am_hal_card_host_t *pHost); 125 126 //***************************************************************************** 127 // 128 //! @brief SDHC detects the card function 129 //! 130 //! @param pHandle - handle for the interface. 131 //! 132 //! This function detects the present of card in the slot. 133 //! 134 //! @return status - boolean. 135 // 136 //***************************************************************************** 137 extern bool am_hal_sdhc_get_cd(void *pHandle); 138 139 //***************************************************************************** 140 // 141 //! @brief SDHC detects the card write protection 142 //! 143 //! @param pHandle - handle for the interface. 144 //! 145 //! This function detects the card write protection in the slot. 146 //! 147 //! @return status - boolean. 148 // 149 //***************************************************************************** 150 extern bool am_hal_sdhc_get_wr_protect(void *pHandle); 151 152 //***************************************************************************** 153 // 154 //! @brief SDHC sets the SDIO bus IO volage 155 //! 156 //! @param pHandle - handle for the interface. 157 //! @param eBusVoltage - SDIO Bus Voltage 158 //! AM_HAL_HOST_BUS_VOLTAGE_1_8, 159 //! AM_HAL_HOST_BUS_VOLTAGE_3_0, 160 //! AM_HAL_HOST_BUS_VOLTAGE_3_3, 161 //! 162 //! This function sets the bus voltage needed to communiate with the card. 163 //! 164 //! @return status - generic or interface specific status. 165 // 166 //***************************************************************************** 167 extern uint32_t am_hal_sdhc_set_bus_voltage(void *pHandle, am_hal_host_bus_voltage_e eBusVoltage); 168 169 //***************************************************************************** 170 // 171 //! @brief SDHC sets the SDIO bus width 172 //! 173 //! @param pHandle - handle for the interface. 174 //! @param eBusWidth - SDIO Bus Width 175 //! AM_HAL_HOST_BUS_WIDTH_1 = 1, 176 //! AM_HAL_HOST_BUS_WIDTH_4 = 4, 177 //! AM_HAL_HOST_BUS_WIDTH_8 = 8, 178 //! 179 //! This function sets the bus width needed to communiate with the card. 180 //! 181 //! @return status - generic or interface specific status. 182 // 183 //***************************************************************************** 184 extern uint32_t am_hal_sdhc_set_bus_width(void *pHandle, am_hal_host_bus_width_e eBusWidth); 185 186 //***************************************************************************** 187 // 188 //! @brief SDHC sets the SDIO bus clock speed 189 //! 190 //! @param pHandle - handle for the interface. 191 //! @param ui32Clock - Clock Speed 192 //! 193 //! This function sets the bus clock speed needed to communiate with the card. 194 //! 195 //! @return status - generic or interface specific status. 196 // 197 //***************************************************************************** 198 extern uint32_t am_hal_sdhc_set_bus_clock(void *pHandle, uint32_t ui32Clock); 199 200 //***************************************************************************** 201 // 202 //! @brief SDHC sets the SDIO UHS Mode 203 //! 204 //! @param pHandle - handle for the interface. 205 //! @param eUHSMode - UHS Mode 206 //! AM_HAL_HOST_UHS_NONE = 0, 207 //! AM_HAL_HOST_UHS_SDR12 = 0, 208 //! AM_HAL_HOST_UHS_SDR25 = 1, 209 //! AM_HAL_HOST_UHS_SDR50 = 2, 210 //! AM_HAL_HOST_UHS_SDR104 = 3, 211 //! AM_HAL_HOST_UHS_DDR50 = 4, 212 //! 213 //! This function sets the bus clock speed needed to communiate with the card. 214 //! 215 //! @return status - generic or interface specific status. 216 // 217 //***************************************************************************** 218 extern uint32_t am_hal_sdhc_set_uhs_mode(void *pHandle, am_hal_host_uhs_mode_e eUHSMode); 219 220 //***************************************************************************** 221 // 222 //! @brief SDHC checks the SDIO bus busy DAT0 line 223 //! 224 //! @param pHandle - handle for the interface. 225 //! @param ui32TimeoutMS - the timeout of checking if this busy line is released ( 226 //! changed from low voltage to high voltage). 227 //! 228 //! This function checks if DAT0 line is busy or not. 229 //! 230 //! @return status - generic or interface specific status. 231 // 232 //***************************************************************************** 233 extern uint32_t am_hal_sdhc_card_busy(void *pHandle, uint32_t ui32TimeoutMS); 234 235 //***************************************************************************** 236 // 237 //! @brief SDHC Set TxRx Delays 238 //! 239 //! @param pHandle - handle for the interface. 240 //! @param ui8TxRxDelays - delay values to set 241 //! 242 //! @return status - generic or interface specific status. 243 // 244 //***************************************************************************** 245 extern void am_hal_sdhc_set_txrx_delay(void *pHandle, uint8_t ui8TxRxDelays[2]); 246 247 //***************************************************************************** 248 // 249 //! @brief SDHC enable function 250 //! 251 //! @param pHandle - the handle for the module instance. 252 //! 253 //! This function accepts a handle to an instance and enables the interface. 254 //! 255 //! @return status - generic or interface specific status. 256 // 257 //***************************************************************************** 258 extern uint32_t am_hal_sdhc_enable(void *pHandle); 259 260 //***************************************************************************** 261 // 262 //! @brief SDHC disable function 263 //! 264 //! @param pHandle - the handle for the module instance. 265 //! 266 //! This function accepts a handle to an instance and disables the interface. 267 //! 268 //! @return status - generic or interface specific status. 269 // 270 //***************************************************************************** 271 extern uint32_t am_hal_sdhc_disable(void *pHandle); 272 273 //***************************************************************************** 274 // 275 //! @brief SDHC send command function 276 //! 277 //! @param pHandle - handle for the interface. 278 //! @param pCmd - pointer to command data structure which including the command index, 279 //! argument, response type, command response and command error code. 280 //! @param pCmdData - pointer to command related data structure, like command direction, 281 //! command transfer mode, block size, block count, data buffer, etc. 282 //! 283 //! This function sends a command to SD/MMC/eMMC/SDIO card and gets the response. if this command 284 //! is using synchronous transfer mode, it will be blocked until the data in the buffer has been 285 //! transmited or received. if this command is using asynchronous transfer mode, it will return immediately 286 //! after sending the command, data transfer completion done event will be notified by registered callback 287 //! function in the ISR. 288 //! 289 //! @return status - generic or interface specific status. 290 // 291 //***************************************************************************** 292 extern uint32_t am_hal_sdhc_execute_cmd(void *pHandle, am_hal_card_cmd_t *pCmd, am_hal_card_cmd_data_t *pCmdData); 293 294 //***************************************************************************** 295 // 296 //! @brief SDHC enable interrupts function 297 //! 298 //! @param pHandle - handle for the interface. 299 //! @param ui32IntMask - SDHC interrupt mask. 300 //! 301 //! This function enables the normal or error specific indicated interrupts. 302 //! 303 //! @return status - generic or interface specific status. 304 // 305 //***************************************************************************** 306 extern uint32_t am_hal_sdhc_intr_status_enable(void *pHandle, 307 uint32_t ui32IntMask); 308 309 //***************************************************************************** 310 // 311 //! @brief SDHC disable interrupts function 312 //! 313 //! @param pHandle - handle for the interface. 314 //! @param ui32IntMask - SDHC interrupt mask. 315 //! 316 //! This function disables the normal or error specific indicated interrupts. 317 //! 318 //! @return status - generic or interface specific status. 319 // 320 //***************************************************************************** 321 extern uint32_t am_hal_sdhc_intr_status_disable(void *pHandle, 322 uint32_t ui32IntMask); 323 324 //***************************************************************************** 325 // 326 //! @brief SDHC interrupt status function 327 //! 328 //! @param pHandle - handle for the interface. 329 //! @param pui32Status - returns the interrupt status value. 330 //! @param bEnabledOnly - TRUE: only report interrupt status for enalbed ints. 331 //! FALSE: report all interrupt status values. 332 //! 333 //! This function returns the normal or error specific indicated interrupt status. 334 //! 335 //! @return status - interrupt status. 336 // 337 //***************************************************************************** 338 extern uint32_t am_hal_sdhc_intr_status_get(void *pHandle, 339 uint32_t *pui32Status, 340 bool bEnabledOnly); 341 342 //***************************************************************************** 343 // 344 //! @brief SDHC interrupt clear 345 //! 346 //! @param pHandle - handle for the interface. 347 //! @param ui32IntMask - uint32_t for interrupts to clear 348 //! 349 //! This function clears the normal or error interrupts for the given peripheral. 350 //! 351 //! @return status - generic or interface specific status. 352 // 353 //***************************************************************************** 354 extern uint32_t am_hal_sdhc_intr_status_clear(void *pHandle, 355 uint32_t ui32IntMask); 356 357 //***************************************************************************** 358 // 359 //! @brief SDHC interrupt clear 360 //! 361 //! @param pHandle - handle for the interface. 362 //! @param ui32IntMask - uint32_t for interrupts to enable 363 //! 364 //! This function enables the normal or error interrupts to generate the SDIO IRQ. 365 //! 366 //! @return status - generic or interface specific status. 367 // 368 //***************************************************************************** 369 extern uint32_t am_hal_sdhc_intr_signal_enable(void *pHandle, uint32_t ui32IntMask); 370 371 //***************************************************************************** 372 // 373 //! @brief SDHC interrupt clear 374 //! 375 //! @param pHandle - handle for the interface. 376 //! @param ui32IntMask - uint32_t for interrupts to clear 377 //! 378 //! This function disables the normal or error interrupts to generate the SDIO IRQ. 379 //! 380 //! @return status - generic or interface specific status. 381 // 382 //***************************************************************************** 383 384 extern uint32_t am_hal_sdhc_intr_signal_disable(void *pHandle, uint32_t ui32IntMask); 385 386 //***************************************************************************** 387 // 388 //! @brief SDHC interrupt service routine 389 //! 390 //! @param pHandle - handle for the interface. 391 //! @param ui32IntStatus - interrupt status. 392 //! 393 //! This function is designed to be called from within the user defined ISR 394 //! in order to service the non-blocking, PIO, SDMA or ADMA processing for a given 395 //! module instance. 396 //! 397 //! @return status - generic or interface specific status. 398 // 399 //***************************************************************************** 400 extern uint32_t am_hal_sdhc_interrupt_service(void *pHandle, 401 uint32_t ui32IntStatus); 402 403 #ifdef __cplusplus 404 } 405 #endif 406 407 #endif // AM_HAL_MSPI_H 408 409 //***************************************************************************** 410 // 411 // End Doxygen group. 412 //! @} 413 // 414 //***************************************************************************** 415 416
