mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: add sdmmc and fatfs docs
This commit is contained in:
Ivan Grokhotkov
parent
44ce833d76
commit
47f4a09704
@ -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
|
||||
##
|
||||
|
||||
64
docs/api/fatfs.rst
Normal file
64
docs/api/fatfs.rst
Normal file
@ -0,0 +1,64 @@
|
||||
FAT Filesystem Support
|
||||
======================
|
||||
|
||||
ESP-IDF uses `FatFs <http://elm-chan.org/fsw/ff/00index_e.html>`_ 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
|
||||
|
||||
95
docs/api/sdmmc.rst
Normal file
95
docs/api/sdmmc.rst
Normal file
@ -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
|
||||
@ -110,11 +110,13 @@ Contents:
|
||||
I2C <api/i2c>
|
||||
Pulse Counter <api/pcnt>
|
||||
Sigma-delta Modulation <api/sigmadelta>
|
||||
SD/MMC <api/sdmmc>
|
||||
SPI Flash and Partition APIs <api/spi_flash>
|
||||
SPI Master API <api/spi_master>
|
||||
Logging <api/log>
|
||||
Non-Volatile Storage <api/nvs_flash>
|
||||
Virtual Filesystem <api/vfs>
|
||||
FAT Filesystem <api/fatfs>
|
||||
Ethernet <api/esp_eth>
|
||||
Interrupt Allocation <api/intr_alloc>
|
||||
Memory Allocation <api/mem_alloc>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user