ra8_sdcard.c

Go to the documentation of this file.

 
#include "ra8_sdcard.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_sdhi.h"

static const char* s_tag = "SDCARD";

typedef enum : uint32_t {
  k_sd_block_size_bytes  = 512U,         
  k_sd_csd_struct_shift  = 30U,          
  k_sd_rca_mask          = 0xFFFFU,      
  k_sd_read_bl_mask      = 0xFU,         
  k_sd_csize_v2_lo_mask  = 0x0000003FUL, 
  k_sd_csize_v2_mid_mask = 0x0000FFFFUL, 
  k_sd_csize_v2_mask     = 0x003FFFFFUL, 
  k_sd_csize_v1_shift    = 10U,          
  k_sd_csize_v1_lo_shift = 22U,          
  k_sd_csize_v1_lo_mask  = 0x000003FFUL, 
  k_sd_csize_v1_mask     = 0xFFFU,       
  k_sd_csize_mult_shift  = 7U,           
  k_sd_csize_mult_mask   = 0x7U,         
} sd_csd_field_t;

typedef enum : uint8_t {
  k_ra8_sdcard_cmd0_go_idle        = 0U,  
  k_ra8_sdcard_cmd2_all_send_cid   = 2U,  
  k_ra8_sdcard_cmd3_send_rca       = 3U,  
  k_ra8_sdcard_cmd7_select_card    = 7U,  
  k_ra8_sdcard_cmd8_send_if_cond   = 8U,  
  k_ra8_sdcard_cmd9_send_csd       = 9U,  
  k_ra8_sdcard_cmd55_app_cmd       = 55U, 
  k_ra8_sdcard_acmd41_send_op_cond = 41U, 
} ra8_sdcard_cmd_t;

typedef enum : uint32_t {
  k_ra8_sdcard_cmd8_pattern       = 0x000001AAUL, 
  k_ra8_sdcard_cmd8_pattern_mask  = 0x00000FFFUL, 
  k_ra8_sdcard_acmd41_hcs         = 0x40000000UL, 
  k_ra8_sdcard_acmd41_voltage_win = 0x00FF8000UL, 
  k_ra8_sdcard_ocr_busy_done_mask = 0x80000000UL, 
  k_ra8_sdcard_ocr_ccs_mask       = 0x40000000UL, 
  k_ra8_sdcard_init_retry_max     = 1000U,        
  k_ra8_sdcard_default_clk_div    = 0x00000004UL, 
} ra8_sdcard_proto_t;

typedef enum : uint32_t {
  k_ra8_sdcard_csd_v2_blocks_per_unit = 1024UL,    
  k_ra8_sdcard_sdhc_threshold_blocks  = 4194304UL, 
} ra8_sdcard_csd_t;

typedef struct {
  uint32_t               capacity_blocks; 
  uint16_t               rca;             
  ra8_sdcard_card_type_t type;            
  uint8_t                instance;        
  uint8_t                initialized;     
} ra8_sdcard_state_t;

static ra8_sdcard_state_t s_sdcard;
 
/* Issue ACMD41 with the host capacity-support bit set and loop -- see implementation for details. */
RA8_INTERNAL
static ra8_err_t internal_run_acmd41(uint8_t instance, uint32_t* out_ocr)
{
  RA8_CHECK_NULL_PTR(out_ocr, s_tag, "ocr");
 
  uint32_t rsp[4] = {0U, 0U, 0U, 0U};
  uint32_t ocr    = 0U;
  uint8_t  done   = 0U;
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_sdcard_init_retry_max; ++i) {
    /* HUM Ch 47.2.1 "SD_CMD : Command Type Register" p 3123 */
    /* CMD55 prefix is required before every ACMDxx. */
    const ra8_err_t e55 =
      ra8_sdhi_send_command(instance, (uint32_t)k_ra8_sdcard_cmd55_app_cmd, 0U, rsp);
    if (e55 != k_ra8_ok) {
      return e55;
    }
    /* HUM Ch 47.2.2 "SD_ARG : SD Command Argument" p 3124 */
    /* HCS=1 (host supports SDHC/SDXC) | voltage window 2.7-3.6 V. */
    const uint32_t arg =
      (uint32_t)k_ra8_sdcard_acmd41_hcs | (uint32_t)k_ra8_sdcard_acmd41_voltage_win;
    const ra8_err_t e41 =
      ra8_sdhi_send_command(instance, (uint32_t)k_ra8_sdcard_acmd41_send_op_cond, arg, rsp);
    if (e41 != k_ra8_ok) {
      return e41;
    }
    ocr = rsp[0];
    if ((ocr & (uint32_t)k_ra8_sdcard_ocr_busy_done_mask) != 0U) {
      done = 1U;
      break;
    }
  }
  if (done == 0U) {
    return k_ra8_err_hw_init_failed;
  }
  *out_ocr = ocr;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_decode_csd(const uint32_t* rsp, uint32_t* out_blocks)
{
  RA8_CHECK_NULL_PTR(rsp, s_tag, "rsp");
  RA8_CHECK_NULL_PTR(out_blocks, s_tag, "blocks");
 
  /* CSD_STRUCTURE is rsp[3][31:30]. SDHI shifts the response left by
   * 8 (CRC drop), so the architectural CSD[127:126] lands at
   * rsp[3][31:30] -- the same place FSP r_sdhi.c reads it from. */
  const uint8_t csd_structure = (uint8_t)((rsp[3] >> k_sd_csd_struct_shift) & 0x3U);
  if (csd_structure == 1U) {
    /* CSD v2 (SDHC/SDXC): C_SIZE is bits [69:48], i.e. rsp[1][29:8]
     * once you account for the CRC shift. The 22-bit field needs the
     * low 6 bits of rsp[2] OR'd with the high 16 bits of rsp[1]. */
    const uint32_t c_size =
      (((rsp[2] & k_sd_csize_v2_lo_mask) << 16U) | ((rsp[1] >> 16U) & k_sd_csize_v2_mid_mask)) &
      k_sd_csize_v2_mask;
    *out_blocks = (c_size + 1U) * (uint32_t)k_ra8_sdcard_csd_v2_blocks_per_unit;
    return k_ra8_ok;
  }
  if (csd_structure == 0U) {
    /* CSD v1 (SDSC): READ_BL_LEN [83:80], C_SIZE [73:62],
     * C_SIZE_MULT [49:47]. Compute capacity in bytes then divide by
     * 512 to land on the block count. */
    const uint8_t  read_bl_len = (uint8_t)((rsp[2] >> 16U) & k_sd_read_bl_mask);
    const uint16_t c_size =
      (uint16_t)((((rsp[2] & 0x00000003UL) << k_sd_csize_v1_shift) |
                  ((rsp[1] >> k_sd_csize_v1_lo_shift) & k_sd_csize_v1_lo_mask)) &
                 k_sd_csize_v1_mask);
    const uint8_t c_size_mult = (uint8_t)((rsp[1] >> k_sd_csize_mult_shift) & k_sd_csize_mult_mask);
    const uint32_t mult       = 1U << ((uint32_t)c_size_mult + 2U);
    const uint32_t block_len  = 1U << (uint32_t)read_bl_len;
    const uint32_t blocknr    = ((uint32_t)c_size + 1U) * mult;
    /* Convert to 512-byte sectors. */
    *out_blocks = (blocknr * block_len) / k_sd_block_size_bytes;
    return k_ra8_ok;
  }
  return k_ra8_err_hw_init_failed;
}

RA8_INTERNAL
static ra8_err_t internal_sdcard_identify(uint8_t instance)
{
  uint32_t rsp[4] = {0U, 0U, 0U, 0U};
 
  /* HUM Ch 47.2.1 "SD_CMD : Command Type Register" p 3123 */
  /* CMD0 GO_IDLE_STATE -- no response, but send_command still polls
   * RSPEND so the host stays in lockstep with the bus state machine. */
  const ra8_err_t e0 =
    ra8_sdhi_send_command(instance, (uint32_t)k_ra8_sdcard_cmd0_go_idle, 0U, rsp);
  RA8_RETURN_ON_ERROR(e0, s_tag, "cmd0");
 
  /* HUM Ch 47.2.5 "SD_RSP10 : Response Register 10" p 3132 */
  /* CMD8 SEND_IF_COND -- echoes the low 12 bits of the argument back
   * in R7. Mismatch means a v1 (no-CMD8) card or no card at all. */
  const ra8_err_t e8 = ra8_sdhi_send_command(instance,
                                             (uint32_t)k_ra8_sdcard_cmd8_send_if_cond,
                                             (uint32_t)k_ra8_sdcard_cmd8_pattern,
                                             rsp);
  /* GCOVR_EXCL_BR_START -- no failing SDHI fake drives this cmd err */
  RA8_RETURN_ON_ERROR(e8, s_tag, "cmd8");
  /* GCOVR_EXCL_BR_STOP */
  if ((rsp[0] & (uint32_t)k_ra8_sdcard_cmd8_pattern_mask) !=
      ((uint32_t)k_ra8_sdcard_cmd8_pattern & (uint32_t)k_ra8_sdcard_cmd8_pattern_mask)) {
    return k_ra8_err_hw_init_failed;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_sdcard_publish_rca(uint8_t instance, uint16_t* out_rca)
{
  uint32_t rsp[4] = {0U, 0U, 0U, 0U};
 
  /* HUM Ch 47.2.5 "SD_RSP10..76 : Response Registers" p 3132 */
  /* CMD2 ALL_SEND_CID -- 136-bit R2; we don't decode the CID. */
  const ra8_err_t e2 =
    ra8_sdhi_send_command(instance, (uint32_t)k_ra8_sdcard_cmd2_all_send_cid, 0U, rsp);
  /* GCOVR_EXCL_BR_START -- SD command fail never injected by suite */
  RA8_RETURN_ON_ERROR(e2, s_tag, "cmd2");
  /* GCOVR_EXCL_BR_STOP */
 
  /* CMD3 SEND_RELATIVE_ADDR -- card publishes its RCA in rsp[0][31:16]. */
  const ra8_err_t e3 =
    ra8_sdhi_send_command(instance, (uint32_t)k_ra8_sdcard_cmd3_send_rca, 0U, rsp);
  /* GCOVR_EXCL_BR_START -- cmd error propagation arm not driven */
  RA8_RETURN_ON_ERROR(e3, s_tag, "cmd3");
  /* GCOVR_EXCL_BR_STOP */
  *out_rca = (uint16_t)((rsp[0] >> 16U) & k_sd_rca_mask);
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t
internal_sdcard_publish_and_select(uint8_t instance, uint16_t* out_rca, uint32_t* out_blocks)
{
  uint16_t        rca     = 0U;
  const ra8_err_t rca_err = internal_sdcard_publish_rca(instance, &rca);
  if (rca_err != k_ra8_ok) {
    return rca_err;
  }
  const uint32_t rca_arg = ((uint32_t)rca) << 16U;
  uint32_t       rsp[4]  = {0U, 0U, 0U, 0U};
 
  /* CMD9 SEND_CSD -- arg = RCA<<16; R2 holds the 128-bit CSD. */
  const ra8_err_t e9 =
    ra8_sdhi_send_command(instance, (uint32_t)k_ra8_sdcard_cmd9_send_csd, rca_arg, rsp);
  /* GCOVR_EXCL_BR_START -- SDHI fake never fails this transfer */
  RA8_RETURN_ON_ERROR(e9, s_tag, "cmd9");
  /* GCOVR_EXCL_BR_STOP */
 
  const ra8_err_t dec_err = internal_decode_csd(rsp, out_blocks);
  if (dec_err != k_ra8_ok) {
    return dec_err;
  }
 
  /* CMD7 SELECT_CARD -- arg = RCA<<16 to put this card into TRAN. */
  const ra8_err_t e7 =
    ra8_sdhi_send_command(instance, (uint32_t)k_ra8_sdcard_cmd7_select_card, rca_arg, rsp);
  /* GCOVR_EXCL_BR_START -- no test injects SD read failure here */
  RA8_RETURN_ON_ERROR(e7, s_tag, "cmd7");
  /* GCOVR_EXCL_BR_STOP */
 
  *out_rca = rca;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_sdcard_card_type_t internal_classify(uint8_t high_capacity, uint32_t blocks)
{
  if (high_capacity == 0U) {
    return k_ra8_sdcard_type_sdsc;
  }
  if (blocks > (uint32_t)k_ra8_sdcard_sdhc_threshold_blocks * 16U) {
    return k_ra8_sdcard_type_sdxc;
  }
  return k_ra8_sdcard_type_sdhc;
}

RA8_INTERNAL
static void
internal_sdcard_negotiate_width(uint8_t instance, ra8_sdhi_bus_width_t width, uint16_t rca)
{
  if (width != k_ra8_sdhi_bus_width_4bit) {
    return;
  }
  const ra8_err_t we = ra8_sdhi_set_bus_width_4bit(instance, rca);
  if (we != k_ra8_ok) {
    /* Best-effort: fall back to the proven 1-bit mode. */
    ra8_log_info_val(s_tag, "4-bit negotiation failed; staying 1-bit", (uint32_t)we);
  }
}

RA8_INTERNAL
static ra8_err_t internal_sdcard_card_online(uint8_t   instance,
                                             uint16_t* out_rca,
                                             uint32_t* out_blocks,
                                             uint8_t*  out_high_capacity)
{
  /* HUM Ch 47.1 "SDHI Overview" p 3122 */ /* module bring-up first. */
  const ra8_err_t hw_err = ra8_sdhi_init(instance);
  RA8_RETURN_ON_ERROR(hw_err, s_tag, "sdhi_init");
 
  const ra8_err_t id_err = internal_sdcard_identify(instance);
  if (id_err != k_ra8_ok) {
    (void)ra8_sdhi_deinit(instance);
    return id_err;
  }
 
  /* ACMD41 op-cond loop -- card moves from idle to ready. */
  uint32_t        ocr = 0U;
  const ra8_err_t e41 = internal_run_acmd41(instance, &ocr);
  if (e41 != k_ra8_ok) {
    (void)ra8_sdhi_deinit(instance);
    return e41;
  }
  *out_high_capacity = ((ocr & (uint32_t)k_ra8_sdcard_ocr_ccs_mask) != 0U) ? 1U : 0U;
 
  const ra8_err_t pub_err = internal_sdcard_publish_and_select(instance, out_rca, out_blocks);
  if (pub_err != k_ra8_ok) {
    (void)ra8_sdhi_deinit(instance);
    return pub_err;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_sdcard_init(const ra8_sdcard_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg");
  if (s_sdcard.initialized != 0U) {
    return k_ra8_err_invalid_state;
  }
 
  uint16_t        rca           = 0U;
  uint32_t        blocks        = 0U;
  uint8_t         high_capacity = 0U;
  const ra8_err_t on_err =
    internal_sdcard_card_online(cfg->instance, &rca, &blocks, &high_capacity);
  if (on_err != k_ra8_ok) {
    return on_err;
  }
 
  /* Optional bus-width widening (best-effort, never fatal) while still
   * at the identification clock, before the default-speed clock bump. */
  internal_sdcard_negotiate_width(cfg->instance, cfg->bus_width, rca);
 
  /* HUM Ch 47.2.18 "SD_CLK_CTRL : SD Clock Control Register" p 3138 */
  /* Bump the bus from the 400 kHz identification rate to default
   * speed. The SDR50 / DDR50 negotiation lives in the future
   * ::ra8_sdcard_set_speed extension. */
  const ra8_err_t eclk = ra8_sdhi_set_clock(cfg->instance, (uint32_t)k_ra8_sdcard_default_clk_div);
  /* GCOVR_EXCL_BR_START -- card error unwind not staged on host */
  RA8_RETURN_ON_ERROR(eclk, s_tag, "set_clock");
  /* GCOVR_EXCL_BR_STOP */
 
  s_sdcard.instance        = cfg->instance;
  s_sdcard.rca             = rca;
  s_sdcard.capacity_blocks = blocks;
  s_sdcard.type            = internal_classify(high_capacity, blocks);
  s_sdcard.initialized     = 1U;
 
  ra8_log_info_val(s_tag, "sdcard init blocks", blocks);
  return k_ra8_ok;
}

RA8_INTERNAL
static uint32_t internal_to_card_address(uint32_t lba)
{
  if (s_sdcard.type == k_ra8_sdcard_type_sdsc) {
    return lba * k_sd_block_size_bytes;
  }
  return lba;
}
 
ra8_err_t ra8_sdcard_read_blocks(uint32_t lba, uint8_t* buf, uint32_t count)
{
  RA8_CHECK_NULL_PTR(buf, s_tag, "buf");
  if (count == 0U) {
    return k_ra8_err_invalid_arg;
  }
  if (s_sdcard.initialized == 0U) {
    return k_ra8_err_invalid_state;
  }
  if ((lba + count) > s_sdcard.capacity_blocks) {
    return k_ra8_err_out_of_range;
  }
  const uint32_t card_lba = internal_to_card_address(lba);
  return ra8_sdhi_read_block(s_sdcard.instance, card_lba, buf, count);
}
 
ra8_err_t ra8_sdcard_write_blocks(uint32_t lba, const uint8_t* buf, uint32_t count)
{
  RA8_CHECK_NULL_PTR(buf, s_tag, "buf");
  if (count == 0U) {
    return k_ra8_err_invalid_arg;
  }
  if (s_sdcard.initialized == 0U) {
    return k_ra8_err_invalid_state;
  }
  if ((lba + count) > s_sdcard.capacity_blocks) {
    return k_ra8_err_out_of_range;
  }
  const uint32_t card_lba = internal_to_card_address(lba);
  return ra8_sdhi_write_block(s_sdcard.instance, card_lba, buf, count);
}
 
ra8_err_t ra8_sdcard_get_capacity(uint32_t* out_blocks)
{
  RA8_CHECK_NULL_PTR(out_blocks, s_tag, "out_blocks");
  if (s_sdcard.initialized == 0U) {
    return k_ra8_err_invalid_state;
  }
  *out_blocks = s_sdcard.capacity_blocks;
  return k_ra8_ok;
}
 
ra8_err_t ra8_sdcard_get_type(ra8_sdcard_card_type_t* out_type)
{
  RA8_CHECK_NULL_PTR(out_type, s_tag, "out_type");
  if (s_sdcard.initialized == 0U) {
    return k_ra8_err_invalid_state;
  }
  *out_type = s_sdcard.type;
  return k_ra8_ok;
}
 
ra8_err_t ra8_sdcard_deinit(void)
{
  if (s_sdcard.initialized == 0U) {
    return k_ra8_ok;
  }
  const uint8_t inst       = s_sdcard.instance;
  s_sdcard.initialized     = 0U;
  s_sdcard.capacity_blocks = 0U;
  s_sdcard.rca             = 0U;
  s_sdcard.type            = k_ra8_sdcard_type_unknown;
  const ra8_err_t err      = ra8_sdhi_deinit(inst);
  if (err != k_ra8_ok) {
    /* ra8_sdhi_deinit fails only if ra8_mstp_disable times out on the MSTP
     * readback loop. Reached on host by arming the ra8_fake_mmio seam on the
     * SDHI module's MSTPCR register so that readback never settles. */
    return k_ra8_err_invalid_state;
  }
  return k_ra8_ok;
}