From f2304a5f7378be10721b4a125c364b1ded0294c0 Mon Sep 17 00:00:00 2001 From: morris Date: Fri, 3 Nov 2023 13:39:29 +0800 Subject: [PATCH] docs: adding migration guide about esp_driver_xyz components --- docs/en/migration-guides/index.rst | 1 + .../release-5.x/5.3/index.rst | 9 ++++++ .../release-5.x/5.3/peripherals.rst | 30 +++++++++++++++++++ docs/zh_CN/migration-guides/index.rst | 1 + .../release-5.x/5.3/index.rst | 9 ++++++ .../release-5.x/5.3/peripherals.rst | 30 +++++++++++++++++++ 6 files changed, 80 insertions(+) create mode 100644 docs/en/migration-guides/release-5.x/5.3/index.rst create mode 100644 docs/en/migration-guides/release-5.x/5.3/peripherals.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/5.3/index.rst create mode 100644 docs/zh_CN/migration-guides/release-5.x/5.3/peripherals.rst diff --git a/docs/en/migration-guides/index.rst b/docs/en/migration-guides/index.rst index 5ef5054568..199427c2e9 100644 --- a/docs/en/migration-guides/index.rst +++ b/docs/en/migration-guides/index.rst @@ -12,3 +12,4 @@ ESP-IDF 5.x Migration Guide release-5.x/5.0/index release-5.x/5.1/index release-5.x/5.2/index + release-5.x/5.3/index diff --git a/docs/en/migration-guides/release-5.x/5.3/index.rst b/docs/en/migration-guides/release-5.x/5.3/index.rst new file mode 100644 index 0000000000..caccc54187 --- /dev/null +++ b/docs/en/migration-guides/release-5.x/5.3/index.rst @@ -0,0 +1,9 @@ +Migration from 5.2 to 5.3 +------------------------- + +:link_to_translation:`zh_CN:[中文]` + +.. toctree:: + :maxdepth: 1 + + peripherals diff --git a/docs/en/migration-guides/release-5.x/5.3/peripherals.rst b/docs/en/migration-guides/release-5.x/5.3/peripherals.rst new file mode 100644 index 0000000000..7321835ee1 --- /dev/null +++ b/docs/en/migration-guides/release-5.x/5.3/peripherals.rst @@ -0,0 +1,30 @@ +Peripherals +=========== + +:link_to_translation:`zh_CN:[中文]` + +In order to control the dependence of other components on drivers at a smaller granularity, the original peripheral drivers under the `driver`` component were split into separate components: + +- `esp_driver_gptimer` - Driver for general purpose timers +- `esp_driver_pcnt` - Driver for pulse counter +- `esp_driver_gpio` - Driver for GPIO + +For compatibility, the original `driver`` component is still treated as an all-in-one component by registering these `esp_driver_xyz`` components as its public dependencies. In other words, you do not need to modify the CMake file of an existing project, but you now have a way to specify the specific peripheral driver that your project depends on. + +Originally, you may have used **linker.lf** to specify the link location of some driver functions in memory space, but now, because the location of the driver files have been moved, you need to make changes your **linker.lf** file accordingly. For example, a linker.lf file with the following entries: + +.. code-block:: none + + [mapping:my_mapping_scheme] + archive: libdriver.a + entries: + gpio (noflash) + +Should be changed to: + +.. code-block:: none + + [mapping:my_mapping_scheme] + archive: libesp_driver_gpio.a + entries: + gpio (noflash) diff --git a/docs/zh_CN/migration-guides/index.rst b/docs/zh_CN/migration-guides/index.rst index a451fb268d..c458c6398f 100644 --- a/docs/zh_CN/migration-guides/index.rst +++ b/docs/zh_CN/migration-guides/index.rst @@ -12,3 +12,4 @@ release-5.x/5.0/index release-5.x/5.1/index release-5.x/5.2/index + release-5.x/5.3/index diff --git a/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst b/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst new file mode 100644 index 0000000000..25aeb7dff3 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst @@ -0,0 +1,9 @@ +从 5.2 迁移到 5.3 +----------------- + +:link_to_translation:`en:[English]` + +.. toctree:: + :maxdepth: 1 + + peripherals diff --git a/docs/zh_CN/migration-guides/release-5.x/5.3/peripherals.rst b/docs/zh_CN/migration-guides/release-5.x/5.3/peripherals.rst new file mode 100644 index 0000000000..81411dc91f --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/5.3/peripherals.rst @@ -0,0 +1,30 @@ +外设 +==== + +:link_to_translation:`en:[English]` + +为了细粒度地控制其他组件对外设驱动的依赖，原先位于 `driver` 组件下的驱动程序被拆分到了各自独立的组件中。这些组件包括： + +- `esp_driver_gptimer` - 通用定时器驱动 +- `esp_driver_pcnt` - 脉冲计数器驱动 +- `esp_driver_gpio` - GPIO 驱动 + +为了兼容性，原来的 `driver` 组件仍然存在，并作为一个 “all-in-one" 的组件，将以上这些 `esp_driver_xyz` 组件注册成自己的公共依赖。换句话说，你无需修改既有项目的 CMake 文件，但是你现在多了一个途径去指定你项目依赖的具体的外设驱动。 + +原来你可能使用 **linker.lf** 指定了一些驱动函数在内存空间的链接位置，但是现在，因为驱动文件的位置发生了挪动，就需要你对 **linker.lf** 文件做出相应的改动的。假如，你的 linker.lf 文件里面有以下的条目： + +.. code-block:: none + + [mapping:my_mapping_scheme] + archive: libdriver.a + entries: + gpio (noflash) + +现在需要修改成： + +.. code-block:: none + + [mapping:my_mapping_scheme] + archive: libesp_driver_gpio.a + entries: + gpio (noflash)