From d3f5882ed7543e0ba0f2772958840d47c8f450bd Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Mon, 22 Oct 2018 13:33:26 +0800 Subject: [PATCH 1/5] docs: fix git submodule update command Closes https://github.com/espressif/esp-idf/issues/2584 --- docs/en/versions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/versions.rst b/docs/en/versions.rst index 5d6530cb6..0c36d7302 100644 --- a/docs/en/versions.rst +++ b/docs/en/versions.rst @@ -166,7 +166,7 @@ For example, to follow the branch for ESP-IDF v3.1, including any bugfixes for f git fetch git checkout release/v3.1 git pull - git submodule --update --init --recursive + git submodule update --init --recursive Each time you ``git pull`` this branch, ESP-IDF will be updated with fixes for this release. From c8fe9f696ce10c1e5b8d9cc83c80d8506937a162 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Mon, 22 Oct 2018 13:45:09 +0800 Subject: [PATCH 2/5] docs: fix instructions for building toolchain on macOS Closes https://github.com/espressif/esp-idf/issues/503 Closes https://github.com/espressif/esp-idf/issues/2607 --- .../get-started-cmake/linux-setup-scratch.rst | 12 +++++++----- .../get-started-cmake/macos-setup-scratch.rst | 19 +++++++++++-------- docs/en/get-started/linux-setup-scratch.rst | 10 ++++++++-- docs/en/get-started/macos-setup-scratch.rst | 14 +++++++++++--- docs/gen-toolchain-links.py | 1 - 5 files changed, 37 insertions(+), 19 deletions(-) diff --git a/docs/en/get-started-cmake/linux-setup-scratch.rst b/docs/en/get-started-cmake/linux-setup-scratch.rst index 57f461afc..7a1582ee7 100644 --- a/docs/en/get-started-cmake/linux-setup-scratch.rst +++ b/docs/en/get-started-cmake/linux-setup-scratch.rst @@ -51,12 +51,14 @@ Compile the Toolchain from Source TODO -Download ``crosstool-NG`` and build it:: +Create the working directory and go into it:: - cd ~/esp - git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git - cd crosstool-NG - ./bootstrap && ./configure --enable-local && make install + mkdir -p ~/esp + cd ~/esp + +Download ``crosstool-NG`` and build it: + +.. include:: /_build/inc/scratch-build-code.inc Build the toolchain:: diff --git a/docs/en/get-started-cmake/macos-setup-scratch.rst b/docs/en/get-started-cmake/macos-setup-scratch.rst index d75a1a8bb..d74a35487 100644 --- a/docs/en/get-started-cmake/macos-setup-scratch.rst +++ b/docs/en/get-started-cmake/macos-setup-scratch.rst @@ -14,6 +14,8 @@ MacPorts needs a full XCode installation, while homebrew only needs XCode comman .. _homebrew: https://brew.sh/ .. _MacPorts: https://www.macports.org/install.php +See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. + Install Prerequisites ===================== @@ -58,15 +60,16 @@ Mount it:: Create a symlink to your work directory:: - cd ~/esp - ln -s /Volumes/ctng crosstool-NG + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume -Download ``crosstool-NG`` and build it:: +Go into the newly created directory:: - cd ~/esp - git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git - cd crosstool-NG - ./bootstrap && ./configure --enable-local && make install + cd ~/esp/ctng-volume + +Download ``crosstool-NG`` and build it: + +.. include:: /_build/inc/scratch-build-code.inc Build the toolchain:: @@ -74,7 +77,7 @@ Build the toolchain:: ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. +Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. Next Steps diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst index 40b5e432f..b14530f6d 100644 --- a/docs/en/get-started/linux-setup-scratch.rst +++ b/docs/en/get-started/linux-setup-scratch.rst @@ -2,8 +2,9 @@ Setup Linux Toolchain from Scratch ********************************** -The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`. - +.. note:: + + Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. Install Prerequisites ===================== @@ -49,6 +50,11 @@ Compile the Toolchain from Source TODO +Create the working directory and go into it:: + + mkdir -p ~/esp + cd ~/esp + Download ``crosstool-NG`` and build it: .. include:: /_build/inc/scratch-build-code.inc diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index f743d9995..0cf8130bf 100644 --- a/docs/en/get-started/macos-setup-scratch.rst +++ b/docs/en/get-started/macos-setup-scratch.rst @@ -2,6 +2,10 @@ Setup Toolchain for Mac OS from Scratch *************************************** +.. note:: + + Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. + Install Prerequisites ===================== @@ -41,8 +45,12 @@ Mount it:: Create a symlink to your work directory:: - cd ~/esp - ln -s /Volumes/ctng crosstool-NG + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume + +Go into the newly created directory:: + + cd ~/esp/ctng-volume Download ``crosstool-NG`` and build it: @@ -54,7 +62,7 @@ Build the toolchain:: ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. +Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. Next Steps diff --git a/docs/gen-toolchain-links.py b/docs/gen-toolchain-links.py index 10c2aeef9..aa824b93c 100644 --- a/docs/gen-toolchain-links.py +++ b/docs/gen-toolchain-links.py @@ -43,7 +43,6 @@ def main(): scratch_build_code_linux_macos = """ :: - cd ~/esp git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git cd crosstool-NG ./bootstrap && ./configure --enable-local && make install From 5a3c0d8adf200dd0b82e94e35a7c7d8b966f38e6 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Mon, 22 Oct 2018 14:30:48 +0800 Subject: [PATCH 3/5] esp_timer: document limitations on timeout/period Closes https://github.com/espressif/esp-idf/issues/2572 Closes https://github.com/espressif/esp-idf/issues/2350 --- docs/en/api-reference/system/esp_timer.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/en/api-reference/system/esp_timer.rst b/docs/en/api-reference/system/esp_timer.rst index a4fdbc28f..2f8423c0c 100644 --- a/docs/en/api-reference/system/esp_timer.rst +++ b/docs/en/api-reference/system/esp_timer.rst @@ -17,6 +17,12 @@ Timer callbacks are dispatched from a high-priority ``esp_timer`` task. Because .. note: Provisions are made to dispatch some simple callbacks directly from the interrupt handler, if needed. However this option is not implemented at the moment. +If other tasks with priority higher than ``esp_timer`` are running, callback dispatching will be delayed until ``esp_timer`` task has a chance to run. For example, this will happen if a SPI Flash operation is in progress. + +Creating and starting a timer, and dispatching the callback takes some time. Therefore there is a lower limit to the timeout value of one-shot ``esp_timer``. If :cpp:func:`esp_timer_start_once` is called with a timeout value less than 20us, the callback will be dispatched only after approximately 20us. + +Periodic ``esp_timer`` also imposes a 50us restriction on the minimal timer period. Periodic software timers with period of less than 50us are not practical since they would consume most of the CPU time. Consider using dedicated hardware peripherals or DMA features if you find that a timer with small period is required. + Using ``esp_timer`` APIs ------------------------ From 338012b7765929548c3f6c1b65eb66073000ac59 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Mon, 22 Oct 2018 14:37:17 +0800 Subject: [PATCH 4/5] docs: use generated links in CMake getting started guides --- docs/en/get-started-cmake/linux-setup.rst | 18 ++++++++++++------ docs/en/get-started-cmake/macos-setup.rst | 10 +++++----- .../windows-setup-scratch.rst | 6 ++++-- 3 files changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/en/get-started-cmake/linux-setup.rst b/docs/en/get-started-cmake/linux-setup.rst index cdac99ce7..3bcdca537 100644 --- a/docs/en/get-started-cmake/linux-setup.rst +++ b/docs/en/get-started-cmake/linux-setup.rst @@ -27,21 +27,27 @@ To compile with ESP-IDF you need to get the following packages: Toolchain Setup =============== +.. include:: /_build/inc/download-links.inc + ESP32 toolchain for Linux is available for download from Espressif website: - for 64-bit Linux: - https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz + |download_link_linux64| - for 32-bit Linux: - https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz + |download_link_linux32| -1. Download this file, then extract it in ``~/esp`` directory:: +1. Download this file, then extract it in ``~/esp`` directory: - mkdir -p ~/esp - cd ~/esp - tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz + - for 64-bit Linux: + + .. include:: /_build/inc/unpack-code-linux64.inc + + - for 32-bit Linux: + + .. include:: /_build/inc/unpack-code-linux32.inc .. _setup-linux-toolchain-add-it-to-path-cmake: diff --git a/docs/en/get-started-cmake/macos-setup.rst b/docs/en/get-started-cmake/macos-setup.rst index 7672444e8..b2570514d 100644 --- a/docs/en/get-started-cmake/macos-setup.rst +++ b/docs/en/get-started-cmake/macos-setup.rst @@ -41,15 +41,15 @@ ESP-IDF will use the version of Python installed by default on Mac OS. Toolchain Setup =============== +.. include:: /_build/inc/download-links.inc + ESP32 toolchain for macOS is available for download from Espressif website: -https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz +|download_link_osx| -Download this file, then extract it in ``~/esp`` directory:: +Download this file, then extract it in ``~/esp`` directory: - mkdir -p ~/esp - cd ~/esp - tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz +.. include:: /_build/inc/unpack-code-osx.inc .. _setup-macos-toolchain-add-it-to-path-cmake: diff --git a/docs/en/get-started-cmake/windows-setup-scratch.rst b/docs/en/get-started-cmake/windows-setup-scratch.rst index 58c6af9e2..a0d1ad43e 100644 --- a/docs/en/get-started-cmake/windows-setup-scratch.rst +++ b/docs/en/get-started-cmake/windows-setup-scratch.rst @@ -54,9 +54,11 @@ This tool will also need to be unzipped to a directory which is then `added to y Toolchain Setup =============== -Download the precompiled Windows toolchain from dl.espressif.com: +.. include:: /_build/inc/download-links.inc -https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip +Download the precompiled Windows toolchain: + +|download_link_win32| Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``. From 0a2049582e4aa96ede02ab965b16ba5cedadb3c9 Mon Sep 17 00:00:00 2001 From: morris Date: Mon, 22 Oct 2018 18:26:44 +0800 Subject: [PATCH 5/5] bugfix: minor_doc_fixes into Chinese --- docs/zh_CN/get-started/linux-setup-scratch.rst | 10 +++++++++- docs/zh_CN/get-started/macos-setup-scratch.rst | 14 +++++++++++--- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/zh_CN/get-started/linux-setup-scratch.rst b/docs/zh_CN/get-started/linux-setup-scratch.rst index 3610ce06f..e7abf81b5 100644 --- a/docs/zh_CN/get-started/linux-setup-scratch.rst +++ b/docs/zh_CN/get-started/linux-setup-scratch.rst @@ -2,7 +2,9 @@ 从零开始设置 Linux 环境下的工具链 ********************************** -除了直接从 Espressif 官网下载二进制格式的工具链，下面将再介绍一种可替代的办法。如果想要快速设置二进制工具链而不是手动从源码编译，请做好备份，并前往 :doc:`Linux 环境下的设置 ` 章节。 +.. note:: + + 安装工具链的标准流程可以通过阅读文档 :doc:`Linux 平台工具链的标准设置 ` 来获得，:ref:`工具链的自定义设置 ` 章节会介绍哪些情况下我们必须要重新定义工具链。 安装必要的工具 @@ -48,6 +50,12 @@ TODO +新建工作目录，然后进入:: + + mkdir -p ~/esp + cd ~/esp + + 下载 ``crosstool-NG`` 然后编译: .. include:: /_build/inc/scratch-build-code.inc diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst index 30d7d7f73..0b2d23809 100644 --- a/docs/zh_CN/get-started/macos-setup-scratch.rst +++ b/docs/zh_CN/get-started/macos-setup-scratch.rst @@ -2,6 +2,10 @@ 从零开始设置 Mac OS 环境下的工具链 ********************************** +.. note:: + + 安装工具链的标准流程可以通过阅读文档 :doc:`在 MacOS 上安装 ESP32 工具链 ` 来获得， :ref:`工具链的自定义设置 ` 章节会介绍哪些情况下我们必须要重新定义工具链。 + 安装必要的工具 ===================== @@ -41,8 +45,12 @@ 创建指向你工作目录的符号链接:: - cd ~/esp - ln -s /Volumes/ctng crosstool-NG + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume + +进入新创建的工作目录:: + + cd ~/esp/ctng-volume 下载 ``crosstool-NG`` 然后编译: @@ -54,7 +62,7 @@ ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 +编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 下一步