HWLOC-BIND(1) hwloc HWLOC-BIND(1)

hwloc-bind - اجرای دستوری که به پردازنده‌ها یا حافظه خاصی مقید شده است، یا بررسی مقیدسازی یک برنامه موجود

hwloc-bind [گزینه‌های توپولوژی] [گزینه‌ها] <موقعیت۱> [<موقعیت۲> [...] ] [--] <دستور> ...

توجه داشته باشید که hwloc(7) توضیح مفصلی درباره سامانه hwloc و قالب‌های معتبر <موقعیت> ارائه می‌دهد؛ باید پیش از خواندن این صفحه راهنما مطالعه شود.

تمام گزینه‌های توپولوژی باید پیش از سایر گزینه‌ها مشخص شوند.

تنها نخستین واحد پردازش (PU) به ازای هر هسته پیش از مقیدسازی حفظ می‌شود. در صورت مشخص شدن <N>، به جای آن N-امین واحد (در صورت وجود) نگه‌داشته می‌شود. واحدهای PU در طول این فیلترسازی بر اساس نمایه فیزیکی مرتب می‌شوند.

توجه داشته باشید که این گزینه پس از جستجوی موقعیت‌ها اعمال می‌شود. بنابراین --no-smt pu:2-5 ابتدا واحدهای پردازش شماره ۲ تا ۵ را در ماشین انتخاب کرده و سپس به یکی از آن‌ها به ازای هر هسته مقید می‌شود. برای مقیدسازی روی واحدهای شماره ۲ تا ۵ پس از فیلتر کردن یکی به ازای هر هسته، باید آن را با hwloc-calc ترکیب کنید:


hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --no-smt all) pu:2-5) -- echo hello

توپولوژی را به مجموعه پردازنده‌های (cpuset) مشخص‌شده محدود می‌کند. این کار برخی واحدهای PU و والدینی که دیگر فرزندی ندارند را حذف می‌کند.

دقت داشته باشید که محدود کردن واحدهای PU در یک توپولوژی ممکن است نمایه‌های منطقی بسیاری از اشیاء، از جمله گره‌های NUMA را تغییر دهد.

توپولوژی را به مجموعه گره‌های (nodeset) مشخص‌شده محدود می‌کند (مگر اینکه --restrict-flags چیز دیگری تعیین کند). این کار برخی گره‌های NUMA و والدینی که دیگر فرزندی ندارند را حذف می‌کند.

دقت داشته باشید که محدود کردن گره‌های NUMA در یک توپولوژی ممکن است نمایه‌های منطقی بسیاری از اشیاء، از جمله واحدهای PU را تغییر دهد.

اعمال فلگ‌ها هنگام محدود کردن توپولوژی. فلگ‌ها می‌توانند به صورت مقادیر عددی یا فهرستی جداشده با کاما از نام فلگ‌ها مشخص شوند که به hwloc_topology_restrict() پاس داده می‌شوند. این نام‌ها تا زمانی که تطابق یکتایی داشته باشند می‌توانند زیررشته‌ای از نام واقعی فلگ باشند، برای نمونه bynodeset,memless. پیش‌فرض 0 (یا none) است.
اشیاء منع‌شده توسط محدودیت‌های مدیریتی را نیز شامل می‌شود.
بهترین گره(های) NUMA را در میان مجموعه مقیدسازی حافظه ارائه‌شده با بررسی ویژگی حافظه مشخص‌شده با <name> (یا به صورت یک نمایه) انتخاب می‌کند.

اگر مقادیر ویژگی حافظه به آغازگر (initiator) وابسته باشد، مجموعه مقیدسازی پردازنده به عنوان آغازگر استفاده می‌شود.

نام‌های استاندارد ویژگی‌ها عبارتند از: Capacity، Locality، Bandwidth و Latency. تمام ویژگی‌های موجود در توپولوژی جاری را می‌توان با دستور زیر فهرست کرد:


$ lstopo --memattrs

نام <name> می‌تواند پسوندی از فلگ‌ها برای تنظیم دقیق انتخاب بهترین گره‌ها داشته باشد، به عنوان نمونه bandwidth,strict,default.

فلگ default یعنی اگر بهترین گره پیدا نشد، گره‌های پیش‌فرض گزارش شوند (نگاه کنید به --default-nodes). اگر نه بهترین و نه گره‌های پیش‌فرض یافت نشوند، تمام گره‌های محلی گزارش می‌شوند.

فلگ strict یعنی گره‌ها تنها در صورتی انتخاب شوند که کارایی آن‌ها برای تمام CPUهای ورودی بهترین باشد. روی یک ماشین دو سوکته با HBM در هر سوکت، هر دو HBM برای سوکت محلی خود بهترین هستند، اما نه برای سوکت راه دور. بنابراین هر دو HBM به طور پیش‌فرض برای کل ماشین نیز بهترین در نظر گرفته می‌شوند، اما در صورت استفاده از strict هیچ‌کدام انتخاب نمی‌شوند.

--default-nodes تنها گره‌های پیش‌فرض NUMA را نگه می‌دارد. این معمولاً شامل گره‌های حافظه DRAM (یا گره‌های همان رده حافظه) است به جای گره‌هایی با ویژگی‌های خاص (مانند HBM، NVM، CXL و غیره). برای جزئیات بیشتر به ()hwloc_topology_get_default_nodeset مراجعه کنید.

هنگام جستجوی گره‌های NUMA در موقعیت‌های ورودی، تنها گره‌های حافظه با پهنای باند بالا (علامت‌گذاری‌شده با زیرنوع "HBM"، یا "MCDRAM" در Intel Xeon Phi) را در نظر می‌گیرد.

این گزینه باید با موقعیت‌های گره NUMA ترکیب شود، مانند --hbm numa:1 برای مقیدسازی روی دومین گره HBM. همچنین می‌تواند به صورت numa[hbm]:1 یا numa[mcdram]:1 نوشته شود.

هنگام جستجوی گره‌های NUMA در موقعیت‌های ورودی، گره‌های حافظه با پهنای باند بالا (علامت‌گذاری‌شده با زیرنوع "HBM"، یا "MCDRAM" در Intel Xeon Phi) را نادیده می‌گیرد.

تمام این گزینه‌ها باید پس از تمام گزینه‌های توپولوژی بالا آورده شوند.

از آرگومان‌های بعدی برای مقیدسازی CPU استفاده می‌کند (پیش‌فرض).
از آرگومان‌های بعدی برای مقیدسازی حافظه استفاده می‌کند. اگر --mempolicy نیز ارائه نشود، سیاست پیش‌فرض bind است.
سیاست مقیدسازی حافظه را تغییر می‌دهد.

این گزینه تنها زمانی معنا دارد که یک مقیدسازی واقعی نیز با --membind ارائه شده باشد. اگر --membind بدون --mempolicy داده شود، سیاست پیش‌فرض bind خواهد بود.

سیاست‌های موجود عبارتند از default، firsttouch، bind، interleave، weighted (پخش متناوب با وزن) و nexttouch. برای جزئیات درباره این سیاست‌ها به hwloc.h مراجعه کنید.

توجه داشته باشید که سیاست‌های مقیدسازی حافظه در hwloc ممکن است کمی با سیاست‌های سیستم‌عامل متفاوت باشد. برای نمونه، سیاست bind در hwloc به طور پیش‌فرض از MPOL_PREFERRED_MANY (یا MPOL_PREFERRED) در لینوکس استفاده می‌کند، اما در صورتی که گزینه یا فلگ strict در hwloc داده شده باشد، به MPOL_BIND در لینوکس تغییر می‌یابد.

مقیدسازی‌های فعلی را گزارش می‌کند. خروجی یک ماسک بیتی مات است که می‌تواند با hwloc-calc به اشیاء تبدیل شود (بخش مثال‌ها را در زیر ببینید).
 
هنگامی که یک دستور داده شود، مقیدسازی پیش از اجرای دستور نمایش داده می‌شود. هنگامی که دستوری داده نشود، برنامه پس از نمایش مقیدسازی جاری خارج می‌شود.
 
در صورت ترکیب با --membind، به جای مقیدسازی CPU، مقیدسازی حافظه را گزارش می‌کند.
 
هیچ موقعیتی نمی‌تواند تعیین شود زیرا هیچ مقیدسازی‌ای انجام نمی‌شود.
در صورتی که --get داده شده باشد، مقیدسازی را به جای یک مجموعه‌پردازنده (cpuset) به عنوان یک مجموعه گره‌های حافظه NUMA گزارش می‌کند. این برای کار با گره‌های NUMA بدون CPU مفید است زیرا مجموعه‌پردازنده آن‌ها خالی است در حالی که مجموعه‌گره آن‌ها معتبر است.
 
همچنین ماسک‌های بیتی ورودی را به جای مجموعه‌پردازنده به عنوان مجموعه‌گره تجزیه می‌کند.
 
هنگامی که این گزینه ارسال نشود، ماسک‌های بیتی منفرد در ورودی اگر دارای پیشوند nodeset= باشند همچنان می‌توانند به عنوان مجموعه‌گره تجزیه شوند.
آخرین پردازنده‌هایی را که فرآیند روی آن‌ها اجرا شده است گزارش می‌دهد. خروجی یک ماسک بیتی مات است که می‌تواند با hwloc-calc به اشیاء تبدیل شود (بخش مثال‌ها را در زیر ببینید).
 
توجه داشته باشید که نتیجه ممکن است در زمان گزارش شدن منسوخ شده باشد، زیرا سیستم‌عامل می‌تواند بر اساس مقیدسازی در هر زمان فرآیند را به پردازنده‌های دیگر منتقل کند.
 
هنگامی که دستوری داده شود، آخرین پردازنده‌ها پیش از اجرای دستور نمایش داده می‌شوند. هنگامی که دستوری داده نشود، برنامه پس از نمایش آخرین پردازنده‌ها خارج می‌شود.
 
این گزینه نمی‌تواند با --membind ترکیب شود.
 
هیچ موقعیتی نمی‌تواند تعیین شود زیرا هیچ مقیدسازی‌ای انجام نمی‌شود.
روی یک تک‌پردازنده مقید می‌شود تا از مهاجرت (migration) جلوگیری کند.
مقیدسازی سخت‌گیرانه (strict) را الزامی می‌کند.
روی فرآیند <pid> عمل می‌کند.
به جای کل فرآیند، روی رشته (thread) مشخص‌شده با <tid> عمل می‌کند. این ویژگی تنها در لینوکس برای مقیدسازی CPU رشته، یا برای گزارش آخرین پردازنده‌ای که رشته روی آن اجرا شده در صورتی که -e نیز ارسال شده باشد، پشتیبانی می‌شود.
موقعیت‌های ورودی را با نمایه‌های فیزیکی/سیستم‌عامل به جای نمایه‌های منطقی تفسیر می‌کند. این گزینه روی خروجی اعمال نمی‌شود، --get را در بالا ببینید.
موقعیت‌های ورودی را با نمایه‌های منطقی به جای نمایه‌های فیزیکی/سیستم‌عامل تفسیر می‌کند (پیش‌فرض). این گزینه روی خروجی اعمال نمی‌شود، --get را در بالا ببینید.
قالب رشته‌های مجموعه‌پردازنده (CPUset) یا مجموعه‌گره نمایش‌داده‌شده توسط --get، -e و غیره را تغییر می‌دهد. به طور پیش‌فرض، قالب اختصاصی hwloc استفاده می‌شود. اگر list داده شود، خروجی به صورت اعدادی یا بازه‌هایی جداشده با کاما خواهد بود، مانند 2,4-5,8 . اگر taskset داده شود، خروجی سازگار با برنامه taskset خواهد بود (جایگزین گزینه پیشین --taskset).

این گزینه تأثیری بر قالب رشته‌های مجموعه پردازنده ورودی ندارد؛ قالب‌های hwloc، list و taskset همیشه پذیرفته می‌شوند. در صورت وجود ابهام، از hwloc-calc --cpuset-input-format استفاده کنید.

برنامه اجرایی را حتی در صورت شکست در مقیدسازی اجرا می‌کند.
پیام‌های خطای غیربحرانی را پنهان می‌کند. این شامل موقعیت‌هایی است که به اشیاء ناموجود اشاره دارند، و همچنین شکست در مقیدسازی. این گزینه معمولاً علاوه بر --force مفید است.
خروجی پرجزئیات.
گزارش نسخه و خروج.
نمایش پیام راهنما و خروج.

دستور hwloc-bind یک برنامه اجرایی را (با آرگومان‌های اختیاری خط فرمان) که به موقعیت (یا فهرستی از موقعیت‌ها) مقید شده است، اجرا (exec) می‌کند. نحوه تعیین موقعیت در hwloc(7) توضیح داده شده است. پس از اجرای موفقیت‌آمیز، hwloc-bind صرفاً مقیدسازی‌ها را تنظیم کرده و سپس برنامه اجرایی را روی خود اجرا (exec) می‌کند.

اگر موقعیتِ ماسک بیتی با پیشوند nodeset= داده شود، به عنوان یک مجموعه‌گره به جای یک مجموعه‌پردازنده در نظر گرفته می‌شود. همچنین به --nodeset مراجعه کنید.

اگر چندین موقعیت داده شوند، به این صورت ترکیب می‌شوند که مقیدسازی گسترده‌تر خواهد شد. فرآیند مجاز خواهد بود روی هر موقعیتی در درون این ترکیب اجرا شود.

فهرست موقعیت‌های ورودی می‌تواند صراحتاً با "--" خاتمه یابد.

اگر مقیدسازی با شکست مواجه شود، یا اگر مجموعه مقیدسازی خالی باشد، و --force داده نشده باشد، hwloc-bind با یک خطا برمی‌گردد به جای آنکه برنامه اجرایی را اجرا کند.

نکته: بسیار توصیه می‌شود که پیش از خواندن این صفحه راهنما، صفحه نمای کلی hwloc(7) را مطالعه کنید. بیشتر مفاهیم توصیف‌شده در hwloc(7) مستقیماً در ابزار hwloc-bind نیز کاربرد دارند.

عملکرد hwloc-bind از طریق چندین مثال به بهترین شکل توصیف می‌شود. جزئیات بیشتر درباره نحوه تعیین موقعیت‌ها در خط فرمان hwloc-bind در hwloc(7) آمده است.

برای اجرای دستور echo روی نخستین پردازنده منطقی از دومین بسته (Package):


$ hwloc-bind package:1.pu:0 -- echo hello

که دقیقاً معادل سطر زیر است، تا زمانی که ابهامی میان نام گزینه‌های hwloc-bind و نام دستور اجراشده وجود نداشته باشد:


$ hwloc-bind package:1.pu:0 echo hello

برای مقیدسازی دستور "echo" به نخستین هسته از دومین بسته و دومین هسته از نخستین بسته:


$ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello

برای مقیدسازی روی نخستین PU از تمام هسته‌های نخستین بسته:


$ hwloc-bind package:0.core:all.pu:0 -- echo hello
$ hwloc-bind --no-smt package:0 -- echo hello

گزینه --get می‌تواند مقیدسازی‌های جاری را گزارش کند. این مثال تودرتویی فراخوانی‌های hwloc-bind را برای تنظیم یک مقیدسازی و سپس گزارش آن نشان می‌دهد:


$ hwloc-bind node:1.package:2 -- hwloc-bind --get
0x00004444,0x44000000

برای مقیدسازی روی یک گره خاص و واگذاری استقرار اجرا به سیستم‌عامل بر همان اساس:


$ hwloc-bind --membind node:2 -- echo hello

برای مقیدسازی حافظه روی دومین گره حافظه و اجرا روی نخستین گره (هنگامی که توسط سیستم‌عامل پشتیبانی شود):


$ hwloc-bind --cpubind node:1 --membind node:0 -- echo hello

برای مقیدسازی روی گره(های) حافظه محلیِ یک PU با بیشترین ظرفیت:


$ hwloc-bind --best-memattr capacity --cpubind pu:23 --membind pu:23 -- echo hello

برای مقیدسازی روی گره حافظه پیش‌فرض نزدیک یک بسته:


$ hwloc-bind --default-nodeset --membind package:1 -- echo hello

برای مقیدسازی حافظه روی نخستین گره NUMA علامت‌گذاری‌شده با زیرنوع "HBM":


$ hwloc-bind --membind numa[hbm]:0 -- echo hello
$ hwloc-bind --hbm --membind numa:0 -- echo hello

برای مقیدسازی حافظه روی نخستین گره حافظه با پهنای باند بالا (MCDRAM) در پردازنده Intel Xeon Phi:


$ hwloc-bind --membind numa[mcdram]:0 -- echo hello
$ hwloc-bind --hbm --membind numa:0 -- echo hello

توجه داشته باشید که مقیدسازی دستور "echo" به چندین پردازنده احتمالاً بی‌معنی است (چرا که "echo" معمولاً به عنوان یک برنامه تک‌رشته‌ای پیاده‌سازی شده است)؛ این مثال‌ها صرفاً برای نشان دادن قابلیت‌های hwloc-bind هستند.

مقیدسازی جاری حافظه نیز می‌تواند گزارش شود:


$ hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind --get --membind
0x000000f0 (interleave)

برای اجرا روی سه بسته نخست در گره‌های دوم و سوم:


$ hwloc-bind node:1-2.package:0:3 -- echo hello

که همچنین معادل است با:


$ hwloc-bind node:1-2.package:0-2 -- echo hello

توجه داشته باشید که اگر سعی کنید به اشیائی که وجود ندارند مقید شوید، hwloc-bind هشداری نمی‌دهد مگر اینکه -v مشخص شده باشد.

برای اجرا روی هسته‌ای با نمایه فیزیکی ۲ در بسته‌ای با نمایه فیزیکی ۱:


$ hwloc-bind --physical package:1.core:2 -- echo hello

برای اجرا روی هسته‌های فرد در درون بسته‌های زوج:


$ hwloc-bind package:even.core:odd -- echo hello

برای اجرا روی نخستین بسته، به جز روی هسته‌های دوم و پنجم آن:


$ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 -- echo hello

برای اجرا در هر جا به جز روی نخستین بسته:


$ hwloc-bind all ~package:0 -- echo hello

برای اجرا روی هسته‌ای نزدیک رابط شبکه به نام eth0:


$ hwloc-bind os=eth0 -- echo hello

برای اجرا روی هسته‌ای نزدیک دستگاه PCI که شناسه گذرگاه آن 0000:01:02.0 است:


$ hwloc-bind pci=0000:01:02.0 -- echo hello

دستور hwloc-bind گزینه‌ای برای انتخاب نوع هسته پردازنده ندارد، اما می‌توان آن را با hwloc-calc برای انجام این کار ترکیب کرد. برای نمونه، برای مقیدسازی روی دو هسته نخست که نوع آن‌ها با CoreType=IntelAtom مطابقت دارد:


$ hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --cpukind CoreType=IntelAtom all) core:0-1) -- echo hello

ابزار hwloc-calc همچنین می‌تواند برای تبدیل رشته‌های ماسک CPU به رشته‌های خوانای package/core/PU استفاده شود؛ برای جزئیات بیشتر به توضیحات H- در hwloc-calc(1) مراجعه کنید. مثال زیر به تمام واحدهای PU در یک هسته خاص مقید می‌شود، از گزینه --get برای بازیابی جایی که فرآیند واقعاً به آن مقید شده است استفاده می‌کند، و سپس با استفاده از hwloc-calc ماسک CPU حاصل را در فهرستی جداشده با فاصله از موقعیت‌های خوانا برای انسان نمایش می‌دهد:


$ hwloc-bind package:1.core:2 -- hwloc-bind --get | hwloc-calc -q -H package.core.pu
Package:1.Core:2.PU:0 Package:1.Core:2.PU:1

ابزار hwloc-calc می‌تواند این خروجی را به اشیاء واقعی، چه با نمایه‌های منطقی و چه فیزیکی تبدیل کند:


$ hwloc-calc --physical -I pu `hwloc-bind --get`
26,30,34,38,42,46
$ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " "
24 25 26 27 28 29

موقعیت‌ها همچنین می‌توانند به عنوان یک ماسک بیتی هگزادسیمال (که معمولاً توسط hwloc-calc تولید می‌شود) مشخص شوند. برای نمونه:


$ hwloc-bind 0x00004444,0x44000000 -- echo hello
$ hwloc-bind `hwloc-calc node:1.package:2` -- echo hello

اگر نسخه دارای رابط گرافیکی lstopo در دسترس است، برای نمونه از دستور زیر استفاده کنید:


$ hwloc-bind core:2 -- lstopo --pid 0

تا بررسی کنید نتیجه دستور مقیدسازی شما واقعاً چیست. ابزار lstopo به صورت گرافیکی نشان خواهد داد که توسط hwloc-bind به کجا مقید شده است.

پس از اجرای موفقیت‌آمیز، hwloc-bind دستور را روی خود اجرا (exec) می‌کند. بنابراین مقدار بازگشتی همان مقدار بازگشتی دستور اجراشده است.

اگر هر گونه خطایی رخ دهد، hwloc-bind یک مقدار غیر صفر برمی‌گرداند، مانند (اما نه محدود به): عدم موفقیت در تجزیه خط فرمان، عدم موفقیت در بازیابی مقیدسازی‌های فرآیند، یا نبود دستوری برای اجرا.

hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)

June 8, 2026 2.14.0