micropython · nickovs · May 5, 2019 · May 5, 2019 · May 9, 2019 · May 9, 2019
diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst
@@ -1,8 +1,8 @@
 .. currentmodule:: machine
 .. _machine.SD:
 
-class SD -- secure digital memory card
-======================================
+class SD -- secure digital memory card (cc3200 port only)
+=========================================================
 
 .. warning::
 

diff --git a/docs/library/machine.SDCard.rst b/docs/library/machine.SDCard.rst
@@ -0,0 +1,133 @@
+.. currentmodule:: machine
+.. _machine.SDCard:
+
+
+
+class SDCard -- secure digital memory card
+==========================================
+
+SD cards are one of the most common small form factor removable storage media.
+SD cards come in a variety of sizes and phsyical form factors. MMC cards are
+similar removable storage devices while eMMC devices are electically similar
+storage devices designed to be embedded into other systems. All three form
+share a common protocol for communication with their host system and high-level
+support looks the same for them all. As such in micropython they are implemented
+in a single class called :class:`machine.SDCard` .
+
+Both SD and MMC interfaces support being accessed with a variety of bus widths.
+When being accessed with a 1-bit wide interface they can be accessed using the
+SPI protocol. Different micropython hardware platforms support different widths
+and pin configurations but for most platforms there is a standard configuation
+for any given hardware. In general constructing an `SDCard`` object with without
+passing any parameters will initialise the interface to the default card slot
+for the current hardware. The arguments listed below represent the common
+arguments that might need to be set in order to use either a non-stanard slot
+or a non-standard pin assignment. The exact subset of arguments suported will
+vary from platform to platform.
+
+
+.. class:: SDCard(slot=1, width=1, cd=None, wp=None, sck=None, miso=None, mosi=None, cs=None)
+
+    This class provides access to SD or MMC storage cards using either
+    the ESP32's dedicated SD/MMC interface hardware or through an SPI
+    channel using DMA for the data transfers. The class implements
+    that block protocol defined in the :class:`uos.AbstractBlockDev`
+    class. This allows the mounting of an SD card to be as simple as::
+
+      uos.mount(storage.SDCard(), "/sd")
+
+    The constrcutor takes the following paramters:
+
+     - ``slot`` selects which of the available interfaces to use. Leaving this
+       unset will select the default interface.
+
+     - ``width`` selects the bus width for the SD/MMC interface. 
+
+     - ``cd`` can be used to specify a card-detect pin.
+
+     - ``wp`` can be used to specify a write-protect pin.
+
+     - ``sck`` can be used to specify an SPI clock pin.
+
+     - ``miso`` can be used to specify an SPI miso pin.
+
+     - ``mosi`` can be used to specify an SPI mosi pin.
+
+     - ``cs`` can be used to specify an SPI chip select pin.
+
+
+
+Implementation-specific details
+-------------------------------
+
+Different implementations of the ``SDCard`` class on different hardware support
+varying subsets of the options above.
+
+PyBoard
+```````
+
+The standard PyBoard has just one slot. No arguments are necessary or supported.
+
+ESP32
+`````
+
+The ESP32 provides two channels of SD/MMC hardware and also supports
+access to SD Cards through either of the two SPI ports that are
+generally available to the user. As a result the ``slot`` argument can
+take a value between 0 and 3, inclusive. Slots 0 and 1 use the
+built-in SD/MMC hardware while slots 2 and 3 use the SPI ports. Slot 0
+supports 1, 4 or 8-bit wide access while slot 1 supports 1 or 4-bit
+access; the SPI slots only support 1-bit access.
+
+  .. note:: Slot 0 is used to communicate with on-board flash memory
+            on most ESP32 modules and so will be unavailable to the
+            user.
+
+  .. note:: Most ESP32 modules that provide an SD card slot using the
+            dedicated hardware only wire up 1 data pin, so the default
+            value for ``width`` is 1.
+
+The pins used by the dedicated SD/MMC hardware are fixed. The pins
+used by the SPI hardware can be reassigned.
+
+  .. note:: If any of the SPI signals are remapped then all of the SPI
+            signals will pass through a GPIO multiplexer unit which
+            can limit the performance of high frequency signals. Since
+            the normal operating speed for SD cards is 40MHz this can
+            cause problems on some cards.
+
+The default (and preferred) pin assignment are as follows:
+
+    ====== ====== ====== ====== ======
+    Slot   0      1      2      3
+    ------ ------ ------ ------ ------
+    Signal   Pin    Pin    Pin    Pin
+    ====== ====== ====== ====== ======
+    sck       6     14     18     14
+    cmd      11     15
+    cs                      5     15
+    miso                   19     12
+    mosi                   23     13
+    D0        7      2
+    D1        8      4
+    D2        9     12
+    D3       10     13
+    D4       16
+    D5       17
+    D6        5
+    D7       18
+    ====== ====== ====== ====== ======
+
+
+
+cc3200
+``````
+
+You can set the pins used for SPI access by passing a tuple as the
+``pins`` argument.
+
+*Note:* The current cc3200 SD card implementation names the this class
+:class:`machine.SD` rather than :class:`machine.SDCard` .
+
+
+
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
@@ -168,3 +168,4 @@ Classes
    machine.Timer.rst
    machine.WDT.rst
    machine.SD.rst
+   machine.SDCard.rst
diff --git a/ports/esp32/Makefile b/ports/esp32/Makefile
@@ -111,6 +111,7 @@ INC_ESPCOMP += -I$(ESPCOMP)/app_trace/include
 INC_ESPCOMP += -I$(ESPCOMP)/app_update/include
 INC_ESPCOMP += -I$(ESPCOMP)/pthread/include
 INC_ESPCOMP += -I$(ESPCOMP)/smartconfig_ack/include
+INC_ESPCOMP += -I$(ESPCOMP)/sdmmc/include
 
 # these flags are common to C and C++ compilation
 CFLAGS_COMMON = -Os -ffunction-sections -fdata-sections -fstrict-volatile-bitfields \
@@ -192,6 +193,7 @@ SRC_C = \
 	machine_wdt.c \
 	mpthreadport.c \
 	machine_rtc.c \
+	machine_sdcard.c \
 	$(SRC_MOD)
 
 EXTMOD_SRC_C = $(addprefix extmod/,\
@@ -665,6 +667,26 @@ ESPIDF_WPA_SUPPLICANT_O = $(addprefix $(ESPCOMP)/wpa_supplicant/,\
 	port/os_xtensa.o \
 	)
 
+ESPIDF_SDMMC_O = $(addprefix $(ESPCOMP)/sdmmc/,\
+	sdmmc_cmd.o \
+	sdmmc_common.o \
+	sdmmc_init.o \
+	sdmmc_mmc.o \
+	sdmmc_sd.o \
+	sdmmc_io.o \
+	) \
+	$(addprefix $(ESPCOMP)/driver/,\
+	sdmmc_host.o \
+	sdmmc_transaction.o \
+	sdspi_host.o \
+	sdspi_transaction.o \
+	sdspi_crc.o \
+	) \
+	$(addprefix $(ESPCOMP)/soc/,\
+	esp32/sdmmc_periph.o \
+	)
+
+
 OBJ_ESPIDF =
 OBJ_ESPIDF += $(addprefix $(BUILD)/, $(ESPIDF_NEWLIB_O))
 OBJ_ESPIDF += $(addprefix $(BUILD)/, $(ESPIDF_DRIVER_O))
@@ -693,6 +715,7 @@ OBJ_ESPIDF += $(addprefix $(BUILD)/, $(ESPIDF_SMARTCONFIG_ACK_O))
 OBJ_ESPIDF += $(addprefix $(BUILD)/, $(ESPIDF_SPI_FLASH_O))
 OBJ_ESPIDF += $(addprefix $(BUILD)/, $(ESPIDF_ULP_O))
 OBJ_ESPIDF += $(addprefix $(BUILD)/, $(ESPIDF_WPA_SUPPLICANT_O))
+OBJ_ESPIDF += $(addprefix $(BUILD)/, $(ESPIDF_SDMMC_O))
 
 $(OBJ_ESPIDF): $(SDKCONFIG_H)
 
@@ -723,6 +746,7 @@ LIB_ESPIDF += ulp
 LIB_ESPIDF += lwip
 LIB_ESPIDF += mbedtls
 LIB_ESPIDF += wpa_supplicant
+LIB_ESPIDF += sdmmc
 
 BUILD_ESPIDF_LIB = $(BUILD)/esp-idf
 
@@ -763,6 +787,7 @@ $(eval $(call gen_espidf_lib_rule,ulp,$(ESPIDF_ULP_O)))
 $(eval $(call gen_espidf_lib_rule,lwip,$(ESPIDF_LWIP_O)))
 $(eval $(call gen_espidf_lib_rule,mbedtls,$(ESPIDF_MBEDTLS_O)))
 $(eval $(call gen_espidf_lib_rule,wpa_supplicant,$(ESPIDF_WPA_SUPPLICANT_O)))
+$(eval $(call gen_espidf_lib_rule,sdmmc,$(ESPIDF_SDMMC_O)))
 
 LIB = $(foreach lib,$(LIB_ESPIDF),$(BUILD_ESPIDF_LIB)/$(lib)/lib$(lib).a)