نام (NAME)

dfu-util - پروگرمر USB برای به‌روزرسانی سفت‌افزار دستگاه (DFU)

خلاصه دستور (SYNOPSIS)

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]

توضیحات (DESCRIPTION)

dfu-util برنامه‌ای است که سمت میزبان (رایانه) پروتکل USB DFU (ارتقای سفت‌افزار دستگاه از طریق گذرگاه سریال جهانی) را پیاده‌سازی می‌کند.

برنامه dfu-util با دستگاه‌هایی که سمت دستگاه پروتکل USB DFU را پیاده‌سازی کرده‌اند ارتباط برقرار می‌کند و اغلب برای ارتقای سفت‌افزار این دستگاه‌ها به کار می‌رود.

گزینه‌ها (OPTIONS)

-l, --list: فهرست کردن دستگاه‌های USB متصل با قابلیت DFU.
-d, --device [Run-Time VENDOR]:[Run-Time PRODUCT][,[DFU Mode VENDOR]:[DFU Mode PRODUCT]]

شناسهٔ سازنده (vendor ID) و/یا شناسهٔ محصول (product ID) دستگاه DFU را در حالت زمان‌اجرا (run-time) و/یا حالت DFU برای کار با آن مشخص می‌کند. VENDOR و PRODUCT اعداد هگزادسیمال (بدون نیاز به پیشوند)، «*» (تطبیق با هر موردی) یا «-» (عدم تطبیق با هیچ موردی) هستند. به‌طور پیش‌فرض، هر دستگاه با قابلیت DFU چه در حالت زمان‌اجرا و چه در حالت DFU در نظر گرفته می‌شود.

اگر فقط یک دستگاه منطبق بر استاندارد DFU به رایانه شما متصل باشد، این پارامتر اختیاری است. با این حال، به محض اینکه چندین دستگاه DFU متصل شوند، dfu-util این موضوع را تشخیص داده و با لغو اجرا، از شما می‌خواهد مشخص کنید از کدام دستگاه استفاده شود.

اگر فقط شناسه‌های زمان‌اجرا مشخص شوند (برای مثال «--device 1457:51ab»)، علاوه بر شناسه‌های زمان‌اجرای مشخص‌شده، هر دستگاهی در حالت DFU نیز در نظر گرفته خواهد شد. این ویژگی از آن جهت سودمند است که به یک دستگاه با قابلیت DFU امکان می‌دهد پس از تغییر حالت به DFU دوباره پیدا شود، چرا که شناسهٔ سازنده و/یا محصول یک دستگاه معمولاً در حالت DFU تغییر می‌کند.

اگر فقط شناسه‌های حالت DFU مشخص شوند (برای مثال «--device ,951:26»)، تمامی دستگاه‌های زمان‌اجرا نادیده گرفته می‌شوند، که هدف قرار دادن یک دستگاه خاص در حالت DFU را آسان می‌سازد.

اگر هر دو شناسهٔ حالت زمان‌اجرا و DFU مشخص شوند (برای مثال «--device 1457:51ab,:2bc»)، مؤلفه‌های نامشخص حالت DFU از مقدار مشخص‌شده برای زمان‌اجرا استفاده خواهند کرد.

مثال‌ها:

--device 1457:51ab,951:26: کار با دستگاهی در حالت زمان‌اجرا با شناسه سازنده 0x1457 و شناسه محصول 0x51ab، یا در حالت DFU با شناسه سازنده 0x0951 و شناسه محصول 0x0026
--device 1457:51ab,:2bc: کار با دستگاهی در حالت زمان‌اجرا با شناسه سازنده 0x1457 و شناسه محصول 0x51ab، یا در حالت DFU با شناسه سازنده 0x1457 و شناسه محصول 0x02bc
--device 1457:51ab: کار با دستگاهی در حالت زمان‌اجرا با شناسه سازنده 0x1457 و شناسه محصول 0x51ab، یا در حالت DFU با هر شناسه سازنده و محصولی
--device ,951:26: کار با دستگاهی در حالت DFU با شناسه سازنده 0x0951 و شناسه محصول 0x0026
--device *,-: کار با هر دستگاهی در حالت زمان‌اجرا، و نادیده گرفتن هر دستگاهی در حالت DFU
--device ,: نادیده گرفتن هر دستگاهی در حالت زمان‌اجرا، و کار با هر دستگاهی در حالت DFU

-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]]

شماره سریال‌های حالت زمان‌اجرا و حالت DFU را برای محدود کردن بیشتر تطبیق دستگاه مشخص می‌کند. اگر چندین دستگاه DFU یکسان به‌طور هم‌زمان به سیستم متصل باشند، شناسهٔ سازنده و محصول برای هدف قرار دادن یک دستگاه واحد کافی نخواهد بود. در این وضعیت، می‌توان از این پارامتر برای مشخص کردن شماره سریالی که آن هم باید مطابقت داشته باشد استفاده کرد.

اگر فقط یک شماره سریال مشخص شود، همان شماره سریال در هر دو حالت زمان‌اجرا و DFU استفاده می‌شود. یک شماره سریال خالی با هر شماره سریالی در حالت مربوطه تطبیق خواهد یافت.

-t, --transfer-size SIZE: تعداد بایت‌ها در هر انتقال USB را مشخص می‌کند. مقدار بهینه معمولاً به‌طور خودکار تعیین می‌شود، بنابراین این گزینه به‌ندرت مفید است. اگر برای دستگاهی نیاز به استفاده از این گزینه دارید، لطفاً آن را به عنوان یک باگ گزارش دهید.
-Z, --upload-size SIZE: اندازهٔ مورد انتظار بارگذاری را بر حسب بایت مشخص می‌کند. توجه داشته باشید که این مقدار تنها برای مقیاس‌بندی نوار پیشرفت استفاده می‌شود؛ اندازهٔ واقعی بارگذاری توسط دستگاه تعیین می‌شود.
-U, --upload FILE: خواندن سفت‌افزار از دستگاه و ذخیره در FILE.
-D, --download FILE: نوشتن سفت‌افزار از FILE روی دستگاه. هنگامی که FILE برابر - باشد، سفت‌افزار از ورودی استاندارد (stdin) خوانده می‌شود.
-R, --reset: ارسال سیگنال بازنشانی (reset) USB پس از پایان بارگذاری یا بارگیری.
-e, --detach: درخواست از دستگاه برای بازشماری (re-enumerate) جهت خروج از حالت زمان‌اجرا و ورود به حالت DFU همانند زمان بارگذاری یا بارگیری، اما خروج فوری پس از ارسال درخواست.
-E, --detach-delay SECONDS: هنگام بارگذاری یا بارگیری، پس از ارسال درخواست جدا شدن (detach)، به مدت SECONDS ثانیه برای بازشماری دستگاه پیش از انصراف منتظر می‌ماند. مقدار پیش‌فرض ۵ ثانیه است. این گزینه با -e بی‌تأثیر است، زیرا آن گزینه باعث می‌شود dfu-util بلافاصله پس از ارسال درخواست جدا شدن خارج شود.
-w, --wait: انتظار تا زمانی که دستگاه منطبق بر روی گذرگاه USB ظاهر شود.
-s, --dfuse-address [ADDRESS][:LENGTH][:MODIFIERS]: آدرس مقصد را برای بارگیری/بارگذاری باینری خام در دستگاه‌های DfuSe مشخص می‌کند. از این گزینه برای بارگیری فایل‌های DfuSe (.dfu) استفاده نکنیدبرای بارگذاری‌ها می‌توان یک طول مشخص کرد. تغییردهنده‌ها را می‌توان پس از آدرس با دونقطه اضافه کرد تا دستورهای خاص DfuSe نظیر «leave» برای خروج از حالت DFU، «unprotect» و «mass-erase» حافظه فلش اجرا شوند. اگر انتظار می‌رود دستگاه پس از عملیات بازنشانی شود، باید «will-reset» اضافه شود. تغییردهندهٔ «force» برخی بررسی‌های اولیه را نادیده می‌گیرد و همچنین برای عملیات‌های «unprotect» و «mass-erase» ضروری است.
-v, --verbose: نمایش اطلاعات بیشتر درباره عملکرد dfu-util. گزینهٔ -v دوم جزئیات بیشتری می‌افزاید. گزینهٔ -v سوم گزارش‌گیری با جزئیات کامل از درخواست‌های USB (خروجی اشکال‌زدایی libusb) را فعال می‌کند.
-h, --help: نمایش متن راهنما و خروج.
-V, --version: نمایش اطلاعات نسخه و خروج.

مثال‌ها (EXAMPLES)

استفاده از 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 در حافظه RAM دستگاه Neo1973 در دسترس خواهد بود. نکته: با این روش نمی‌توان بیش از ۲ مگابایت داده را به RAM منتقل کرد.

استفاده از dfu-util با یک دستگاه DfuSe

فلش کردن یک فایل .dfu (قالب ویژه DfuSe) روی دستگاه:
$ dfu-util -D /path/to/dfuse-image.dfu

خواندن ۱ کیلوبایت از حافظه فلش با شروع از آدرس 0x8000000:
$ dfu-util -a 0 -s 0x08000000:1024 -U newfile.bin

فلش کردن یک فایل باینری در آدرس 0x8004000 حافظه دستگاه و درخواست از دستگاه برای خروج از حالت DFU:
$ dfu-util -a 0 -s 0x08004000:leave -D /path/to/image.bin

گزارش باگ‌ها (BUGS)

لطفاً هرگونه باگ را در سامانه پیگیری باگ dfu-util در http://sourceforge.net/p/dfu-util/tickets گزارش دهید. لطفاً برای ارائه اطلاعات بیشتر در گزارش باگ خود، از گزینهٔ --verbose (در صورت نیاز به صورت مکرر) استفاده کنید.

همچنین ببینید (SEE ALSO)

صفحهٔ خانگی dfu-util: http://dfu-util.sourceforge.net

تاریخچه (HISTORY)

برنامهٔ dfu-util در ابتدا برای پروژه OpenMoko توسط Weston Schmidt <weston_schmidt@yahoo.com> و Harald Welte <hwelte@hmw-consulting.de> نوشته شد. با گذشت زمان، پشتیبانی تقریباً کاملی از DFU 1.0،‏ DFU 1.1 و DfuSe («1.1a») به آن افزوده شد.

مجوز (LICENSE)

dfu-util تحت مجوز عمومی همگانی گنو (GPL)، نسخه ۲ یا بالاتر پوشش داده شده است.

کپی‌رایت و تکثیر (COPYRIGHT)

این صفحهٔ راهنما در ابتدا توسط Uwe Hermann <uwe@hermann-uwe.de> نوشته شد و اکنون بخشی از پروژه dfu-util است.