SG_SES(8) SG3_UTILS SG_SES(8)

sg_ses - دسترسی به یک دستگاه خدمات محفظه SCSI (SES)

sg_ses [--all] [--ALL] [--descriptor=DES] [--dev-slot-num=SN] [--eiioe=A_F] [--filter] [--get=STR] [--hex] [--index=IIA | --index=TIA,II] [--inner-hex] [--join] [--json[=JO]] [--js-file=JFN] [--maxlen=LEN] [--no-config] [--no-time] [--page=PG] [--quiet] [--raw] [--readonly] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE

sg_ses --control [--byte1=B1] [--clear=STR] [--data=H,H...] [--data=@FN] [--descriptor=DES] [--dev-slot-num=SN] [--index=IIA | --index=TIA,II] [--mask] [--maxlen=LEN] [--nickname=SEN] [--nickid=SEID] [--page=PG] [--readonly] [--sas-addr=SA] [--set=STR] [--verbose] DEVICE

sg_ses --data=@FN --status [--raw --raw] [<تمام گزینه‌ها از شکل اول>]
sg_ses --inhex=FN --status [--raw --raw] [<تمام گزینه‌ها از شکل اول>]

sg_ses [--enumerate] [--index=IIA] [--list] [--help] [--version]

اطلاعات مدیریتی را از یک دستگاه خدمات محفظه SCSI (SES) واکشی می‌کند. این ابزار همچنین می‌تواند وضعیت یک دستگاه SES را تغییر دهد. DEVICE باید یک دستگاه SES باشد که ممکن است یک پردازنده اختصاصی خدمات محفظه باشد؛ در این حالت، Peripheral Device Type (نوع دستگاه جانبی) در پاسخ INQUIRY برابر با 13 [0xd] است. همچنین ممکن است به نوع دیگری از دستگاه SCSI (مانند یک دیسک) متصل باشد که در این صورت، بیت EncServ در پاسخ INQUIRY آن تنظیم شده است.

اگر آرگومان DEVICE بدون هیچ گزینه‌ای داده شود، نام تمام صفحه‌های تشخیصی SES (موسوم به dpage) پشتیبانی‌شده فهرست می‌شوند. بیشتر dpageهای نام‌برده‌شده در استانداردها و پیش‌نویس‌های SES تعریف شده‌اند. جدیدترین مرجع برای این ابزار، پیش‌نویس سند SCSI Enclosure Services 4 با شناسه T10/BSR INCITS 555 ویرایش 5 در https://www.t10.org است. استانداردهای موجود برای SES، SES-2 و SES-3 به ترتیب ANSI INCITS 305-1998، ANSI INCITS 448-2008 و ANSI INCITS 518-2017 هستند.

اکسپندرهای SAS معمولاً یک دستگاه SES متصل از طریق یک پورت مجازی دارند. برخی HBAها (آغازگرهای SCSI) ترجیح می‌دهند یک دستگاه SES را به صورت داخلی در معرض دید قرار دهند. این بدان معناست که زیرسیستم SCSI در ماشین میزبان می‌تواند دستگاه SES را ببیند، اما دستگاه‌های متصل به آن HBA (مانند یک اکسپندر SAS) نمی‌توانند دستگاه SES مربوط به HBA را ببینند. آن دستگاه SES داخلی ممکن است دما(های) HBA و اتصال یا عدم اتصال دستگاه‌ها به پورت‌های SCSI آن را گزارش دهد.

شکل اول نمایش‌داده‌شده در SYNOPSIS (خلاصه دستور) برای واکشی و رمزگشایی dpageها یا فیلدها از DEVICE مربوط به SES است. یک دستور SCSI RECEIVE DIAGNOSTIC RESULTS به DEVICE ارسال می‌شود تا پاسخ هر dpage دریافت گردد. به جای رمزگشایی یک dpage واکشی‌شده، محتوای آن می‌تواند با استفاده از گزینه‌های --hex یا --raw --raw در قالب هگز یا باینری خروجی داده شود.

شکل دوم در SYNOPSIS برای تغییر دادن dpageها یا فیلدهای نگه‌داری‌شده در DEVICE مربوط به SES است. یک دستور SCSI SEND DIAGNOSTIC حاوی یک dpage «کنترلی» (control) به DEVICE ارسال می‌شود تا تغییرات را اعمال کند. تغییر وضعیت یک محفظه (مانند درخواست چشمک زدن نشانگر LED مربوط به "ident" (مکان‌یابی) روی کشوی دیسک در یک آرایه) معمولاً با استفاده از چرخه خواندن-اصلاح-نوشتن (read-modify-write) انجام می‌شود. به بخش «تغییر وضعیت» در زیر مراجعه کنید.

شکل سوم در SYNOPSIS دارای دو فراخوانی معادل است که نشان داده شده‌اند. آن‌ها محتوای فایلی (به نام FN) را رمزگشایی می‌کنند که نمایش هگزادسیمال یا باینری پاسخ یک یا چند dpage مربوط به SES را در بر دارد. معمولاً یک فراخوانی پیشین از شکل اول این ابزار با گزینه '-HHHH' آن فایل را ایجاد کرده است. از آنجا که هیچ دستور SCSI ارسال نمی‌شود، آرگومان DEVICE در صورت ارائه نادیده گرفته خواهد شد.

آخرین شکل در SYNOPSIS، گزینه‌های مربوط به ارائه راهنمای خط فرمان (یعنی اطلاعات نحوه استفاده)، فهرست کردن جدول‌های اطلاعاتی dpage و فیلد نگه‌داری‌شده توسط این ابزار (--enumerate)، یا چاپ رشته نسخه این ابزار را نشان می‌دهد.

صفحه وبی برای بررسی این ابزار در https://sg.danny.cz/sg/sg_ses.html وجود دارد. پشتیبانی از بارگیری ریزکد به یک دستگاه SES در ابزار جداگانه‌ای به نام sg_ses_microcode قرار داده شده است.

در بخش‌های بعدی "dpage" به یک صفحه تشخیصی اشاره دارد، که یا با یک دستور SCSI RECEIVE DIAGNOSTIC RESULTS واکشی شده، یا با یک دستور SCSI SEND DIAGNOSTIC به DEVICE ارسال شده، یا از داده‌های ارائه‌شده توسط گزینه --data= یا --inhex=FN دریافت شده است.

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

خروجی گزینه --join و سپس سایر dpageهای SES را نشان می‌دهد. از آنجا که یک گزینه --join منفرد شامل dpage مربوط به Threshold In نمی‌شود، در بخش "other SES dpages" (سایر dpageهای SES) به طور جداگانه فهرست می‌گردد. در این زمینه، «سایر» به معنی تمام dpageهای SES است که به طور صریح توسط گزینه --join خروجی داده نشده‌اند.
برای خروجی دادن تمام صفحه‌ها بدون تلاش برای ادغام، از گزینه --page=all به جای این گزینه استفاده کنید.
اگر این گزینه دو بار استفاده شود، dpage مربوط به Threshold In (در صورت موجود بودن) در خروجی گزینه --join گنجانده می‌شود. توجه داشته باشید که اکنون dpage مربوط به Threshold In به طور جداگانه در بخش "other SES dpages" فهرست نمی‌شود. استفاده دو بار از این گزینه معادل با فراخوانی گزینه --ALL است.
این گزینه تا زمانی که گزینه --control داده نشده باشد، به طور ضمنی بیانگر گزینه --status است.
استفاده همزمان از این گزینه به همراه گزینه‌های -HHH، -HHHH یا -HHHHH خطا تلقی می‌شود زیرا خروجی گیج‌کننده‌ای تولید می‌کند. برای اجبار به انجام این کار، از -H به دفعات بیشتر استفاده کنید (برای بازدارندگی). در عوض، استفاده از گزینه --page=all همراه با گزینه‌های -HHH، -HHHH یا -HHHHH به احتمال زیاد خروجی مطلوب را تولید می‌کند: تخلیه تمام صفحه‌های تشخیصی SES به صورت هگز، مناسب برای تجزیه در آینده یا بازبینی چشمی با یک ویرایشگر متنی.
خروجی گزینه --join را که دو بار فراخوانی شده است، به همراه سایر dpageهای SES نشان می‌دهد. از آنجا که دو گزینه --join شامل dpage مربوط به Threshold In می‌شود، آن dpage به طور جداگانه در بخش "other SES dpages" فهرست نمی‌شود.
این گزینه تا زمانی که گزینه --control داده نشده باشد، به طور ضمنی بیانگر گزینه --status است.
برخی از dpageهای قابل‌تغییر ممکن است نیاز به تنظیم بایت ۱ (یعنی دومین بایت) داشته باشند. در dpage مربوط به Enclosure Control، بایت ۱ شامل بیت‌های INFO، NON-CRIT، CRIT و UNRECOV است. در dpageهای Subenclosure String Out، Subenclosure Nickname Control و Download Microcode Control، بایت ۱ شناسه زیرمحفظه است. زمانی فعال است که گزینه‌های --control و --data=H,H... استفاده شده باشند و مقدار پیش‌فرض آن 0 است. اگر از گزینه --clear=STR یا --set=STR استفاده شود، مقدار خوانده‌شده از بایت ۱ مجدداً روی بایت ۱ نوشته می‌شود. B1 در مبنای ده است مگر اینکه دارای پیشوند '0x' یا '0X' باشد (یا پسوند 'h' یا 'H' داشته باشد).
برای پاک کردن یک فیلد عنصر در dpage مربوط به Enclosure Control یا Threshold Out استفاده می‌شود. باید به همراه یک گزینه شاخص‌گذاری استفاده شود تا مشخص کند کدام عنصر باید تغییر یابد. اگر گزینه --page=PG داده نشود، dpage مربوط به Enclosure Control فرض می‌شود. به بخش‌های «قالب رشته» (STR FORMAT) و «پاک‌سازی، دریافت، تنظیم» (CLEAR, GET, SET) در زیر مراجعه کنید.
اطلاعات کنترلی را از طریق یک دستور SCSI SEND DIAGNOSTIC به DEVICE ارسال می‌کند. نمی‌توان هر دوی این گزینه و --status را مشخص کرد. در حال حاضر dpageهای Enclosure Control، String Out، Threshold Out، Array Control (در SES-2 منسوخ شده)، Subenclosure String Out، Subenclosure Nickname Control و Download Microcode قابل تنظیم هستند. اگر هر یک از گزینه‌های --clear=STR یا --set=STR داده شود، این گزینه به طور ضمنی در نظر گرفته می‌شود.
امکان تعیین رشته‌ای از بایت‌های هگزادسیمال (ASCII) جداشده با کاما را فراهم می‌کند (محدودیت ۱۰۲۴). رشته‌ای از بایت‌های هگز جداشده با فاصله (تکی) نیز مجاز است اما فهرست باید داخل علامت نقل‌قول قرار گیرد. این گزینه اجازه می‌دهد پارامترهای یک dpage کنترلی مشخص شوند. رشته ارائه‌شده نباید شامل ۴ بایت نخست (یعنی کد صفحه و طول) باشد. به بخش «داده‌های ارائه‌شده» (DATA SUPPLIED) در زیر مراجعه کنید.
یک یا چند رشته داده را از ورودی استاندارد (stdin) می‌خواند، محدودیت تقریباً 2**16 بایت است. stdin می‌تواند هگزادسیمال ASCII را به صورت فهرستی جداشده با کاما ارائه دهد (یعنی مانند گزینه --data=H,H...). علاوه بر این، فاصله‌ها، تب‌ها و شکست‌های خط به عنوان جداکننده از stdin مجاز هستند. هنگامی که یک EOF تشخیص داده شود، خواندن از stdin متوقف می‌شود. به بخش «داده‌های ارائه‌شده» (DATA SUPPLIED) در زیر مراجعه کنید.
یک یا چند رشته داده را از فایل به نام FN می‌خواند، محدودیت تقریباً 2**16 بایت است. محتوای فایل به همان شیوه‌ای که برای stdin در گزینه قبلی شرح داده شد، رمزگشایی می‌شود. به بخش «داده‌های ارائه‌شده» (DATA SUPPLIED) در زیر مراجعه کنید.
که در آن DES یک نام توصیف‌گر (رشته) است همان‌طور که در dpage مربوط به Element Descriptor یافت می‌شود. این یک روش شاخص‌گذاری سطح متوسط در مقایسه با گزینه‌های سطح پایین --index= است. اگر نام توصیف‌گر حاوی فاصله باشد، DES باید در علامت نقل‌قول (تکی یا دوگانه) قرار گیرد یا فاصله گریز داده شود (مثلاً یک بک‌اسلش قبل از آن قرار گیرد). به بخش «نام توصیف‌گر، شماره اسلات دستگاه و آدرس ساس» در زیر مراجعه کنید.
که در آن SN یک شماره اسلات دستگاه است که در dpage مربوط به Additional Element Status یافت می‌شود. تنها مدخل‌های مربوط به دستگاه‌های FCP و SAS (با EIP=1) دارای شماره اسلات دستگاه هستند. SN باید عددی در محدوده 0 تا 255 (شامل هر دو) باشد. 255 برای نشان دادن اینکه هیچ اسلات دستگاه متناظری وجود ندارد استفاده می‌شود. این یک روش شاخص‌گذاری سطح متوسط در مقایسه با گزینه‌های سطح پایین --index= است. به بخش «نام توصیف‌گر، شماره اسلات دستگاه و آدرس ساس» در زیر مراجعه کنید.
A_F یا رشته 'auto' است یا 'force'. در تفسیر فیلد 'element index' در dpage مربوط به Additional Element Status (موسوم به AES) بین SES-2 و SES-3 نوعی ابهام وجود داشت. بیت EIIOE برای رفع این مشکل معرفی شد اما همه محفظه‌ها با آن هماهنگ نشده‌اند. در پیش‌نویس بازنگری 12 از SES-3، بیت EIIOE به یک فیلد ۲ بیتی EIIOE گسترش یافت. استفاده از '--eiioe=force' صفحه تشخیصی AES را به گونه‌ای رمزگشایی می‌کند که گویی فیلد EIIOE روی 1 تنظیم شده است. استفاده از '--eiioe=auto' صفحه تشخیصی AES را طوری رمزگشایی می‌کند که گویی اگر اولین توصیف‌گر AES دارای بیت EIP تنظیم‌شده باشد و فیلد element index آن برابر 1 باشد، فیلد EIIOE روی 1 تنظیم شده است (به عبارت دیگر، روشی مکاشفه‌ای برای حدس زدن اینکه آیا فیلد EIIOE باید روی 1 تنظیم شود یا 0).
اگر محفظه فیلد واقعی EIIOE را روی 1 یا بیشتر تنظیم کند، این گزینه تأثیری ندارد. به کاربران HP JBOD توصیه می‌شود که --eiioe=auto را تنظیم کنند.
تمام نام‌های شناخته‌شده صفحه‌های تشخیصی (dpage) و عناصر SES را که این ابزار شناسایی می‌کند به همراه اختصارات پذیرفته‌شده توسط این ابزار برمی‌شمارد. اگر DEVICE داده شده باشد، آن را نادیده می‌گیرد. در واقع، این گزینه جداولی را که به صورت داخلی توسط این ابزار نگه‌داری می‌شوند، تخلیه می‌کند.
اگر --enumerate دو بار داده شود، نام‌های اختصاری شناسایی‌شده برای گزینه‌های --clear=STR، --get=STR و --set=STR فهرست می‌شوند. این ابزار پس از فهرست کردن این اطلاعات خارج می‌شود، بنابراین بیشتر گزینه‌های دیگر و DEVICE نادیده گرفته می‌شوند. از آنجا که اختصارات زیادی برای dpage مربوط به Enclosure Control/Status وجود دارد، می‌توان با دادن گزینه --index=IIA خروجی را بیشتر محدود کرد (مثلاً "sg_ses -ee -I ts"; برای نمایش فقط اختصارات مرتبط با نوع عنصر حسگر دما (Temperature Sensor Element Type) در dpage مربوط به Enclosure Control/Status).
میزان خروجی حاصل از dpage مربوط به Enclosure Status و dpage مربوط به Additional Element Status را کاهش می‌دهد. هنگامی که این گزینه داده شود، هر سطری که تمام پرچم‌های باینری آن پاک (یعنی 0) باشند فیلتر می‌شود (یعنی نادیده گرفته می‌شود). اگر سطری مقدار دیگری روی خود داشته باشد (مانند دما)، خروجی داده می‌شود. هنگامی که این گزینه دو بار استفاده شود، تنها عناصر مرتبط با فیلد "status=ok" (در dpage مربوط به Enclosure status) خروجی داده می‌شوند. گزینه --filter برای کاهش میزان خروجی تولیدشده توسط گزینه --join مفید است.
برای خواندن یک فیلد در یک عنصر وضعیت استفاده می‌شود. باید همراه با یک گزینه شاخص‌گذاری استفاده شود تا مشخص کند کدام عنصر باید خوانده شود. به طور پیش‌فرض dpage مربوط به Enclosure Status خوانده می‌شود؛ تنها dpageهای دیگری که می‌توانند خوانده شوند، dpageهای Threshold In و Additional Element Status هستند. اگر مقداری پیدا شود، در مبنای ده به stdout خروجی داده می‌شود (به طور پیش‌فرض) یا در مبنای شانزده با پیشوند "0x" در صورتی که گزینه --hex نیز داده شده باشد. به بخش‌های «قالب رشته» (STR FORMAT) و «پاک‌سازی، دریافت، تنظیم» (CLEAR, GET, SET) در زیر مراجعه کنید.
پیام نحوه استفاده را چاپ کرده و سپس خارج می‌شود. از آنجا که اطلاعات زیادی وجود دارد، به دو صفحه تقسیم شده است. مهم‌ترین اطلاعات در صفحه اول نمایش داده می‌شود. از این گزینه دو بار (مثلاً '-hh') برای چاپ صفحه دوم استفاده کنید. نکته: گزینه --enumerate نیز ممکن است به عنوان یک گزینه از نوع راهنما یا نحوه استفاده در نظر گرفته شود، و مانند این گزینه دارای شکل «دو بار داده‌شده» است: '-ee'.
اگر گزینه --get=STR داده شده باشد، مقدار یافت‌شده (در صورت وجود) را در مبنای شانزده با پیشوند "0x" خروجی می‌دهد. در غیر این صورت، پاسخ را در مبنای شانزده با یک آدرس/شاخص هگز در ابتدای هر سطر خروجی می‌دهد. اگر دو بار داده شود، یک نمایش ASCII در سمت راست هر سطر ارائه می‌شود. اگر سه بار یا بیشتر داده شود، تنها بایت‌های هگزادسیمال، ۱۶ بایت (یا کمتر) در هر سطر خروجی داده می‌شوند.
هنگامی که تمام عناصر حاصل از چند dpage در حال دسترسی باشند نادیده گرفته می‌شود (مانند زمانی که گزینه --join استفاده شده است). همچنین به گزینه --raw مراجعه کنید که ممکن است همراه با این گزینه استفاده شود.
برای تخلیه پاسخ یک یا چند dpage به stdout در قالب هگزادسیمال قابل تجزیه با ASCII، از -HHH یا -HHHH استفاده کنید. شکل سه‌گانه H فقط هگزادسیمال را خروجی می‌دهد که برای پاسخ یک dpage منفرد مناسب است. هنگامی که تمام dpageها تخلیه می‌شوند (مثلاً با --page=all)، شکل چهارگانه H نام هر dpage را به همراه علامت هش ('#') قبل از آن اضافه می‌کند. بنابراین خروجی شکل چهارگانه H همچنان قابل تجزیه است، به علاوه مشاهده و ویرایش احتمالی آن برای کاربران ساده‌تر است. استفاده از این گزینه به تعداد ۵ بار (مثلاً -HHHHH) کد صفحه را در مبنای شانزده پس از نام صفحه در توضیحِ قبل از نمایش هگزِ آن صفحه حالت اضافه می‌کند.
اگر گزینه --inner-hex نیز داده شده باشد، عملکرد این گزینه را تغییر می‌دهد. به توضیحات گزینه --inner-hex مراجعه کنید. دادن هر دوی -HHHH (یا بیشتر) و گزینه --inner-hex به عنوان خطا گزارش می‌شود.
توجه داشته باشید که معنای '-H' و '-HH' در نسخه "2.72 20230130" به منظور سازگاری با سایر ابزارهای این بسته و توضیحات این گزینه در صفحه راهنمای sg3_utils(8) جابجا شده است.
که در آن IIA یا یک شاخص تکی (II) یا یک اختصار نوع عنصر (A) است. به بخش «شاخص‌ها» در زیر مراجعه کنید. اگر گزینه --page=PG داده نشود، dpage مربوط به Enclosure Status (یا Control) فرض می‌شود. می‌تواند با گزینه --join یا یکی از گزینه‌های --clear=STR، --get=STR یا --set=STR استفاده شود. برای برشمردن اختصارات موجود نوع عنصر، از گزینه --enumerate استفاده کنید.
که در آن TIA,II یک شاخص سرآیند نوع (TI) یا اختصار نوع عنصر (A) است که پس از آن یک شاخص تکی (II) می‌آید. به بخش «شاخص‌ها» در زیر مراجعه کنید. اگر گزینه --page=PG داده نشود، dpage مربوط به Enclosure Status (یا Control) فرض می‌شود. می‌تواند با گزینه --join یا یکی از گزینه‌های --clear=STR، --get=STR یا --set=STR استفاده شود. برای برشمردن اختصارات موجود نوع عنصر، از گزینه --enumerate استفاده کنید.
که در آن FN یک نام فایل است. عملکردی معادل با گزینه --data=@FN دارد. اگر FN برابر '-' باشد، ورودی استاندارد (stdin) خوانده می‌شود. این گزینه به منظور سازگاری با سایر ابزارهای این بسته ارائه شده است که از --inhex=FN (یا --in=FN) به شیوه مشابهی استفاده می‌کنند. برای اطلاعات بیشتر به بخش "HEX, BINARY AND JSON FORMATS" در صفحه راهنمای sg3_utils مراجعه کنید.
سطوح بیرونی یک dpage وضعیت رمزگشایی و چاپ می‌شوند اما درونی‌ترین سطح(ها) (مانند Element Status Descriptor) در قالب هگز خروجی داده می‌شوند. برای dpageهایی که به dpage مربوط به Configuration وابسته‌اند، ساختار آن با این گزینه در نظر گرفته می‌شود، در حالی که وقتی از گزینه --no-config استفاده می‌شود، ساختار آن نادیده گرفته می‌شود. می‌تواند با یک گزینه شاخص‌گذاری و/یا گزینه‌های --join استفاده شود. این گزینه عمدتاً برای اشکال‌زدایی است.
این گزینه همچنین ممکن است با گزینه --json[=JO] برای کاستن از وابستگی رمزگشایی به سایر dpageها استفاده شود. این گزینه می‌تواند دو بار در این زمینه به کار رود. به بخش «اطلاعات JSON» در زیر مراجعه کنید.
گزینه --hex ممکن است همراه با این گزینه برای کنترل این موضوع که آیا متن ASCII در سمت راست هر سطر هگز از بایت‌ها ظاهر شود یا خیر، داده شود. بدون گزینه --hex، متن ASCII در سمت راست هر سطر هگز از بایت‌ها ظاهر می‌شود؛ اگر گزینه --hex یک بار ظاهر شود، هیچ بازنمایی ASCII ظاهر نخواهد شد.
عناصر حاصل از dpageهای Element Descriptor، Enclosure Status و Additional Element Status را گروه‌بندی می‌کند. اگر این گزینه دو بار داده شود، عناصر حاصل از dpage مربوط به Threshold In نیز گروه‌بندی می‌شوند. ترتیب توسط dpage مربوط به Configuration دیکته می‌شود، اما آن dpage به طور صریح نشان داده نمی‌شود.
ممکن است حجم سردرگم‌کننده‌ای از اطلاعات در خروجی "join" وجود داشته باشد. رفتار پیش‌فرض این است که همه‌چیز خروجی داده شود. چندین گزینه اضافی برای کاستن از مقدار نمایش‌داده‌شده ارائه شده است. اگر گزینه‌های شاخص‌گذاری داده شوند، فقط عناصر منطبق و فیلدهای مرتبط با آن‌ها خروجی داده می‌شوند. گزینه --filter (به توضیحات آن مراجعه کنید) می‌تواند برای کاهش مقدار خروجی اضافه شود. همچنین "--page=aes" (یا "-p 0xa";) می‌تواند برای جلوگیری از خروجی سطرهایی که فاقد مؤلفه dpage از نوع "aes" هستند اضافه شود. به بخش‌های «شاخص‌ها» و «نام توصیف‌گر، شماره اسلات دستگاه و آدرس ساس» در زیر مراجعه کنید.
این گزینه به طور ضمنی بیانگر گزینه --status است. دادن گزینه --control همراه با این گزینه یک خطا است.
خروجی به جای فرمت متن ساده، در قالب JSON خواهد بود. توجه داشته باشید که آرگومان‌های شکل کوتاه و بلند به خودی خود اختیاری هستند و در صورت وجود با "=" شروع می‌شوند و هیچ فاصله‌ای در اطراف آن "=" مجاز نیست.
صفحه راهنمای sg3_utils_json را ببینید یا از '?' برای JO استفاده کنید تا خلاصه‌ای دریافت نمایید. برای اطلاعات اختصاصی‌تر درباره خروجی JSON با این ابزار، به بخش «اطلاعات JSON» در زیر مراجعه کنید.
خروجی در قالب JSON است و به فایلی به نام JFN ارسال می‌شود. اگر آن فایل وجود داشته باشد، محتوای آن پاک (کوتاه) می‌شود. به طور پیش‌فرض، خروجی JSON به خروجی استاندارد (stdout) ارسال می‌گردد.
هنگامی که این گزینه داده شود، گزینه --json[=JO] به طور ضمنی در نظر گرفته می‌شود و نیازی به دادن آن نیست. گزینه --json[=JO] ممکن است همچنان برای تنظیم پارامتر JO روی مقادیر غیر پیش‌فرض مورد نیاز باشد.
این گزینه معادل با --enumerate است. به آن گزینه مراجعه کنید.
هنگام تغییر عناصر، عمل پیش‌فرض عبارت است از خواندن (عنصر وضعیت)، ماسک کردن، اصلاح (بر اساس --clear=STR یا --set=STR)، و سپس نوشتن دوباره به عنوان عنصر کنترلی. مرحله ماسک کردن در نسخه 1.98 از sg_ses جدید است و بر اساس مواردی است که در پیش‌نویس SES-3 بازنگری 6 مجاز شمرده شده (و در همان مکان قرار دارد). این ماسک‌ها ممکن است مانند گذشته دستخوش تکامل شوند. این گزینه منطق پیشین را که نادیده گرفتن مرحله ماسک بود، مجدداً برقرار می‌کند. اقدام پیش‌فرض (یعنی بدون این گزینه) اجرای مرحله ماسک در توالی خواندن-ماسک-اصلاح-نوشتن است.
LEN در فیلد ALLOCATION LENGTH از دستورات SCSI RECEIVE DIAGNOSTIC RESULTS ارسال‌شده توسط ابزار قرار می‌گیرد. این مقدار بیانگر حداکثر اندازه داده‌ای است که دستگاه SES می‌تواند بازگرداند (بر حسب بایت). این مقدار نمی‌تواند از 65535 تجاوز کند و مقدار پیش‌فرض آن 65532 (بایت) است. برخی سامانه‌ها ممکن است چنین اندازه‌های بزرگی را مجاز ندانند، از این رو نیاز به این گزینه است. اگر LEN کمتر از 0 یا بزرگ‌تر از 65535 باشد، یک خطا ایجاد می‌شود. اگر LEN برابر 0 باشد، مقدار پیش‌فرض استفاده می‌شود، در غیر این صورت اگر کمتر از 4 باشد نادیده گرفته می‌شود (و یک هشدار به stderr ارسال می‌گردد).
که در آن SEN نام مستعار جدید زیرمحفظه است. تنها ۳۲ نویسه (بایت) اول SEN استفاده می‌شود؛ در صورت ارائه نویسه‌های بیشتر، آن‌ها نادیده گرفته می‌شوند. به بخش «تنظیم نام مستعار زیرمحفظه» در زیر مراجعه کنید.
که در آن SEID شناسه زیرمحفظه‌ای است که نام مستعار جدید (SEN) روی آن اعمال خواهد شد. بنابراین SEID باید یک شناسه زیرمحفظه موجود باشد. مقدار پیش‌فرض 0 است که همان محفظه اصلی است.
dpageهای Element status، Array status (منسوخ)، Element Descriptor، Additional element status و Threshold In همگی برای رمزگشایی به dpage مربوط به Configuration وابسته هستند. برای مقاصد اشکال‌زدایی، هنگامی که مشکلی در ارتباط بین این dpageها وجود دارد، ممکن است بررسی آن صفحه‌ها بدون استفاده از dpage پیکربندی مفید باشد. این همان کاری است که این گزینه انجام می‌دهد. آن dpageها همچنان ساختاری دارند که می‌تواند بدون dpage مربوط به Configuration خروجی داده شود، اما بخش‌های درونی هنگامی که این گزینه داده می‌شود معمولاً در قالب هگز خروجی داده می‌شوند. این گزینه تا حدی مرتبط با گزینه --inner-hex است که آن نیز برای اشکال‌زدایی سودمند است.
این گزینه در dpageهایی که به dpage مربوط به Configuration وابستگی ندارند، از جمله خود dpage مربوط به Configuration، نادیده گرفته می‌شود.
این ابزار اکنون یک دستور SCSI REPORT TIMESTAMP را درست پس از یک دستور INQUIRY در ابتدای اجرای خود صادر می‌کند. این کار ابزار را قادر می‌سازد تا یک برچسب تاریخ-زمان یا مدت زمان فعال بودن سیستم (uptime) را خروجی دهد. مقدار زمان بازگردانده‌شده بر حسب میلی‌ثانیه از یک مبدأ زمانی (epoch) خاص است. اگر مقدار مربوط به دوره‌ای کمتر از ۳ سال باشد، به عنوان مدت زمان فعالیت در نظر گرفته می‌شود و بر حسب روز، ساعت، دقیقه، ثانیه و میلی‌ثانیه خروجی داده می‌شود. سیستم‌های یونیکس از جمله لینوکس، FreeBSD و سولاریس از ساعت 00:00 اول ژانویه 1970 UTC به عنوان مبدأ زمانی خود استفاده می‌کنند. برچسب تاریخ-زمان خروجی در قالب تاریخ RFC 2822 در دو سطر مجاور نمایش داده می‌شود، یکی در UTC و دیگری در زمان محلی.
اگر به دلایلی فراخوانی دستور REPORT TIMESTAMP مشکلی ایجاد کند، این گزینه این قابلیت را غیرفعال خواهد کرد.
توجه داشته باشید که زمان بازگردانده‌شده از سوی محفظه است، نه ماشینی که ابزار از آن اجرا می‌شود. این ابزار می‌تواند از دیسک‌های مدرن SCSI به عنوان DEVICE برای واکشی برچسب زمانی آن دیسک استفاده کند؛ سپس این ابزار متوجه می‌شود که DEVICE یک محفظه نیست و بدون ایجاد هیچ آسیبی خارج می‌شود.
که در آن PG اختصار یا کد (یک عدد) dpage است. اگر PG با یک رقم شروع شود، در مبنای ده فرض می‌شود مگر اینکه دارای پیشوند 0x برای هگز باشد. محدوده معتبر 0 تا 255 (0x0 تا 0xff) شامل هر دو است. مقدار پیش‌فرض dpage 'sdp' است که همان page_code 0 (یعنی "Supported Diagnostic Pages") می‌باشد، در صورتی که گزینه‌های دیگری داده نشود.
کد صفحه 0xff یا اختصار "all" یک dpage واقعی نیست (چرا که بالاترین dpage واقعی 0x3f است) بلکه در عوض باعث می‌شود تمام dpageهای SES که کد صفحه آن‌ها 0x2f یا کمتر است خروجی داده شوند. این می‌تواند با -HHHH یا -rr برای ارسال هگزادسیمال ASCII یا باینری به خروجی استاندارد (stdout) استفاده شود. اگر خطایی در حین واکشی یا رمزگشایی یک صفحه تشخیصی شناسایی شود، یادداشت می‌گردد، بقیه صفحه‌ها پردازش می‌شوند و سپس خطای به تعویق افتاده در وضعیت خروج گزارش می‌شود. اگر گزینه --warn نیز داده شده باشد، --page=all بلافاصله پس از تشخیص خطا خارج می‌شود.
برای فهرست کردن اختصارات dpageهای موجود، "xxx" را برای PG بدهید؛ همین اطلاعات را می‌توان با گزینه --enumerate نیز پیدا کرد.
تعداد هشدارها و پیام‌های خروجی را سرکوب می‌کند. وضعیت خروج ابزار تحت تأثیر این گزینه قرار نمی‌گیرد.
dpage وضعیت انتخاب‌شده را در قالب هگز ASCII با قالبی مناسب برای فراخوانی بعدی با استفاده از گزینه --data= خروجی می‌دهد. یک dpage بدون ۴ بایت نخست آن (کد صفحه و طول) خروجی داده می‌شود. در صورت استفاده دوبار (مثلاً -rr)، کل محتوای dpage به صورت باینری به stdout ارسال می‌شود.
توجه داشته باشید که استفاده از گزینه --raw تکی با اکثر ابزارهای دیگر در بسته sg3_utils متفاوت است.
هنگامی که -rr همراه با --data=-، --data=@FN یا --inhex=FN استفاده شود، ورودی استاندارد یا فایل FN به صورت یک جریان باینری رمزگشایی می‌شود که خواندن آن تا رسیدن به انتهای فایل (EOF) ادامه می‌یابد. پس از خواندن آن داده، گزینه داخلی raw روی 0 پاک می‌شود تا خروجی تحت تأثیر قرار نگیرد. بنابراین گزینه -rr یا نحوه برخورد با ورودی را تغییر می‌دهد یا نحوه برخورد با خروجی را، اما نه هر دو را در یک فراخوانی واحد.
DEVICE را فقط‌خواندنی باز می‌کند (مثلاً در یونیکس با پرچم O_RDONLY). رفتار پیش‌فرض این است که به صورت خواندنی-نوشتنی باز شود.
این یک روش شاخص‌گذاری برای دستگاه‌های پایانی SAS (مانند دیسک‌های SAS) است. این ابزار تلاش خواهد کرد عنصر یا اسلاتی را در dpage مربوط به Additional Element Status پیدا کند که آدرس SAS آن با SA مطابقت دارد. برای یک دیسک یا نوار SAS، آن آدرس SAS همان شناسه پورت هدف برای پورت متصل به آن عنصر یا اسلات است. بیشتر دیسک‌ها و نوارهای SAS دارای دو پورت هدف از این نوع هستند که معمولاً شماره‌گذاری متوالی دارند.
دستگاه‌های SATA در یک محفظه SAS معمولاً شناسه‌های پورت هدف ساختگی (manufactured) را از یک اکسپندر SAS دریافت می‌کنند؛ به طور معمول دارای یک آدرس SAS نزدیک به آدرس SAS خود اکسپندر، اما متفاوت از آن خواهند بود. توجه داشته باشید که این شناسه پورت هدف ساختگی با WWN یک دیسک SATA متفاوت است.
SA یک عدد هگز است که حداکثر ۸ رقم طول دارد. ممکن است دارای پیشوند '0x' یا '0X' یا پسوند 'h' یا 'H' باشد. این گزینه یک روش شاخص‌گذاری سطح متوسط در مقایسه با گزینه‌های سطح پایین --index= است. به بخش «نام توصیف‌گر، شماره اسلات دستگاه و آدرس ساس» در زیر مراجعه کنید.
برای تنظیم یک فیلد عنصر در dpage مربوط به Enclosure Control یا Threshold Out استفاده می‌شود. باید همراه با یک گزینه شاخص‌گذاری استفاده شود تا مشخص کند کدام عنصر باید تغییر یابد. اگر گزینه --page=PG داده نشود، dpage مربوط به Enclosure Control فرض می‌شود. به بخش‌های «قالب رشته» (STR FORMAT) و «پاک‌سازی، دریافت، تنظیم» (CLEAR, GET, SET) در زیر مراجعه کنید.
یک dpage را از طریق یک دستور SCSI RECEIVE DIAGNOSTIC RESULTS (یا از --data=@FN) از DEVICE واکشی می‌کند. در صورت عدم وجود گزینه‌های دیگری که حاکی از تغییر یک dpage باشند (مانند --control یا --set=STR)، گزینه --status فرض می‌شود، مگر زمانی که گزینه --data= داده شود. هنگامی که گزینه --data= داده می‌شود، هیچ اقدام پیش‌فرضی وجود ندارد: یا باید --control داده شود یا این گزینه، تا بین دو روش مختلف پردازش داده‌ها تمایز قائل شد.
سطح پرحرفی را افزایش می‌دهد. برای مثال، زمانی که این گزینه چهار بار داده شود (که در این حالت شکل کوتاه آن راحت‌تر است: '-vvvv')، اگر آرایه ادغام داخلی تولید شده باشد، در قالبی مناسب برای اشکال‌زدایی به stderr خروجی داده می‌شود.
رشته نسخه را چاپ کرده و سپس خارج می‌شود.
درباره برخی بی‌نظمی‌ها با هشدارهایی که به stderr ارسال می‌شوند، هشدار می‌دهد. ادغام (join) یک عملیات پیچیده است که مستلزم همگام‌سازی فیلدهای حاصل از چندین dpage است. کیفیت دستگاه‌های SES متفاوت است و برای رعایت انصاف، توضیحات ارائه‌شده در پیش‌نویس‌ها و استانداردهای T10 چندین بار دستکاری شده‌اند (به فیلد EIIOE نگاه کنید) تا ابهامات برطرف شوند.
این گزینه باعث می‌شود که واکشی تمام dpageها با گزینه --page=all بلافاصله پس از تشخیص خطا پایان یابد.

یک محفظه می‌تواند اطلاعات مربوط به درایوهای دیسک و نوار خود و همچنین سایر اجزای پشتیبان مانند منابع تغذیه را در چندین dpage پخش کرده باشد. نشانی‌دهی به یک عنصر خاص (کلی یا منفرد) در داخل یک dpage پیچیده است. این بخش شاخص‌گذاری سطح پایین را شرح می‌دهد (یعنی انتخاب یک عنصر منفرد (یا گروهی از عناصر مرتبط) از میان تعداد زیادی عنصر). در صورت در دسترس بودن، شاخص‌گذاری سطح متوسط شرح‌داده‌شده در بخش بعدی (نام توصیف‌گر، شماره اسلات دستگاه و آدرس ساس) ممکن است برای استفاده ساده‌تر باشد.

صفحه تشخیصی Configuration کلید شاخص‌گذاری سطح پایین است: این صفحه شامل فهرستی از «سرآیندهای نوع» (type headers) است که هر یک شامل یک نوع عنصر (مانند Array Device Slot)، یک شناسه زیرمحفظه (0 برای محفظه اصلی) و یک «تعداد عناصر ممکن» (Number of possible elements) می‌باشد. متناظر با هر سرآیند نوع، صفحه تشخیصی Enclosure Status دارای یک عنصر «کلی» (overall) به علاوه «تعداد عناصر ممکن» عنصر منفرد است که همگی دارای نوع عنصر داده‌شده هستند. برای برخی از انواع عنصر، «تعداد عناصر ممکن» برابر 0 خواهد بود، بنابراین صفحه تشخیصی Enclosure Status تنها دارای یک عنصر «کلی» متناظر با آن سرآیند نوع است. صفحه‌های تشخیصی Element Descriptor و Threshold (ورودی و خروجی) از الگویی مشابه صفحه تشخیصی Enclosure Status پیروی می‌کنند.

شاخص عددی متناظر با عنصر کلی "-1" است. اگر صفحه تشخیصی Configuration نشان دهد که یک نوع عنصر خاص دارای "n" عنصر است، شاخص‌های آن از -1 تا n-1 متغیر خواهند بود.

صفحه تشخیصی Additional Element Status کمی پیچیده‌تر است. این صفحه شامل مدخل‌هایی برای «تعداد عناصر ممکن» از انواع عنصر خاصی است. این صفحه مدخل‌های متناظر با عناصر «کلی» را ندارد. برای روشن‌تر شدن این تناظر، هر توصیف‌گر در این dpage به صورت اختیاری شامل یک نشانگر "Element Index Present" (EIP) است. اگر EIP تنظیم شده باشد، فیلد "Element Index" هر عنصر به موقعیت عنصر متناظر در صفحه تشخیصی Enclosure Status اشاره می‌کند.

نشانی‌دهی به یک عنصر کلی منفرد یا یک عنصر منفرد با دو شاخص انجام می‌شود: TI و II. مقدار TI=0 متناظر با اولین مدخل سرآیند نوع است که باید یک نوع عنصر Device Slot یا Array Device Slot باشد (طبق استاندارد SES-2). برای نشانی‌دهی به نمونه کلی متناظر، II برابر -1 قرار می‌گیرد، در غیر این صورت II می‌تواند روی شاخص نمونه منفرد تنظیم شود. به عنوان جایگزینی برای شاخص سرآیند نوع (TI)، می‌توان یک اختصار نوع عنصر (A) (مانند "ps" برای نوع عنصر منبع تغذیه) را ارائه داد که به صورت اختیاری عددی به دنبال آن می‌آید (مثلاً "ps" به اولین نوع عنصر منبع تغذیه اشاره دارد؛ "ps1" به دومی اشاره دارد).

می‌توان از یکی از دو حالت خط فرمان برای تعیین شاخص‌ها استفاده کرد: --index=TIA,II که در آن TIA یا یک شاخص سرآیند نوع (TI) یا یک اختصار نوع عنصر (A) است (مانند "ps" یا "ps1"). II یا یک شاخص منفرد است یا "-1" برای مشخص کردن عنصر کلی. حالت دوم --index=IIA است که در آن IIA یا یک شاخص منفرد (II) یا یک اختصار نوع عنصر (A) است. هنگامی که IIA یک شاخص منفرد باشد، این گزینه معادل با --index=0,II است. هنگامی که IIA یک اختصار نوع عنصر باشد، این گزینه معادل با --index=A,-1 خواهد بود.

در هر جایی که یک شاخص منفرد کاربرد داشته باشد، می‌توان آن را با یک محدوده شاخص منفرد جایگزین کرد. این محدوده به شکل <first_ii>:<last_ii> است. برای مثال: '3:5' شاخص‌های منفرد ۳، ۴ و ۵ را انتخاب خواهد کرد. توجه داشته باشید که محدوده -1:255 نشان‌دهنده تمام عناصر ممکن از یک نوع عنصر است و خطا نیست؛ تنها عناصری که وجود دارند انتخاب خواهند شد. پیش‌تر از '-' به عنوان جداکننده محدوده شاخص استفاده می‌شد، اما این امر منجر به نحوی نامأنوس مانند -1-1 برای شاخص‌های -1 (عنصر کلی)، 0 و 1 (عناصر منفرد) می‌شد.

برای هماهنگی با انواع عنصر اختصاصی سازندگان (که کدهای نوع آن‌ها باید در محدوده 128 تا 255 باشد)، کد نوع عنصر می‌تواند به عنوان یک عدد با یک خط زیر (underscore) در ابتدا ارائه شود. برای مثال، این دو معادل هستند: --index=arr و --index=_23 زیرا کد نوع عنصر Array Device Slot برابر 23 است. همچنین --index=ps1 و --index=_2_1 معادل هستند.

مثالی دیگر: اگر اولین سرآیند نوع در صفحه تشخیصی Configuration دارای نوع عنصر Array Device Slot باشد، در این صورت --index=0,-1 معادل با --index=arr است. همچنین --index=arr,3 معادل با --index=3 خواهد بود.

گزینه --index= برای کاهش میزان خروجی استفاده می‌شود (مثلاً فقط نمایش عنصر مرتبط با دومین منبع تغذیه ۱۲ ولت). این گزینه همچنین می‌تواند همراه با گزینه‌های --clear=STR، --get=STR و --set=STR که در بخش STR در زیر شرح داده شده‌اند استفاده شود.

سه گزینه: --descriptor=DES، --dev-slot-num=SN و --sas-addr=SA امکان شاخص‌گذاری سطح متوسط را به عنوان جایگزینی برای گزینه سطح پایین --index= فراهم می‌کنند. تنها یکی از این سه گزینه می‌تواند در یک فراخوانی استفاده شود. هنگامی که هر یک از این سه گزینه استفاده شود، پیش از انجام انتخاب عنصر، یک عملیات ادغام (join) انجام می‌شود (اما نمایش داده نمی‌شود).

این گزینه‌های شاخص‌گذاری سطح متوسط نیازمند پشتیبانی از سوی دستگاه SES هستند و این پشتیبانی اختیاری است. برای مثال، --descriptor=DES نیازمند dpage مربوط به Element Descriptor است که توسط دستگاه SES ارائه می‌شود، با این حال ارائه آن اختیاری است. همچنین نام‌های توصیف‌گر ارائه‌شده باید کاربردی باشند، و داشتن نام‌های توصیف‌گری که همگی "0" هستند چندان سودمند نیست. همچنین برخی عناصر (مانند عناصر کلی) ممکن است نام توصیف‌گر نداشته باشند.

این گزینه‌های شاخص‌گذاری سطح متوسط می‌توانند برای کاهش حجم خروجی استفاده شوند (مثلاً فقط نمایش عناصر مربوط به شماره اسلات دستگاه 3). آن‌ها همچنین می‌توانند به همراه گزینه‌های --clear=STR، --get=STR و --set=STR که در بخش بعدی شرح داده شده‌اند به کار روند. توجه داشته باشید که حتی اگر یک فیلد قابل تنظیم باشد (مانند "do not remove" (dnr)) و آن فیلد را بتوان با --get=STR بازخوانی کرد تا تغییر تأیید شود، آرایه دیسک ممکن است همچنان آن را نادیده بگیرد (مثلاً به این دلیل که سازوکاری برای قفل کردن کشوی دیسک ندارد).

عملوندهای STR در گزینه‌های --clear=STR، --get=STR و --set=STR همگی ساختار یکسانی دارند. دو شکل وجود دارد:


<acronym>[=<value>]
<start_byte>:<start_bit>[:<num_bits>][=<value>]

مورد <acronym> یکی از فیلدهای رایج است (مانند "ident" و "fault") که این ابزار به صورت داخلی آن را به شکل دوم تبدیل می‌کند. مقدار <start_byte> معمولاً در محدوده 0 تا 3 است، <start_bit> باید در محدوده 0 تا 7 باشد و <num_bits> باید در محدوده 1 تا 64 باشد (پیش‌فرض 1 است). تعداد بیت‌ها از چپ به راست در جدول‌های عناصر که در اسناد مختلف پیش‌نویس SES نشان داده شده‌اند، خوانده می‌شوند. برای مثال، ۸ بیت بایت ۲ به صورت 2:7:8 نمایش داده می‌شود که پرارزش‌ترین بیت آن 2:7 و کم‌ارزش‌ترین بیت آن 2:0 خواهد بود.

مقدار <value> اختیاری است، اما اگر به --get=STR داده شود نادیده گرفته خواهد شد. برای --set=STR مقدار پیش‌فرض <value> برابر 1 است، در حالی که برای --clear=STR مقدار پیش‌فرض 0 است. مقدار <value> در مبنای ده فرض می‌شود؛ مقادیر هگزادسیمال را می‌توان به شیوه معمول ارائه داد.

فهرست پشتیبانی‌شده از <acronym>ها را می‌توان با استفاده دو بار از گزینه --enumerate (یا "-ee") مشاهده کرد.

گزینه‌های --clear=STR، --get=STR و --set=STR می‌توانند حداکثر ۸ بار در یک فراخوانی مشابه استفاده شوند. هر <acronym> استفاده‌شده در عملوندهای STR باید به همان dpage یکسان ارجاع دهد.

هنگامی که چند مورد از این گزینه‌ها استفاده شوند (حداکثر: ۸ مورد)، آن‌ها به ترتیبی که در خط فرمان ظاهر می‌شوند اعمال می‌گردند. بنابراین اگر گزینه‌ها با یکدیگر تناقض داشته باشند، آخرین گزینه‌ای که در خط فرمان ظاهر شده است اعمال خواهد شد. هنگامی که چند گزینه --clear=STR و --set=STR وجود داشته باشد، dpage مربوطه تنها پس از آخرین مورد نوشته می‌شود.

این بخش دو سناریویی را که هنگام استفاده از گزینه --data= ممکن است رخ دهند، شرح می‌دهد. این سناریوها صرف‌نظر از اینکه آرگومان گزینه --data= رشته‌ای از بایت‌های هگز در خط فرمان باشد، از ورودی استاندارد باشد (که با --data=- مشخص می‌شود) یا نام یک فایل باشد (مانند --data=@thresh_in_dpage.hex)، یکسان هستند.

سناریوی اول با گزینه --control مشخص می‌شود. این سناریو از داده‌های ارائه‌شده برای ساخت یک dpage «کنترلی» استفاده می‌کند که با استفاده از دستور SCSI SEND DIAGNOSTIC به DEVICE ارسال خواهد شد. داده‌های dpage ارائه‌شده نباید شامل ۴ بایت نخست آن باشد. آن ۴ بایت توسط این ابزار با استفاده از گزینه --page=PG اضافه می‌شوند و PG در آفست بایت 0 قرار می‌گیرد. در صورت نیاز، گزینه --byte1=B1 آفست بایت 1 را تنظیم می‌کند، در غیر این صورت 0 در آن موقعیت قرار می‌گیرد. تعداد بایت‌های رمزگشایی‌شده از داده‌های ارائه‌شده (یعنی طول آن) در آفست‌های بایت 2 و 3 قرار می‌گیرد.

سناریوی دوم با گزینه --status (یا عدم وجود گزینه --control) مشخص می‌شود. این سناریو داده‌های ارائه‌شده را با این فرض رمزگشایی می‌کند که پاسخ یک یا چند دستور SCSI RECEIVE DIAGNOSTIC RESULTS را نشان می‌دهند. آن پاسخ‌ها معمولاً از فراخوانی(های) قبلی این ابزار ضبط شده‌اند. آن فراخوانی‌های قبلی می‌توانستند از گزینه '-HHH' یا '-HHHH' و هدایت مجدد فایل برای ضبط آن پاسخ (یا پاسخ‌ها) در قالب هگزادسیمال استفاده کنند. داده‌های پاسخ dpage ارائه‌شده بر اساس سایر گزینه‌های خط فرمان رمزگشایی می‌شوند. برای مثال، گزینه --join می‌تواند داده شود و این کار نیازمند داده‌های حاصل از چندین dpage به طور معمول است: dpageهای Configuration، Enclosure status، Element descriptor و Additional element status. اگر شک دارید، در مرحله ضبط از --page=all استفاده کنید؛ داشتن dpageهایی بیشتر از حد نیاز مشکلی ایجاد نمی‌کند.

به طور پیش‌فرض فرض می‌شود که داده‌های ارائه‌شده توسط کاربر به صورت هگزادسیمال ASCII در سطرهایی است که از ۵۱۲ نویسه تجاوز نمی‌کنند. هر چیزی در یک سطر از علامت هش ('#') به بعد تا انتهای سطر نادیده گرفته می‌شود. انتهای سطر می‌تواند LF یا CR,LF باشد و سطرهای خالی نادیده گرفته می‌شوند. هر جفت (یا رقم تکی) هگزادسیمال جداشده نشان‌دهنده یک بایت است (و نه پیشوند '0x' و نه پسوند 'h' نباید داده شود). جداکننده‌ها عبارتند از فاصله، تب، کاما یا انتهای سطر.

از طرف دیگر، می‌توان از حالت باینری استفاده کرد که با گزینه '-rr' مشخص می‌شود. شکل --data=H,H... نمی‌تواند از مقادیر باینری برای 'H'ها استفاده کند و فقط هگزادسیمال ASCII را می‌پذیرد. دو شکل دیگر (--data=- و --data=@FN) ممکن است حاوی داده‌های باینری باشند. توجه داشته باشید که وقتی گزینه '-rr' همراه با --data=@FN استفاده می‌شود، تنها تفسیر داده‌های ورودی را تغییر می‌دهد و نمایش رمزگشایی و خروجی را تغییر نمی‌دهد.

این ابزار تکنیک‌های مختلفی برای تغییر وضعیت یک دستگاه SES دارد. همان‌طور که در بالا اشاره شد، این معمولاً یک عملیات از نوع خواندن-اصلاح-نوشتن است. اکثر dpageهای قابل‌تغییر دارای یک صفحه "status" (یا "in") هستند که می‌توان آن را خواند، و یک dpage متناظر "control" (یا "out") دارند که می‌توان آن را برای تغییر وضعیت محفظه مجدداً بازنویسی کرد.

تکنیک سطح پایین‌تر ارائه‌شده توسط این ابزار شامل خروجی دادن یک dpage «وضعیت» در قالب هگز با --raw است. سپس می‌توان از یک ویرایشگر متن برای ویرایش هگز استفاده کرد (توجه: برای تغییر یک توصیف‌گر Enclosure Control، بیت SELECT باید تنظیم شود). سپس داده‌های dpage کنترلی را می‌توان با گزینه --data=H,H... همراه با گزینه --control بازخورد داد؛ ممکن است لازم باشد گزینه --byte1=B1 نیز ارائه شود.

تغییرات در dpage مربوط به Enclosure Control (و dpage مربوط به Threshold Out) می‌تواند در سطح بالاتری انجام شود. این کار شامل انتخاب یک dpage است (پیش‌فرض در این حالت dpage مربوط به Enclosure Control است). سپس یک شاخص عنصر منفرد یا کلی را انتخاب کنید (یا آن را با رشته Element Descriptor مربوطه نام‌گذاری کنید). سپس نام عنصر (مثلاً "ident" برای RQST IDENT) یا موقعیت آن را در داخل آن عنصر مشخص کنید (مثلاً در یک عنصر Array Device Slot Control، مقدار RQST IDENT در بایت ۲، بیت ۱ و به طول ۱ بیت است ("2:1:1")). در نهایت می‌توان یک مقدار تعیین کرد؛ در غیر این صورت، مقدار برای --set=STR به طور پیش‌فرض 1 و برای --clear=STR به طور پیش‌فرض 0 خواهد بود.

قالب dpage کنترلی Subenclosure Nickname با dpage وضعیت متناظر آن متفاوت است. صفحه تشخیصی وضعیت تمام نام‌های مستعار زیرمحفظه را گزارش می‌کند (و شناسه زیرمحفظه 0 همان محفظه اصلی است) در حالی که dpage کنترلی تنها اجازه تغییر یکی از آن‌ها را می‌دهد. بنابراین استفاده از روش گزینه --data برای تغییر نام مستعار زیرمحفظه دشوار است (اما همچنان امکان‌پذیر است).

برای ساده‌سازی تغییر نام مستعار زیرمحفظه، گزینه‌های --nickname=SEN و --nickid=SEID اضافه شده‌اند. اگر رشته SEN شامل فاصله یا سایر علائم نگارشی باشد، باید درون علامت نقل‌قول قرار گیرد: محصور در گیومه تکی یا دوتایی (یا نویسه‌های ناسازگار گریز داده شوند). اگر --nickid=SEID داده نشود، شناسه زیرمحفظه 0 فرض می‌شود. به عنوان یک محافظ، گزینه --control نیز باید داده شود. اگر گزینه --page=PG داده نشود، --page=snic فرض می‌شود.

هنگامی که --nickname=SEN داده شود، dpage مربوط به Subenclosure Nickname Status خوانده می‌شود تا فیلد Generation Code به دست آید. آن Generation Code به همراه حداکثر ۳۲ بایت از نام مستعار (SEN) و شناسه زیرمحفظه (SEID) در dpage مربوط به Subenclosure Nickname Control نوشته می‌شوند.

نمونه‌ای از تغییر یک نام مستعار در بخش «مثال‌ها» در زیر آمده است.

پشتیبانی از محفظه‌های NVMe (همچنین موسوم به NVM Express) به sg_ses (در واقع، کتابخانه زیربنایی آن) اضافه شده است. این قابلیت را می‌توان در نسخه 1.43 بسته sg3_utils و نسخه 2.34 از sg_ses آزمایشی در نظر گرفت.

این پشتیبانی بر اساس تصمیمی از سوی توسعه‌دهندگان NVME-MI (رابط مدیریت) برای پشتیبانی از استاندارد SES-3 اتخاذ شده است. این امر با افزودن دستورات NVME-MI SES Send و SES Receive که محتوای dpage را همان‌طور که توسط SES استفاده می‌شود تونل می‌کنند، تسهیل شد.

رویکرد اتخاذشده در مورد خروجی JSON (یعنی زمانی که گزینه --json[=JO] داده شده است) این است که اطلاعات صفحه تشخیصی خروجی داده شود مگر اینکه گزینه --join داده شده باشد. مشکلی که مختص SES است این است که بسیاری از صفحه‌های تشخیصی به سایر صفحه‌های تشخیصی وابسته هستند (مثلاً رمزگشایی dpageهای Enclosure Status و Element Descriptor هر دو به dpage مربوط به Configuration وابسته هستند).

هنگامی که گزینه‌های --json[=JO] و --page=PG در یک فراخوانی مشابه استفاده شوند، در صورتی که PG هرگونه وابستگی به سایر صفحه‌های تشخیصی داشته باشد، آن صفحه‌های دیگر واکشی می‌شوند. برای مثال، dpage مربوط به Element Descriptor به dpage مربوط به Configuration وابسته است. در برخی موارد (مانند dpageهایی که به درستی پیکربندی نشده‌اند یا در فرآیند تغییر هستند)، ممکن است رمزگشایی هر آنچه ممکن است بدون واکشی سایر dpageها مفید باشد. گزینه --inner-hex ممکن است برای این منظور استفاده شود. برخی از dpageها (مانند dpage مربوط به Enclosure Status) به هیچ وجه بدون واکشی dpage مربوط به Configuration قابل رمزگشایی نیستند، بنابراین هر عنصر ۴ بایتی در قالب هگز خروجی داده می‌شود. در مورد dpage مربوط به Element Descriptor، توصیف‌گرها ممکن است به صورت ASCII خروجی داده شوند و زمانی که گزینه --inner-hex یک بار داده شود به همین صورت خواهند بود. اگر گزینه --inner-hex دو بار داده شود، هر توصیف‌گر در قالب هگز خروجی داده خواهد شد.

هنگامی که گزینه‌های --json[=JO] و --page=PG در یک فراخوانی مشابه استفاده شوند، نام شیء سطح بالا همان نام PG در نمادگذاری ماری (snake_case) است. این شامل پسوند "_diagnostic_page" نیز می‌شود.

هنگامی که گزینه‌های --json[=JO] و --join در یک فراخوانی مشابه استفاده شوند (و گزینه --page=PG داده _نشده_ باشد)، نام شیء سطح بالا "join_of_diagnostic_pages" است که شامل یک آرایه (JSON) به نام "element_list" می‌باشد. هر عنصر در آن آرایه با یک فیلد "element_type" شروع می‌شود و به دنبال آن فیلدهای "descriptor" و "element_number" می‌آیند. مقدار فیلد "descriptor" یک رشته است. تمام عناصر با "element_type" یکسان با هم گروه‌بندی می‌شوند و با "overall_element" در ابتدا شروع می‌شوند. مقدار "element_number" برای "overall_element" برابر -1 است. عناصر منفرد با همان "element_type" در عناصر بعدی آرایه "element_list" با مقدار "element_number" برابر 0 شروع می‌شوند. پس از فیلد "element_number"، یک فیلد "overall" با مقدار صحیح 0 (برای عنصر "individual") یا مقدار 1 (برای عنصر "overall") وجود دارد. برای تأکید بر این نکته، یک فیلد "individual" با مقدار بولی true (برای عنصر "individual") یا false وجود دارد. سپس شیئی به نام "status_descriptor" قرار دارد که شامل عنصر وضعیت محفظه از dpage متناظر "Enclosure Status" است. بر حسب نیاز، توصیف‌گرهای وضعیت متناظر Additional element status، Element descriptor by type element و Threshold status نیز ممکن است ظاهر شوند.

خروجی متن ساده (که به طور پیش‌فرض تولید می‌شود) زمانی که یک سطر از مقادیر عناصر همگی 0 باشند، تمایل دارد خروجی را کوتاه کند. از سوی دیگر، هنگامی که خروجی JSON انتخاب می‌شود، تمام فیلدهایی که الزامات گزینه‌های خط فرمان را برآورده می‌کنند خروجی داده می‌شوند.

این ابزار می‌تواند برای واکشی dpageهای دلخواه (یعنی غیر SES) (با استفاده از دستور SCSI READ DIAGNOSTIC) استفاده شود. برای این منظور، گزینه‌های --page=PG و --hex مناسب خواهند بود. dpageهای غیر SES را می‌توان با استفاده از ابزار sg_senddiag به یک دستگاه ارسال کرد.

دردسرسازترین بخش عملیات ادغام (join)، مرتبط ساختن صحیح توصیف‌گرهای Additional Element Status است. دست‌کم یک سازنده دستگاه SES استاندارد SES-2 را به ویژه در تفسیر فیلد "element index" آن نادرست تفسیر کرده است. کد موجود در این ابزار فیلد "element index" را طبق استاندارد SES-2 تفسیر می‌کند و اگر این کار منجر به یک نوع عنصر نامناسب شود، شاخص‌گذاری خود را طوری تنظیم می‌کند که از تفسیر نادرست آن سازنده پیروی کند. پیش‌نویس‌های SES-3 بیت EIIOE (Element Index Includes Overall Elements) را معرفی کردند که بعدها به یک فیلد ۲ بیتی برای رفع این ابهام تبدیل شد. به گزینه --eiioe=A_F مراجعه کنید.

در پیش‌نویس SES-3 بازنگری 5، نام عنصر "Door Lock" به "Door" تغییر یافت (و فیلد OPEN به عنصر وضعیت اضافه شد). در نتیجه، اختصار پیشین نوع عنصر 'dl' به 'do' تغییر یافته است.

برخی از کنترل‌کننده‌های RAID گره‌های دستگاه SES را از سیستم‌عامل میزبان پنهان می‌کنند. گزارش شده است که برخی از کنترل‌کننده‌های MegaRAID این کار را انجام می‌دهند و دستور زیر برای آشکار کردن آن‌ها مورد نیاز است:


perccli /cx set backplane expose=<on/off>

که در آن perccli نسخه شرکت Dell از ابزار storcli متعلق به BroadCom (LSI) است.

مجموعه دستورات مرتبطی به نام SAF-TE (محفظه خطاپذیر متصل به SCSI) برای وضعیت و کنترل محفظه (شامل RAID) وجود دارد. دستگاه‌های SCSI که از SAF-TE پشتیبانی می‌کنند، نوع دستگاه جانبی "Processor" (0x3) را در پاسخ INQUIRY خود گزارش می‌دهند. به ابزار sg_safte در این بسته یا ابزار safte-monitor در اینترنت مراجعه کنید.

آرایه ادغام داخلی به صورت ایستا تخصیص یافته و اندازه آن توسط تعریف MX_JOIN_ROWS کنترل می‌شود. مقدار فعلی آن 520 است.

مثال‌ها را همچنین می‌توان در https://sg.danny.cz/sg/sg_ses.html یافت.

مثال‌های زیر از نام‌های دستگاه لینوکس استفاده می‌کنند. برای نام‌های دستگاه مناسب در سایر سیستم‌عامل‌های پشتیبانی‌شده به صفحه راهنمای sg3_utils(8) مراجعه کنید.

برای مشاهده dpageهای پشتیبانی‌شده:


sg_ses /dev/bsg/6:0:2:0

برای مشاهده dpage تشخیصی Configuration:


sg_ses --page=cf /dev/bsg/6:0:2:0

برای مشاهده dpage مربوط به Enclosure Status:


sg_ses --page=es /dev/bsg/6:0:2:0

برای دریافت آدرس SAS (متصل) آن دستگاه (که در dpage مربوط به Additional Element Sense (dpage 10) نگه‌داری می‌شود) چاپ‌شده در قالب هگز:


sg_ses -p aes -D ArrayDevice07 -G at_sas_addr -H /dev/sg3

برای تطبیق و یکپارچه‌سازی اطلاعات موجود در dpageهای Enclosure Status، Element Descriptor و Additional Element Status، می‌توان از گزینه --join استفاده کرد:


sg_ses --join /dev/sg3

این کار خروجی زیادی تولید می‌کند. برای فیلتر کردن سطرهایی که اطلاعات زیادی ندارند، گزینه --filter را اضافه کنید:


sg_ses --join --filter /dev/sg3

فیلدها در عناصر مختلف dpageهای Enclosure Control و Threshold را می‌توان با گزینه‌های --clear=STR و --set=STR تغییر داد. [تمام dpageهای قابل‌تغییر را می‌توان با گزینه‌های --raw و --data=H,H... تغییر داد.] مثال زیر به چشمک زدن LED نشانگر "ident" (همچنین موسوم به "locate") روی "ArrayDevice07" که یک دیسک است (یا دقیق‌تر بگوییم، کشوی نگهدارنده‌ای که دیسک در آن قرار دارد) می‌پردازد:


sg_ses --index=7 --set=2:1:1 /dev/sg3

در فراخوانی بالا، گزینه --set= به طور ضمنی بیانگر --control است، بنابراین نیازی به دادن گزینه دوم نیست. همین امر در مورد --clear= نیز صدق می‌کند. از سوی دیگر، گزینه --get= به طور ضمنی بیانگر --status است.
اگر dpage تشخیصی Element Descriptor نشان دهد که "ArrayDevice07" نام توصیف‌گر مرتبط با شاخص عنصر 7 است، در این صورت این فراخوانی معادل مورد قبلی است:


sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3

علاوه بر این، فیلد بایت ۲، بیت ۱ (به طول ۱ بیت) در عنصر Array Device Slot Control برابر با RQST IDENT است تا از نگهدارنده دیسک بخواهد یک LED را چشمک‌زن کند تا بتوان آن را پیدا کرد. در این حالت "ident" (یا "locate") به عنوان یک سرنام برای آن فیلد پذیرفته می‌شود:


sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3

برای متوقف کردن چشمک زدن آن LED:


sg_ses --dev-slot-num=7 --clear=ident /dev/sg3

موارد فوق فرض می‌کنند که نام توصیف‌گر 'ArrayDevice07' متناظر با شماره اسلات دستگاه 7 است.

حال مثالی از یک تکنیک عمومی‌تر اما سطح پایین‌تر برای تغییر یک dpage تشخیصی قابل‌تغییر ارائه می‌شود. dpage تشخیصی String (ورودی و خروجی) نسبتاً ساده است (در مقایسه با dpage مربوط به Enclosure Status/Control). با این حال، استفاده از این تکنیک سطح پایین‌تر دشوارتر است و شامل سه مرحله می‌شود: خواندن، اصلاح و سپس نوشتن. ابتدا محتوای فعلی dpage مربوط به String (In) را بررسی کنید:


sg_ses --page=str /dev/bsg/6:0:2:0

اکنون مرحله «خواندن». دستور زیر محتوای dpage مربوط به String را (از بایت ۴ به بعد) به خروجی استاندارد ارسال می‌کند. خروجی در قالب هگزادسیمال ASCII با جفت‌ارقام هگز نشان‌دهنده یک بایت خواهد بود، ۱۶ جفت در هر سطر که با فاصله از هم جدا شده‌اند. تغییر مسیر، stdout را در فایلی به نام "t" قرار می‌دهد:


sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t

سپس به کمک سند SES-3 (در بازنگری 3: بخش 6.1.6) از ویرایشگر مورد علاقه خود برای تغییر t استفاده کنید. تغییرات را می‌توان با دستور زیر به دستگاه ارسال کرد:


sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t

اگر موارد بالا موفقیت‌آمیز باشد، dpage مربوط به String باید تغییر یافته باشد. برای بررسی امتحان کنید:


sg_ses --page=str /dev/bsg/6:0:2:0

برای تغییر نام مستعار در محفظه اصلی:


sg_ses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0

برای ضبط وضعیت کل یک محفظه (از دیدگاه SES) برای تحلیل‌های بعدی، می‌توان این کار را انجام داد:


sg_ses --page=all -HHHH /dev/sg5 > enc_sg5_all.hex

توجه داشته باشید که اگر خطا یا هشداری وجود داشته باشد، به stderr ارسال خواهد شد بنابراین در خط فرمان ظاهر می‌شوند (زیرا فقط stdout هدایت مجدد شده است). می‌توان از یک ویرایشگر متنی برای بررسی enc_sg5_all.hex استفاده کرد. اگر بعداً همه‌چیز مرتب به نظر برسد، احتمالاً در ماشینی دیگر که enc_sg5_all.hex در آن کپی شده است، می‌توان یک "join" انجام داد. توجه داشته باشید که join وضعیت محفظه را در زمان انجام ضبط منعکس می‌کند.


sg_ses --data=@enc_sg5_all.hex --status --join

فراخوانی فوق را می‌توان به این صورت نیز بیان کرد:
sg_ses --inhex=enc_sg5_all.hex --join

گزینه --join به طور ضمنی بیانگر --status است.

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

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

گزارش باگ‌ها را به <dgilbert at interlog dot com> بفرستید.

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

sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils); safte-monitor (Internet)

ژوئن ۲۰۲۳ sg3_utils-1.48