| HWLOC-ANNOTATE(1) | hwloc | HWLOC-ANNOTATE(1) |
نام (NAME)
hwloc-annotate - ویرایش ویژگی‌ها در یک توپولوژی XML
خلاصه دستور (SYNOPSIS)
hwloc-annotate [options] <input.xml> <output.xml> -- <location1> <location2> ... -- <mode> <annotation>
hwloc-annotate [options] <input.xml> <output.xml> <location> <mode> <annotation>
توجه داشته باشید که hwloc(7) توضیح مفصلی درباره سامانه hwloc و قالب‌های معتبر <location> ارائه می‌دهد؛ این بخش باید پیش از خواندن این صفحه راهنما مطالعه شود.
گزینه‌ها (OPTIONS)
- --ri
- حذف تمام ویژگی‌های اطلاعاتی (info) موجود با نام یکسان پیش از افزودن مورد جدید. این گزینه فقط در حالت «info» پذیرفته می‌شود. اگر مقدار info حذف شود، مقادیر info موجود با هیچ جایگزین می‌شوند.
- --ci
- پاک کردن ویژگی‌های اطلاعاتی موجود در اشیاء هدف پیش از نشانه‌گذاری. اگر پس از پاک‌سازی نیازی به افزودن نشانه‌گذاری جدیدی نیست، mode باید روی none تنظیم شود.
- --cu
- پاک کردن داده‌های کاربری (userdata) موجود از اشیاء هدف. اگر پس از پاک‌سازی کار دیگری نباید انجام شود، mode باید روی none تنظیم شود.
- --cd
- پاک کردن فاصله‌های (distances) موجود از توپولوژی. اگر پس از پاک‌سازی کار دیگری نباید انجام شود، mode باید روی none تنظیم شود.
- --version
- گزارش نسخه و خروج.
- -h --help
- نمایش پیام راهنما و خروج.
توضیحات (DESCRIPTION)
دستور hwloc-annotate یک توپولوژی را از یک فایل XML بارگیری می‌کند، برخی نشانه‌گذاری‌ها را می‌افزاید، و توپولوژی حاصل را به یک فایل XML دیگر صادر می‌کند. فایل‌های ورودی و خروجی ممکن است یکسان باشند.
نشانه‌گذاری‌ها ممکن است ویژگی‌های اطلاعاتی رشته‌ای باشند. این مورد با mode مشخص می‌شود:
- info <name> <value>
- یک ویژگی اطلاعاتی رشته‌ای جدید را مشخص می‌کند که نام آن name و مقدار آن value است.
- subtype <subtype>
- مشخص می‌کند که ویژگی زیرنوع (subtype) شیء اکنون باید subtype باشد. اگر یک رشته خالی داده شود، زیرنوع حذف می‌شود.
- size <size>
- اندازه یک حافظه موقت (cache) یا گره NUMA را مشخص می‌کند. این مقدار می‌تواند پسوندهایی مانند kB، KiB، MB، MiB، GB، GiB و غیره داشته باشد.
- misc <name>
- نام یک شیء Misc جدید را مشخص می‌کند.
- memattr <name> <flags>
- یک ویژگی
حافظه جدید
را ثبت
می‌کند که
نام آن name و
پرچم‌های
آن flags است. در
این حالت location
نادیده
گرفته
می‌شود.
پرچم‌ها ممکن است به صورت مقادیر عددی یا فهرستی جداشده با کاما از نام‌های پرچم که به hwloc_memattr_register() ارسال می‌شوند، داده شوند. این نام‌ها تا زمانی که فقط با یک پرچم تطابق داشته باشند، می‌توانند زیررشته‌هایی از نام‌های واقعی پرچم باشند. برای نمونه، مقدار 1 (یا higher) به این معنی است که بالاترین مقادیر برای این ویژگی به عنوان بهترین در نظر گرفته می‌شوند.
- memattr <name> <initiator> <value>
- ویژگی
حافظه (با
نام name) را از
آغازگر initiator
(شیء یا CPU-set)
برای گره NUMA
هدف location روی
مقدار value
تنظیم
می‌کند.
اگر این ویژگی به آغازگرهای خاصی نیاز نداشته باشد، initiator نادیده گرفته می‌شود.
نام‌های استاندارد ویژگی‌ها عبارت‌اند از: Capacity، Locality، Bandwidth و Latency. تمام ویژگی‌های موجود در توپولوژی ورودی را می‌توان با دستور زیر فهرست کرد:
$ lstopo --memattrs -i input.xml - cpukind <cpuset> <efficiency> <flags> [<infoname> <infovalue>]
- نوع
پردازنده
را برای
PUهای
فهرست‌شده
در cpuset
داده‌شده
مشخص
می‌کند. در
این حالت location
نادیده
گرفته
می‌شود.
مقدار efficiency یک مقدار کارایی انتزاعی است که رتبه‌بندی انواع را اعمال خواهد کرد. در صورت نامشخص بودن باید -1 باشد.
مقدار flags در حال حاضر باید 0 باشد.
اگر infoname و infovalue داده شده و غیرخالی باشند، به عنوان ویژگی‌های اطلاعاتی به این نوع پردازنده افزوده می‌شوند.
برای جزئیات به تابع hwloc_cpukinds_register() مراجعه کنید.
- distances <filename> [<flags>]
- فاصله‌های
جدیدی را
مشخص
می‌کند که
با استفاده
از مشخصات
موجود در
<filename> به
توپولوژی
اضافه شوند.
پرچم
اختیاری flags (0
مگر اینکه
مشخص شود)
با
پرچم‌های
داده‌شده
به تابع
hwloc_distances_set()
مطابقت
دارد. در
این حالت location
نادیده
گرفته
می‌شود.
نخستین خط واقعی فایل ارجاع‌شده باید یک عدد صحیح نشان‌دهنده نوع فاصله (kind) باشد، همان‌طور که در hwloc/distances.h تعریف شده است. خط دوم تعداد اشیاء درگیر در فاصله‌ها است. خطوط بعدی هر کدام شامل یک شیء هستند. خطوط بعدی هر کدام شامل یک مقدار فاصله هستند، یا ممکن است یک خط منفرد با ترکیب عددی در قالب x*y یا x*y*z داده شود. یک خط اختیاری پیش از تمام خطوط می‌تواند با name= آغاز شود تا نام ساختار فاصله‌ها را در صورت وجود مشخص کند.
- distances-transform <name> links
- یک ساختار فاصله‌های پهنای باند با نام <name> را به پیوندها (links) تبدیل می‌کند. برای جزئیات، مستندات HWLOC_DISTANCES_TRANSFORM_LINKS را در hwloc/distances.h ببینید.
- distances-transform <name> merge-switch-ports
- هنگامی که سوئیچ‌ها در ماتریس به صورت درگاه‌های متفاوتی ظاهر می‌شوند، برای شفافیت بیشتر همه آنها را در یک درگاه واحد ادغام می‌کند. این مورد در حال حاضر فقط برای ماتریس NVLinkBandwidth بین پردازنده‌های گرافیکی NVIDIA اعمال می‌شود. برای جزئیات، مستندات HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS را در hwloc/distances.h ببینید.
- distances-transform <name> transitive-closure
- اگر اشیاء از طریق یک سوئیچ به هم متصل باشند، یک بستار متعدی (transitive-closure) اعمال می‌کند تا پهنای باند از طریق آن سوئیچ گزارش شود. این مورد در حال حاضر فقط برای ماتریس NVLinkBandwidth بین پردازنده‌های گرافیکی NVIDIA اعمال می‌شود. پهنای باند بین تمام جفت‌های GPU ارائه خواهد شد، نه پهنای باند بین تک‌تک GPUها و درگاه‌های تکی NVSwitch. برای جزئیات، مستندات HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE را در hwloc/distances.h ببینید.
- distances-transform <name> remove-obj <obj>
- شیء مشخص‌شده را از ساختار فاصله‌ها با نام <name> حذف می‌کند.
- distances-transform <name> replace-objs <oldtype> <newtype>
- اشیاء از
نوع <oldtype> را در
ساختار
فاصله‌ها
با نام <name> با
اشیاء از
نوع <newtype> با
همان
محلی‌بودن
(locality) جایگزین
می‌کند. اگر
<oldtype> یا <newtype> از
نوع شیء
نباشند،
فرض می‌شود
که
زیرنوع‌های
دستگاه‌های
سیستم‌عامل
هستند،
مانند "NVML" یا
"OpenCL". برای
جزئیات،
مستندات
hwloc_get_obj_with_same_locality() را در
hwloc/helper.h ببینید.
اگر <newtype> برابر با "NULL" باشد، اشیاء از ساختار فاصله‌ها حذف می‌شوند..TP none هیچ یادداشت جدیدی افزوده نمی‌شود. این حالت هنگام پاک‌کردن مشخصه‌های موجود کاربرد دارد.
یادداشت‌ها ممکن است به یک شیء خاص در مکان‌نگاری (topology)، همهٔ آنها یا همهٔ اشیاء از یک نوع مشخص اضافه شوند. این مورد توسط location مشخص می‌شود (بخش «مثال‌ها» در زیر را نیز ببینید). اگر مکان‌ها میان -- مشخص شوند، چندین مکان ممکن است تحت تأثیر قرار گیرند. همان‌طور که در hwloc(7) توضیح داده شده است، اشیاء را می‌توان به صورت چندتایی‌های مکان (location tuples) مشخص کرد. با این حال، ماسک‌های بیتی هگزادسیمال پذیرفته نمی‌شوند، زیرا ممکن است با چندین شیء مطابقت داشته باشند.
نکته: یادداشت‌های موجود را می‌توان با hwloc-info فهرست کرد.
نکته: اکیداً توصیه می‌شود پیش از مطالعهٔ این صفحهٔ راهنما، صفحهٔ مرور کلی hwloc(7) را بخوانید. بیشتر مفاهیم توصیف‌شده در hwloc(7) مستقیماً در ابزار hwloc-annotate کاربرد دارند.
مثال‌ها (EXAMPLES)
عملکرد hwloc-annotate با چند مثال به بهترین شکل شرح داده می‌شود.
افزودن یک مشخصهٔ info به تمام اشیاء Core و PU:
$ hwloc-annotate input.xml output.xml -- Core:all PU:all -- info infoname
infovalue
تنها افزودن به تمام اشیاء Core:
$ hwloc-annotate input.xml output.xml Core:all info infoname infovalue
افزودن یک مشخصهٔ info به دستگاه‌های سیستم‌عامل (OS device) شماره ۲ و ۳:
$ hwloc-annotate input.xml output.xml os:2-3 info infoname infovalue
تغییر رنگ اشیاء package به سبز با متن قرمز در خروجی گرافیکی lstopo:
$ hwloc-annotate topo.xml topo.xml package:all info lstopoStyle
"Background=#00ff00;Text=#ff0000"
$ lstopo -i topo.xml
افزودن یک شیء Misc به نام «foobar» ذیل شیء ریشه (root) مکان‌نگاری و اصلاح مستقیم فایل XML ورودی:
$ hwloc-annotate file.xml file.xml root misc foobar
مثال‌ها با مشخصه‌های حافظه (Examples with memory attributes)
تنظیم مشخصهٔ حافظهٔ Latency به ۱۲۳ نانوثانیه از PUهای نخستین package به نخستین گره NUMA:
$ hwloc-annotate topo.xml topo.xml numanode:0 memattr Latency $(hwloc-calc
package:0) 123
ثبت مشخصهٔ حافظهٔ MyApplicationPerformance (با پرچم‌هایی که مشخص می‌کنند به یک آغازگر نیاز دارد و مقادیر بالاتر را اول گزارش می‌دهد) و تنظیم مقدار آن برای آغازگر CPU-set با مقدار 0x11 به گره NUMA شماره ۲ روی ۲۳۴۵:
$ hwloc-annotate topo.xml topo.xml ignored memattr MyApplicationPerformance
need_init,higher
$ hwloc-annotate topo.xml topo.xml numanode:2 memattr
MyApplicationPerformance 0x11 2345
برای مشخص کردن اینکه گره NUMA شماره ۰ از نوع DDR است در حالی که گره NUMA شماره ۱ از نوع HBM است:
$ hwloc-annotate topo.xml topo.xml numa:0 subtype DDR
$ hwloc-annotate topo.xml topo.xml numa:1 subtype HBM
مثال‌ها با انواع پردازنده (Examples with CPU kinds)
مشخص کردن اینکه PU 0-3 و PU 4-7 از انواع متفاوتی هستند و دومی کارآمدتر است:
$ hwloc-annotate topo.xml topo.xml dummy cpukind 0x0f 0 0 CoreType Small
$ hwloc-annotate topo.xml topo.xml dummy cpukind 0xf0 1 0 CoreType Big
جایگزینی گره‌های NUMA با Packageها در ماتریس فواصل NUMALatency، هنگامی که دقیقاً محلی‌سازی (locality) یکسانی دارند:
$ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
NUMALatency replace-objs numanode packages
حذف گره NUMA شماره ۳ از ماتریس فواصل NUMALatency:
$ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
NUMALatency remove-obj numa:3
ادغام اطلاعات پهنای باند تمام درگاه‌های NVSwitch در یک درگاه واحد در ماتریس NVLinkBandwidth:
$ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
NVLinkBandwidth merge-switch-ports
اعمال یک بستار متعدی (transitive closure) برای به‌دست‌آوردن پهنای باند میان GPUها از طریق NVSwitchها در ماتریس NVLinkBandwidth:
$ hwloc-annotate topo.xml topo.xml -- dummy -- distances-transform
NVLinkBandwidth transitive-closure
مقدار بازگشتی (RETURN VALUE)
در صورت اجرای موفقیت‌آمیز، hwloc-annotate توپولوژی خروجی را تولید می‌کند. مقدار بازگشتی 0 است.
در صورت بروز هرگونه خطا، مانند (اما نه محدود به) شکست در تجزیه خط فرمان، hwloc-annotate یک مقدار غیرصفر بازمی‌گرداند.
همچنین ببینید (SEE ALSO)
hwloc(7), lstopo(1), hwloc-info(1)
| June 8, 2026 | 2.14.0 |