1 /***************************************************************************//** 2 * \file cyhal_sdio.h 3 * 4 * \brief 5 * Provides a high level interface for interacting with the Infineon SDIO interface. 6 * This interface abstracts out the chip specific details. If any chip specific 7 * functionality is necessary, or performance is critical the low level functions 8 * can be used directly. 9 * 10 ******************************************************************************** 11 * \copyright 12 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 13 * an affiliate of Cypress Semiconductor Corporation 14 * 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); 18 * you may not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, 25 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 *******************************************************************************/ 29 30 /** 31 * \addtogroup group_hal_sdio SDIO (Secure Digital Input Output) 32 * \ingroup group_hal 33 * \{ 34 * High level interface to the Secure Digital Input Output (SDIO). 35 * 36 * The SDIO protocol is an extension of the SD interface for general I/O functions. 37 * Refer to the SD Specifications Part 1 SDIO Specifications Version 4.10 for more 38 * information on the SDIO protocol and specifications. 39 * 40 * The host functionality of this driver allows commands to be sent over the SDIO bus; 41 * the supported commands can be found in cyhal_sdio_host_command_t. Bulk data transfer 42 * is supported via cyhal_sdio_bulk_transfer(). 43 * 44 * The device functionality of this driver allows configuring the SDIO device for 45 * receiving commands from the host. Data can be sent and received from/to application 46 * buffers. 47 * 48 * \section subsection_sdio_features Features 49 * * Supports 4-bit interface 50 * * Supports Ultra High Speed (UHS-I) mode 51 * * Supports Default Speed (DS), High Speed (HS), SDR12, SDR25 and SDR50 speed modes 52 * * Supports SDIO card interrupts in both 1-bit SD and 4-bit SD modes 53 * * Supports Standard capacity (SDSC), High capacity (SDHC) and Extended capacity (SDXC) memory 54 * 55 * \section subsection_sdio_quickstart Quick Start 56 * 57 * \ref cyhal_sdio_init initializes the SDIO peripheral and passes a pointer to the SDIO block through the **obj** object of type \ref cyhal_sdio_t. 58 * 59 * \section subsection_sdio_code_snippets Code Snippets 60 * 61 * \subsection subsection_sdio_host_code_snippets Host Code Snippets 62 * 63 * \subsubsection subsection_sdio_host_use_case_1 Snippet1: Simple SDIO Host Initialization example 64 * The following snippet shows how to initialize the SDIO host interface with a pre-defined configuration 65 * 66 * \snippet hal_sdio.c snippet_cyhal_sdio_host_simple_init 67 * 68 * \subsubsection subsection_sdio_host_use_case_2 Snippet2: Configure Host Interrupt 69 * The following snippet shows how to configure an interrupt to handle host specific events. Refer \ref cyhal_sdio_event_t for different types of events. 70 * 71 * \snippet hal_sdio.c snippet_cyhal_sdio_host_interrupt_callback 72 * 73 * \subsubsection subsection_sdio_host_use_case_3 Snippet3: Sending Host Commands 74 * The following snippet shows how to send a particular command. Some steps of the card initialization have been provided for reference. Refer to cyhal_sdio_host_command_t for different commands. 75 * 76 * \snippet hal_sdio.c snippet_cyhal_sdio_host_send_command 77 * 78 * \subsubsection subsection_sdio_host_use_case_4 Snippet4: Host Bulk Data Transfer 79 * The following snippet shows how to start a bulk data transfer. 80 * 81 * \snippet hal_sdio.c snippet_cyhal_sdio_host_bulk_transfer 82 * 83 * \subsubsection subsection_sdio_host_use_case_5 Snippet5: Host Async Data Transfer 84 * 85 * The following snippet shows how to start an async data transfer. 86 * \snippet hal_sdio.c snippet_cyhal_sdio_host_async_transfer 87 * 88 * \subsection subsection_sdio_dev_code_snippets Device Code Snippets 89 * 90 * \subsubsection subsection_sdio_dev_use_case_1 Snippet1: Simple SDIO Device Initialization example 91 * The following snippet shows how to initialize the SDIO device interface with a pre-defined configuration 92 * 93 * \snippet hal_sdio.c snippet_cyhal_sdio_dev_simple_init 94 * 95 * \subsubsection subsection_sdio_dev_use_case_2 Snippet2: Configure Device Interrupt 96 * The following snippet shows how to configure an interrupt to handle device specific events. Refer \ref cyhal_sdio_event_t for different types of events. 97 * 98 * \snippet hal_sdio.c snippet_cyhal_sdio_dev_interrupt_callback 99 * 100 * \subsubsection subsection_sdio_dev_use_case_3 Snippet3: Device Async Read 101 * The following snippet shows how to start an async read. 102 * 103 * \snippet hal_sdio.c snippet_cyhal_sdio_dev_async_read 104 * 105 * \subsubsection subsection_sdio_dev_use_case_4 Snippet4: Device Mailbox Write 106 * The following snippet shows how to write to the mailbox. 107 * 108 * \snippet hal_sdio.c snippet_cyhal_sdio_dev_write_mailbox 109 * 110 */ 111 112 #pragma once 113 114 #include <stdint.h> 115 #include <stdbool.h> 116 #include "cy_result.h" 117 #include "cyhal_hw_types.h" 118 119 #if defined(__cplusplus) 120 extern "C" { 121 #endif 122 123 /******************************************************************************* 124 * Defines 125 *******************************************************************************/ 126 127 /* HAL return value defines */ 128 129 /** \addtogroup group_hal_results_sdio SDIO HAL Results 130 * SDIO specific return codes 131 * \ingroup group_hal_results 132 * \{ *//** 133 */ 134 135 /** Incorrect parameter value define */ 136 #define CYHAL_SDIO_RSLT_ERR_BAD_PARAM \ 137 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 0)) 138 /** Define to indicate canceled operation */ 139 #define CYHAL_SDIO_RSLT_CANCELED \ 140 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 1)) 141 /** Transfers are not allowed after the SDIO block has allowed power mode transition. */ 142 #define CYHAL_SDIO_RSLT_ERR_PM_PENDING \ 143 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 2)) 144 /** Requested feature is not supported on this hardware. */ 145 #define CYHAL_SDIO_RSLT_ERR_UNSUPPORTED \ 146 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 3)) 147 /** Failure in command send. */ 148 #define CYHAL_SDIO_RSLT_ERR_COMMAND_SEND \ 149 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 4)) 150 /** SDIO Configuration error. */ 151 #define CYHAL_SDIO_RSLT_ERR_CONFIG \ 152 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 5)) 153 /** Another SDIO IO volt select pin already configured. */ 154 #define CYHAL_SDIO_RSLT_ERR_IO_VOLT_SEL_PIN_CONFIGURED \ 155 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 6)) 156 /** Error occured during I/O voltage switch sequence. */ 157 #define CYHAL_SDIO_RSLT_ERR_IO_VOLT_SWITCH_SEQ \ 158 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 7)) 159 /** Clock initialization error define */ 160 #define CYHAL_SDIO_RSLT_ERR_CLOCK \ 161 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 8)) 162 163 /** Failed to write SDIO Device data */ 164 #define CYHAL_SDIO_DEV_RSLT_WRITE_ERROR \ 165 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 1 << 4)) 166 /** Failed to read SDIO Device data */ 167 #define CYHAL_SDIO_DEV_RSLT_READ_ERROR \ 168 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 2 << 4)) 169 /** Failed to write SDIO Device mailbox data */ 170 #define CYHAL_SDIO_DEV_RSLT_MAILBOX_WRITE_ERROR \ 171 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 3 << 4)) 172 /** Failed to read SDIO Device mailbox data */ 173 #define CYHAL_SDIO_DEV_RSLT_MAILBOX_READ_ERROR \ 174 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_SDIO, 4 << 4)) 175 176 /** 177 * \} 178 */ 179 180 181 /******************************************************************************* 182 * Common Enumerations 183 *******************************************************************************/ 184 185 /** Types of events that could be asserted by SDIO */ 186 typedef enum { 187 #if (CYHAL_DRIVER_AVAILABLE_SDIO_HOST) 188 /* SDIO host events */ 189 CYHAL_SDIO_CMD_COMPLETE = 0x00001, //!< Command Complete 190 CYHAL_SDIO_XFER_COMPLETE = 0x00002, //!< Host read/write transfer is complete 191 CYHAL_SDIO_BGAP_EVENT = 0x00004, //!< Set when both read/write transaction is stopped 192 CYHAL_SDIO_DMA_INTERRUPT = 0x00008, //!< Host controller detects an SDMA Buffer Boundary during transfer 193 CYHAL_SDIO_BUF_WR_READY = 0x00010, //!< Set if the Buffer Write Enable changes from 0 to 1 194 CYHAL_SDIO_BUF_RD_READY = 0x00020, //!< Set if the Buffer Read Enable changes from 0 to 1 195 CYHAL_SDIO_CARD_INSERTION = 0x00040, //!< Set if the Card Inserted in the Present State 196 CYHAL_SDIO_CARD_REMOVAL = 0x00080, //!< Set if the Card Inserted in the Present State 197 CYHAL_SDIO_CARD_INTERRUPT = 0x00100, //!< Synchronized value of the DAT[1] interrupt input for SD mode 198 CYHAL_SDIO_INT_A = 0x00200, //!< Reserved: set to 0 199 CYHAL_SDIO_INT_B = 0x00400, //!< Reserved: set to 0 200 CYHAL_SDIO_INT_C = 0x00800, //!< Reserved: set to 0 201 CYHAL_SDIO_RE_TUNE_EVENT = 0x01000, //!< Reserved: set to 0 202 CYHAL_SDIO_FX_EVENT = 0x02000, //!< Set when R[14] of response register is set to 1 203 CYHAL_SDIO_CQE_EVENT = 0x04000, //!< Set if Command Queuing/Crypto event has occurred 204 CYHAL_SDIO_ERR_INTERRUPT = 0x08000, //!< Set if any of the bits in the Error Interrupt Status register are set 205 CYHAL_SDIO_GOING_DOWN = 0x10000, //!< The interface is going away (eg: powering down for some period of time) 206 CYHAL_SDIO_COMING_UP = 0x20000, //!< The interface is back up (eg: came back from a low power state) 207 #endif 208 #if (CYHAL_DRIVER_AVAILABLE_SDIO_DEV) 209 /* SDIO device events */ 210 CYHAL_SDIO_DEV_HOST_INFO = 0x80001, /**< Info from host (e.g. mailbox) was received */ 211 CYHAL_SDIO_DEV_READ_COMPLETE = 0x80002, /**< Device read operation is complete */ 212 CYHAL_SDIO_DEV_WRITE_COMPLETE = 0x80004, /**< Device write operation is complete */ 213 CYHAL_SDIO_DEV_READ_ERROR = 0x80008, /**< Device error while performing read */ 214 CYHAL_SDIO_DEV_WRITE_ERROR = 0x80010, /**< Device error while performing write */ 215 #endif 216 CYHAL_SDIO_ALL_INTERRUPTS = 0x0E1FF, //!< Used to enable/disable all interrupts events 217 } cyhal_sdio_event_t; 218 219 220 /******************************************************************************* 221 * Enumerations 222 *******************************************************************************/ 223 224 #if (CYHAL_DRIVER_AVAILABLE_SDIO_HOST) 225 226 /** Commands that can be issued */ 227 typedef enum 228 { 229 CYHAL_SDIO_CMD_GO_IDLE_STATE = 0, //!< Go to idle state 230 CYHAL_SDIO_CMD_SEND_RELATIVE_ADDR = 3, //!< Send a relative address 231 CYHAL_SDIO_CMD_IO_SEND_OP_COND = 5, //!< Send an OP IO 232 CYHAL_SDIO_CMD_SELECT_CARD = 7, //!< Send a card select 233 CYHAL_SDIO_CMD_VOLTAGE_SWITCH = 11, //!< Voltage switch 234 CYHAL_SDIO_CMD_GO_INACTIVE_STATE = 15, //!< Go to inactive state 235 CYHAL_SDIO_CMD_IO_RW_DIRECT = 52, //!< Perform a direct read/write 236 CYHAL_SDIO_CMD_IO_RW_EXTENDED = 53, //!< Perform an extended read/write 237 } cyhal_sdio_host_command_t; 238 239 /** Types of transfer that can be performed */ 240 typedef enum 241 { 242 CYHAL_SDIO_XFER_TYPE_READ, //!< Read from the card 243 CYHAL_SDIO_XFER_TYPE_WRITE //!< Write to the card 244 } cyhal_sdio_host_transfer_type_t; 245 246 /** I/O voltage levels */ 247 typedef enum 248 { 249 CYHAL_SDIO_IO_VOLTAGE_3_3V = 0U, //!< I/O voltage is 3.3V. 250 CYHAL_SDIO_IO_VOLTAGE_1_8V = 1U //!< I/O voltage is 1.8V. 251 } cyhal_sdio_host_io_voltage_t; 252 253 /** SDIO I/O voltage select principle */ 254 typedef enum 255 { 256 CYHAL_SDIO_IO_VOLT_ACTION_SWITCH_SEQ_ONLY = 1U, //!< HAL driver performs switching sequence (if voltage is being switched to 1.8V) and changes io_volt_sel pin level accordingly. No commands are being send to the card in this mode. 257 CYHAL_SDIO_IO_VOLT_ACTION_NONE = 2U, //!< I/O voltage is changed by changing io_volt_sel pin's level. No commands are being send to the card in this mode. 258 } cyhal_sdio_host_io_volt_action_type_t; 259 260 /** 261 * \cond INTERNAL 262 */ 263 /* Compatibility types */ 264 typedef cyhal_sdio_host_command_t cyhal_sdio_command_t; 265 typedef cyhal_sdio_host_transfer_type_t cyhal_sdio_transfer_type_t; 266 typedef cyhal_sdio_host_io_voltage_t cyhal_sdio_io_voltage_t; 267 typedef cyhal_sdio_host_io_volt_action_type_t cyhal_sdio_io_volt_action_type_t; 268 /** \endcond */ 269 270 #endif /* (CYHAL_DRIVER_AVAILABLE_SDIO_HOST) */ 271 272 273 /******************************************************************************* 274 * Data Structures 275 *******************************************************************************/ 276 277 /** @brief SDIO initial configuration */ 278 typedef struct 279 { 280 uint32_t frequencyhal_hz; //!< Clock frequency in hertz (target SDIO frequency for device mode) 281 uint16_t block_size; //!< Block size (max block size for device mode) 282 bool is_sdio_dev; //!< 0 if SDIO host, 1 if SDIO device 283 } cyhal_sdio_cfg_t; 284 285 /** Callback for SDIO events */ 286 typedef void (*cyhal_sdio_event_callback_t)(void *callback_arg, cyhal_sdio_event_t event); 287 288 289 /******************************************************************************* 290 * Functions 291 *******************************************************************************/ 292 /** Initialize the SDIO peripheral 293 * 294 * @param[out] obj Pointer to an SDIO object. The caller must allocate the memory for this object but 295 * the init function will initialize its contents. 296 * @param[in] cmd The pin for the command signal 297 * @param[in] clk The pin for the clk signal 298 * @param[in] data0 The pin for the data0 signal 299 * @param[in] data1 The pin for the data1 signal 300 * @param[in] data2 The pin for the data2 signal 301 * @param[in] data3 The pin for the data3 signal 302 * @return The status of the init request 303 * 304 * Returns \ref CY_RSLT_SUCCESS on successful operation. Refer to \ref subsection_sdio_host_use_case_1 305 * and \ref subsection_sdio_dev_use_case_1 for more information. 306 */ 307 cy_rslt_t cyhal_sdio_init(cyhal_sdio_t *obj, cyhal_gpio_t cmd, cyhal_gpio_t clk, cyhal_gpio_t data0, cyhal_gpio_t data1, cyhal_gpio_t data2, cyhal_gpio_t data3); 308 309 /** Release the SDIO block 310 * 311 * Return the peripheral, pins and clock owned by the SDIO object to its reset state 312 * @param[in,out] obj The SDIO object to deinitialize 313 */ 314 void cyhal_sdio_free(cyhal_sdio_t *obj); 315 316 /** Configure the SDIO block 317 * 318 * SDIO is either a host or a device type. This function allows specifying the 319 * features for either type. Refer to \ref cyhal_sdio_cfg_t for more information. 320 * 321 * @param[in,out] obj The SDIO object 322 * @param[in] config The SDIO configuration to apply 323 * @return The status of the configure request. 324 * 325 * Returns \ref CY_RSLT_SUCCESS on successful operation. 326 */ 327 cy_rslt_t cyhal_sdio_configure(cyhal_sdio_t *obj, const cyhal_sdio_cfg_t *config); 328 329 /** Check if the specified SDIO is in use 330 * 331 * @param[in] obj The SDIO peripheral to check 332 * @return true if SDIO is in use. false, otherwise. 333 */ 334 bool cyhal_sdio_is_busy(const cyhal_sdio_t *obj); 335 336 /** Abort an SDIO transfer 337 * 338 * @param[in] obj The SDIO peripheral to stop 339 * @return The status of the abort_async request. 340 * 341 * Returns \ref CY_RSLT_SUCCESS on successful operation. 342 */ 343 cy_rslt_t cyhal_sdio_abort_async(cyhal_sdio_t *obj); 344 345 /** Register an SDIO event callback handler 346 * 347 * This function will be called when one of the events enabled by \ref cyhal_sdio_enable_event occurs. 348 * 349 * @param[in] obj The SDIO object 350 * @param[in] callback The callback function which will be invoked when the event triggers 351 * @param[in] callback_arg Generic argument that will be provided to the callback when executed 352 * 353 * Refer to \ref subsection_sdio_host_use_case_2 and \ref subsection_sdio_dev_use_case_2 for usage information. 354 */ 355 void cyhal_sdio_register_callback(cyhal_sdio_t *obj, cyhal_sdio_event_callback_t callback, void *callback_arg); 356 357 /** Configure the callback event 358 * 359 * Callbacks will be triggered for the specified SDIO events. 360 * Refer to \ref cyhal_sdio_event_t for the list of supported events. 361 * 362 * @param[in] obj The SDIO object 363 * @param[in] event The SDIO event type 364 * @param[in] intr_priority The priority for NVIC interrupt events 365 * @param[in] enable Set to true to enable events, or false to disable them 366 * 367 * Refer to \ref subsection_sdio_host_use_case_2 and \ref subsection_sdio_dev_use_case_2 for usage information. 368 */ 369 void cyhal_sdio_enable_event(cyhal_sdio_t *obj, cyhal_sdio_event_t event, uint8_t intr_priority, bool enable); 370 371 /** Initialize the SDIO peripheral using a configurator generated configuration struct. 372 * 373 * @param[in] obj The SDIO peripheral to configure 374 * @param[in] cfg Configuration structure generated by a configurator. 375 * @return The status of the operation 376 */ 377 cy_rslt_t cyhal_sdio_init_cfg(cyhal_sdio_t *obj, const cyhal_sdio_configurator_t *cfg); 378 379 380 #if (CYHAL_DRIVER_AVAILABLE_SDIO_DEV) 381 382 /******************************************************************************* 383 * Device-specific Functions 384 *******************************************************************************/ 385 386 /** Check if the device is initialized by the host 387 * 388 * The SDIO device must be initialized by host commands. This function 389 * will return true if the sequence has completed. 390 * 391 * @param[in] obj The SDIO device object 392 * @return true if SDIO is initialized. false, otherwise. 393 */ 394 bool cyhal_sdio_dev_is_ready(cyhal_sdio_t *obj); 395 396 /** Write to the mailbox and send a signal to the host 397 * 398 * This function will send a mailbox interrupt to the host, which will inform the host 399 * to access the data available in the mailbox on the device. 400 * 401 * @param[in] obj The SDIO device object 402 * @param[in] bits Mailbox signal to notify 403 * @param[in] data Data to send to the mailbox (NULL if nothing to send) 404 * @return The status of the mailbox write request. Refer to \ref subsection_sdio_dev_use_case_4 for usage information. 405 */ 406 cy_rslt_t cyhal_sdio_dev_mailbox_write(cyhal_sdio_t *obj, uint32_t bits, uint32_t *data); 407 408 /** Read mailbox data 409 * 410 * This function will read the mailbox data register. It should be performed 411 * after the device receives a mailbox notification from the host. 412 * 413 * @param[in] obj The SDIO device object 414 * @param[in] data Data to send to the mailbox (Optional) 415 * @return The status of the mailbox read request. Refer to \ref subsection_sdio_dev_use_case_4 for usage information. 416 */ 417 cy_rslt_t cyhal_sdio_dev_mailbox_read(cyhal_sdio_t *obj, uint32_t *data); 418 419 /** Synchronous read data 420 * 421 * This is a blocking call that reads the data sent from the host. The read will not 422 * complete until a suitable command from the host is received. 423 * 424 * @param[in] obj The SDIO device object 425 * @param[out] data The buffer for receiving 426 * @param[in,out] length Number of words to read, updated with the number actually read 427 * @param[in] timeout_ms Timeout in millisecond, set this value to 0 if you don't want to wait at all. 428 * @return The status of the read request 429 */ 430 cy_rslt_t cyhal_sdio_dev_read(cyhal_sdio_t *obj, uint8_t *data, size_t length, uint32_t timeout_ms); 431 432 /** Synchronous write data 433 * 434 * This is a blocking call that writes the data to the host. The write will not 435 * complete until a suitable command from the host is received. 436 * 437 * @param[in] obj The SDIO device object 438 * @param[in] data The buffer for sending 439 * @param[in,out] length Number of words to write, updated with the number actually written 440 * @param[in] timeout_ms Timeout in millisecond, set this value to 0 if you don't want to wait at all. 441 * @return The status of the write request 442 */ 443 cy_rslt_t cyhal_sdio_dev_write(cyhal_sdio_t *obj, const uint8_t *data, size_t length, uint32_t timeout_ms); 444 445 /** Start SDIO Device asynchronous read 446 * 447 * This is a non-blocking call. It will initiate the hardware to read from the host 448 * and then immediately return. 449 * When the requested quantity of data has been read, the \ref CYHAL_SDIO_DEV_READ_COMPLETE 450 * event will be raised. 451 * 452 * @param[in] obj The SDIO device object 453 * @param[out] data The read buffer 454 * @param[in] length Number of words to read 455 * @return The status of the async read request. Refer to \ref subsection_sdio_dev_use_case_3 for usage information. 456 */ 457 cy_rslt_t cyhal_sdio_dev_read_async(cyhal_sdio_t *obj, uint8_t *data, size_t length); 458 459 /** Start SDIO Device asynchronous write 460 * 461 * This is a non-blocking call. It will initiate the hardware to write to the host 462 * and then immediately return. 463 * When the requested quantity of data has been written, the \ref CYHAL_SDIO_DEV_WRITE_COMPLETE 464 * event will be raised. 465 * 466 * @param[in] obj The SDIO device object 467 * @param[in] data The write buffer 468 * @param[in] length The number of words to write 469 * @return The status of the async write request. Refer to \ref subsection_sdio_dev_use_case_3 for usage information. 470 */ 471 cy_rslt_t cyhal_sdio_dev_write_async(cyhal_sdio_t *obj, const uint8_t *data, size_t length); 472 473 #endif /* (CYHAL_DRIVER_AVAILABLE_SDIO_DEV) */ 474 475 #if (CYHAL_DRIVER_AVAILABLE_SDIO_HOST) 476 477 /******************************************************************************* 478 * Host-specific Functions 479 *******************************************************************************/ 480 481 /** Send command to the SDIO device 482 * 483 * See \ref cyhal_sdio_host_command_t for list of available commands. 484 * This will block until the command is completed. 485 * 486 * @param[in,out] obj The SDIO host object 487 * @param[in] direction The direction of transfer (read/write) 488 * @param[in] command The command to send to the SDIO device 489 * @param[in] argument The argument to the command 490 * @param[out] response The response from the SDIO device 491 * @return The status of the command transfer. 492 * 493 * Returns \ref CY_RSLT_SUCCESS on successful operation. Refer \ref subsection_sdio_host_use_case_3 for more information. 494 */ 495 cy_rslt_t cyhal_sdio_host_send_cmd(cyhal_sdio_t *obj, cyhal_sdio_host_transfer_type_t direction, cyhal_sdio_host_command_t command, uint32_t argument, uint32_t* response); 496 497 /** Deprecated. Send command to the SDIO device 498 * 499 * See \ref cyhal_sdio_host_command_t for list of available commands. 500 * This will block until the command is completed. 501 * 502 * @param[in,out] obj The SDIO host object 503 * @param[in] direction The direction of transfer (read/write) 504 * @param[in] command The command to send to the SDIO device 505 * @param[in] argument The argument to the command 506 * @param[out] response The response from the SDIO device 507 * @return The status of the command transfer. 508 * 509 * Returns \ref CY_RSLT_SUCCESS on successful operation. Refer \ref subsection_sdio_host_use_case_3 for more information. 510 */ 511 #define cyhal_sdio_send_cmd cyhal_sdio_host_send_cmd 512 513 /** Perform a bulk data transfer 514 * 515 * Sends \ref CYHAL_SDIO_CMD_IO_RW_EXTENDED command (CMD=53) which allows writing and reading 516 * of a large number of I/O registers with a single command. 517 * This will block until the transfer is completed. 518 * 519 * @param[in,out] obj The SDIO host object 520 * @param[in] direction The direction of transfer (read/write) 521 * @param[in] argument The argument to the command 522 * @param[in] data The data to send to the SDIO device. A bulk transfer is done in block 523 * size (default: 64 bytes) chunks for better performance. Therefore, 524 * the size of the data buffer passed into this function must be at least 525 * `length` bytes and a multiple of the block size. For example, when 526 * requesting to read 100 bytes of data with a block size 64 bytes, the 527 * data buffer needs to be at least 128 bytes. The first 100 bytes of data 528 * in the buffer will be the requested data. 529 * @param[in] length The number of bytes to send 530 * @param[out] response The response from the SDIO device 531 * @return The status of the bulk transfer operation. 532 * 533 * Returns \ref CY_RSLT_SUCCESS on successful operation. Refer \ref subsection_sdio_host_use_case_4 for more information. 534 */ 535 cy_rslt_t cyhal_sdio_host_bulk_transfer(cyhal_sdio_t *obj, cyhal_sdio_host_transfer_type_t direction, uint32_t argument, const uint32_t* data, uint16_t length, uint32_t* response); 536 537 /** Deprecated. Perform a bulk data transfer 538 * 539 * Sends \ref CYHAL_SDIO_CMD_IO_RW_EXTENDED command (CMD=53) which allows writing and reading 540 * of a large number of I/O registers with a single command. 541 * This will block until the transfer is completed. 542 * 543 * @param[in,out] obj The SDIO host object 544 * @param[in] direction The direction of transfer (read/write) 545 * @param[in] argument The argument to the command 546 * @param[in] data The data to send to the SDIO device. A bulk transfer is done in block 547 * size (default: 64 bytes) chunks for better performance. Therefore, 548 * the size of the data buffer passed into this function must be at least 549 * `length` bytes and a multiple of the block size. For example, when 550 * requesting to read 100 bytes of data with a block size 64 bytes, the 551 * data buffer needs to be at least 128 bytes. The first 100 bytes of data 552 * in the buffer will be the requested data. 553 * @param[in] length The number of bytes to send 554 * @param[out] response The response from the SDIO device 555 * @return The status of the bulk transfer operation. 556 * 557 * Returns \ref CY_RSLT_SUCCESS on successful operation. Refer \ref subsection_sdio_host_use_case_4 for more information. 558 */ 559 #define cyhal_sdio_bulk_transfer cyhal_sdio_host_bulk_transfer 560 561 /** Perform a bulk asynchronous data transfer 562 * 563 * Transfer by issuing \ref CYHAL_SDIO_CMD_IO_RW_EXTENDED command(CMD=53) to the SDIO block. 564 * After exiting this function, \ref CYHAL_SDIO_CMD_COMPLETE and \ref CYHAL_SDIO_XFER_COMPLETE events are not asserted. 565 * 566 * The \ref CYHAL_SDIO_CMD_COMPLETE and \ref CYHAL_SDIO_XFER_COMPLETE events are enabled 567 * after the asynchronous transfer completes and in the condition they were 568 * enabled in before the transfer operation started. Handle these events in the interrupt callback. 569 * 570 * When the transfer is complete, the \ref CYHAL_SDIO_XFER_COMPLETE event will be raised. 571 * See \ref cyhal_sdio_register_callback and \ref cyhal_sdio_enable_event. 572 * 573 * @param[in,out] obj The SDIO host object 574 * @param[in] direction The direction of transfer (read/write) 575 * @param[in] argument The argument to the command 576 * @param[in] data The data to send to the SDIO device 577 * @param[in] length The number of bytes to send 578 * @return The status of the async tranfer operation. 579 * 580 * Returns \ref CY_RSLT_SUCCESS on successful operation. Refer \ref subsection_sdio_host_use_case_5 for more information. 581 */ 582 cy_rslt_t cyhal_sdio_host_transfer_async(cyhal_sdio_t *obj, cyhal_sdio_host_transfer_type_t direction, uint32_t argument, const uint32_t* data, uint16_t length); 583 584 /** Deprecated. Perform a bulk asynchronous data transfer 585 * 586 * Transfer by issuing \ref CYHAL_SDIO_CMD_IO_RW_EXTENDED command(CMD=53) to the SDIO block. 587 * After exiting this function, \ref CYHAL_SDIO_CMD_COMPLETE and \ref CYHAL_SDIO_XFER_COMPLETE events are not asserted. 588 * 589 * The \ref CYHAL_SDIO_CMD_COMPLETE and \ref CYHAL_SDIO_XFER_COMPLETE events are enabled 590 * after the asynchronous transfer completes and in the condition they were 591 * enabled in before the transfer operation started. Handle these events in the interrupt callback. 592 * 593 * When the transfer is complete, the \ref CYHAL_SDIO_XFER_COMPLETE event will be raised. 594 * See \ref cyhal_sdio_register_callback and \ref cyhal_sdio_enable_event. 595 * 596 * @param[in,out] obj The SDIO host object 597 * @param[in] direction The direction of transfer (read/write) 598 * @param[in] argument The argument to the command 599 * @param[in] data The data to send to the SDIO device 600 * @param[in] length The number of bytes to send 601 * @return The status of the async tranfer operation. 602 * 603 * Returns \ref CY_RSLT_SUCCESS on successful operation. Refer \ref subsection_sdio_host_use_case_5 for more information. 604 */ 605 #define cyhal_sdio_transfer_async cyhal_sdio_host_transfer_async 606 607 /** Set the voltage level of the I/O line 608 * 609 * This function changes the logic level on the io_volt_sel pin. It assumes that this 610 * line is used to control a regulator connected to the VDDIO of the MCU. 611 * This regulator allows for switching between the 3.3V and 1.8V signaling. High level on the pin stands for 612 * 1.8V signaling, while low - for 3.3V. 613 * 614 * @param[in] obj The SDIO host object 615 * @param[in] io_volt_sel The pin connected to the io_volt_sel signal (This pin can be NC). 616 * @param[in] io_voltage I/O voltage to be set on lines 617 * @param[in] io_switch_type Defines how I/O voltage will be switched 618 * @return The status of the operation 619 */ 620 cy_rslt_t cyhal_sdio_host_set_io_voltage(cyhal_sdio_t *obj, cyhal_gpio_t io_volt_sel, cyhal_sdio_host_io_voltage_t io_voltage, 621 cyhal_sdio_host_io_volt_action_type_t io_switch_type); 622 623 /** Deprecated. Set the voltage level of the I/O line 624 * 625 * This function changes the logic level on the io_volt_sel pin. It assumes that this 626 * line is used to control a regulator connected to the VDDIO of the MCU. 627 * This regulator allows for switching between the 3.3V and 1.8V signaling. High level on the pin stands for 628 * 1.8V signaling, while low - for 3.3V. 629 * 630 * @param[in] obj The SDIO host object 631 * @param[in] io_volt_sel The pin connected to the io_volt_sel signal (This pin can be NC). 632 * @param[in] io_voltage I/O voltage to be set on lines 633 * @param[in] io_switch_type Defines how I/O voltage will be switched 634 * @return The status of the operation 635 */ 636 #define cyhal_sdio_set_io_voltage cyhal_sdio_host_set_io_voltage 637 638 #endif /* (CYHAL_DRIVER_AVAILABLE_SDIO_HOST) */ 639 640 #if defined(__cplusplus) 641 } 642 #endif 643 644 #ifdef CYHAL_SDIO_IMPL_HEADER 645 #include CYHAL_SDIO_IMPL_HEADER 646 #endif /* CYHAL_SDIO_IMPL_HEADER */ 647 648 /** \} group_hal_sdio */ 649
