mirror of
https://github.com/espressif/esp-idf.git
synced 2026-05-05 04:15:21 +02:00
Moved files into separate folders per 'en' and 'zh_CN' language version and linked 'zh_CN' files back to 'en' files if translation is not yet available
This commit is contained in:
krzychb
@@ -0,0 +1,60 @@
|
||||
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_path`` 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"``, ``"/spiflash"``), 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_path`` with the path where the file system is mounted 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_path
|
||||
|
||||
|
||||
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_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
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
Storage API
|
||||
***********
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
SPI Flash and Partition APIs <spi_flash>
|
||||
SD/MMC Card Host <sdmmc>
|
||||
Non-Volatile Storage <nvs_flash>
|
||||
Virtual Filesystem <vfs>
|
||||
FAT Filesystem <fatfs>
|
||||
Wear Levelling <wear-levelling>
|
||||
SPIFFS Filesystem <spiffs>
|
||||
|
||||
|
||||
Example code for this API section is provided in :example:`storage` directory of ESP-IDF examples.
|
||||
@@ -0,0 +1,33 @@
|
||||
.. include:: ../../../../components/nvs_flash/README.rst
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Two examples are provided in :example:`storage` directory of ESP-IDF examples:
|
||||
|
||||
:example:`storage/nvs_rw_value`
|
||||
|
||||
Demonstrates how to read and write a single integer value using NVS.
|
||||
|
||||
The value holds the number of ESP32 module restarts. Since it is written to NVS, the value is preserved between restarts.
|
||||
|
||||
Example also shows how to check if read / write operation was successful, or certain value is not initialized in NVS. Diagnostic is provided in plain text to help track program flow and capture any issues on the way.
|
||||
|
||||
:example:`storage/nvs_rw_blob`
|
||||
|
||||
Demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP32 module restarts.
|
||||
|
||||
* value - tracks number of ESP32 module soft and hard restarts.
|
||||
* blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. New run time is added to the table on each manually triggered soft restart and written back to NVS. Triggering is done by pulling down GPIO0.
|
||||
|
||||
Example also shows how to implement diagnostics if read / write operation was successful.
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/nvs_flash.inc
|
||||
|
||||
.. include:: /_build/inc/nvs.inc
|
||||
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
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.
|
||||
|
||||
In addition to SDMMC Host peripheral, ESP32 has SPI peripherals which can also be used to work with SD cards. This is supported using a variant of the host driver, ``driver/sdspi_host.h``. This driver has the same interface as SDMMC host driver, and the protocol layer can use either of two.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
An example which combines SDMMC driver with FATFS library is provided in ``examples/storage/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
|
||||
.. doxygendefine:: SDMMC_SLOT_WIDTH_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
|
||||
|
||||
SD SPI driver APIs
|
||||
------------------
|
||||
|
||||
SPI controllers accessible via spi_master driver (HSPI, VSPI) can be used to work with SD cards. In SPI mode, SD driver has lower throughput than in 1-line SD mode. However SPI mode makes pin selection more flexible, as SPI peripheral can be connected to any ESP32 pins using GPIO Matrix. SD SPI driver uses software controlled CS signal. Currently SD SPI driver assumes that it can use the SPI controller exclusively, so applications which need to share SPI bus between SD cards and other peripherals need to make sure that SD card and other devices are not used at the same time from different tasks.
|
||||
|
||||
SD SPI driver is represented using an ``sdmmc_host_t`` structure initialized using ``SDSPI_HOST_DEFAULT`` macro. For slot initialization, ``SDSPI_SLOT_CONFIG_DEFAULT`` can be used to fill in default pin mapping, which is the same as the pin mapping in SD mode.
|
||||
|
||||
SD SPI driver APIs are very similar to SDMMC host APIs. As with the SDMMC host driver, only ``sdspi_host_init``, ``sdspi_host_init_slot``, and ``sdspi_host_deinit`` functions are normally used by the applications. Other functions are called by the protocol level driver via function pointers in ``sdmmc_host_t`` structure.
|
||||
|
||||
.. note:
|
||||
|
||||
SD over SPI does not support speeds above SDMMC_FREQ_DEFAULT due to a limitation of SPI driver.
|
||||
|
||||
|
||||
.. doxygenfunction:: sdspi_host_init
|
||||
|
||||
.. doxygendefine:: SDSPI_HOST_DEFAULT
|
||||
|
||||
.. doxygenfunction:: sdspi_host_init_slot
|
||||
|
||||
.. doxygenstruct:: sdspi_slot_config_t
|
||||
:members:
|
||||
|
||||
.. doxygendefine:: SDSPI_SLOT_NO_CD
|
||||
.. doxygendefine:: SDSPI_SLOT_NO_WP
|
||||
.. doxygendefine:: SDSPI_SLOT_CONFIG_DEFAULT
|
||||
|
||||
.. doxygenfunction:: sdspi_host_set_card_clk
|
||||
.. doxygenfunction:: sdspi_host_do_transaction
|
||||
.. doxygenfunction:: sdspi_host_deinit
|
||||
@@ -0,0 +1,61 @@
|
||||
.. include:: ../../../../components/spi_flash/README.rst
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
|
||||
- :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating app firmware stored in flash.
|
||||
- :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small items of data in SPI flash.
|
||||
|
||||
|
||||
.. _spi-flash-implementation-details:
|
||||
|
||||
Implementation details
|
||||
----------------------
|
||||
|
||||
In order to perform some flash operations, we need to make sure both CPUs
|
||||
are not running any code from flash for the duration of the flash operation.
|
||||
In a single-core setup this is easy: we disable interrupts/scheduler and do
|
||||
the flash operation. In the dual-core setup this is slightly more complicated.
|
||||
We need to make sure that the other CPU doesn't run any code from flash.
|
||||
|
||||
|
||||
When SPI flash API is called on CPU A (can be PRO or APP), we start
|
||||
spi_flash_op_block_func function on CPU B using esp_ipc_call API. This API
|
||||
wakes up high priority task on CPU B and tells it to execute given function,
|
||||
in this case spi_flash_op_block_func. This function disables cache on CPU B and
|
||||
signals that cache is disabled by setting s_flash_op_can_start flag.
|
||||
Then the task on CPU A disables cache as well, and proceeds to execute flash
|
||||
operation.
|
||||
|
||||
While flash operation is running, interrupts can still run on CPUs A and B.
|
||||
We assume that all interrupt code is placed into RAM. Once interrupt allocation
|
||||
API is added, we should add a flag to request interrupt to be disabled for
|
||||
the duration of flash operations.
|
||||
|
||||
Once flash operation is complete, function on CPU A sets another flag,
|
||||
s_flash_op_complete, to let the task on CPU B know that it can re-enable
|
||||
cache and release the CPU. Then the function on CPU A re-enables the cache on
|
||||
CPU A as well and returns control to the calling code.
|
||||
|
||||
Additionally, all API functions are protected with a mutex (s_flash_op_mutex).
|
||||
|
||||
In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), we simply
|
||||
disable both caches, no inter-CPU communication takes place.
|
||||
|
||||
API Reference - SPI Flash
|
||||
-------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_spi_flash.inc
|
||||
|
||||
API Reference - Partition Table
|
||||
-------------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_partition.inc
|
||||
|
||||
API Reference - Flash Encrypt
|
||||
-----------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_flash_encrypt.inc
|
||||
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
SPIFFS Filesystem
|
||||
=================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
SPIFFS is a file system intended for SPI NOR flash devices on embedded targets.
|
||||
It supports wear leveling, file system consistency checks and more.
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
- Presently, spiffs does not support directories. It produces a flat structure. If SPIFFS is mounted under ``/spiffs`` creating a file with path ``/spiffs/tmp/myfile.txt`` will create a file called ``/tmp/myfile.txt`` in SPIFFS, instead of ``myfile.txt`` under directory ``/spiffs/tmp``.
|
||||
- It is not a realtime stack. One write operation might last much longer than another.
|
||||
- Presently, it does not detect or handle bad blocks.
|
||||
|
||||
Tools
|
||||
-----
|
||||
|
||||
Host-Side tools for creating SPIFS partition images exist and one such tool is `mkspiffs <https://github.com/igrr/mkspiffs>`_.
|
||||
You can use it to create image from a given folder and then flash that image with ``esptool.py``
|
||||
|
||||
To do that you need to obtain some parameters:
|
||||
|
||||
- Block Size: 4096 (standard for SPI Flash)
|
||||
- Page Size: 256 (standard for SPI Flash)
|
||||
- Image Size: Size of the partition in bytes (can be obtained from partition table)
|
||||
- Partition Offset: Starting address of the partition (can be obtained from partition table)
|
||||
|
||||
To pack a folder into 1 Megabyte image::
|
||||
|
||||
mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin
|
||||
|
||||
To flash the image to ESP32 at offset 0x110000::
|
||||
|
||||
python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
An example for using SPIFFS is provided in :example:`storage/spiffs` directory. This example initializes and mounts SPIFFS partition, and writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
|
||||
|
||||
High level API Reference
|
||||
------------------------
|
||||
|
||||
* :component_file:`spiffs/include/esp_spiffs.h`
|
||||
|
||||
.. include:: /_build/inc/esp_spiffs.inc
|
||||
@@ -0,0 +1,16 @@
|
||||
.. include:: ../../../../components/vfs/README.rst
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
`Instructions`_
|
||||
|
||||
.. _Instructions: ../../template.html
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_vfs.inc
|
||||
|
||||
.. include:: /_build/inc/esp_vfs_dev.inc
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
.. include:: ../../../../components/wear_levelling/README.rst
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
- :doc:`FAT Filesystem <./fatfs>`
|
||||
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
An example which combines wear levelling driver with FATFS library is provided in ``examples/storage/wear_levelling`` directory. This example initializes the wear levelling driver, mounts FATFS partition, and writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
|
||||
|
||||
High level API Reference
|
||||
------------------------
|
||||
|
||||
Header Files
|
||||
^^^^^^^^^^^^
|
||||
|
||||
* :component_file:`fatfs/src/esp_vfs_fat.h`
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_mount
|
||||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||||
:members:
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_unmount
|
||||
|
||||
Mid level API Reference
|
||||
-----------------------
|
||||
|
||||
.. include:: /_build/inc/wear_levelling.inc
|
||||
|
||||
Reference in New Issue
Block a user