dfu-util: DFU-утилиты программирования

Добавил(а) microsin

Программа dfu-util это реализация на стороне хоста спецификаций протоколов DFU 1.0 и DFU 1.1 форума USB, распространяемая под управлением лицензии GPL version 2. Протокол DFU (расшифровывается как Device Firmware Upgrade) предназначен для загрузки (прошивки) встраиваемого ПО firmware в устройства, подключенные через USB. Это применяется в широком диапазоне приложений, от мелких устройств на микроконтроллерах до мобильных телефонов. С помощью dfu-util можно загрузить firmware в устройство, поддерживающее DFU, или прочитать firmware из него. Утилита dfu-util тестировалась на Openmoko Neo1973, Freerunner и на многих других устройствах.

Примечание: dfu-util изначально была написана Harald Welte на основе dfu-programmer 0.4 [9], и поддерживается Tormod Volden.

man dfu-util

dfu-util - Device firmware update (DFU) USB programmer

[Синопсис]

dfu-util -l [-v] [-d vid:pid[,vid:pid]] [-p path] [-c configuration] [-i interface] [-a alt-intf]
[-S serial[,serial]]

dfu-util [-v] [-d vid:pid[,vid:pid]] [-p path] [-c configuration] [-i interface] [-a alt-intf]
[-S serial[,serial]] [-t size] [-Z size] [-w] [-s address] [-R] [-D|-U file]

dfu-util [-hV]

[Описание]

Консольная утилита dfu-util реализует на стороне хоста (компьютер) протокол USB DFU (Universal Serial Bus Device Firmware Upgrade). Подразумевается, что на устройстве USB имеется загрузчик, поддерживающий протокол USB DFU, что позволяет обновить firmware устройства.

[Описание опций]

-l, --list

Выведет список подключенных в настоящий момент USB-устройств, поддерживающих DFU.

-d, --device [Run-Time VENDOR]:[Run-Time PRODUCT][,[DFU Mode VENDOR]:[DFU Mode PRODUCT]]

Указывает run-time и/или DFU mode vendor и/или product ID устройства DFU, с которым предстоит работать. VENDOR и PRODUCT указываются как HEX-числа (без префикса), либо как "*" (любое соответствие), или "-" (ничему не соответствовать). По умолчанию подразумевается, что подключено любое DFU-совместимое устройство, находящееся либо в рабочем режиме (run-time), или в режиме загрузки (DFU mode).

Если в настоящий момент к компьютеру подключено только одно стандартное устройство DFU, то этот параметр опциональный. Но если подключено несколько DFU-совместимых устройств, то dfu-util обнаружит этот факт, оборвет операцию и запросит указать, какое из устройств надо использовать.

Если указан только run-time ID (например "--device 1457:51ab"), то в дополнение к этим указанным run-time ID будут также рассматриваться любые устройства в режиме DFU. Это удобно для обеспечения возможности повторного нахождения устройства, поддерживающего DFU, после переключения в режим DFU, поскольку идентификатор продавца (vendor ID) и/или продукта (product ID) устройства обычно изменяется в режиме DFU.

Если указаны только DFU mode ID (например "--device ,951:26"), то все run-time устройства будут проигнорированы, что упрощает нацеливание на определенное устройство, находящееся в DFU mode.

Если указаны идентификаторы обоих режимов, и run-time ID, и DFU mode ID, (например "--device 1457:51ab,:2bc"), то не указанные компоненты DFU mode будут использовать указанное run-time значение.

Примеры:

--device 1457:51ab,951:26

Работать с устройством в run-time mode с vendor ID 0x1457 и product ID 0x51ab, или в DFU mode с vendor ID 0x0951 и product ID 0x0026.

--device 1457:51ab,:2bc

Работать с устройством в run-time mode с vendor ID 0x1457 и product ID 0x51ab, или в DFU mode с vendor ID 0x1457 и product ID 0x02bc

--device 1457:51ab

Работать с устройством в run-time mode с vendor ID 0x1457 и product ID 0x51ab, или в DFU mode с любым vendor ID и product ID.

--device ,951:26

Работать с устройством в DFU mode с vendor ID 0x0951 и product ID 0x0026.

--device *,-

Работать с любым устройством в run-time mode, и игнорировать любое устройство в DFU mode.

--device ,

Игнорировать любое устройство в run-time mode, и работать с любым устройством в DFU mode.

-p, --path BUS-PORT. ... .PORT

Указывает путь до устройства DFU.

-c, --cfg CONFIG-NR

Указывает конфигурацию устройства DFU. Обратите внимание, что это используется только для указания соответствия, dfu-util не устанавливает конфигурацию устройства.

-i, --intf INTF-NR

Указывает номер интерфейса DFU.

-a, --alt ALT

Указывает альтернативную настройку (altsetting) интерфейса DFU по имени или номеру.

-S, --serial [Run-Time SERIAL][,[DFU Mode SERIAL]]

Указывает серийные номера run-time mode и DFU mode, используемые для дальнейшего ограничения соответствия устройств. Если к системе одновременно подключено несколько идентичных DFU-устройств, то vendor ID и product ID недостаточно для идентификации конкретного устройства. В такой ситуации можно использовать этот параметр, чтобы указать необходимость соответствия также и серифного номера устройства.

Если указан только серийный номер, то один и тот же серийный номер будет использоваться и в run-time, и в DFU mode. Пустой серийный номер будет соответствовать любому серийному номеру в соответствующем режиме.

-t, --transfer-size SIZE

Указывает количество байт на одну USB-транзакцию. Оптимальное значение обычно определяется автоматически, так что эта опция будет редко когда полезна. Если вам все-таки необходимо использовать для устройства эту опцию, то сообщите об этом факте как о баге.

-Z, --upload-size SIZE

Указывает ожидаемый размер выгрузки в байтах. Имейте в виду, что это значение используется только для отображения шкалы прогресса операции, реальный размер выгрузки определяется устройством.

-U, --upload FILE

Прочитать firmware из устройства в файл FILE.

-D, --download FILE

Записать firmware из файла FILE в устройство. Когда в качестве FILE указано -, firmware считывается из stdin.

-R, --reset

Выдать сигнализацию USB reset после завершения upload или download.

-e, --detach

Запросить повторную энумерацию USB-устройства с выходом из run-time mode и переходом в DFU mode для выгрузки или загрузки, однако произойдет немедленный выход после отправки запроса.

-E, --detach-delay SECONDS

При выгрузке или загрузке подождать SECONDS секунд, чтобы устройство выполнило повторную энумерацию USB после отправки запроса detach перед тем, как оставить попытки соединения. По умолчанию 5 секунд. Эта опция не дает эффекта вместе с опцией -e, поскольку она приводит к немедленному завершению dfu-util после отправки запроса detach.

-w, --wait

Подождать, пока соответствующее устройство не появится на шине USB.

-s, --dfuse-address [ADDRESS][:LENGTH][:MODIFIERS]

Указывает целевой адрес для сырого бинарника при операции download/upload на устройствах DfuSe. Не используйте эту опцию для файлов типа DfuSe (.dfu). Может быть указана длина выгрузки для upload. После адреса могут быть добавлены модификаторы, отделяемые двоеточием, чтобы выполнить специальные команды DfuSE, такие как "leave" DFU mode (выйти из режима обновления прошивки), "unprotect" (снять защиту от записи памяти flash) и "mass-erase" (полное стирание памяти flash). Если ожидается, что после операции устройство сбросит само себя, то должен быть добавлен модификатор "will-reset". Модификатор "force" отменит некоторые проверки работоспособности, и это также необходимо для операций "unprotect" и "mass-erase".

-v, --verbose

Печатает больше информации по выполняемой dfu-util операции. Продублированная -v добавляет больше подробностей. Трижды указанная -v активирует подробный лог (verbose logging) запросов USB (вывод отладочных сообщений библиотеки libusb).

-h, --help

Покажет текст помощи и завершит работу.

-V, --version

Покажет информацию о версии и завершит работу.

[Примеры]

Использование dfu-util в проекте OpenMoko (вместе с аппаратурой Neo1973).

Прошивка корневой файловой системы (rootfs):

$ dfu-util -a rootfs -R -D /path/to/openmoko-devel-image.jffs2

Прошивка ядра (kernel):

$ dfu-util -a kernel -R -D /path/to/uImage

Прошивка загрузчика (bootloader):

$ dfu-util -a u-boot -R -D /path/to/u-boot.bin

Копирование ядра в ОЗУ (RAM):

$ dfu-util -a 0 -R -D /path/to/uImage

После завершения этих операций ядро будет доступно по адресу загрузки по умолчанию 0x32000000 в Neo1973 RAM. Внимание: таким методом нельзя передать в RAM больше 2 мегабайт данных.

Использование dfu-util вместе с устройством DfuSe. Прошивка в DFU-устройство файла .dfu (специальный формат DfuSe):

$ dfu-util -D /path/to/dfuse-image.dfu

Чтение 1 килобайт из flash, начиная с адреса 0x8000000, и запись в файл newfile.bin:

$ dfu-util -a 0 -s 0x08000000:1024 -U newfile.bin

Прошивка двоичного файла в память устройства по адресу 0x8004000, с запросом выхода из DFU mode:

$ dfu-util -a 0 -s 0x08004000:leave -D /path/to/image.bin

[Баги]

О найденных ошибка сообщайте в баг-трекер dfu-util, http://sourceforge.net/p/dfu-util/tickets/. Для получения дополнительной информации, отправляемой в баг-репорте, используйте опцию --verbose (при необходимости с повторениями).

См. также: http://dfu-util.sourceforge.net/

[История]

Изначально dfu-util была написана для проекта OpenMoko программистами Weston Schmidt < weston_schmidt@yahoo.com> и Harald Welte < hwelte@hmw-consulting.de>. Со временем была добавлена полная поддержка DFU 1.0, DFU 1.1 и DfuSe ("1.1a").

[Лицензия]

dfu-util защищена GNU General Public License (GPL), версии 2 или более свежей.

[COPYRIGHT]

Эта man-страничка была написана Uwe Hermann < uwe@hermann-uwe.de>, и сейчас является частью проекта dfu-util.

Программа dfu-suffix может использоваться для добавления, проверки и удаления суффикса файла DFU firmware (прошивка), что рекомендуется для безопасного соответствия файла прошивки и устройства. Программа dfu-prefix может использоваться вместе с форматами файлов TI LMDFU/Stellaris или NXP LPC.

Поддерживаемые устройства:

● Openmoko Neo1973

● Openmoko Freerunner

● Leaflabs Maple

● OpenPCD и OpenPICC

● Qi Hardware ATUSB (use dfu-util 0.7)

● Osmocom SIMtrace

● Многие устройства, использующие DfuSe DFU extension от компании ST, например:

- Black Magic Probe.
- DSO nano.
- Spark Core / Particle Photon.
- Встроенный загрузчик STM32F2, STM32F3, STM32F4.
- Некоторые устройства, основанные на STR750, например USB2CAN.

[Релизы]

Релизы различных версий dfu-util можно найти в [2]. Текущий релиз 0.11. Предоставляются бинарники для Microsoft Windows и некоторых других платформ. Программа dfu-util использует libusb 1.0 для доступа к устройству USB, так что на Windows нужно зарегистрировать устройство с драйвером WinUSB (альтернативно libusb-win32 или libusbK), подробности см. в libusb wiki [3].

Пользователи Mac OS X могут получить dfu-util с помощью Homebrew [4] командой "brew install dfu-util", или из MacPorts [5].

Большинство дистрибутивов Linux предоставляют dfu-util в бинарных пакетов для случаев, когда нет желания скомпилировать dfu-util из исходного кода. На Debian, Ubuntu, Fedora и Gentoo вы можете установить dfu-util штатным инструментарием для программных пакетов. Для других дистрибутивов (наподобие OpenSuSe, Mandriva, CentOS) Holger Freyther любезно предоставил двоичные пакеты через Open Build Service [6].

[Разработка]

Текущая разработка выкладывается в GIT, его можно просмотреть через web-интерфейс [7], или клонировать командой:

$ git clone git://git.code.sf.net/p/dfu-util/dfu-util

Инструкции по сборки на различных платформах см. в [8].

[Использование dfu-util вместе DfuSe-устройствами]

DfuSe (DFU с расширениями от ST Microsystems) это протокол, основанный на DFU 1.1. Однако с целью расширения функционала DFU компания ST Microsystems полностью разрушила совместимость со стандартом DFU 1.1. DfuSe-устройства сообщают о себе как поддерживающие DFU-версию "1.1a".

DfuSe может использоваться для загрузки firmware и других данных с компьютера-хоста в DfuSe-совместимое устройство (или выгрузить в обратном направлении) через USB, подобно тому, как это делается со стандартным DFU.

Основное отличие от стандартного DFU в том, что целевой адрес в (flash) памяти устройства указывается на хосте, благодаря чему можно загружать код и данные в отдельные части памяти устройства. Программа на хосте также отвечает за стирание страниц flash перед записью в них данных.

Файлы *.dfu. Компания ST Microsystems определила специальный формат файла для переноса firmware в память DfuSe-устройств. Этот файл в дополнение к двоичным данным также содержит такую target-информацию, как адрес и альтернативный интерфейс. Несколько блоков двоичных данных могут быть скомбинированы в один файл *.dfu. Сопутствующий Python-скрипт dfuse-pack.py может использоваться для создания, проверки и распаковки таких файлов.

Альтернативные интерфейсы. Различные области памяти в устройстве могут обладать разными характеристиками, которые должна учитывать программа хоста (dfu-util). К таким характеристикам относятся размер страницы flash, сегменты только для чтения (read-only) и с полным доступом (read-write), необходимость стирания, и т. д. Эти параметры устройство предоставляет в строковых дескрипторах, предназначенных для описания интерфейсов USB. Программа хоста декодирует эти строки, чтобы составить карту памяти устройства. Для доступа к областям памяти с разными свойствами должны быть выбраны различные элементы памяти, или области адресов, перечисленные в альтернативных настройках интерфейса (alternate interface settings).

Обратите внимание, что dfu-util оставляет за пользователем выбор альтернативного интерфейса. Когда делается парсинг файла .dfu, будут пропущены сегменты файла, которые не соответствуют выбранному альтернативному интерфейсу. Также некоторые реализации firmware устройства DfuSe игнорируют установки альтернативного интерфейса и сами вычисляют необходимую область памяти по адресу, поскольку нет перекрытия адресов между областями памяти с разными свойствами.

Специальные команды DfuSe. Программа хоста использует специальные команды DfuSe во время обычных операций download или upload, такие как установка адреса (SET_ADDRESS) и стирание страницы (ERASE_PAGE). Также в протоколе Dfuse у команд DFU_DNLOAD и DFU_UPLOAD имеются специальные реализации. Многие устройства DfuSe также поддерживают команды для того, чтобы покинуть режим прошивки (DFU mode), снять защиту flash-памяти на чтение и/или запись, или чтобы полностью стереть flash-память (mass erase). Программа dfu-util (начиная с версии 0.7) поддерживает добавление "leave", "unprotect" или "mass-erase" к аргументу опции -s, чтобы отправить такие запросы в комбинации с download-запросом. Эти модификаторы отделяются друг от друга двоеточием.

У некоторых устройств DfuSe загрузчик работает из памяти flash. Таким образом, полное стирание всей памяти flash приведет к тому, что DfuSe-загрузчик уничтожит сам себя, т. е. устройство для большинства пользователей "окирпичится" (т. е. станет неработоспособным и непрошиваемым). Таким образом, использование таких модификаторов, как "unprotect" и "mass-erase", требует комбинации с модификатором "force". Это не добавлено в примеры, чтобы не побуждать неграмотных пользователей использовать такие опасные модификаторы, стреляя себе в ногу.

Например, все устройства на основе STM32F103 запускают bootloader из flash, поскольку у них в ROM нет загрузчика USB.

У устройств STM32F107, STM32F2xx и STM32F4xx DfuSe bootloader запускается из ROM, так что flash может быть стерта, сохраняя работоспособность последующей перепрошивки транзакциями USB DFU, пока разработчики используют заводской встроенный загрузчик, и не реализуют другой DfuSe загрузчик в памяти flash, от которого зависит пользователь.

Хорошо спроектированные загрузчики, работающие из flash, сообщают о своей собственной памяти как о регионе только для чтения (read-only), и с невозможностью стирания (not eraseable), однако это не защитит от отправки программой dfu-util запроса "unprotect" или "mass-erase", который отменит ограничения, если на этом настаивает пользователь.

Ниже приведено несколько примеров работы с DfuSe-устройствами. Прошивка в устройство файла .dfu (специальный формат DfuSe):

$ dfu-util -a 0 -D /path/to/dfuse-image.dfu

Чтение 1 KB памяти flash, начиная с адреса 0x8000000:

$ dfu-util -a 0 -s 0x08000000:1024 -U newfile.bin

Прошивка двоичного файла в память устройства по адресу 0x8004000, с запросом покинуть DFU mode после завершения записи:

$ dfu-util -a 0 -s 0x08004000:leave -D /path/to/image.bin

[Ссылки]

1. dfu-util Device Firmware Upgrade Utilities site:sourceforge.net.
2. https://dfu-util.sourceforge.net/releases/.
3. libusb / libusb Windows site:github.com.
4. Homebrew Missing Package Manager for macOS (or Linux) site:brew.sh.
5. MacPorts Project Official Homepage site:macports.org.
6. dfu-util site:build.opensuse.org.
7. dfu-util Code site:sourceforge.net.
8. How to build dfu-util from source site:sourceforge.net.
9. dfu-programmer multi-platform command-line programmer site:github.io.

Добавить комментарий

JComments

Поделиться

Нашли опечатку?

Добавить комментарий