.\" -*- nroff -*-
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright © 2013-2024 Inria.  All rights reserved.
.\" See COPYING in top-level directory.
.TH HWLOC-ANNOTATE "1" "Jun 08, 2026" "2.14.0" "hwloc"
.SH "نام (NAME)"
hwloc-annotate \- ویرایش ویژگی‌ها در یک توپولوژی XML
.
.\" **************************
.\"    Synopsis Section
.\" **************************
.SH "خلاصه دستور (SYNOPSIS)"
.B hwloc-annotate
[\fIoptions\fR]
\fI<input.xml>\fR
\fI<output.xml>\fR
-- \fI<location1>\fR \fI<location2>\fR ... --
\fI<mode>\fR
\fI<annotation>\fR
.

.B hwloc-annotate
[\fIoptions\fR]
\fI<input.xml>\fR
\fI<output.xml>\fR
\fI<location>\fR
\fI<mode>\fR
\fI<annotation>\fR
.
.PP
توجه داشته باشید که hwloc(7) توضیح مفصلی درباره سامانه hwloc
و قالب‌های معتبر <location> ارائه می‌دهد؛
این بخش باید پیش از خواندن این صفحه راهنما مطالعه شود.
.\" **************************
.\"    Options Section
.\" **************************
.SH "گزینه‌ها (OPTIONS)"
.
.TP 10
\fB\-\-ri\fR
حذف تمام ویژگی‌های اطلاعاتی (info) موجود با نام یکسان پیش از افزودن مورد جدید.
این گزینه فقط در حالت «info» پذیرفته می‌شود.
اگر مقدار info حذف شود، مقادیر info موجود با هیچ جایگزین می‌شوند.
.TP
\fB\-\-ci\fR
پاک کردن ویژگی‌های اطلاعاتی موجود در اشیاء هدف پیش از نشانه‌گذاری.
اگر پس از پاک‌سازی نیازی به افزودن نشانه‌گذاری جدیدی نیست، \fImode\fR باید روی
\fInone\fR تنظیم شود.
.TP
\fB\-\-cu\fR
پاک کردن داده‌های کاربری (userdata) موجود از اشیاء هدف.
اگر پس از پاک‌سازی کار دیگری نباید انجام شود، \fImode\fR باید روی
\fInone\fR تنظیم شود.
.
.TP
\fB\-\-cd\fR
پاک کردن فاصله‌های (distances) موجود از توپولوژی.
اگر پس از پاک‌سازی کار دیگری نباید انجام شود، \fImode\fR باید روی
\fInone\fR تنظیم شود.
.TP
\fB\-\-version\fR
گزارش نسخه و خروج.
.TP
\fB\-h\fR \fB\-\-help\fR
نمایش پیام راهنما و خروج.
.
.\" **************************
.\"    Description Section
.\" **************************
.SH "توضیحات (DESCRIPTION)"
.
دستور hwloc-annotate یک توپولوژی را از یک فایل XML بارگیری می‌کند، برخی نشانه‌گذاری‌ها را می‌افزاید،
و توپولوژی حاصل را به یک فایل XML دیگر صادر می‌کند.
فایل‌های ورودی و خروجی ممکن است یکسان باشند.
.
.PP
نشانه‌گذاری‌ها ممکن است ویژگی‌های اطلاعاتی رشته‌ای باشند.
این مورد با \fImode\fR مشخص می‌شود:
.
.TP
.B info <name> <value>
یک ویژگی اطلاعاتی رشته‌ای جدید را مشخص می‌کند که نام آن \fIname\fR و
مقدار آن \fIvalue\fR است.
.TP
.B subtype <subtype>
مشخص می‌کند که ویژگی زیرنوع (subtype) شیء اکنون باید \fIsubtype\fR باشد.
اگر یک رشته خالی داده شود، زیرنوع حذف می‌شود.
.TP
.B size <size>
اندازه یک حافظه موقت (cache) یا گره NUMA را مشخص می‌کند.
این مقدار می‌تواند پسوندهایی مانند \fBkB\fR، \fBKiB\fR، \fBMB\fR، \fBMiB\fR،
\fBGB\fR، \fBGiB\fR و غیره داشته باشد.
.TP
.B misc <name>
نام یک شیء Misc جدید را مشخص می‌کند.
.TP
.B memattr <name> <flags>
یک ویژگی حافظه جدید را ثبت می‌کند که نام آن \fIname\fR و
پرچم‌های آن \fIflags\fR است.
در این حالت \fIlocation\fR نادیده گرفته می‌شود.

پرچم‌ها ممکن است به صورت مقادیر عددی یا فهرستی جداشده با کاما از نام‌های پرچم
که به \fIhwloc_memattr_register()\fR ارسال می‌شوند، داده شوند.
این نام‌ها تا زمانی که فقط با یک پرچم تطابق داشته باشند، می‌توانند زیررشته‌هایی از نام‌های واقعی پرچم باشند.
برای نمونه، مقدار \fB1\fR (یا \fBhigher\fR) به این معنی است که
بالاترین مقادیر برای این ویژگی به عنوان بهترین در نظر گرفته می‌شوند.
.TP
.B memattr <name> <initiator> <value>
ویژگی حافظه (با نام \fIname\fR) را از آغازگر \fIinitiator\fR (شیء یا CPU-set)
برای گره NUMA هدف \fIlocation\fR
روی مقدار \fIvalue\fR تنظیم می‌کند.

اگر این ویژگی به آغازگرهای خاصی نیاز نداشته باشد،
\fIinitiator\fR نادیده گرفته می‌شود.

نام‌های استاندارد ویژگی‌ها عبارت‌اند از: \fICapacity\fR، \fILocality\fR،
\fIBandwidth\fR و \fILatency\fR.
تمام ویژگی‌های موجود در توپولوژی ورودی را می‌توان با دستور زیر فهرست کرد:

    $ lstopo --memattrs -i input.xml

.TP
.B cpukind <cpuset> <efficiency> <flags> [<infoname> <infovalue>]
نوع پردازنده را برای PUهای فهرست‌شده در cpuset داده‌شده مشخص می‌کند.
در این حالت \fIlocation\fR نادیده گرفته می‌شود.

مقدار \fIefficiency\fR یک مقدار کارایی انتزاعی است که
رتبه‌بندی انواع را اعمال خواهد کرد. در صورت نامشخص بودن باید -1 باشد.

مقدار \fIflags\fR در حال حاضر باید 0 باشد.

اگر \fIinfoname\fR و \fIinfovalue\fR داده شده و غیرخالی باشند،
به عنوان ویژگی‌های اطلاعاتی به این نوع پردازنده افزوده می‌شوند.

برای جزئیات به تابع hwloc_cpukinds_register() مراجعه کنید.

.TP
.B distances <filename> [<flags>]
فاصله‌های جدیدی را مشخص می‌کند که با استفاده از مشخصات موجود در \fI<filename>\fR به توپولوژی اضافه شوند.
پرچم اختیاری \fIflags\fR (0 مگر اینکه مشخص شود) با پرچم‌های
داده‌شده به تابع \fBhwloc_distances_set()\fR مطابقت دارد.
در این حالت \fIlocation\fR نادیده گرفته می‌شود.

نخستین خط واقعی فایل ارجاع‌شده باید یک عدد صحیح نشان‌دهنده
نوع فاصله (\fBkind\fR) باشد، همان‌طور که در \fBhwloc/distances.h\fR تعریف شده است.
خط دوم تعداد اشیاء درگیر در فاصله‌ها است.
خطوط بعدی هر کدام شامل یک شیء هستند.
خطوط بعدی هر کدام شامل یک مقدار فاصله هستند،
یا ممکن است یک خط منفرد با ترکیب عددی در قالب \fBx*y\fR یا \fBx*y*z\fR داده شود.
یک خط اختیاری پیش از تمام خطوط می‌تواند با \fBname=\fR آغاز شود
تا نام ساختار فاصله‌ها را در صورت وجود مشخص کند.

.TP
.B distances-transform <name> links
یک ساختار فاصله‌های پهنای باند با نام <name> را به پیوندها (links) تبدیل می‌کند.
برای جزئیات، مستندات HWLOC_DISTANCES_TRANSFORM_LINKS را در hwloc/distances.h ببینید.
.TP
.B distances-transform <name> merge-switch-ports
هنگامی که سوئیچ‌ها در ماتریس به صورت درگاه‌های متفاوتی ظاهر می‌شوند، برای شفافیت بیشتر
همه آنها را در یک درگاه واحد ادغام می‌کند.
این مورد در حال حاضر فقط برای ماتریس NVLinkBandwidth بین پردازنده‌های گرافیکی NVIDIA اعمال می‌شود.
برای جزئیات، مستندات HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS را در hwloc/distances.h ببینید.
.TP
.B distances-transform <name> transitive-closure
اگر اشیاء از طریق یک سوئیچ به هم متصل باشند، یک بستار متعدی (transitive-closure) اعمال می‌کند
تا پهنای باند از طریق آن سوئیچ گزارش شود.
این مورد در حال حاضر فقط برای ماتریس NVLinkBandwidth بین پردازنده‌های گرافیکی NVIDIA اعمال می‌شود.
پهنای باند بین تمام جفت‌های GPU ارائه خواهد شد، نه
پهنای باند بین تک‌تک GPUها و درگاه‌های تکی NVSwitch.
برای جزئیات، مستندات HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE را در hwloc/distances.h ببینید.
.TP
.B distances-transform <name> remove-obj <obj>
شیء مشخص‌شده را از ساختار فاصله‌ها با نام <name> حذف می‌کند.
.TP
.B 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
.B none
هیچ یادداشت جدیدی افزوده نمی‌شود. این حالت هنگام پاک‌کردن مشخصه‌های موجود کاربرد دارد.
.
.PP
یادداشت‌ها ممکن است به یک شیء خاص در مکان‌نگاری (topology)، همهٔ آن‌ها یا همهٔ اشیاء از یک نوع مشخص اضافه شوند.
این مورد توسط \fIlocation\fR مشخص می‌شود (بخش «مثال‌ها» در زیر را نیز ببینید).
اگر مکان‌ها میان \fB--\fR مشخص شوند، چندین مکان ممکن است تحت تأثیر قرار گیرند.
همان‌طور که در hwloc(7) توضیح داده شده است، اشیاء را می‌توان به صورت چندتایی‌های مکان (location tuples) مشخص کرد.
با این حال، ماسک‌های بیتی هگزادسیمال پذیرفته نمی‌شوند، زیرا ممکن است با چندین شیء مطابقت داشته باشند.
.
.PP
.B نکته:
یادداشت‌های موجود را می‌توان با hwloc-info فهرست کرد.
.PP
.B نکته:
اکیداً توصیه می‌شود پیش از مطالعهٔ این صفحهٔ راهنما، صفحهٔ مرور کلی hwloc(7) را بخوانید.
بیشتر مفاهیم توصیف‌شده در hwloc(7) مستقیماً در ابزار hwloc-annotate کاربرد دارند.
.
.\" **************************
.\"    Examples Section
.\" **************************
.SH "مثال‌ها (EXAMPLES)"
.PP
عملکرد hwloc-annotate با چند مثال به بهترین شکل شرح داده می‌شود.
.
.PP
افزودن یک مشخصهٔ 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
.\" **************************
.SH "مثال‌ها با مشخصه‌های حافظه (Examples with memory attributes)"
.PP
تنظیم مشخصهٔ حافظهٔ Latency به ۱۲۳ نانوثانیه از PUهای نخستین package به نخستین گره NUMA:

    $ hwloc-annotate topo.xml topo.xml numanode:0 memattr Latency $(hwloc-calc package:0) 123

ثبت مشخصهٔ حافظهٔ \fBMyApplicationPerformance\fR
(با پرچم‌هایی که مشخص می‌کنند به یک آغازگر نیاز دارد و مقادیر بالاتر را اول گزارش می‌دهد)
و تنظیم مقدار آن برای آغازگر 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
.\" **************************
.SH "مثال‌ها با انواع پردازنده (Examples with CPU kinds)"
.PP
مشخص کردن این‌که 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

.
.\" **************************
.\"    Examples distances matrices
.\" **************************.SH "مثال‌ها با ماتریس‌های فواصل (Examples with distances matrices)"
.PP
جایگزینی گره‌های 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 section
.\" **************************
.SH "مقدار بازگشتی (RETURN VALUE)"
در صورت اجرای موفقیت‌آمیز، hwloc-annotate توپولوژی خروجی را تولید می‌کند.
مقدار بازگشتی 0 است.
.
.PP
در صورت بروز هرگونه خطا، مانند (اما نه محدود به) شکست در تجزیه خط فرمان، hwloc-annotate یک مقدار غیرصفر بازمی‌گرداند.
.
.\" **************************
.\"    See also section
.\" **************************
.SH "همچنین ببینید (SEE ALSO)"
.
.ft R
hwloc(7), lstopo(1), hwloc-info(1)
.sp