.TH SG_WRITE_BUFFER "8" "November 2018" "sg3_utils\-1.45" SG3_UTILS
.SH "نام (NAME)"
sg_write_buffer \- ارسال دستورات SCSI WRITE BUFFER
.SH "خلاصه دستور (SYNOPSIS)"
.B sg_write_buffer
[\fI\-\-bpw=CS\fR] [\fI\-\-dry\-run\fR] [\fI\-\-help\fR] [\fI\-\-id=ID\fR]
[\fI\-\-in=FILE\fR] [\fI\-\-length=LEN\fR] [\fI\-\-mode=MO\fR]
[\fI\-\-offset=OFF\fR] [\fI\-\-read\-stdin\fR] [\fI\-\-skip=SKIP\fR]
[\fI\-\-specific=MS\fR] [\fI\-\-timeout=TO\fR] [\fI\-\-verbose\fR]
[\fI\-\-version\fR] \fIDEVICE\fR
.SH "توضیحات (DESCRIPTION)"
.\" Add any additional description here
یک یا چند دستور SCSI WRITE BUFFER را به همراه داده‌های ارائه‌شده توسط کاربر به \fIDEVICE\fR ارسال می‌کند. در برخی موارد نیازی به داده نیست، یا می‌توان داده‌ها را از فایل مشخص‌شده در گزینه \fI\-\-in=FILE\fR خواند، یا در صورت ارائه گزینه \fI\-\-read\-stdin\fR یا \fI\-\-in=\-\fR داده‌ها از ورودی استاندارد (stdin) خوانده می‌شوند.
.PP
برخی از گونه‌های دستور WRITE BUFFER داده‌های مرتبطی برای ارسال به دستگاه ندارند؛ به عنوان مثال "activate_mc" ریزکد (میکروکد) به تعویق افتاده‌ای را فعال می‌کند که از طریق دستورات پیشین WRITE BUFFER ارسال شده بود. روش متفاوتی برای بارگیری ریزکد به دستگاه‌های SES به کار می‌رود؛ به ابزار sg_ses_microcode مراجعه کنید.
.SH "گزینه‌ها (OPTIONS)"
آرگومان‌های گزینه‌های طولانی برای گزینه‌های کوتاه نیز الزامی هستند.
گزینه‌ها بر اساس نام گزینه طولانی به ترتیب الفبایی مرتب شده‌اند.
.TP
\fB\-b\fR, \fB\-\-bpw\fR=\fICS\fR
که در آن \fICS\fR اندازه تکه (chunk size) بر حسب بایت است. این مقدار حداکثر تعداد بایت‌های ارسالی در هر دستور WRITE BUFFER خواهد بود. بنابراین اگر \fICS\fR کمتر از طول مؤثر باشد، چندین دستور WRITE BUFFER ارسال می‌شود که هر کدام تکه بعدی را از داده‌های خوانده‌شده برمی‌دارد و فیلد آفست بافر (buffer offset) را در دستور WRITE BUFFER به میزان مناسب افزایش می‌دهد. مقدار پیش‌فرض اندازه تکه 0 است که به عنوان یک عدد بسیار بزرگ تفسیر می‌شود و در نتیجه تنها یک دستور WRITE BUFFER ارسال خواهد شد. این گزینه تنها باید در حالت‌هایی استفاده شود که عبارت «download microcode, with offsets ...» دارند؛ یعنی حالت‌های 0x6، 0x7، 0xd یا 0xe.
.br
عدد موجود در \fICS\fR می‌تواند به صورت اختیاری با ",act" یا ",activate" دنبال شود. در این حالت پس از ارسال دستورات WRITE BUFFER تا زمانی که طول مؤثر تمام شود، یک دستور WRITE BUFFER دیگر با حالتی که روی «حالت فعال‌سازی ریزکد معوق» [حالت 0xf] تنظیم شده است ارسال می‌گردد.
.TP
\fB\-d\fR, \fB\-\-dry\-run\fR
تمام پردازش‌های خط فرمان و بررسی‌های درستی‌سنجی از جمله خواندن فایل ورودی را انجام می‌دهد. با این حال، در نقطه‌ای که قرار است دستور(ات) SCSI WRITE BUFFER ارسال شود، از فراخوانی آن رد شده و فرض می‌کند که بدون خطا تکمیل شده است و ادامه می‌دهد. \fIDEVICE\fR همچنان باز می‌شود اما می‌تواند /dev/null باشد (در یونیکس). توصیه می‌شود از \fI\-\-verbose\fR همراه با این گزینه استفاده کنید تا نمای کلی از آنچه رخ می‌داد به دست آورید.
.TP
\fB\-h\fR, \fB\-\-help\fR
پیام راهنمای استفاده را چاپ کرده و خارج می‌شود. در صورت استفاده مکرر، نام حالت‌ها و کوته‌نوشت‌های آن‌ها را نیز چاپ می‌کند.
.TP
\fB\-i\fR, \fB\-\-id\fR=\fIID\fR
این گزینه فیلد buffer id را در cdb تنظیم می‌کند. \fIID\fR مقداری بین 0 (پیش‌فرض) تا 255 (شامل هر دو) است.
.TP
\fB\-I\fR, \fB\-\-in\fR=\fIFILE\fR
داده‌ها را از فایل \fIFILE\fR می‌خواند که قرار است با دستور WRITE BUFFER ارسال شوند. اگر \fIFILE\fR برابر با '\-' باشد، ورودی استاندارد (stdin) تا رسیدن به پایان فایل (EOF) خوانده می‌شود (این عملکرد مشابه \fI\-\-read\-stdin\fR است). داده‌ها از ابتدای \fIFILE\fR خوانده می‌شوند، به جز زمانی که یک فایل معمولی باشد و گزینه \fI\-\-skip=SKIP\fR مشخص شده باشد.
.TP
\fB\-l\fR, \fB\-\-length\fR=\fILEN\fR
که در آن \fILEN\fR طول داده‌های ارسالی برای نوشتن روی دستگاه، بر حسب بایت است. اگر مشخص نشود (و طول نتواند از \fI\-\-in=FILE\fR یا \fI\-\-read\-stdin\fR استنباط شود)، مقدار پیش‌فرض صفر در نظر گرفته می‌شود. اگر این گزینه مشخص شده باشد و طول استنباط‌شده از \fI\-\-in=FILE\fR یا \fI\-\-read\-stdin\fR کمتر باشد (یا داده‌ای ارائه نشود)، از بایت‌های 0xff به عنوان بایت‌های پرکننده (fill bytes) استفاده می‌شود.
.TP
\fB\-m\fR, \fB\-\-mode\fR=\fIMO\fR
این گزینه فیلد MODE را در cdb تنظیم می‌کند. \fIMO\fR مقداری بین 0 (پیش‌فرض) تا 31 (شامل هر دو) است. از طرف دیگر، می‌توان از کوته‌نوشت استفاده کرد. بخش حالت‌ها (MODES) در زیر را ببینید. برای فهرست کردن کوته‌نوشت‌های موجود در زمان اجرا، یک مقدار نامعتبر وارد کنید (مانند '\-\-mode=xxx') یا از گزینه '\-hh' استفاده کنید.
.TP
\fB\-o\fR, \fB\-\-offset\fR=\fIOFF\fR
این گزینه فیلد BUFFER OFFSET را در cdb تنظیم می‌کند. \fIOFF\fR مقداری بین 0 (پیش‌فرض) تا 2**24\-1 است. این مقدار یک آفست بایتی است.
.TP
\fB\-r\fR, \fB\-\-read\-stdin\fR
داده‌ها را از ورودی استاندارد تا رسیدن به پایان فایل (EOF) می‌خواند. این داده‌ها همراه با دستور WRITE BUFFER به \fIDEVICE\fR ارسال می‌شوند. عملکرد این گزینه مشابه استفاده از '\-\-in=\-' است. قبلاً نام بلند این گزینه \fI\-\-raw\fR بود و همچنان ممکن است برای سازگاری با نسخه‌های پیشین استفاده شود.
.TP
\fB\-s\fR, \fB\-\-skip\fR=\fISKIP\fR
این گزینه تنها زمانی فعال است که \fI\-\-in=FILE\fR مشخص شده باشد و \fIFILE\fR یک فایل معمولی باشد، نه stdin. داده‌ها از آفست بایتی \fISKIP\fR تا انتهای فایل (یا مقداری که با \fI\-\-length=LEN\fR مشخص شده است) خوانده می‌شوند. در صورت عدم تعیین، آفست بایتی پیش‌فرض برابر با 0 خواهد بود (یعنی ابتدای فایل).
.TP
\fB\-S\fR, \fB\-\-specific\fR=\fIMS\fR
\fIMS\fR فیلد MODE SPECIFIC در cdb است. این یک فیلد ۳ بیتی است، بنابراین مقادیر 0 تا 7 پذیرفته می‌شوند. این فیلد در بازبینی 32 استاندارد SPC\-4 معرفی شد و می‌تواند برای مشخص کردن رویدادهای اضافی که ریزکد معوق را فعال می‌کنند (زمانی که \fIMO\fR برابر با 0xD است) استفاده شود.
.TP
\fB\-t\fR, \fB\-\-timeout\fR=\fITO\fR
\fITO\fR مهلت زمانی دستور (بر حسب ثانیه) برای هر دستور WRITE BUFFER صادرشده توسط این ابزار است. مقدار پیش‌فرض آن 300 ثانیه (5 دقیقه) است و تنها در صورتی که این مقدار کافی نباشد باید تغییر کند.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
سطح پرگویی خروجی (خروجی اشکال‌زدایی) را افزایش می‌دهد.
.TP
\fB\-V\fR, \fB\-\-version\fR
رشته نسخه را چاپ کرده و سپس خارج می‌شود.
.SH "حالت‌ها (MODES)"
در ادامه فهرستی از تنظیمات دستور WRITE BUFFER برای فیلد MODE آمده است.
ابتدا کوته‌نوشتی که توسط آرگومان \fIMO\fR این ابزار پذیرفته می‌شود ذکر شده است.
پس از کوته‌نوشت در قلاب‌ها، مقادیر معادل ده‌دهی و هگزادسیمال متناظر که می‌توان برای \fIMO\fR داد آمده‌اند. موارد زیر به ترتیب عددی فهرست شده‌اند.
.TP
hd  [0, 0x0]
ترکیب سرآیند و داده (در SPC\-4 منسوخ شده است).
.TP
vendor  [1, 0x1]
وابسته به سازنده (Vendor specific).
.TP
data  [2, 0x2]
داده (در SPC\-3 به نام "Write Data" خوانده می‌شد).
.TP
dmc  [4, 0x4]
بارگیری ریزکد و فعال‌سازی (در SPC\-3 به نام "Download microcode" خوانده می‌شد).
.TP
dmc_save  [5, 0x5]
بارگیری ریزکد، ذخیره و فعال‌سازی (در SPC\-3 به نام "Download microcode and save" خوانده می‌شد).
.TP
dmc_offs  [6, 0x6]
بارگیری ریزکد همراه با آفست و فعال‌سازی (در SPC\-3 به نام "Download microcode with offsets" خوانده می‌شد).
.TP
dmc_offs_save  [7, 0x7]
بارگیری ریزکد همراه با آفست، ذخیره و فعال‌سازی (در SPC\-3 به نام "Download microcode with offsets and save" خوانده می‌شد).
.TP
echo  [10, 0xa]
نوشتن داده در بافر انعکاس (در SPC\-3 به نام "Echo buffer" خوانده می‌شد).
.TP
dmc_offs_ev_defer  [13, 0xd]
بارگیری ریزکد همراه با آفست، انتخاب رویدادهای فعال‌سازی، ذخیره و تعویق فعال‌سازی (در SPC\-4 معرفی شد).
.TP
dmc_offs_defer  [14, 0xe]
بارگیری ریزکد همراه با آفست، ذخیره و تعویق فعال‌سازی (در SPC\-4 معرفی شد).
.TP
activate_mc  [15, 0xf]
فعال‌سازی ریزکد معوق (در SPC\-4 معرفی شد).
.TP
en_ex  [26, 0x1A]
فعال‌سازی پروتکل ارتباطی بسط‌دهنده و بافر انعکاس (در SPC\-4 منسوخ شد).
.TP
dis_ex  [27, 0x1B]
غیرفعال‌سازی پروتکل ارتباطی بسط‌دهنده (در SPC\-4 منسوخ شد).
.TP
deh  [28, 0x1C]
بارگیری تاریخچه خطای کلاینت برنامه (در SPC\-3 به نام "Download application log" خوانده می‌شد).
.SH "نکات (NOTES)"
اگر گزینه \fI\-\-length=LEN\fR مشخص نشده باشد، این ابزار تا ۸ مبی‌بایت (8 MiB) داده را از فایل داده‌شده \fIFILE\fR (یا stdin) می‌خواند. اگر مقدار بیشتری داده مورد نیاز است، باید گزینه \fI\-\-length=LEN\fR مشخص شود.
.PP
کاربر باید توجه داشته باشد که اکثر سیستم‌عامل‌ها محدودیت‌هایی برای مقدار داده‌ای که می‌توان با یک دستور SCSI ارسال کرد دارند. در لینوکس این امر به سازوکار گذر مستقیم (pass-through) مورد استفاده (مانند block SG_IO یا درایور sg) و تنظیمات مختلف در sysfs در سری هسته‌های لینوکس 2.6/3 (مانند /sys/block/sda/queue/max_sectors_kb) بستگی دارد. دستگاه‌ها (یعنی واحدهای منطقی یا logical units) نیز معمولاً محدودیت‌هایی برای حداکثر مقدار داده‌ای که می‌توانند در یک دستور مدیریت کنند دارند. این دو محدودیت ایجاب می‌کنند که با بزرگ‌تر و بزرگ‌تر شدن فایل‌های سفت‌افزار (firmware)، حالت‌های حاوی کلمه "offset" همراه با گزینه \fI\-\-bpw=CS\fR به کار روند. و مقدار \fICS\fR می‌تواند کاملاً کوچک باشد، برای مثال ۴۰۹۶ بایت، که منجر به ارسال دستورات WRITE BUFFER متعددی خواهد شد.
.PP
تلاش برای بارگیری یک فایل ریزکد/سفت‌افزار که بیش از حد بزرگ است ممکن است موجب بروز خطا در لایه گذر مستقیم شود (یعنی پیش از صدور دستور SCSI). در لینوکس چنین گزارش‌های خطایی ممکن است مبهم باشند، مانند "pass through os error invalid argument". فری‌بی‌اس‌دی (FreeBSD) چنین خطاهایی را به خوبی در کنسول دستگاه گزارش می‌دهد اما پیام خطای مبهمی را به این ابزار برمی‌گرداند.
.PP
بارگیری ریزکد نادرست روی یک دستگاه می‌تواند آن دستگاه را از کار بیندازد و غیرقابل استفاده کند. امید می‌رود که سازنده دستگاه پیش از فعال‌سازی داده‌ها، آن‌ها را اعتبارسنجی کند. اگر در cdb دستور SCSI WRITE BUFFER مقادیری نامناسب (مانند بیش از حد بزرگ بودن \fILEN\fR) داده شود، دستگاه باید با کلید حس (sense key) خطای ILLEGAL REQUEST و کد حس اضافی (additional sense code) خطای INVALID FIELD in CDB پاسخ دهد. اگر یک دستور WRITE BUFFER (یا توالی‌ای از آن‌ها) به دلیل بررسی‌های اعتبارسنجی سازنده دستگاه ناموفق باشد، باید با کلید حس ILLEGAL REQUEST و کد حس اضافی COMMAND SEQUENCE ERROR پاسخ دهد.
.PP
تمام اعداد ارائه‌شده همراه با گزینه‌ها ده‌دهی فرض می‌شوند. در غیر این صورت، مقادیر عددی می‌توانند به صورت هگزادسیمال همراه با پیشوند "0x" یا "0X" (یا پسوند "h" یا "H") داده شوند.
.SH "مثال‌ها (EXAMPLES)"
مثال زیر سفت‌افزار جدیدی را به یک محفظه (enclosure) ارسال می‌کند. ارسال یک فایل ۱.۵ مگابایتی در یک دستور WRITE BUFFER باعث شد که محفظه به طور موقت قفل شود و سفت‌افزار به‌روزرسانی نشود. خرد کردن فایل سفت‌افزار به تکه‌های ۴ کیلوبایتی (یک حدس حساب‌شده) موفقیت‌آمیزتر بود:
.PP
  sg_write_buffer \-b 4k \-m dmc_offs_save \-I firmware.bin /dev/sg4
.PP
به‌روزرسانی سفت‌افزار در چرخه خاموش و روشن شدن (power cycle) بعدی محفظه رخ داد. در یک محفظه مدرن، صفحه Extended Inquiry VPD نشان می‌دهد که ارتقای سفت‌افزار در چه شرایطی رخ خواهد داد.
.SH "وضعیت خروج (EXIT STATUS)"
وضعیت خروج sg_write_buffer در صورت موفقیت 0 است. در غیر این صورت به صفحه راهنمای sg3_utils(8) مراجعه کنید.
.SH "نویسندگان (AUTHORS)"
نوشته‌شده توسط Luben Tuikov و Douglas Gilbert.
.SH "گزارش باگ‌ها (REPORTING BUGS)"
گزارش باگ‌ها به <dgilbert at interlog dot com>.
.SH "حق نشر (COPYRIGHT)"
Copyright \(co 2006\-2018 Luben Tuikov and Douglas Gilbert
.br
این نرم‌افزار تحت مجوز BSD\-2\-Clause توزیع شده است. هیچ تضمینی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب با یک هدف خاص.
.SH "همچنین ببینید (SEE ALSO)"
.B sg_read_buffer, sg_ses_microcode(sg3_utils)