samples/subsys/usb/dfu/README.html · samples/subsys/usb/dfu/README.rst 공식 원문 ↗

Zephyr 3.7.0 · Samples · USB DFU

USB DFU

SLOT-0 backup부터 SLOT-1 download, test swap, revert와 permanent image까지 추적합니다.

Official pathsamples/subsys/usb/dfu/README.html
Source filesamples/subsys/usb/dfu/README.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

DFU image manager, partition layout, image signing과 자동 reboot의 위험을 설명합니다.

Bootloader

MCUboot stage 1

Host Tool

dfu-util

Flow

test · revert · perm

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 252F2411B392BD5AC5A1C92EF06242C5B1C79E0650D2BC04293FE981C030E9D9
.. zephyr:code-sample:: usb-dfu
   :name: USB DFU (Device Firmware Upgrade)
   :relevant-api: _usb_device_core_api

   Implement device firmware upgrade using the USB DFU class driver.

Overview
********

This sample app demonstrates use of a USB DFU Class driver provided
by the Zephyr project.

Requirements
************

This project requires an USB device driver. Currently, the USB DFU
class provided by the Zephyr project depends on DFU image manager and
partition layout. Refer to :ref:`flash_map_api` for details about
partition layout. You SoC must run MCUboot as the stage 1 bootloader.
This sample is built as an application for the MCUboot bootloader.

.. note::
   This example explicitly turns :kconfig:option:`CONFIG_USB_DFU_ENABLE_UPLOAD` on.

Building and Testing
********************

Building and signing the application
====================================

This sample can be built in the usual way (see :ref:`build_an_application`
for more details) and flashed with regular flash tools, but will need
to be loaded at the offset of SLOT-0.

Application images (such as this sample) must be signed.
The build system can do this for you by setting the :kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE` symbol.

For example:

.. code-block:: console

   west build -b nrf52840dk/nrf52840 zephyr/samples/subsys/usb/dfu -d build-dfu -- \
   -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"

Build and flash MCUboot bootloader for Zephyr project as it is described in
the `Using MCUboot with Zephyr`_ documentation. Then build, sign and flash
the USB DFU sample at the offset of SLOT-0.

Build and sign a second application image e.g. :ref:`hello_world`,
which will be used as an image for the update.
Do not forget to enable the required :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` option (as described
in :ref:`mcuboot`). For example:

.. code-block:: console

   west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -d build-hello_world -- \
   -DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"'

Testing
=======

The Linux ``dfu-util`` tool can be used to backup or update the application
image.

Use the following command to backup the SLOT-0 image:

.. code-block:: console

   dfu-util --alt 0 --upload slot0_backup.bin

Use the following command to update the application:

.. code-block:: console

   dfu-util --alt 1 --download build-hello_world/zephyr/zephyr.signed.bin

Reset the SoC. MCUboot boot will swap the images and boot the new application,
showing this output to the console:

.. code-block:: console

   *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d  ***
   I: Starting bootloader
   I: Primary image: magic=good, swap_type=0x3, copy_done=0x1, image_ok=0x1
   I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
   I: Boot source: none
   I: Swap type: test
   I: Bootloader chainload address offset: 0xc000
   I: Jumping to the first image slot
   *** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9  ***
   Hello World! nrf52840dk


Reset the SoC again and MCUboot should revert the images and boot
USB DFU sample, showing this output to the console:

.. code-block:: console

   *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d  ***
   I: Starting bootloader
   I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x3
   I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
   I: Boot source: none
   I: Swap type: revert
   I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
   I: Bootloader chainload address offset: 0xc000
   I: Jumping to the first image slot
   *** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9  ***
   [00:00:00.005,920] <inf> main: This device supports USB DFU class.

Permanent download and automatic reboot
=======================================

There are some symbols that can be used to enable a hands free download:

To mark SLOT-1 as permanent after the download completes,
enable the :kconfig:option:`CONFIG_USB_DFU_PERMANENT_DOWNLOAD` symbol.

To automatically reboot after the download completes,
enable the :kconfig:option:`CONFIG_USB_DFU_REBOOT` symbol.

.. warning::
   Enabling :kconfig:option:`CONFIG_USB_DFU_PERMANENT_DOWNLOAD` can lead to a bricked device!
   Make sure there is another way to download firmware.
   For example via a debugger or Mcuboot's recovery mode.

Both symbols can be enabled with the :file:`overlay-permanent-download.conf` overlay. For example:

.. code-block:: console

   west build -b nrf52840dk/nrf52840 zephyr/samples/subsys/usb/dfu -d build-dfu -- \
   -DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"' \
   -DEXTRA_CONF_FILE=overlay-permanent-download.conf


The listing below shows the output to the console when downloading via dfu-util.
Note the ``Swap type: perm``.

.. code-block:: console

   *** Booting Zephyr OS build zephyr-v3.0.0-361-ge6900e2451d5  ***
   [00:00:00.005,920] <inf> main: This device supports USB DFU class.

   *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d  ***
   I: Starting bootloader
   I: Primary image: magic=good, swap_type=0x4, copy_done=0x1, image_ok=0x1
   I: Secondary image: magic=good, swap_type=0x3, copy_done=0x3, image_ok=0x1
   I: Boot source: none
   I: Swap type: perm
   I: Bootloader chainload address offset: 0xc000
   I: Jumping to the first image slot
   *** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9  ***
   Hello World! nrf52840dk


.. _MCUboot GitHub repo: https://github.com/zephyrproject-rtos/mcuboot
.. _Using MCUboot with Zephyr: https://docs.mcuboot.com/readme-zephyr

Part 3

한국어 전문 번역

개요

이 sample application은 Zephyr project가 제공하는 USB DFU(Device Firmware Upgrade) Class driver 사용법을 보여 줍니다.

요구 사항

USB device driver가 필요합니다. Zephyr의 USB DFU class는 DFU image manager와 partition layout에 의존하므로 flash map API 문서에서 layout을 확인해야 합니다.

SoC는 stage 1 bootloader로 MCUboot를 실행해야 하며, 이 sample은 MCUboot가 load할 application으로 build됩니다. 또한 이 example은 CONFIG_USB_DFU_ENABLE_UPLOAD을 명시적으로 활성화합니다.

빌드 및 테스트

Application 빌드와 서명

일반 application과 같은 방식으로 build하고 보통의 flash tool로 기록할 수 있지만, image는 SLOT-0 offset에 load해야 합니다.

이 sample 같은 application image에는 서명이 필요합니다. CONFIG_MCUBOOT_SIGNATURE_KEY_FILE symbol을 설정하면 build system이 image를 서명합니다. 예를 들어 다음 command는 nRF52840 DK용 DFU sample을 RSA-2048 root key로 build합니다.

west build -b nrf52840dk/nrf52840 zephyr/samples/subsys/usb/dfu -d build-dfu -- \
-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"

‘Using MCUboot with Zephyr’ 문서의 절차대로 MCUboot bootloader를 build하고 flash합니다. 그런 다음 USB DFU sample을 build·sign해 SLOT-0 offset에 flash합니다.

Update image로 사용할 두 번째 application, 예를 들면 Hello World도 build하고 sign합니다. MCUboot 문서에 설명된 CONFIG_BOOTLOADER_MCUBOOT option을 반드시 활성화해야 합니다.

west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -d build-hello_world -- \
-DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"'

테스트

Linux의 dfu-util tool로 application image를 backup하거나 update할 수 있습니다. 다음 command는 alternate setting 0에서 SLOT-0 image를 upload해 backup합니다.

dfu-util --alt 0 --upload slot0_backup.bin

다음 command는 alternate setting 1로 signed Hello World image를 download해 update slot에 기록합니다.

dfu-util --alt 1 --download build-hello_world/zephyr/zephyr.signed.bin

SoC를 reset하면 MCUboot가 image를 swap하고 새 application을 test mode로 boot합니다. Console의 Swap type: test, SLOT 상태, chainload offset과 Hello World 출력을 확인합니다.

*** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d  ***
I: Starting bootloader
I: Primary image: magic=good, swap_type=0x3, copy_done=0x1, image_ok=0x1
I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
I: Boot source: none
I: Swap type: test
I: Bootloader chainload address offset: 0xc000
I: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9  ***
Hello World! nrf52840dk

새 image가 confirm되지 않은 상태에서 SoC를 다시 reset하면 MCUboot가 image를 revert하고 USB DFU sample로 돌아옵니다. Console에는 Swap type: revert와 USB DFU class 지원 message가 나타납니다.

*** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d  ***
I: Starting bootloader
I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x3
I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
I: Boot source: none
I: Swap type: revert
I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
I: Bootloader chainload address offset: 0xc000
I: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9  ***
[00:00:00.005,920] <inf> main: This device supports USB DFU class.

영구 download와 자동 reboot

Download가 끝난 뒤 SLOT-1을 영구 image로 표시하려면 CONFIG_USB_DFU_PERMANENT_DOWNLOAD을 활성화합니다. 완료 직후 자동으로 reboot하려면 CONFIG_USB_DFU_REBOOT을 활성화합니다.

CONFIG_USB_DFU_PERMANENT_DOWNLOAD은 잘못 사용하면 device를 복구 불능 상태로 만들 수 있습니다. Debugger 또는 MCUboot recovery mode처럼 firmware를 다시 download할 별도 경로가 있는지 먼저 확인해야 합니다.

두 symbol은 overlay-permanent-download.conf overlay로 함께 활성화할 수 있습니다.

west build -b nrf52840dk/nrf52840 zephyr/samples/subsys/usb/dfu -d build-dfu -- \
-DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"' \
-DEXTRA_CONF_FILE=overlay-permanent-download.conf

다음은 dfu-util download 뒤의 console output입니다. Swap type: perm은 새 image가 영구적으로 선택됐음을 나타냅니다.

*** Booting Zephyr OS build zephyr-v3.0.0-361-ge6900e2451d5  ***
[00:00:00.005,920] <inf> main: This device supports USB DFU class.

*** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d  ***
I: Starting bootloader
I: Primary image: magic=good, swap_type=0x4, copy_done=0x1, image_ok=0x1
I: Secondary image: magic=good, swap_type=0x3, copy_done=0x3, image_ok=0x1
I: Boot source: none
I: Swap type: perm
I: Bootloader chainload address offset: 0xc000
I: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9  ***
Hello World! nrf52840dk

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.