• LLVM-EXEGESIS-DEFREG <register name> - افزودن این حاشیه‌نویسی به قطعه‌کد متنی اسمبلی جهت بنچمارک، ثبات (register) را به عنوان نیازمند مقداردهی مشخص می‌کند. مقداری به طور خودکار فراهم خواهد شد، مگر اینکه پارامتر دومی به صورت یک مقدار هگزادسیمال (hex) وارد شود. این کار با ساختار LLVM-EXEGESIS-DEFREG <register name> <hex value> انجام می‌گیرد. <hex value> یک الگوی بیتی است که برای پر کردن ثبات استفاده می‌شود. اگر این مقدار از اندازهٔ ثبات کوچک‌تر باشد، با حفظ علامت (sign extended) گسترش می‌یابد تا با اندازهٔ ثبات مطابقت پیدا کند.
• LLVM-EXEGESIS-LIVEIN <register name> - این حاشیه‌نویسی امکان تعیین ثبات‌هایی را فراهم می‌کند که باید مقدار خود را در هنگام شروع بنچمارک حفظ کنند. در برخی موارد مقادیر می‌توانند از طریق ثبات‌ها از بخش راه‌اندازی بنچمارک منتقل شوند. ثبات‌ها و مقادیر تخصیص‌یافته به آن‌ها که می‌توانند در اسکریپت بنچمارک با LLVM-EXEGESIS-LIVEIN استفاده شوند، به شرح زیر هستند:

• LLVM-EXEGESIS-MEM-DEF <value name> <size> <value> - این حاشیه‌نویسی امکان تعیین تعاریف حافظه‌ای را فراهم می‌کند که می‌توانند بعداً با حاشیه‌نویسی LLVM-EXEGESIS-MEM-MAP به فرآیند اجرای قطعه‌کد نگاشت (map) شوند. هر مقدار با استفاده از آرگومان <value name> نام‌گذاری می‌شود تا بتوان بعداً درون یک حاشیه‌نویسی نگاشت به آن ارجاع داد. اندازه به صورت تعداد بایت‌ها در مبنای ۱۰ (اعشاری) مشخص شده و مقدار در مبنای ۱۶ (هگزادسیمال) ارائه می‌شود. اگر اندازهٔ مقدار کمتر از اندازهٔ مشخص‌شده باشد، مقدار تا زمانی تکرار می‌شود که کل بخش حافظه را پر کند. استفاده از این حاشیه‌نویسی نیازمند استفاده از حالت اجرای زیرفرآیند (subprocess execution mode) است.
• LLVM-EXEGESIS-MEM-MAP <value name> <address> - این حاشیه‌نویسی امکان نگاشت تعاریف حافظهٔ از پیش تعریف‌شده را به بافتار اجرای (execution context) یک فرآیند فراهم می‌کند. نام مقدار به یک تعریف حافظهٔ از پیش تعیین‌شده اشاره دارد و آدرس، عددی در مبنای ۱۰ است که آدرس شروع تعریف حافظه را مشخص می‌کند. توجه داشته باشید که یک تعریف حافظه می‌تواند چندین بار نگاشت شود. استفاده از این حاشیه‌نویسی نیازمند حالت اجرای زیرفرآیند است.
• LLVM-EXEGESIS-SNIPPET-ADDRESS <address> - این حاشیه‌نویسی امکان تعیین آدرسی را فراهم می‌کند که ابتدای قطعه‌کد برای اجرا در آنجا نگاشت خواهد شد. آدرس در مبنای ۱۶ (هگزادسیمال) داده می‌شود. توجه داشته باشید که قطعه‌کد شامل کد راه‌اندازی اولیه نیز می‌باشد، بنابراین دستورالعمل دقیقاً واقع در آدرس مشخص‌شده، اولین دستورالعمل درون قطعه‌کد نخواهد بود. استفاده از این حاشیه‌نویسی نیازمند حالت اجرای زیرفرآیند است. این ویژگی در مواردی کاربرد دارد که حافظهٔ مورد دسترسی قطعه‌کد به مکان قطعه‌کد وابسته است؛ مانند آدرس‌دهی وابسته به RIP (RIP-relative addressing).
• LLVM-EXEGESIS-LOOP-REGISTER <register name> - این حاشیه‌نویسی، ثبات حلقه را برای ردیابی تکرار فعلی در هنگام استفاده از حالت تکرار حلقه (loop repetition mode) مشخص می‌کند. llvm-exegesis باید تکرار فعلی حلقه را درون حالت تکرار حلقه به شیوه‌ای با کارایی بالا (یعنی بدون دسترسی به حافظه) دنبال کند و برای این کار از یک ثبات استفاده می‌کند. این ثبات یک مقدار پیش‌فرض مختص معماری دارد (مانند R8 در X86)، اما این ممکن است با برخی از قطعه‌کدها تداخل داشته باشد. این حاشیه‌نویسی امکان تغییر ثبات را فراهم می‌کند تا از تداخل بین ثبات شاخص حلقه و قطعه‌کد جلوگیری شود.

  فرض کنید یک دستگاه X86-64 دارید. برای اندازه‌گیری تاخیر (latency) یک تک‌دستورالعمل، اجرا کنید:

$ llvm-exegesis --mode=latency --opcode-name=ADD64rr

اندازه‌گیری تجزیه uop یا توان عملیاتی معکوس (inverse throughput) یک دستورالعمل نیز به روشی مشابه کار می‌کند:

$ llvm-exegesis --mode=uops --opcode-name=ADD64rr
$ llvm-exegesis --mode=inverse_throughput --opcode-name=ADD64rr

خروجی یک سند YAML است (حالت پیش‌فرض نوشتن در stdout است، اما می‌توانید با استفاده از --benchmarks-file خروجی را به یک فایل هدایت کنید):

---
key:
  opcode_name:     ADD64rr
  mode:            latency
  config:          ''
cpu_name:        haswell
llvm_triple:     x86_64-unknown-linux-gnu
num_repetitions: 10000
measurements:
  - { key: latency, value: 1.0058, debug_string: '' }
error:           ''
info:            'explicit self cycles, selecting one aliasing configuration.
Snippet:
ADD64rr R8, R8, R10
'
...

برای اندازه‌گیری تاخیر تمامی دستورالعمل‌ها برای معماری میزبان، اجرا کنید:

$ llvm-exegesis --mode=latency --opcode-index=-1

# LLVM-EXEGESIS-LIVEIN RDI
# LLVM-EXEGESIS-DEFREG XMM1 42
vmulps        (%rdi), %xmm1, %xmm2
vhaddps       %xmm2, %xmm2, %xmm3
addq $0x10, %rdi

برخی از قطعه‌کدها برای اجرا بدون از کار افتادگی (crash)، نیازمند برپاسازی حافظه در مکان‌های خاصی هستند. برپاسازی حافظه را می‌توان با استفاده از حاشیه‌نویسی‌های LLVM-EXEGESIS-MEM-DEF و LLVM-EXEGESIS-MEM-MAP انجام داد. برای اجرای قطعه‌کد زیر:

movq $8192, %rax
movq (%rax), %rdi

باید حداقل هشت بایت حافظهٔ تخصیص‌یافته با شروع از 0x2000 داشته باشیم. ما می‌توانیم محیط اجرای لازم را با افزودن حاشیه‌نویسی‌های زیر به قطعه‌کد ایجاد کنیم:

# LLVM-EXEGESIS-MEM-DEF test1 4096 7fffffff
# LLVM-EXEGESIS-MEM-MAP test1 8192
movq $8192, %rax
movq (%rax), %rdi

--help

چاپ خلاصه‌ای از گزینه‌های خط فرمان.

--opcode-index=<LLVM opcode index>;

مشخص کردن opcode برای اندازه‌گیری، بر اساس اندیس. مشخص کردن -1 منجر به اندازه‌گیری تمام opcodeهای موجود خواهد شد. برای جزئیات به مثال ۱ مراجعه کنید. باید یکی از گزینه‌های opcode-index، opcode-name یا snippets-file تعیین شده باشد.

--opcode-name=<opcode name 1>;,<opcode name 2>,...

مشخص کردن opcode برای اندازه‌گیری، بر اساس نام. چندین opcode را می‌توان به صورت فهرستی جداشده با کاما تعیین کرد. برای جزئیات به مثال ۱ مراجعه کنید. باید یکی از گزینه‌های opcode-index، opcode-name یا snippets-file تعیین شده باشد.

--snippets-file=<filename>

مشخص کردن قطعه‌کد سفارشی برای اندازه‌گیری. برای جزئیات به مثال ۲ مراجعه کنید. باید یکی از گزینه‌های opcode-index، opcode-name یا snippets-file تعیین شده باشد.

--mode=[latency|uops|inverse_throughput|analysis]

مشخص کردن حالت اجرا. توجه داشته باشید که برخی حالت‌ها نیازمندی‌ها و گزینه‌های اضافی دارند.

حالت latency می‌تواند از RDTSC یا LBR استفاده کند. حالت latency[LBR] تنها در X86 (حداقل Skylake) در دسترس است. برای اجرا در حالت latency، باید مقداری مثبت برای x86-lbr-sample-period و همچنین --repetition-mode=loop تعیین شود.

در حالت analysis، شما همچنین باید حداقل یکی از گزینه‌های -analysis-clusters-output-file= یا -analysis-inconsistencies-output-file= را مشخص کنید.

--benchmark-phase=[prepare-snippet|prepare-and-assemble-snippet|assemble-measured-code|measure]

به طور پیش‌فرض، هنگامی که -mode= مشخص می‌شود، قطعه‌کد تولیدشده اجرا و اندازه‌گیری خواهد شد؛ این امر مستلزم آن است که برنامه روی سخت‌افزاری اجرا شود که قطعه‌کد برای آن تولید شده و از اندازه‌گیری‌های کارایی پشتیبانی می‌کند. با این حال، امکان متوقف کردن فرآیند در مراحلی پیش از اندازه‌گیری وجود دارد. گزینه‌ها عبارتند از: * prepare-snippet: تنها توالی کمینه دستورالعمل‌ها را تولید می‌کند. * prepare-and-assemble-snippet: مانند prepare-snippet، اما همچنین بخشی از توالی را به صورت هگزادسیمال (hex encoded) استخراج می‌کند. * assemble-measured-code: مانند prepare-and-assemble-snippet، اما کل توالی را ایجاد می‌کند که می‌تواند با استفاده از --dump-object-to-disk در یک فایل ذخیره شود. * measure: مانند assemble-measured-code، اما اندازه‌گیری را نیز اجرا می‌کند.

--x86-lbr-sample-period=<nBranches/sample>

دوره نمونه‌برداری LBR را مشخص می‌کند - یعنی چند انشعاب پیش از گرفتن نمونه طی شود. هنگامی که مقداری مثبت برای این گزینه تعیین شود و حالت برابر با latency باشد، از LBRها برای اندازه‌گیری استفاده خواهد شد. در انتخاب دوره نمونه‌برداری "مناسب"، مقادیر کوچک‌تر ترجیح داده می‌شوند، اما در صورت تکرار بیش از حد نمونه‌برداری، ممکن است گلوگاه و افت نرخ نمونه‌برداری (throttling) رخ دهد. توصیه می‌شود از یک عدد اول استفاده شود تا از نادیده گرفته شدن مداوم برخی بلوک‌های خاص جلوگیری گردد.

--x86-disable-upper-sse-registers

استفاده از ثبات‌های بالایی xmm (شامل xmm8-xmm15) باعث طولانی‌تر شدن کدگذاری دستورالعمل‌ها می‌شود که ممکن است فشار بیشتری به مراحل واکشی (fetch) و رمزگشایی (decode) در بخش frontend وارد کند؛ این موضوع به ویژه در سخت‌افزارهای قدیمی‌تر، پتانسیل کاهش نرخ اعزام (dispatch) دستورالعمل‌ها به backend را دارد. مقایسه نتایج پایه با فعال بودن این حالت می‌تواند به تعیین اثرات frontend کمک کرده و برای بهبود تخمین‌های تاخیر (latency) و توان عملیاتی (throughput) استفاده شود.

--repetition-mode=[duplicate|loop|min|middle-half-duplicate|middle-half-loop]

مشخص کردن حالت تکرار. گزینه duplicate یک بلوک پایه (basic block) بزرگ و خطی با min-instructions دستورالعمل ایجاد می‌کند (تکرار قطعه‌کد به تعداد min-instructions/snippet size مرتبه). گزینه loop در صورت لزوم، قطعه‌کد را تا زمانی تکرار می‌کند که بدنه حلقه حداقل شامل loop-body-size دستورالعمل باشد، و سپس نتیجه را درون حلقه‌ای قرار می‌دهد که min-instructions دستورالعمل را اجرا خواهد کرد (بنابراین مجدداً قطعه‌کد را min-instructions/snippet size بار تکرار می‌کند). حالت loop، به ویژه همراه با باز کردن حلقه (loop unrolling)، تمایل دارد اثرات frontend پردازنده را در معماری‌هایی که دستورالعمل‌های رمزگشایی‌شده را حافظه پنهان می‌کنند بهتر پنهان سازد، اما یک ثبات را برای شمارش تکرارها مصرف می‌کند. اگر در حال انجام تحلیل روی چندین opcode هستید، شاید بهتر باشد از حالت min استفاده کنید که هر یک از حالت‌های دیگر را اجرا کرده و کمترین نتیجه اندازه‌گیری‌شده را برمی‌گرداند. حالت‌های تکرار middle half بسته به حالت خاص، قطعه‌کد را تکرار کرده یا درون حلقه اجرا می‌کنند. این حالت‌ها دو بنچمارک اجرا می‌کنند، یکی با دو برابر طول اولی، و سپس تفاضل میان آن‌ها را برای به دست آوردن مقادیر بدون سربار (overhead) کسر می‌کنند.

--min-instructions=<Number of instructions>;

تعداد هدف برای دستورالعمل‌های اجراشده را مشخص می‌کند. توجه داشته باشید که تعداد تکرار واقعی قطعه‌کد برابر با min-instructions/snippet size خواهد بود. مقادیر بالاتر منجر به اندازه‌گیری‌های دقیق‌تر می‌شوند اما زمان اجرای بنچمارک را طولانی‌تر می‌کنند.

--loop-body-size=<Preferred loop body size>;

تنها برای -repetition-mode=[loop|min] مؤثر است. به جای اجرای مستقیم حلقه روی قطعه‌کد، ابتدا آن را کپی می‌کند تا بدنه حلقه حداقل شامل این تعداد دستورالعمل باشد. این امر به صورت بالقوه منجر به قرارگیری بدنه حلقه در حافظه پنهان دستورات پردازنده (Op Cache / Loop Cache) می‌شود که ممکن است توان عملیاتی بالاتری نسبت به رمزگشاهای پردازنده داشته باشد.

--max-configs-per-opcode=<value>

حداکثر پیکربندی‌هایی که می‌توان برای هر opcode تولید کرد را مشخص می‌کند. به طور پیش‌فرض این مقدار 1 است، به این معنی که فرض می‌کنیم یک اندازه‌گیری واحد برای توصیف ویژگی‌های یک opcode کافی است. ممکن است این مورد برای همه دستورالعمل‌ها صادق نباشد؛ برای مثال، مشخصات کارایی دستورالعمل LEA در X86 به مقدار ثبات‌ها و مقادیر بی‌درنگ (immediates) تخصیص‌یافته بستگی دارد. تعیین مقداری بزرگتر از 1 برای -max-configs-per-opcode به llvm-exegesis اجازه می‌دهد تا پیکربندی‌های بیشتری را بررسی کند تا مشخص شود آیا برخی از انتساب‌های ثبات یا مقدار بی‌درنگ منجر به ویژگی‌های کارایی متفاوتی می‌شوند یا خیر.

--benchmarks-file=</path/to/file>

فایلی برای خواندن (حالت analysis) یا نوشتن (حالت‌های latency/uops/inverse_throughput) نتایج بنچمارک. مقدار "-" از stdin/stdout استفاده می‌کند.

--analysis-clusters-output-file=</path/to/file>

در صورت ارائه، خوشه‌های تحلیل را با ساختار CSV در این فایل می‌نویسد. مقدار "-" خروجی را در stdout چاپ می‌کند. به طور پیش‌فرض، این تحلیل اجرا نمی‌شود.

--analysis-inconsistencies-output-file=</path/to/file>

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

--analysis-filter=[all|reg-only|mem-only]

به طور پیش‌فرض، همه نتایج بنچمارک تحلیل می‌شوند، اما گاهی اوقات ممکن است بررسی مواردی که حافظه را درگیر نمی‌کنند مفید باشد، یا برعکس. این گزینه اجازه می‌دهد تا یا همه بنچمارک‌ها حفظ شوند، یا تمام مواردی که حافظه را درگیر می‌کنند (شامل دستورالعمل‌هایی که ممکن است از حافظه بخوانند یا در آن بنویسند) نادیده گرفته شوند، یا برعکس، فقط چنین بنچمارک‌هایی نگه داشته شوند.

--analysis-clustering=[dbscan,naive]

الگوریتم خوشه‌بندی مورد استفاده را مشخص می‌کند. به طور پیش‌فرض DBSCAN استفاده خواهد شد. الگوریتم خوشه‌بندی Naive برای پردازش‌های بیشتر روی خروجی -analysis-inconsistencies-output-file= مناسب‌تر است؛ این الگوریتم به ازای هر opcode یک خوشه ایجاد کرده و پایدار بودن آن خوشه را بررسی می‌کند (اینکه آیا همه نقاط همسایه یکدیگرند یا خیر).

--analysis-numpoints=<dbscan numPoints parameter>;

پارامتر numPoints مورد استفاده در خوشه‌بندی DBSCAN را مشخص می‌کند (حالت analysis، فقط DBSCAN).

--analysis-clustering-epsilon=<dbscan epsilon parameter>;

پارامتر epsilon مورد استفاده برای خوشه‌بندی نقاط بنچمارک را مشخص می‌کند (حالت analysis).

--analysis-inconsistency-epsilon=<epsilon>

پارامتر epsilon مورد استفاده برای تشخیص زمان تفاوت خوشه با مقادیر پروفایل زمان‌بندی LLVM را مشخص می‌کند (حالت analysis).

--analysis-display-unstable-clusters

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

--mtriple=<triple name>;

سه‌گانهٔ هدف (Target triple). برای دیدن هدف‌های موجود، -version را ببینید.

--mcpu=<cpu name>;

در صورت تنظیم، ویژگی‌های پردازنده با استفاده از شمارنده‌های این پردازنده اندازه‌گیری می‌شود. این گزینه هنگام ایجاد مدل‌های زمان‌بندی جدید (زمانی که پردازندهٔ میزبان برای LLVM ناشناخته است) مفید است. (برای جزئیات -mcpu=help را ببینید)

--analysis-override-benchmark-triple-and-cpu

به‌طور پیش‌فرض، llvm-exegesis محک‌ها (benchmarks) را برای سه‌گانه/پردازنده‌ای که رویش اندازه‌گیری شده‌اند تحلیل می‌کند، اما اگر بخواهید آن‌ها را برای ترکیب دیگری تحلیل کنید (که از طریق -mtriple/-mcpu مشخص می‌شود)، می‌توانید این پرچم را مشخص کنید.

--dump-object-to-disk=<filename>

در صورت تنظیم، llvm-exegesis کد تولیدشده را برای امکان بازبینی کد درون یک فایل موقت ذخیره می‌کند. به‌طور پیش‌فرض غیرفعال است.

--use-dummy-perf-counters

در صورت تنظیم، llvm-exegesis هیچ شمارندهٔ کارایی واقعی را نمی‌خواند و در عوض یک مقدار ساختگی بازمی‌گرداند. این گزینه می‌تواند برای اطمینان از فروپاشی نکردن قطعه‌کد (snippet) در زمان عدم دسترسی به شمارنده‌های کارایی سخت‌افزاری و همچنین برای اشکال‌زدایی خود llvm-exegesis استفاده شود.

--execution-mode=[inprocess,subprocess]

این گزینه حالت اجرایی مورد استفاده را مشخص می‌کند. حالت اجرای inprocess پیش‌فرض است. حالت اجرای subprocess امکانات بیشتری مانند یادداشت‌های حافظه (memory annotations) را فراهم می‌کند، اما در حال حاضر به X86-64 روی لینوکس محدود است.

--benchmark-repeat-count=<repeat-count>

این گزینه امکان تعیین تعداد دفعات تکرار اندازه‌گیری را هنگام انجام اندازه‌گیری‌های تاخیر (latency) فراهم می‌کند. به‌طور پیش‌فرض، llvm-exegesis یک اندازه‌گیری تاخیر را به تعداد دفعات کافی تکرار می‌کند تا تعادلی بین زمان اجرا و کاهش نویز برقرار شود.

--validation-counter=[instructions-retired,l1d-cache-load-misses,

l1d-cache-store-misses,l1i-cache-load-misses,data-tlb-load-misses,

data-tld-store-misses,instruction-tlb-load-misses]

این گزینه استفاده از شمارنده‌های اعتبارسنجی را فعال می‌کند؛ این شمارنده‌ها رخدادهای ریزمعماری اضافی مانند خطاهای حافظهٔ نهان (cache misses) را برای اعتبارسنجی شرایط اجرای قطعه‌کد اندازه‌گیری می‌کنند. این رخدادها با استفاده از زیرسیستم perf و در یک گروه مشترک با شمارندهٔ کاراییِ مورد استفاده برای اندازه‌گیری مقدار مورد نظر، سنجیده می‌شوند. این پرچم را می‌توان چندین بار برای اندازه‌گیری چندین رخداد مشخص کرد. حداکثر تعداد شمارنده‌های اعتبارسنجی به پلتفرم بستگی دارد.

--benchmark-process-cpu=<cpu id>;

این گزینه شمارهٔ پردازنده‌ای را مشخص می‌کند که باید برای اجرای زیرپردازهٔ محک‌زنی استفاده شود. هنگام شروع زیرپردازه، llvm-exegesis همبستگی پردازشی (affinity) زیرپردازه را طوری تنظیم می‌کند که تنها شامل پردازندهٔ مشخص‌شده باشد. این گزینه فقط در حالت اجرای subprocess کار می‌کند.