Delete me: SDCard/Init (Rev #6)

Note to readers and editors

The purpose of this page (and related pages) is to capture useful information and observations about various SD drivers that exist in the Open Source community, notably Linux, but without documenting any specifics (e.g. source code examples). This will hopefully aid in a clean-room implementation of an SD driver for RISC OS.

Linux SDHCI driver init

Notes based on reading linux/drivers/mmc/host/sdhci.c and associated files. sdhci.c 20% complete.

HC = Host Controller

SDHCI controller Quirk bits – complete

 0 Resets not honoured until we provide a clock SDHCI_QUIRK_CLOCK_BEFORE_RESET
 1 Really supports DMA but caps bits lie SDHCI_QUIRK_FORCE_DMA
 2 Doesn't like being reset when there's no card SDHCI_QUIRK_NO_CARD_NO_RESET
 3 Doesn't like clearing the power register before being changed SDHCI_QUIRK_SINGLE_POWER_WRITE
 4 Needs command data reset on each ios change due to flaky internal state SDHCI_QUIRK_RESET_CMD_DATA_ON_IOS
 5 Broken DMA engine SDHCI_QUIRK_BROKEN_DMA
 6 Broken ADMA engine SDHCI_QUIRK_BROKEN_ADMA
 7 Needs DMA addresses to be 32 bit aligned SDHCI_QUIRK_32BIT_DMA_ADDR
 8 Needs DMA chunks to be a multiple of 32 bits SDHCI_QUIRK_32BIT_DMA_SIZE
 9 Needs ADMA chunks to be a multiple of 32 bits SDHCI_QUIRK_32BIT_ADMA_SIZE
 10 Have to reset after every request to stay stable SDHCI_QUIRK_RESET_AFTER_REQUEST
 11 Can't cope with simulataneous voltage and power writes SDHCI_QUIRK_NO_SIMULT_VDD_AND_POWER
 12 Provides broken timeout value for transfers SDHCI_QUIRK_BROKEN_TIMEOUT_VAL
 13 Has problem with buffer bits in PIO transfers < 4 bytes (eg JMicron JMB38x) SDHCI_QUIRK_BROKEN_SMALL_PIO
 14 Doesn't provide a transfer-complete IRQ if not busy SDHCI_QUIRK_NO_BUSY_IRQ
 15 Can't reliably detect cards SDHCI_QUIRK_BROKEN_CARD_DETECTION
 16 Write protect state inverted SDHCI_QUIRK_INVERTED_WRITE_PROTECT
 17 Clock management non-standard SDHCI_QUIRK_NONSTANDARD_CLOCK
 18 Needs delay for PIO transfers (doesn't like them fast) SDHCI_QUIRK_PIO_NEEDS_DELAY
 19 Loses signal/IRQ enable states over reset - have to restore afterwards SDHCI_QUIRK_RESTORE_IRQS_AFTER_RESET
 20 Needs forcing of block size to be 2048 bytes SDHCI_QUIRK_FORCE_BLK_SZ_2048
 21 Can't do multi-block transfers SDHCI_QUIRK_NO_MULTIBLOCK
 22 Can only do 1 bit data transfers SDHCI_QUIRK_FORCE_1_BIT_DATA
 23 Needs 10ms delay between power and clock SDHCI_QUIRK_DELAY_AFTER_POWER
 24 SDCLK used instead of TMCLK for data timeouts SDHCI_QUIRK_DATA_TIMEOUT_USES_SDCLK
 25 Capability reports wrong base clock SDHCI_QUIRK_CAP_CLOCK_BASE_BROKEN
 26 Can't support End Attribute in NOP ADMA descriptor SDHCI_QUIRK_NO_ENDATTR_IN_NOPDESC
 27 No device capabilities register.  Need to be faked up by host SDHCI_QUIRK_MISSING_CAPS
 28 Multiblock transfers stopped with ACMD12 SDHCI_QUIRK_MULTIBLOCK_READ_ACMD12
 29 No HISPD bit field for HI-SPEED SD cards SDHCI_QUIRK_NO_HISPD_BIT
 30 ADMA descriptors with length 0 are treated incorrectly SDHCI_QUIRK_BROKEN_ADMA_ZEROLEN_DESC
 31 Read-only detection using the SDHCI_PRESENT_STATE register is not reliable SDHCI_QUIRK_UNSTABLE_RO_DETECT

Platform drivers (ie specific ARM boards with SDHCI ports) only set SDHCI_QUIRK_MULTIBLOCK_READ_ACMD12, SDHCI_QUIRK_FORCE_1_BIT_DATA, SDHCI_QUIRK_INVERTED_WRITE_PROTECT. Some SoCs have extra drivers for their own weirdnesses (Tegra does, OMAP doesn’t AFAICS) which may set more quirk bits.

SDHCI Quirk2 bits – complete

  0 Driver does its own card detection SDHCI_QUIRK2_OWN_CARD_DETECTION

MMC/SD/SDIO card quirks – complete

0 SDIO FN0 outside the VS CCCR range are permitted  MMC_QUIRK_LENIENT_FN0
1 Use current block size for byte mode MMC_QUIRK_BLKSZ_FOR_BYTE_MODE
2 SDIO attached is missing CIA registers MMC_QUIRK_NONSTD_SDIO
3 Card will fail if SDIO bus clock gated MMC_QUIRK_BROKEN_CLK_GATING
4 Non-standard function interfaces on SDIO card MMC_QUIRK_NONSTD_FUNC_IF
5 Resistor for CD/DAT[3] should be disconnected MMC_QUIRK_DISABLE_CD
6 CMD38 broken for iNAND devices MMC_QUIRK_INAND_CMD38
7 Don't use CMD23 for regular multiblock MMC_QUIRK_BLK_NO_CMD23
8 Don't send 512 bytes in byte mode MMC_QUIRK_BROKEN_BYTE_MODE_512

SDHCI register map – complete

0x0,SDHCI_DMA_ADDRESS/SDHCI_ARGUMENT2
0x4,SDHCI_BLOCK_SIZE
0x06,SDHCI_BLOCK_COUNT
0x08,SDHCI_ARGUMENT
0x0C,SDHCI_TRANSFER_MODE
0x0E,SDHCI_COMMAND
0x10,SDHCI_RESPONSE
0x20,SDHCI_BUFFER
0x24,SDHCI_PRESENT_STATE
0x28,SDHCI_HOST_CONTROL
0x29,SDHCI_POWER_CONTROL
0x2A,SDHCI_BLOCK_GAP_CONTROL
0x2B,SDHCI_WAKE_UP_CONTROL
0x2C,SDHCI_CLOCK_CONTROL
0x2E,SDHCI_TIMEOUT_CONTROL
0x2F,SDHCI_SOFTWARE_RESET
0x30,SDHCI_INT_STATUS
0x34,SDHCI_INT_ENABLE
0x38,SDHCI_SIGNAL_ENABLE
0x3C,SDHCI_ACMD12_ERR
0x3E,SDHCI_HOST_CONTROL2
0x40,SDHCI_CAPABILITIES
0x44,SDHCI_CAPABILITIES_1
0x48,SDHCI_MAX_CURRENT (4C-4F reserved for further max current)
0x50,SDHCI_SET_ACMD12_ERROR
0x52,SDHCI_SET_INT_ERROR
0x54,SDHCI_ADMA_ERROR
0x55-0x57,reserved
0x58,SDHCI_ADMA_ADDRESS
0x60-0xFB,reserved
0xFC,SDHCI_SLOT_INT_STATUS
0xFE,SDHCI_HOST_VERSION

sdhci_reset(mask) – complete algorithm

To reset the controller:

1. If SDHCI_QUIRK_NO_CARD_NO_RESET and no card is present (read32 SDHCI_PRESENT_STATE to check), then return
2. If SDHCI_QUIRK_RESTORE_IRQS_AFTER_RESET then ier=read32 of SDHCI_INT_ENABLE reg so we know the interrupt state to restore after reset
3. If there’s some platform reset code, call the pre-handler
4. Write8 of the reset mask parameter to SDHCI_SOFTWARE_RESET reg
5. If mask contains SDHCI_RESET_ALL, set the local copy of the clock reg to zero
6. Poll (read8) SDHCI_SOFTWARE_RESET every 1ms until the mask bits are no longer set (timeout 100ms)
7. Call the post-handler
8. If SDHCI_QUIRK_RESTORE_IRQS_AFTER_RESET then write back ier, the stored interrupt enable state, with sdhci_clear_set_irqs

sdhci_clear_set_irqs – complete algorithm

To clear and set IRQs:

1. ier = Read32 of SDHCI_INT_ENABLE
2. Clear and set bits in ier
3. Write32 ier to SDHCI_INT_ENABLE
4. Write32 ier to SDHCI_SIGNAL_ENABLE

sdhci_set_card_detection(enable_irqs) – complete

1. If SDHCI_QUIRK_BROKEN_CARD_DETECTION or SDHCI_QUIRK2_OWN_CARD_DETECTION, give up
2. Read32(SDHCI_PRESENT_STATE) – if SDHCI_CARD_PRESENT bit set, card is present
3. If present, set interrupts to notify if card removed, else notify if card inserted
4. If enable_irqs, unmask the above IRQs else mask them

sdhci_init(soft_reset) – complete

1. If doing a soft reset, call sdhci_reset with RESET_CMD and RESET_DATA bits, else call with RESET_ALL bits
2. sdhci_clear_set_irqs(Clear all bits; set bits for bus power, data end bit, data crc, data timeout, index, end, crc, timeout, data end [not same as data end bit], response)
3. if soft reset, force clock reconfiguration (sdhci_set_ios)

sdhci_read_block_pio – complete

Read a block into a scatter/gather list. Perform read32s of SDHCI_BUFFER, but watch that the scatter/gather blocks may not be multiples of 4 bytes.
Save the local Linux interrupt state before and restore after the PIO loop

sdhci_write_block_pio – complete

The same as above, but for writes. Uses write32 to SDHCI_BUFFER

sdhci_transfer_pio – complete

1. If SDHCI_QUIRK_BROKEN_SMALL_PIO, force a transfer of one block and ignore the buffer flags in the loop below
2. For each block:
   1. Read32 the buffer flags in SDHCI_PRESENT_STATE
   2. If there’s data available (a read) or space (a write), then
      1. Wait 100us if SDHCI_QUIRK_PIO_NEEDS_DELAY
      2. Read or write a block (sdhci_read/write_block_pio)
   3. Repeat until we’ve done all the blocks we want

sdhci_add_host – complete

1. Reset the sdhci device (sdhci_reset)
2. Read16 the SDHCI_HOST_VERSION register and mask out the version bits
   1. If the Host Controller version >= 3.00, error that the controller version is unknown and may cause problems
3. If host→quirks contains SDHCI_QUIRK_MISSING_CAPS, return a faked up capabilities register, else caps⁰ = 32 bits of SDHCI_CAPABILITIES
4. If version >= 3.00, read SDHCI_CAPABILITIES_1 register and save in caps¹, else save 0.
5. If host→quirks contains SDHCI_QUIRK_FORCE_DMA then we’ll use SDMA mode.
6. If caps say we can use SDMA, we’ll use SDMA
7. If caps say we can use SDMA but SDHCI_QUIRK_BROKEN_DMA is set, don’t use SDMA as we don’t trust it
8. If Host Controller 2.00 or later, will use ADMA if device can use it (capability bit SDHCI_CAN_DO_AMA2) and not disabled by quirk (SDHCI_QUIRK_BROKEN_ADMA).
9. If we think we can do SDMA or ADMA, try to enable DMA on the host. If it doesn’t work, fallback to PIO
10. If can do ADMA, allocate descriptors for scatter/gather entries – if can’t allocate fallback to SDMA.
11. If using SDMA or ADMA, try to set up the host DMA mask (?)
12. Max clock freq (in MHz) is bits 15-8 in capability register in version >= 3.00, bits 13-8 before. If SDHCI_QUIRK_CLOCK_BASE_BROKEN or freq from caps reg is 0, call host→ops→get_max_clock(host) to ask the host to work out the clock freq.
13. If HC >= 3.00, read out clock multiplier from caps ¹. If not supported or zero, clock multipler = 1
14. Calculate f_min and f_max:
    1. f_max = max_clk
    2. If spec 3.00 and clock multipler non-zero:
       1. f_min = max_clk * clk_mul / 1024
       2. f_max = max_clk * clk_mul
    3. If spec 3.00 and clk_mul=0
       1. f_min = max_clk / max clock divider from spec 3.00
    4. If spec < 3.00
       1. f_min = max_clk / max clock divider from spec 2.00
15. Read timeout clock from cap⁰. If zero, get from host host→ops→get_timeout_clock if available. If caps⁰ SDHCI_TIMEOUT_CLK_UNIT bit set, time in ms else in seconds.
16. If SDHCI_QUIRK_DATA_TIMEOUT_USES_SDCLK, timeout clk is f_max / 1000
17. max_discard_to (?) is (1<<27) / timeout clk
18. turn driver options on: MMC_CAP_SDIO_IRQ, MMC_CAP_ERASE, MMC_CAP_CMD23
19. If quirk SDHCI_QUIRK_MULTIBLOCK_READ_ACMD12, set option SDHCI_AUTO_CMD12 (?)
20. If spec 3.00 and using ADMA or not using SDMA, then support command ACMD23, otherwise don’t.
21. Bus width: Platform code (not sdhci.c) sets MMC_CAP_8_BIT_DATA if available on our board: controller may support it but have pins wired
    1. If SDHCI_QUIRK_FORCE_1_BIT_DATA then we can use MMC_CAP_4_BIT_DATA
22. If SDHCI_QUIRK_BROKEN_CARD_DETECTION then we’ll need to poll to check if the card’s there
23. Speeds:
    1. If spec >= 3.00 can use UHS-I mode (UHS_SDR12 and UHS_SDR25)
    2. caps¹ says if can support SDR104+SDR50 mode, or SDR50 mode
    3. caps¹ says if can support DDR50 mode
    4. caps¹ says if need tuning for SDR50
    5. caps¹ says if supports any of driver type A, type C, type D
24. Set power off notify timeout values (short or none) – only for host (?)
25. Initialise re-tuning timer count from caps¹ (2^(caps_field-1))
26. Tuning mode extracted from caps¹
27. Read32 SDHCI_MAX_CURRENT register and read voltage options:
    1. If can do VDD=3.3V (caps⁰), pick out max_current_330 from MAX_CURRENT register (in mA). If >150mA set XPC bit for 3.3V.
    2. Same again for VDD=3.0V, 1.8V. Max current at 1.8V can be in steps of 800mA, 600mA, 400mA, 200mA.
    3. ocr_avail flags set as an OR of the voltages available: MMC_VDD_32_33 | MMC_VDD_33_34 for 3.3V, MMC_VDD_29_30 | MMC_VDD_30_31 for 3.0V, MMC_VDD_165_195 for 1.8V
    4. Make a note of all the voltages we can do for all cards, and for SDIO (only)
    5. If host has a list of voltages for SDIO, clear those not found in our new list
    6. If host has a list of voltages for SD, clear those not found in our new list. Normal SD controllers also don’t support 1.8V
    7. If host has a list of voltages for MMC, clear those not found in our new list
    8. If our list of voltages is empty, abort because hardware doesn’t say what it supports
28. If using ADMA or PIO, can do 128 scatter/gather segments. SDMA can only do one (ie no hardware scatter/gather support).
29. Max number of sectors in one transfer is 524288. Limited by DMA boundary size (512KiB)
30. Max segment size (with hardware scatter/gather, each segment can’t be >64KiB)
    1. 65535 if ADMA and SDHCI_QUIRK_BROKEN_ADMA_ZEROLEN_DESC
    2. 65536 if ADMA but not SDHCI_QUIRK_BROKEN_ADMA_ZEROLEN_DESC
    3. Max number of sectors (524288) otherwise
31. Max block size:
    1. 512<<2 if SDHCI_QUIRK_FORCE_BLK_SZ_2048
    2. Otherwise read from caps⁰ and shift left 512 by that value (eg caps⁰ field=1, block size = 512<<1 = 1024). If caps⁰ field >= 3 value doesn’t make sense, report an error and use 512 bytes. (So block size could be 512, 1024, 2048 only).
32. Max block count:
    1. 1 if SDHCI_QUIRK_NO_MULTIBLOCK
    2. 65535 otherwise
33. Initialise tasklets
34. Set up timers
35. If spec >= 3.00, initialise queues and re-tuning timer
36. Register interrupt service routine (sdhci_irq)
    1. If that failed, cancel the tasklets and exit
37. Set up voltage regulators
38. Call sdhci_init(hard reset)
39. Register a handler for the LED (if driven by GPIO and not the host controller)
40. Call mmiowb() (? something to do with memory mapped IO)
41. Call sdhci_enable_card_detection()
42. Return

Suspend/resume functions

• sdhci_suspend_host()
• sdhci_resume_host()
• sdhci_enable_irq_wakeups()
• sdhci_runtime_suspend_host()
• sdhci_runtime_resume_host()

Interrupt

• sdhci_irq(intmask)
• sdhci_cmd_irq(intmask)
• sdhci_show_adma_error(): debug printout in case of a DMA error

Timers/tasklets – complete

• sdhci_tuning_timer(): called on timer to say that we need to retune – just set a flag to note that
• sdhci_timeout_timer(): called on timeout timer – just abandon any operations if we were waiting for an interrupt that never happened – schedule a call to sdhci_tasklet_finish()
• sdhci_tasklet_finish(): tasklet for the end of a transfer (?). If SDHCI_QUIRK_RESET_AFTER_REQUEST, configure the clock with speed 0. Then send a reset with a command reset and a data reset [ sdhci_reset(SDHCI_RESET_CMD); sdhci_reset(SDHCI_RESET_DATA) ]. Spec says to send them together, but Ricoh controllers don’t like that.
• sdhci_tasklet_card(): called when a card insert/remove event happens. If read32 of SDHCI_PRESENT_STATE reg says that the card is not present (ie it was just removed) then abort any transfer in progress with an error and reset (same method as sdhci_tasklet_finish() )

Tuning

Requests

sdhci_request(command packet): callback from MMC layer to perform an SD command
(complete)

1. Activate the LED (if software LED control)
2. If Auto-CMD12 is enabled, don’t send STOP for non-SET_BLOCK_COUNTED requests
3. If SDHCI_QUIRK_BROKEN_CARD_DETECTION is set, assume the card is present, else read32 the SDHCI_PRESENT_STATE register and check there’s a card present
4. If no card, or our flag SDHCI_DEVICE_DEAD set, report an error of medium no present, schedule the finish tasklet
5. Check if the retuning timer has expired. If so, and there’s no ongoing data transfer, execute the tuning procedure (sdhci_execute_tuning()) before executing the command
6. If mrq→sbc (?) and don’t support Auto-CMD23, send the command packet mrq→sbc otherwise send the command packet we’re given, using sdhci_send_command()
7. mmiowb() (?) – no-op on ARM

sdhci_send_command(command packet)

(complete)

1. Set up a mask to use with reads from SDHCI_PRESENT_STATE register.
   1. Always set command inhibit
   2. Set data inhibit if the command packet data field is non-null, or has flags MMC_RSP_BUSY set
   3. Clear data inhibit if it’s a stop command
2. Poll read32s from SDHCI_PRESENT_STATE register and AND with our mask
   1. Each poll takes 1ms
   2. After 10ms timeout and complain that controller never released inhibit bit(s). Schedule the finish tasklet
3. Set up the host’s timer timeout to be ‘jiffies’ + 10*HZ
4. Call sdhci_prepare_data(command packet)
5. Write32 the command argument to the SDHCI_ARGUMENT register
6. Call sdhci_set_transfer_mode(command packet)
7. If command flags set for 136 bit MMC response and the card may send busy (MMC) then complain about an unsupported response type and schedule the finish tasklet
8. Set up command flags
   1. Response is either none, long (136 bits), short-busy or short
   2. If calling CMD19 (MMC_SEND_TUNING_BLOCK) then force Data Present Select
9. Combine the command and the flags into a command word (16 bits ccff), and write16 it to the SDHCI_COMMAND register