Line data    Source code

       1           1 : /*
       2             :  * Copyright 2022 NXP
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief Public API for SD subsystem
      10             :  */
      11             : 
      12             : #ifndef ZEPHYR_INCLUDE_SD_SD_H_
      13             : #define ZEPHYR_INCLUDE_SD_SD_H_
      14             : 
      15             : #include <zephyr/device.h>
      16             : #include <zephyr/drivers/sdhc.h>
      17             : #include <zephyr/kernel.h>
      18             : 
      19             : #ifdef __cplusplus
      20             : extern "C" {
      21             : #endif
      22             : 
      23             : /**
      24             :  * @brief card status. Used internally by subsystem.
      25             :  */
      26           1 : enum card_status {
      27             :         CARD_UNINITIALIZED = 0, /*!< card has not been initialized */
      28             :         CARD_ERROR = 1, /*!< card state is error */
      29             :         CARD_INITIALIZED = 2, /*!< card is in valid state */
      30             : };
      31             : 
      32             : /**
      33             :  * @brief card type. Used internally by subsystem.
      34             :  */
      35           1 : enum card_type {
      36             :         CARD_SDMMC = 0, /*!< SD memory card */
      37             :         CARD_SDIO = 1, /*!< SD I/O card */
      38             :         CARD_COMBO = 2, /*!< SD memory and I/O card */
      39             :         CARD_MMC = 3, /*!< MMC memory card */
      40             : };
      41             : 
      42             : /**
      43             :  * @brief SDIO function definition
      44             :  *
      45             :  * SDIO function definition. Used to store function information
      46             :  * per each SDIO function
      47             :  */
      48           1 : struct sdio_func {
      49           1 :         enum sdio_func_num num; /*!< Function number */
      50           1 :         struct sd_card *card; /*!< Card this function is present on */
      51           1 :         struct sdio_cis cis; /*!< CIS tuple data for this function */
      52           1 :         uint16_t block_size; /*!< Current block size for this function */
      53             : };
      54             : 
      55             : 
      56             : /**
      57             :  * @brief SD card structure
      58             :  *
      59             :  * This structure is used by the subsystem to track an individual SD
      60             :  * device connected to the system. The application may access these
      61             :  * fields, but use caution when changing values.
      62             :  */
      63           1 : struct sd_card {
      64           1 :         const struct device *sdhc; /*!< SD host controller for card */
      65           1 :         struct sdhc_io bus_io; /*!< Current bus I/O props for SDHC */
      66           1 :         enum sd_voltage card_voltage; /*!< Card signal voltage */
      67           1 :         struct k_mutex lock; /*!< card mutex */
      68           1 :         struct sdhc_host_props host_props; /*!< SDHC host properties */
      69           1 :         uint32_t ocr; /*!< Raw card OCR content */
      70           1 :         struct sd_switch_caps switch_caps; /*!< SD switch capabilities */
      71           1 :         unsigned int num_io: 3; /*!< I/O function count. 0 for SD cards */
      72           1 :         uint16_t relative_addr; /*!< Card relative address */
      73           1 :         uint32_t block_count; /*!< Number of blocks in SD card */
      74           1 :         uint16_t block_size; /*!< SD block size */
      75           1 :         uint8_t sd_version; /*!< SD specification version */
      76           1 :         uint8_t card_speed; /*!< Card timing mode */
      77           1 :         enum card_status status; /*!< Card status */
      78           1 :         enum card_type type; /*!< Card type */
      79           1 :         uint16_t flags; /*!< Card flags */
      80           1 :         uint8_t bus_width; /*!< Desired bus width */
      81           1 :         uint32_t cccr_flags; /*!< SDIO CCCR data */
      82           1 :         struct sdio_func func0; /*!< Function 0 common card data */
      83             : 
      84             :         /* NOTE: The buffer is accessed as a uint32_t* by the SD subsystem, so must be
      85             :          * aligned to 4 bytes for platforms that don't support unaligned access...
      86             :          * Systems where the buffer is accessed by DMA may require wider alignment, in
      87             :          * which case, use CONFIG_SDHC_BUFFER_ALIGNMENT.
      88             :          */
      89           0 :         uint8_t card_buffer[CONFIG_SD_BUFFER_SIZE]
      90             :                 __aligned(MAX(4, CONFIG_SDHC_BUFFER_ALIGNMENT)); /* Card internal buffer */
      91             : };
      92             : 
      93             : /**
      94             :  * @brief Initialize an SD device
      95             :  *
      96             :  * Initializes an SD device to use with the subsystem. After this call,
      97             :  * only the SD card structure is required to access the card.
      98             :  * @param sdhc_dev SD host controller device for this card
      99             :  * @param card SD card structure for this card
     100             :  * @retval 0 card was initialized
     101             :  * @retval -ETIMEDOUT: card initialization timed out
     102             :  * @retval -EBUSY: card is busy
     103             :  * @retval -EIO: IO error while starting card
     104             :  */
     105           1 : int sd_init(const struct device *sdhc_dev, struct sd_card *card);
     106             : 
     107             : /**
     108             :  * @brief checks to see if card is present in the SD slot
     109             :  *
     110             :  * @param sdhc_dev SD host controller to check for card presence on
     111             :  * @retval true card is present
     112             :  * @retval false card is not present
     113             :  */
     114           1 : bool sd_is_card_present(const struct device *sdhc_dev);
     115             : 
     116             : 
     117             : #ifdef __cplusplus
     118             : }
     119             : #endif
     120             : 
     121             : #endif /* ZEPHYR_INCLUDE_SD_SD_H_ */