.TH SG_RAW "8" "May 2023" "sg3_utils\-1.48" SG3_UTILS
.SH "نام (NAME)"
sg_raw \- ارسال دستور دلخواه SCSI یا NVMe به یک دستگاه
.SH "خلاصه دستور (SYNOPSIS)"
.B sg_raw
[\fI\-\-binary\fR] [\fI\-\-cmdfile=CF\fR] [\fI\-\-cmdset=CS\fR]
[\fI\-\-enumerate\fR] [\fI\-\-help\fR] [\fI\-\-infile=IFILE\fR]
[\fI\-\-nosense\fR] [\fI\-\-nvm\fR] [\fI\-\-outfile=OFILE\fR] [\fI\-\-raw\fR]
[\fI\-\-readonly\fR] [\fI\-\-request=RLEN\fR] [\fI\-\-scan=FO,LO\fR]
[\fI\-\-send=SLEN\fR] [\fI\-\-skip=KLEN\fR] [\fI\-\-timeout=SECS\fR]
[\fI\-\-verbose\fR] [\fI\-\-version\fR]
\fIDEVICE\fR [CDB0 CDB1 ...]
.SH "توضیحات (DESCRIPTION)"
این ابزار یک دستور دلخواه SCSI (بین ۶ تا ۲۵۶ بایت) را به
\fIDEVICE\fR
ارسال می‌کند. ممکن است هیچ انتقال داده‌ای همراه آن نباشد؛ یا داده‌ها ممکن است از یک فایل خوانده شده و به
\fIDEVICE\fR
ارسال شوند؛ یا داده‌ها ممکن است از
\fIDEVICE\fR
دریافت شده و سپس نمایش داده شوند یا در یک فایل نوشته شوند. در صورت پشتیبانی رابط عبور مستقیم (pass through)، دستورات دوطرفه (bidirectional) نیز ممکن است ارسال شوند (یعنی شامل داده‌هایی که هم به
\fIDEVICE\fR
ارسال می‌شوند و هم از
\fIDEVICE\fR
دریافت می‌گردند).
.PP
طول دستور SCSI ممکن است بین ۶ تا ۲۵۶ بایت باشد. هر بایت دستور در قالب هگزادسیمال ساده (00..FF) بدون پیشوند یا پسوند مشخص می‌شود. دستور را می‌توان در خط فرمان یا از طریق گزینه
\fI\-\-cmdfile=CF\fR
مشخص کرد. بخش «مثال‌ها» را در ادامه ببینید.
.PP
دستورات از طریق یک رابط عمومی SCSI (یا generic SCSI) عبور می‌کنند که برای چندین سیستم‌عامل از جمله لینوکس، FreeBSD و ویندوز پیاده‌سازی شده است.
.PP
پشتیبانی آزمایشی برای ارسال دستورات NVMe Admin و NVM به
\fIDEVICE\fR
اضافه شده است. از آنجا که تمام دستورات NVMe دارای طول ۶۴ بایت هستند، استفاده از گزینه
\fI\-\-cmdfile=CF\fR
بسیار راحت‌تر از تایپ کردن ۶۴ بایت دستور NVMe در خط فرمان است. بخش «پشتیبانی از NVME» را در ادامه ببینید. از یک روش ابتکاری (heuristic) بر پایه طول دستور برای تشخیص SCSI یا NVMe بودن دستور داده‌شده استفاده می‌شود؛ برای نادیده گرفتن این روش ابتکاری از گزینه
\fI\-\-cmdset=CS\fR
استفاده کنید.
.SH "گزینه‌ها (OPTIONS)"
آرگومان‌های گزینه‌های طولانی برای گزینه‌های کوتاه نیز الزامی هستند.
گزینه‌ها بر اساس نام گزینه طولانی به ترتیب الفبایی مرتب شده‌اند.
.TP
\fB\-b\fR, \fB\-\-binary\fR
داده‌ها را در قالب باینری تخلیه (dump) می‌کند، حتی هنگام نوشتن در خروجی استاندارد (stdout).
.TP
\fB\-c\fR, \fB\-\-cmdfile\fR=\fICF\fR
\fICF\fR
نام فایلی است که حاوی دستور مورد نظر برای اجرا می‌باشد. بدون این گزینه، دستور باید در خط فرمان، پس از گزینه‌ها و
\fIDEVICE\fR
داده شود.
.TP
\fB\-C\fR, \fB\-\-cmdset\fR=\fICS\fR
\fICS\fR
عددی برای مشخص کردن مجموعه دستوری مورد استفاده است (یعنی SCSI یا NVMe). مقدار 0، که پیش‌فرض است، باعث استفاده از یک روش ابتکاری بر پایه طول دستور می‌شود. برای نادیده گرفتن این روش ابتکاری و انتخاب مجموعه دستوری SCSI از مقدار 1 برای
\fICS\fR
استفاده کنید. برای نادیده گرفتن این روش ابتکاری و انتخاب مجموعه دستوری NVMe از مقدار 2 برای
\fICS\fR
استفاده کنید.
.TP
\fB\-h\fR, \fB\-\-help\fR
نمایش اطلاعات نحوه استفاده و خروج.
.TP
\fB\-i\fR, \fB\-\-infile\fR=\fIIFILE\fR
خواندن داده‌های باینری از
\fIIFILE\fR
به جای stdin. این گزینه در صورتی که
\fB\-\-send\fR
مشخص نشده باشد نادیده گرفته می‌شود. آن داده‌ها، در صورت استفاده، به بافر «داده‌های خروجی» ("data\-out") دستور تبدیل خواهند شد.
.TP
\fB\-n\fR, \fB\-\-nosense\fR
اطلاعات Sense مربوط به SCSI نمایش داده نشود.
.TP
\fB\-N\fR, \fB\-\-nvm\fR
هنگام ارسال دستورات NVMe، مجموعه دستورات Admin پیش‌فرض فرض می‌شود. برای ارسال مجموعه دستورات NVM (مانند دستورات Read و Write (داده‌های کاربر)) این گزینه باید ارائه شود.
.TP
\fB\-o\fR, \fB\-\-outfile\fR=\fIOFILE\fR
نوشتن داده‌های دریافت شده از
\fIDEVICE\fR
در
\fIOFILE\fR.
آن داده‌ها بافر «داده‌های ورودی» ("data\-in") دستور هستند. داده‌ها به صورت باینری نوشته می‌شوند. به طور پیش‌فرض، داده‌ها با قالب هگزادسیمال در stdout ریخته می‌شوند.
اگر
\fIOFILE\fR
برابر با '\-' باشد، داده‌ها به صورت باینری در stdout ریخته می‌شوند.
این گزینه در صورتی که
\fI\-\-request\fR
مشخص نشده باشد نادیده گرفته می‌شود.
.TP
\fB\-w\fR, \fB\-\-raw\fR
تفسیر
\fICF\fR
(یعنی فایل دستور) به عنوان فایلی حاوی داده‌های باینری. حالت پیش‌فرض این است که فرض شود فایل حاوی مقادیر هگزادسیمال ASCII است.
.TP
\fB\-R\fR, \fB\-\-readonly\fR
باز کردن
\fIDEVICE\fR
به صورت فقط‌خواندنی. حالت پیش‌فرض (بدون این گزینه) باز کردن آن به صورت خواندنی\-نوشتنی است.
.TP
\fB\-r\fR, \fB\-\-request\fR=\fIRLEN\fR
انتظار دریافت تا سقف
\fIRLEN\fR
بایت داده از
\fIDEVICE\fR.
مقدار
\fIRLEN\fR
می‌تواند دارای پسوند 'k' باشد تا به جای بایت، از کیلوبایت (۱۰۲۴ بایت) استفاده شود. مقدار
\fIRLEN\fR
در مبنای ده‌دهی است مگر اینکه دارای پیشوند '0x' یا پسوند 'h' باشد.
.br
اگر
\fIRLEN\fR
بیش از حد کوچک باشد (یعنی یا کوچک‌تر از مقدار مشخص‌شده توسط cdb (معمولاً فیلد "allocation length") و/یا کوچک‌تر از مقداری که
\fIDEVICE\fR
سعی در بازگرداندن آن دارد)، درایور HBA ممکن است خطایی گزارش کند. بزرگ‌تر تعیین کردن
\fIRLEN\fR
از مقدار مورد نیاز نباید مشکلی ایجاد کند. اکثر دستورات "data\-in" مربوط به SCSI یک بلوک داده برمی‌گردانند که (در بایت‌های اولیه خود) شامل طولی است که
\fIDEVICE\fR
در صورت کافی بودن اندازه فیلد "allocation length" در cdb «مایل است» ارسال کند. در عمل،
\fIDEVICE\fR
بیش از تعداد بایت‌های مشخص‌شده در فیلد "allocation length" در cdb بازنخواهد گرداند.
.TP
\fB\-Q\fR, \fB\-\-scan\fR=\fIFO\fR,\fILO\fR
پویش محدوده‌ای از آپ‌کدها (opcodes؛ یعنی بایت اول هر دستور). اولین آپ‌کد در این پویش
\fIFO\fR
است (که ده‌دهی است مگر اینکه دارای پیشوند '0x' یا پسوند 'h' باشد). آخرین آپ‌کد در پویش
\fILO\fR
است. حداکثر مقدار
\fILO\fR
برابر ۲۵۵ است. بایت‌های باقی‌مانده از دستور SCSI/NVMe همان مقادیری هستند که هنگام فراخوانی برنامه داده شده‌اند.
.br
هشدار: این گزینه می‌تواند
.B خطرناک
باشد. ارسال دستورات تا حدی تصادفی به یک دستگاه می‌تواند نتایج غیرمنتظره‌ای به همراه داشته باشد. توصیه می‌شود از این گزینه به همراه گزینه
\fI\-\-cmdset=CS\fR
که در آن
\fICS\fR
برابر ۱ یا ۲ است استفاده شود تا از احتمال تغییر مجموعه دستوری در طول پویش جلوگیری به عمل آید.
.TP
\fB\-s\fR, \fB\-\-send\fR=\fISLEN\fR
خواندن
\fISLEN\fR
بایت داده، چه از stdin یا از یک فایل، و ارسال آن‌ها به
\fIDEVICE\fR.
در لایه انتقال SCSI، مقدار
\fISLEN\fR
طول (به بایت) بافر "data\-out" خواهد شد. مقدار
\fISLEN\fR
در مبنای ده‌دهی است مگر اینکه دارای پیشوند '0x' یا پسوند 'h' باشد.
.br
مسئولیت اطمینان از این که طول "data\-out" ضمنی یا تصریح‌شده در cdb با
\fISLEN\fR
همخوانی دارد بر عهده کاربر است. توجه داشته باشید که برخی از دستورات رایج SCSI مانند WRITE(10) دارای یک فیلد "transfer length" هستند که واحد آن بلوک‌های منطقی است (که معمولاً دارای طول ۵۱۲ یا ۴۰۹۶ بایت هستند).
.TP
\fB\-k\fR, \fB\-\-skip\fR=\fIKLEN\fR
رد کردن
\fIKLEN\fR
بایت اول از فایل ورودی یا جریان ورودی. این گزینه در صورتی که
\fI\-\-send\fR
مشخص نشده باشد نادیده گرفته می‌شود. اگر
\fI\-\-send\fR
مشخص شده باشد و این گزینه داده نشود، صفر بایت رد می‌شود.
.TP
\fB\-t\fR, \fB\-\-timeout\fR=\fISECS\fR
انتظار تا سقف
\fISECS\fR
ثانیه برای اتمام دستور (پیش‌فرض: ۲۰). توجه داشته باشید که اگر زمان دستور به پایان برسد (timeout رخ دهد)، سیستم‌عامل ممکن است ابتدا با لغو (abort) دستور شروع کند و اگر ناموفق باشد ممکن است اقدام به ریست دستگاه نماید. شکل طولانیِ دیگر این گزینه
\fI\-\-tmo=SECS\fR
است.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
افزایش سطح پرگویی (verbosity). می‌تواند چندین بار استفاده شود.
.TP
\fB\-V\fR, \fB\-\-version\fR
نمایش اطلاعات نسخه و مجوز و خروج.
.SH "نکات (NOTES)"
ابزار sg_inq می‌تواند برای ارسال دستور INQUIRY به یک دستگاه جهت تعیین نوع دستگاه جانبی آن (مانند '1' برای یک دستگاه استریم مانند درایو نوار) استفاده شود که تعیین می‌کند دستگاه چه مجموعه‌های دستوری SCSI را باید پشتیبانی کند (مانند SPC و SSC). ابزار sg_vpd صفحات داده‌های حیاتی محصول (VPD) دستگاه را خوانده و رمزگشایی می‌کند که ممکن است شامل اطلاعات مفیدی باشند.
.PP
امکان ارسال CDB بزرگ‌تر از ۱۶ بایت (و در برخی موارد بزرگ‌تر از ۱۲ بایت) ممکن است توسط رابط عبور مستقیم (pass\-through)، درایور سطح پایین یا لایه انتقال محدود شود. در سری ۳ هسته‌های لینوکس، درایور bsg می‌تواند CDBهای طولانی‌تر را مدیریت کند؛ دستگاه‌های بلوکی (مانند /dev/sdc) که از طریق فراخوانی SG_IO ioctl مورد دسترسی قرار می‌گیرند نمی‌توانند CDBهای بیش از ۱۶ بایت را پردازش کنند؛ و درایور sg از هسته ۳.۱۷ لینوکس به بعد قادر به مدیریت CDBهای طولانی‌تر است.
.PP
نام دستور CDB تعریف‌شده توسط T10 برای CDB ارائه‌شده در صورت مشخص شدن گزینه '\-vv' نمایش داده می‌شود. نحو خط فرمان همچنان باید صحیح باشد، بنابراین می‌توان از /dev/null برای
\fIDEVICE\fR
استفاده کرد زیرا رمزگشایی نام دستور CDB پیش از بررسی
\fIDEVICE\fR
انجام می‌شود.
.PP
هدف از گزینه
\fI\-\-scan=FO,LO\fR
این است که فرایند یافتن دستورات پنهان یا مستندنه‌شده را تا حدودی ساده‌تر کند. این گزینه باید با احتیاط استفاده شود؛ به عنوان مثال هنگام بررسی دستورات SCSI خاصِ سازنده:
'sg_raw \-\-cmdset=1 \-\-scan=0xc0,0xff /dev/sg1 0 0 0 0 0 0'.
.SH "پشتیبانی از NVME (NVME SUPPORT)"
پشتیبانی از NVMe (یا همان NVM Express) در حال حاضر آزمایشی است. مفاهیم NVMe به طور منطقی بر معماری SCSI منطبق می‌شوند. یک واحد منطقی (LU) در SCSI مشابه با یک فضای نام (namespace) در NVMe است (اگرچه LUN 0 در SCSI بسیار رایج است در حالی که شناسه‌های فضای نام از ۱ شروع می‌شوند). یک دستگاه مقصد (target) در SCSI مشابه با یک کنترل‌کننده در NVMe است. دستورات SCSI از ۶ تا ۲۶۰ بایت متغیر هستند (اگرچه بلوک‌های توصیف‌کننده دستور SCSI یا همان cdb_ها که بیش از ۳۲ بایت طول داشته باشند رایج نیستند) در حالی که تمام دستورات NVMe در حال حاضر دارای طول ۶۴ بایت هستند. معماری SCSI تمایز آشکاری میان آغازگر (initiator - که اغلب HBA نامیده می‌شود) و مقصد (target - یا دستگاه) قائل می‌شود در حالی که (دست‌کم روی بستر ارتباطی PCIe) کنترل‌کننده NVMe هر دو نقش را ایفا می‌کند.
این ابزار به طور پیش‌فرض فرض می‌کند که دستور ۶۴ بایتیِ ارائه‌شده توسط کاربر متعلق به مجموعه دستورات Admin مربوط به NVMe است. برای صدور دستورات از مجموعه دستورات "NVM"، گزینه
\fI\-\-nvm\fR
باید ارائه شود. دستورات Admin و NVM به صف ارسال ۰ (submission queue 0) فرستاده می‌شوند.
.PP
یک تفاوت چشمگیر این است که SCSI از نمایش big endian برای اعداد صحیح بزرگ‌تر از ۸ بیت (یعنی بزرگ‌تر از ۱ بایت) استفاده می‌کند در حالی که NVMe از نمایش little endian استفاده می‌نماید (مانند بیشتر مواردی که از سازمان اینتل سرچشمه گرفته‌اند). مشخصات NVMe از کلمه‌ها یا Words (۱۶ بیت)، کلمه‌های دوگانه یا Double Words (۳۲ بیت) و گاهی کلمه‌های چهارگانه یا Quad Words (۶۴ بیت) صحبت می‌کنند و الزامات ترازسازی (alignment) سخت‌گیرانه‌تری نسبت به SCSI دارند.
.PP
تفاوتی که بر این ابزار تأثیر می‌گذارد این است که NVMe اشاره‌گرهایی به حافظه میزبان را در درون دستورات خود قرار می‌دهد در حالی که SCSI این جزئیات را به لایه انتقالی که استفاده می‌کند (مانند SAS، iSCSI، SRP) واگذار می‌نماید. از آنجا که این ابزار دستور را از کاربر دریافت می‌کند (چه در خط فرمان یا در فایلی با نام
\fICF\fR)
اما خود ابزار بافر data\-in یا data\-out را بنا به نیاز تخصیص می‌دهد، کاربر از پیش نمی‌داند آدرس آن بافر چه خواهد بود. برخی آدرس‌های ویژه برای کمک به این مسئله معرفی شده‌اند: آدرس 0xfffffffffffffffe به عنوان «استفاده از آدرس بافر data\-in» تفسیر می‌شود در حالی که 0xfffffffffffffffd به عنوان «استفاده از آدرس بافر data\-out» تفسیر می‌گردد. از آنجا که NVMe از نمادگذاری little endian استفاده می‌کند، آن آدرس نخست در جریان بایت‌های دستور NVMe به صورت "fe" و به دنبال آن هفت "ff" ظاهر می‌شود. ترتیب مشابهی برای طول آن بافر (به بایت) در نظر گرفته شده است، اما از آنجا که آن یک مقدار ۳۲ بیتی (در متن اصلی: 32 byte) است، ۴ بایت نخست (همگی "ff") حذف می‌شوند.
.PP
چندین نمونه از فایل‌های دستور را می‌توان در دایرکتوری inhex از بسته سورس تاربال (tarball) این ابزار یافت:
nvme_identify_ctl.hex، nvme_dev_self_test.hex، nvme_read_ctl.hex و nvme_write_ctl.hex .
.PP
توجه و احتیاط: استاندارد NVMe اغلب به برخی از فیلدهای خود با عنوان "0's based" (شروع از صفر) اشاره می‌کند. این‌ها معمولاً شمارش چیزی شبیه به تعداد بلوک‌های خوانده‌شدنی هستند. برای مثال در دستور NVMe Read، یک فیلد تعداد بلوک‌های "0's based" حاوی مقدار ۳ به معنای خواندن ۴ بلوک است! خیر، این یک شوخی نیست.
.SH "مثال‌ها (EXAMPLES)"
این مثال‌ها، به جز مورد آخر، از نام‌های دستگاه‌های لینوکس استفاده می‌کنند. برای نام‌های دستگاه‌های مناسب در سایر سیستم‌های عامل پشتیبانی‌شده، صفحه راهنمای
.BR sg3_utils (8)
را ببینید.
.TP
sg_raw /dev/scd0 1b 00 00 00 02 00
خارج کردن رسانه (دیسک) از درایو سی‌دی /dev/scd0.
.TP
sg_raw \-r 1k /dev/sg0 12 00 00 00 60 00
اجرای یک دستور INQUIRY روی /dev/sg0 و ریختن داده‌های پاسخ (حداکثر تا ۱۰۲۴ بایت) در stdout.
.TP
sg_raw \-s 512 \-i i512.bin /dev/sda 3b 02 00 00 00 00 00 02 00 00
ارائه مثالی از نوشتن ۵۱۲ بایت روی یک سکتور از دیسک تا حدی خطرناک است. به جای آن، این مثال فایل i512.bin (با فرض داشتن طول ۵۱۲ بایت) را می‌خواند و از دستور SCSI WRITE BUFFER برای ارسال آن به بافر "data" (یعنی حالت ۲) استفاده می‌کند. این یک عملیات ایمن است.
.TP
sg_raw \-r 512 \-o o512.bin /dev/sda 3c 02 00 00 00 00 00 02 00 00
این دستور از دستور SCSI READ BUFFER برای خواندن ۵۱۲ بایت از بافر "data" (یعنی حالت ۲) و سپس نوشتن آن در فایل o512.bin استفاده می‌کند. هنگامی که همراه با مثال قبلی استفاده شود، اگر هر دو دستور کار کنند، دستور 'cmp i512.bin o512.bin' باید تطابق آن‌ها را نشان دهد.
.TP
sg_raw \-\-infile=urandom.bin \-\-send=512 \-\-request=512 \-\-outfile=out.bin "/dev/bsg/7:0:0:0" 53 00 00 00 00 00 00 00 01 00
این یک دستور دوطرفه (bidirectional) به نام XDWRITEREAD(10) است که از طریق یک دستگاه bsg در لینوکس ارسال می‌شود. توجه داشته باشید که داده‌ها از "urandom.bin" خوانده شده و به دستگاه فرستاده می‌شوند (data\-out)، در حالی که داده‌های حاصل (data\-in) در فایل "out.bin" قرار می‌گیرند. همچنین توجه داشته باشید که طول هر دو ۵۱۲ بایت است که متناظر با طول انتقال ۱ (بلوک) در cdb می‌باشد (یعنی بایت ماقبل آخر). فایل urandom.bin را می‌توان به این صورت ایجاد کرد:
.br
dd if=/dev/urandom bs=512 count=1 of=urandom.bin
.TP
sg_raw.exe PhysicalDrive1 a1 0c 0e 00 00 00 00 00 00 e0 00 00
این مثال از ویندوز است و ارسال دستور ATA STANDBY IMMEDIATE را به PhysicalDrive1 نشان می‌دهد. این دستور ATA درون دستور SCSI ATA PASS\-THROUGH(12) گنجانده شده است (استاندارد SAT یا SAT\-2 را در https://www.t10.org ببینید). توجه داشته باشید که دستور STANDBY IMMEDIATE هیچ داده اضافی ارسال یا دریافت نمی‌کند؛ با این حال اگر ناموفق باشد، داده‌های sense باید بازگردانده شده و نمایش داده شوند.
.TP
برای نمونه‌های NVMe فایل‌هایی را در پوشه inhex این بسته که با 'nvme_' شروع می‌شوند، مانند inhex/nvme_identify_ctl.hex ببینید.
.SH "وضعیت خروج (EXIT STATUS)"
وضعیت خروج sg_raw در صورت موفقیت 0 است. در غیر این صورت صفحه راهنمای
.BR sg3_utils (8)
را ببینید.
.SH "نویسنده (AUTHOR)"
نوشته‌شده توسط Ingo van Lil
.SH "گزارش باگ‌ها (REPORTING BUGS)"
گزارش باگ‌ها به <inguin at gmx dot de> یا به <dgilbert at interlog dot com>.
.SH "حق نشر (COPYRIGHT)"
حق نشر \(co 2001\-2023 Ingo van Lil
.br
این نرم‌افزار تحت مجوز GPL نسخه ۲ توزیع شده است. هیچ تضمینی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب با یک هدف خاص.
.SH "همچنین ببینید (SEE ALSO)"
.B sg_inq, sg_vpd, sg3_utils (sg3_utils), plscsi