docs: update format issues for EN and CN files under api-reference/peripherals
This commit is contained in:
caixinying-git
@@ -11,6 +11,7 @@ The spi_flash component contains API functions related to reading, writing, eras
|
||||
For higher-level API functions which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`, see :doc:`/api-reference/storage/partition`
|
||||
|
||||
.. note::
|
||||
|
||||
``esp_partition_*`` APIs are recommended to be used instead of the lower level ``esp_flash_*`` API functions when accessing the main SPI flash chip, since they conduct bounds checking and are guaranteed to calculate correct offsets in flash based on the information in the partition table. ``esp_flash_*`` functions can still be used directly when accessing an external (secondary) SPI flash chip.
|
||||
|
||||
Different from the API before ESP-IDF v4.0, the functionality of ``esp_flash_*`` APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.
|
||||
@@ -23,7 +24,7 @@ Different from the API before ESP-IDF v4.0, the functionality of ``esp_flash_*``
|
||||
|
||||
.. note::
|
||||
|
||||
Flash APIs after ESP-IDF v4.0 are no longer *atomic*. If a write operation occurs during another on-going read operation, and the flash addresses of both operations overlap, the data returned from the read operation may contain both old data and new data (that was updated written by the write operation).
|
||||
Flash APIs after ESP-IDF v4.0 are no longer **atomic**. If a write operation occurs during another on-going read operation, and the flash addresses of both operations overlap, the data returned from the read operation may contain both old data and new data (that was updated written by the write operation).
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -35,7 +36,7 @@ Support for Features of Flash Chips
|
||||
Quad/Dual Mode Chips
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Features of different flashes are implemented in different ways and thus need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all flashes with 24-bit address are supported, because they don't need any vendor-specific commands.
|
||||
Features of different flashes are implemented in different ways and thus need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all flashes with 24-bit address are supported, because they do not need any vendor-specific commands.
|
||||
|
||||
Quad mode (QIO/QOUT) is supported on the following chip types:
|
||||
|
||||
@@ -69,7 +70,7 @@ There are some features that are not supported by all flash chips, or not suppor
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
- High performance mode (HPM) - means that flash works under high frequency which is higher than 80MHz.
|
||||
- High performance mode (HPM) - means that flash works under high frequency which is higher than 80 MHz.
|
||||
|
||||
- Flash unique ID - means that flash supports its unique 64-bit ID.
|
||||
|
||||
@@ -95,7 +96,7 @@ To use the ``esp_flash_*`` APIs, you need to initialise a flash chip on a certai
|
||||
|
||||
2. Call :cpp:func:`spi_bus_add_flash_device` to attach the flash device to the bus. This function allocates memory and fills the members for the ``esp_flash_t`` structure. The CS I/O is also initialized here.
|
||||
|
||||
3. Call :cpp:func:`esp_flash_init` to actually communicate with the chip. This will also detect the chip type, and influence the following operations.
|
||||
3. Call :cpp:func:`esp_flash_init` to actually communicate with the chip. This also detects the chip type, and influence the following operations.
|
||||
|
||||
.. note:: Multiple flash chips can be attached to the same bus now.
|
||||
|
||||
@@ -117,7 +118,7 @@ SPI Flash Size
|
||||
|
||||
The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000.
|
||||
|
||||
By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
|
||||
By default, the SPI flash size is detected by ``esptool.py`` when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
|
||||
|
||||
If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``esp_flash_*`` functions (in both software & ROM) to check the bounds.
|
||||
|
||||
@@ -131,7 +132,7 @@ Concurrency Constraints for Flash on SPI1
|
||||
|
||||
.. attention::
|
||||
|
||||
The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI flash driver). Hence, calling SPI Flash API on SPI1 bus (including the main flash) will cause significant influence to the whole system. See :doc:`spi_flash_concurrency` for more details.
|
||||
The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI flash driver). Hence, calling SPI Flash API on SPI1 bus (including the main flash) causes significant influence to the whole system. See :doc:`spi_flash_concurrency` for more details.
|
||||
|
||||
|
||||
SPI Flash Encryption
|
||||
@@ -144,7 +145,7 @@ Refer to the :doc:`Flash Encryption documentation </security/flash-encryption>`
|
||||
Memory Mapping API
|
||||
------------------
|
||||
|
||||
{IDF_TARGET_CACHE_SIZE:default="64 KB",esp32c2=16~64 KB}
|
||||
{IDF_TARGET_CACHE_SIZE:default="64 KB", esp32c2=16 ~ 64 KB}
|
||||
|
||||
{IDF_TARGET_NAME} features memory hardware which allows regions of flash memory to be mapped into instruction and data address spaces. This mapping works only for read operations. It is not possible to modify contents of flash memory by writing to a mapped memory region.
|
||||
|
||||
@@ -163,11 +164,12 @@ Memory mapping API are declared in ``spi_flash_mmap.h`` and ``esp_partition.h``:
|
||||
Differences between :cpp:func:`spi_flash_mmap` and :cpp:func:`esp_partition_mmap` are as follows:
|
||||
|
||||
- :cpp:func:`spi_flash_mmap` must be given a {IDF_TARGET_CACHE_SIZE} aligned physical address.
|
||||
- :cpp:func:`esp_partition_mmap` may be given any arbitrary offset within the partition. It will adjust the returned pointer to mapped memory as necessary.
|
||||
- :cpp:func:`esp_partition_mmap` may be given any arbitrary offset within the partition. It adjusts the returned pointer to mapped memory as necessary.
|
||||
|
||||
Note that since memory mapping happens in pages, it may be possible to read data outside of the partition provided to ``esp_partition_mmap``, regardless of the partition boundary.
|
||||
|
||||
.. note::
|
||||
|
||||
mmap is supported by cache, so it can only be used on main flash.
|
||||
|
||||
SPI Flash Implementation
|
||||
@@ -177,7 +179,7 @@ The ``esp_flash_t`` structure holds chip data as well as three important parts o
|
||||
|
||||
1. The host driver, which provides the hardware support to access the chip;
|
||||
2. The chip driver, which provides compatibility service to different chips;
|
||||
3. The OS functions, provide support of some OS functions (e.g. lock, delay) in different stages (1st/2nd boot, or the app).
|
||||
3. The OS functions, provide support of some OS functions (e.g., lock, delay) in different stages (1st/2nd boot, or the app).
|
||||
|
||||
Host Driver
|
||||
^^^^^^^^^^^
|
||||
@@ -212,7 +214,7 @@ The lock (see :ref:`spi_bus_lock`) is used to resolve the conflicts among the ac
|
||||
|
||||
2. On the other buses, the flash driver needs to disable the ISR registered by SPI Master driver, to avoid conflicts.
|
||||
|
||||
3. Some devices of SPI Master driver may require to use the bus monopolized during a period (especially when the device doesn't have a CS wire, or the wire is controlled by software like SDSPI driver).
|
||||
3. Some devices of SPI Master driver may require to use the bus monopolized during a period (especially when the device does not have a CS wire, or the wire is controlled by software like SDSPI driver).
|
||||
|
||||
The delay is used by some long operations which requires the master to wait or polling periodically.
|
||||
|
||||
@@ -220,14 +222,14 @@ The top API wraps these the chip driver and OS functions into an entire componen
|
||||
|
||||
OS functions can also help to avoid a watchdog timeout when erasing large flash areas. During this time, the CPU is occupied with the flash erasing task. This stops other tasks from being executed. Among these tasks is the idle task to feed the watchdog timer (WDT). If the configuration option :ref:`CONFIG_ESP_TASK_WDT_PANIC` is selected and the flash operation time is longer than the watchdog timeout period, the system will reboot.
|
||||
|
||||
It's pretty hard to totally eliminate this risk, because the erasing time varies with different flash chips, making it hard to be compatible in flash drivers. Therefore, users need to pay attention to it. Please use the following guidelines:
|
||||
It is pretty hard to totally eliminate this risk, because the erasing time varies with different flash chips, making it hard to be compatible in flash drivers. Therefore, users need to pay attention to it. Please use the following guidelines:
|
||||
|
||||
1. It is recommended to enable the :ref:`CONFIG_SPI_FLASH_YIELD_DURING_ERASE` option to allow the scheduler to re-schedule during erasing flash memory. Besides, following parameters can also be used.
|
||||
|
||||
- Increase :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_TICKS` or decrease :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS` in menuconfig.
|
||||
- You can also increase :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` in menuconfig for a larger watchdog timeout period. However, with larger watchdog timeout period, previously detected timeouts may no longer be detected.
|
||||
|
||||
2. Please be aware of the consequences of enabling the :ref:`CONFIG_ESP_TASK_WDT_PANIC` option when doing long-running SPI flash operations which will trigger the panic handler when it times out. However, this option can also help dealing with unexpected exceptions in your application. Please decide whether this is needed to be enabled according to actual condition.
|
||||
2. Please be aware of the consequences of enabling the :ref:`CONFIG_ESP_TASK_WDT_PANIC` option when doing long-running SPI flash operations which triggers the panic handler when it times out. However, this option can also help dealing with unexpected exceptions in your application. Please decide whether this is needed to be enabled according to actual condition.
|
||||
|
||||
3. During your development, please carefully review the actual flash operation according to the specific requirements and time limits on erasing flash memory of your projects. Always allow reasonable redundancy based on your specific product requirements when configuring the flash erasing timeout threshold, thus improving the reliability of your product.
|
||||
|
||||
|
||||
@@ -34,27 +34,27 @@ Under this condition, all CPUs should always execute code and access data from i
|
||||
|
||||
.. note::
|
||||
|
||||
When :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is enabled, these APIs won't disable the caches. The hardware will handle the arbitration between them.
|
||||
When :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is enabled, these APIs will not disable the caches. The hardware will handle the arbitration between them.
|
||||
|
||||
.. only:: SOC_SPIRAM_XIP_SUPPORTED
|
||||
|
||||
.. note::
|
||||
|
||||
When :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA` are both enabled, these APIs won't disable the caches.
|
||||
When :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA` are both enabled, these APIs will not disable the caches.
|
||||
|
||||
.. only:: not CONFIG_FREERTOS_UNICORE
|
||||
|
||||
The way that these APIs disable the caches will suspend all the other tasks. Besides, all non-IRAM-safe interrupts will be disabled. The other core will be polling in a busy loop. These will be restored until the Flash operation completes.
|
||||
The way that these APIs disable the caches suspends all the other tasks. Besides, all non-IRAM-safe interrupts will be disabled. The other core will be polling in a busy loop. These will be restored until the Flash operation completes.
|
||||
|
||||
.. only:: CONFIG_FREERTOS_UNICORE
|
||||
|
||||
The way that these APIs disable the caches will also disable non-IRAM-safe interrupts. These will be restored until the Flash operation completes.
|
||||
The way that these APIs disable the caches also disables non-IRAM-safe interrupts. These will be restored until the Flash operation completes.
|
||||
|
||||
See also :ref:`esp_flash_os_func` and :ref:`spi_bus_lock`.
|
||||
|
||||
There are no such constraints and impacts for flash chips on other SPI buses than SPI0/1.
|
||||
|
||||
For differences between internal RAM (e.g. IRAM, DRAM) and flash cache, please refer to the :ref:`application memory layout <memory-layout>` documentation.
|
||||
For differences between internal RAM (e.g., IRAM, DRAM) and flash cache, please refer to the :ref:`application memory layout <memory-layout>` documentation.
|
||||
|
||||
|
||||
.. _iram-safe-interrupt-handlers:
|
||||
@@ -75,7 +75,7 @@ If a function or symbol is not correctly put into IRAM/DRAM, and the interrupt h
|
||||
Non-IRAM-Safe Interrupt Handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If the ``ESP_INTR_FLAG_IRAM`` flag is not set when registering, the interrupt handler will not get executed when the caches are disabled. Once the caches are restored, the non-IRAM-safe interrupts will be re-enabled. After this moment, the interrupt handler will run normally again. This means that as long as caches are disabled, users won't see the corresponding hardware event happening.
|
||||
If the ``ESP_INTR_FLAG_IRAM`` flag is not set when registering, the interrupt handler will not get executed when the caches are disabled. Once the caches are restored, the non-IRAM-safe interrupts will be re-enabled. After this moment, the interrupt handler will run normally again. This means that as long as caches are disabled, users will not see the corresponding hardware event happening.
|
||||
|
||||
|
||||
.. only:: esp32c3 or esp32c2 or esp32s3
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
SPI Flash API ESP-IDF version vs Chip-ROM version
|
||||
=================================================
|
||||
SPI Flash API ESP-IDF Version vs Chip-ROM Version
|
||||
===================================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
There is a set of SPI Flash drivers in Chip-ROM which you can use by enabling :ref:`CONFIG_SPI_FLASH_ROM_IMPL`. Most of the ESP-IDF SPI Flash driver code are in internal RAM, therefore enabling this option will free some internal RAM usage. Note if you enable this option, this means some SPI Flash driver features and bugfixes that are done in ESP-IDF might not be included in the Chip-ROM version.
|
||||
There is a set of SPI Flash drivers in Chip-ROM which you can use by enabling :ref:`CONFIG_SPI_FLASH_ROM_IMPL`. Most of the ESP-IDF SPI Flash driver code are in internal RAM, therefore enabling this option frees some internal RAM usage. Note if you enable this option, this means some SPI Flash driver features and bugfixes that are done in ESP-IDF might not be included in the Chip-ROM version.
|
||||
|
||||
|
||||
Feature Supported by ESP-IDF but not in Chip-ROM
|
||||
Feature Supported by ESP-IDF but Not in Chip-ROM
|
||||
------------------------------------------------
|
||||
|
||||
.. list::
|
||||
@@ -17,13 +17,13 @@ Feature Supported by ESP-IDF but not in Chip-ROM
|
||||
- TH Flash chip support.
|
||||
- Kconfig option :ref:`CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED`.
|
||||
- :ref:`CONFIG_SPI_FLASH_VERIFY_WRITE`, enabling this option helps you detect bad writing.
|
||||
- :ref:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`, enabling this option will print the bad writing.
|
||||
- :ref:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`, enabling this option will check if you're writing zero to one.
|
||||
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`, enabling this option will check for flash programming to certain protected regions like bootloader, partition table or application itself.
|
||||
- :ref:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`, enabling this option prints the bad writing.
|
||||
- :ref:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`, enabling this option checks if you are writing zero to one.
|
||||
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`, enabling this option checks for flash programming to certain protected regions like bootloader, partition table or application itself.
|
||||
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`, enabling this option to collect performance data for ESP-IDF SPI Flash driver APIs.
|
||||
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, enabling this option to automatically suspend / resume a long Flash operation when short Flash operation happens. Note this feature is an optional feature, please do read :ref:`auto-suspend-intro` for more limitations.
|
||||
|
||||
Bugfixes Introduced in ESP-IDF but not in Chip-ROM
|
||||
Bugfixes Introduced in ESP-IDF but Not in Chip-ROM
|
||||
--------------------------------------------------
|
||||
|
||||
.. list::
|
||||
|
||||
@@ -15,7 +15,7 @@ Some features are not supported on all ESP chips and Flash chips. You can check
|
||||
|
||||
.. note::
|
||||
|
||||
- The features listed above needs to be supported by both esp chips and flash chips.
|
||||
- The features listed above needs to be supported by both ESP chips and flash chips.
|
||||
|
||||
- If you are using an official Espressif modules/SiP. Some of the modules/SiPs always support the feature, in this case you can see these features listed in the datasheet. Otherwise please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_ to know if we can supply such products for you.
|
||||
|
||||
@@ -23,7 +23,7 @@ Some features are not supported on all ESP chips and Flash chips. You can check
|
||||
|
||||
.. attention::
|
||||
|
||||
This document only shows that IDF code has supported the features of those flash chips. It's not a list of stable flash chips certified by Espressif. If you build your own hardware from flash chips with your own brought flash chips (even with flash listed in this page), you need to validate the reliability of flash chips yourself.
|
||||
This document only shows that ESP-IDF code has supported the features of those flash chips. It is not a list of stable flash chips certified by Espressif. If you build your own hardware from flash chips with your own brought flash chips (even with flash listed in this page), you need to validate the reliability of flash chips yourself.
|
||||
|
||||
.. _auto-suspend-intro:
|
||||
|
||||
@@ -49,7 +49,7 @@ Flash Chips List:
|
||||
|
||||
There are multiple limitations about the auto-suspend feature, please do read :ref:`auto-suspend` for more information before you enable this feature.
|
||||
|
||||
Flash unique ID
|
||||
Flash Unique ID
|
||||
---------------
|
||||
|
||||
Unique ID is not flash id, which means flash has 64-Bit unique ID for each device. The instruction to read the unique ID (4Bh) accesses a factory-set read-only 64-bit number that is unique to each flash device. This ID number helps you to recognize each single device. Not all flash vendors support this feature. If you try to read the unique ID on a chip which does not have this feature, the behavior is not determined. The support list is as follows.
|
||||
@@ -70,16 +70,16 @@ Flash Chips List:
|
||||
|
||||
.. _hpm-doc:
|
||||
|
||||
High performance mode
|
||||
High Performance Mode
|
||||
---------------------
|
||||
|
||||
.. note::
|
||||
|
||||
This section is provided for Dual mode (DOUT/DIO) and Quad mode (QIO/QOUT) flash chips. Octal flash used on ESP-chips support High performance mode by default so far, you can refer to the octal flash support list below.
|
||||
|
||||
High performance mode (HPM) means that the SPI1 and flash chip works under high frequency. Usually, when the operating frequency of the flash is greater than 80MHz, it is considered that the flash works under HPM. As far as we acknowledged, flash chips have more than two different coping strategies when flash work under HPM. For some flash chips, HPM is controlled by high performance flag (HPF) in status register and for some flash chips, HPM is controlled by dummy cycle bit.
|
||||
High performance mode (HPM) means that the SPI1 and flash chip works under high frequency. Usually, when the operating frequency of the flash is greater than 80 MHz, it is considered that the flash works under HPM. As far as we acknowledged, flash chips have more than two different coping strategies when flash work under HPM. For some flash chips, HPM is controlled by high performance flag (HPF) in status register and for some flash chips, HPM is controlled by dummy cycle bit.
|
||||
|
||||
For following conditions， IDF start code deals with HPM internally.
|
||||
For following conditions, ESP-IDF start code deals with HPM internally.
|
||||
|
||||
ESP Chips List:
|
||||
|
||||
@@ -97,7 +97,7 @@ Flash Chips (name & ID) List:
|
||||
|
||||
.. _oct-flash-doc:
|
||||
|
||||
OPI flash support
|
||||
OPI flash Support
|
||||
-----------------
|
||||
|
||||
OPI flash means that the flash chip supports octal peripheral interface, which has octal I/O pins. Different octal flash has different configurations and different commands. Hence, it is necessary to carefully check the support list.
|
||||
@@ -135,8 +135,8 @@ Flash Chips List:
|
||||
|
||||
.. important::
|
||||
|
||||
Over 16 MBytes space on flash mentioned above can be only used for `data saving`, like file system. If your data / instructions over 16 MBytes spaces need to be mapped to MMU (so as to be accessed by the CPU), please enable the config `IDF_EXPERIMENTAL_FEATURES` and `CONFIG_SPI_FLASH_32BIT_ADDRESS` and read the limitations following:
|
||||
Over 16 MBytes space on flash mentioned above can be only used for ``data saving``, like file system. If your data/instructions over 16 MBytes spaces need to be mapped to MMU (so as to be accessed by the CPU), please enable the config ``IDF_EXPERIMENTAL_FEATURES`` and ``CONFIG_SPI_FLASH_32BIT_ADDRESS`` and read the limitations following:
|
||||
|
||||
1. This option only valid for 4-line flash. Octal flash doesn't need this.
|
||||
2. Only MMU on ESP chip that supports mapping to a range over 16MB memory supports this config. (Only ESP32S3 supports this up to now)
|
||||
3. This option is experimental, which means it can't use on all flash chips stable, for more information, please contact Espressif Business support.
|
||||
1. This option only valid for 4-line flash. Octal flash does not need this.
|
||||
2. Only MMU on ESP chip that supports mapping to a range over 16 MB memory supports this config. (Only ESP32S3 supports this up to now)
|
||||
3. This option is experimental, which means it can not use on all flash chips stable, for more information, please contact Espressif Business support.
|
||||
|
||||
@@ -2,43 +2,45 @@ Overriding Default Chip Drivers
|
||||
===============================
|
||||
|
||||
.. warning::
|
||||
|
||||
Customizing SPI Flash Chip Drivers is considered an "expert" feature. Users should only do so at their own risk. (See the notes below)
|
||||
|
||||
During the SPI Flash driver's initialization (i.e., :cpp:func:`esp_flash_init`), there is a chip detection step during which the driver will iterate through a Default Chip Driver List and determine which chip driver can properly support the currently connected flash chip. The Default Chip Drivers are provided by the IDF, thus are updated in together with each IDF version. However IDF also allows users to customize their own chip drivers.
|
||||
During the SPI Flash driver's initialization (i.e., :cpp:func:`esp_flash_init`), there is a chip detection step during which the driver iterates through a Default Chip Driver List and determine which chip driver can properly support the currently connected flash chip. The Default Chip Drivers are provided by the ESP-IDF, thus are updated in together with each ESP-IDF version. However ESP-IDF also allows users to customize their own chip drivers.
|
||||
|
||||
Users should note the following when customizing chip drivers:
|
||||
|
||||
1. You may need to rely on some non-public IDF functions, which have slight possibility to change between IDF versions. On the one hand, these changes may be useful bug fixes for your driver, on the other hand, they may also be breaking changes (i.e., breaks your code).
|
||||
2. Some IDF bug fixes to other chip drivers will not be automatically applied to your own custom chip drivers.
|
||||
1. You may need to rely on some non-public ESP-IDF functions, which have slight possibility to change between ESP-IDF versions. On the one hand, these changes may be useful bug fixes for your driver, on the other hand, they may also be breaking changes (i.e., breaks your code).
|
||||
2. Some ESP-IDF bug fixes to other chip drivers are not automatically applied to your own custom chip drivers.
|
||||
3. If the protection of flash is not handled properly, there may be some random reliability issues.
|
||||
4. If you update to a newer IDF version that has support for more chips, you will have to manually add those new chip drivers into your custom chip driver list. Otherwise the driver will only search for the drivers in custom list you provided.
|
||||
4. If you update to a newer ESP-IDF version that has support for more chips, you will have to manually add those new chip drivers into your custom chip driver list. Otherwise the driver will only search for the drivers in custom list you provided.
|
||||
|
||||
|
||||
Steps For Creating Custom Chip Drivers and Overriding the IDF Default Driver List
|
||||
---------------------------------------------------------------------------------
|
||||
Steps For Creating Custom Chip Drivers and Overriding the ESP-IDF Default Driver List
|
||||
-------------------------------------------------------------------------------------
|
||||
|
||||
.. highlight: cmake
|
||||
|
||||
1. Enable the :ref:`CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST` config option. This will prevent compilation and linking of the Default Chip Driver List (`default_registered_chips`) provided by IDF. Instead, the linker will search for the structure of the same name (`default_registered_chips`) that must be provided by the user.
|
||||
2. Add a new component in your project, e.g. `custom_chip_driver`.
|
||||
3. Copy the necessary chip driver files from the `spi_flash` component in IDF. This may include:
|
||||
1. Enable the :ref:`CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST` config option. This prevents compilation and linking of the Default Chip Driver List (``default_registered_chips``) provided by ESP-IDF. Instead, the linker searches for the structure of the same name (``default_registered_chips``) that must be provided by the user.
|
||||
2. Add a new component in your project, e.g., ``custom_chip_driver``.
|
||||
3. Copy the necessary chip driver files from the ``spi_flash`` component in ESP-IDF. This may include:
|
||||
|
||||
- `spi_flash_chip_drivers.c` (to provide the `default_registered_chips` structure)
|
||||
- Any of the `spi_flash_chip_*.c` files that matches your own flash model best
|
||||
- `CMakeLists.txt` and `linker.lf` files
|
||||
- ``spi_flash_chip_drivers.c`` (to provide the ``default_registered_chips`` structure)
|
||||
- Any of the ``spi_flash_chip_*.c`` files that matches your own flash model best
|
||||
- ``CMakeLists.txt`` and ``linker.lf`` files
|
||||
|
||||
Modify the files above properly. Including:
|
||||
|
||||
- Change the ``default_registered_chips`` variable to non-static and remove the #ifdef logic around it.
|
||||
- Update `linker.lf` file to rename the fragment header and the library name to match the new component.
|
||||
- Update ``linker.lf`` file to rename the fragment header and the library name to match the new component.
|
||||
- If reusing other drivers, some header names need prefixing with ``spi_flash/`` when included from outside spi_flash component.
|
||||
|
||||
.. note::
|
||||
- When writing your own flash chip driver, you can set your flash chip capabilities through `spi_flash_chip_***(vendor)_get_caps` and points the function pointer `get_chip_caps` for protection to the `spi_flash_chip_***_get_caps` function. The steps are as follows.
|
||||
|
||||
- When writing your own flash chip driver, you can set your flash chip capabilities through ``spi_flash_chip_***(vendor)_get_caps`` and points the function pointer ``get_chip_caps`` for protection to the ``spi_flash_chip_***_get_caps`` function. The steps are as follows.
|
||||
|
||||
1. Please check whether your flash chip have the capabilities listed in `spi_flash_caps_t` by checking the flash datasheet.
|
||||
2. Write a function named `spi_flash_chip_***(vendor)_get_caps`. Take the example below as a reference. (if the flash support `suspend` and `read unique id`).
|
||||
3. Points the pointer `get_chip_caps` (in `spi_flash_chip_t`) to the function mentioned above.
|
||||
1. Please check whether your flash chip have the capabilities listed in ``spi_flash_caps_t`` by checking the flash datasheet.
|
||||
2. Write a function named ``spi_flash_chip_***(vendor)_get_caps``. Take the example below as a reference. (if the flash support ``suspend`` and ``read unique id``).
|
||||
3. Points the pointer ``get_chip_caps`` (in ``spi_flash_chip_t``) to the function mentioned above.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -62,7 +64,7 @@ Steps For Creating Custom Chip Drivers and Overriding the IDF Default Driver Lis
|
||||
|
||||
- You also can see how to implement this in the example :example:`storage/custom_flash_driver`.
|
||||
|
||||
4. Write a new `CMakeLists.txt` file for the `custom_chip_driver` component, including an additional line to add a linker dependency from `spi_flash` to `custom_chip_driver`::
|
||||
4. Write a new ``CMakeLists.txt`` file for the ``custom_chip_driver`` component, including an additional line to add a linker dependency from ``spi_flash`` to ``custom_chip_driver``::
|
||||
|
||||
idf_component_register(SRCS "spi_flash_chip_drivers.c"
|
||||
"spi_flash_chip_mychip.c" # modify as needed
|
||||
@@ -73,7 +75,7 @@ Steps For Creating Custom Chip Drivers and Overriding the IDF Default Driver Lis
|
||||
|
||||
- An example of this component CMakeLists.txt can be found in :example_file:`storage/custom_flash_driver/components/custom_chip_driver/CMakeLists.txt`
|
||||
|
||||
5. The `linker.lf` is used to put every chip driver that you are going to use whilst cache is disabled into internal RAM. See :doc:`/api-guides/linker-script-generation` for more details. Make sure this file covers all the source files that you add.
|
||||
5. The ``linker.lf`` is used to put every chip driver that you are going to use whilst cache is disabled into internal RAM. See :doc:`/api-guides/linker-script-generation` for more details. Make sure this file covers all the source files that you add.
|
||||
|
||||
6. Build your project, and you will see the new flash driver is used.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user