[PATCH] D151039: [Docs][llvm-exegesis] Add documentation for memory

[Aiden Grossman via Phabricator via llvm-commits]

aidengrossman created this revision.
aidengrossman added reviewers: RKSimon, courbet, gchatelet, ondrasej.
Herald added a subscriber: mstojanovic.
Herald added a project: All.
aidengrossman requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

https://reviews.llvm.org/D151039

Files:
  llvm/docs/CommandGuide/llvm-exegesis.rst
  llvm/tools/llvm-exegesis/README.md


Index: llvm/tools/llvm-exegesis/README.md
===================================================================
--- llvm/tools/llvm-exegesis/README.md
+++ llvm/tools/llvm-exegesis/README.md
@@ -16,6 +16,10 @@
 due to a dependency on the Linux perf subsystem for reading performance
 counters.
 
+The subprocess execution mode and memory annotations currently only supports
+Linux due to a heavy reliance on many Linux specific syscalls/syscall
+implementations.
+
 #### Currently Supported Architectures for Benchmarking
 
 Currently, using `llvm-exegesis` for benchmarking is supported on the following
@@ -29,3 +33,9 @@
 * PowerPC (PowerPC64LE only)
 
 Note that not benchmarking functionality is guaranteed to work on all platforms.
+
+Memory annotations are currently only supported on 64-bit X86. There is no
+inherent limitations for porting memory annotations to other architectures, but
+parts of the test harness are implemented as MCJITed assembly that is generated
+in `./lib/X86/Target.cpp` that would need to be implemented on other architectures
+to bring up support.
Index: llvm/docs/CommandGuide/llvm-exegesis.rst
===================================================================
--- llvm/docs/CommandGuide/llvm-exegesis.rst
+++ llvm/docs/CommandGuide/llvm-exegesis.rst
@@ -65,6 +65,21 @@
     is platform dependent (e.g., it is the RDI register on X86 Linux). Setting
     this register as a live in ensures that a pointer to a block of memory (1MB)
     is placed within this register that can be used by the snippet.
+* `LLVM-EXEGESIS-MEM-DEF <value name> <size> <value>` - This annotation allows
+  specifying memory definitions that can later be mapped into the execution
+  process of a snippet with the `LLVM-EXEGESIS-MEM-MAP` annotation. Each
+  value is named using the `<value name>` argument so that it can be referenced
+  later within a map annotation. The size is specified in bytes the the value
+  is taken in hexadecimal. If the size of the value is less than the specified
+  size, the value will be repeated until it fills the entire section of memory.
+  Using this annotation requires using the subprocess execution mode.
+* `LLVM-EXEGESIS-MEM-MAP <value name> <address>` - This annotation allows for
+  mapping previously defined memory definitions into the execution context of a
+  process. The value name refers to a previously defined memory definition and
+  the address is a decimal number that specifies the address the memory
+  definition should start at. Note that a single memory definition can be
+  mapped multiple times. Using this annotation requires the subprocess
+  execution mode.
 
 EXAMPLE 1: benchmarking instructions
 ------------------------------------
@@ -141,7 +156,31 @@
   addq $0x10, %rdi
 
 
-EXAMPLE 3: analysis
+Example 3: benchmarking with memory annotations
+-----------------------------------------------
+
+Some snippets require memory setup in specific places to execute without
+crashing. Setting up memory can be accomplished with the `LLVM-EXEGESIS-MEM-DEF`
+and `LLVM-EXEGESIS-MEM-MAP` annotations. To execute the following snippet:
+
+.. code-block:: none
+
+    movq $8192, %rax
+    movq (%rax), %rdi
+
+We need to have at least eight bytes of memory allocated starting `0x2000`.
+We can create the necessary execution environment with the following
+annotations added to the snippet:
+
+.. code-block:: none
+  
+  # LLVM-EXEGESIS-MEM-DEF test1 4096 2147483647
+  # LLVM-EXEGESIS-MEM-MAP test1 8192
+
+  movq $8192, %rax
+  movq (%rax), %rdi
+
+EXAMPLE 4: analysis
 -------------------
 
 Assuming you have a set of benchmarked instructions (either latency or uops) as
@@ -378,6 +417,13 @@
  crash when hardware performance counters are unavailable and for
  debugging :program:`llvm-exegesis` itself.
 
+.. option:: --execution-mode=[inprocess,subprocess]
+
+  This option specifies what execution mode to use. The `inprocess` execution
+  mode is the default. The `subprocess` execution mode allows for additional
+  features such as memory annotations but is currently restricted to X86-64
+  on Linux.
+
 EXIT STATUS
 -----------
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D151039.524067.patch
Type: text/x-patch
Size: 4121 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20230520/e0fcee70/attachment.bin>