نام (NAME)

llvm-offload-binary - بسته‌بند باینری آفلود LLVM

خلاصه دستور (SYNOPSIS)

llvm-offload-binary [گزینه‌ها] [فایل‌های ورودی...]

توضیحات (DESCRIPTION)

ابزار llvm-offload-binary ابزاری برای بسته‌بندی چندین فایل شیء (object file) مربوط به دستگاه (device) در قالب یک ظرف باینری واحد است. باینری حاصل را می‌توان در جدول بخش‌های میزبان تعبیه کرد تا یک باینری فربه (fat binary) شامل کدهای آفلودینگ (offloading) برای اهداف مختلف تشکیل شود. برعکس، این ابزار همچنین می‌تواند ایمیج‌های دستگاهی را که پیش‌تر بسته‌بندی شده‌اند استخراج کند.

قالب باینری با بایت‌های جادویی 0x10FF10AD آغاز می‌شود که پس از آن نسخه و اندازه قرار دارند. هر باینری حاوی سرایند (header) اختصاصی خود است که به ابزارها امکان می‌دهد بخش‌های آفلودینگ را حتی در صورت ادغام توسط یک پیونددهنده (linker) پیدا کنند. هر مدخل آفلود شامل فراداده‌هایی مانند نوع ایمیج دستگاه، نوع سازنده (producer) و فراداده‌های رشته‌ای کلید-مقدار است. چندین ایمیج آفلودینگ به یکدیگر متصل می‌شوند تا یک باینری فربه تشکیل شود.

مثال‌ها (EXAMPLES)

# بسته‌بندی چندین ایمیج دستگاه در یک باینری فربه:
$ llvm-offload-binary -o out.bin \
      --image=file=input.o,triple=nvptx64,arch=sm_70
# استخراج یک ایمیج منطبق از یک باینری فربه:
$ llvm-offload-binary in.bin \
      --image=file=output.o,triple=nvptx64,arch=sm_70
# استخراج و بایگانی ایمیج‌ها در یک کتابخانه ایستا:
$ llvm-offload-binary in.bin --archive -o libdevice.a

گزینه‌ها (OPTIONS)

--archive: هنگام استخراج از یک باینری ورودی، همهٔ ایمیج‌های استخراج‌شده را به جای فایل‌های جداگانه در یک بایگانی ایستا (static archive) می‌نویسد.

--image=<<key>=<value>,...>: مجموعه‌ای از آرگومان‌های کلید-مقدار دلخواه را برای توصیف یک ایمیج مشخص می‌کند. کلیدهای اختیاری پرکاربرد شامل arch (مانند sm_70 برای CUDA) و triple (مانند nvptx64-nvidia-cuda) هستند.

-o <file>: خروجی را در <file> می‌نویسد. هنگام بسته‌بندی، این گزینه نام فایل باینری فربه را تعیین می‌کند. هنگام استخراج، مقصد فایل خروجی یا بایگانی را مشخص می‌کند.

--help, -h: گزینه‌های موجود را نمایش می‌دهد. برای نمایش گزینه‌های پنهان از --help-hidden استفاده کنید.

--help-list: فهرستی از تمام گزینه‌ها را نمایش می‌دهد. برای نمایش گزینه‌های پنهان از --help-list-hidden استفاده کنید.

--version: نسخهٔ فایل اجرایی llvm-offload-binary را نمایش می‌دهد.

@<FILE>: گزینه‌های خط فرمان را از فایل پاسخ <FILE> می‌خواند.

قالب باینری (BINARY FORMAT)

قالب باینری با بایت‌های جادویی 0x10FF10AD و به دنبال آن یک شمارهٔ نسخه مشخص می‌شود. هر باینری ایجادشده شامل سرایند اختصاصی خود است. این ساختار به ابزارها اجازه می‌دهد تا بخش‌های آفلودینگ را حتی پس از انجام عملیات پیونددهنده مانند پیوند با قابلیت جابه‌جایی (relocatable linking) پیدا کنند. از نظر مفهومی، این قالب باینری یک سریال‌سازی از یک نگاشت رشته‌ای و یک بافر ایمیج است.

سرایند باینری آفلود (Offloading Binary Header)

نوع	شناسه	توضیحات
uint8_t	magic	بایت‌های جادویی قالب باینری (0x10FF10AD)
uint32_t	version	نسخهٔ این قالب (در حال حاضر نسخهٔ ۱)
uint64_t	size	اندازهٔ این باینری به بایت
uint64_t	entry offset	آفست مطلق مدخل‌های آفلود به بایت
uint64_t	entry size	اندازهٔ مدخل‌های آفلود به بایت

هر مدخل آفلود، یک ایمیج بسته‌بندی‌شده را به همراه فراداده‌های مربوط به آن توصیف می‌کند..SH "جدول مدخل‌های برون‌سپاری (Offloading Entry Table)"

نوع	شناسه	توضیحات
uint16_t	image kind	نوع تصویر دستگاه (به‌عنوان مثال bc، cubin)
uint16_t	offload kind	تولیدکننده تصویر (به‌عنوان مثال openmp، cuda)
uint32_t	flags	پرچم‌های عمومی برای تصویر
uint64_t	string offset	آفست مطلق جدول فراداده‌های رشته‌ای
uint64_t	num strings	تعداد مدخل‌های رشته در جدول
uint64_t	image offset	آفست مطلق تصویر دستگاه به بایت
uint64_t	image size	اندازه تصویر دستگاه به بایت

جدول مدخل‌ها هم به یک جدول رشته و هم به خودِ تصویر خام دستگاه ارجاع می‌دهد. جدول رشته فراداده‌های کلید-مقدار دلخواه را فراهم می‌کند.

مدخل رشته‌ای برون‌سپاری (Offloading String Entry)

نوع	شناسه	توضیحات
uint64_t	key offset	آفست بایتی مطلق کلید در جدول رشته
uint64_t	value offset	آفست بایتی مطلق مقدار در جدول رشته

جدول رشته مجموعه‌ای از رشته‌های خاتمه‌یافته با null است که در تصویر ذخیره شده‌اند. آفست‌ها اجازه می‌دهند مدخل‌های رشته به عنوان جفت‌های کلید-مقدار تفسیر شوند، که فراداده‌های انعطاف‌پذیری مانند معماری یا target triple را ممکن می‌سازد.

مقادیر شمارشی (enumerated) برای image kind و offload kind عبارتند از:

نوع تصویر (Image Kind)

نام	مقدار	توضیحات
IMG_None	0x00	هیچ اطلاعات تصویری ارائه نشده است
IMG_Object	0x01	تصویر یک فایل شیء (object file) عمومی است
IMG_Bitcode	0x02	تصویر یک فایل بیت‌کد LLVM-IR است
IMG_Cubin	0x03	تصویر یک فایل شیء CUDA است
IMG_Fatbinary	0x04	تصویر یک فایل fatbinary مربوط به CUDA است
IMG_PTX	0x05	تصویر یک فایل PTX مربوط به CUDA است
"نوع برون‌سپاری (Offload Kind)"
box center;
l\|l\|l.
نام	مقدار	توضیحات
OFK_None	0x00	هیچ اطلاعاتی برای برون‌سپاری ارائه نشده است
OFK_OpenMP	0x01	تولیدکننده برون‌سپاری OpenMP بوده است
OFK_CUDA	0x02	تولیدکننده CUDA بوده است
OFK_HIP	0x03	تولیدکننده HIP بوده است
OFK_SYCL	0x04	تولیدکننده SYCL بوده است

همچنین ببینید (SEE ALSO)

clang(1) <clang.html>، llvm-objdump(1) <llvm-objdump.html>

نویسندگان (AUTHORS)

نگه‌داری‌شده توسط تیم LLVM (https://llvm.org).

کپی‌رایت و تکثیر (COPYRIGHT)

2003-2026، پروژهٔ LLVM