diff --git a/components/vfs/README.rst b/components/vfs/README.rst index 9510b9b669..7521894ddd 100644 --- a/components/vfs/README.rst +++ b/components/vfs/README.rst @@ -228,7 +228,7 @@ The following code is transferred to ``fprintf(__getreent()->_stderr, "42\n");`` fprintf(stderr, "42\n"); -The ``__getreent()`` function returns a per-task pointer to ``struct _reent`` (:component_file:`newlib/include/sys/reent.h#L370-L417`). This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout``, and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout``, and ``_stderr`` of ``_GLOBAL_REENT`` (i.e., the structure which is used before FreeRTOS is started). +The ``__getreent()`` function returns a per-task pointer to ``struct _reent`` in newlib libc. This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout``, and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout``, and ``_stderr`` of ``_GLOBAL_REENT`` (i.e., the structure which is used before FreeRTOS is started). Such a design has the following consequences: diff --git a/components/vfs/README_CN.rst b/components/vfs/README_CN.rst index 93118ec191..9e5e0c0b7b 100644 --- a/components/vfs/README_CN.rst +++ b/components/vfs/README_CN.rst @@ -82,7 +82,7 @@ VFS 组件支持 C 库函数（如 fopen 和 fprintf 等）与文件系统 (FS) 请参考以下示例，查看如何使用 VFS 文件描述符调用 :cpp:func:`select`： -- :example:`peripherals/uart_select` +- :example:`peripherals/uart/uart_select` - :example:`system/select` 如果 :cpp:func:`select` 用于套接字文件描述符，您可以启用 :envvar:`CONFIG_LWIP_USE_ONLY_LWIP_SELECT` 选项来减少代码量，提高性能。 @@ -158,7 +158,7 @@ VFS 还为输入和输出提供换行符转换功能（可选）。多数应用 fprintf(__getreent()->_stderr, "42\n"); -其中 ``__getreent()`` 函数将为每个任务返回一个指向 ``struct _reent`` 的指针 (:component_file:`newlib/include/sys/reent.h#L370-L417`)。每个任务的 TCB 均拥有一个 ``struct _reent`` 结构体，任务初始化后，``struct _reent`` 结构体中的 ``_stdin``、``_stdout`` 和 ``_stderr`` 将会被赋予 ``_GLOBAL_REENT`` 中 ``_stdin``、 ``_stdout`` 和 ``_stderr`` 的值，``_GLOBAL_REENT`` 即为 FreeRTOS 启动之前所用结构体。 +其中 ``__getreent()`` 函数将为每个任务返回一个指向 ``struct _reent`` 的指针。每个任务的 TCB 均拥有一个 ``struct _reent`` 结构体，任务初始化后，``struct _reent`` 结构体中的 ``_stdin``、``_stdout`` 和 ``_stderr`` 将会被赋予 ``_GLOBAL_REENT`` 中 ``_stdin``、 ``_stdout`` 和 ``_stderr`` 的值，``_GLOBAL_REENT`` 即为 FreeRTOS 启动之前所用结构体。 这样设计带来的结果是： diff --git a/docs/en/COPYRIGHT.rst b/docs/en/COPYRIGHT.rst index d362becae1..8f278376b4 100644 --- a/docs/en/COPYRIGHT.rst +++ b/docs/en/COPYRIGHT.rst @@ -17,11 +17,11 @@ These third party libraries can be included into the application (firmware) prod * :component:`Newlib ` is licensed under the BSD License and is Copyright of various parties, as described in :component_file:`COPYING.NEWLIB`. -* :component:`Xtensa header files` are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduced in the individual header files. +* :component:`Xtensa header files` are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduced in the individual header files. * Original parts of FreeRTOS_ (components/freertos) are Copyright (C) 2015 Real Time Engineers Ltd and is licensed under the GNU General Public License V2 with the FreeRTOS Linking Exception, as described in :component_file:`license.txt`. -* Original parts of LWIP_ (components/lwip) are Copyright (C) 2001, 2002 Swedish Institute of Computer Science and are licensed under the BSD License as described in :component_file:`COPYING file`. +* Original parts of LWIP_ (components/lwip) are Copyright (C) 2001, 2002 Swedish Institute of Computer Science and are licensed under the BSD License as described in :component_file:`COPYING file`. * `wpa_supplicant`_ Copyright (c) 2003-2005 Jouni Malinen and licensed under the BSD license. @@ -58,7 +58,7 @@ These third party libraries can be included into the application (firmware) prod * :component:`Asio `, Copyright (c) 2003-2018 Christopher M. Kohlhoff is licensed under the Boost Software License. * :component:`ESP-MQTT ` MQTT Package (contiki-mqtt) - Copyright (c) 2014, Stephen Robinson, MQTT-ESP - Tuan PM is licensed under Apache License 2.0. -* :component:`BLE Mesh ` is adapted from Zephyr Project, Copyright (c) 2017-2018 Intel Corporation and licensed under Apache License 2.0 +* :component:`BLE Mesh ` is adapted from Zephyr Project, Copyright (c) 2017-2018 Intel Corporation and licensed under Apache License 2.0 * `mynewt-nimble`_ Apache Mynewt NimBLE, Copyright 2015-2018, The Apache Software Foundation, is licensed under Apache License 2.0. @@ -72,9 +72,9 @@ This is the list of licenses for tools included in this repository, which are us * :idf:`KConfig ` is Copyright (C) 2002 Roman Zippel and others, and is licensed under the GNU General Public License V2. -* :idf:`Kconfiglib ` is Copyright (C) 2011-2019, Ulf Magnusson, and is licensed under the ISC License. +* :idf_file:`Kconfiglib ` is Copyright (C) 2011-2019, Ulf Magnusson, and is licensed under the ISC License. -* :idf:`Menuconfig of Kconfiglib ` is Copyright (C) 2018-2019, Nordic Semiconductor ASA and Ulf Magnusson, and is licensed under the ISC License. +* :idf_file:`Menuconfig of Kconfiglib ` is Copyright (C) 2018-2019, Nordic Semiconductor ASA and Ulf Magnusson, and is licensed under the ISC License. ROM Source Code Copyrights diff --git a/docs/en/api-guides/RF_calibration.rst b/docs/en/api-guides/RF_calibration.rst index 25b5862e34..883d82f809 100644 --- a/docs/en/api-guides/RF_calibration.rst +++ b/docs/en/api-guides/RF_calibration.rst @@ -41,14 +41,20 @@ If you use the default method of RF calibration, there are two ways to add the f No calibration --------------- -No calibration method is only used when {IDF_TARGET_NAME} wakes up from deep sleep. +No calibration method is only used when the device wakes up from deep sleep. PHY initialization data ----------------------- The PHY initialization data is used for RF calibration. There are two ways to get the PHY initialization data. -One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`. +.. only:: esp32 + + One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/esp32/include/phy_init_data.h`. + +.. only:: esp32s2 + + One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/esp32s2/include/phy_init_data.h`. It is embedded into the application binary after compiling and then stored into read-only memory (DROM). To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`. diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 758d7f08f4..2919e2e145 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -666,7 +666,7 @@ By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``. -Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details. +Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf:`/tools/cmake/` for more details. .. _gnu-make-to-cmake: diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst index eedb341f3c..01ea380e94 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst @@ -261,7 +261,7 @@ Specific files that provide implementation of provisioning of Node are shown in - Functionality * - :component_file:`prov.c ` - ESP-BLE-MESH Node provisioning (PB-ADV & PB-GATT) - * - :component_file:`proxy.c ` + * - :component_file:`proxy_client.c ` - ESP-BLE-MESH Proxy Server related functionalities * - :component_file:`beacon.c ` - APIs used to handle ESP-BLE-MESH Beacons @@ -276,7 +276,7 @@ Specific files that implement functions of Provisioner are shown in Table 2.3: - Functionality * - :component_file:`provisioner_prov.c ` - ESP-BLE-MESH Provisioner provisioning (PB-ADV & PB-GATT) - * - :component_file:`provisioner_proxy.c ` + * - :component_file:`proxy_server.c ` - ESP-BLE-MESH Proxy Client related functionalities * - :component_file:`provisioner_beacon.c ` - ESP-BLE-MESH Provisioner receives Unprovisioned Device Beacon @@ -322,7 +322,7 @@ Mesh Models are used to implement the specific functions of model in nodes. Serv 2.2 Mesh Bearers Implementation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Portability is fully considered in the implementation of Mesh Bearers. When the ESP-BLE-MESH protocol stack is being ported to other platforms, users only need to modify :component_file:`mesh_bearer_adapt.c `. +Portability is fully considered in the implementation of Mesh Bearers. When the ESP-BLE-MESH protocol stack is being ported to other platforms, users only need to modify :component_file:`mesh_bearer_adapt.c ` (example of :component_file:`NimBLE version `). .. list-table:: Table 2.5 Mesh Bearers File Description :widths: 40 150 @@ -330,12 +330,12 @@ Portability is fully considered in the implementation of Mesh Bearers. When the * - File - Functionality - * - :component_file:`mesh_bearer_adapt.c ` + * - :component_file:`mesh_bearer_adapt.c ` - ESP-BLE-MESH Bearer Layer adapter，This file provides the interfaces used to receive and send ESP-BLE-MESH ADV & GATT related packets. .. note:: - :component_file:`mesh_bearer_adapt.c ` is the implementation of ``Advertising Bearer`` and ``GATT Bearer`` in Mesh Networking framework. + :component_file:`mesh_bearer_adapt.c ` is the implementation of ``Advertising Bearer`` and ``GATT Bearer`` in Mesh Networking framework. 2.3 Mesh Applications Implementation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -385,11 +385,11 @@ When adopting the design of independent module, the two main factors should be c - ESP-BLE-MESH Friend functionality * - :component_file:`net.c ` - ESP-BLE-MESH Relay feature, network creation, IV Update procedure, IV Index recovery procedure, Key Refresh procedure related functionalities - * - :component_file:`proxy.c ` + * - :component_file:`proxy_client.c ` - ESP-BLE-MESH Proxy Server related functionalities - * - :component_file:`provisioner_proxy.c ` + * - :component_file:`proxy_server.c ` - ESP-BLE-MESH Proxy Client related functionalities * - :component_file:`settings.c ` - ESP-BLE-MESH Node NVS storage functionality - * - :component_file:`mesh_main.c ` + * - :component_file:`main.c ` - ESP-BLE-MESH node removal related functionality diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst index 12a35edff9..77a8b1d97c 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst @@ -113,19 +113,19 @@ Mesh Applications """"""""""""""""" * ESP-BLE-MESH Node - * :example:`Tutorial ` - * :example:`Tutorial ` + * :example_file:`Tutorial ` + * :example_file:`Tutorial ` * :example:`Example ` * ESP-BLE-MESH Provisioner - * :example:`Tutorial ` + * :example_file:`Tutorial ` * :example:`Example ` * ESP-BLE-MESH Fast Provisioning - * :example:`Fast Provisioning Client Model Tutorial ` - * :example:`Fast Provisioning Server Model Tutorial ` + * :example_file:`Fast Provisioning Client Model Tutorial ` + * :example_file:`Fast Provisioning Server Model Tutorial ` * :example:`Example ` * `Demo Video `__ * ESP-BLE-MESH and Wi-Fi Coexistence - * :example:`Tutorial ` + * :example_file:`Tutorial ` * :example:`Example ` * `Demo Video `__ * ESP-BLE-MESH Console Commands @@ -144,4 +144,4 @@ Mesh Applications """"""""""""""""" * Fast OTA -* Friendship \ No newline at end of file +* Friendship diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst index 3e610a9a6e..4a13c682a6 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -211,15 +211,15 @@ The following screenshot shows different board with different color on. ESP-BLE-MESH Examples ===================== -* :example:`ESP-BLE-MESH Node OnOff Server ` - shows the use of ESP-BLE-MESH as a node having a Configuration Server model and a Generic OnOff Server model. A ESP-BLE-MESH Provisioner can then provision the unprovisioned device and control a RGB LED representing on/off state, see :example:`example code `. +* :example_file:`ESP-BLE-MESH Node OnOff Server ` - shows the use of ESP-BLE-MESH as a node having a Configuration Server model and a Generic OnOff Server model. A ESP-BLE-MESH Provisioner can then provision the unprovisioned device and control a RGB LED representing on/off state, see :example:`example code `. -* :example:`ESP-BLE-MESH Node OnOff Client ` - shows how a Generic OnOff Client model works within a node. The node has a Configuration Server model and a Generic OnOff Client model, see :example:`example code `. +* :example_file:`ESP-BLE-MESH Node OnOff Client ` - shows how a Generic OnOff Client model works within a node. The node has a Configuration Server model and a Generic OnOff Client model, see :example:`example code `. -* :example:`ESP-BLE-MESH Provisioner ` - shows how a device can act as an ESP-BLE-MESH Provisioner to provision devices. The Provisioner has a Configuration Server model, a Configuration Client model and a Generic OnOff Client model, see :example:`example code `. +* :example_file:`ESP-BLE-MESH Provisioner ` - shows how a device can act as an ESP-BLE-MESH Provisioner to provision devices. The Provisioner has a Configuration Server model, a Configuration Client model and a Generic OnOff Client model, see :example:`example code `. -* ESP-BLE-MESH Fast Provisioning - :example:`Client ` and :example:`Server ` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code ` and :example:`example server code `. +* ESP-BLE-MESH Fast Provisioning - :example_file:`Client ` and :example_file:`Server ` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code ` and :example:`example server code `. -* :example:`ESP-BLE-MESH and Wi-Fi Coexistence ` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code `. +* :example_file:`ESP-BLE-MESH and Wi-Fi Coexistence ` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code `. * ESP-BLE-MESH Node Console - an example that implements BLE Mesh node basic features. Within this example a node can be scanned and provisioned by Provisioner and reply to get/set message from Provisioner, see :example:`example node code ` and :example:`example Provisioner code `. diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index e5c2fd62a8..cb5e71c4e9 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -153,7 +153,7 @@ and :cpp:func:`xTaskCreateStatic` have led to the addition of :cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS (see :ref:`backported-features`). -For more details see :component_file:`freertos/task.c` +For more details see :component_file:`freertos/tasks.c` The ESP-IDF FreeRTOS task creation functions are nearly identical to their vanilla counterparts with the exception of the extra parameter known as @@ -397,8 +397,8 @@ The ESP-IDF FreeRTOS critical section functions have been modified as follows… section functions (``port*_CRITICAL`` in Non-ISR and ``port*_CRITICAL_ISR`` in ISR) in order to be in compliance with Vanilla FreeRTOS. -For more details see :component_file:`freertos/include/freertos/portmacro.h` -and :component_file:`freertos/task.c` +For more details see :component_file:`soc/include/soc/spinlock.h` +and :component_file:`freertos/tasks.c` It should be noted that when modifying vanilla FreeRTOS code to be ESP-IDF FreeRTOS compatible, it is trivial to modify the type of critical section @@ -495,12 +495,22 @@ The ESP-IDF FreeRTOS can be configured in the project configuration menu highlights some of the ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` -:ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only -on **PRO_CPU**. Note that this is **not equivalent to running vanilla -FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such -as :component_file:`{IDF_TARGET_PATH_NAME}/cpu_start.c`. For more details regarding the -effects of running ESP-IDF FreeRTOS on a single core, search for -occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components. +.. only:: esp32 + + :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only + on **PRO_CPU**. Note that this is **not equivalent to running vanilla + FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such + as :component_file:`esp32/cpu_start.c`. For more details regarding the + effects of running ESP-IDF FreeRTOS on a single core, search for + occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components. + +.. only:: esp32s2 + + As ESP32-S2 is a single core SoC, the config item :ref:`CONFIG_FREERTOS_UNICORE` is + always set. This means ESP-IDF only runs on the single CPU. Note that this is **not + equivalent to running vanilla FreeRTOS**. Behaviors of multiple components in ESP-IDF + will be modified. For more details regarding the effects of running ESP-IDF FreeRTOS + on a single core, search for occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components. :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` will define the number of Thread Local Storage Pointers each task will have in ESP-IDF diff --git a/docs/en/api-guides/linker-script-generation.rst b/docs/en/api-guides/linker-script-generation.rst index 3c377aef37..4769c9c392 100644 --- a/docs/en/api-guides/linker-script-generation.rst +++ b/docs/en/api-guides/linker-script-generation.rst @@ -427,7 +427,7 @@ will be generated for the target ``flash_text``. These catch-all rules then effectively serve as fallback rules for those whose mappings were not specified. -The ``default scheme`` is defined in :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are +The ``default scheme`` is defined in :component_file:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are built-in schemes referenced in the quick start guide are also defined in this file. @@ -589,5 +589,5 @@ Then the corresponding excerpt from the generated linker script will be as follo it too is placed wherever ``iram0_text`` is referenced by a marker. Since it is a rule generated from the default scheme, it comes first among all other rules collected under the same target name. - The linker script template currently used is :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`, specified by the ``{IDF_TARGET_PATH_NAME}`` component; the + The linker script template currently used is :component_file:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`, specified by the ``{IDF_TARGET_PATH_NAME}`` component; the generated output script is put under its build directory. diff --git a/docs/en/api-guides/lwip.rst b/docs/en/api-guides/lwip.rst index a4497afbfa..75efb7e002 100644 --- a/docs/en/api-guides/lwip.rst +++ b/docs/en/api-guides/lwip.rst @@ -17,7 +17,7 @@ Adapted APIs Some common lwIP "app" APIs are supported indirectly by ESP-IDF: - DHCP Server & Client are supported indirectly via the :doc:`/api-reference/network/esp_netif` functionality -- Simple Network Time Protocol (SNTP) is supported via the :component_file:`lwip/include/apps/sntp/sntp.h` :component_file:`lwip/lwip/src/inlude/lwip/apps/sntp.h` functions (see also :ref:`system-time-sntp-sync`) +- Simple Network Time Protocol (SNTP) is supported via the :component_file:`lwip/include/apps/sntp/sntp.h` :component_file:`lwip/lwip/src/include/lwip/apps/sntp.h` functions (see also :ref:`system-time-sntp-sync`) - ICMP Ping is supported using a variation on the lwIP ping API. See :doc:`/api-reference/protocols/icmp_echo`. - NetBIOS lookup is available using the standard lwIP API. :example:`protocols/http_server/restful_server` has an option to demonstrate using NetBIOS to look up a host on the LAN. - mDNS uses a different implementation to the lwIP default mDNS (see :doc:`/api-reference/protocols/mdns`), but lwIP can look up mDNS hosts using standard APIs such as ``gethostbyname()`` and the convention ``hostname.local``, provided the :ref:`CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES` setting is enabled. @@ -138,7 +138,7 @@ Example:: Socket Error Reason Code ++++++++++++++++++++++++ -Below is a list of common error codes. For more detailed error codes, please query :component:`newlib/include/sys/errno.h` +Below is a list of common error codes. For more detailed list of standard POSIX/C error codes, please see `newlib errno.h ` and the platform-specific extensions :component_file:`newlib/platform_include/errno.h` +-----------------+-------------------------------------+ | Error code | Description | diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 3e675aed80..6ca5f6000d 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1486,7 +1486,7 @@ The table below shows the best throughput results we got in Espressif's lab and | TCP TX | 20 MBit/sec | 50 MBit/sec | iperf example | 05838641 | +----------------------+-----------------+-----------------+---------------+--------------+ -When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.99` +When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.ci.99` Wi-Fi 80211 Packet Send --------------------------- diff --git a/docs/en/api-reference/bluetooth/controller_vhci.rst b/docs/en/api-reference/bluetooth/controller_vhci.rst index 2f98339290..22fb3f7903 100644 --- a/docs/en/api-reference/bluetooth/controller_vhci.rst +++ b/docs/en/api-reference/bluetooth/controller_vhci.rst @@ -11,9 +11,9 @@ Overview Application Example ------------------- -Check :example:`bluetooth/bluedroid/hci` folder in ESP-IDF examples, which contains the following application: +Check :example:`bluetooth/hci` folder in ESP-IDF examples, which contains the following application: -* This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising - :example:`bluetooth/bluedroid/hci/controller_vhci_ble_adv`. +* This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising - :example:`bluetooth/hci/controller_vhci_ble_adv`. API Reference ------------- diff --git a/docs/en/api-reference/network/esp_eth.rst b/docs/en/api-reference/network/esp_eth.rst index 88cd39168f..9edb7c46a9 100644 --- a/docs/en/api-reference/network/esp_eth.rst +++ b/docs/en/api-reference/network/esp_eth.rst @@ -6,8 +6,9 @@ Ethernet Application Example ------------------- -- Ethernet basic example: :example:`ethernet/ethernet`. +- Ethernet basic example: :example:`ethernet/basic`. - Ethernet iperf example: :example:`ethernet/iperf`. +- Ethernet to Wi-Fi AP "router": :example:`ethernet/eth2ap`. Ethernet Driver Model --------------------- diff --git a/docs/en/api-reference/network/esp_netif.rst b/docs/en/api-reference/network/esp_netif.rst index 16c00cc9a2..e51f23a87b 100644 --- a/docs/en/api-reference/network/esp_netif.rst +++ b/docs/en/api-reference/network/esp_netif.rst @@ -141,9 +141,9 @@ ESP-NETIF programmer's manual Please refer to the example section for basic initialization of default interfaces: -- WiFi Station: :example:`wifi/getting_started/station/main/station_example_main.c` -- WiFi Access Point: :example:`wifi/getting_started/softAP/main/softap_example_main.c` -- Ethernet: :example:`ethernet/basic/main/ethernet_example_main.c` +- 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` For more specific cases please consult this guide: :doc:`/api-reference/network/esp_netif_driver`. diff --git a/docs/en/api-reference/network/tcpip_adapter_migration.rst b/docs/en/api-reference/network/tcpip_adapter_migration.rst index 450930c265..4c508b8be9 100644 --- a/docs/en/api-reference/network/tcpip_adapter_migration.rst +++ b/docs/en/api-reference/network/tcpip_adapter_migration.rst @@ -31,9 +31,9 @@ Network interface instance shall be explicitly constructed for the :doc:`/api-re 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: -- WiFi Station: :example:`wifi/getting_started/station/main/station_example_main.c` -- WiFi Access Point: :example:`wifi/getting_started/softAP/main/softap_example_main.c` -- Ethernet: :example:`ethernet/basic/main/ethernet_example_main.c` +- 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 diff --git a/docs/en/api-reference/peripherals/rmt.rst b/docs/en/api-reference/peripherals/rmt.rst index f1efcef120..e27af877a8 100644 --- a/docs/en/api-reference/peripherals/rmt.rst +++ b/docs/en/api-reference/peripherals/rmt.rst @@ -159,7 +159,7 @@ Now, depending on how the channel is configured, we are ready to either `Transmi Transmit Data ------------- -Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. +Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. .. packetdiag:: :caption: Structure of RMT items (L - signal level) @@ -256,7 +256,13 @@ The RMT controller triggers interrupts on four specific events describes below. Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`. -When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, n] and the ``event_name`` is one of four events described above. +.. only:: esp32 + + When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/soc/esp32/include/soc/rmt_struct.h`, where N is the RMT channel number [0, n] and the ``event_name`` is one of four events described above. + +.. only:: esp32s2 + + When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/soc/esp32s2/include/soc/rmt_struct.h`, where N is the RMT channel number [0, n] and the ``event_name`` is one of four events described above. If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`. diff --git a/docs/en/api-reference/peripherals/temp_sensor.rst b/docs/en/api-reference/peripherals/temp_sensor.rst index 9fa4a977cf..89754cb0cb 100644 --- a/docs/en/api-reference/peripherals/temp_sensor.rst +++ b/docs/en/api-reference/peripherals/temp_sensor.rst @@ -25,7 +25,7 @@ The conversion relationship is the first columns of the table below. Among them, Application Example ------------------- -Temperature sensor reading example: :example:`peripherals/temp_sensor`. +Temperature sensor reading example: :example:`peripherals/temp_sensor_esp32s2`. API Reference - Normal Temp Sensor ---------------------------------- diff --git a/docs/en/api-reference/peripherals/timer.rst b/docs/en/api-reference/peripherals/timer.rst index c50701c675..9c0c09257b 100644 --- a/docs/en/api-reference/peripherals/timer.rst +++ b/docs/en/api-reference/peripherals/timer.rst @@ -91,7 +91,7 @@ Registration of the interrupt handler for a specific timer or a timer group can To enable interrupts for a timer group, call :cpp:func:`timer_group_intr_enable`, for a specific timer call :cpp:func:`timer_enable_intr`. To disable interrupts for a timer group, call :cpp:func:`timer_group_intr_disable`, for a specified timer, call :cpp:func:`timer_disable_intr`. -When handling an interrupt within an interrupt serivce routine (ISR), the interrupt status bit needs to be explicitly cleared. To do that, set the ``TIMERGN.{IDF_TARGET_INT_CLR_REG}.tM`` structure, defined in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/timer_group_struct.h`. In this structure, ``N`` is the timer group number [0, 1], ``M`` is the timer number [0, 1]. For example, to clear an interrupt status bit for the timer 1 in the timer group 0, call the following:: +When handling an interrupt within an interrupt serivce routine (ISR), the interrupt status bit needs to be explicitly cleared. To do that, set the ``TIMERGN.{IDF_TARGET_INT_CLR_REG}.tM`` structure, defined in :component_file:`soc/soc/{IDF_TARGET_PATH_NAME}/include/soc/timer_group_struct.h`. In this structure, ``N`` is the timer group number [0, 1], ``M`` is the timer number [0, 1]. For example, to clear an interrupt status bit for the timer 1 in the timer group 0, call the following:: TIMERG0.{IDF_TARGET_INT_CLR_REG}.t1 = 1 diff --git a/docs/en/api-reference/peripherals/uart.rst b/docs/en/api-reference/peripherals/uart.rst index 45b7953daf..e638d8edea 100644 --- a/docs/en/api-reference/peripherals/uart.rst +++ b/docs/en/api-reference/peripherals/uart.rst @@ -238,7 +238,7 @@ By default, the :cpp:func:`uart_driver_install` function installs the driver's i The API provides a convenient way to handle specific interrupts discussed in this document by wrapping them into dedicated functions: -- **Event detection**: There are several events defined in :cpp:type:`uart_event_type_t` that may be reported to a user application using the FreeRTOS queue functionality. You can enable this functionality when calling :cpp:func:`uart_driver_install` described in :ref:`uart-api-driver-installation`. An example of using Event detection can be found in :example:`peripherals/uart_events`. +- **Event detection**: There are several events defined in :cpp:type:`uart_event_type_t` that may be reported to a user application using the FreeRTOS queue functionality. You can enable this functionality when calling :cpp:func:`uart_driver_install` described in :ref:`uart-api-driver-installation`. An example of using Event detection can be found in :example:`peripherals/uart/uart_events`. - **FIFO space threshold or transmission timeout reached**: The Tx and Rx FIFO buffers can trigger an interrupt when they are filled with a specific number of characters, or on a timeout of sending or receiving data. To use these interrupts, do the following: diff --git a/docs/en/api-reference/storage/sdmmc.rst b/docs/en/api-reference/storage/sdmmc.rst index 86aea71708..b3131a46a1 100644 --- a/docs/en/api-reference/storage/sdmmc.rst +++ b/docs/en/api-reference/storage/sdmmc.rst @@ -8,7 +8,7 @@ Overview The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This is a protocol level driver built on top of SDMMC and SD SPI host drivers. -SDMMC and SD SPI host drivers (:component:`driver/include/driver/sdmmc_host.h`) provide API functions for: +SDMMC and SD SPI host drivers (:component_file:`driver/include/driver/sdmmc_host.h`) provide API functions for: - Sending commands to slave devices - Sending and receiving data diff --git a/docs/en/api-reference/storage/wear-levelling.rst b/docs/en/api-reference/storage/wear-levelling.rst index a96571c958..f954f6d4f6 100644 --- a/docs/en/api-reference/storage/wear-levelling.rst +++ b/docs/en/api-reference/storage/wear-levelling.rst @@ -9,7 +9,7 @@ See also Application Example ------------------- -An example which combines the wear levelling driver with the FATFS library is provided in the :example:`storage/wear_levelling` directory. This example initializes the wear levelling driver, mounts FATFS partition, as well as writes and reads data from it using POSIX and C library APIs. See the :example:`storage/wear_levelling/README.md` file for more information. +An example which combines the wear levelling driver with the FATFS library is provided in the :example:`storage/wear_levelling` directory. This example initializes the wear levelling driver, mounts FATFS partition, as well as writes and reads data from it using POSIX and C library APIs. See the :example_file:`storage/wear_levelling/README.md` file for more information. High level API Reference ------------------------ @@ -17,7 +17,7 @@ High level API Reference Header Files ^^^^^^^^^^^^ -* :component_file:`fatfs/src/esp_vfs_fat.h` +* :component_file:`fatfs/vfs/esp_vfs_fat.h` Functions ^^^^^^^^^ diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index 55e858898b..c55680c21e 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -89,7 +89,7 @@ Interrupt Watchdog API Reference Header File ^^^^^^^^^^^ - * :component_file:`{IDF_TARGET_PATH_NAME}/include/esp_int_wdt.h` + * :component_file:`esp_common/include/esp_int_wdt.h` Functions diff --git a/docs/en/api-reference/template.rst b/docs/en/api-reference/template.rst index 258b0e7a00..b536d875db 100644 --- a/docs/en/api-reference/template.rst +++ b/docs/en/api-reference/template.rst @@ -5,7 +5,7 @@ API Documentation Template *INSTRUCTIONS* - 1. Use this file (:idf_file:`docs/api-reference/template.rst`) as a template to document API. + 1. Use this file (:idf_file:`docs/en/api-reference/template.rst`) as a template to document API. 2. Change the file name to the name of the header file that represents documented API. 3. Include respective files with descriptions from the API folder using ``..include::`` @@ -61,9 +61,9 @@ API Reference 1. This repository provides for automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`. - 2. Update is done on each documentation build by invoking script :idf_file:`docs/gen-dxd.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/Doxyfile`. - - 3. Each line of the ``INPUT`` statement (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that will be used to generate corresponding ``*.inc`` files:: + 1. Update is done on each documentation build by invoking Sphinx extension :idf_file:`docs/idf_extensions/run_doxygen.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/Doxyfile`. + + 1. Each line of the ``INPUT`` statement (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that will be used to generate corresponding ``*.inc`` files:: ## ## Wi-Fi - API Reference @@ -71,15 +71,17 @@ API Reference ../components/esp32/include/esp_wifi.h \ ../components/esp32/include/esp_smartconfig.h \ - 4. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g. ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``. + 1. When the headers are expanded, any macros defined by default in ``sdkconfig.h`` as well as any macros defined in SOC-specific ``include/soc/*_caps.h`` headers will be expanded. This allows the headers to include/exclude material based on the ``IDF_TARGET`` value. - 5. To show contents of ``*.inc`` file in documentation, include it as follows:: + 1. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g. ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``. + + 1. To show contents of ``*.inc`` file in documentation, include it as follows:: .. include-build-file:: inc/esp_wifi.inc - For example see :idf_file:`docs/en/api-reference/wifi/esp_wifi.rst` + For example see :idf_file:`docs/en/api-reference/network/esp_wifi.rst` - 6. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp.rst` for example. + 1. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp.rst` for example. Below is the list of common ``.. doxygen...::`` directives: @@ -96,6 +98,6 @@ API Reference * :component_file:`path_to/header_file.h` - 7. In any case, to generate API reference, the file :idf_file:`docs/Doxyfile` should be updated with paths to ``*.h`` headers that are being documented. + 1. In any case, to generate API reference, the file :idf_file:`docs/Doxyfile` should be updated with paths to ``*.h`` headers that are being documented. - 8. When changes are committed and documentation is build, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required. + 1. When changes are committed and documentation is build, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required. diff --git a/docs/en/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst b/docs/en/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst index 2965319936..fed47be2de 100644 --- a/docs/en/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst +++ b/docs/en/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst @@ -354,7 +354,7 @@ Move on to the next section only if you have successfully completed all the abov Configure and Load the Ethernet Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/ethernet` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`ESP32-Ethernet-Kit V1.0 board `. +After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/basic` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`ESP32-Ethernet-Kit V1.0 board `. Related Documents diff --git a/docs/en/hw-reference/esp32/get-started-ethernet-kit.rst b/docs/en/hw-reference/esp32/get-started-ethernet-kit.rst index c0d149f76a..9c18f5926d 100644 --- a/docs/en/hw-reference/esp32/get-started-ethernet-kit.rst +++ b/docs/en/hw-reference/esp32/get-started-ethernet-kit.rst @@ -359,7 +359,7 @@ Move on to the next section only if you have successfully completed all the abov Configure and Load the Ethernet Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/ethernet` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`get-started-esp32-ethernet-kit-v1.1`. +After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/basic` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`get-started-esp32-ethernet-kit-v1.1`. Summary of Changes from ESP32-Ethernet-Kit V1.0 diff --git a/docs/idf_extensions/link_roles.py b/docs/idf_extensions/link_roles.py index 5d8728f653..bf7fc7a620 100644 --- a/docs/idf_extensions/link_roles.py +++ b/docs/idf_extensions/link_roles.py @@ -25,16 +25,15 @@ def setup(app): rev = get_github_rev() # links to files or folders on the GitHub - baseurl = 'https://github.com/espressif/esp-idf' - app.add_role('idf', autolink('{}/tree/{}/%s'.format(baseurl, rev))) - app.add_role('idf_file', autolink('{}/blob/{}/%s'.format(baseurl, rev))) - app.add_role('idf_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev))) - app.add_role('component', autolink('{}/tree/{}/components/%s'.format(baseurl, rev))) - app.add_role('component_file', autolink('{}/blob/{}/components/%s'.format(baseurl, rev))) - app.add_role('component_raw', autolink('{}/raw/{}/components/%s'.format(baseurl, rev))) - app.add_role('example', autolink('{}/tree/{}/examples/%s'.format(baseurl, rev))) - app.add_role('example_file', autolink('{}/blob/{}/examples/%s'.format(baseurl, rev))) - app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev))) + app.add_role('idf', github_link('tree', rev, '/', app.config)) + app.add_role('idf_file', github_link('blob', rev, '/', app.config)) + app.add_role('idf_raw', github_link('raw', rev, '/', app.config)) + app.add_role('component', github_link('tree', rev, '/components/', app.config)) + app.add_role('component_file', github_link('blob', rev, '/components/', app.config)) + app.add_role('component_raw', github_link('raw', rev, '/components/', app.config)) + app.add_role('example', github_link('tree', rev, '/examples/', app.config)) + app.add_role('example_file', github_link('blob', rev, '/examples/', app.config)) + app.add_role('example_raw', github_link('raw', rev, '/examples/', app.config)) # link to the current documentation file in specific language version on_rtd = os.environ.get('READTHEDOCS', None) == 'True' @@ -49,21 +48,72 @@ def setup(app): app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev))) - return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.2'} -def autolink(pattern): +def github_link(link_type, rev, root_path, app_config): def role(name, rawtext, text, lineno, inliner, options={}, content=[]): - m = re.search('(.*)\s*<(.*)>', text) # noqa: W605 - regular expression + msgs = [] + + def warning(msg): + system_msg = inliner.reporter.warning(msg) + system_msg.line = lineno + msgs.append(system_msg) + + BASE_URL = 'https://github.com/espressif/esp-idf' + + # search for a named link (:label) with descriptive label vs a plain URL + m = re.search(r'(.*)\s*<(.*)>', text) if m: link_text = m.group(1) link = m.group(2) else: link_text = text link = text - url = pattern % (link,) + + rel_path = root_path + link + abs_path = os.path.join(app_config.idf_path, rel_path.lstrip('/')) + line_no = None + url = BASE_URL + link_type + rel_path + + if '#L' in abs_path: + # drop any URL line number from the file, line numbers take the form #Lnnn or #Lnnn-Lnnn for a range + abs_path, line_no = abs_path.split('#L') + line_no = re.search(r'^(\d+)(?:-L(\d+))?', line_no) + if line_no is None: + warning("Line number anchor in URL %s doesn't seem to be valid" % link) + else: + line_no = tuple(int(l) for l in line_no.groups() if l) # tuple of (nnn,) or (nnn, NNN) for ranges + elif '#' in abs_path: # drop any other anchor from the line + abs_path = abs_path.split('#')[0] + warning("URL %s seems to contain an unusable anchor after the #, only line numbers are supported" % link) + + is_dir = (link_type == 'tree') + + if not os.path.exists(abs_path): + warning("IDF path %s does not appear to exist (absolute path %s)" % (rel_path, abs_path)) + elif is_dir and not os.path.isdir(abs_path): + # note these "wrong type" warnings are not strictly needed as GitHub will apply a redirect, + # but the may become important in the future (plus make for cleaner links) + warning("IDF path %s is not a directory but role :%s: is for linking to a directory, try :%s_file:" % (rel_path, name, name)) + elif not is_dir and os.path.isdir(abs_path): + warning("IDF path %s is a directory but role :%s: is for linking to a file" % (rel_path, name)) + + # check the line number is valid + if line_no: + if is_dir: + warning("URL %s contains a line number anchor but role :%s: is for linking to a directory" % (rel_path, name, name)) + elif os.path.exists(abs_path) and not os.path.isdir(abs_path): + with open(abs_path, "r") as f: + lines = len(f.readlines()) + if any(True for l in line_no if l > lines): + warning("URL %s specifies a range larger than file (file has %d lines)" % (rel_path, lines)) + + if tuple(sorted(line_no)) != line_no: # second line number comes before first one! + warning("URL %s specifies a backwards line number range" % rel_path) + node = nodes.reference(rawtext, link_text, refuri=url, **options) - return [node], [] + return [node], msgs return role diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 04baf23dc9..a2ea9888f8 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -480,7 +480,7 @@ project 函数 - 将最终的应用程序可执行文件添加到构建系统中。 - 返回并为组件之间指定依赖关系（将每个组件的公共头文件目录添加到其他组件中）。 -更多详细信息请参阅 :idf_file:`/tools/cmake/project.cmake` 文件和 :idf_file:`/tools/cmake/idf_functions.cmake` 文件。 +更多详细信息请参阅 :idf_file:`/tools/cmake/project.cmake` 文件。 CMake 调试 ---------- @@ -860,45 +860,6 @@ CMake 在许多开源的 C/C++ 项目中广泛使用，用户可以在自己的 ESP-IDF 提供了一个模板 CMake 项目，可以基于此轻松创建应用程序。然而在有些情况下，用户可能已有一个现成的 CMake 项目，或者想自己创建一个 CMake 项目，此时就希望将 IDF 中的组件以库的形式链接到用户目标（库/可执行文件）。 -.. highlight:: cmake - -使用 :idf_file:`tools/cmake/idf_functions.cmake` 中提供的 ``idf_import_components`` 和 ``idf_link_components`` 函数可以实现上述功能，例如:: - - cmake_minimum_required(VERSION 3.5) - project(my_custom_app C) - - # 源文件 main.c 包含有 app_main() 函数的定义 - add_executable(${CMAKE_PROJECT_NAME}.elf main.c) - - # 提供 idf_import_components 及 idf_link_components 函数 - include($ENV{IDF_PATH}/tools/cmake/idf_functions.cmake) - - # 为 idf_import_components 做一些配置 - # 使能创建构件（不是每个项目都必须） - set(IDF_BUILD_ARTIFACTS ON) - set(IDF_PROJECT_EXECUTABLE ${CMAKE_PROJECT_NAME}.elf) - set(IDF_BUILD_ARTIFACTS_DIR ${CMAKE_BINARY_DIR}) - - # idf_import_components 封装了 add_subdirectory()，为组件创建库目标，然后使用给定的变量接收“返回”的库目标。 - # 在本例中，返回的库目标被保存在“component”变量中。 - idf_import_components(components $ENV{IDF_PATH} esp-idf) - - # idf_link_components 封装了 target_link_libraries()，将被 idf_import_components 处理过的组件链接到目标 - idf_link_components(${CMAKE_PROJECT_NAME}.elf "${components}") - -上述代码片段导入了 ESP-IDF 目录下的所有组件，并使用了 KConfig 中的默认值，同时还允许创建其它一些构件（比如分区表、包含项目信息的 json 文件、引导程序等）。除此以外，用户还可以设置其它的构建参数，其完整列表如下： - -- ``IDF_BUILD_ARTIFACTS``：构建工件，例如引导加载程序、分区表二进制文件、分区二进制数据、将二进制文件烧录到目标芯片时所需的包含项目信息的 json 文件等。同时需要设置 ``IDF_PROJECT_EXECUTABLE`` 和 ``IDF_BUILD_ARTIFACTS_DIR`` 变量。 -- ``IDF_PROJECT_EXECUTABLE``：最终可执行文件的名称。某些工件在创建的时候需要此参数。 -- ``IDF_BUILD_ARTIFACTS_DIR``：创建的构件被存放的位置。 -- ``IDF_EXTRA_COMPONENTS_DIR``：在 :idf:`默认组件目录 ` 之外的组件搜索路径。 -- ``IDF_COMPONENTS``：要导入的组件列表，设置此变量可以精简导入的组件，仅导入需要的组件，加快构建的速度。如果没有设置该变量，将会导入默认组件目录以及 ``IDF_EXTRA_COMPONENTS_DIR`` （如果设置了该变量）中找到的所有组件。请注意，该列表中组件的依赖组件（除了 ``IDF_COMPONENT_REQUIRES_COMMON`` 之外）也会被加入到构建之中。 -- ``IDF_COMPONENT_REQUIRES_COMMON``：通用组件依赖列表。无论 ``IDF_COMPONENTS`` 的值是什么，此列表中的组件及其依赖组件都会被导入到构建中。默认情况下，此变量被设置为核心“系统”组件的最小集合。 -- ``IDF_SDKCONFIG_DEFAULTS``：配置文件的覆盖路径，如果未设置，组件将会使用默认的配置选项来构建。 -- ``IDF_BUILD_TESTS``：在构建中包含组件的测试。默认情况下，所有的组件测试都会被包含。组件测试可通过 ``IDF_TEST_COMPONENTS`` 和 ``IDF_TEST_EXCLUDE_COMPONENTS`` 进行过滤。 -- ``IDF_TEST_COMPONENTS``：如果设置了 ``IDF_BUILD_TESTS``，构建中只会包含此列表中的组件测试。如果没有设置 ``IDF_BUILD_TESTS``，请忽略此项。 -- ``IDF_TEST_EXCLUDE_COMPONENTS``：如果设置了 ``IDF_BUILD_TESTS``，此列表中的组件测试将不会包含在构建中。如果没有设置 ``IDF_BUILD_TESTS``，请忽略此项。该变量的优先级高于 ``IDF_TEST_COMPONENTS``，这意味着，即使 ``IDF_TEST_COMPONENTS`` 中也存在此列表中的组件测试，它也不会被包含到构建之中。 - :example:`build_system/cmake/idf_as_lib` 中的示例演示了如何在自定义的 CMake 项目创建一个类似于 :example:`Hello World ` 的应用程序。 .. _cmake-file-globbing: diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst index 8bd54a0bbe..5128b4c150 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst @@ -262,7 +262,7 @@ ESP-BLE-MESH 架构采用分层的方式进行设计，数据包的处理所经 - 功能 * - :component_file:`prov.c ` - BLE Mesh 节点配网 (PB-ADV & PB-GATT) - * - :component_file:`proxy.c ` + * - :component_file:`proxy_client.c ` - BLE Mesh 节点代理相关功能 * - :component_file:`beacon.c ` - 用于处理 BLE Mesh Beacon 的 API @@ -277,7 +277,7 @@ ESP-BLE-MESH 架构采用分层的方式进行设计，数据包的处理所经 - 功能 * - :component_file:`provisioner_prov.c ` - BLE Mesh Provisioner 配置入网 (PB-ADV & PB-GATT) - * - :component_file:`provisioner_proxy.c ` + * - :component_file:`proxy_server.c ` - BLE Mesh 代理客户端相关功能 * - :component_file:`provisioner_beacon.c ` - BLE Mesh Provisioner 接收 Unprovisioned Device Beacon @@ -315,7 +315,7 @@ Mesh Models 用于实现节点中所包含的模型的具体功能。服务器 2.2 Mesh Bearers 实现 ^^^^^^^^^^^^^^^^^^^^^ -Mesh Bearers 在实现时充分考虑了可移植性。当 ESP-BLE-MESH 协议栈需要移植到其它平台时，用户只需要修改 :component_file:`mesh_bearer_adapt.c ` 就能移植成功。 +Mesh Bearers 在实现时充分考虑了可移植性。当 ESP-BLE-MESH 协议栈需要移植到其它平台时，用户只需要修改 :component_file:`mesh_bearer_adapt.c ` 就能移植成功。 .. list-table:: 表 2.5 Mesh Bearers 文件描述 :widths: 40 150 @@ -323,12 +323,12 @@ Mesh Bearers 在实现时充分考虑了可移植性。当 ESP-BLE-MESH 协议 * - 文件 - 功能 - * - :component_file:`mesh_bearer_adapt.c ` + * - :component_file:`mesh_bearer_adapt.c ` - BLE Mesh 承载层适配文件。此文件提供用于接收和发送 BLE Mesh ADV 和 GATT 相关数据包的接口。 .. note:: - :component_file:`mesh_bearer_adapt.c ` 是对 Mesh 网络框架中 ``Advertising Bearer`` 和 ``GATT Bearer`` 的实现。 + :component_file:`mesh_bearer_adapt.c ` 是对 Mesh 网络框架中 ``Advertising Bearer`` 和 ``GATT Bearer`` 的实现。 2.3 Mesh Applications 实现 ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -378,11 +378,11 @@ Mesh Bearers 在实现时充分考虑了可移植性。当 ESP-BLE-MESH 协议 - BLE Mesh 好友功能 * - :component_file:`net.c ` - BLE Mesh 中继功能、网络创建、网络索引更新程序、网络索引恢复程序、秘钥更新程序相关功能 - * - :component_file:`proxy.c ` + * - :component_file:`proxy_client.c ` - BLE Mesh 代理服务器相关功能 - * - :component_file:`provisioner_proxy.c ` + * - :component_file:`proxy_server.c ` - BLE Mesh 代理客户端相关功能 * - :component_file:`settings.c ` - BLE Mesh 节点 NVS 存储器功能 - * - :component_file:`mesh_main.c ` + * - :component_file:`main.c ` - BLE Mesh 节点移除相关功能 diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst index 31d02f14cc..0865d35290 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -212,15 +212,15 @@ Step 5. 运行网络 ESP-BLE-MESH 示例 =================== -* :example:`ESP-BLE-MESH 节点 ` - 展示了将 ESP-BLE-MESH 作为拥有 Configuration Server model 和 Generic OnOff Server model 的节点设备的用法。然后，ESP-BLE-MESH Provisioner 可以配网设备，控制表示开/关状态的 RGB 灯，示例请见 :example:`example code `。 +* :example_file:`ESP-BLE-MESH 节点 ` - 展示了将 ESP-BLE-MESH 作为拥有 Configuration Server model 和 Generic OnOff Server model 的节点设备的用法。然后，ESP-BLE-MESH Provisioner 可以配网设备，控制表示开/关状态的 RGB 灯，示例请见 :example:`example code `。 -* :example:`ESP-BLE-MESH 客户端模型 ` - 展示了 Generic OnOff Client model 如何在节点内工作。节点拥有 Configuration Server model、Generic OnOff Server model 和 Generic OnOff Client model，示例请见：:example:`example code `。 +* :example_file:`ESP-BLE-MESH 客户端模型 ` - 展示了 Generic OnOff Client model 如何在节点内工作。节点拥有 Configuration Server model、Generic OnOff Server model 和 Generic OnOff Client model，示例请见：:example:`example code `。 -* :example:`ESP-BLE-MESH Provisioner ` - 展示了设备如何充当 ESP-BLE-MESH Provisioner 以配网设备。Provisioner 拥有 Configuration Server model、Configuration Client model 和 Generic OnOff Client model，示例请见 :example:`example code `。 +* :example_file:`ESP-BLE-MESH Provisioner ` - 展示了设备如何充当 ESP-BLE-MESH Provisioner 以配网设备。Provisioner 拥有 Configuration Server model、Configuration Client model 和 Generic OnOff Client model，示例请见 :example:`example code `。 -* ESP-BLE-MESH 快速配网 - :example:`Client ` 和 :example:`Server ` - 该示例用于演示快速配网。配网 100 个设备费时不超过 60 秒，示例请见：:example:`example client code ` 和 :example:`example server code `。 +* ESP-BLE-MESH 快速配网 - :example_file:`Client ` 和 :example_file`Server ` - 该示例用于演示快速配网。配网 100 个设备费时不超过 60 秒，示例请见：:example:`example client code ` 和 :example:`example server code `。 -* :example:`Wi-Fi 和 ESP-BLE-MESH 共存 ` - 该示例用于演示 Wi-Fi 和 ESP-BLE-MESH 共存的功能。简而言之，用户可在运行 ESP-BLE-MESH 时使用 Wi-Fi，示例请见 :example:`example code `。 +* :example_file:`Wi-Fi 和 ESP-BLE-MESH 共存 ` - 该示例用于演示 Wi-Fi 和 ESP-BLE-MESH 共存的功能。简而言之，用户可在运行 ESP-BLE-MESH 时使用 Wi-Fi，示例请见 :example:`example code `。 * ESP-BLE-MESH 节点控制台 - 该演示实现 ESP-BLE-MESH 节点的基本功能。在演示中，Provisioner 可以扫描、验证节点，节点可以回复 Provisioner 的获取/设置消息，示例请见：:example:`example node code ` 和 :example:`example provisioner code `。 diff --git a/docs/zh_CN/api-guides/linker-script-generation.rst b/docs/zh_CN/api-guides/linker-script-generation.rst index d639b5f1de..8e87c238ab 100644 --- a/docs/zh_CN/api-guides/linker-script-generation.rst +++ b/docs/zh_CN/api-guides/linker-script-generation.rst @@ -292,7 +292,7 @@ scheme 片段定义了为每个 sections 指定的 ``target``。 .. note:: - ``default`` scheme 是在 :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf` 文件中定义的，此外，快速上手指南中提到的内置 ``noflash`` scheme 片段和 ``rtc`` scheme 片段也是在这个文件中定义的。 + ``default`` scheme 是在 :component_file:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf` 文件中定义的，此外，快速上手指南中提到的内置 ``noflash`` scheme 片段和 ``rtc`` scheme 片段也是在这个文件中定义的。 .. _ldgen-mapping-fragment : @@ -491,7 +491,7 @@ mapping 片段的映射条目共有三种类型，分别为： 链接脚本模板 ^^^^^^^^^^^^ -目前使用的链接脚本模板是 :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`，仅用于应用程序的构建，生成的链接脚本文件将放在同一组件的构建目录下。值得注意的是，修改此链接描述文件模板会触发应用程序的二进制文件的重新链接。 +目前使用的链接脚本模板是 :component_file:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`，仅用于应用程序的构建，生成的链接脚本文件将放在同一组件的构建目录下。值得注意的是，修改此链接描述文件模板会触发应用程序的二进制文件的重新链接。 链接片段文件 ^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-reference/network/esp_eth.rst b/docs/zh_CN/api-reference/network/esp_eth.rst index 1ed85dca63..977a7377e3 100644 --- a/docs/zh_CN/api-reference/network/esp_eth.rst +++ b/docs/zh_CN/api-reference/network/esp_eth.rst @@ -6,7 +6,7 @@ 应用示例 ------------------- -- 以太网基本示例：:example:`ethernet/ethernet`. +- 以太网基本示例：:example:`ethernet/basic`. - 以太网 iperf 示例：:example:`ethernet/iperf`. 以太网驱动程序模型 diff --git a/docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst b/docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst index 5b28ed80c9..ad9cbf689c 100644 --- a/docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst +++ b/docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst @@ -32,9 +32,9 @@ TCP/IP 适配器静态定义了三个接口： 。 请参阅这三个接口的初始化代码示例： -- Wi-Fi Station: :example:`wifi/getting_started/station/main/station_example_main.c` -- Wi-Fi AP: :example:`wifi/getting_started/softAP/main/softap_example_main.c` -- 以太网: :example:`ethernet/basic/main/ethernet_example_main.c` +- Wi-Fi Station: :example_file:`wifi/getting_started/station/main/station_example_main.c` +- Wi-Fi AP: :example_file:`wifi/getting_started/softAP/main/softap_example_main.c` +- 以太网: :example_file:`ethernet/basic/main/ethernet_example_main.c` 更换其他 tcpip_adapter API diff --git a/docs/zh_CN/api-reference/peripherals/timer.rst b/docs/zh_CN/api-reference/peripherals/timer.rst index e5dce607e8..f432cd8b5e 100644 --- a/docs/zh_CN/api-reference/peripherals/timer.rst +++ b/docs/zh_CN/api-reference/peripherals/timer.rst @@ -89,7 +89,7 @@ ESP32 芯片提供两组硬件定时器，每组包含两个通用硬件定时 调用 :cpp:func:`timer_group_intr_enable` 使能定时器组的中断程序，调用 :cpp:func:`timer_enable_intr` 使能某定时器的中断程序。调用 :cpp:func:`timer_group_intr_disable` 关闭定时器组的中断程序，调用 :cpp:func:`timer_disable_intr` 关闭某定时器的中断程序。 -在中断服务程序（ISR）中处理中断时，需要明确地清除中断状态位。为此，请设置定义在 :component_file:`soc/esp32/include/soc/timer_group_struct.h` 中的 ``TIMERGN.int_clr_timers.tM`` 结构。该结构中 ``N`` 是定时器组别编号 [0, 1]，``M`` 是定时器编号 [0, 1]。例如，要清除定时器组别 0 中定时器 1 的中断状态位，请调用以下命令:: +在中断服务程序（ISR）中处理中断时，需要明确地清除中断状态位。为此，请设置定义在 :component_file:`soc/soc/esp32/include/soc/timer_group_struct.h` 中的 ``TIMERGN.int_clr_timers.tM`` 结构。该结构中 ``N`` 是定时器组别编号 [0, 1]，``M`` 是定时器编号 [0, 1]。例如，要清除定时器组别 0 中定时器 1 的中断状态位，请调用以下命令:: TIMERG0.int_clr_timers.t1 = 1 diff --git a/docs/zh_CN/api-reference/storage/sdmmc.rst b/docs/zh_CN/api-reference/storage/sdmmc.rst index e9af6a3d63..446ff64484 100644 --- a/docs/zh_CN/api-reference/storage/sdmmc.rst +++ b/docs/zh_CN/api-reference/storage/sdmmc.rst @@ -8,7 +8,7 @@ SD/SDIO/MMC 驱动程序 SD/SDIO/MMC 驱动是一种基于 SDMMC 和 SD SPI 主机驱动的协议级驱动程序，目前已支持 SD 存储器、SDIO 卡和 eMMC 芯片。 -SDMMC 主机驱动和 SD SPI 主机驱动（:component:`driver/include/driver/sdmmc_host.h`）为以下功能提供 API： +SDMMC 主机驱动和 SD SPI 主机驱动（:component_file:`driver/include/driver/sdmmc_host.h`）为以下功能提供 API： - 发送命令至从设备 - 接收和发送数据 diff --git a/docs/zh_CN/api-reference/storage/wear-levelling.rst b/docs/zh_CN/api-reference/storage/wear-levelling.rst index 86b5eea55f..bd4e98ab99 100644 --- a/docs/zh_CN/api-reference/storage/wear-levelling.rst +++ b/docs/zh_CN/api-reference/storage/wear-levelling.rst @@ -9,7 +9,7 @@ 应用示例 ------------------- -:example:`storage/wear_levelling` 中提供了一款磨损均衡驱动与 FatFs 库结合使用的示例。该示例初始化磨损均衡驱动，挂载 FAT 文件系统分区，并使用 POSIX（可移植操作系统接口）和 C 库 API 从中写入和读取数据。如需了解更多信息，请参考 :example:`storage/wear_levelling/README.md`。 +:example:`storage/wear_levelling` 中提供了一款磨损均衡驱动与 FatFs 库结合使用的示例。该示例初始化磨损均衡驱动，挂载 FAT 文件系统分区，并使用 POSIX（可移植操作系统接口）和 C 库 API 从中写入和读取数据。如需了解更多信息，请参考 :example_file:`storage/wear_levelling/README.md`。 高级 API 参考 ------------------------ @@ -17,7 +17,7 @@ 头文件 ^^^^^^^^^^^^ -* :component_file:`fatfs/src/esp_vfs_fat.h` +* :component_file:`fatfs/vfs/esp_vfs_fat.h` 函数 ^^^^^^^^^ diff --git a/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst b/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst index 01731a327e..eae0da8eb8 100644 --- a/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst @@ -350,7 +350,7 @@ ESP32-Ethernet-Kit 上电前，请首先确认开发板完好无损。 配置与加载以太网示例 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -在完成开发环境设置和开发板测试后，您可以配置并烧录 :example:`ethernet/ethernet` 示例。本示例专门用于测试以太网功能，支持不同 PHY，包括 :ref:`ESP32-Ethernet-Kit V1.0 开发板 ` 使用的 **IP101GRI**。 +在完成开发环境设置和开发板测试后，您可以配置并烧录 :example:`ethernet/basic` 示例。本示例专门用于测试以太网功能，支持不同 PHY，包括 :ref:`ESP32-Ethernet-Kit V1.0 开发板 ` 使用的 **IP101GRI**。 相关文档