.TH CLINFO 1 "2025-02-14" "clinfo 3.0.25.02.14"

.SH "نام (NAME)"

clinfo \- نمایش پلتفرم‌ها و دستگاه‌های OpenCL

.SH "خلاصه دستور (SYNOPSIS)"
.B clinfo
.RI [ "گزینه‌ها ..." ]

.SH "توضیحات (DESCRIPTION)"
.B clinfo
تمام اطلاعات موجود درباره تمام پلتفرم‌های OpenCL
موجود در سیستم و دستگاه‌هایی که ارائه می‌دهند را چاپ می‌کند.

.SH "گزینه‌ها (OPTIONS)"
.B clinfo
گزینه‌های زیر را می‌پذیرد:
.TP 2
.BR -a ", " --all-props
تلاش برای دریافت تمام ویژگی‌ها، حتی مواردی که به طور رسمی پشتیبانی نمی‌شوند
(برای مثال به این دلیل که به افزونه‌های خاصی نیاز دارند)، اما فقط در صورتی نمایش داده می‌شوند
که ویژگی با موفقیت دریافت شده باشد؛ همچنین بخش
.B "محدودیت‌ها (LIMITATIONS)"
در زیر را ببینید؛ توجه داشته باشید با وجود اینکه این کار ممکن است ویژگی‌های پنهان را آشکار کند،
هیچ تضمینی وجود ندارد که مقادیر بازگردانده‌شده معنادار باشند یا قابلیت مربوطه در عمل
اصلاً در دسترس باشد؛
.TP
.BR -A ", " --always-all-props
مانند
.BR -a ،
اما خطاها را نیز نشان می‌دهد؛
.TP
.B --human
تولید خروجی خوانا برای انسان؛ این حالت پیش‌فرض است (به‌جز
موارد ذکرشده در زیر)؛
.TP
.B --raw
تولید خروجی مناسب ماشین؛ این حالت پیش‌فرض است اگر
.B clinfo
با نامی فراخوانی شود که حاوی رشته
.RI \*(lq raw \*(rq
باشد؛
.TP
.B --json
داده‌های خام را در قالب JSON خروجی می‌دهد (مقایسه کنید با گزینه
.BR --raw )؛
پشتیبانی از این گزینه آزمایشی است،
زیرا نحوه نمایش برخی از مقادیر هنوز نهایی نشده است؛
.TP
.B --offline
دستگاه‌های آفلاین را نیز برای پلتفرم‌هایی که این قابلیت را ارائه می‌دهند نشان می‌دهد؛
.TP
.B --null-platform
تلاش می‌کند با پلتفرم NULL مانند یک پلتفرم عادی رفتار کند،
و ویژگی‌ها و دستگاه‌های آن را دریافت کرده و نشان دهد؛
این علاوه بر آزمایش‌های رفتاری پلتفرم NULL است که در انتها انجام می‌شود،
و می‌تواند در سیستم‌هایی که هیچ پلتفرم ICD در آن‌ها وجود ندارد،
اما یک پلتفرم درون خود کتابخانه OpenCL به صورت مستقیم کدنویسی شده است، مفید باشد؛
.TP
.BR -l ", " --list
فهرست کردن پلتفرم‌ها و دستگاه‌ها بر اساس نام، بدون ویژگی‌های (دیگر)؛
.TP
.BI -d " platform_index" : device_index
.TQ
.BI --device " platform_index" : device_index
فقط ویژگی‌های دستگاه مشخص‌شده در پلتفرم مشخص‌شده را نشان می‌دهد؛
می‌توان چندین مشخصه دستگاه را در خط فرمان مشخص کرد؛
.TP
.BI --prop " property-name"
فقط ویژگی‌هایی را نشان می‌دهد که نام نمادین آن‌ها با
.IR property-name
داده‌شده مطابقت داشته باشد (آن را به عنوان یک زیررشته شامل شود)؛
نام به صورت حروف بزرگ و با جایگزینی خط فاصله (-)
با خط زیر (_) نرمال‌سازی می‌شود؛
می‌توان چندین مشخصه ویژگی را در خط فرمان مشخص کرد؛
وقتی این فلگ مشخص شود، حالت خام (raw) اجباری می‌شود؛
.TP
.BR --help ", " -? ", " -h
نمایش راهنمای استفاده؛
.TP
.BR --version ", " -v
نمایش نسخه برنامه.

.SH "سازگاری با استانداردها (CONFORMING TO)"

OpenCL 1.1, OpenCL 1.2, OpenCL 2.0, OpenCL 2.1, OpenCL 2.2, OpenCL 3.0.

.SH "افزونه‌ها (EXTENSIONS)"

افزونه‌های پشتیبانی‌شده OpenCL:
.TP 2
.B cl_khr_device_uuid
برای UUID، LUID و ماسک گره (node mask) دستگاه؛
.TP
.B cl_khr_extended_versioning
برای ویژگی‌های نسخه‌بندی‌شده گسترش‌یافته پلتفرم، دستگاه، افزونه و IL
که از OpenCL 3.0 به نسخه‌های پیشین OpenCL منتقل شده‌اند؛
.TP
.BR cl_khr_fp16 ", " cl_khr_fp64 ", " cl_amd_fp64 ", " cl_APPLE_fp64_basic_ops
برای اطلاعات درباره پشتیبانی از انواع داده‌های ممیز شناور
با دقت نیمه (half-precision) و دقت مضاعف (double-precision)؛
.TP
.B cl_khr_image2d_from_buffer
برای اطلاعات درباره الزامات هم‌ترازی آدرس پایه و گام (pitch)
بافرهایی که به عنوان پایه برای تصاویر دوبعدی استفاده می‌شوند؛
.TP
.B cl_khr_il_program
برای اطلاعات درباره نمایش‌های پشتیبانی‌شده زبان میانی (IL)؛
.TP
.B cl_khr_spir
برای اطلاعات درباره نسخه‌های پشتیبانی‌شده نمایش میانی استاندارد قابل حمل (SPIR)؛
.TP
.B cl_khr_icd
برای پسوند توابع افزونه‌های عرضه‌کننده؛
.TP
.B cl_khr_subgroup_named_barrier
برای حداکثر تعداد سدهای نام‌گذاری‌شده زیرگروه؛
.TP
.BI cl_khr_terminate_context ", " cl_arm_controlled_kernel_termination
برای قابلیت‌های خاتمه دادن به دستگاه؛
.TP
.B cl_ext_device_fission
برای پشتیبانی از تقسیم دستگاه (device fission) در دستگاه‌های OpenCL 1.1؛
.TP
.B cl_khr_pci_bus_info
برای اطلاعات گذرگاه PCI (همچنین
.BR cl_nv_device_attribute_query " و"
.BR cl_amd_device_attribute_query
را ببینید)؛
.TP
.B cl_ext_atomic_counters_32
.TQ
.B cl_ext_atomic_counters_64
برای افزونه شمارنده‌های اتمیک؛
.TP
.B cl_ext_float_atomics
برای قابلیت‌های اتمیک ممیز شناور برای دقت نیمه، یگانه و مضاعف
(بسته به پشتیبانی سخت‌افزار از اندازه ممیز شناور)؛
.TP
.B cl_ext_cxx_for_opencl
برای نسخه زبان C++ for OpenCL که توسط کامپایلر دستگاه پشتیبانی می‌شود؛
.TP
.B cl_amd_device_attribute_query
برای ویژگی‌های دستگاه اختصاصی AMD؛
.TP
.B cl_amd_object_metadata
برای نمایش حداکثر تعداد کلیدهای پشتیبانی‌شده توسط پلتفرم؛
.TP
.B cl_amd_offline_devices
برای نمایش دستگاه‌های آفلاین ارائه‌شده توسط پلتفرم، در صورت درخواست (گزینه
.B --offline
را ببینید)؛
.TP
.B cl_amd_copy_buffer_p2p
برای نمایش تعداد و شناسه‌های دستگاه‌های P2P موجود؛
.TP
.B cl_amd_svm
.TQ
.B cl_arm_shared_virtual_memory
برای قابلیت‌های حافظه مجازی مشترک (SVM) در دستگاه‌های OpenCL 1.2؛
.TP
.B cl_arm_core_id
برای نمایش فهرست (احتمالاً تنک) شناسه‌های هسته‌ای که ممکن است دستگاه بازگرداند؛
.TP
.B cl_arm_job_slot_selection
برای نمایش فهرست (احتمالاً تنک) اسلات‌های کاری در دسترس برای ارسال دستورات؛
.TP
.B cl_arm_scheduling_controls
برای نمایش کنترل‌های زمان‌بندی کار پشتیبانی‌شده و مجموعه‌های موجود برای تخصیص ثبات‌ها؛
.TP
.B cl_nv_device_attribute_query
برای ویژگی‌های دستگاه اختصاصی NVIDIA؛
.TP
.B cl_intel_device_attribute_query
برای ویژگی‌های دستگاه اختصاصی Intel؛
.TP
.B cl_intel_exec_by_local_thread
برای افزونه Intel که به دستگاه‌های پردازنده (CPU) اجازه می‌دهد کرنل‌ها را به عنوان بخشی از
نخ میزبان جاری اجرا کنند؛
.TP
.B cl_intel_advanced_motion_estimation
برای نسخه شتاب‌دهنده تخمین حرکت پیشرفته Intel؛
.TP
.B cl_intel_device_side_avc_motion_estimation
برای نسخه و قابلیت‌های پشتیبانی‌شده از تخمین حرکت AVC سمت دستگاه Intel؛
.TP
.B cl_intel_planar_yuv
برای حداکثر ابعاد تصاویر مسطح YUV؛
.TP
.B cl_intel_simultaneous_sharing
برای اشتراک‌گذاری همزمان کانتکست‌های CL/GL/DirectX (فقط پشتیبانی جزئی)؛
.TP
.B cl_intel_required_subgroup_size
برای شمارش اندازه‌های مجاز زیرگروه؛
.TP
.B cl_intel_command_queue_families
برای شمارش صف‌های دستور موجود و ویژگی‌ها و قابلیت‌های آن‌ها؛
.TP
.B cl_altera_device_temperature
برای افزونه Altera جهت پرس‌وجوی دمای هسته دستگاه؛
.TP
.B cl_qcom_ext_host_ptr
برای افزونه QUALCOMM جهت پرس‌وجوی اندازه صفحه و فاصله‌گذاری (padding) مورد نیاز در تخصیص حافظه خارجی.

.SH "نکات (NOTES)"
برخی اطلاعات در صورتی که از چندین منبع در دسترس باشند، تکرار می‌شوند.
مثال‌ها:
.IP \(bu 2
انواع پارتیشن و دامنه‌های پشتیبانی‌شده دستگاه که با استفاده از افزونه
.B cl_ext_device_fission
به دست می‌آیند، معمولاً با موارد به‌دست‌آمده با استفاده از
قابلیت پارتیشن دستگاه در هسته OpenCL 1.2 مطابقت دارند؛
.IP \(bu
مضرب اندازه ترجیحی گروه کاری با اندازه warp انویدیا (روی
دستگاه‌های NVIDIA) یا پهنای wavefront در AMD (روی دستگاه‌های AMD) مطابقت دارد.

.P
برخی از فلگ‌های پیکربندی ممیز شناور ممکن است فقط برای
دقت‌های خاص یا نسخه‌های خاصی از OpenCL معنادار باشند. به عنوان مثال،
.B CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT
فقط برای دقت یگانه در دستگاه‌های OpenCL 1.2 مرتبط است.

.P
رفتار تعریف‌شده توسط پیاده‌سازی برای پلتفرم NULL یا ویژگی‌های
کانتکست، برای فراخوانی‌های API زیر آزمایش می‌شود:
.TP 2
.B clGetPlatformInfo()
با تلاش برای نمایش نام پلتفرم؛
.TP
.B clGetDeviceIDs()
با تلاش برای شمارش دستگاه‌ها؛ سپس پلتفرم مربوطه (در صورت وجود)
با پرس‌وجوی پلتفرم دستگاه از نخستین دستگاه شناسایی می‌شود؛
.TP
.B clCreateteContext()
با تلاش برای ساخت یک کانتکست از یک دستگاه از فهرست
قبلی (در صورت وجود)، و یک کانتکست از یک دستگاه از پلتفرمی دیگر؛
.TP
.B clCreateteContextFromType()
با تلاش برای ساخت کانتکست‌ها برای هر نوع دستگاه (به‌جز DEFAULT).

.SH "قابلیت‌های آزمایشی (EXPERIMENTAL FEATURES)"
.P
پشتیبانی از ویژگی‌های OpenCL 2.x به طور کامل آزمایش نشده است.

.P
پشتیبانی از
.B cl_khr_subgroup_named_barrier
به دلیل نبود تعاریف در هدرهای رسمی OpenCL، آزمایشی است.

.P
خروجی خام (قابل تجزیه توسط ماشین) آزمایشی در نظر گرفته می‌شود؛ قالب خروجی
ممکن است همچنان دستخوش تغییرات شود.

.P
ویژگی‌های بارگذار ICD نیز در صورتی که تابع افزونه
.B clGetICDLoaderInfoOCLICD
یافت شود، مورد پرس‌وجو قرار خواهند گرفت.

.P
پشتیبانی از ویژگی‌های ارائه‌شده توسط
.B cl_amd_copy_buffer_p2p
آزمایشی است.

.P
پشتیبانی از برخی ویژگی‌های (مستندشده و مستندنشده) ارائه‌شده توسط
.B cl_amd_device_attribute_query
آزمایشی است (همچنین بخش
.B "محدودیت‌ها (LIMITATIONS)"
را ببینید).

.P
پشتیبانی از فهرست‌های تعامل‌پذیری (interop) ارائه‌شده توسط
.B cl_intel_simultaneous_sharing
آزمایشی است.

.P
بالاترین نسخه OpenCL پشتیبانی‌شده توسط بارگذار ICD با برخی
روش‌های اکتشافی ساده (نمادهای یافت‌شده) شناسایی می‌شود؛ در صورتی که این نسخه
از بالاترین نسخه OpenCL پلتفرم کمتر باشد، یا اگر نسخه شناسایی‌شده با نسخه
اعلام‌شده توسط خود بارگذار ICD مطابقت نداشته باشد، پیامی نمایش داده می‌شود.

.SH "محدودیت‌ها (LIMITATIONS)"

.P
OpenCL تا نسخه 3.0 روش صریحی برای تشخیص نسخه پشتیبانی‌شده از هر افزونه
ارائه‌شده توسط یک دستگاه ارائه نکرده بود. این امر در بسیاری از شرایط، تعیین پیشینی این موضوع
را که آیا پرس‌وجوی موفقیت‌آمیز یک ویژگی خاص از دستگاه امکان‌پذیر است یا خیر، غیرممکن می‌سازد،
حتی اگر دستگاه پشتیبانی از یک افزونه معین را اعلام کرده باشد.
علاوه بر این، اندازه و مفهوم واقعی برخی از ویژگی‌ها به طور رسمی در هیچ کجا
اعلام نشده است.

.P
به‌ویژه این موضوع بر افزونه‌هایی مانند
.BR cl_amd_device_attribute_query ،
.B cl_nv_device_attribute_query
و
.B cl_arm_core_id
تأثیر می‌گذارد. روش‌های اکتشافی مبتنی بر پشتیبانی از نسخه استاندارد تا حدی در کد استفاده می‌شوند
تا مشخص شود کدام نسخه ممکن است پشتیبانی شود.

.P
ویژگی‌هایی که مشخص شده است تحت تأثیر این محدودیت‌ها قرار دارند عبارتند از:

.TP 2
.B CL_DEVICE_GLOBAL_FREE_MEMORY_AMD
که در نسخه 3 از مشخصات افزونه
.B cl_amd_device_attribute_query
به عنوان حافظه آزاد سراسری بر حسب کیلوبایت مستند شده است، بدون اینکه توضیحی
درباره علت وجود دو مقدار ارائه شده باشد؛ هرچند در کد منبع استک
.B ROCm
مقدار دوم به عنوان بزرگ‌ترین بلوک آزاد مستند شده است؛
.TP
.B CL_DEVICE_AVAILABLE_ASYNC_QUEUES_AMD
که در نسخه 3 از مشخصات افزونه
.B cl_amd_device_attribute_query
مستند شده است، اما توسط درایورهایی که از سایر ویژگی‌های نسخه 3 پشتیبانی می‌کنند
گزارش نمی‌شود. این مورد اکنون برای درایورهایی که
.I فرض می‌شود
از نسخه 4 همین افزونه پشتیبانی می‌کنند فعال شده است؛
.TP
.B CL_DEVICE_TERMINATE_CAPABILITY_KHR
ارائه‌شده توسط
.B cl_khr_terminate_context
که مقدار آن میان OpenCL 1.x و 2.x تغییر کرده است، و
.I ظاهراً
یک میدان بیتی (bitfield) است که با این حال مقادیر آن در هیچ کجا تعریف نشده‌اند.

.SH "اشکالات (BUGS)"

.SS عمومی (General)

.P
لطفاً هرگونه مشکل را در
.UR https://github.com/Oblomov/clinfo
ردیاب پروژه در GitHub
.UE
گزارش دهید.

.SS خطاهای خط فرمان LLVM (LLVM CommandLine errors)

.P
اگر چندین پلتفرم OpenCL که از کتابخانه‌های مشترک
.B LLVM
استفاده می‌کنند در سیستم وجود داشته باشند، ممکن است
.B clinfo
(و سایر برنامه‌های کاربردی OpenCL) با خطاهایی مشابه
.PP
.nf
.RS
.B : CommandLine Error: Option '(some option name)' registered more than once!
.B LLVM ERROR: inconsistency in registered CommandLine options
.RE
.fi
.PP
یا مانند آن دچار کرش شوند. این یک اشکال در
.BR clinfo ،
یا در هیچ‌یک از پلتفرم‌ها یا برنامه‌های کاربردی OpenCL نیست، بلکه به دلیل نحوه مدیریت
.B LLVM
در تجزیه گزینه‌های خط فرمان خودش است.
این مشکل در بالادست
.UR https://bugs.llvm.org/show_bug.cgi?id=30587
به عنوان گزارش اشکال شماره 30587
.UE
گزارش شده است.
برای راهکارهای احتمالی و کمک به شناسایی پلتفرم‌های دارای تداخل، نکته بعدی را ببینید.

.SS خطاهای نقض حافظه (Segmentation faults)

.P
پلتفرم‌های معیوب OpenCL ممکن است باعث بروز خطای نقض حافظه (segmentation fault) در
.B clinfo
در طول مرحله جمع‌آوری اطلاعات شوند، گاهی اوقات حتی پیش از اینکه هرگونه خروجی نمایش داده شود.
کار چندانی از دست
.B clinfo
برای جلوگیری از این امر ساخته نیست. اگر مشاهده کردید این اتفاق رخ می‌دهد،
سعی کنید همه پلتفرم‌ها را غیرفعال کرده و سپس آن‌ها را یکی‌یکی دوباره فعال کنید
تا زمانی که کرش مجدداً اتفاق بیفتد.
به احتمال زیاد آخرین پلتفرمی که فعال کرده‌اید به نوعی معیوب است
(یا به دلیل ناسازگاری با سایر پلتفرم‌ها یا به دلیل نبود اجزای ضروری و
عدم مدیریت مناسب نبود آن‌ها).

.P
برای فعال یا غیرفعال کردن گزینشی پلتفرم‌ها، یک روش انتقال یا تغییر نام فایل‌های
.I *.icd
موجود در
.I /etc/OpenCL/vendors/
و سپس بازگردانی آن‌ها یکی پس از دیگری است. هنگام استفاده از کتابخانه نرم‌افزار آزاد
.B ocl-icd
برای OpenCL، می‌توان با تنظیم متغیرهای محیطی
.B OPENCL_VENDOR_PATH
یا
.B OCL_ICD_VENDORS
به اثر مشابهی دست یافت، همان‌طور که در
.BR libOpenCL (7)
مستند شده است. سایر پیاده‌سازی‌های
.B libOpenCL
نیز شناخته شده‌اند که از
.B OPENCL_VENDOR_PATH
پشتیبانی می‌کنند.

.TP 2
.B مثال
find /etc/OpenCL/vendors/ -name '*.icd' | while read OPENCL_VENDOR_PATH ; do clinfo -l > /dev/null ; echo "$? ${OPENCL_VENDOR_PATH}" ; done

.P
این دستور تک‌خطی
.B clinfo -l
را برای هر پلتفرم به صورت مجزا اجرا می‌کند (خروجی عادی را پنهان می‌سازد)،
و مسیر
.I .icd
را با پیشوند
.B 0
برای اجراهای موفقیت‌آمیز، و یک مقدار غیر صفر برای پلتفرم‌های معیوب
گزارش می‌دهد.