.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "LLVM-REMARKUTIL" "1" "2026-07-15" "22" "LLVM"
.SH "نام (NAME)"
llvm\-remarkutil \- ابزار کاربردی Remark
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBllvm\-remarkutil\fP [\fIزیردستور\fP] [\fIگزینه‌ها\fP]
.SH "توضیحات (DESCRIPTION)"
.sp
ابزاری برای نمایش اطلاعات و تبدیل بین قالب‌های مختلف remark \%<https://\:llvm\:.org/\:docs/\:Remarks\:.html>.
.SH "زیردستورها (SUBCOMMANDS)"
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
bitstream2yaml \- سریال‌سازی مجدد remarkهای bitstream به YAML.
.IP \(bu 2
yaml2bitstream \- سریال‌سازی مجدد remarkهای YAML به bitstream.
.IP \(bu 2
instruction\-count \- خروجی دادن تعداد دستورالعمل‌های توابع.
.IP \(bu 2
annotation\-count \- خروجی دادن تعداد انواع remark از روی remarkهای حاشیه‌نویسی (annotation).
.IP \(bu 2
size\-diff \- محاسبه تفاوت در remarkهای اندازه (size).
.UNINDENT
.UNINDENT
.UNINDENT
.SS bitstream2yaml
.sp
کاربرد: \fBllvm\-remarkutil\fP bitstream2yaml <input file> \-o <output file>
.SS "خلاصه (Summary)"
.sp
یک فایل remark با قالب bitstream را به عنوان ورودی دریافت کرده و آن را مجدداً به صورت YAML سریال‌سازی می‌کند.
.SS yaml2bitstream
.sp
کاربرد: \fBllvm\-remarkutil\fP yaml2bitstream <input file> \-o <output file>
.SS "خلاصه (Summary)"
.sp
یک فایل remark با قالب YAML را به عنوان ورودی دریافت کرده و آن را مجدداً در قالب bitstream سریال‌سازی می‌کند.
.SS instruction\-count
.sp
کاربرد: \fBllvm\-remarkutil\fP instruction\-count <input file> \-\-parser=<bitstream|yaml> [\-\-use\-debug\-loc] \-o <output file>
.SS "خلاصه (Summary)"
.sp
remarkهای شمارش دستورالعمل را برای هر تابع در خروجی تولید می‌کند. remarkهای شمارش دستورالعمل، تعداد دستورالعمل‌های یک تابع را در زمان چاپ اسمبلی کدگذاری می‌کنند.
.sp
remarkهای شمارش دستورالعمل به remarkهای asm\-printer نیاز دارند.
.sp
قالب CSV به صورت زیر است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Function,InstructionCount
foo,123
.EE
.UNINDENT
.UNINDENT
.sp
اگر \fI\-\-use\-debug\-loc\fP داده شود، خروجی CSV شامل مسیر منبع، شماره خط و ستون نیز خواهد بود.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Source,Function,InstructionCount
path:line:column,foo,3
.EE
.UNINDENT
.UNINDENT.SS annotation\-count
.sp
کاربرد: \fBllvm\-remarkutil\fP annotation\-count <input file> \-\-parser=<bitstream|yaml> \-\-annotation\-type=<type>  [\-\-use\-debug\-loc] \-o <output file>
.SS خلاصه (Summary)
.sp
تعداد تذکرهای (remarks) مربوط به annotation\-type از نوع \fI<type>\fP را برای هر تابع در خروجی نمایش می‌دهد. این تعداد، نشان‌دهندهٔ شمار بررسی‌های تذکر درج‌شده در تابع است.
.sp
تذکرهای شمارش پانویس نیازمند تذکرهای AnnotationRemarksPass هستند.
.sp
قالب CSV به صورت زیر است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Function,Count
foo,123
.EE
.UNINDENT
.UNINDENT
.sp
در صورت ارسال \fI\-\-use\-debug\-loc\fP، خروجی CSV شامل مسیر فایل مبدأ، شمارهٔ خط و ستون نیز خواهد بود.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Source,Function,Count
path:line:column,foo,3
.EE
.UNINDENT
.UNINDENT
.SS count
.sp
کاربرد: \fBllvm\-remarkutil\fP count [\fIoptions\fP] <input file>
.SS خلاصه (Summary)
.sp
دستور \fBllvm\-remarkutil count\fP تذکرها \%<https://llvm.org/docs/Remarks.html> را بر اساس ویژگی‌های مشخص‌شده شمارش می‌کند.
به‌طور پیش‌فرض، این ابزار تذکرها را بر اساس تعداد رخداد در یک فایل مبدأ، تابع، یا مجموع کل تذکرهای فایل تولیدشده شمارش می‌کند.
این ابزار همچنین از جمع‌آوری شمارش بر اساس آرگومان‌های خاص تذکر پشتیبانی می‌کند. آرگومان‌های مشخص‌شده برای امکان گزارش شمارش باید دارای یک مقدار عدد صحیح باشند.
.sp
این ابزار شامل امکاناتی برای فیلتر کردن شمارش تذکرها بر اساس نام تذکر، نام گذر (pass name)، مقدار آرگومان و نوع تذکر است.
.SS گزینه‌ها (OPTIONS)
.INDENT 0.0
.TP
.B \-\-parser=<yaml|bitstream>
نوع تجزیه‌کنندهٔ (parser) تذکرهای ورودی را انتخاب می‌کند. اجباری.
.INDENT 7.0
.IP \(bu 2
\fByaml\fP : ابزار، تذکرهای YAML را تجزیه می‌کند.
.IP \(bu 2
\fBbitstream\fP : ابزار، تذکرهای bitstream را تجزیه می‌کند.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-count\-by=<value>
گزینهٔ مبنای جمع‌آوری تذکرها را انتخاب می‌کند.
.INDENT 7.0
.IP \(bu 2
\fBremark\-name\fP : شمارش تعداد تذکرهای مجزا.
.IP \(bu 2
\fBarg\fP : شمارش تذکرها بر اساس آرگومان‌های مشخص‌شده از طریق \-\-(r)args. مقدار آرگومان باید یک عدد باشد.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-group\-by=<value>
گروه‌بندی شمارش تذکرها بر اساس ویژگی.
.INDENT 7.0
.IP \(bu 2
\fBsource\fP : شمارش به ازای هر مسیر مبدأ جمع‌آوری می‌شود. تذکرهای فاقد موقعیت اشکال‌زدایی (debug location) شمارش نخواهند شد.
.IP \(bu 2
\fBfunction\fP : شمارش به ازای هر تابع جمع‌آوری می‌شود.
.IP \(bu 2
\fBfunction\-with\-loc\fP : شمارش به ازای هر تابع در هر فایل مبدأ جمع‌آوری می‌شود. تذکرهای فاقد موقعیت اشکال‌زدایی شمارش نخواهند شد.
.IP \(bu 2
\fBTotal\fP : گزارش تعداد کل برای فایل تذکر ارائه‌شده.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-args[=arguments]
اگر \fIcount\-by\fP روی \fIarg\fP تنظیم شده باشد، این پرچم می‌تواند برای جمع‌آوری داده‌ها از آرگومان‌های مشخص‌شدهٔ تذکر به‌صورت یک رشتهٔ جداشده با کاما استفاده شود.
آرگومان‌ها برای امکان شمارش تذکرها باید یک مقدار عددی داشته باشند.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rargs[=arguments]
اگر \fIcount\-by\fP روی \fIarg\fP تنظیم شده باشد، این پرچم می‌تواند برای جمع‌آوری داده‌ها از آرگومان‌های مشخص‌شدهٔ تذکر با استفاده از عبارت باقاعده (regular expression) استفاده شود.
آرگومان‌ها برای امکان شمارش تذکرها باید یک مقدار عددی داشته باشند.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pass\-name[=<string>]
فیلتر کردن شمارش بر اساس نام گذر (pass name).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rpass\-name[=<string>]
فیلتر کردن شمارش بر اساس نام گذر با استفاده از عبارت‌های باقاعده.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-remark\-name[=<string>]
فیلتر کردن شمارش بر اساس نام تذکر.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rremark\-name[=<string>]
فیلتر کردن شمارش بر اساس نام تذکر با استفاده از عبارت‌های باقاعده.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-filter\-arg\-by[=<string>]
فیلتر کردن شمارش بر اساس مقدار آرگومان.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rfilter\-arg\-by[=<string>]
فیلتر کردن شمارش بر اساس مقدار آرگومان با استفاده از عبارت‌های باقاعده.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-remark\-type=<value>
فیلتر کردن تذکرها بر اساس نوع با گزینه‌های زیر:
.INDENT 7.0
.IP \(bu 2
\fBunknown\fP
.IP \(bu 2
\fBpassed\fP
.IP \(bu 2
\fBmissed\fP
.IP \(bu 2
\fBanalysis\fP
.IP \(bu 2
\fBanalysis\-fp\-commute\fP
.IP \(bu 2
\fBanalysis\-aliasing\fP
.IP \(bu 2
\fBfailure\fP
.UNINDENT
.UNINDENT.SS size\-diff
.sp
کاربرد: \fBllvm\-remarkutil\fP size\-diff [\fIگزینه‌ها\fP] \fIfile_a\fP \fIfile_b\fP \fB\-\-parser\fP \fIparser\fP
.SS خلاصه (Summary)
.sp
دستور \fBllvm\-remarkutil size\-diff\fP تذکرهای اندازه (size remarks) \%<https://llvm.org/docs/Remarks.html> را در دو فایل تذکر \fBfile_a\fP
و \fBfile_b\fP مقایسه می‌کند\&.
.sp
از \fBllvm\-remarkutil size\-diff\fP می‌توان برای به‌دست آوردن بینشی پیرامون این‌که کدام توابع
بیشترین تأثیر را از تغییرات تولید کد پذیرفته‌اند، استفاده کرد.
.sp
در بیشتر سناریوهای رایج، \fBfile_a\fP و \fBfile_b\fP تذکرهای حاصل از کامپایل یک
\fBکد مبدأ ثابت\fP با \fBکامپایلرهای متفاوت\fP یا
\fBتنظیمات بهینه‌سازی متفاوت\fP خواهند بود\&.
.sp
ابزار \fBllvm\-remarkutil size\-diff\fP از هر دو نوع تذکر
YAML \%<https://llvm.org/docs/Remarks.html#yaml-remarks> و
bitstream \%<https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks>
پشتیبانی می‌کند.
.SS گزینه‌ها (Options)
.INDENT 0.0
.TP
.B \-\-parser=<yaml|bitstream>
.UNINDENT
.sp
نوع تجزیه‌کنندهٔ (parser) تذکرهای ورودی را مشخص می‌کند. الزامی است.
.INDENT 0.0
.IP \(bu 2
\fByaml\fP : ابزار تذکرهای YAML را تجزیه خواهد کرد.
.IP \(bu 2
\fBbitstream\fP : ابزار تذکرهای bitstream را تجزیه خواهد کرد.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-report\-style=<human|json>
سبک گزارش خروجی.
.INDENT 7.0
.IP \(bu 2
\fBhuman\fP : گزارش متنی خوانا برای انسان. گزینهٔ پیش‌فرض.
.IP \(bu 2
\fBjson\fP : گزارش به قالب JSON.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pretty
چاپ زیبا و مرتب (Pretty\-print) خروجی JSON. اختیاری.
.sp
اگر خروجی روی JSON تنظیم نشده باشد، این گزینه هیچ کاری انجام نمی‌دهد.
.UNINDENT
.INDENT 0.0
.TP
.B \-o=<file>
فایل خروجی برای گزارش. به‌طور پیش‌فرض در stdout نوشته می‌شود.
.UNINDENT
.SS خروجی خوانا برای انسان (Human\-Readable Output)
.sp
قالب خوانا برای انسان در \fBllvm\-remarkutil size\-diff\fP از دو
بخش تشکیل شده است:
.INDENT 0.0
.IP \(bu 2
تغییرات به ازای هر تابع.
.IP \(bu 2
خلاصه‌ای کلی و سطح‌بالا از تمام تغییرات.
.UNINDENT
.SS بخش توابع تغییریافته (Changed Function Section)
.sp
فرض کنید در حال مقایسهٔ دو فایل تذکر OLD و NEW هستید.
.sp
به ازای هر تابعی با \fBتعداد دستورالعمل تغییریافته\fP در OLD و NEW،
ابزار \fBllvm\-remarkutil size\-diff\fP خطی مانند زیر را صادر می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(++|\-\-|==) (>|<) function_name, N instrs, M stack B
.EE
.UNINDENT
.UNINDENT
.sp
تفکیک و توضیح این قالب در زیر آمده است:
.INDENT 0.0
.TP
.B \fB(++|\-\-|==)\fP
مشخص می‌کند که \fBfunction_name\fP در کدام‌یک از فایل‌های OLD و NEW حضور دارد.
.INDENT 7.0
.IP \(bu 2
\fB++\fP: فقط در NEW. (\(dqاضافه‌شده\(dq)
.IP \(bu 2
\fB\-\-\fP: فقط در OLD. (\(dqحذف‌شده\(dq)
.IP \(bu 2
\fB==\fP: در هر دو فایل.
.UNINDENT
.TP
.B \fB(>|<)\fP
مشخص می‌کند که آیا \fBfunction_name\fP در فایل دوم نسبت به فایل اول، دستورالعمل‌های
بیشتر یا کمتری دارد.
.INDENT 7.0
.IP \(bu 2
\fB>\fP: دستورالعمل‌های بیشتر در فایل دوم نسبت به فایل اول.
.IP \(bu 2
\fB<\fP: دستورالعمل‌های کمتر در فایل دوم نسبت به فایل اول.
.UNINDENT
.TP
.B \fBfunction_name\fP
نام تابع تغییریافته.
.TP
.B \fBN instrs\fP
تعداد دستورالعمل‌های فایل دوم \- تعداد دستورالعمل‌های فایل اول.
.TP
.B \fBM stack B\fP
تعداد بایت‌های پشتهٔ فایل دوم \- تعداد بایت‌های پشتهٔ فایل اول.
.UNINDENT.SS بخش خلاصه (Summary Section)
.sp
ابزار \fBllvm\-remarkutil size\-diff\fP پس از چاپ تمام توابع تغییریافته، یک خلاصه سطح‌بالا خروجی خواهد داد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
instruction count: N (inst_pct_change%)
stack byte usage: M (sb_pct_change%)
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBN\fP
مجموع تمام تغییرات تعداد دستورالعمل‌ها بین فایل دوم و اول.
.TP
.B \fBinst_pct_change%\fP
درصد افزایش یا کاهش در تعداد دستورالعمل‌ها بین فایل دوم و اول.
.TP
.B \fBM\fP
مجموع تمام تغییرات تعداد بایت‌های پشته بین فایل دوم و اول.
.TP
.B \fBsb_pct_change%\fP
درصد افزایش یا کاهش در مصرف بایت پشته بین فایل دوم و اول.
.UNINDENT
.SS خروجی JSON (JSON OUTPUT)
.SS نمای سطح‌بالا (High\-Level view)
.sp
فرض کنید در حال مقایسه دو فایل OLD و NEW هستیم.
.sp
ابزار \fBllvm\-remarkutil size\-diff\fP خروجی JSON را به صورت زیر تولید می‌کند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\(dqFiles\(dq: [
  \(dqA\(dq: \(dqpath/to/OLD\(dq,
  \(dqB\(dq: \(dqpath/to/NEW\(dq
]

\(dqInBoth\(dq: [
  ...
],

\(dqOnlyInA\(dq: [
  ...
],

\(dqOnlyInB\(dq: [
  ...
]
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBFiles\fP
مسیرهای اصلی فایل‌های remark.
.INDENT 7.0
.IP \(bu 2
\fBA\fP: مسیر فایل اول.
.IP \(bu 2
\fBB\fP: مسیر فایل دوم.
.UNINDENT
.TP
.B \fBInBoth\fP
توابع موجود در هر دو فایل.
.TP
.B \fBOnlyInA\fP
توابعی که فقط در فایل اول وجود دارند.
.TP
.B \fBOnlyInB\fP
توابعی که فقط در فایل دوم وجود دارند.
.UNINDENT
.SS ساختار JSON تابع (Function JSON)
.sp
بخش‌های \fBInBoth\fP، \fBOnlyInA\fP و \fBOnlyInB\fP حاوی اطلاعات اندازه برای هر تابع در فایل‌های remark ورودی هستند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{
  \(dqFunctionName\(dq : \(dqfunction_name\(dq
  \(dqInstCount\(dq: [
      INST_COUNT_A,
      INST_COUNT_B
    ],
  \(dqStackSize\(dq: [
      STACK_BYTES_A,
      STACK_BYTES_B
    ],
}
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBFunctionName\fP
نام تابع.
.TP
.B \fBInstCount\fP
تعداد دستورالعمل‌های تابع.
.INDENT 7.0
.IP \(bu 2
\fBINST_COUNT_A\fP: تعداد دستورالعمل‌ها در OLD.
.IP \(bu 2
\fBINST_COUNT_B\fP: تعداد دستورالعمل‌ها در NEW.
.UNINDENT
.TP
.B \fBStackSize\fP
تعداد بایت‌های پشته برای تابع.
.INDENT 7.0
.IP \(bu 2
\fBSTACK_BYTES_A\fP: بایت‌های پشته در OLD.
.IP \(bu 2
\fBSTACK_BYTES_B\fP: بایت‌های پشته در NEW.
.UNINDENT
.UNINDENT.SS محاسبه تفاوت‌ها از JSON توابع
.sp
خروجی JSON توابع حاوی تفاوت‌ها نیست. ابزارهایی که از خروجی JSON دستور
\fBllvm\-remarkutil size\-diff\fP استفاده می‌کنند، مسئول محاسبه جداگانه تفاوت‌ها
هستند.
.sp
\fBبرای محاسبه تفاوت‌ها:\fP
.INDENT 0.0
.IP \(bu 2
تفاوت تعداد دستورالعمل‌ها: \fBINST_COUNT_B \- INST_COUNT_A\fP
.IP \(bu 2
تفاوت تعداد بایت‌های پشته: \fBSTACK_BYTES_B \- STACK_BYTES_A\fP
.UNINDENT
.SS "وضعیت خروج (EXIT STATUS)"
.sp
دستور \fBllvm\-remarkutil size\-diff\fP در صورت موفقیت مقدار 0 و در غیر این صورت
مقداری غیرصفر را برمی‌گرداند.
.SH "نویسندگان (AUTHORS)"
توسط تیم LLVM نگهداری می‌شود (https://llvm.org).
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
2003-2026, LLVM Project
.\" End of generated man page.