From 389cef7739528d571f435a6a06ecd9199ac4b8e8 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Fri, 1 Apr 2022 11:54:56 +0800 Subject: [PATCH 1/6] docs: update esp-docs 1.0.0 Update esp-docs to 1.0.0 and fix new warnings introduced from update --- docs/doxygen/Doxyfile | 1 + docs/requirements.txt | 2 +- docs/sphinx-known-warnings.txt | 90 +++++++++++++--------------------- 3 files changed, 35 insertions(+), 58 deletions(-) diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index d90f9310b2..3e413a3d48 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -253,6 +253,7 @@ PREDEFINED = \ configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \ configUSE_APPLICATION_TASK_TAG=1 \ configTASKLIST_INCLUDE_COREID=1 \ + PRIVILEGED_FUNCTION= \ "ESP_EVENT_DECLARE_BASE(x)=extern esp_event_base_t x" ## Do not complain about not having dot diff --git a/docs/requirements.txt b/docs/requirements.txt index 16bd54ca82..d6c84d9212 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1 @@ -esp-docs==0.1.1 +esp-docs~=1.0.0 diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index e7f9301603..a8a50570fe 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -6,76 +6,52 @@ # # Warnings in this file must be in the same overall order as the log file. # -# -# Breathe known issue: https://github.com/michaeljones/breathe/issues/405 -# Sphinx known issue: https://github.com/sphinx-doc/sphinx/pull/5901 -# -# Note: warnings below have been identified after upgrade -# to the following package==version -# -# sphinx==1.8.4 -# breathe==4.11.1 -# -ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) -ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) -ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) -ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) -ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) -ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) -ulp-risc-v.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) -README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) - - -# This seems like a bug, as the field are ::model_id and ::vnd::model_id -esp_ble_mesh_defs.inc:line: WARNING: Duplicate declaration, uint16_t esp_ble_mesh_model::model_id -WARNING:esp_bt_defs, use :noindex: for one of them -WARNING:esp_blufi, use :noindex: for one of them -esp_bt_defs.inc:line: WARNING: Duplicate declaration, uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN] - -# -# Issue present only when building on msys2 / mingw32 START >>> -# +esp_ble_mesh_defs.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/bluetooth/esp-ble-mesh:line. +Declaration is '.. cpp:member:: uint16_t model_id'. +esp_bt_defs.inc:line: WARNING: Duplicate C declaration, also defined at api-reference/bluetooth/esp_blufi:line. +Declaration is '.. c:macro:: ESP_BD_ADDR_LEN'. +esp_bt_defs.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/bluetooth/esp_blufi:line. +Declaration is '.. cpp:type:: uint8_t esp_bd_addr_t [ESP_BD_ADDR_LEN]'. esp_spp_api.inc:line: WARNING: Error in type declaration. If typedef-like declaration: Type must be either just a name or a typedef-like declaration. If just a name: - Error in declarator or parameters and qualifiers - Invalid definition: Expected identifier in nested name, got keyword: void [error at 4] - void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param) + Error in declarator or parameters-and-qualifiers + Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 4] + void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param) ----^ If typedef-like declaration: Error in declarator - If pointer to member declarator: - Invalid definition: Expected identifier in nested name. [error at 4] - void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param) - ----^ - If declId, parameters, and qualifiers: - Invalid definition: Expected identifier in nested name. [error at 4] - void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param) + If declarator-id with parameters-and-qualifiers: + Invalid C++ declaration: Expected identifier in nested name. [error at 4] + void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param) ----^ If parenthesis in noptr-declarator: - Error in declarator or parameters and qualifiers + Error in declarator or parameters-and-qualifiers If pointer to member declarator: - Invalid definition: Expected identifier in nested name. [error at 5] - void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param) + Invalid C++ declaration: Expected identifier in nested name. [error at 5] + void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param) -----^ If declarator-id: - Invalid definition: Expected identifier in nested name. [error at 5] - void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param) + Invalid C++ declaration: Expected identifier in nested name. [error at 5] + void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param) -----^ If type alias or template alias: - Invalid definition: Expected identifier in nested name, got keyword: void [error at 4] - void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param) + Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 4] + void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param) ----^ -# -# Issue present only when building on msys2 / mingw32 END <<< -# -spi_master.inc:line: WARNING: Duplicate declaration, struct spi_transaction_t spi_transaction_t -spi_slave.inc:line: WARNING: Duplicate declaration, struct spi_slave_transaction_t spi_slave_transaction_t -esp_flash.inc:line: WARNING: Duplicate declaration, struct esp_flash_t esp_flash_t -spi_flash_types.inc:line: WARNING: Duplicate declaration, struct spi_flash_host_driver_t spi_flash_host_driver_t -wear-levelling.rst:line: WARNING: Duplicate declaration, bool esp_vfs_fat_mount_config_t::format_if_mount_failed -wear-levelling.rst:line: WARNING: Duplicate declaration, int esp_vfs_fat_mount_config_t::max_files -wear-levelling.rst:line: WARNING: Duplicate declaration, size_t esp_vfs_fat_mount_config_t::allocation_unit_size -wear-levelling.rst:line: WARNING: Duplicate declaration, esp_vfs_fat_mount_config_t +spi_master.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/peripherals/spi_master:line. +Declaration is '.. cpp:type:: struct spi_transaction_t spi_transaction_t'. +spi_slave.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/peripherals/spi_slave:line. +Declaration is '.. cpp:type:: struct spi_slave_transaction_t spi_slave_transaction_t'. +esp_flash.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/spi_flash:line. +Declaration is '.. cpp:type:: struct esp_flash_t esp_flash_t'. +wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line. +Declaration is '.. cpp:struct:: esp_vfs_fat_mount_config_t'. +wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line. +Declaration is '.. cpp:member:: bool format_if_mount_failed'. +wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line. +Declaration is '.. cpp:member:: int max_files'. +wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line. +Declaration is '.. cpp:member:: size_t allocation_unit_size'. From 116eda0bd22cac53c8122fdb68baa8d3ec062b71 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Mon, 25 Apr 2022 14:56:01 +0800 Subject: [PATCH 2/6] CI: update esp-idf-doc-env docker image version --- .gitlab-ci.yml | 2 +- .gitlab/ci/docs.yml | 18 ++++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 532af3812b..2d6ec408f7 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -56,7 +56,7 @@ variables: # Docker images BOT_DOCKER_IMAGE_TAG: ":latest" - ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v4.4-1-v5" + ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v4.4-1-v6" ESP_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-env:v4.4-1" AFL_FUZZER_TEST_IMAGE: "$CI_DOCKER_REGISTRY/afl-fuzzer-test:v4.4-1-1" CLANG_STATIC_ANALYSIS_IMAGE: "${CI_DOCKER_REGISTRY}/clang-static-analysis:v4.4-1-2" diff --git a/.gitlab/ci/docs.yml b/.gitlab/ci/docs.yml index 4292c5f0df..222cdf2083 100644 --- a/.gitlab/ci/docs.yml +++ b/.gitlab/ci/docs.yml @@ -58,13 +58,14 @@ check_docs_lang_sync: .build_docs_template: image: $ESP_IDF_DOC_ENV_IMAGE variables: - PYTHON_VER: 3.6.13 + PYTHON_VER: 3.7.10 tags: - build_docs dependencies: [] script: - - cd docs - pip install -r requirements.txt + - cd docs + - pip install -U -r requirements.txt - build-docs -t $DOCTGT -bs $DOC_BUILDERS -l $DOCLANG build parallel: matrix: @@ -74,13 +75,14 @@ check_docs_lang_sync: check_docs_gh_links: image: $ESP_IDF_DOC_ENV_IMAGE variables: - PYTHON_VER: 3.6.13 + PYTHON_VER: 3.7.10 extends: - .pre_check_job_template - .doc-rules:build:docs script: - - cd docs - pip install -r requirements.txt + - cd docs + - pip install -U -r requirements.txt - build-docs gh-linkcheck # stage: build_doc @@ -150,20 +152,19 @@ build_docs_pdf: extends: - .before_script_no_sync_submodule image: $ESP_IDF_DOC_ENV_IMAGE - variables: - PYTHON_VER: 3.6.13 stage: test_deploy tags: - deploy - shiny variables: + PYTHON_VER: 3.7.10 DOCS_BUILD_DIR: "${IDF_PATH}/docs/_build/" PYTHONUNBUFFERED: 1 dependencies: [] script: - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER - export GIT_VER=$(git describe --always ${PIPELINE_COMMIT_SHA} --) - - pip install -r docs/requirements.txt + - pip install -U -r docs/requirements.txt - deploy-docs # stage: test_deploy @@ -224,7 +225,8 @@ check_doc_links: expire_in: 1 week allow_failure: true script: - - cd docs - pip install -r requirements.txt + - cd docs + - pip install -U -r requirements.txt # At the moment this check will always fail due to multiple known limitations, ignore result - build-docs -t $DOCTGT -l $DOCLANG linkcheck || { echo "THERE ARE ISSUES DUE TO KNOWN LIMITATIONS, PLEASE FIX THEM. Nowadays we're ignored them to pass pipeline."; true; } From 2ad49d47ebbb365292fee472de774d7719ad403b Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Mon, 25 Apr 2022 13:45:37 +0800 Subject: [PATCH 3/6] docs: fix indention in dac code snippet --- docs/en/api-reference/peripherals/dac.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/en/api-reference/peripherals/dac.rst b/docs/en/api-reference/peripherals/dac.rst index 06f4005a27..73863b9639 100644 --- a/docs/en/api-reference/peripherals/dac.rst +++ b/docs/en/api-reference/peripherals/dac.rst @@ -28,14 +28,17 @@ For other analog output options, see the :doc:`Sigma-delta Modulation module +.. code:: c - ... + #include + + ... + + dac_output_enable(DAC_CHANNEL_1); + dac_output_voltage(DAC_CHANNEL_1, 200); - dac_output_enable(DAC_CHANNEL_1); - dac_output_voltage(DAC_CHANNEL_1, 200); API Reference ------------- From 27cd55dca189d8f09ceb4b09e137c71f4e7de1ff Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Thu, 28 Apr 2022 14:33:42 +0800 Subject: [PATCH 4/6] docs: fix broken links --- .../host/bluedroid/api/include/api/esp_gap_ble_api.h | 2 +- docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst | 8 +++++--- docs/en/api-reference/api-conventions.rst | 8 ++++---- docs/en/api-reference/peripherals/touch_pad.rst | 2 +- docs/en/api-reference/system/mem_alloc.rst | 4 +++- docs/zh_CN/api-guides/build-system.rst | 4 ++-- docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst | 6 ++++-- docs/zh_CN/api-reference/peripherals/touch_pad.rst | 2 +- .../hw-reference/esp32/user-guide-devkits-r-v1.1.rst | 12 ++++++------ 9 files changed, 27 insertions(+), 21 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h index dd48ab982d..f81ad21800 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h @@ -1455,7 +1455,7 @@ esp_err_t esp_ble_gap_config_local_privacy (bool privacy_enable); * * * @param[in] icon - External appearance value, these values are defined by the Bluetooth SIG, please refer to - * https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.characteristic.gap.appearance.xml + * https://specificationrefs.bluetooth.com/assigned-values/Appearance%20Values.pdf * * @return * - ESP_OK : success diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst index bb50901242..5e652ea7b1 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -527,11 +527,13 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m 3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The `ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. + .. only:: esp32 - And some configurations in menuconfig shall be enabled to support PSRAM. + The :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. - - :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` + Some configurations in menuconfig shall be enabled to support PSRAM. + + - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` - :code:`Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the memory from the PSRAM` - :code:`Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation in BT/BLE stack.` - :code:`Bluetooth --> Bluetooth controller --> BLE full scan feature supported.` diff --git a/docs/en/api-reference/api-conventions.rst b/docs/en/api-reference/api-conventions.rst index f47911c2b4..008dcf84d7 100644 --- a/docs/en/api-reference/api-conventions.rst +++ b/docs/en/api-reference/api-conventions.rst @@ -9,7 +9,7 @@ ESP-IDF provides several kinds of programming interfaces: * C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures and types. * Build system functions, predefined variables and options. These are documented in the :ref:`build system guide`. -* `Kconfig `_ options can can be used in code and in the build system (CMakeLists.txt) files. +* :doc:`Kconfig ` options can can be used in code and in the build system (CMakeLists.txt) files. * :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of ESP-IDF interface. ESP-IDF consists of components written specifically for ESP-IDF as well as third-party libraries. In some cases, an ESP-IDF-specific wrapper is added to the third-party library, providing an interface that is either simpler or better integrated with the rest of ESP-IDF facilities. In other cases, the original API of the third-party library is presented to the application developers. @@ -96,7 +96,7 @@ It is not recommended to reference these components directly in custom projects API Stability ------------- -ESP-IDF uses `Semantic Versioning `_ as explained in the :ref:`versions page`. +ESP-IDF uses `Semantic Versioning `_ as explained in the :ref:`versions page`. Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain different aspects and limitations to compatibility. @@ -109,7 +109,7 @@ The following changes are allowed between minor versions and do not break source * Deprecating functions (using the ``deprecated`` attribute) and header files (using a preprocessor ``#warning``). Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and files can be removed in major versions of ESP-IDF. * Renaming components, moving source and header files between components — provided that the build system ensures that correct files are still found. -* Renaming Kconfig options. Kconfig system `renaming mechanism `_ ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code. +* Renaming Kconfig options. Kconfig system :ref:`renaming mechanism ` ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code. Lack of binary compatibility ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -132,7 +132,7 @@ While we try to make upgrading to a new ESP-IDF version easy, there are parts of * Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones. * Features which were never functional. For example, if it was never possible to use a certain function or an enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which depend on non-functional chip hardware features. * Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not documented explicitly may be fixed/changed. -* Location of `Kconfig `_ options in menuconfig. +* Location of :doc:`Kconfig ` options in menuconfig. * Location and names of example projects. .. _designated initializers: https://en.cppreference.com/w/c/language/struct_initialization diff --git a/docs/en/api-reference/peripherals/touch_pad.rst b/docs/en/api-reference/peripherals/touch_pad.rst index d224757f00..025921e7f7 100644 --- a/docs/en/api-reference/peripherals/touch_pad.rst +++ b/docs/en/api-reference/peripherals/touch_pad.rst @@ -25,7 +25,7 @@ In-depth design details of touch sensors and firmware development guidelines for .. only:: SOC_TOUCH_VERSION_1 - For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit `_. + For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit `_. Functionality Overview ---------------------- diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 8eaf0d530a..72c65539a7 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -151,12 +151,14 @@ Implementation Notes Knowledge about the regions of memory in the chip comes from the "soc" component, which contains memory layout information for the chip, and the different capabilities of each region. Each region's capabilities are prioritised, so that (for example) dedicated DRAM and IRAM regions will be used for allocations ahead of the more versatile D/IRAM regions. -Each contiguous region of memory contains its own memory heap. The heaps are created using the `multi_heap `_ functionality. multi_heap allows any contiguous region of memory to be used as a heap. +Each contiguous region of memory contains its own memory heap. The heaps are created using the :ref:`multi_heap ` functionality. multi_heap allows any contiguous region of memory to be used as a heap. The heap capabilities allocator uses knowledge of the memory regions to initialize each individual heap. Allocation functions in the heap capabilities API will find the most appropriate heap for the allocation (based on desired capabilities, available space, and preferences for each region's use) and then calling :cpp:func:`multi_heap_malloc` or :cpp:func:`multi_heap_calloc` for the heap situated in that particular region. Calling ``free()`` involves finding the particular heap corresponding to the freed address, and then calling :cpp:func:`multi_heap_free` on that particular multi_heap instance. +.. _multi-heap: + API Reference - Multi Heap API ------------------------------ diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 4675b79549..a09eedbf86 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -1136,7 +1136,7 @@ CMake 在许多开源的 C/C++ 项目中广泛使用，用户可以在自己的 实际的案例请参考 :example:`build_system/cmake/import_lib`。请注意，导入第三方库所需要做的工作可能会因库的不同而有所差异。建议仔细阅读第三方库的文档，了解如何将其导入到其它项目中。阅读第三方库的 CMakeLists.txt 文件以及构建结构也会有所帮助。 -用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 `_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 `。 +用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 `_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 `。 每当使用 ESP-IDF 构建系统时，CMake 变量 ``ESP_PLATFORM`` 都会被设置为 1。如果要在通用的 CMake 代码加入 IDF 特定的代码时，可以采用 ``if (ESP_PLATFORM)`` 的形式加以分隔。 @@ -1582,7 +1582,7 @@ CMake 中不可用的功能 - ``COMPONENT_OBJS``：以前，可以以目标文件列表的方式指定组件源，现在，可以通过 ``COMPONENT_SRCS`` 以源文件列表的形式指定组件源。 - ``COMPONENT_OBJEXCLUDE``：已被 ``COMPONENT_SRCEXCLUDE`` 替换。用于指定源文件（绝对路径或组件目录的相对路径）。 - ``COMPONENT_EXTRA_CLEAN``：已被 ``ADDITIONAL_MAKE_CLEAN_FILES`` 属性取代，注意，:ref:`CMake 对此项功能有部分限制 `。 -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 `_ 替代，详细内容请参阅 :ref:`component-build-full-override`。 +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 ` 替代，详细内容请参阅 :ref:`component-build-full-override`。 - ``COMPONENT_CONFIG_ONLY``：已被 ``register_config_only_component()`` 函数替代，请参阅 :ref:`config_only_component`。 - ``CFLAGS``、``CPPFLAGS``、``CXXFLAGS``：已被相应的 CMake 命令替代，请参阅 :ref:`component_build_control`。 diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst index 377444b907..5983bb7b2a 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -530,11 +530,13 @@ ESP-BLE-MESH 常见问题手册 3.2 Wi-Fi 和 ESP-BLE-MESH 共存时，为什么 Wi-Fi 吞吐量很低？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 未搭载 PSRAM 的 `ESP32-DevKitC <../../hw-reference/get-started-devkitc>`_ 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。 + .. only:: esp32 + + 未搭载 PSRAM 的 :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。 应使能 menuconfig 中的一些配置来支持 PSRAM。 - - :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` + - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` - :code:`Bluetooth --> Bluedriod Enable --> BT/BLE will first malloc the memory from the PSRAM` - :code:`Bluetooth --> Bluedriod Enable --> Use dynamic memory allocation in BT/BLE stack.` - :code:`Bluetooth --> Blutooth controller --> BLE full scan feature supported.` diff --git a/docs/zh_CN/api-reference/peripherals/touch_pad.rst b/docs/zh_CN/api-reference/peripherals/touch_pad.rst index 17658dc8f9..703d8d471f 100644 --- a/docs/zh_CN/api-reference/peripherals/touch_pad.rst +++ b/docs/zh_CN/api-reference/peripherals/touch_pad.rst @@ -25,7 +25,7 @@ .. only:: SOC_TOUCH_VERSION_1 - 如果想评估触摸传感器的多种应用场景，请查看 `ESP32 触摸功能开发套件 `_。 + 如果想评估触摸传感器的多种应用场景，请查看 `ESP32 触摸功能开发套件 `_。 功能介绍 ---------------------- diff --git a/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst b/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst index 6460088a88..46fe1cec1a 100644 --- a/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst +++ b/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst @@ -9,9 +9,9 @@ ESP32-DevKitS(-R) ESP32-DevKitS(-R) 包括两款开发板，分别是 ESP32-DevKitS 和 ESP32-DevKitS-R。S 代表弹簧 (spring)，R 代表 WROVER 模组。 +-----------------+-------------------+ -| |ESP32-DevKitS| | |ESP32-DevKitS-R| | +| |ESP32-DevKitS| | |ESP32-DevKitS-R| | +-----------------+-------------------+ -| ESP32-DevKitS | ESP32-DevKitS-R | +| ESP32-DevKitS | ESP32-DevKitS-R | +-----------------+-------------------+ .. |ESP32-DevKitS| image:: ../../../_static/esp32-devkits-v1.1-layout-isometric-raw.png @@ -146,14 +146,14 @@ Windows 用户也可以使用 `Flash 下载工具 `_ (PDF) - `ESP32-WROOM-32D & ESP32-WROOM-32U 技术规格书 `_ (PDF) - `ESP32-SOLO-1 技术规格书 `_ (PDF) -- `ESP32-WROVER 技术规格书 `_ (PDF) +- `ESP32-WROVER 技术规格书 `_ (PDF) - `ESP32-WROVER-B 技术规格书 `_ (PDF) -- `乐鑫产品选型工具 `__ +- `乐鑫产品选型工具 `__ \ No newline at end of file From e07d16d6a38a7bf18fd4c9f8745b45ad5cfa65d1 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Thu, 28 Apr 2022 15:59:03 +0800 Subject: [PATCH 5/6] docs: update linkcheck configs linkcheck CI job can now pass, no longer necessary to ignore the results from it. --- .gitlab/ci/docs.yml | 3 +-- docs/conf_common.py | 13 +++++++++++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/.gitlab/ci/docs.yml b/.gitlab/ci/docs.yml index 222cdf2083..783c6bade9 100644 --- a/.gitlab/ci/docs.yml +++ b/.gitlab/ci/docs.yml @@ -228,5 +228,4 @@ check_doc_links: - pip install -r requirements.txt - cd docs - pip install -U -r requirements.txt - # At the moment this check will always fail due to multiple known limitations, ignore result - - build-docs -t $DOCTGT -l $DOCLANG linkcheck || { echo "THERE ARE ISSUES DUE TO KNOWN LIMITATIONS, PLEASE FIX THEM. Nowadays we're ignored them to pass pipeline."; true; } + - build-docs -t $DOCTGT -l $DOCLANG linkcheck diff --git a/docs/conf_common.py b/docs/conf_common.py index c8db151621..1942555e06 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -172,6 +172,19 @@ google_analytics_id = os.environ.get('CI_GOOGLE_ANALYTICS_ID', None) project_homepage = 'https://github.com/espressif/esp-idf' +linkcheck_anchors = False + +linkcheck_exclude_documents = ['index', # several false positives due to the way we link to different sections + 'api-reference/protocols/esp_local_ctrl', # Fails due to `https://.local` + 'api-reference/provisioning/wifi_provisioning', # Fails due to `https://.local` + ] + + +linkcheck_ignore = ['https://webhome.phy.duke.edu/~rgb/General/dieharder.php', # Certificate error + 'https://dl.espressif.com/dl/esp32s3_rom.elf', # Not published + ] + + # Custom added feature to allow redirecting old URLs with open('../page_redirects.txt') as f: lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')] From 90e58c3721f509454dd3897c7760024a12161b17 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Wed, 11 May 2022 15:52:09 +0800 Subject: [PATCH 6/6] docs: fix all doxygen warnings Doxygen warnings would previously not result in a failed pipeline. Fixed this as well as all current warnings. --- components/app_update/include/esp_ota_ops.h | 6 ++-- components/esp_eth/include/esp_eth_mac.h | 2 +- .../include/esp_https_server.h | 2 +- components/esp_hw_support/include/esp_mac.h | 2 +- components/esp_lcd/include/esp_lcd_panel_io.h | 8 +++-- .../esp_lcd/include/esp_lcd_panel_rgb.h | 4 +-- .../esp_lcd/include/esp_lcd_panel_vendor.h | 6 ++-- .../esp_netif/include/esp_netif_ip_addr.h | 26 +++++++++++----- .../esp_netif/include/esp_netif_types.h | 31 +++++++++++++------ components/esp_phy/include/esp_phy_init.h | 11 ++++++- components/freertos/include/freertos/queue.h | 3 -- components/freertos/include/freertos/task.h | 15 +++++---- components/hal/include/hal/adc_types.h | 2 +- .../include/transports/protocomm_ble.h | 8 +++-- components/soc/esp32/include/soc/soc_caps.h | 1 - .../include/touch_element/touch_element.h | 22 +++---------- .../include/touch_element/touch_matrix.h | 20 +++--------- .../include/touch_element/touch_slider.h | 20 +++--------- components/usb/include/usb/usb_host.h | 6 ++-- components/usb/include/usb/usb_types_ch9.h | 30 +++++++++--------- components/usb/include/usb/usb_types_stack.h | 4 +++ docs/conf_common.py | 1 + docs/doxygen-known-warnings.txt | 2 ++ docs/doxygen/Doxyfile | 12 +++---- docs/doxygen/Doxyfile_esp32s3 | 1 - docs/requirements.txt | 2 +- docs/sphinx-known-warnings.txt | 10 +++++- 27 files changed, 138 insertions(+), 119 deletions(-) diff --git a/components/app_update/include/esp_ota_ops.h b/components/app_update/include/esp_ota_ops.h index ba07c013d9..ece5275db3 100644 --- a/components/app_update/include/esp_ota_ops.h +++ b/components/app_update/include/esp_ota_ops.h @@ -327,9 +327,9 @@ typedef enum { /** * @brief Revokes the old signature digest. To be called in the application after the rollback logic. * - * Relevant for Secure boot v2 on ESP32-S2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1). - * When key #N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key #N-1 & Key #N. - * After successfully booting the OTA app should call this function to revoke Key #N-1. + * Relevant for Secure boot v2 on ESP32-S2, ESP32-S3, ESP32-C3 where upto 3 key digests can be stored (Key \#N-1, Key \#N, Key \#N+1). + * When key \#N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key \#N-1 & Key \#N. + * After successfully booting the OTA app should call this function to revoke Key \#N-1. * * @param index - The index of the signature block to be revoked * diff --git a/components/esp_eth/include/esp_eth_mac.h b/components/esp_eth/include/esp_eth_mac.h index db462728a1..be23792d2d 100644 --- a/components/esp_eth/include/esp_eth_mac.h +++ b/components/esp_eth/include/esp_eth_mac.h @@ -411,7 +411,7 @@ typedef struct { /** * @brief Create ESP32 Ethernet MAC instance * -* @param config: Ethernet MAC configuration +* @param config: Ethernet MAC configuration * * @return * - instance: create MAC instance successfully diff --git a/components/esp_https_server/include/esp_https_server.h b/components/esp_https_server/include/esp_https_server.h index efe726e9e7..75720bd1ce 100644 --- a/components/esp_https_server/include/esp_https_server.h +++ b/components/esp_https_server/include/esp_https_server.h @@ -25,7 +25,7 @@ typedef enum { * @brief Callback data struct, contains the ESP-TLS connection handle */ typedef struct esp_https_server_user_cb_arg { - const esp_tls_t *tls; + const esp_tls_t *tls; /*!< ESP-TLS connection handle */ } esp_https_server_user_cb_arg_t; /** diff --git a/components/esp_hw_support/include/esp_mac.h b/components/esp_hw_support/include/esp_mac.h index f0efddfc2f..e700b72ffe 100644 --- a/components/esp_hw_support/include/esp_mac.h +++ b/components/esp_hw_support/include/esp_mac.h @@ -139,7 +139,7 @@ esp_err_t esp_read_mac(uint8_t *mac, esp_mac_type_t type); * address, then the first octet is XORed with 0x4 in order to create a different * locally administered MAC address. * - * @param mac base MAC address, length: 6 bytes/8 bytes. + * @param local_mac base MAC address, length: 6 bytes/8 bytes. * length: 6 bytes for MAC-48 * 8 bytes for EUI-64(used for IEEE 802.15.4) * @param universal_mac Source universal MAC address, length: 6 bytes. diff --git a/components/esp_lcd/include/esp_lcd_panel_io.h b/components/esp_lcd/include/esp_lcd_panel_io.h index 7b99bde3f1..57f27ac96a 100644 --- a/components/esp_lcd/include/esp_lcd_panel_io.h +++ b/components/esp_lcd/include/esp_lcd_panel_io.h @@ -134,6 +134,10 @@ typedef struct { */ esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t bus, const esp_lcd_panel_io_spi_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io); +/** + * @brief Panel IO configuration structure, for I2C interface + * + */ typedef struct { uint32_t dev_addr; /*!< I2C device address */ esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done; /*!< Callback invoked when color data transfer has finished */ @@ -145,7 +149,7 @@ typedef struct { struct { unsigned int dc_low_on_data: 1; /*!< If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa */ unsigned int disable_control_phase: 1; /*!< If this flag is enabled, the control phase isn't used */ - } flags; + } flags; /*!< Extra flags to fine-tune the I2C device */ } esp_lcd_panel_io_i2c_config_t; /** @@ -223,7 +227,7 @@ typedef struct { unsigned int swap_color_bytes: 1; /*!< Swap adjacent two color bytes */ unsigned int pclk_active_neg: 1; /*!< The display will write data lines when there's a falling edge on WR signal (a.k.a the PCLK) */ unsigned int pclk_idle_low: 1; /*!< The WR signal (a.k.a the PCLK) stays at low level in IDLE phase */ - } flags; + } flags; /*!< Panel IO config flags */ } esp_lcd_panel_io_i80_config_t; /** diff --git a/components/esp_lcd/include/esp_lcd_panel_rgb.h b/components/esp_lcd/include/esp_lcd_panel_rgb.h index 95dfb6ba4f..f821a75883 100644 --- a/components/esp_lcd/include/esp_lcd_panel_rgb.h +++ b/components/esp_lcd/include/esp_lcd_panel_rgb.h @@ -66,7 +66,7 @@ typedef struct { unsigned int de_idle_high: 1; /*!< The de signal is high in IDLE state */ unsigned int pclk_active_neg: 1; /*!< Whether the display data is clocked out at the falling edge of PCLK */ unsigned int pclk_idle_high: 1; /*!< The PCLK stays at high level in IDLE phase */ - } flags; + } flags; /*!< LCD RGB timing flags */ } esp_lcd_rgb_timing_t; /** @@ -106,7 +106,7 @@ typedef struct { unsigned int disp_active_low: 1; /*!< If this flag is enabled, a low level of display control signal can turn the screen on; vice versa */ unsigned int relax_on_idle: 1; /*!< If this flag is enabled, the host won't refresh the LCD if nothing changed in host's frame buffer (this is usefull for LCD with built-in GRAM) */ unsigned int fb_in_psram: 1; /*!< If this flag is enabled, the frame buffer will be allocated from PSRAM preferentially */ - } flags; + } flags; /*!< LCD RGB panel configuration flags */ } esp_lcd_rgb_panel_config_t; /** diff --git a/components/esp_lcd/include/esp_lcd_panel_vendor.h b/components/esp_lcd/include/esp_lcd_panel_vendor.h index dde8be68d3..2503adeb7e 100644 --- a/components/esp_lcd/include/esp_lcd_panel_vendor.h +++ b/components/esp_lcd/include/esp_lcd_panel_vendor.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -22,8 +22,8 @@ typedef struct { unsigned int bits_per_pixel; /*!< Color depth, in bpp */ struct { unsigned int reset_active_high: 1; /*!< Setting this if the panel reset is high level active */ - } flags; - void *vendor_config; /* vendor specific configuration, optional, left as NULL if not used */ + } flags; /*!< LCD panel config flags */ + void *vendor_config; /*!< vendor specific configuration, optional, left as NULL if not used */ } esp_lcd_panel_dev_config_t; /** diff --git a/components/esp_netif/include/esp_netif_ip_addr.h b/components/esp_netif/include/esp_netif_ip_addr.h index 25b877d359..57f10999b3 100644 --- a/components/esp_netif/include/esp_netif_ip_addr.h +++ b/components/esp_netif/include/esp_netif_ip_addr.h @@ -81,25 +81,37 @@ extern "C" { #define ESP_IP4ADDR_INIT(a, b, c, d) { .type = ESP_IPADDR_TYPE_V4, .u_addr = { .ip4 = { .addr = ESP_IP4TOADDR(a, b, c, d) }}}; #define ESP_IP6ADDR_INIT(a, b, c, d) { .type = ESP_IPADDR_TYPE_V6, .u_addr = { .ip6 = { .addr = { a, b, c, d }, .zone = 0 }}}; +/** + * @brief IPv6 address + * + */ struct esp_ip6_addr { - uint32_t addr[4]; - uint8_t zone; + uint32_t addr[4]; /*!< IPv6 address */ + uint8_t zone; /*!< zone ID */ }; +/** + * @brief IPv4 address + * + */ struct esp_ip4_addr { - uint32_t addr; + uint32_t addr; /*!< IPv4 address */ }; typedef struct esp_ip4_addr esp_ip4_addr_t; typedef struct esp_ip6_addr esp_ip6_addr_t; +/** + * @brief IP address + * + */ typedef struct _ip_addr { union { - esp_ip6_addr_t ip6; - esp_ip4_addr_t ip4; - } u_addr; - uint8_t type; + esp_ip6_addr_t ip6; /*!< IPv6 address type */ + esp_ip4_addr_t ip4; /*!< IPv4 address type */ + } u_addr; /*!< IP address union */ + uint8_t type; /*!< ipaddress type */ } esp_ip_addr_t; typedef enum { diff --git a/components/esp_netif/include/esp_netif_types.h b/components/esp_netif/include/esp_netif_types.h index cc7a37b9c4..ee6b92a3b2 100644 --- a/components/esp_netif/include/esp_netif_types.h +++ b/components/esp_netif/include/esp_netif_types.h @@ -112,6 +112,11 @@ typedef struct { esp_ip6_addr_t ip; /**< Interface IPV6 address */ } esp_netif_ip6_info_t; + +/** + * @brief Event structure for IP_EVENT_GOT_IP event + * + */ typedef struct { int if_index; /*!< Interface index for which the event is received (left for legacy compilation) */ esp_netif_t *esp_netif; /*!< Pointer to corresponding esp-netif object */ @@ -164,6 +169,10 @@ typedef enum esp_netif_ip_event_type { // 3) network stack specific config (esp_netif_net_stack_ifconfig_t) -- no publicly available // +/** + * @brief ESP-netif inherent config parameters + * + */ typedef struct esp_netif_inherent_config { esp_netif_flags_t flags; /*!< flags that define esp-netif behavior */ uint8_t mac[6]; /*!< initial mac address for this interface */ @@ -185,19 +194,23 @@ typedef struct esp_netif_config esp_netif_config_t; */ typedef void * esp_netif_iodriver_handle; +/** + * @brief ESP-netif driver base handle + * + */ typedef struct esp_netif_driver_base_s { - esp_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h); - esp_netif_t *netif; + esp_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h); /*!< post attach function pointer */ + esp_netif_t *netif; /*!< netif handle */ } esp_netif_driver_base_t; /** * @brief Specific IO driver configuration */ struct esp_netif_driver_ifconfig { - esp_netif_iodriver_handle handle; - esp_err_t (*transmit)(void *h, void *buffer, size_t len); - esp_err_t (*transmit_wrap)(void *h, void *buffer, size_t len, void *netstack_buffer); - void (*driver_free_rx_buffer)(void *h, void* buffer); + esp_netif_iodriver_handle handle; /*!< io-driver handle */ + esp_err_t (*transmit)(void *h, void *buffer, size_t len); /*!< transmit function pointer */ + esp_err_t (*transmit_wrap)(void *h, void *buffer, size_t len, void *netstack_buffer); /*!< transmit wrap function pointer */ + void (*driver_free_rx_buffer)(void *h, void* buffer); /*!< free rx buffer function pointer */ }; typedef struct esp_netif_driver_ifconfig esp_netif_driver_ifconfig_t; @@ -212,9 +225,9 @@ typedef struct esp_netif_netstack_config esp_netif_netstack_config_t; * @brief Generic esp_netif configuration */ struct esp_netif_config { - const esp_netif_inherent_config_t *base; - const esp_netif_driver_ifconfig_t *driver; - const esp_netif_netstack_config_t *stack; + const esp_netif_inherent_config_t *base; /*!< base config */ + const esp_netif_driver_ifconfig_t *driver; /*!< driver config */ + const esp_netif_netstack_config_t *stack; /*!< stack config */ }; /** diff --git a/components/esp_phy/include/esp_phy_init.h b/components/esp_phy/include/esp_phy_init.h index ec68213950..efefd114d4 100644 --- a/components/esp_phy/include/esp_phy_init.h +++ b/components/esp_phy/include/esp_phy_init.h @@ -14,7 +14,8 @@ extern "C" { #endif /** - * @file PHY init parameters and API + * @file + * init parameters and API */ @@ -34,6 +35,10 @@ typedef struct { uint8_t opaque[1894]; /*!< calibration data */ } esp_phy_calibration_data_t; +/** + * @brief PHY calibration mode + * + */ typedef enum { PHY_RF_CAL_PARTIAL = 0x00000000, /*!< Do part of RF calibration. This should be used after power-on reset. */ PHY_RF_CAL_NONE = 0x00000001, /*!< Don't do any RF calibration. This mode is only suggested to be used after deep sleep reset. */ @@ -223,6 +228,10 @@ int64_t esp_phy_rf_get_on_ts(void); /** * @brief Update the corresponding PHY init type according to the country code of Wi-Fi. + * + * @param country country code + * @return ESP_OK on success. + * @return esp_err_t code describing the error on fail */ esp_err_t esp_phy_update_country_info(const char *country); diff --git a/components/freertos/include/freertos/queue.h b/components/freertos/include/freertos/queue.h index 05ca7de454..5070b76e79 100644 --- a/components/freertos/include/freertos/queue.h +++ b/components/freertos/include/freertos/queue.h @@ -1398,9 +1398,6 @@ BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION; BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; -/**@}*/ -/** @endcond */ - /** * @cond !DOC_EXCLUDE_HEADER_SECTION * queue. h diff --git a/components/freertos/include/freertos/task.h b/components/freertos/include/freertos/task.h index 125a924d06..88b2730933 100644 --- a/components/freertos/include/freertos/task.h +++ b/components/freertos/include/freertos/task.h @@ -392,7 +392,7 @@ typedef enum * example, to create a privileged task at priority 2 the uxPriority parameter * should be set to ( 2 | portPRIVILEGE_BIT ). * - * @param pvCreatedTask Used to pass back a handle by which the created task + * @param pxCreatedTask Used to pass back a handle by which the created task * can be referenced. * * @return pdPASS if the task was successfully created and added to a ready @@ -538,7 +538,7 @@ typedef enum * * @param uxPriority The priority at which the task will run. * - * @param pxStackBuffer Must point to a StackType_t array that has at least + * @param puxStackBuffer Must point to a StackType_t array that has at least * ulStackDepth indexes - the array will then be used as the task's stack, * removing the need for the stack to be allocated dynamically. * @@ -2368,7 +2368,7 @@ uint32_t ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION; * notification value at that index being updated. ulValue is not used and * xTaskNotifyIndexed() always returns pdPASS in this case. * - * pulPreviousNotificationValue - + * @param pulPreviousNotificationValue - * Can be used to pass out the subject task's notification value before any * bits are modified by the notify function. * @@ -2532,6 +2532,10 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, * requested from an ISR is dependent on the port - see the documentation page * for the port in use. * + * @param pulPreviousNotificationValue - + * Can be used to pass out the subject task's notification value before any + * bits are modified by the notify function. + * * @return Dependent on the value of eAction. See the description of the * eAction parameter. * @@ -2778,11 +2782,10 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, * @endcond * \ingroup TaskNotifications */ -#define xTaskNotifyGive( xTaskToNotify ) \ - xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) #define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL ) - +#define xTaskNotifyGive( xTaskToNotify ) \ + xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) /** * @cond !DOC_EXCLUDE_HEADER_SECTION * task. h diff --git a/components/hal/include/hal/adc_types.h b/components/hal/include/hal/adc_types.h index f5efb1d427..dc07531e0b 100644 --- a/components/hal/include/hal/adc_types.h +++ b/components/hal/include/hal/adc_types.h @@ -121,7 +121,7 @@ typedef struct { struct { uint16_t data: 12; /*!