LLVM-REMARKUTIL(1)

LLVM

LLVM-REMARKUTIL(1)

نام (NAME)

llvm-remarkutil - ابزار کاربردی Remark

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

llvm-remarkutil [زیردستور] [گزینه‌ها]

توضیحات (DESCRIPTION)

ابزاری برای نمایش اطلاعات و تبدیل بین قالب‌های مختلف remark https://llvm.org/docs/Remarks.html.

زیردستورها (SUBCOMMANDS)

bitstream2yaml - سریال‌سازی مجدد remarkهای bitstream به YAML.
yaml2bitstream - سریال‌سازی مجدد remarkهای YAML به bitstream.
instruction-count - خروجی دادن تعداد دستورالعمل‌های توابع.
annotation-count - خروجی دادن تعداد انواع remark از روی remarkهای حاشیه‌نویسی (annotation).
size-diff - محاسبه تفاوت در remarkهای اندازه (size).

bitstream2yaml

کاربرد: llvm-remarkutil bitstream2yaml <input file> -o <output file>

خلاصه (Summary)

یک فایل remark با قالب bitstream را به عنوان ورودی دریافت کرده و آن را مجدداً به صورت YAML سریال‌سازی می‌کند.

yaml2bitstream

کاربرد: llvm-remarkutil yaml2bitstream <input file> -o <output file>

خلاصه (Summary)

یک فایل remark با قالب YAML را به عنوان ورودی دریافت کرده و آن را مجدداً در قالب bitstream سریال‌سازی می‌کند.

instruction-count

کاربرد: llvm-remarkutil instruction-count <input file> --parser=<bitstream|yaml> [--use-debug-loc] -o <output file>

خلاصه (Summary)

remarkهای شمارش دستورالعمل را برای هر تابع در خروجی تولید می‌کند. remarkهای شمارش دستورالعمل، تعداد دستورالعمل‌های یک تابع را در زمان چاپ اسمبلی کدگذاری می‌کنند.

remarkهای شمارش دستورالعمل به remarkهای asm-printer نیاز دارند.

قالب CSV به صورت زیر است:

Function,InstructionCount
foo,123

اگر --use-debug-loc داده شود، خروجی CSV شامل مسیر منبع، شماره خط و ستون نیز خواهد بود.

Source,Function,InstructionCount
path:line:column,foo,3

کاربرد: llvm-remarkutil annotation-count <input file> --parser=<bitstream|yaml> --annotation-type=<type> [--use-debug-loc] -o <output file>

خلاصه (Summary)

تعداد تذکرهای (remarks) مربوط به annotation-type از نوع <type> را برای هر تابع در خروجی نمایش می‌دهد. این تعداد، نشان‌دهندهٔ شمار بررسی‌های تذکر درج‌شده در تابع است.

تذکرهای شمارش پانویس نیازمند تذکرهای AnnotationRemarksPass هستند.

قالب CSV به صورت زیر است:

Function,Count
foo,123

در صورت ارسال --use-debug-loc، خروجی CSV شامل مسیر فایل مبدأ، شمارهٔ خط و ستون نیز خواهد بود.

Source,Function,Count
path:line:column,foo,3

count

کاربرد: llvm-remarkutil count [options] <input file>

دستور llvm-remarkutil count تذکرها https://llvm.org/docs/Remarks.html را بر اساس ویژگی‌های مشخص‌شده شمارش می‌کند. به‌طور پیش‌فرض، این ابزار تذکرها را بر اساس تعداد رخداد در یک فایل مبدأ، تابع، یا مجموع کل تذکرهای فایل تولیدشده شمارش می‌کند. این ابزار همچنین از جمع‌آوری شمارش بر اساس آرگومان‌های خاص تذکر پشتیبانی می‌کند. آرگومان‌های مشخص‌شده برای امکان گزارش شمارش باید دارای یک مقدار عدد صحیح باشند.

این ابزار شامل امکاناتی برای فیلتر کردن شمارش تذکرها بر اساس نام تذکر، نام گذر (pass name)، مقدار آرگومان و نوع تذکر است.

گزینه‌ها (OPTIONS)

--parser=<yaml|bitstream>: نوع تجزیه‌کنندهٔ (parser) تذکرهای ورودی را انتخاب می‌کند. اجباری.

yaml : ابزار، تذکرهای YAML را تجزیه می‌کند.
bitstream : ابزار، تذکرهای bitstream را تجزیه می‌کند.

--count-by=<value>: گزینهٔ مبنای جمع‌آوری تذکرها را انتخاب می‌کند.

remark-name : شمارش تعداد تذکرهای مجزا.
arg : شمارش تذکرها بر اساس آرگومان‌های مشخص‌شده از طریق --(r)args. مقدار آرگومان باید یک عدد باشد.

--group-by=<value>: گروه‌بندی شمارش تذکرها بر اساس ویژگی.

source : شمارش به ازای هر مسیر مبدأ جمع‌آوری می‌شود. تذکرهای فاقد موقعیت اشکال‌زدایی (debug location) شمارش نخواهند شد.
function : شمارش به ازای هر تابع جمع‌آوری می‌شود.
function-with-loc : شمارش به ازای هر تابع در هر فایل مبدأ جمع‌آوری می‌شود. تذکرهای فاقد موقعیت اشکال‌زدایی شمارش نخواهند شد.
Total : گزارش تعداد کل برای فایل تذکر ارائه‌شده.

--args[=arguments]: اگر count-by روی arg تنظیم شده باشد، این پرچم می‌تواند برای جمع‌آوری داده‌ها از آرگومان‌های مشخص‌شدهٔ تذکر به‌صورت یک رشتهٔ جداشده با کاما استفاده شود. آرگومان‌ها برای امکان شمارش تذکرها باید یک مقدار عددی داشته باشند.

--rargs[=arguments]: اگر count-by روی arg تنظیم شده باشد، این پرچم می‌تواند برای جمع‌آوری داده‌ها از آرگومان‌های مشخص‌شدهٔ تذکر با استفاده از عبارت باقاعده (regular expression) استفاده شود. آرگومان‌ها برای امکان شمارش تذکرها باید یک مقدار عددی داشته باشند.

--pass-name[=<string>]: فیلتر کردن شمارش بر اساس نام گذر (pass name).

--rpass-name[=<string>]: فیلتر کردن شمارش بر اساس نام گذر با استفاده از عبارت‌های باقاعده.

--remark-name[=<string>]: فیلتر کردن شمارش بر اساس نام تذکر.

--rremark-name[=<string>]: فیلتر کردن شمارش بر اساس نام تذکر با استفاده از عبارت‌های باقاعده.

--filter-arg-by[=<string>]: فیلتر کردن شمارش بر اساس مقدار آرگومان.

--rfilter-arg-by[=<string>]: فیلتر کردن شمارش بر اساس مقدار آرگومان با استفاده از عبارت‌های باقاعده.

--remark-type=<value>: فیلتر کردن تذکرها بر اساس نوع با گزینه‌های زیر:

unknown
passed
missed
analysis
analysis-fp-commute
analysis-aliasing
failure

کاربرد: llvm-remarkutil size-diff [گزینه‌ها] file_a file_b --parser parser

خلاصه (Summary)

دستور llvm-remarkutil size-diff تذکرهای اندازه (size remarks) https://llvm.org/docs/Remarks.html را در دو فایل تذکر file_a و file_b مقایسه می‌کند.

از llvm-remarkutil size-diff می‌توان برای به‌دست آوردن بینشی پیرامون این‌که کدام توابع بیشترین تأثیر را از تغییرات تولید کد پذیرفته‌اند، استفاده کرد.

در بیشتر سناریوهای رایج، file_a و file_b تذکرهای حاصل از کامپایل یک کد مبدأ ثابت با کامپایلرهای متفاوت یا تنظیمات بهینه‌سازی متفاوت خواهند بود.

ابزار llvm-remarkutil size-diff از هر دو نوع تذکر YAML https://llvm.org/docs/Remarks.html#yaml-remarks و bitstream https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks پشتیبانی می‌کند.

گزینه‌ها (Options)

--parser=<yaml|bitstream>

نوع تجزیه‌کنندهٔ (parser) تذکرهای ورودی را مشخص می‌کند. الزامی است.

yaml : ابزار تذکرهای YAML را تجزیه خواهد کرد.
bitstream : ابزار تذکرهای bitstream را تجزیه خواهد کرد.

--report-style=<human|json>: سبک گزارش خروجی.

human : گزارش متنی خوانا برای انسان. گزینهٔ پیش‌فرض.
json : گزارش به قالب JSON.

--pretty: چاپ زیبا و مرتب (Pretty-print) خروجی JSON. اختیاری.
اگر خروجی روی JSON تنظیم نشده باشد، این گزینه هیچ کاری انجام نمی‌دهد.

-o=<file>: فایل خروجی برای گزارش. به‌طور پیش‌فرض در stdout نوشته می‌شود.

خروجی خوانا برای انسان (Human-Readable Output)

قالب خوانا برای انسان در llvm-remarkutil size-diff از دو بخش تشکیل شده است:

تغییرات به ازای هر تابع.
خلاصه‌ای کلی و سطح‌بالا از تمام تغییرات.

بخش توابع تغییریافته (Changed Function Section)

فرض کنید در حال مقایسهٔ دو فایل تذکر OLD و NEW هستید.

به ازای هر تابعی با تعداد دستورالعمل تغییریافته در OLD و NEW، ابزار llvm-remarkutil size-diff خطی مانند زیر را صادر می‌کند:

(++|--|==) (>|<) function_name, N instrs, M stack B

تفکیک و توضیح این قالب در زیر آمده است:

(++|--|==): مشخص می‌کند که function_name در کدام‌یک از فایل‌های OLD و NEW حضور دارد.

++: فقط در NEW. ("اضافه‌شده")
--: فقط در OLD. ("حذف‌شده")
==: در هر دو فایل.

(>|<): مشخص می‌کند که آیا function_name در فایل دوم نسبت به فایل اول، دستورالعمل‌های بیشتر یا کمتری دارد.

>: دستورالعمل‌های بیشتر در فایل دوم نسبت به فایل اول.
<: دستورالعمل‌های کمتر در فایل دوم نسبت به فایل اول.

function_name: نام تابع تغییریافته.
N instrs: تعداد دستورالعمل‌های فایل دوم - تعداد دستورالعمل‌های فایل اول.
M stack B: تعداد بایت‌های پشتهٔ فایل دوم - تعداد بایت‌های پشتهٔ فایل اول.
ابزار llvm-remarkutil size-diff پس از چاپ تمام توابع تغییریافته، یک خلاصه سطح‌بالا خروجی خواهد داد.

instruction count: N (inst_pct_change%)
stack byte usage: M (sb_pct_change%)

N: مجموع تمام تغییرات تعداد دستورالعمل‌ها بین فایل دوم و اول.
inst_pct_change%: درصد افزایش یا کاهش در تعداد دستورالعمل‌ها بین فایل دوم و اول.
M: مجموع تمام تغییرات تعداد بایت‌های پشته بین فایل دوم و اول.
sb_pct_change%: درصد افزایش یا کاهش در مصرف بایت پشته بین فایل دوم و اول.

خروجی JSON (JSON OUTPUT)

نمای سطح‌بالا (High-Level view)

فرض کنید در حال مقایسه دو فایل OLD و NEW هستیم.

ابزار llvm-remarkutil size-diff خروجی JSON را به صورت زیر تولید می‌کند.

"Files": [
  "A": "path/to/OLD",
  "B": "path/to/NEW"
]
"InBoth": [
  ...
],
"OnlyInA": [
  ...
],
"OnlyInB": [
  ...
]

Files: مسیرهای اصلی فایل‌های remark.

A: مسیر فایل اول.
B: مسیر فایل دوم.

InBoth: توابع موجود در هر دو فایل.
OnlyInA: توابعی که فقط در فایل اول وجود دارند.
OnlyInB: توابعی که فقط در فایل دوم وجود دارند.

ساختار JSON تابع (Function JSON)

بخش‌های InBoth، OnlyInA و OnlyInB حاوی اطلاعات اندازه برای هر تابع در فایل‌های remark ورودی هستند.

{
  "FunctionName" : "function_name"
  "InstCount": [
      INST_COUNT_A,
      INST_COUNT_B
    ],
  "StackSize": [
      STACK_BYTES_A,
      STACK_BYTES_B
    ],
}

FunctionName: نام تابع.
InstCount: تعداد دستورالعمل‌های تابع.

INST_COUNT_A: تعداد دستورالعمل‌ها در OLD.
INST_COUNT_B: تعداد دستورالعمل‌ها در NEW.

StackSize: تعداد بایت‌های پشته برای تابع.

STACK_BYTES_A: بایت‌های پشته در OLD.
STACK_BYTES_B: بایت‌های پشته در NEW.

خروجی JSON توابع حاوی تفاوت‌ها نیست. ابزارهایی که از خروجی JSON دستور llvm-remarkutil size-diff استفاده می‌کنند، مسئول محاسبه جداگانه تفاوت‌ها هستند.

برای محاسبه تفاوت‌ها:

تفاوت تعداد دستورالعمل‌ها: INST_COUNT_B - INST_COUNT_A
تفاوت تعداد بایت‌های پشته: STACK_BYTES_B - STACK_BYTES_A

وضعیت خروج (EXIT STATUS)

دستور llvm-remarkutil size-diff در صورت موفقیت مقدار 0 و در غیر این صورت مقداری غیرصفر را برمی‌گرداند.

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

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

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

2003-2026, LLVM Project

2026-07-15