SD/eMMC Driver for Hard Processor System¶
Last updated: May 14, 2026
Upstream Status: Upstreamed
Devices supported: Agilex™ 3, Agilex™ 5
Introduction¶
The Secure Digital/Embedded Multimedia Card (SD/eMMC) driver supports the SD/eMMC controller in the Hard Processor System (HPS) which interfaces with external SD Flash cards, secure digital I/O (SDIO) devices, and eMMC storage devices.
For More information please refer to the Altera® Agilex™ 5 Hard Processor System Technical Reference Manual.
Driver Sources¶
The source code for this driver can be found at:
Driver Capabilities¶
- Manage SD/eMMC features such as configuration and reset and timeout clock frequency
- Supports SDMA and ADMA modes.
- Handles data transfer to/from the SD/eMMC.
Kernel Configurations¶
CONFIG_MMC_SDHCI_CADENCE
Symbol: MMC_SDHCI_CADENCE [=y]
Type : tristate
Defined at drivers/mmc/host/Kconfig:291
Prompt: SDHCI support for the Cadence SD/SDIO/eMMC controller
Depends on: MMC [=y] && MMC_SDHCI_PLTFM [=y] && OF [=y]
Location:
-> Device Drivers?
-> MMC/SD/SDIO card support (MMC [=y])
-> Secure Digital Host Controller Interface support (MMC_SDHCI
-> SDHCI platform and OF driver helper (MMC_SDHCI_PLTFM [=y])
(1) -> SDHCI support for the Cadence SD/SDIO/eMMC controller (M
Selects: MMC_SDHCI_IO_ACCESSORS [=y]
Device Tree¶
Example Device tree location to configure the SD/eMMC:
Agilex™ 5
- For SD Card: https://github.com/altera-fpga/linux-socfpga/blob/socfpga-6.18.2-lts/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk.dts
- For eMMC: https://github.com/altera-fpga/linux-socfpga/blob/socfpga-6.18.2-lts/arch/arm64/boot/dts/intel/socfpga_agilex5_socdk_emmc.dts
Agilex™ 3
- For SD Card: https://github.com/altera-fpga/linux-socfpga/blob/socfpga-6.18.2-lts/arch/arm64/boot/dts/intel/socfpga_agilex3_socdk.dts
- For eMMC: https://github.com/altera-fpga/linux-socfpga/blob/socfpga-6.18.2-lts/arch/arm64/boot/dts/intel/socfpga_agilex3_socdk_emmc.dts
Device Tree Configuration for Supported Operations Modes¶
Linux Device Tree Configuration for SD Card
| Operation Mode ➜ Parameter ↓ |
High Speed | SDR12 | SDR25 | SDR50 | DDR50² | SDR104³ |
|---|---|---|---|---|---|---|
| sdhci-caps⁴ | <0x00000000 0x0000c800> |
<0x00000000 <0x0000c800> |
<0x00000000 0x0000c800> |
<0x00000000 0x0000c800> |
<0x00000000 0x0000c800> |
<0x00000000 0x0000c800> |
| sdhci-caps-mask⁴ | <0x00002007 0x0000ff00> |
<0x00002007 0x0000ff00> |
<0x00002007 0x0000ff00> |
<0x00002006 0x0000ff00> |
<0x00002003 0x0000ff00> |
<0x00002000 0x0000ff00> |
| sd-uhs-sdr12 | No | Yes | No | No | No | No |
| sd-uhs-sdr25 | No | No | Yes | No | No | No |
| sd-uhs-sdr50 | No | No | No | Yes | No | No |
| sd-uhs-ddr50 | No | No | No | No | Yes | No |
| sd-uhs-sdr104 | No | No | No | No | No | Yes |
| bus-width | 1,4 | 4 | 4 | 4 | 4 | 4 |
| cap-sd-highspeed | Yes | No | Yes | Yes | Yes | Yes |
| max-frequency¹ | 200000000 Min: 50 MHz |
200000000 Min: 25 MHz |
200000000 Min: 50 MHz |
200000000 Min: 100 MHz |
200000000 Min: 50 MHz |
200000000 |
| no-sd | No | No | No | No | No | No |
| no-sdio | No | No | No | No | No | No |
| non-removable | No | No | No | No | No | No |
| cap-mmc-highspeed | No | No | No | No | No | No |
| mmc-hs200-1_8v | No | No | No | No | No | No |
| mmc-hs400-1_8v | No | No | No | No | No | No |
| no-mmc | Yes | Yes | Yes | Yes | Yes | Yes |
| no-1-8-v | Yes | No | No | No | No | No |
¹ The frequency should be at least the minimum value provided in Min value.
² This mode may not be functional. Please refer to the Known Issues section for more details.
³ This mode may not be functional in Agilex™ 5 ES device. Please refer to the Known Issues section for more details.
⁴ The sdhci-caps and sdhci-caps-mask device tree parameters are used to override the value of the SRS16 and SRS17 capabilities registers in the SD/eMMC controller. The clock frequency value defined in SRS16.BSDCLK or the overridden value set by sdhci-caps/sdhci-caps-mask parameters MUST match the value defined for the SOFT PHY clock in the hardware design hence this is used as reference to calculate the clock divider value needed to get final clock frequency for the operation mode selected. In Agilex 5 Engineering Samples the SRS16.BSDCLK value is set to 50 MHz, so this value must be overridden with the sdhci-caps/sdhci-caps-mask parameters if wanted to run at higher frequency. In the Agilex 5 production silicon, the SRS16.BSDCLK value is set to 200 MHz, so if your project needs to run at a different frequency, this value must be also overridden with the sdhci-caps/sdhci-caps-mask parameters.
Linux Device Tree Configuration for eMMC
| Operation Mode ➜ Parameter ↓ |
High Speed | HS-200² | HS-400² |
|---|---|---|---|
| sdhci-caps³ | <0x00000000 0x0000c800> |
<0x00000000 0x0000c800> |
<0x00000000 0x0000c800> |
| sdhci-caps-mask³ | <0x00002000 0x0000ff00> |
<0x00002000 0x0000ff00> |
<0x00002000 0x0000ff00> |
| bus-width | 4,8 | 4,8 | 8 |
| max-frequency¹ | 200000000 Min: 50 MHz |
200000000 | 200000000 |
| cap-sd-highspeed | No | No | No |
| no-sd | Yes | Yes | Yes |
| no-sdio | Yes | Yes | Yes |
| non-removable | Yes | Yes | Yes |
| cap-mmc-highspeed | Yes | Yes | Yes |
| mmc-hs200-1_8v | No | Yes | No |
| mmc-hs400-1_8v | No | No | Yes |
| no-mmc | No | No | No |
| no-1-8-v | Yes | No | No |
¹ The frequency should be at least the minimum value provided in Min value.
² This mode may not be functional in Agilex™ 5 ES device. Please refer to the Known Issues section for more details.
³ The sdhci-caps and sdhci-caps-mask device tree parameters are used to override the value of the SRS16 and SRS17 capabilities registers in the SD/eMMC controller. The clock frequency value defined in SRS16.BSDCLK or the overridden value set by sdhci-caps/sdhci-caps-mask parameters MUST match the value defined for the SOFT PHY clock in the hardware design hence this is used as reference to calculate the clock divider value needed to get final clock frequency for the operation mode selected. In Agilex 5 Engineering Samples the SRS16.BSDCLK value is set to 50 MHz, so this value must be overridden with the sdhci-caps/sdhci-caps-mask parameters if wanted to run at higher frequency. In the Agilex 5 production silicon, the SRS16.BSDCLK value is set to 200 MHz, so if your project needs to run at a different frequency, this value must be also overridden with the sdhci-caps/sdhci-caps-mask parameters.
The Linux SD/eMMC driver allow you to provide the PHY timing values that your board requires. These are defined through device tree parameters. In case these are not defined, the default values are being used instead. The following table describes these parameters:
| Parameter | Description | Default value |
|---|---|---|
| cdns,iocell-input-delay | Input delay across IO cells in picoseconds | SDHCI_CDNS6_PHY_DEFAULT_IOCELL_DELAY 2500 |
| cdns,iocell-output-delay | Output delay across IO cells in picoseconds | SDHCI_CDNS6_PHY_DEFAULT_IOCELL_DELAY 2500 |
| cdns,delay-element | Delay element size in picoseconds | SDHCI_CDNS6_PHY_DEFAULT_DELAY_ELEMENT 24 |
Note: The Linux driver uses the above parameters to calculate the PHY timing values that need to be programmed in the Combo PHY registers.
U-Boot Configuration for some SD/eMMC Operation Modes
The following device trees and Config U-Boot files are the ones that define the operation mode as indicated in the following table:
Agilex™ 5
* CONFIG for SDCard: https://github.com/altera-fpga/u-boot-socfpga/blob/socfpga_v2026.01/configs/socfpga_agilex5_defconfig * CONFIG for eMMC: https://github.com/altera-fpga/u-boot-socfpga/blob/socfpga_v2026.01/configs/socfpga_agilex5_emmc_defconfig * Device Tree for SDCard: https://github.com/altera-fpga/u-boot-socfpga/blob/socfpga_v2026.01/arch/arm/dts/socfpga_agilex5_socdk-u-boot.dtsi * Device Tree for eMMC: https://github.com/altera-fpga/u-boot-socfpga/blob/socfpga_v2026.01/arch/arm/dts/socfpga_agilex5_socdk_emmc-u-boot.dtsi
Agilex™ 3
* CONFIG for SDCard: https://github.com/altera-fpga/u-boot-socfpga/blob/socfpga_v2026.01/configs/socfpga_agilex3_defconfig
* Device Tree for SDCard: https://github.com/altera-fpga/u-boot-socfpga/blob/socfpga_v2026.01/arch/arm/dts/socfpga_agilex3_socdk-u-boot.dtsi
The next table shows some U-Boot configurations that allow the SD/eMMC controller to operate in a specific mode:
| Operation Mode ➜ Configuration ↓ |
SD High Speed | SD SDR12² | SD SDR104³ | eMMC High Speed | eMMC HS-200² | eMMC HS-400² |
|---|---|---|---|---|---|---|
| sdhci-caps⁴ | <0x00000000 0x0000c800> |
<0x00000000 0x0000c800> |
<0x00000000 0x0000c800> |
<0x00000000 0x0004c800> |
<0x00000000 0x0004c800> |
<0x00000000 0x0004c800> |
| sdhci-caps-mask⁴ | <0x00002007 0x0000ff00> |
<0x00002007 0x0000ff00> |
<0x00002000 0x0000ff00> |
<0x00000000 0x0004ff00> |
<0x00000000 0x0004ff00> |
<0x00000000 0x0004ff00> |
| cap-sd-highspeed | Yes | No | Yes | No | No | No |
| sd-uhs-sdr12 | No | Yes | No | No | No | No |
| sd-uhs-sdr104 | No | No | Yes | No | No | No |
| max-frequency¹ | 200000000 Min 50 MHz |
200000000 Min 25 MHz |
200000000 | 200000000 Min 50 MHz |
200000000 | 200000000 |
| bus-width | 4 | 4 | 4 | 4,8 | 4,8 | 8 |
| no-sd | No | No | No | Yes | Yes | Yes |
| no-sdio | No | No | No | Yes | Yes | Yes |
| non-removable | No | No | No | Yes | Yes | Yes |
| cap-mmc-highspeed | No | No | No | Yes | Yes | Yes |
| mmc-hs200-1_8v | No | No | No | No | Yes | No |
| mmc-hs400-1_8v | No | No | No | No | No | Yes |
| no-mmc | Yes | Yes | Yes | No | No | No |
| no-1-8-v | Yes | No | No | Yes | No | No |
| U-Boot Configs CONFIG_SPL_DM_REGULATOR_GPIO CONFIG_DM_REGULATOR_GPIO CONFIG_SPL_MMC_UHS_SUPPORT CONFIG_MMC_UHS_SUPPORT CONFIG_SPL_DWAPB_GPIO CONFIG_MMC_HS200_SUPPORT CONFIG_SPL_MMC_HS200_SUPPORT CONFIG_MMC_HS400_SUPPORT CONFIG_SPL_MMC_HS400_SUPPORT |
y y y y y n n n n |
y y y y y n n n n |
y y y y y n n n n |
n n n n n n n n n |
n n n n n y y n n |
n n n n n y y y y |
¹ The frequency should be at least the minimum value provided in Min value.
² This configuration requires a temporary workaroud the driver source code. Please refer to the Known Issues section for more details.
³ This mode may not be functional in Agilex™ 5 ES device. Please refer to the Known Issues section for more details.
⁴ The sdhci-caps and sdhci-caps-mask device tree parameters are used to override the value of the SRS16 and SRS17 capabilities registers in the SD/eMMC controller. The clock frequency value defined in SRS16.BSDCLK or the overridden value set by sdhci-caps/sdhci-caps-mask parameters MUST match the value defined for the SOFT PHY clock in the hardware design hence this is used as reference to calculate the clock divider value needed to get final clock frequency for the operation mode selected. In Agilex 5 Engineering Samples the SRS16.BSDCLK value is set to 50 MHz, so this value must be overridden with the sdhci-caps/sdhci-caps-mask parameters if wanted to run at higher frequency. In the Agilex 5 production silicon, the SRS16.BSDCLK value is set to 200 MHz, so if your project needs to run at a different frequency, this value must be also overridden with the sdhci-caps/sdhci-caps-mask parameters.
Note: The PHY parameters defined in the device tree, were calculated to match the clock configuration in the GHRD (which uses a SOFT PHY clock of 200 MHz). For any other SOFT PHY clock frequency, the parameters need to be adjusted.
Test Procedures¶
In Linux you can find out what is the current operation mode and the SM/eMMC configuration by inspecting the /sys/kernel/debug/mmc0/ios file as shown next:
root@agilex5_dk_a5e065bb32aes1:~# cat /sys/kernel/debug/mmc0/ios
clock: 200000000 Hz
actual clock: 200000000 Hz
vdd: 21 (3.3 ~ 3.4 V)
bus mode: 2 (push-pull)
chip select: 0 (don't care)
power mode: 2 (on)
bus width: 3 (8 bits)
timing spec: 10 (mmc HS400)
signal voltage: 1 (1.80 V)
driver type: 0 (driver type B)
In U-Boot you can also find out the current operation mode using the mmc info command:
SOCFPGA_AGILEX5 # mmc info
Device: mmc0@10808000
Manufacturer ID: 13
OEM: 4e
Name: G1M15L
Bus Speed: 200000000
Mode: HS400 (200MHz)
Rd Block Len: 512
MMC version 5.1
High Capacity: Yes
Capacity: 29.6 GiB
Bus Width: 8-bit DDR
Erase Group Size: 512 KiB
HC WP Group Size: 8 MiB
User Capacity: 29.6 GiB WRREL
Boot Capacity: 31.5 MiB ENH
RPMB Capacity: 4 MiB ENH
Boot area 0 is not write protected
Boot area 1 is not write protected
Note: To observe the SD/eMMC operation mode from the Mode field above, you need to use set CONFIG_MMC_VERBOSE=y in your config.
In Linux, if the file system is stored in the SD Card or eMMC device, then the content of this can be accessed directly by navigating in the directory structure of the file system.
In U-Boot you can also use the mmc command to read and write from the SD Card or eMMC device. For example:
SOCFPGA_AGILEX5 # mmc rescan
SOCFPGA_AGILEX5 # mmc list
mmc0@10808000: 0 (eMMC)
SOCFPGA_AGILEX5 # mmc part
Partition Map for mmc device 0 -- Partition Type: DOS
Part Start Sector Num Sectors UUID Type
1 2048 131073 af519e93-01 0b
2 133121 131073 af519e93-02 83
# Read 5000 bytes from block 2048 and load it into memory
SOCFPGA_AGILEX5 # mmc read ${loadaddr} 2048 5000
MMC read: dev # 0, block # 8264, count 20480 ... 20480 blocks read: OK
Note: If you have a FAT partition in your device, you can also access the content of this using the fatinfo, fatload, fatls, fatmkdir, fatrm, fatsize, fatwrite commands.
Known Issues¶
- SD Card DDR50 mode is not functional in Agilex™ 5 and Agilex™ 3 device due to CRC errors observed in the SD Card interface. Please refer to the 350306 KDB.
- Agilex 5 ES (Engineering Sample) fails to boot from SD Card and eMMC devices operating in SDR104, HS400 and HS200 modes. Please refer to the 350691 KDB.
- SD Card SDR12 mode in U-Boot requires a driver source code workaround in 26.1 release. Please refer to the 351127 KDB.
Notices & Disclaimers¶
Altera® Corporation technologies may require enabled hardware, software or service activation. No product or component can be absolutely secure. Performance varies by use, configuration and other factors. Your costs and results may vary. You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Altera or Intel products described herein. You agree to grant Altera Corporation a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein. No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document, with the sole exception that you may publish an unmodified copy. You may create software implementations based on this document and in compliance with the foregoing that are intended to execute on the Altera or Intel product(s) referenced in this document. No rights are granted to create modifications or derivatives of this document. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Altera disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade. You are responsible for safety of the overall system, including compliance with applicable safety-related requirements or standards. © Altera Corporation. Altera, the Altera logo, and other Altera marks are trademarks of Altera Corporation. Other names and brands may be claimed as the property of others.
OpenCL* and the OpenCL* logo are trademarks of Apple Inc. used by permission of the Khronos Group™.
Created: May 25, 2024