mirror of
https://github.com/espressif/esp-idf.git
synced 2025-09-30 19:19:21 +00:00
docs: translate networking.rst and storage.rst
This commit is contained in:
wangziyan
@@ -4,69 +4,64 @@ Networking
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Ethernet
|
||||
**********
|
||||
********
|
||||
|
||||
esp_eth_ioctl() API
|
||||
-------------------
|
||||
|
||||
:cpp:func:`esp_eth_ioctl` third argument could take `int` (`bool`) number as an input in some cases. However, it was not properly documented and, in addition, the number had to be "unnaturally" type casted to `void *` datatype to prevent compiler warnings as shown in below example:
|
||||
Previously, the :cpp:func:`esp_eth_ioctl` API had the following issues:
|
||||
|
||||
.. highlight:: c
|
||||
- The third parameter (which is of type ``void *``) would accept an ``int``/``bool`` type arguments (i.e., not pointers) as input in some cases. However, these cases were not documented properly.
|
||||
- To pass ``int``/``bool`` type argument as the third parameter, the argument had to be "unnaturally" casted to a ``void *`` type, to prevent a compiler warning as demonstrated in the code snippet below. This casting could lead to misuse of the :cpp:func:`esp_eth_ioctl` function.
|
||||
|
||||
::
|
||||
.. code-block:: c
|
||||
|
||||
esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true);
|
||||
|
||||
|
||||
This could lead to misuse of the :cpp:func:`esp_eth_ioctl`. Therefore, ESP-IDF 5.0 unified usage of :cpp:func:`esp_eth_ioctl`. Its third argument now always acts as pointer to a memory location of specific type from/to where the configuration option is read/stored.
|
||||
Therefore, the usage of :cpp:func:`esp_eth_ioctl` is now unified. Arguments to the third parameter must be passed as pointers to a specific data type to/from where data will be stored/read by :cpp:func:`esp_eth_ioctl`. The code snippets below demonstrate the usage of :cpp:func:`esp_eth_ioctl`.
|
||||
|
||||
Usage example to set Ethernet configuration:
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
::
|
||||
.. code-block:: c
|
||||
|
||||
eth_duplex_t new_duplex_mode = ETH_DUPLEX_HALF;
|
||||
esp_eth_ioctl(eth_handle, ETH_CMD_S_DUPLEX_MODE, &new_duplex_mode);
|
||||
|
||||
Usage example to get Ethernet configuration:
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
::
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
eth_duplex_t duplex_mode;
|
||||
esp_eth_ioctl(eth_handle, ETH_CMD_G_DUPLEX_MODE, &duplex_mode);
|
||||
|
||||
|
||||
KSZ8041/81 and LAN8720 Driver Update
|
||||
------------------------------------
|
||||
|
||||
KSZ8041/81 and LAN8720 Drivers were updated to support more devices (generations) from associated product family. The drivers are able to recognize particular chip number and its potential support by the driver.
|
||||
The KSZ8041/81 and LAN8720 drivers are updated to support more devices (i.e., generations) from their associated product families. The drivers can recognize particular chip numbers and their potential support by the driver.
|
||||
|
||||
As a result, the specific "chip number" functions calls were replaced by generic ones as follows:
|
||||
As a result, the specific "chip number" functions calls are replaced by generic ones as follows:
|
||||
|
||||
* `esp_eth_phy_new_ksz8041` and `esp_eth_phy_new_ksz8081` were removed, use :cpp:func:`esp_eth_phy_new_ksz80xx` instead
|
||||
* `esp_eth_phy_new_lan8720` was removed, use :cpp:func:`esp_eth_phy_new_lan87xx` instead
|
||||
* Removed ``esp_eth_phy_new_ksz8041()`` and ``esp_eth_phy_new_ksz8081()``, and use :cpp:func:`esp_eth_phy_new_ksz80xx` instead
|
||||
* Removed ``esp_eth_phy_new_lan8720()``, and use :cpp:func:`esp_eth_phy_new_lan87xx` instead
|
||||
|
||||
|
||||
ESP NETIF Glue Event Handlers
|
||||
-----------------------------
|
||||
|
||||
``esp_eth_set_default_handlers()`` and ``esp_eth_clear_default_handlers()`` functions were removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If users have already followed the recommendation to fully initialize the Ethernet driver and network interface prior to registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Otherwise, users should ensure that they register the user event handlers as the last thing prior to starting the Ethernet driver.
|
||||
``esp_eth_set_default_handlers()`` and ``esp_eth_clear_default_handlers()`` functions are removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If you have already followed the suggestion to fully initialize the Ethernet driver and network interface before registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Otherwise, you may start the Ethernet driver right after they register the user event handler.
|
||||
|
||||
PHY Address Auto-detect
|
||||
-----------------------
|
||||
|
||||
Ethernet PHY address auto-detect function ``esp_eth_detect_phy_addr`` was renamed to :cpp:func:`esp_eth_phy_802_3_detect_phy_addr` and its header declaration was moved to :component_file:`esp_eth/include/esp_eth_phy_802_3.h`.
|
||||
The Ethernet PHY address auto-detect function ``esp_eth_detect_phy_addr()`` is renamed to :cpp:func:`esp_eth_phy_802_3_detect_phy_addr` and its header declaration is moved to :component_file:`esp_eth/include/esp_eth_phy_802_3.h`.
|
||||
|
||||
|
||||
SPI-Ethernet Modules Initialization
|
||||
SPI-Ethernet Module Initialization
|
||||
-----------------------------------
|
||||
|
||||
The SPI-Ethernet Module's initialization has been simplified. The previous initialization process required you to manually allocate an SPI device using :cpp:func:`spi_bus_add_device` before instantiating the SPI-Ethernet MAC.
|
||||
The SPI-Ethernet Module initialization is now simplified. Previously, you had to manually allocate an SPI device using :cpp:func:`spi_bus_add_device` before instantiating the SPI-Ethernet MAC.
|
||||
|
||||
Now, you no longer need to call :cpp:func:`spi_bus_add_device` as the allocation of the SPI device is done internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures were updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros have been updated to accept new input parameters. Refer to the :doc:`Ethernet API-Reference Guide<../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization
|
||||
Now, you no longer need to call :cpp:func:`spi_bus_add_device` as SPI devices are allocated internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures are updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros are updated to accept new input parameters. Refer to :doc:`Ethernet API Reference Guide<../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization.
|
||||
|
||||
|
||||
.. _tcpip-adapter:
|
||||
@@ -74,41 +69,40 @@ Now, you no longer need to call :cpp:func:`spi_bus_add_device` as the allocation
|
||||
TCP/IP Adapter
|
||||
*****************
|
||||
|
||||
TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This page outlines migration from tcpip_adapter API to its successor :doc:`/api-reference/network/esp_netif`.
|
||||
The TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This section outlines migration from tcpip_adapter API to its successor :doc:`/api-reference/network/esp_netif`.
|
||||
|
||||
|
||||
Updating network connection code
|
||||
Updating Network Connection Code
|
||||
--------------------------------
|
||||
|
||||
|
||||
Network stack initialization
|
||||
Network Stack Initialization
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Simply replace ``tcpip_adapter_init()`` with ``esp_netif_init()``. Please note that the :doc:`/api-reference/network/esp_netif` initialization API returns standard error code and the ``esp_netif_deinit()`` for un-initialization is available.
|
||||
|
||||
Also replace ``#include "tcpip_adapter.h"`` with ``#include "esp_netif.h"``.
|
||||
- You may simply replace ``tcpip_adapter_init()`` with ``esp_netif_init()``. However, please should note that the ``esp_netif_init()`` function now returns standard error codes. See :doc:`/api-reference/network/esp_netif` for more details.
|
||||
- The ``esp_netif_deinit()`` function is provided to de-initialize the network stack.
|
||||
- You should also replace ``#include "tcpip_adapter.h"`` with ``#include "esp_netif.h"``.
|
||||
|
||||
|
||||
Network interface creation
|
||||
Network Interface Creation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
TCP/IP Adapter defined these three interfaces statically:
|
||||
Previously, the TCP/IP Adapter defined the following network interfaces statically:
|
||||
|
||||
- WiFi Station
|
||||
- WiFi Access Point
|
||||
- Ethernet
|
||||
|
||||
Network interface instance shall be explicitly constructed for the :doc:`/api-reference/network/esp_netif` to enable its connection to the TCP/IP stack.
|
||||
For example initialization code for WiFi has to explicitly call ``esp_netif_create_default_wifi_sta();`` or ``esp_netif_create_default_wifi_ap();`` after the TCP/IP stack and the event loop have been initialized.
|
||||
Please consult an example initialization code for these three interfaces:
|
||||
This now changes. Network interface instance should be explicitly constructed, so that the :doc:`/api-reference/network/esp_netif` can connect to the TCP/IP stack. For example, after the TCP/IP stack and the event loop are initialized, the initialization code for WiFi must explicitly call ``esp_netif_create_default_wifi_sta();`` or ``esp_netif_create_default_wifi_ap();``.
|
||||
|
||||
Please refer to the example initialization code for these three interfaces:
|
||||
|
||||
- WiFi Station: :example_file:`wifi/getting_started/station/main/station_example_main.c`
|
||||
- WiFi Access Point: :example_file:`wifi/getting_started/softAP/main/softap_example_main.c`
|
||||
- Ethernet: :example_file:`ethernet/basic/main/ethernet_example_main.c`
|
||||
|
||||
|
||||
Replacing other tcpip_adapter API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Other tcpip_adapter API Replacement
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All the tcpip_adapter functions have their esp-netif counter-part. Please refer to the esp_netif.h grouped into these sections:
|
||||
|
||||
@@ -117,13 +111,13 @@ All the tcpip_adapter functions have their esp-netif counter-part. Please refer
|
||||
* :component_file:`DNS <esp_netif/include/esp_netif.h#L516>`
|
||||
* :component_file:`IP address <esp_netif/include/esp_netif.h#L568>`
|
||||
|
||||
|
||||
Default event handlers
|
||||
Default Event Handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, all events shall be handled in the same way.
|
||||
Please note that within IP related event handlers, application code usually receives IP addresses in a form of esp-netif specific struct (not the LwIP structs, but binary compatible).
|
||||
This is the preferred way of printing the address:
|
||||
Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, as all events should be handled in the same way. Please note that for IP-related event handlers, application code usually receives IP addresses in the form of an esp-netif specific struct instead of the LwIP structs. However, both structs are binary compatible.
|
||||
|
||||
|
||||
This is the preferred way to print the address:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -135,19 +129,18 @@ Instead of
|
||||
|
||||
ESP_LOGI(TAG, "got ip:%s\n", ip4addr_ntoa(&event->ip_info.ip));
|
||||
|
||||
Since ``ip4addr_ntoa()`` is a LwIP API, the esp-netif provides ``esp_ip4addr_ntoa()`` as a replacement, but the above method is generally preferred.
|
||||
Since ``ip4addr_ntoa()`` is a LwIP API, the esp-netif provides ``esp_ip4addr_ntoa()`` as a replacement. However, the above method using ``IP2STR()`` is generally preferred.
|
||||
|
||||
|
||||
IP addresses
|
||||
IP Addresses
|
||||
^^^^^^^^^^^^
|
||||
|
||||
It is preferred to use esp-netif defined IP structures. Please note that the LwIP structs will still work when default compatibility enabled.
|
||||
You are advised to use esp-netif defined IP structures. Please note that with default compatibility enabled, the LwIP structs will still work.
|
||||
|
||||
* :component_file:`esp-netif IP address definitions <esp_netif/include/esp_netif_ip_addr.h#L96>`
|
||||
|
||||
|
||||
Next steps
|
||||
Next Steps
|
||||
^^^^^^^^^^
|
||||
|
||||
Additional step in porting an application to fully benefit from the :doc:`/api-reference/network/esp_netif` is to disable the tcpip_adapter compatibility layer in the component configuration:
|
||||
``ESP NETIF Adapter`` -> ``Enable backward compatible tcpip_adapter interface`` and check if the project compiles.
|
||||
TCP/IP adapter brings many include dependencies and this step might help in decoupling the application from using specific TCP/IP stack API directly.
|
||||
To port an application which may fully benefit from the :doc:`/api-reference/network/esp_netif`, you also need to disable the tcpip_adapter compatibility layer in the component configuration option. Please go to ``ESP NETIF Adapter`` > ``Enable backward compatible tcpip_adapter interface``. After that, check if your project compiles.
|
||||
|
||||
The TCP/IP adapter includes many dependencies. Thus, disabling its compatibility might help separate the application from using specific TCP/IP stack API directly.
|
||||
|
||||
@@ -1,90 +1,91 @@
|
||||
Storage
|
||||
=======
|
||||
|
||||
Breaking changes:
|
||||
~~~~~~~~~~~~~~~~~
|
||||
FatFs
|
||||
-----
|
||||
|
||||
f_mkfs() signature change in FATFS v0.14
|
||||
----------------------------------------
|
||||
FatFs is now updated to v0.14. As a result, the function signature of ``f_mkfs()`` has changed. The new signature is ``FRESULT f_mkfs (const TCHAR* path, const MKFS_PARM* opt, void* work, UINT len);`` which uses ``MKFS_PARM`` struct as a second argument.
|
||||
|
||||
New signature is ``FRESULT f_mkfs (const TCHAR* path, const MKFS_PARM* opt, void* work, UINT len);`` which now uses ``MKFS_PARM`` struct as a second argument.
|
||||
Partition Table
|
||||
---------------
|
||||
|
||||
Partition table generation no longer supports misaligned partitions
|
||||
-------------------------------------------------------------------
|
||||
The partition table generator no longer supports misaligned partitions. When generating a partition table, ``esp-idf`` only accepts partitions with offsets that align to 4 KB. This change only affects generating new partition tables. Reading and writing to already existing partitions remains unchanged.
|
||||
|
||||
When generating a partiton table, ``esp-idf`` will no longer accept partitions which offset does not align to 4kB. This change only affects generating new partition tables, reading and writing to already existing partitions remains unchanged.
|
||||
|
||||
esp_vfs_semihost_register() signature change
|
||||
--------------------------------------------
|
||||
|
||||
New signature is ``esp_err_t esp_vfs_semihost_register(const char* base_path);`` Absolute path as a second parameter will no longer in use. Instead, the OpenOCD command ``ESP_SEMIHOST_BASEDIR`` should be used to set the full path on the host.
|
||||
|
||||
NVS
|
||||
VFS
|
||||
---
|
||||
|
||||
``nvs_entry_find()``, ``nvs_entry_next()`` and ``nvs_entry_info()`` always return ``esp_err_t`` now instead of ``void`` or ``nvs_iterator_t``. This provides better error reporting when parameters are invalid or something goes wrong internally than returning ``nullptr`` instead of a valid iterator or checking parameters with ``assert``. ``nvs_entry_find()`` and ``nvs_entry_next()`` modify iterators via parameters now instead of returning an iterator.
|
||||
The ``esp_vfs_semihost_register()`` function signature is changed as follows:
|
||||
|
||||
- The new signature is ``esp_err_t esp_vfs_semihost_register(const char* base_path);``
|
||||
- The ``host_path`` parameter of the old signature no longer exists. Instead, the OpenOCD command ``ESP_SEMIHOST_BASEDIR`` should be used to set the full path on the host.
|
||||
|
||||
Function Signature Changes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following functions now return ``esp_err_t`` instead of ``void`` or ``nvs_iterator_t``. Previously, when parameters were invalid or when something goes wrong internally, these functions would ``assert()`` or return a ``nullptr``. With an ``esp_err_t`` returned, you can get better error reporting.
|
||||
|
||||
- :cpp:func:`nvs_entry_find`
|
||||
- :cpp:func:`nvs_entry_next`
|
||||
- :cpp:func:`nvs_entry_info`
|
||||
|
||||
Because the ``esp_err_t`` return type changes, the usage patterns of ``nvs_entry_find()`` and ``nvs_entry_next()`` become different. Both functions now modify iterators via parameters instead of returning an iterator.
|
||||
|
||||
The old programming pattern to iterate over an NVS partition was as follows:
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
::
|
||||
.. code-block:: c
|
||||
|
||||
nvs_iterator_t it = nvs_entry_find(<nvs_partition_name>, <namespace>, NVS_TYPE_ANY);
|
||||
while (it != NULL) {
|
||||
nvs_entry_info_t info;
|
||||
nvs_entry_info(it, &info);
|
||||
it = nvs_entry_next(it);
|
||||
printf("key '%s', type '%d' \n", info.key, info.type);
|
||||
printf("key '%s', type '%d'", info.key, info.type);
|
||||
};
|
||||
|
||||
The new programming pattern to iterate over an NVS partition is now:
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
::
|
||||
.. code-block:: c
|
||||
|
||||
nvs_iterator_t it = nullptr;
|
||||
esp_err_t res = nvs_entry_find(<nvs_partition_name>, <namespace>, NVS_TYPE_ANY, &it);
|
||||
while(res == ESP_OK) {
|
||||
nvs_entry_info_t info;
|
||||
nvs_entry_info(it, &info); // Can omit error check if parameters are guaranteed to be non-NULL
|
||||
printf("key '%s', type '%d' \n", info.key, info.type);
|
||||
printf("key '%s', type '%d'", info.key, info.type);
|
||||
res = nvs_entry_next(&it);
|
||||
}
|
||||
nvs_release_iterator(it);
|
||||
|
||||
Signature Changes
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
``nvs_iterator_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t type)`` changes to ``esp_err_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t type, nvs_iterator_t *output_iterator)``. The iterator is returned via the parameter ``output_iterator`` instead of a return value. This allows reporting additional errors, like e.g. memory errors, via the new return value.
|
||||
|
||||
``nvs_iterator_t nvs_entry_next(nvs_iterator_t iterator)`` changes to ``esp_err_t nvs_entry_next(nvs_iterator_t *it)``. This allows reporting parameter errors and internal errors, like e.g. flash errors.
|
||||
|
||||
``void nvs_entry_info(nvs_iterator_t iterator, nvs_entry_info_t *out_info)`` changes to ``esp_err_t nvs_entry_info(const nvs_iterator_t iterator, nvs_entry_info_t *out_info)`` to allow reporting parameter errors.
|
||||
|
||||
Iterator Validity
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Note that due to the new signatures, it is possible to have an invalid iterator from ``nvs_entry_find()``, if there is a parameter errors. Hence, it is important to initialize the iterator with ``NULL`` before using ``nvs_entry_find()`` to avoid complex error checking before calling ``nvs_release_iterator()``. A good example is the programming pattern above.
|
||||
Note that because the function signature changes, if there is a parameter error, you may get an invalid iterator from ``nvs_entry_find()``. Hence, it is important to initialize the iterator to ``NULL`` before using ``nvs_entry_find()``, so that you can avoid complex error checking before calling ``nvs_release_iterator()``. A good example is the programming pattern above.
|
||||
|
||||
Removed SDSPI deprecated API
|
||||
|
||||
Removed SDSPI Deprecated API
|
||||
----------------------------
|
||||
|
||||
Removed structure ``sdspi_slot_config_t`` and fuction ``sdspi_host_init_slot``. These were replaced by a structure ``sdspi_device_config_t`` and a fuction ``sdspi_host_init_device`` respectively.
|
||||
Structure ``sdspi_slot_config_t`` and function ``sdspi_host_init_slot()`` are removed, and replaced by structure ``sdspi_device_config_t`` and function ``sdspi_host_init_device()`` respectively.
|
||||
|
||||
SPI Flash Interface
|
||||
-------------------
|
||||
ROM SPI Flash
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Version before v5.0, spi flash functions in rom can be included by ``esp32**/rom/spi_flash.h``. However, your code written for different chips may be filled with ROM headers of different versions. At the meantime not all the APIs can be used on all chips.
|
||||
In versions before v5.0, ROM SPI flash functions were included via ``esp32**/rom/spi_flash.h``. Thus, code written to support different ESP chips might be filled with ROM headers of different targets. Furthermore, not all of the APIs could be used on all ESP chips.
|
||||
|
||||
Therefore, the common APIs are extracted to ``esp_rom_spiflash.h``. Although it's not a breaking change, it is strongly recommended to only use the functions with prefix ``esp_rom_spiflash`` included by ``esp_rom_spiflash.h`` for better cross-compatibility.
|
||||
Now, the common APIs are extracted to ``esp_rom_spiflash.h``. Although it is not a breaking change, you are strongly recommended to only use the functions from this header (i.e., prefixed with ``esp_rom_spiflash`` and included by ``esp_rom_spiflash.h``) for better cross-compatibility between ESP chips.
|
||||
|
||||
To make the API clearer, we renamed the function ``esp_rom_spiflash_lock`` to ``esp_rom_spiflash_set_bp``. We renamed ``esp_rom_spiflash_unlock`` to ``esp_rom_spiflash_clear_bp``.
|
||||
To make ROM SPI flash APIs clearer, the following functions are also renamed:
|
||||
|
||||
ENUM type ``esp_flash_speed_t`` has been deprecated. From now on, you can directly parse the real clock frequency value to the flash initialization structure. For example, if you want the flash frequency is 80M, you can write the code like:
|
||||
- ``esp_rom_spiflash_lock()`` to ``esp_rom_spiflash_set_bp()``
|
||||
- ``esp_rom_spiflash_unlock()`` to ``esp_rom_spiflash_clear_bp()``
|
||||
|
||||
.. code:: c
|
||||
SPI Flash Driver
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``esp_flash_speed_t`` ``enum`` type is now deprecated. Instead, you may now directly pass the real clock frequency value to the flash configuration structure. The following example demonstrates how to configure a flash frequency of 80MHz:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_flash_spi_device_config_t dev_cfg = {
|
||||
// Other members
|
||||
@@ -92,29 +93,32 @@ ENUM type ``esp_flash_speed_t`` has been deprecated. From now on, you can direct
|
||||
// Other members
|
||||
};
|
||||
|
||||
Breaking changes in legacy APIs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Legacy SPI Flash Driver
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In order to make spi_flash driver more stable, legacy spi_flash driver is removed on v5.0. Legacy spi_flash driver refers to default spi_flash driver since v3.0 and spi_flash driver with configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` switched on on v4.0 series. The major breaking change is legacy spi_flash driver is not supported on new version anymore. Therefore, the configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` is removed. After that, following functions will no longer exist. But meanwhile, you can use our new APIs instead.
|
||||
To make SPI flash drivers more stable, the legacy SPI flash driver is removed from v5.0. The legacy SPI flash driver refers to default spi_flash driver since v3.0, and the SPI flash driver with configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` enabled since v4.0. The major breaking change here is that the legacy spi_flash driver is no longer supported from v5.0. Therefore, the legacy driver APIs and the ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` configuration option are both removed. Please use the new spi_flash driver's APIs instead.
|
||||
|
||||
+---------------------------------+-------------------------------+
|
||||
| Removed items | Replacement |
|
||||
+=================================+===============================+
|
||||
| ``spi_flash_erase_sector()`` | ``esp_flash_erase_region`` |
|
||||
+---------------------------------+-------------------------------+
|
||||
| ``spi_flash_erase_range()`` | ``esp_flash_erase_region`` |
|
||||
+---------------------------------+-------------------------------+
|
||||
| ``spi_flash_write`` | ``esp_flash_write`` |
|
||||
+---------------------------------+-------------------------------+
|
||||
| ``spi_flash_read()`` | ``esp_flash_read`` |
|
||||
+---------------------------------+-------------------------------+
|
||||
| ``spi_flash_write_encrypted()`` | ``esp_flash_write_encrypted`` |
|
||||
+---------------------------------+-------------------------------+
|
||||
| ``spi_flash_read_encrypted`` | ``esp_flash_read_encrypted`` |
|
||||
+---------------------------------+-------------------------------+
|
||||
.. list-table::
|
||||
:widths: 50 50
|
||||
:header-rows: 1
|
||||
|
||||
* - Removed items
|
||||
- Replacement
|
||||
* - ``spi_flash_erase_sector()``
|
||||
- ``esp_flash_erase_region()``
|
||||
* - ``spi_flash_erase_range()``
|
||||
- ``esp_flash_erase_region()``
|
||||
* - ``spi_flash_write()``
|
||||
- ``esp_flash_write()``
|
||||
* - ``spi_flash_read()``
|
||||
- ``esp_flash_read()``
|
||||
* - ``spi_flash_write_encrypted()``
|
||||
- ``esp_flash_write_encrypted()``
|
||||
* - ``spi_flash_read_encrypted()``
|
||||
- ``esp_flash_read_encrypted()``
|
||||
|
||||
.. note::
|
||||
|
||||
New functions with prefix ``esp_flash`` accept an additional ``esp_flash_t*`` parameter. You can simply set it to NULL means that the function will operate the main flash(``esp_flash_default_chip``)
|
||||
New functions with prefix ``esp_flash`` accept an additional ``esp_flash_t*`` parameter. You can simply set it to NULL. This will make the function to run the main flash (``esp_flash_default_chip``).
|
||||
|
||||
Header ``esp_spi_flash.h`` has been deprecated, system functions are no longer public. To make use of flash memory mapping APIs, you should include ``spi_flash_mmap.h`` instead.
|
||||
The ``esp_spi_flash.h`` header is deprecated as system functions are no longer public. To use flash memory mapping APIs, you may include ``spi_flash_mmap.h`` instead.
|
||||
|
||||
Reference in New Issue
Block a user