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_ */