[llvm] 3336836 - [Docs][llvm-exegesis] Add documentation for memory annotations

[Aiden Grossman via llvm-commits]

Author: Aiden Grossman
Date: 2023-07-18T10:23:07-07:00
New Revision: 3336836dc21b7bea912b5bb2b72438b18b8cea04

URL: https://github.com/llvm/llvm-project/commit/3336836dc21b7bea912b5bb2b72438b18b8cea04
DIFF: https://github.com/llvm/llvm-project/commit/3336836dc21b7bea912b5bb2b72438b18b8cea04.diff

LOG: [Docs][llvm-exegesis] Add documentation for memory annotations

Reviewed By: gchatelet

Differential Revision: https://reviews.llvm.org/D151039

Added: 
    

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

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CommandGuide/llvm-exegesis.rst b/llvm/docs/CommandGuide/llvm-exegesis.rst
index 7fdce24e011149..9650df4023d86b 100644
--- a/llvm/docs/CommandGuide/llvm-exegesis.rst
+++ b/llvm/docs/CommandGuide/llvm-exegesis.rst
@@ -65,6 +65,21 @@ properly.
     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 @@ will be set by the tool) and the memory buffer passed in RDI (live in).
   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 @@ OPTIONS
  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
 -----------
 

diff  --git a/llvm/tools/llvm-exegesis/README.md b/llvm/tools/llvm-exegesis/README.md
index 6f2d3a9c487742..bbc24688a2a2c6 100644
--- a/llvm/tools/llvm-exegesis/README.md
+++ b/llvm/tools/llvm-exegesis/README.md
@@ -16,6 +16,10 @@ Currently, `llvm-exegesis`  only supports benchmarking on Linux. This is mainly
 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 @@ architectures:
 * 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.