From: Ivan Grokhotkov Date: Sun, 8 Jan 2017 20:09:09 +0000 (+0800) Subject: docs: add sdmmc and fatfs docs X-Git-Tag: v2.0-rc1~71^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=47f4a097049d74d6154c8dedda1850a4e99f45a2;p=esp-idf docs: add sdmmc and fatfs docs --- diff --git a/docs/Doxyfile b/docs/Doxyfile index 668ebaba02..7dbd1cc8d1 100755 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -32,7 +32,10 @@ INPUT = ../components/esp32/include/esp_wifi.h \ ../components/esp32/include/esp_heap_alloc_caps.h \ ../components/freertos/include/freertos/heap_regions.h \ ../components/esp32/include/esp_smartconfig.h \ - ../components/esp32/include/esp_deep_sleep.h + ../components/esp32/include/esp_deep_sleep.h \ + ../components/sdmmc/include/sdmmc_cmd.h \ + ../components/fatfs/src/esp_vfs_fat.h \ + ../components/fatfs/src/diskio.h ## Get warnings for functions that have no documentation for their parameters or return value ## diff --git a/docs/api/fatfs.rst b/docs/api/fatfs.rst new file mode 100644 index 0000000000..d2efc87abf --- /dev/null +++ b/docs/api/fatfs.rst @@ -0,0 +1,64 @@ +FAT Filesystem Support +====================== + +ESP-IDF uses `FatFs `_ library to work with FAT filesystems. FatFs library resides in ``fatfs`` component. Although it can be used directly, many of its features can be accessed via VFS using C standard library and POSIX APIs. + +Additionally, FatFs has been modified to support run-time pluggable disk IO layer. This allows mapping of FatFs drives to physical disks at run-time. + +Using FatFs with VFS +-------------------- + +``esp_vfs_fat.h`` header file defines functions to connect FatFs with VFS. ``esp_vfs_fat_register`` function allocates a ``FATFS`` structure, and registers a given path prefix in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. ``esp_vfs_fat_unregister`` function deletes the registration with VFS, and frees the ``FATFS`` structure. + +Most applications will use the following flow when working with ``esp_vfs_fat_`` functions: + +1. Call ``esp_vfs_fat_register``, specifying path prefix where the filesystem has to be mounted (e.g. ``"/sdcard"``), FatFs drive number, and a variable which will receive a pointer to ``FATFS`` structure. + +2. Call ``ff_diskio_register`` function to register disk IO driver for the drive number used in step 1. + +3. Call ``f_mount`` function (and optionally ``f_fdisk``, ``f_mkfs``) to mount the filesystem using the same drive number which was passed to ``esp_vfs_fat_register``. See FatFs documentation for more details. + +4. Call POSIX and C standard library functions to open, read, write, erase, copy files, etc. Use paths starting with the prefix passed to ``esp_vfs_register`` (such as ``"/sdcard/hello.txt"``). + +5. Optionally, call FatFs library functions directly. Use paths without a VFS prefix in this case (``"/hello.txt"``). + +6. Close all open files. + +7. Call ``f_mount`` function for the same drive number, with NULL ``FATFS*`` argument, to unmount the filesystem. + +8. Call ``ff_diskio_register`` with NULL ``ff_diskio_impl_t*`` argument and the same drive number. + +9. Call ``esp_vfs_fat_unregister`` to remove FatFs from VFS, and free the ``FATFS`` structure allocated on step 1. + +Convenience functions, ``esp_vfs_fat_sdmmc_mount`` and ``esp_vfs_fat_sdmmc_unmount``, which wrap these steps and also handle SD card initialization, are described in the next section. + +.. doxygenfunction:: esp_vfs_fat_register +.. doxygenfunction:: esp_vfs_fat_unregister + + +Using FatFs with VFS and SD cards +--------------------------------- + +``esp_vfs_fat.h`` header file also provides a convenience function to perform steps 1–3 and 7–9, and also handle SD card initialization: ``esp_vfs_fat_sdmmc_mount``. This function does only limited error handling. Developers are encouraged to look at its source code and incorporate more advanced versions into production applications. ``esp_vfs_fat_sdmmc_unmount`` function unmounts the filesystem and releases resources acquired by ``esp_vfs_fat_sdmmc_mount``. + +.. doxygenfunction:: esp_vfs_fat_sdmmc_mount + +.. doxygenstruct:: esp_vfs_fat_sdmmc_mount_config_t + :members: + +.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount + +FatFS disk IO layer +------------------- + +FatFs has been extended with an API to register disk IO driver at runtime. + +Implementation of disk IO functions for SD/MMC cards is provided. It can be registered for the given FatFs drive number using ``ff_diskio_register_sdmmc`` function. + +.. doxygenfunction:: ff_diskio_register + +.. doxygenstruct:: ff_diskio_impl_t + :members: + +.. doxygenfunction:: ff_diskio_register_sdmmc + diff --git a/docs/api/sdmmc.rst b/docs/api/sdmmc.rst new file mode 100644 index 0000000000..126be86576 --- /dev/null +++ b/docs/api/sdmmc.rst @@ -0,0 +1,95 @@ +SDMMC Host Peripheral +===================== + +Overview +-------- + +SDMMC peripheral supports SD and MMC memory cards and SDIO cards. SDMMC software builds on top of SDMMC driver and consists of the following parts: + +1. SDMMC host driver (``driver/sdmmc_host.h``) — this driver provides APIs to send commands to the slave device(s), send and receive data, and handling error conditions on the bus. + +2. SDMMC protocol layer (``sdmmc_cmd.h``) — this component handles specifics of SD protocol such as card initialization and data transfer commands. Despite the name, only SD (SDSC/SDHC/SDXC) cards are supported at the moment. Support for MCC/eMMC cards can be added in the future. + +Protocol layer works with the host via ``sdmmc_host_t`` structure. This structure contains pointers to various functions of the host. This design makes it possible to implement an SD host using SPI interface later. + +Application Example +------------------- + +An example which combines SDMMC driver with FATFS library is provided in ``examples/24_sd_card`` directory. This example initializes the card, writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information. + + +Protocol layer APIs +------------------- + +Protocol layer is given ``sdmmc_host_t`` structure which describes the SD/MMC host driver, lists its capabilites, and provides pointers to functions of the driver. Protocol layer stores card-specific information in ``sdmmc_card_t`` structure. When sending commands to the SD/MMC host driver, protocol layer uses ``sdmmc_command_t`` structure to describe the command, argument, expected return value, and data to transfer, if any. + +Normal usage of the protocol layer is as follows: + +1. Call the host driver functions to initialize the host (e.g. ``sdmmc_host_init``, ``sdmmc_host_init_slot``). +2. Call ``sdmmc_card_init`` to initialize the card, passing it host driver information (``host``) and a pointer to ``sdmmc_card_t`` structure which will be filled in (``card``). +3. To read and write sectors of the card, use ``sdmmc_read_sectors`` and ``sdmmc_write_sectors``, passing the pointer to card information structure (``card``). +4. When card is not used anymore, call the host driver function to disable SDMMC host peripheral and free resources allocated by the driver (e.g. ``sdmmc_host_deinit``). + +Most applications need to use the protocol layer only in one task; therefore the protocol layer doesn't implement any kind of locking on the ``sdmmc_card_t`` structure, or when accessing SDMMC host driver. Such locking has to be implemented in the higher layer, if necessary (e.g. in the filesystem driver). + +.. doxygenstruct:: sdmmc_host_t + :members: + +.. doxygendefine:: SDMMC_HOST_FLAG_1BIT +.. doxygendefine:: SDMMC_HOST_FLAG_4BIT +.. doxygendefine:: SDMMC_HOST_FLAG_8BIT +.. doxygendefine:: SDMMC_HOST_FLAG_SPI +.. doxygendefine:: SDMMC_FREQ_DEFAULT +.. doxygendefine:: SDMMC_FREQ_HIGHSPEED +.. doxygendefine:: SDMMC_FREQ_PROBING + +.. doxygenstruct:: sdmmc_command_t + :members: + +.. doxygenstruct:: sdmmc_card_t + :members: + +.. doxygenstruct:: sdmmc_csd_t + :members: + +.. doxygenstruct:: sdmmc_cid_t + :members: + +.. doxygenstruct:: sdmmc_scr_t + :members: + +.. doxygenfunction:: sdmmc_card_init +.. doxygenfunction:: sdmmc_write_sectors +.. doxygenfunction:: sdmmc_read_sectors + +SDMMC host driver APIs +---------------------- + +On the ESP32, SDMMC host peripheral has two slots: + +- Slot 0 (``SDMMC_HOST_SLOT_0``) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX. +- Slot 1 (``SDMMC_HOST_SLOT_1``) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX. + +Card Detect and Write Protect signals can be routed to arbitrary pins using GPIO matrix. To use these pins, set ``gpio_cd`` and ``gpio_wp`` members of ``sdmmc_slot_config_t`` structure when calling ``sdmmc_host_init_slot``. + +Of all the funtions listed below, only ``sdmmc_host_init``, ``sdmmc_host_init_slot``, and ``sdmmc_host_deinit`` will be used directly by most applications. Other functions, such as ``sdmmc_host_set_bus_width``, ``sdmmc_host_set_card_clk``, and ``sdmmc_host_do_transaction`` will be called by the SD/MMC protocol layer via function pointers in ``sdmmc_host_t`` structure. + +.. doxygenfunction:: sdmmc_host_init + +.. doxygendefine:: SDMMC_HOST_SLOT_0 +.. doxygendefine:: SDMMC_HOST_SLOT_1 +.. doxygendefine:: SDMMC_HOST_DEFAULT + +.. doxygenfunction:: sdmmc_host_init_slot + +.. doxygenstruct:: sdmmc_slot_config_t + :members: + +.. doxygendefine:: SDMMC_SLOT_NO_CD +.. doxygendefine:: SDMMC_SLOT_NO_WP +.. doxygendefine:: SDMMC_SLOT_CONFIG_DEFAULT + +.. doxygenfunction:: sdmmc_host_set_bus_width +.. doxygenfunction:: sdmmc_host_set_card_clk +.. doxygenfunction:: sdmmc_host_do_transaction +.. doxygenfunction:: sdmmc_host_deinit diff --git a/docs/index.rst b/docs/index.rst index 3161db345b..2d9a62f14b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -110,11 +110,13 @@ Contents: I2C Pulse Counter Sigma-delta Modulation + SD/MMC SPI Flash and Partition APIs SPI Master API Logging Non-Volatile Storage Virtual Filesystem + FAT Filesystem Ethernet Interrupt Allocation Memory Allocation