LLVM-PROFDATA(1) LLVM LLVM-PROFDATA(1)

llvm-profdata - ابزار داده‌های پروفایل

llvm-profdata command [args...]

ابزار llvm-profdata یک ابزار کمکی کوچک برای کار با فایل‌های داده‌های پروفایل (profile data) است.

  • merge
  • show
  • overlap
  • order

llvm-profdata merge [options] [filename...]

دستور llvm-profdata merge چندین فایل داده‌های پروفایل تولیدشده توسط ابزار دقیق PGO را دریافت کرده و آن‌ها را در یک فایل داده‌های پروفایل نمایه‌سازی‌شده (indexed) ادغام می‌کند.

به‌طور پیش‌فرض، داده‌های پروفایل بدون تغییر ادغام می‌شوند. این بدان معناست که اهمیت نسبی هر فایل ورودی متناسب با تعداد نمونه‌ها یا شمارش‌های موجود در آن است. به‌طور کلی، ورودی حاصل از یک اجرای آموزشی طولانی‌تر، نسبت به یک اجرای کوتاه‌تر با اهمیت بیشتری تفسیر خواهد شد. بسته به ماهیت اجراهای آموزشی، ممکن است تنظیم وزن اختصاص‌یافته به هر فایل ورودی با استفاده از گزینه -weighted-input مفید باشد.

پروفایل‌هایی که از طریق -weighted-input، -input-files یا از طریق آرگومان‌های مکانی ارسال می‌شوند، به ازای هر بار مشاهده شدن، پردازش می‌گردند.

چاپ خلاصه‌ای از گزینه‌های خط فرمان.
مشخص کردن نام فایل خروجی. مقدار Output نمی‌تواند - باشد زیرا داده‌های پروفایل نمایه‌سازی‌شده حاصل نمی‌توانند در خروجی استاندارد نوشته شوند.
مشخص کردن نام فایل ورودی به همراه یک وزن. شمارش‌های پروفایل مربوط به filename ارائه‌شده در weight ضرب (مقیاس‌بندی) خواهد شد، که در آن weight یک عدد صحیح ده‌دهی بزرگ‌تر یا مساوی ۱ (>= 1) است. به فایل‌های ورودی که بدون استفاده از این گزینه مشخص شوند، وزن پیش‌فرض ۱ اختصاص داده می‌شود. مثال‌ها در ادامه آورده شده‌اند.
مشخص کردن فایلی که حاوی فهرستی از فایل‌ها برای ادغام است. ورودی‌های این فایل با خط جدید از هم جدا می‌شوند. خطوطی که با '#' شروع می‌شوند نادیده گرفته می‌شوند. ورودی‌ها می‌توانند به قالب <filename> یا <weight>,<filename> باشند.
مشخص کردن فایلی که شامل نگاشت مجدد از نام‌های نماد در پروفایل ورودی به نام‌های نمادی است که باید در پروفایل خروجی استفاده شوند. این فایل باید شامل خطوطی با قالب <input-symbol> <output-symbol> باشد. خطوط خالی و خطوطی که با # شروع می‌شوند نادیده گرفته می‌شوند.

از ابزار llvm-cxxmap <> می‌توان برای تولید فایل نگاشت مجدد نماد استفاده کرد.

مشخص می‌کند که پروفایل ورودی، یک پروفایل مبتنی بر ابزار دقیق (instrumentation-based) است.
مشخص می‌کند که پروفایل ورودی، یک پروفایل مبتنی بر نمونه‌برداری (sample-based) است.

قالب فایل تولیدشده را می‌توان به یکی از روش‌های زیر تعیین کرد:

انتشار پروفایل با استفاده از کدگذاری دودویی (binary). برای پروفایل‌های مبتنی بر ابزار دقیق، قالب خروجی همان قالب دودویی نمایه‌سازی‌شده است.

انتشار پروفایل با استفاده از کدگذاری دودویی گسترش‌پذیر (extensible binary). این گزینه تنها با پروفایل‌های مبتنی بر نمونه‌برداری قابل استفاده است. کدگذاری دودویی گسترش‌پذیر در صورت فعال بودن فشرده‌سازی می‌تواند کم‌حجم‌تر باشد و سریع‌تر از کدگذاری دودویی پیش‌فرض بارگذاری شود.

انتشار پروفایل در حالت متنی. این گزینه نیز می‌تواند هم با پروفایل‌های مبتنی بر نمونه‌برداری و هم با پروفایل‌های مبتنی بر ابزار دقیق استفاده شود. در صورت استفاده از این گزینه، پروفایل در قالبی متنی تخلیه می‌شود که توسط خواننده پروفایل قابل تجزیه است.

انتشار پروفایل با استفاده از قالب gcov مربوط به GCC (هنوز پشتیبانی نمی‌شود).

رکوردهای توابع با تعداد دفعات اجرای ۰ منتشر نشوند. تنها در ترکیب با -instr قابل استفاده است. مقدار پیش‌فرض آن false است، زیرا می‌تواند از بهینه‌سازی کامپایلر در حین PGO جلوگیری کند.
استفاده از N رشته (thread) برای انجام ادغام پروفایل. هنگامی که N=0 باشد، llvm-profdata تعداد مناسبی از رشته‌ها را برای استفاده به‌طور خودکار تشخیص می‌دهد. این حالت پیش‌فرض است.
تنظیم حالت شکست. دو گزینه وجود دارد: مقدار 'any' باعث می‌شود که در صورت نامعتبر بودن هر یک از پروفایل‌ها، دستور merge با شکست مواجه شود؛ و مقدار 'all' تنها در صورتی باعث شکست دستور merge می‌شود که تمام پروفایل‌ها نامعتبر باشند. اگر روی 'all' تنظیم شود، اطلاعات مربوط به پروفایل‌های نامعتبر از خروجی نهایی ادغام‌شده حذف می‌گردد. حالت شکست پیش‌فرض 'any' است.
مشخص کردن فایلی که حاوی فهرستی از نمادها برای تولید فهرست نمادهای پروفایل در پروفایل خروجی است. این گزینه فقط با پروفایل مبتنی بر نمونه‌برداری در قالب extbinary قابل استفاده است. ورودی‌های این فایل با خط جدید از یکدیگر جدا می‌شوند.
--compress-all-sections=[true|false] فشرده‌سازی تمام بخش‌ها هنگام نوشتن نمایه. این گزینه فقط با نمایه مبتنی بر نمونه‌برداری (sample-based) در قالب extbinary قابل استفاده است.
استفاده از MD5 برای نمایش رشته‌ها در جدول نام‌ها هنگام نوشتن نمایه. این گزینه فقط با نمایه مبتنی بر نمونه‌برداری در قالب extbinary قابل استفاده است.
علامت‌گذاری نمایه به‌عنوان یک نمایه جزئی که تنها پوشش نمایه‌ایِ جزئی را برای هدف بهینه‌سازی‌شده فراهم می‌کند. این گزینه فقط با نمایه مبتنی بر نمونه‌برداری در قالب extbinary قابل استفاده است.
تقسیم بخش داده‌های نمایه به دو بخش؛ به‌طوری که یکی شامل نمایه‌های نمونه‌برداری با توابع درون‌خطی‌شده (inlined) باشد و دیگری نباشد. این گزینه فقط با نمایه مبتنی بر نمونه‌برداری در قالب extbinary قابل استفاده است.
تبدیل نمایه ادغام‌شده به نمایه‌ای با ساختار جدید. ساختارهای پشتیبانی‌شده عبارتند از nest (نمایه تو‌در‌تو؛ ورودی باید یک نمایه مسطح CS باشد) و flat (نمایه‌ای که توابع درون‌خطی تو‌در‌توی آن مسطح شده‌اند).
تکمیل یک نمایه ابزاردقیق‌سازی (instrumentation profile) با نمایه نمونه‌برداری. نمایه نمونه‌برداری ورودیِ این پرچم است. خروجی در قالب ابزاردقیق‌سازی خواهد بود (تنها با -instr کار می‌کند).
برای تابعی که در نمایه instr سرد (cold) اما در نمایه نمونه‌برداری داغ (hot) است، اگر نسبت تعداد شمارنده‌های صفر تقسیم بر تعداد کل شمارنده‌ها از آستانه بیشتر باشد، نمایه آن تابع برای کارایی مضر تلقی شده و حذف خواهد شد.
آستانه سرد مشخص‌شده توسط کاربر برای نمایه instr که بر آستانه سردِ به‌دست‌آمده از خلاصه نمایه اولویت خواهد داشت.
اگر اندازه یک تابع کوچک‌تر از این آستانه باشد، فرض می‌شود که می‌تواند توسط درون‌خط‌ساز اولیه PGO درون‌خطی شود و بر اساس نمایه نمونه‌برداری تنظیم نخواهد شد.
مشخص کردن فایل اجرایی یا .dSYM حاوی اطلاعات اشکال‌زدایی برای نمایه خام. هنگامی که از --debug-info-correlate یا --profile-correlate=debug-info برای ابزاردقیق‌سازی استفاده شده باشد، از این گزینه برای همبسته‌سازی نمایه خام استفاده کنید.
مشخص کردن فایل اجرایی شامل بخش‌های داده و نام نمایه برای نمایه خام. هنگامی که از -profile-correlate=binary برای ابزاردقیق‌سازی استفاده شده باشد، از این گزینه برای همبسته‌سازی نمایه خام استفاده کنید.
استفاده از debuginfod برای یافتن فایل‌های اجرایی مرتبط که شامل بخش‌های داده و نام برای نمایه‌های خام هستند تا آن‌ها را همبسته کند. هنگامی که از -profile-correlate=binary برای ابزاردقیق‌سازی استفاده شده باشد، این گزینه می‌تواند برای همبسته‌سازی استفاده شود.
استفاده از پوشه‌های محلی ارائه‌شده برای جستجوی فایل‌های اجرایی شامل بخش‌های داده و نام برای نمایه‌های خام به‌منظور همبسته‌سازی آن‌ها. هنگامی که از -profile-correlate=binary برای ابزاردقیق‌سازی استفاده شده باشد، این گزینه می‌تواند برای همبسته‌سازی استفاده شود.
مشخص کردن نوع همبستگی (debug_info یا binary) برای استفاده هنگامی که گزینه -debuginfod یا -debug-file-directory=<dir> ارائه شده باشد.
حداکثر تعداد ردهای نمایه زمانی (temporal profile traces) جهت ذخیره در نمایه خروجی. اگر ردهای بیشتری اضافه شوند، از نمونه‌برداری مخزنی برای انتخاب ردهایی که باید نگه‌داری شوند استفاده خواهد شد. توجه داشته باشید که تغییر این مقدار میان فراخوانی‌های مختلف ادغام بر روی یک نمایه نمایه‌گذاری‌شده یکسان، می‌تواند منجر به سوگیری نمونه‌برداری شود. مقدار پیش‌فرض 100 است.
حداکثر تعداد توابع در یک رد نمایه زمانی منفرد. ردهای طولانی‌تر بریده (truncated) خواهند شد. مقدار پیش‌فرض 1000 است.
تنها توابعی که با عبارت باقاعده (regex) مطابقت دارند در خروجی نگه داشته می‌شوند؛ بقیه توابع از نمایه حذف خواهند شد.
حذف توابعی که با عبارت باقاعده مطابقت دارند از نمایه. اگر هر دو گزینه --function و --no-function مشخص شده باشند و تابعی با هر دو مطابقت داشته باشد، حذف خواهد شد.

ادغام سه پروفایل:

llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata

فایل ورودی foo.profdata اهمیت ویژه‌ای دارد، شمارنده‌های آن را در ۱۰ ضرب کنید:

llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata

دقیقاً معادل فراخوانی قبلی (فرم صریح؛ مناسب برای فراخوانی به‌صورت خودکار و برنامه‌نویسی‌شده):

llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata

llvm-profdata show [options] [filename]

دستور llvm-profdata show یک فایل داده‌های پروفایل را دریافت کرده و اطلاعات مربوط به شمارنده‌های پروفایل را برای این فایل و هر یک از توابع مشخص‌شده نمایش می‌دهد.

اگر filename حذف شود یا - باشد، آن‌گاه llvm-profdata show ورودی خود را از ورودی استاندارد می‌خواند.

چاپ جزئیات برای تمام توابع.
چاپ شناسه‌های باینری (binary ids) تعبیه‌شده در پروفایل.
چاپ مقادیر شمارنده برای توابع نمایش‌داده‌شده.
تولید خروجی در قالب انتخاب‌شده، در صورتی که توسط نوع پروفایل ارائه‌شده پشتیبانی شود.
چاپ جزئیات یک تابع در صورتی که نام تابع شامل رشته‌ی داده‌شده باشد.
چاپ خلاصه‌ای از گزینه‌های خط فرمان.
مشخص کردن نام فایل خروجی. اگر output برابر با - باشد یا مشخص نشود، خروجی به خروجی استاندارد فرستاده می‌شود.
مشخص می‌کند که پروفایل ورودی مبتنی بر ابزارگذاری (instrumentation-based) است.
به ابزار استخراج پروفایل دستور می‌دهد تا مقادیر شمارنده‌ها را در قالب متنیِ نمایش داده‌های پروفایل مبتنی بر instrumentation نمایش دهد. به‌طور پیش‌فرض، اطلاعات پروفایل در قالبی خواناتر برای انسان (نیز متنی) همراه با حاشیه‌نویسی‌ها استخراج می‌شود.
به ابزار استخراج پروفایل دستور می‌دهد تا n تابع برتر با داغ‌ترین بلوک‌های پایه (basic blocks) را در بخش خلاصه نمایش دهد. به‌طور پیش‌فرض، توابع topn استخراج نمی‌شوند.
مشخص می‌کند که پروفایل ورودی مبتنی بر نمونه‌برداری (sample-based) است.
نمایش اندازه‌های پروفایل‌شده برای فراخوانی‌های ذاتی حافظه (memory intrinsic calls) برای توابع نمایش‌داده‌شده.
تنها توابعی را نشان می‌دهد که حداکثر مقادیر شمارش آن‌ها بزرگ‌تر یا مساوی n باشد. به‌طور پیش‌فرض، value-cutoff بر روی ۰ تنظیم شده است.
تنها نام توابعی را در خروجی می‌آورد که حداکثر مقدار شمارش آن‌ها زیر مقدار آستانه (cutoff) باشد.
چاپ نسخه پروفایل.
تنها شمارش‌های پروفایل حساس به زمینه (context sensitive) را نمایش می‌دهد. حالت پیش‌فرض فیلتر کردن تمامی شمارش‌های پروفایل حساس به زمینه است.
نمایش فهرست نمادهای پروفایل در صورت وجود در پروفایل. این گزینه تنها برای پروفایل مبتنی بر نمونه‌برداری در قالب extbinary معنادار است.
نمایش اطلاعات پایه‌ای درباره هر بخش (section) در پروفایل. این گزینه تنها برای پروفایل مبتنی بر نمونه‌برداری در قالب extbinary معنادار است.
مشخص کردن فایل اجرایی یا .dSYM که حاوی اطلاعات اشکال‌زدایی برای پروفایل خام (raw profile) است. هنگامی که از --debug-info-correlate یا --profile-correlate=debug-info برای ابزارگذاری استفاده شده باشد، از این گزینه برای نمایش توابع همبسته‌شده از پروفایل خام استفاده کنید.
تنها توابعی را نشان می‌دهد که اجرا شده‌اند؛ یعنی توابعی با مقادیر شمارش غیرصفر.

llvm-profdata overlap [گزینه‌ها] [base profile file] [test profile file]

دستور llvm-profdata overlap دو فایل دادهٔ پروفایل را دریافت کرده و هم‌پوشانی (overlap) توزیع شمارنده‌ها را بین کل فایل‌ها و بین هر یک از توابع مشخص‌شده نمایش می‌دهد.

در این دستور، overlap به‌صورت زیر تعریف می‌شود: فرض کنید base profile file دارای مقادیر شمارش زیر باشد: {c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s}، و test profile file دارای مقادیر زیر باشد: {c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}. در اینجا c{1|2}_i (به‌ازای i = 1 .. n) شمارنده‌های منطبق، و c1_u_i (به‌ازای i = 1 .. s) و c2_v_i (به‌ازای i = 1 .. v) به‌ترتیب شمارنده‌های تطبیق‌نیافته (یا شمارنده‌هایی که منحصراً وجود دارند) در base profile file و test profile file هستند. فرض کنید sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2 + ... + c2_u_s و sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t باشد. overlap = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ... + min(c1_n/sum_1, c2_n/sum_2).

توزیع هم‌پوشانی حاصل یک مقدار درصدی بین 0.0% تا 100.0% است، که 0.0% به معنای نبود هیچ‌گونه هم‌پوشانی و 100.0% به معنای هم‌پوشانی کامل است.

به‌عنوان مثال، اگر base profile file دارای مقادیر شمارش {400, 600} باشد و test profile file مقادیر شمارش منطبق {60000, 40000} داشته باشد، میزان overlap برابر با 80% خواهد بود.

چاپ جزئیات برای یک تابع در صورتی که نام تابع حاوی رشتهٔ مشخص‌شده باشد.
چاپ خلاصه‌ای از گزینه‌های خط فرمان.
مشخص کردن نام فایل خروجی. اگر output برابر با - باشد یا مشخص نشده باشد، خروجی به خروجی استاندارد ارسال می‌شود.
نمایش تنها توابعی که بیشینهٔ مقادیر شمارش آن‌ها بزرگ‌تر یا مساوی با n است. به‌طور پیش‌فرض، value-cutoff روی بیشینهٔ مقدار unsigned long long تنظیم شده است.
تنها نمایش هم‌پوشانی برای شمارش‌های پروفایل حساس به زمینه (context-sensitive). حالت پیش‌فرض نمایش شمارش‌های پروفایل غیرحساس به زمینه است.

llvm-profdata order [گزینه‌ها] [filename]

دستور llvm-profdata order از ردپاهای پروفایل‌سازی زمانی موجود در یک پروفایل استفاده کرده و ترتیب توابعی را می‌یابد که تعداد خطاهای صفحه (page faults) را برای آن ردپاها کاهش دهد. این خروجی می‌تواند مستقیماً از طریق --symbol-ordering-file= برای ELF یا -order-file برای Mach-O به lld ارسال شود. اگر ردپاهای یافت‌شده در پروفایل بازتاب‌دهندهٔ عملکرد در دنیای واقعی باشند، این ترتیب باید کارایی راه‌اندازی را بهبود بخشد.

چاپ خلاصه‌ای از گزینه‌های خط فرمان.
مشخص کردن نام فایل خروجی. اگر output برابر با - باشد یا مشخص نشده باشد، خروجی به خروجی استاندارد ارسال می‌شود.

در صورتی که دستور مشخص نشده یا نامعتبر باشد، نتواند فایل‌های ورودی را بخواند، یا عدم تطابقی میان داده‌های آن‌ها وجود داشته باشد، llvm-profdata مقدار 1 را بازمی‌گرداند.

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

2003-2026, LLVM Project

2026-07-15 22