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

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

@courbet Now that (most of) the memory annotation patch stack has landed, do you mind taking a look at this patch when you have time?

[ondrasej]

llvm/docs/CommandGuide/llvm-exegesis.rst

72

Typo: ...in bytes, the value is

79

Would it be possible to parse both decimal and hex? E.g. parse "123" as decimal, and "0x123" as hex.

Similar for the size of the memory (on the other side, the value stored in the memory might be easiest when kept only in hex).

[aidengrossman]

Address reviewer feedback.

llvm/docs/CommandGuide/llvm-exegesis.rst

79

Yes, this is possible, just not something I currently have implemented (but probably something I should write up a patch for at some point). Since this isn't supported currently, I'm thinking we leave the documentation as is, documenting the functionality currently, and then add in enhanced parsing along with documentation changes in a future patch. Thoughts?

llvm/docs/CommandGuide/llvm-exegesis.rst

     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
 ------------------------------------

   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

  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
 -----------
 

llvm/tools/llvm-exegesis/README.md

 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

 * 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.