.. _migration:

从旧版教程迁移
############################################################

本页依据 :doc:`/maintenance` 中记录的 Zephyr ``main`` 快照更新。

仓库原有教程多以 2021—2022 年源码和工具环境为背景。
升级应先选定 Zephyr 目标版本，再读取每个跨越版本的官方迁移指南，
不能一次替换几个头文件就认为已完成迁移。

环境与工作区
============

#. 用 Python 虚拟环境安装当前版本所需依赖；本次基线要求 Python 3.12。
#. 获取目标 Zephyr 修订版后执行 ``west update``，使模块与清单一致。
#. 按目标版本安装 Python 依赖与 SDK。
#. 用当前完整 board target 重新构建，清理旧 CMake 缓存。
#. 在真实硬件验证外设、存储、镜像布局和协议行为。

常见变化
========

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - 早期教程内容
     - 当前处理方式
     - 本地说明
   * - 系统 Python 安装、Python 3.6
     - 虚拟环境；核对当前最低版本
     - :doc:`develop/getting_started`
   * - Windows 旧 Chocolatey/MSYS2 拼装流程
     - 官方 winget 与 SDK 流程
     - :doc:`develop/windows`
   * - SDK 只支持 Linux
     - 按主机平台安装兼容 SDK
     - :doc:`develop/getting_started`
   * - ``west init --mr v2.5.0``
     - 明确选择发布标签或提交号
     - :doc:`develop/west/basic`
   * - ``nrf52840dk_nrf52840`` 等旧板名
     - 查当前硬件模型的完整目标
     - :doc:`develop/application`
   * - ``<kernel.h>``、``<logging/log.h>`` 等路径
     - 使用 ``<zephyr/...>`` 命名空间
     - :doc:`develop/kernel/index`
   * - ``<zephyr/fs/nvs.h>`` 与 ``subsys/fs/nvs``
     - 新头文件 ``<zephyr/kvss/nvs.h>`` 与 ``subsys/kvss/nvs``
     - :doc:`develop/subsys/storage/nvs`
   * - ``FIXED_PARTITION_*``
     - 当前 ``PARTITION_*`` 公共宏
     - :doc:`develop/subsys/storage/flash_map`
   * - ``k_pipe_put/get`` 的输出长度与 ``min_xfer``
     - ``k_pipe_write/read`` 返回实际长度，处理部分传输
     - :doc:`develop/kernel/pipe`
   * - wait 后手动 clear 事件
     - 需要消费时考虑 ``k_event_wait_safe`` 等接口
     - :doc:`develop/kernel/event`
   * - ``CONFIG_NUM_MBOX_ASYNC_MSGS=y``
     - 它是整数容量；结合资源池设计流控
     - :doc:`develop/kernel/mailbox`
   * - 旧日志引擎与 ``log_strdup``
     - 当前 logger 打包机制与日志模式选项
     - :doc:`develop/subsys/logging/logging_usage`
   * - 写完流后继续使用已 flush 上下文
     - flush 结束会话，后续会话重新初始化
     - :doc:`develop/subsys/storage/flash_stream`

存储格式是单独的迁移任务
========================

固件能重新编译不表示旧数据一定兼容。分区地址、sector 数量、写块大小、数据 CRC、
ID 含义以及应用结构体布局发生变化，都要确认已有设备的数据迁移策略。
不要在挂载失败时直接清空存储作为通用升级方案。

本次更新采用官网 ``latest`` 的固定源码快照。NVS 头文件和分区宏等近期变化，在较早
稳定版本中可能不存在；维护发布版应用时，应按对应版本头文件选择接口。

上游迁移入口
============

查看 `发布说明目录 <https://docs.zephyrproject.org/latest/releases/index.html>`_ 中各版本的
Migration Guide。管道重写的跨版本背景见 4.1 迁移指南；最新分支上的声明以本次固定提交为准。

上游依据
========

* `官方文档：releases/migration-guide-4.1 <https://docs.zephyrproject.org/latest/releases/migration-guide-4.1.html>`_
* `固定提交：include/zephyr/kernel.h <https://github.com/zephyrproject-rtos/zephyr/blob/02d743889396e724d53be61e4fe34c484c1d5a97/include/zephyr/kernel.h>`_
* `固定提交：include/zephyr/storage/flash_map.h <https://github.com/zephyrproject-rtos/zephyr/blob/02d743889396e724d53be61e4fe34c484c1d5a97/include/zephyr/storage/flash_map.h>`_
* `固定提交：include/zephyr/kvss/nvs.h <https://github.com/zephyrproject-rtos/zephyr/blob/02d743889396e724d53be61e4fe34c484c1d5a97/include/zephyr/kvss/nvs.h>`_