SG_WRITE_BUFFER(8) SG3_UTILS SG_WRITE_BUFFER(8)

sg_write_buffer - ارسال دستورات SCSI WRITE BUFFER

sg_write_buffer [--bpw=CS] [--dry-run] [--help] [--id=ID] [--in=FILE] [--length=LEN] [--mode=MO] [--offset=OFF] [--read-stdin] [--skip=SKIP] [--specific=MS] [--timeout=TO] [--verbose] [--version] DEVICE

یک یا چند دستور SCSI WRITE BUFFER را به همراه داده‌های ارائه‌شده توسط کاربر به DEVICE ارسال می‌کند. در برخی موارد نیازی به داده نیست، یا می‌توان داده‌ها را از فایل مشخص‌شده در گزینه --in=FILE خواند، یا در صورت ارائه گزینه --read-stdin یا --in=- داده‌ها از ورودی استاندارد (stdin) خوانده می‌شوند.

برخی از گونه‌های دستور WRITE BUFFER داده‌های مرتبطی برای ارسال به دستگاه ندارند؛ به عنوان مثال "activate_mc" ریزکد (میکروکد) به تعویق افتاده‌ای را فعال می‌کند که از طریق دستورات پیشین WRITE BUFFER ارسال شده بود. روش متفاوتی برای بارگیری ریزکد به دستگاه‌های SES به کار می‌رود؛ به ابزار sg_ses_microcode مراجعه کنید.

آرگومان‌های گزینه‌های طولانی برای گزینه‌های کوتاه نیز الزامی هستند. گزینه‌ها بر اساس نام گزینه طولانی به ترتیب الفبایی مرتب شده‌اند.

که در آن CS اندازه تکه (chunk size) بر حسب بایت است. این مقدار حداکثر تعداد بایت‌های ارسالی در هر دستور WRITE BUFFER خواهد بود. بنابراین اگر CS کمتر از طول مؤثر باشد، چندین دستور WRITE BUFFER ارسال می‌شود که هر کدام تکه بعدی را از داده‌های خوانده‌شده برمی‌دارد و فیلد آفست بافر (buffer offset) را در دستور WRITE BUFFER به میزان مناسب افزایش می‌دهد. مقدار پیش‌فرض اندازه تکه 0 است که به عنوان یک عدد بسیار بزرگ تفسیر می‌شود و در نتیجه تنها یک دستور WRITE BUFFER ارسال خواهد شد. این گزینه تنها باید در حالت‌هایی استفاده شود که عبارت «download microcode, with offsets ...» دارند؛ یعنی حالت‌های 0x6، 0x7، 0xd یا 0xe.
عدد موجود در CS می‌تواند به صورت اختیاری با ",act" یا ",activate" دنبال شود. در این حالت پس از ارسال دستورات WRITE BUFFER تا زمانی که طول مؤثر تمام شود، یک دستور WRITE BUFFER دیگر با حالتی که روی «حالت فعال‌سازی ریزکد معوق» [حالت 0xf] تنظیم شده است ارسال می‌گردد.
تمام پردازش‌های خط فرمان و بررسی‌های درستی‌سنجی از جمله خواندن فایل ورودی را انجام می‌دهد. با این حال، در نقطه‌ای که قرار است دستور(ات) SCSI WRITE BUFFER ارسال شود، از فراخوانی آن رد شده و فرض می‌کند که بدون خطا تکمیل شده است و ادامه می‌دهد. DEVICE همچنان باز می‌شود اما می‌تواند /dev/null باشد (در یونیکس). توصیه می‌شود از --verbose همراه با این گزینه استفاده کنید تا نمای کلی از آنچه رخ می‌داد به دست آورید.
پیام راهنمای استفاده را چاپ کرده و خارج می‌شود. در صورت استفاده مکرر، نام حالت‌ها و کوته‌نوشت‌های آن‌ها را نیز چاپ می‌کند.
این گزینه فیلد buffer id را در cdb تنظیم می‌کند. ID مقداری بین 0 (پیش‌فرض) تا 255 (شامل هر دو) است.
داده‌ها را از فایل FILE می‌خواند که قرار است با دستور WRITE BUFFER ارسال شوند. اگر FILE برابر با '-' باشد، ورودی استاندارد (stdin) تا رسیدن به پایان فایل (EOF) خوانده می‌شود (این عملکرد مشابه --read-stdin است). داده‌ها از ابتدای FILE خوانده می‌شوند، به جز زمانی که یک فایل معمولی باشد و گزینه --skip=SKIP مشخص شده باشد.
که در آن LEN طول داده‌های ارسالی برای نوشتن روی دستگاه، بر حسب بایت است. اگر مشخص نشود (و طول نتواند از --in=FILE یا --read-stdin استنباط شود)، مقدار پیش‌فرض صفر در نظر گرفته می‌شود. اگر این گزینه مشخص شده باشد و طول استنباط‌شده از --in=FILE یا --read-stdin کمتر باشد (یا داده‌ای ارائه نشود)، از بایت‌های 0xff به عنوان بایت‌های پرکننده (fill bytes) استفاده می‌شود.
این گزینه فیلد MODE را در cdb تنظیم می‌کند. MO مقداری بین 0 (پیش‌فرض) تا 31 (شامل هر دو) است. از طرف دیگر، می‌توان از کوته‌نوشت استفاده کرد. بخش حالت‌ها (MODES) در زیر را ببینید. برای فهرست کردن کوته‌نوشت‌های موجود در زمان اجرا، یک مقدار نامعتبر وارد کنید (مانند '--mode=xxx') یا از گزینه '-hh' استفاده کنید.
این گزینه فیلد BUFFER OFFSET را در cdb تنظیم می‌کند. OFF مقداری بین 0 (پیش‌فرض) تا 2**24-1 است. این مقدار یک آفست بایتی است.
داده‌ها را از ورودی استاندارد تا رسیدن به پایان فایل (EOF) می‌خواند. این داده‌ها همراه با دستور WRITE BUFFER به DEVICE ارسال می‌شوند. عملکرد این گزینه مشابه استفاده از '--in=-' است. قبلاً نام بلند این گزینه --raw بود و همچنان ممکن است برای سازگاری با نسخه‌های پیشین استفاده شود.
این گزینه تنها زمانی فعال است که --in=FILE مشخص شده باشد و FILE یک فایل معمولی باشد، نه stdin. داده‌ها از آفست بایتی SKIP تا انتهای فایل (یا مقداری که با --length=LEN مشخص شده است) خوانده می‌شوند. در صورت عدم تعیین، آفست بایتی پیش‌فرض برابر با 0 خواهد بود (یعنی ابتدای فایل).
MS فیلد MODE SPECIFIC در cdb است. این یک فیلد ۳ بیتی است، بنابراین مقادیر 0 تا 7 پذیرفته می‌شوند. این فیلد در بازبینی 32 استاندارد SPC-4 معرفی شد و می‌تواند برای مشخص کردن رویدادهای اضافی که ریزکد معوق را فعال می‌کنند (زمانی که MO برابر با 0xD است) استفاده شود.
TO مهلت زمانی دستور (بر حسب ثانیه) برای هر دستور WRITE BUFFER صادرشده توسط این ابزار است. مقدار پیش‌فرض آن 300 ثانیه (5 دقیقه) است و تنها در صورتی که این مقدار کافی نباشد باید تغییر کند.
سطح پرگویی خروجی (خروجی اشکال‌زدایی) را افزایش می‌دهد.
رشته نسخه را چاپ کرده و سپس خارج می‌شود.

در ادامه فهرستی از تنظیمات دستور WRITE BUFFER برای فیلد MODE آمده است. ابتدا کوته‌نوشتی که توسط آرگومان MO این ابزار پذیرفته می‌شود ذکر شده است. پس از کوته‌نوشت در قلاب‌ها، مقادیر معادل ده‌دهی و هگزادسیمال متناظر که می‌توان برای MO داد آمده‌اند. موارد زیر به ترتیب عددی فهرست شده‌اند.

ترکیب سرآیند و داده (در SPC-4 منسوخ شده است).
وابسته به سازنده (Vendor specific).
داده (در SPC-3 به نام "Write Data" خوانده می‌شد).
بارگیری ریزکد و فعال‌سازی (در SPC-3 به نام "Download microcode" خوانده می‌شد).
بارگیری ریزکد، ذخیره و فعال‌سازی (در SPC-3 به نام "Download microcode and save" خوانده می‌شد).
بارگیری ریزکد همراه با آفست و فعال‌سازی (در SPC-3 به نام "Download microcode with offsets" خوانده می‌شد).
بارگیری ریزکد همراه با آفست، ذخیره و فعال‌سازی (در SPC-3 به نام "Download microcode with offsets and save" خوانده می‌شد).
نوشتن داده در بافر انعکاس (در SPC-3 به نام "Echo buffer" خوانده می‌شد).
بارگیری ریزکد همراه با آفست، انتخاب رویدادهای فعال‌سازی، ذخیره و تعویق فعال‌سازی (در SPC-4 معرفی شد).
بارگیری ریزکد همراه با آفست، ذخیره و تعویق فعال‌سازی (در SPC-4 معرفی شد).
فعال‌سازی ریزکد معوق (در SPC-4 معرفی شد).
فعال‌سازی پروتکل ارتباطی بسط‌دهنده و بافر انعکاس (در SPC-4 منسوخ شد).
غیرفعال‌سازی پروتکل ارتباطی بسط‌دهنده (در SPC-4 منسوخ شد).
بارگیری تاریخچه خطای کلاینت برنامه (در SPC-3 به نام "Download application log" خوانده می‌شد).

اگر گزینه --length=LEN مشخص نشده باشد، این ابزار تا ۸ مبی‌بایت (8 MiB) داده را از فایل داده‌شده FILE (یا stdin) می‌خواند. اگر مقدار بیشتری داده مورد نیاز است، باید گزینه --length=LEN مشخص شود.

کاربر باید توجه داشته باشد که اکثر سیستم‌عامل‌ها محدودیت‌هایی برای مقدار داده‌ای که می‌توان با یک دستور SCSI ارسال کرد دارند. در لینوکس این امر به سازوکار گذر مستقیم (pass-through) مورد استفاده (مانند block SG_IO یا درایور sg) و تنظیمات مختلف در sysfs در سری هسته‌های لینوکس 2.6/3 (مانند /sys/block/sda/queue/max_sectors_kb) بستگی دارد. دستگاه‌ها (یعنی واحدهای منطقی یا logical units) نیز معمولاً محدودیت‌هایی برای حداکثر مقدار داده‌ای که می‌توانند در یک دستور مدیریت کنند دارند. این دو محدودیت ایجاب می‌کنند که با بزرگ‌تر و بزرگ‌تر شدن فایل‌های سفت‌افزار (firmware)، حالت‌های حاوی کلمه "offset" همراه با گزینه --bpw=CS به کار روند. و مقدار CS می‌تواند کاملاً کوچک باشد، برای مثال ۴۰۹۶ بایت، که منجر به ارسال دستورات WRITE BUFFER متعددی خواهد شد.

تلاش برای بارگیری یک فایل ریزکد/سفت‌افزار که بیش از حد بزرگ است ممکن است موجب بروز خطا در لایه گذر مستقیم شود (یعنی پیش از صدور دستور SCSI). در لینوکس چنین گزارش‌های خطایی ممکن است مبهم باشند، مانند "pass through os error invalid argument". فری‌بی‌اس‌دی (FreeBSD) چنین خطاهایی را به خوبی در کنسول دستگاه گزارش می‌دهد اما پیام خطای مبهمی را به این ابزار برمی‌گرداند.

بارگیری ریزکد نادرست روی یک دستگاه می‌تواند آن دستگاه را از کار بیندازد و غیرقابل استفاده کند. امید می‌رود که سازنده دستگاه پیش از فعال‌سازی داده‌ها، آن‌ها را اعتبارسنجی کند. اگر در cdb دستور SCSI WRITE BUFFER مقادیری نامناسب (مانند بیش از حد بزرگ بودن LEN) داده شود، دستگاه باید با کلید حس (sense key) خطای ILLEGAL REQUEST و کد حس اضافی (additional sense code) خطای INVALID FIELD in CDB پاسخ دهد. اگر یک دستور WRITE BUFFER (یا توالی‌ای از آن‌ها) به دلیل بررسی‌های اعتبارسنجی سازنده دستگاه ناموفق باشد، باید با کلید حس ILLEGAL REQUEST و کد حس اضافی COMMAND SEQUENCE ERROR پاسخ دهد.

تمام اعداد ارائه‌شده همراه با گزینه‌ها ده‌دهی فرض می‌شوند. در غیر این صورت، مقادیر عددی می‌توانند به صورت هگزادسیمال همراه با پیشوند "0x" یا "0X" (یا پسوند "h" یا "H") داده شوند.

مثال زیر سفت‌افزار جدیدی را به یک محفظه (enclosure) ارسال می‌کند. ارسال یک فایل ۱.۵ مگابایتی در یک دستور WRITE BUFFER باعث شد که محفظه به طور موقت قفل شود و سفت‌افزار به‌روزرسانی نشود. خرد کردن فایل سفت‌افزار به تکه‌های ۴ کیلوبایتی (یک حدس حساب‌شده) موفقیت‌آمیزتر بود:


sg_write_buffer -b 4k -m dmc_offs_save -I firmware.bin /dev/sg4

به‌روزرسانی سفت‌افزار در چرخه خاموش و روشن شدن (power cycle) بعدی محفظه رخ داد. در یک محفظه مدرن، صفحه Extended Inquiry VPD نشان می‌دهد که ارتقای سفت‌افزار در چه شرایطی رخ خواهد داد.

وضعیت خروج sg_write_buffer در صورت موفقیت 0 است. در غیر این صورت به صفحه راهنمای sg3_utils(8) مراجعه کنید.

نوشته‌شده توسط Luben Tuikov و Douglas Gilbert.

گزارش باگ‌ها به <dgilbert at interlog dot com>.

Copyright © 2006-2018 Luben Tuikov and Douglas Gilbert
این نرم‌افزار تحت مجوز BSD-2-Clause توزیع شده است. هیچ تضمینی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب با یک هدف خاص.

sg_read_buffer, sg_ses_microcode(sg3_utils)

November 2018 sg3_utils-1.45